0
# SOAP Client
1

2
Core functionality for creating SOAP clients from WSDL definitions and invoking web service operations with full TypeScript support and comprehensive error handling.
3

4
## Capabilities
5

6
### Client Creation Functions
7

8
Create SOAP clients from WSDL URLs or file paths with optional configuration and endpoint override.
9

10
```typescript { .api }
11
/**
12
 * Create SOAP client from WSDL URL using callback pattern
13
 * @param url - WSDL URL or local file path
14
 * @param callback - Callback receiving (error, client)
15
 * @param endpoint - Optional endpoint URL to override WSDL endpoint
16
 */
17
function createClient(
18
  url: string,
19
  callback: (err: any, client: Client | null) => void,
20
  endpoint?: string
21
): void;
22

23
/**
24
 * Create SOAP client from WSDL URL with options using callback pattern
25
 * @param url - WSDL URL or local file path  
26
 * @param options - Client configuration options
27
 * @param callback - Callback receiving (error, client)
28
 * @param endpoint - Optional endpoint URL to override WSDL endpoint
29
 */
30
function createClient(
31
  url: string,
32
  options: IOptions,
33
  callback: (err: any, client: Client | null) => void,
34
  endpoint?: string
35
): void;
36

37
/**
38
 * Create SOAP client from WSDL URL using Promise pattern
39
 * @param url - WSDL URL or local file path
40
 * @param options - Optional client configuration
41
 * @param endpoint - Optional endpoint URL to override WSDL endpoint
42
 * @returns Promise resolving to Client instance
43
 */
44
function createClientAsync(
45
  url: string,
46
  options?: IOptions,
47
  endpoint?: string
48
): Promise<Client>;
49
```
50

51
**Usage Examples:**
52

53
```typescript
54
import { createClient, createClientAsync } from "soap";
55

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

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

65
// With options
66
const client = await createClientAsync("http://example.com/service.wsdl", {
67
  endpoint: "https://secure.example.com/service",
68
  wsdl_options: {
69
    timeout: 30000
70
  }
71
});
72
```
73

74
### Client Class
75

76
Main SOAP client class providing method invocation and state management capabilities.
77

78
```typescript { .api }
79
/**
80
 * SOAP Client class for invoking web service operations
81
 * Extends EventEmitter for request/response event handling
82
 */
83
class Client extends EventEmitter {
84
  /** Last SOAP request XML sent to server */
85
  lastRequest?: string;
86
  /** Last message body sent (without SOAP envelope) */
87
  lastMessage?: string;
88
  /** Last response received from server */
89
  lastResponse?: any;
90
  /** Last response headers received (AxiosResponseHeaders | RawAxiosResponseHeaders) */
91
  lastResponseHeaders?: any;
92
  /** Last endpoint URL used for request */
93
  lastEndpoint?: string;
94
  /** Last request headers sent */
95
  lastRequestHeaders?: any;
96
  /** Last request elapsed time in milliseconds */
97
  lastElapsedTime?: number;
98
  /** Last MTOM attachments received */
99
  lastResponseAttachments: IMTOMAttachments;
100
  /** Associated WSDL instance */
101
  wsdl: WSDL;
102
  
103
  constructor(wsdl: WSDL, endpoint?: string, options?: IOptions);
104
  
105
  // Dynamic SOAP method properties are auto-generated from WSDL
106
  [method: string]: any;
107
}
108
```
109

110
### Client Methods
111

112
Manage SOAP headers, security, and endpoint configuration.
113

