0
# SOAP
1

2
SOAP is a comprehensive SOAP (Simple Object Access Protocol) client and server implementation for Node.js applications. It enables developers to easily connect to web services using SOAP by creating clients from WSDL URLs or local filesystem paths, and also provides server capabilities for hosting SOAP services.
3

4
## Package Information
5

6
- **Package Name**: soap
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install soap`
10

11
## Core Imports
12

13
```typescript
14
import { createClient, createClientAsync, listen } from "soap";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { createClient, createClientAsync, listen } = require("soap");
21
```
22

23
Security classes:
24

25
```typescript
26
import { 
27
  BasicAuthSecurity, 
28
  BearerSecurity, 
29
  WSSecurity,
30
  ClientSSLSecurity
31
} from "soap";
32
```
33

34
## Basic Usage
35

36
### Creating a SOAP Client
37

38
```typescript
39
import { createClientAsync } from "soap";
40

41
// Create client from WSDL URL
42
const client = await createClientAsync("http://example.com/service.wsdl");
43

44
// Call SOAP methods (dynamically generated from WSDL)
45
const result = await client.SomeMethodAsync({ param1: "value" });
46
console.log(result);
47
```
48

49
### Creating a SOAP Server
50

51
```javascript
52
const soap = require("soap");
53
const http = require("http");
54

55
const service = {
56
  MyService: {
57
    MyPort: {
58
      MyFunction: function(args, callback) {
59
        callback({ result: "Hello " + args.name });
60
      }
61
    }
62
  }
63
};
64

65
const server = http.createServer();
66
soap.listen(server, "/wsdl", service, xml);
67
server.listen(8000);
68
```
69

70
## Architecture
71

72
SOAP is built around several key components:
73

74
- **Client API**: `createClient` and `createClientAsync` functions for creating SOAP clients from WSDL
75
- **Server API**: `listen` function for hosting SOAP services on HTTP servers
76
- **Security System**: Multiple authentication mechanisms (Basic Auth, Bearer, SSL, WS-Security, NTLM)
77
- **HTTP Transport**: Configurable HTTP client with proxy support, custom agents, and MTOM attachments
78
- **WSDL Processing**: Complete WSDL parsing, validation, and method generation
79
- **Event System**: EventEmitter-based architecture for request/response monitoring
80

81
## Capabilities
82

83
### SOAP Client Operations
84

85
Core functionality for creating SOAP clients from WSDL definitions and invoking web service operations with full TypeScript support.
86

87
```typescript { .api }
88
function createClient(
89
  url: string, 
90
  callback: (err: any, client: Client) => void, 
91
  endpoint?: string
92
): void;
93

94
function createClient(
95
  url: string,
96
  options: IOptions,  
97
  callback: (err: any, client: Client) => void,
98
  endpoint?: string  
99
): void;
100

101
function createClientAsync(
102
  url: string,
103
  options?: IOptions,
104
  endpoint?: string
105
): Promise<Client>;
106
```
107

108
[SOAP Client](./client.md)
109

110
### SOAP Server Hosting
111

112
Server functionality for hosting SOAP web services on HTTP servers with automatic WSDL generation and request handling.
113

114
```typescript { .api }
115
function listen(
116
  server: any,
117
  path: string,
118
  services: IServices,
119
  wsdl: string,
120
  callback?: Function
121
): Server;
122

123
function listen(
124
  server: any, 
125
  options: IServerOptions
126
): Server;
127
```
128

129
[SOAP Server](./server.md)
130

131
### Security and Authentication
132

133
Comprehensive security system supporting multiple authentication mechanisms for enterprise SOAP integration.
134

135
```typescript { .api }
136
class BasicAuthSecurity implements ISecurity {
137
  constructor(username: string, password: string, defaults?: any);
138
}
139

140
class BearerSecurity implements ISecurity {
141
  constructor(token: string, defaults?: any);
142
}
143

