SOAP Client

/**
 * Create SOAP client from WSDL URL using callback pattern
 * @param url - WSDL URL or local file path
 * @param callback - Callback receiving (error, client)
 * @param endpoint - Optional endpoint URL to override WSDL endpoint
 */
function createClient(
  url: string,
  callback: (err: any, client: Client | null) => void,
  endpoint?: string
): void;

/**
 * Create SOAP client from WSDL URL with options using callback pattern
 * @param url - WSDL URL or local file path  
 * @param options - Client configuration options
 * @param callback - Callback receiving (error, client)
 * @param endpoint - Optional endpoint URL to override WSDL endpoint
 */
function createClient(
  url: string,
  options: IOptions,
  callback: (err: any, client: Client | null) => void,
  endpoint?: string
): void;

/**
 * Create SOAP client from WSDL URL using Promise pattern
 * @param url - WSDL URL or local file path
 * @param options - Optional client configuration
 * @param endpoint - Optional endpoint URL to override WSDL endpoint
 * @returns Promise resolving to Client instance
 */
function createClientAsync(
  url: string,
  options?: IOptions,
  endpoint?: string
): Promise<Client>;

import { createClient, createClientAsync } from "soap";

// Callback-based client creation
createClient("http://example.com/service.wsdl", (err, client) => {
  if (err) throw err;
  // Use client...
});

// Promise-based client creation
const client = await createClientAsync("http://example.com/service.wsdl");

// With options
const client = await createClientAsync("http://example.com/service.wsdl", {
  endpoint: "https://secure.example.com/service",
  wsdl_options: {
    timeout: 30000
  }
});

/**
 * SOAP Client class for invoking web service operations
 * Extends EventEmitter for request/response event handling
 */
class Client extends EventEmitter {
  /** Last SOAP request XML sent to server */
  lastRequest?: string;
  /** Last message body sent (without SOAP envelope) */
  lastMessage?: string;
  /** Last response received from server */
  lastResponse?: any;
  /** Last response headers received (AxiosResponseHeaders | RawAxiosResponseHeaders) */
  lastResponseHeaders?: any;
  /** Last endpoint URL used for request */
  lastEndpoint?: string;
  /** Last request headers sent */
  lastRequestHeaders?: any;
  /** Last request elapsed time in milliseconds */
  lastElapsedTime?: number;
  /** Last MTOM attachments received */
  lastResponseAttachments: IMTOMAttachments;
  /** Associated WSDL instance */
  wsdl: WSDL;
  
  constructor(wsdl: WSDL, endpoint?: string, options?: IOptions);
  
  // Dynamic SOAP method properties are auto-generated from WSDL
  [method: string]: any;
}

/**
 * Add SOAP header to all subsequent requests
 * @param soapHeader - Header object or XML string
 * @param name - Header name (optional)
 * @param namespace - Header namespace (optional)
 * @param xmlns - XML namespace (optional)
 * @returns Index of the added header
 */
addSoapHeader(soapHeader: any, name?: string, namespace?: any, xmlns?: string): number;

/**
 * Modify existing SOAP header at specified index
 * @param index - Index of header to modify
 * @param soapHeader - New header object or XML string
 * @param name - Header name (optional)
 * @param namespace - Header namespace (optional)
 * @param xmlns - XML namespace (optional)
 */
changeSoapHeader(index: any, soapHeader: any, name?: any, namespace?: any, xmlns?: any): void;

/**
 * Get array of current SOAP headers
 * @returns Array of current headers
 */
getSoapHeaders(): string[];

/**
 * Clear all SOAP headers
 */
clearSoapHeaders(): void;

/**
 * Set security handler for authentication
 * @param security - Security implementation (BasicAuth, WSSecurity, etc.)
 */
setSecurity(security: ISecurity): void;

/**
 * Change the endpoint URL for subsequent requests
 * @param endpoint - New endpoint URL
 */
setEndpoint(endpoint: string): void;

/**
 * Add HTTP header for all subsequent requests
 * @param name - Header name
 * @param value - Header value
 */
addHttpHeader(name: string, value: any): void;

/**
 * Get all current HTTP headers
 * @returns Object containing current HTTP headers
 */
getHttpHeaders(): IHeaders;

/**
 * Clear all HTTP headers
 */
clearHttpHeaders(): void;

/**
 * Add body attribute to SOAP Body element
 * @param bodyAttribute - Attribute to add
 * @param name - Attribute name (optional)
 * @param namespace - Attribute namespace (optional)
 * @param xmlns - XML namespace (optional)
 */
addBodyAttribute(bodyAttribute: any, name?: string, namespace?: string, xmlns?: string): void;

/**
 * Get all current body attributes
 * @returns Array of current body attributes
 */
getBodyAttributes(): any[];

/**
 * Clear all body attributes
 */
clearBodyAttributes(): void;

/**
 * Get description of services, ports and methods as JavaScript object
 * @returns Service description object
 */
describe(): any;

/**
 * Set custom SOAP Action header value
 * @param SOAPAction - SOAP Action value
 */
setSOAPAction(SOAPAction: string): void;