114
```typescript { .api }
115
/**
116
 * Add SOAP header to all subsequent requests
117
 * @param soapHeader - Header object or XML string
118
 * @param name - Header name (optional)
119
 * @param namespace - Header namespace (optional)
120
 * @param xmlns - XML namespace (optional)
121
 * @returns Index of the added header
122
 */
123
addSoapHeader(soapHeader: any, name?: string, namespace?: any, xmlns?: string): number;
124

125
/**
126
 * Modify existing SOAP header at specified index
127
 * @param index - Index of header to modify
128
 * @param soapHeader - New header object or XML string
129
 * @param name - Header name (optional)
130
 * @param namespace - Header namespace (optional)
131
 * @param xmlns - XML namespace (optional)
132
 */
133
changeSoapHeader(index: any, soapHeader: any, name?: any, namespace?: any, xmlns?: any): void;
134

135
/**
136
 * Get array of current SOAP headers
137
 * @returns Array of current headers
138
 */
139
getSoapHeaders(): string[];
140

141
/**
142
 * Clear all SOAP headers
143
 */
144
clearSoapHeaders(): void;
145

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

152
/**
153
 * Change the endpoint URL for subsequent requests
154
 * @param endpoint - New endpoint URL
155
 */
156
setEndpoint(endpoint: string): void;
157

158
/**
159
 * Add HTTP header for all subsequent requests
160
 * @param name - Header name
161
 * @param value - Header value
162
 */
163
addHttpHeader(name: string, value: any): void;
164

165
/**
166
 * Get all current HTTP headers
167
 * @returns Object containing current HTTP headers
168
 */
169
getHttpHeaders(): IHeaders;
170

171
/**
172
 * Clear all HTTP headers
173
 */
174
clearHttpHeaders(): void;
175

176
/**
177
 * Add body attribute to SOAP Body element
178
 * @param bodyAttribute - Attribute to add
179
 * @param name - Attribute name (optional)
180
 * @param namespace - Attribute namespace (optional)
181
 * @param xmlns - XML namespace (optional)
182
 */
183
addBodyAttribute(bodyAttribute: any, name?: string, namespace?: string, xmlns?: string): void;
184

185
/**
186
 * Get all current body attributes
187
 * @returns Array of current body attributes
188
 */
189
getBodyAttributes(): any[];
190

191
/**
192
 * Clear all body attributes
193
 */
194
clearBodyAttributes(): void;
195

196
/**
197
 * Get description of services, ports and methods as JavaScript object
198
 * @returns Service description object
199
 */
200
describe(): any;
201

202
/**
203
 * Set custom SOAP Action header value
204
 * @param SOAPAction - SOAP Action value
205
 */
206
setSOAPAction(SOAPAction: string): void;
207
```
208

209
**Usage Examples:**
210

211
```typescript
212
// Add custom SOAP headers
213
client.addSoapHeader({
214
  'ns1:AuthToken': {
215
    'ns1:Username': 'user123',
216
    'ns1:Password': 'secret'
217
  }
218
});
219

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

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

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

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

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

238
// Set custom SOAP Action
239
client.setSOAPAction('http://example.com/MyCustomAction');
240
```
241

242
### Client Events
243

244
Monitor request/response lifecycle and handle errors.
245

246
```typescript { .api }
247
/**
248
 * Client events for monitoring SOAP communication
249
 */
250
interface Client extends EventEmitter {
251
  /** Emitted before a request is sent */
252
  on(event: 'request', listener: (xml: string, eid: string) => void): this;
253
  /** Emitted before a request is sent, but only the body is passed to the event handler */
254
  on(event: 'message', listener: (message: string, eid: string) => void): this;
255
  /** Emitted when an erroneous response is received */
256
  on(event: 'soapError', listener: (error: any, eid: string) => void): this;
257
  /** Emitted after a response is received. This is emitted for all responses (both success and errors) */
258
  on(event: 'response', listener: (body: any, response: any, eid: string) => void): this;
259
  
260
  emit(event: 'request', xml: string, eid: string): boolean;
261
  emit(event: 'message', message: string, eid: string): boolean;
262
  emit(event: 'soapError', error: any, eid: string): boolean;
263
  emit(event: 'response', body: any, response: any, eid: string): boolean;
264
}
265
```
266

267
**Usage Examples:**
268