144
class WSSecurity implements ISecurity {
145
  constructor(username: string, password: string, options?: any);
146
}
147
```
148

149
[Security](./security.md)
150

151
### HTTP Transport and Configuration
152

153
HTTP transport layer with support for custom agents, proxies, SSL configuration, and MTOM attachments.
154

155
```typescript { .api }
156
class HttpClient implements IHttpClient {
157
  request(
158
    rurl: string,
159
    data: any,
160
    callback: (error: any, res?: any, body?: any) => any,
161
    exheaders?: IHeaders,
162
    exoptions?: IExOptions,
163
    caller?: any
164
  ): any;
165
  
166
  requestStream?(
167
    rurl: string,
168
    data: any,
169
    exheaders?: IHeaders,
170
    exoptions?: IExOptions,
171
    caller?: any
172
  ): any;
173
}
174
```
175

176
[HTTP Transport](./http-transport.md)
177

178
### WSDL Processing
179

180
WSDL parsing, validation, and XML object conversion capabilities for processing web service definitions.
181

182
```typescript { .api }
183
class WSDL {
184
  constructor(definition: any, uri: string, options: IOptions);
185
  
186
  xmlToObject(xml: any, callback?: any): any;
187
  objectToDocumentXML(name: string, params: any, nsPrefix: string, nsURI?: string, type?: string): any;
188
  objectToRpcXML(name: string, params: any, nsPrefix: string, nsURI: string, isParts?: boolean): string;
189
  describeServices(): any;
190
  toXML(): string;
191
}
192

193
function open_wsdl(uri: any, callback: (error: any, result?: WSDL) => any): any;
194
function open_wsdl(uri: any, options: IOptions, callback: (error: any, result?: WSDL) => any): any;
195
```
196

197
[WSDL Processing](./wsdl.md)
198

199
### Utility Functions
200

201
Helper functions for XML processing, password hashing, and MTOM attachment handling.
202

203
```typescript { .api }
204
function passwordDigest(nonce: string, created: string, password: string): string;
205
function xmlEscape(obj: any): any;
206
function findPrefix(xmlnsMapping: any, nsURI: any): string;
207
function splitQName<T>(nsName: T): { prefix: string; name: T | string };
208
function parseMTOMResp(payload: Buffer, boundary: string, callback: (err?: Error, resp?: IMTOMAttachments) => void): Promise<void>;
209
```
210

211
## Types
212

213
### Core Types
214

215
```typescript { .api }
216
interface IOptions extends IWsdlBaseOptions {
217
  /** Don't cache WSDL files, request them every time */
218
  disableCache?: boolean;
219
  /** Custom cache implementation for WSDLs */
220
  wsdlCache?: IWSDLCache;
221
  /** Override the SOAP service's host specified in the .wsdl file */
222
  endpoint?: string;
223
  /** Set specific key instead of soap:Body */
224
  envelopeKey?: string;
225
  /** Set specific SOAP Schema Url */
226
  envelopeSoapUrl?: string;
227
  /** Provide your own http client that implements request interface */
228
  httpClient?: IHttpClient;
229
  /** Override the request module with axios instance */
230
  request?: any;
231
  /** Enable streaming */
232
  stream?: boolean;
233
  /** Return SAX stream instead of parsed object */
234
  returnSaxStream?: boolean;
235
  /** Custom deserializer */
236
  customDeserializer?: any;
237
  /** Override the default promise suffix from 'Async' */
238
  overridePromiseSuffix?: string;
239
  /** Handle MTOM attachments in response */
240
  parseReponseAttachments?: boolean;
241
  /** Handle endpoint response encoding when using parseReponseAttachments */
242
  encoding?: BufferEncoding;
243
}
244

245
interface IWsdlBaseOptions {
246
  /** XML attributes key */
247
  attributesKey?: string;
248
  /** XML value key */
249
  valueKey?: string;
250
  /** XML key */
251
  xmlKey?: string;
252
  /** Override root element */
253
  overrideRootElement?: {
254
    namespace: string;
255
    xmlnsAttributes?: IXmlAttribute[];
256
  };
257
  /** Ignored namespaces configuration */
258
  ignoredNamespaces?: boolean | string[] | {
259
    namespaces?: string[];
260
    override?: boolean;
261
  };
262
  /** Ignore base namespaces */
263
  ignoreBaseNameSpaces?: boolean;
264
  /** Escape special XML characters in SOAP message */
265
  escapeXML?: boolean;
266
  /** Return an Invalid XML SOAP fault on a bad request */
267
  returnFault?: boolean;
268
  /** Handle nil as null */
269
  handleNilAsNull?: boolean;
270
  /** Replace non-identifier characters with _ */
271
  normalizeNames?: boolean;
272
  /** Preserve leading and trailing whitespace characters */
273
  preserveWhitespace?: boolean;
274
  /** Support for nonstandard array semantics */
275
  namespaceArrayElements?: boolean;
276
  /** Use empty tags */
277
  useEmptyTag?: boolean;
278
  /** Strict mode */
279
  strict?: boolean;
280
  /** Custom HTTP headers to be sent on WSDL requests */
281
  wsdl_headers?: { [key: string]: any };
282
  /** Custom options for the request module on WSDL requests */
283
  wsdl_options?: { [key: string]: any };
284
  /** Set proper headers for SOAP v1.2 */
285
  forceSoap12Headers?: boolean;
286
}
287