// Add custom SOAP headers
client.addSoapHeader({
  'ns1:AuthToken': {
    'ns1:Username': 'user123',
    'ns1:Password': 'secret'
  }
});

// Set endpoint
client.setEndpoint('https://production.example.com/service');

// Set security
import { BasicAuthSecurity } from 'soap';
client.setSecurity(new BasicAuthSecurity('username', 'password'));

// Add HTTP headers
client.addHttpHeader('X-API-Key', 'my-api-key');
client.addHttpHeader('Authorization', 'Bearer token123');

// Add body attributes
client.addBodyAttribute({ id: 'request-123' }, 'requestId');

// Get service description
const description = client.describe();
console.log('Available services:', Object.keys(description));

// Set custom SOAP Action
client.setSOAPAction('http://example.com/MyCustomAction');

/**
 * Client events for monitoring SOAP communication
 */
interface Client extends EventEmitter {
  /** Emitted before a request is sent */
  on(event: 'request', listener: (xml: string, eid: string) => void): this;
  /** Emitted before a request is sent, but only the body is passed to the event handler */
  on(event: 'message', listener: (message: string, eid: string) => void): this;
  /** Emitted when an erroneous response is received */
  on(event: 'soapError', listener: (error: any, eid: string) => void): this;
  /** Emitted after a response is received. This is emitted for all responses (both success and errors) */
  on(event: 'response', listener: (body: any, response: any, eid: string) => void): this;
  
  emit(event: 'request', xml: string, eid: string): boolean;
  emit(event: 'message', message: string, eid: string): boolean;
  emit(event: 'soapError', error: any, eid: string): boolean;
  emit(event: 'response', body: any, response: any, eid: string): boolean;
}

client.on('request', (xml, eid) => {
  console.log('Outgoing SOAP request:', xml);
  console.log('Event ID:', eid);
});

client.on('message', (message, eid) => {
  console.log('Message body only:', message);
  console.log('Event ID:', eid);
});

client.on('response', (body, response, eid) => {
  console.log('Response body:', body);
  console.log('Response status:', response.statusCode);
  console.log('Event ID:', eid);
});

client.on('soapError', (error, eid) => {
  console.error('SOAP Error:', error.message);
  console.log('Event ID:', eid);
});

/**
 * Callback-based SOAP method signature
 * Method names and parameters determined by WSDL operations
 */
type SoapMethod = (
  args: any,
  callback: (err: any, result: any, rawResponse: any, soapHeader: any, rawRequest: any) => void,
  options?: any,
  extraHeaders?: any
) => void;

/**
 * Promise-based SOAP method signature  
 * Async method names are same as sync methods with 'Async' suffix
 */
type SoapMethodAsync = (
  args: any,
  options?: any,
  extraHeaders?: any
) => Promise<[result: any, rawResponse: any, soapHeader: any, rawRequest: any]>;

// Callback-based method call
client.GetUserInfo({ userId: 123 }, (err, result, rawResponse, soapHeader, rawRequest) => {
  if (err) throw err;
  console.log('User:', result);
});

// Promise-based method call  
const [result, rawResponse] = await client.GetUserInfoAsync({ userId: 123 });
console.log('User:', result);

// With options and extra headers
const [result] = await client.UpdateUserAsync(
  { userId: 123, name: 'John' },
  { timeout: 10000 },
  { 'X-Custom-Header': 'value' }
);

interface IOptions {
  /** Override endpoint URL from WSDL */
  endpoint?: string;
  /** SOAP envelope namespace key (default: 'soap') */
  envelopeKey?: string;
  /** Preserve whitespace in XML parsing */
  preserveWhitespace?: boolean;
  /** Headers for WSDL HTTP request */
  wsdl_headers?: any;
  /** WSDL parsing options */
  wsdl_options?: IWsdlBaseOptions;
  /** HTTP client instance */
  httpClient?: IHttpClient;
  /** Request timeout in milliseconds */
  timeout?: number;
  /** Disable WSDL caching */
  disableCache?: boolean;
  /** Custom WSDL cache implementation */
  wsdlCache?: IWSDLCache;
  /** Return full response objects */
  returnFault?: boolean;
  /** Enable MTOM attachment support */
  enableLogging?: boolean;
  /** Custom XML parser options */
  parseReponseAttachments?: boolean;
}

interface IWsdlBaseOptions {
  /** Request timeout for WSDL fetching */
  timeout?: number;
  /** Proxy configuration */
  proxy?: string;
  /** Custom HTTP headers */
  headers?: any;
  /** SSL/TLS options */
  httpsAgent?: any;
  /** Maximum redirects to follow */
  maxRedirects?: number;
}

interface ISoapError extends Error {
  /** SOAP fault details */
  body?: any;
  /** HTTP status code */
  statusCode?: number;
  /** Full HTTP response */
  response?: any;
}

interface ISoapFault {
  /** SOAP fault code */
  faultcode: string;
  /** SOAP fault description */  
  faultstring: string;
  /** Fault actor (SOAP 1.1) */
  faultactor?: string;
  /** Fault detail object */
  detail?: any;
}