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
```