288
interface IServices {
289
  [serviceName: string]: {
290
    [portName: string]: {
291
      [methodName: string]: ISoapServiceMethod;
292
    };
293
  };
294
}
295

296
interface ISoapServiceMethod {
297
  (args: any, callback?: (data: any) => void, headers?: any, req?: any, res?: any, sender?: any): any;
298
}
299

300
interface ISecurity {
301
  addOptions?(options: any): void;
302
  toXML?(): string;  
303
  addHeaders?(headers: IHeaders): void;
304
  postProcess?(xml: any, envelopeKey: any): string;
305
}
306

307
interface IServerOptions extends IWsdlBaseOptions {
308
  /** URL path for WSDL endpoint */
309
  path: string | RegExp;
310
  /** Service implementations */
311
  services: IServices;
312
  /** WSDL content or file path */
313
  xml?: string;
314
  /** URI path for service operations */
315
  uri?: string;
316
  /** Optional completion callback */
317
  callback?: (err: any, res: any) => void;
318
  /** Suppress the full stack trace for error messages */
319
  suppressStack?: boolean;
320
  /** One-way operation options */
321
  oneWay?: IOneWayOptions;
322
  /** Control chunked transfer encoding in response */
323
  enableChunkedEncoding?: boolean;
324
}
325

326
interface IOneWayOptions {
327
  /** Response code for one-way operations */
328
  responseCode?: number;
329
  /** Send empty body for one-way operations */
330
  emptyBody?: boolean;
331
}
332

333
interface IHttpClient {
334
  request(rurl: string, data: any, callback: (error: any, res?: any, body?: any) => any, exheaders?: IHeaders, exoptions?: IExOptions, caller?: any): any;
335
  requestStream?(rurl: string, data: any, exheaders?: IHeaders, exoptions?: IExOptions, caller?: any): any;
336
}
337

338
interface IHeaders {
339
  [k: string]: any;
340
}
341

342
interface IExOptions {
343
  [key: string]: any;
344
}
345

346
interface IXmlAttribute {
347
  name: string;
348
  value: string;
349
}
350

351
interface IMTOMAttachments {
352
  parts: Array<{
353
    body: Buffer;
354
    headers: { [key: string]: string };
355
  }>;
356
}
357

358
interface IWSDLCache {
359
  has(key: string): boolean;
360
  get(key: string): WSDL;
361
  set(key: string, wsdl: WSDL): void;
362
}
363

364
type ServerType = any;
365

366
type SoapMethod = (args: any, callback: (err: any, result: any, rawResponse: any, soapHeader: any, rawRequest: any, mtomAttachments?: IMTOMAttachments) => void, options?: any, extraHeaders?: any, mtomAttachments?: IMTOMAttachments) => void;
367

368
type SoapMethodAsync = (args: any, options?: any, extraHeaders?: any) => Promise<[any, any, any, any, IMTOMAttachments?]>;
369

370
interface ISoapFaultError {
371
  Fault: ISoapFault;
372
}
373

374
type ISoapFault = ISoapFault11 | ISoapFault12;
375

376
interface ISoapFault11 {
377
  faultcode: number | string;
378
  faultstring: string;
379
  detail?: string;
380
  statusCode?: number;
381
}
382

383
interface ISoapFault12 {
384
  Code: {
385
    Value: string;
386
    Subcode?: {
387
      Value: string;
388
    };
389
  };
390
  Reason: {
391
    Text: string;
392
  };
393
  statusCode?: number;
394
}
395
```