269
```typescript
270
client.on('request', (xml, eid) => {
271
  console.log('Outgoing SOAP request:', xml);
272
  console.log('Event ID:', eid);
273
});
274

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

280
client.on('response', (body, response, eid) => {
281
  console.log('Response body:', body);
282
  console.log('Response status:', response.statusCode);
283
  console.log('Event ID:', eid);
284
});
285

286
client.on('soapError', (error, eid) => {
287
  console.error('SOAP Error:', error.message);
288
  console.log('Event ID:', eid);
289
});
290
```
291

292
### Dynamic SOAP Methods
293

294
Methods are auto-generated from WSDL operations and available as properties on Client instances.
295

296
```typescript { .api }
297
/**
298
 * Callback-based SOAP method signature
299
 * Method names and parameters determined by WSDL operations
300
 */
301
type SoapMethod = (
302
  args: any,
303
  callback: (err: any, result: any, rawResponse: any, soapHeader: any, rawRequest: any) => void,
304
  options?: any,
305
  extraHeaders?: any
306
) => void;
307

308
/**
309
 * Promise-based SOAP method signature  
310
 * Async method names are same as sync methods with 'Async' suffix
311
 */
312
type SoapMethodAsync = (
313
  args: any,
314
  options?: any,
315
  extraHeaders?: any
316
) => Promise<[result: any, rawResponse: any, soapHeader: any, rawRequest: any]>;
317
```
318

319
**Usage Examples:**
320

321
```typescript
322
// Callback-based method call
323
client.GetUserInfo({ userId: 123 }, (err, result, rawResponse, soapHeader, rawRequest) => {
324
  if (err) throw err;
325
  console.log('User:', result);
326
});
327

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

332
// With options and extra headers
333
const [result] = await client.UpdateUserAsync(
334
  { userId: 123, name: 'John' },
335
  { timeout: 10000 },
336
  { 'X-Custom-Header': 'value' }
337
);
338
```
339

340
## Configuration Types
341

342
### Client Options
343

344
```typescript { .api }
345
interface IOptions {
346
  /** Override endpoint URL from WSDL */
347
  endpoint?: string;
348
  /** SOAP envelope namespace key (default: 'soap') */
349
  envelopeKey?: string;
350
  /** Preserve whitespace in XML parsing */
351
  preserveWhitespace?: boolean;
352
  /** Headers for WSDL HTTP request */
353
  wsdl_headers?: any;
354
  /** WSDL parsing options */
355
  wsdl_options?: IWsdlBaseOptions;
356
  /** HTTP client instance */
357
  httpClient?: IHttpClient;
358
  /** Request timeout in milliseconds */
359
  timeout?: number;
360
  /** Disable WSDL caching */
361
  disableCache?: boolean;
362
  /** Custom WSDL cache implementation */
363
  wsdlCache?: IWSDLCache;
364
  /** Return full response objects */
365
  returnFault?: boolean;
366
  /** Enable MTOM attachment support */
367
  enableLogging?: boolean;
368
  /** Custom XML parser options */
369
  parseReponseAttachments?: boolean;
370
}
371

372
interface IWsdlBaseOptions {
373
  /** Request timeout for WSDL fetching */
374
  timeout?: number;
375
  /** Proxy configuration */
376
  proxy?: string;
377
  /** Custom HTTP headers */
378
  headers?: any;
379
  /** SSL/TLS options */
380
  httpsAgent?: any;
381
  /** Maximum redirects to follow */
382
  maxRedirects?: number;
383
}
384
```
385

386
## Error Handling
387

388
```typescript { .api }
389
interface ISoapError extends Error {
390
  /** SOAP fault details */
391
  body?: any;
392
  /** HTTP status code */
393
  statusCode?: number;
394
  /** Full HTTP response */
395
  response?: any;
396
}
397

398
interface ISoapFault {
399
  /** SOAP fault code */
400
  faultcode: string;
401
  /** SOAP fault description */  
402
  faultstring: string;
403
  /** Fault actor (SOAP 1.1) */
404
  faultactor?: string;
405
  /** Fault detail object */
406
  detail?: any;
407
}
408
```