### Create SOAP Server (Callback)

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Creates a new SOAP server instance that listens on a specified path and provides defined services. This method uses a callback for server setup completion.

```APIDOC
soap.listen(server: http.Server, path: string, services: object, wsdl: string, callback?: Function): void
  server: The HTTP server instance to attach the SOAP server to.
  path: The URL path where the SOAP services will be exposed.
  services: An object defining the SOAP services and their methods.
  wsdl: The WSDL definition for the services.
  callback: Optional callback function called when the server is ready.
```

--------------------------------

### Asynchronous SOAP Client Creation with Promises and Async/Await

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This JavaScript example demonstrates using `soap.createClientAsync` with modern asynchronous patterns. It shows both the `then/catch` syntax and the `async/await` syntax for creating a client and invoking a SOAP service function.

```javascript
  var soap = require('soap');
  var url = 'http://example.com/wsdl?wsdl';
  var args = {name: 'value'};

  // then/catch
  soap.createClientAsync(url).then((client) => {
    return client.MyFunctionAsync(args);
  }).then((result) => {
    console.log(result);
  });

  // async/await
  var client = await soap.createClientAsync(url);
  var result = await client.MyFunctionAsync(args);
  console.log(result[0]);
```

--------------------------------

### Example: Calling Client.method with Callback

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Demonstrates how to call a SOAP service method using `Client.method` with a callback function. The callback receives error, result, raw response, SOAP header, and raw request.

```javascript
client.MyFunction({name: 'value'}, function(err, result, rawResponse, soapHeader, rawRequest) {
      // result is a javascript object
      // rawResponse is the raw xml response string
      // soapHeader is the response soap header as a javascript object
      // rawRequest is the raw xml request string
  })
```

--------------------------------

### Install Node-SOAP via npm

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This snippet shows the command to install the Node-SOAP library using npm, the package manager for Node.js. It's a prerequisite for using the library's functionalities.

```Shell
npm install soap
```

--------------------------------

### Example: Calling Specific Service/Port Method

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Shows how to invoke a SOAP method by explicitly specifying the service and port. This provides more granular control over which part of the WSDL is targeted for the method call.

```javascript
client.MyService.MyPort.MyFunction({name: 'value'}, function(err, result) {
      // result is a javascript object
  })
```

--------------------------------

### `Client.describe()` Method for Node-SOAP Client

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This JavaScript example demonstrates the `Client.describe()` method, which provides a JavaScript object representation of the SOAP service's structure, including services, ports, methods, and their input parameters.

```javascript
  client.describe() // returns
    {
      MyService: {
        MyPort: {
          MyFunction: {
            input: {
              name: 'string'
            }
          }
        }
      }
    }
```

--------------------------------

### Example: Passing Raw XML String as Arguments

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Demonstrates how to pass a fully-formed XML string directly as arguments using the `_xml` property. This approach requires manual specification of all namespaces and prefixes, bypassing WSDL-based element population.

```javascript
var args = { _xml: "<ns1:MyRootElement xmlns:ns1=\"http://www.example.com/v1/ns1\">\n                        <ChildElement>elementvalue</ChildElement>\n                     </ns1:MyRootElement>"
            };
```

--------------------------------

### Configure node-soap Server with Options Object

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This example illustrates how to configure the `soap.listen` method using an options object. It allows specifying the WSDL path, services, XML content, and custom keys for attributes, values, and XML within the parsed SOAP messages.

```javascript
var xml = require('fs').readFileSync('myservice.wsdl', 'utf8');

soap.listen(server, {
    // Server options.
    path: '/wsdl',
    services: myService,
    xml: xml,

    // WSDL options.
    attributesKey: 'theAttrs',
    valueKey: 'theVal',
    xmlKey: 'theXml'
});
```

--------------------------------

### Example Unit Test Case with `node-soap` Stubbing

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This JavaScript snippet provides an example of a unit test suite utilizing `soap-stub` for `node-soap` clients. It shows the `beforeEach` hook for retrieving and resetting the client stub, and a test case demonstrating how to trigger an error response from a stubbed SOAP operation to verify the application's error handling logic.

```JavaScript
// test.js
var soapStub = require('soap/soap-stub');

describe('myService', function() {
  var clientStub;
  var myService;

  beforeEach(function() {
    clientStub = soapStub.getStub('my client alias');
    soapStub.reset();
    myService.init(clientStub);
  });

  describe('failures', function() {
    beforeEach(function() {
      clientStub.SomeOperation.respondWithError();
    });

    it('should handle error responses', function() {
      myService.somethingThatCallsSomeOperation(function(err, response) {
        // handle the error response.
      });
    });
  });
});
```

--------------------------------

### Example: Calling Client.methodAsync with Promise

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Illustrates how to use the promise-based `Client.methodAsync` method. The promise resolves with an array containing the result, raw response, SOAP header, and raw request.

```javascript
client.MyFunctionAsync({name: 'value'}).then((result) => {
    // result is a javascript array containing result, rawResponse, soapheader, and rawRequest
    // result is a javascript object
    // rawResponse is the raw xml response string
    // soapHeader is the response soap header as a javascript object
    // rawRequest is the raw xml request string
  })
```

--------------------------------

### Initialize `soap-stub` for `node-soap` Client Unit Testing

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This JavaScript snippet outlines the setup for unit testing `node-soap` clients using `soap-stub` and `sinon`. It demonstrates how to create a `sinon` stub for a SOAP operation, attach `soap-stub`'s error and success response handlers, and register the configured client stub with an alias for later retrieval in tests.

```JavaScript
// test-initialization-script.js
var sinon = require('sinon');
var soapStub = require('soap/soap-stub');

var urlMyApplicationWillUseWithCreateClient = 'http://path-to-my-wsdl';
var clientStub = {
  SomeOperation: sinon.stub()
};

clientStub.SomeOperation.respondWithError = soapStub.createErroringStub({..error json...});
clientStub.SomeOperation.respondWithSuccess = soapStub.createRespondingStub({..success json...});

soapStub.registerClient('my client alias', urlMyApplicationWillUseWithCreateClient, clientStub);
```

--------------------------------

### Implement WS-Security UsernameToken in Node-SOAP

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This example illustrates how to apply WS-Security with UsernameToken authentication using the WSSecurity class. It shows the instantiation of WSSecurity with a username, password, and an optional options object. This setup is fundamental for services requiring username/password-based authentication within the SOAP message.

```javascript
  var options = {
    hasNonce: true,
    actor: 'actor'
  };
  var wsSecurity = new soap.WSSecurity('username', 'password', options)
  client.setSecurity(wsSecurity);
```

--------------------------------

### Example: SOAP XML Generated from JSON Arguments

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Shows an example of the SOAP XML message generated when passing a simple JSON object like `{name: 'value'}` as arguments to a SOAP method. It highlights the structure of the SOAP Envelope, Body, and the request element derived from the WSDL.

```xml
<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <Request xmlns="http://www.example.com/v1">
          <name>value</name>
      </Request>
   </soapenv:Body>
</soapenv:Envelope>
```

--------------------------------

### Example of WSDL xmlToObject and objectToXML usage in TypeScript

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Demonstrates how to use a WSDL instance to unmarshal an XML response from a GET request and marshal an object into XML for a POST request. It shows integration with Axios and type handling.

```typescript
// Abstracted from a real use case
import { AxiosInstance } from 'axios';
import { WSDL } from 'soap';
import { IProspectType } from './types';

// A WSDL in a string.
const WSDL_CONTENT = "...";

const httpClient: AxiosInstance = /* ... instantiate ... */;
const url = 'http://example.org/SoapService.svc';

const wsdl = new WSDL(WSDL_CONTENT, baseURL, {});

async function sampleGetCall(): IProspectType | undefined {
    const res = await httpClient.get(`${baseURL}/GetProspect`);

    const object = wsdl.xmlToObject(res.data);

    if (!object.ProspectType) {
      // Response did not contain the expected type
      return undefined;
    }
    // Optionally, unwrap and set defaults for some fields
    // Ensure that the object meets the expected prototype
    // Finally cast and return the result.
    return object.ProspectType as IProspectType;
}

async function samplePostCall(prospect: IProspectType) {
  // objectToXML(object, typeName, namespacePrefix, namespaceURI, ...)
  const objectBody = wsdl.objectToXML(obj, 'ProspectType', '', '');
  const data = `<?xml version="1.0" ?>${body}`;

  const res = await httpClient.post(`${baseURL}/ProcessProspect`, data);
  // Optionally, deserialize request and return response status.
}
```

--------------------------------

### Create SOAP Client from Inline XML WSDL Definition

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This JavaScript example illustrates how to instantiate a SOAP client directly from an XML string containing the WSDL definition. It then proceeds to invoke a service function (`MyFunction`) and print its output.

```javascript
  var soap = require('soap');
  var xml = `
    <?xml version="1.0" encoding="UTF-8"?>
    <definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
       <message name="MyFunctionRequest"/>
       <message name="MyFunctionResponse"/>
    
       <portType name="MyFunctionPortType">
          <operation name="MyFunction">
             <input message="MyFunctionRequest"/>
             <output message="MyFunctionResponse"/>
          </operation>
       </portType>
    
       <binding name="MyFunctionBinding" type="MyFunctionPortType">
          <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/wsdl/soap/http"/>
          <operation name="MyFunction">
             <soap:operation soapAction="MyFunction"/>
             <input><soap:body use="encoded"/></input>
             <output><soap:body use="encoded"/></output>
          </operation>
       </binding>
    
       <service name="MyService">
          <port binding="MyFunctionBinding" name="MyFunctionPort">
             <soap:address location="http://www.examples.com/MyFunction/" />
          </port>
       </service>
    </definitions>
  `;
  var args = {name: 'value'};

  soap.createClient(xml, {}, function(err, client) {
      client.MyFunction(args, function(err, result) {
          console.log(result);
      });
  });
```

--------------------------------

### `Client.setSecurity()` Method for Node-SOAP Client (APIDOC)

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Documentation for the `Client.setSecurity()` method, used to apply a specified security protocol to the SOAP client. It refers to a separate "Security" section for usage examples.

```APIDOC
Client.setSecurity(security) - use the specified security protocol
```

--------------------------------

### Example of $xml Key for Raw XML Insertion

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Illustrates how the `$xml` key is used to insert raw XML strings directly into the SOAP message without further parsing. It shows an input JavaScript object structure and its corresponding XML output, demonstrating how `siblingnode` is ignored when `$xml` is present.

```APIDOC
Input JSON:
{
  "dom": {
    "nodeone": {
      "$xml": "<parentnode type=\"type\"><childnode></childnode></parentnode>",
      "siblingnode": "Cant see me."
    },
    "nodetwo": {
      "parentnode": {
        "attributes": {
          "type": "type"
        },
        "childnode": ""
      }
    }
  }
}

Output XML:
<tns:dom>
  <tns:nodeone>
    <parentnode type="type">
      <childnode></childnode>
    </parentnode>
  </tns:nodeone>
  <tns:nodetwo>
    <tns:parentnode type="type">
      <tns:childnode></tns:childnode>
    </tns:parentnode>
  </tns:nodetwo>
</tns:dom>
```

--------------------------------

### Combine WS-Security and WS-SecurityCert in Node-SOAP

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This example shows how to combine both WSSecurity (UsernameToken) and WSSecurityCert (X.509 certificate) functionalities using the WSSecurityPlusCert class. It demonstrates instantiating both individual security objects and then passing them to WSSecurityPlusCert to apply multiple security layers simultaneously. This is useful for scenarios where both authentication and message signing/encryption are required.

```javascript
  var wsSecurity = new soap.WSSecurity(/* see WSSecurity above */);
  var wsSecurityCert = new soap.WSSecurityCert(/* see WSSecurityCert above */);
  var wsSecurityPlusCert = new soap.WSSecurityPlusCert(wsSecurity, wsSecurityCert);
  client.setSecurity(wsSecurityPlusCert);
```

--------------------------------

### XML Security Header with X509v3 Token Reference

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

An example of a SOAP header containing a `wsse:Security` block with a `ds:Signature` and a `wsse:SecurityTokenReference` pointing to an X509v3 token. This demonstrates how a digital signature is embedded in the SOAP header for security purposes.

```XML
<soap:Header>
    <wsse:Security>
        <ds:Signature>
            <ds:KeyInfo>
                <wsse:SecurityTokenReference>
                    <wsse:Reference URI="#X509-1234567890" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"/>
                </wsse:SecurityTokenReference>
            </ds:KeyInfo>
        </ds:Signature>
    </wsse:Security>
</soap:Header>
```

--------------------------------

### Configure Custom XML Key with wsdlOptions

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Example of setting a custom `xmlKey` within `wsdlOptions` to change the default `$xml` key used by `node-soap` for raw XML insertion. This allows developers to use a preferred key name for embedding unparsed XML.

```JavaScript
var wsdlOptions = {
  xmlKey: 'theXml'
};

soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
  // your code
});
```

--------------------------------

### Configure Custom Value Key with wsdlOptions

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Example of setting a custom `valueKey` within `wsdlOptions` to change the default `$value` key used by `node-soap` for parsed XML values. This is useful to avoid conflicts with reserved words or character restrictions.

```JavaScript
var wsdlOptions = {
  valueKey: 'theVal'
};

soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
  // your code
});
```

--------------------------------

### Accessing Received SOAP Headers in Service Method

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This JavaScript example demonstrates how a SOAP service method can access incoming SOAP headers by providing a third argument (`headers`) to the function. It shows how to extract a specific header value and return it as part of the response.

```javascript
  {
      HeadersAwareFunction: function(args, cb, headers) {
          return {
              name: headers.Token
          };
      }
  }
```

--------------------------------

### Include Custom Element in SOAP Signature References

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This example illustrates the effect of `additionalReferences: ['To']`, showing how a custom `To` element in the SOAP header is included as a `Reference` within the `Signature` element. This ensures the `To` element is signed as part of the message security.

```XML
<soap:Header>
    <To Id="To">localhost.com</To>
    <wsse:Security soap:mustUnderstand="1">
        <wsse:BinarySecurityToken>XXX</wsse:BinarySecurityToken>
        <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
            <SignedInfo>
                <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
                <!-- The "To" tag is signed and added as a reference -->
                <Reference URI="#To">
                    <Transforms>
                        <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                        <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                    </Transforms>
                    <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                    <DigestValue>XYZ</DigestValue>
                </Reference>
            </SignedInfo>
            <SignatureValue>
                Rf6M4F4puQuQHJIPtJz1CZIVvF3qOdpEEcuAiooWkX5ecnAHSf3RW3sOIzFUWW7VOOncJcts/3xr8DuN4+8Wm9hx1MoOcWJ6kyRIdVNbQWLseIcAhxYCntRY57T2TBXzpb0UPA56pry1+TEcnIQXhdIzG5YT+tTVTp+SZHHcnlP5Y+yqnIOH9wzgRvAovbydTYPCODF7Ana9K/7CSGDe7vpVT85CUYUcJE4DfTxaRa9gKkKrBdPN9vFVi0WfxtMF4kv23cZRCZzS5+CoLfPlx3mq65gVXsqH01RLbktNJq9VaQKcZUgapmUCMzrYhqyzUQJ8HrSHqe+ya2GsjlB0VQ==
            </SignatureValue>
            <KeyInfo>
                <wsse:SecurityTokenReference
                        xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
                    <wsse:Reference URI="#x509-c5c0d213676f4a6ba5e6fa58074eb57a"
                                    ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"/>
                </wsse:SecurityTokenReference>
            </KeyInfo>
        </Signature>
    </wsse:Security>
</soap:Header>
```

--------------------------------

### Configure node-soap for Simplified Namespace Ignoring

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This JavaScript snippet illustrates a simplified configuration for `ignoredNamespaces` in `node-soap` by setting it to `true` within the client options. While the text mentions `ignoreBaseNameSpaces`, this code example specifically shows `ignoredNamespaces: true`, which might be used to broadly ignore certain namespace behaviors, particularly when dealing with malformed WSDLs or problematic webservice responses.

```JavaScript
var options = {
ignoredNamespaces: true
}
```

--------------------------------

### Throw SOAP Fault with Custom HTTP Status Code

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This example extends the SOAP Fault mechanism by showing how to include a custom HTTP status code in the fault object. The `statusCode` property allows overriding the default HTTP response code without being included in the XML message.

```javascript
  throw {
    Fault: {
      Code: {
        Value: 'soap:Sender',
        Subcode: { value: 'rpc:BadArguments' }
      },
      Reason: { Text: 'Processing Error' },
      statusCode: 500
    }
  };
```

--------------------------------

### API Reference: soap.listen(server, path, services, wsdl, callback) / soap.listen(server, options)

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Documents the `soap.listen` function for creating and configuring a new SOAP server. It details the various parameters, including server options, WSDL definition, and callback, for setting up a SOAP endpoint.

```APIDOC
soap.listen(server, path, services, wsdl, callback)
soap.listen(server, options)
  - server (Object): A [http](https://nodejs.org/api/http.html) server or [Express](http://expressjs.com/) framework based server.
  - path (string)
  - options (Object): An object containing server options and [WSDL Options](#handling-xml-attributes-value-and-xml-wsdloptions)
    - path (string)
    - services (Object)
    - xml (string)
    - uri (string)
    - pfx (string | Buffer): The private key, certificate and CA certs of the server in PFX or PKCS12 format. (Mutually exclusive with the key, cert and ca options.)
    - key (string | Buffer): The private key of the server in PEM format. (Could be an array of keys). (Required)
    - passphrase (string): The passphrase for the private key or pfx.
    - cert (string | Buffer): The certificate key of the server in PEM format. (Could be an array of certs). (Required)
    - ca (string[] | Buffer[]): Trusted certificates in PEM format. If this is omitted several well known "root" CAs will be used, like VeriSign. These are used to authorize connections.
    - crl (string | string[]): PEM encoded CRLs (Certificate Revocation List)
    - ciphers (string): A description of the ciphers to use or exclude, separated by `:`. The default cipher suite is:
    - enableChunkedEncoding (boolean): Controls chunked transfer encoding in response. Some clients (such as Windows 10's MDM enrollment SOAP client) are sensitive to transfer-encoding mode and can't accept chunked response. This option lets users disable chunked transfer encoding for such clients. (Default: true)
  - services (Object)
  - wsdl (string): An XML string that defines the service.
  - callback (Function): A function to run after the server has been initialized.
  - Returns: Server
```

--------------------------------

### Create SOAP Client (Callback)

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Initializes a new SOAP client from a WSDL URL or a local filesystem path. This method uses a callback function to return the client instance or an error.

```APIDOC
soap.createClient(url: string, options?: object, callback: Function): void
  url: The WSDL URL or local filesystem path to the WSDL definition.
  options: Optional configuration object for the client.
  callback: A function to be called once the client is created, with (err, client) as arguments.
```

--------------------------------

### Create SOAP Client (Async/Promise)

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Initializes a new SOAP client from a WSDL URL or a local filesystem path. This asynchronous method returns a Promise that resolves with the client instance.

```APIDOC
soap.createClientAsync(url: string, options?: object): Promise<Client>
  url: The WSDL URL or local filesystem path to the WSDL definition.
  options: Optional configuration object for the client.
  Returns: A Promise that resolves with the created Client instance.
```

--------------------------------

### API Reference: soap.createClient Method

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Detailed API documentation for the `soap.createClient` method, used to create a new SOAP client from a WSDL URL or local path. It outlines all available parameters, their types, and descriptions, including various options for client configuration and behavior.

```APIDOC
soap.createClient(url[, options], callback) - create a new SOAP client from a WSDL url. Also supports a local filesystem path.
- `url` (*string*): A HTTP/HTTPS URL, XML or a local filesystem path.
- `options` (*Object*):
  - `endpoint` (*string*): Override the host specified by the SOAP service in the WSDL file.
  - `envelopeKey` (*string*): Set a custom envelope key. (**Default:** `'soap'`)
  - `preserveWhitespace` (*boolean*): Preserve any leading and trailing whitespace characters in text and cdata.
  - `escapeXML` (*boolean*): Escape special XML characters (e.g. `&`, `>`, `<` etc) in SOAP messages. (**Default:** `true`)
  - `suppressStack` (*boolean*): Suppress the full stack trace for error messages.
  - `returnFault` (*boolean*): Return an `Invalid XML` SOAP fault upon a bad request. (**Default:** `false`)
  - `forceSoap12Headers` (*boolean*): Enable SOAP 1.2 compliance.
  - `httpClient` (*Object*): Override the built-in HttpClient object with your own. Must implement `request(rurl, data, callback, exheaders, exoptions)`.
  - `request` (*Object*): Override the default request module ([Axios](https://axios-http.com/) as of `v0.40.0`).
  - `wsdl_headers` (*Object*): Set HTTP headers with values to be sent on WSDL requests.
  - `wsdl_options` (*Object*): Set options for the request module on WSDL requests. If using the default request module, see [Request Config | Axios Docs](https://axios-http.com/docs/req_config).
  - `disableCache` (*boolean*): Prevents caching WSDL files and option objects.
  - `wsdlCache` (*IWSDLCache*): Custom cache implementation. If not provided, defaults to caching WSDLs indefinitely.
  - `overridePromiseSuffix` (*string*): Override the default method name suffix of WSDL operations for Promise-based methods. If any WSDL operation name ends with `Async`, you must use this option. (**Default:** `Async`)
  - `normalizeNames` (*boolean*): Replace non-identifier characters (`[^a-z$_0-9]`) with `_` in WSDL operation names. Note: Clients using WSDLs with two operations like `soap:method` and `soap-method` will be overwritten. In this case, you must use bracket notation instead (`client['soap:method']()`).
  - `namespaceArrayElements` (*boolean*): Support non-standard array semantics. JSON arrays of the form `{list: [{elem: 1}, {elem: 2}]}` will be marshalled into XML as `<list><elem>1</elem></list> <list><elem>2</elem></list>`. If `false`, it would be marshalled into `<list> <elem>1</elem> <elem>2</elem> </list>`. (**Default:** `true`)
  - `stream` (*boolean*): Use streams to parse the XML SOAP responses. (**Default:** `false`)
  - `returnSaxStream` (*boolean*): Return the SAX stream, transferring responsibility of parsing XML to the end user. Only valid when the *stream* option is set to `true`. (**Default:** `false`)
  - `parseReponseAttachments` (*boolean*): Treat response as multipart/related response with MTOM attachment. Reach attachments on the `lastResponseAttachments` property of SoapClient. (**Default:** `false`)
- `callback` (*Function*):
  - `err` (*Error* | *<AggregateError>*)
  - `result` (*Any*)
- Returns: `Client`
```

--------------------------------

### Create SOAP Server (Options Object)

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Creates a new SOAP server instance using an options object for configuration. This provides a more flexible way to define server parameters.

```APIDOC
soap.listen(server: http.Server, options: object): void
  server: The HTTP server instance to attach the SOAP server to.
  options: An object containing server configuration, including path, services, wsdl, and optional callback.
```

--------------------------------

### Checkout Git Master Branch for Publishing

Source: https://github.com/vpulim/node-soap/blob/master/PUBLISHING.md

This command ensures the local repository is on the master branch, which is typically the base for preparing a new release.

```Shell
git checkout master
```

--------------------------------

### WSSecurityCert Constructor Options

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This section details the optional properties available for the options object when instantiating WSSecurityCert. These properties allow extensive customization of certificate-based WS-Security, including timestamp inclusion, signature algorithms, digest algorithms, and specific signer options for XML digital signatures.

```APIDOC
WSSecurityCert Constructor Options:
  hasTimeStamp: boolean (default: true) - Includes Timestamp tags.
  signatureTransformations: string[] (default: ['http://www.w3.org/2000/09/xmldsig#enveloped-signature', 'http://www.w3.org/2001/10/xml-exc-c14n#']) - Sets the Reference Transforms Algorithm.
  signatureAlgorithm: string (e.g., 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256') - Sets the signature algorithm.
  digestAlgorithm: string (default: 'http://www.w3.org/2001/04/xmlenc#sha256') - Sets the digest algorithm.
  additionalReferences: string[] (optional) - Array of Soap headers that need to be signed. Must be added using client.addSoapHeader('header').
  excludeReferencesFromSigning: string[] (optional) - An array of SOAP element names to exclude from signing (e.g., Body, Timestamp, To, Action).
  signerOptions: object (optional) - Passes options to the XML Signer package (https://github.com/yaronn/xml-crypto).
    existingPrefixes: object (optional) - A hash of prefixes and namespaces (prefix: namespace) that shouldn't be in the signature because they already exist in the XML (default: { 'wsse': 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' })
    prefix: string (optional) - Adds this value as a prefix for the generated signature tags.
    attrs: object (optional) - A hash of attributes and values (attrName: value) to add to the signature root node.
    idMode: string (optional) - Either 'wssecurity' to generate wsse-scoped reference Id on <Body> or undefined for an unscoped reference Id.
```

--------------------------------

### Create SOAP Client from HTTP/HTTPS WSDL URL

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This JavaScript snippet demonstrates how to create a SOAP client by providing a WSDL URL over HTTP or HTTPS. It initializes the client and then calls a specific function (`MyFunction`) with arguments, logging the result.

```javascript
  var soap = require('soap');
  var url = 'http://example.com/wsdl?wsdl';
  var args = {name: 'value'};

  soap.createClient(url, {}, function(err, client) {
      client.MyFunction(args, function(err, result) {
          console.log(result);
      });
  });
```

--------------------------------

### Client.method(args, callback, options) API Reference

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Documents the `Client.method` signature for making SOAP calls. It details the `args` object, the `callback` function, and various `options` for the request, including connection pooling, MTOM attachments, and Gzip forcing.

```APIDOC
Client.*method*(args, callback, options):
  args: Object - Arguments that generate an XML document inside of the SOAP Body section.
  callback: Function
  options: Object - Set options for the request module on WSDL requests.
    forever: boolean - Enables keep-alive connections and pools them.
    attachments: Array - Array of attachment objects. Converts request to MTOM.
      - mimetype: string - Content mimetype
      - contentId: string - Part id
      - name: string - File name
      - body: binary data
    forceMTOM: boolean - Send the request as MTOM even if no attachments.
    forceGzip: boolean - Force transfer-encoding in gzip (Default: false).
```

--------------------------------

### WSDL Constructor API Reference

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Documents the constructor for the WSDL class, allowing instantiation from WSDL content or URL, with optional base URL and configuration options.

```APIDOC
WSDL.constructor(wsdl: string, baseURL: string, options: object):
  wsdl: A string wSDL or an URL to the WSDL
  baseURL: base URL for the SOAP API
  options: options (see source for details), use {} as default.
```

--------------------------------

### Contribution Steps for WSDL-Related Pull Requests

Source: https://github.com/vpulim/node-soap/blob/master/CONTRIBUTING.md

Outlines the four essential steps for contributing changes related to WSDLs. It emphasizes creating generic WSDLs to reproduce issues, adding them to the test/wsdl path, committing changes to a feature branch, and issuing a pull request.

```Plaintext
1. Make your WSDL as generic as possible to recreate the issue
2. Add the WSDL to the appropriate path in test/wsdl.
3. Commit your changes to a feature branch within your fork.
4. Issue a pull request.
```

--------------------------------

### Override WSDL Import URIs/Paths in node-soap

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This snippet demonstrates how to programmatically override the URIs or paths of imported WSDL files. By providing a `overrideImportLocation` function in the `wsdl_options`, users can define custom logic to resolve import locations, for example, redirecting them to a local or specific remote URL.

```javascript
const options ={
    wsdl_options = {
        overrideImportLocation: (location) => {
          return 'https://127.0.0.1/imported-service.wsdl';
        }
    }
};
soap.createClient('https://127.0.0.1/service.wsdl', options, function(err, client) {
    // your code
});
```

--------------------------------

### Initialize NTLMSecurity with Positional Parameters

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Demonstrates how to initialize `NTLMSecurity` in `node-soap` by passing username, password, domain, and workstation as separate positional arguments to the constructor. This sets up NTLM authentication for the SOAP client.

```JavaScript
client.setSecurity(new soap.NTLMSecurity('username', 'password', 'domain', 'workstation'));
```

--------------------------------

### API Reference: soap.createClientAsync(url[, options])

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Documents the asynchronous method for creating a new SOAP client. It accepts a WSDL URL or local path and an optional options object, returning a Promise that resolves to a Client instance.

```APIDOC
soap.createClientAsync(url[, options])
  - Construct a Promise<Client> with the given WSDL file.
  - url (string): A HTTP/HTTPS URL, XML or a local filesystem path.
  - options (Object): See soap.createClient(url[, options], callback) for a description.
  - Returns: Promise<Client>
```

--------------------------------

### Override Default XML Attribute Key in node-soap

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

By default, `node-soap` uses `attributes` as the key for XML node attributes. This snippet demonstrates how to override this default key, for example to `$attributes`, by configuring `attributesKey` in the `wsdlOptions` object passed to `soap.createClient`. This is useful when `attributes` is a reserved key in the target system's XML structure.

```javascript
{
  parentnode: {
    childnode: {
      attributes: {
        name: 'childsname'
      },
      $value: 'Value'
    }
  }
}
```

```xml
<parentnode>
  <childnode name="childsname">Value</childnode>
</parentnode>
```

```xml
<attributes>
</attributes>
```

```javascript
var wsdlOptions = {
  attributesKey: '$attributes'
};

soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
  client.method({
    parentnode: {
      childnode: {
        $attributes: {
          name: 'childsname'
        },
        $value: 'Value'
      }
    }
  });
});
```

--------------------------------

### Rebasing and Squashing Git Commits for Pull Requests

Source: https://github.com/vpulim/node-soap/blob/master/CONTRIBUTING.md

This command sequence demonstrates how to rebase a feature branch onto the latest master and interactively squash commits. It is a mandatory step for pull requests to ensure a clean, linear, and concise commit history before merging.

```Shell
git checkout master;git pull upstream master;git checkout feature-branch;git rebase -i master
```

--------------------------------

### Implement Custom Deserialization in node-soap

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This section explains how to provide a `customDeserializer` object within `wsdlOptions` to handle specific data types during SOAP response deserialization. It provides an example of a custom function for `date` types, allowing users to implement their own logic for parsing values that `node-soap` might not recognize by default, such as non-standard date formats.

```javascript
var wsdlOptions = {
     customDeserializer: {
       date: function (text, context) {
         return text;
       }
     }
   };

   soap.createClient(__dirname + '/wsdl/default_namespace.wsdl', wsdlOptions, function (err, client) {
     ...
   });
```

--------------------------------

### Initialize NTLMSecurity with JSON Object

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Shows an alternative way to initialize `NTLMSecurity` using a single JSON object containing username, password, domain, and workstation properties. This provides a more flexible and readable way to configure NTLM authentication.

```JavaScript
var loginData = {username: 'username', password: 'password', domain: 'domain', workstation: 'workstation'};
client.setSecurity(new soap.NTLMSecurity(loginData));
```

--------------------------------

### General Contribution Steps for Other Pull Requests

Source: https://github.com/vpulim/node-soap/blob/master/CONTRIBUTING.md

Specifies the general contribution process for pull requests not directly related to WSDLs or client issues. It mandates providing a test in an appropriate *-test.js file under test/, committing changes to a feature branch, and issuing a pull request.

```Plaintext
1. Provide a test of some form in an appropriate *-test.js file under test/
2. Commit your changes to a feature branch within your fork.
3. Issue a pull request.
```

--------------------------------

### Contribution Steps for Client-Related Pull Requests

Source: https://github.com/vpulim/node-soap/blob/master/CONTRIBUTING.md

Details the process for submitting pull requests concerning client-side issues. It requires capturing and generalizing request/response XML and WSDLs, including only relevant messages/operations, adding files to test/request-response-samples, committing, and issuing a pull request.

```Plaintext
1. Capture the request / response XML via client.lastRequest and client.lastResponse as well as the WSDL.
2. Make the WSDL, request, and response XML as generic as possible.
3. Only include the messages or operations that are having issues.
4. Add the appropriate files to test/request-response-samples (see the README therein)
5. Commit your changes to a feature branch within your fork.
6. Issue a pull request
```

--------------------------------

### WSDL Constructor

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Initializes a WSDL object, which is used internally by the module to parse and manage WSDL definitions. This constructor takes the WSDL content, a base URL, and optional configuration.

```APIDOC
WSDL.constructor(wsdl: string, baseURL: string, options?: object): WSDL
  wsdl: The WSDL definition as a string or parsed object.
  baseURL: The base URL for resolving relative paths within the WSDL.
  options: Optional configuration for WSDL parsing.
```

--------------------------------

### Define SOAP Service and Listen with HTTP/Express

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This snippet demonstrates how to define a SOAP service with synchronous, asynchronous (callback and Promise-based), and header-aware functions. It also shows how to set up a SOAP server using both Node.js's built-in HTTP server and an Express application, listening for incoming SOAP requests.

```javascript
  var myService = {
      MyService: {
          MyPort: {
              MyFunction: function(args) {
                  return {
                      name: args.name
                  };
              },

              // This is how to define an asynchronous function with a callback.
              MyAsyncFunction: function(args, callback) {
                  // do some work
                  callback({
                      name: args.name
                  });
              },

              // This is how to define an asynchronous function with a Promise.
              MyPromiseFunction: function(args) {
                  return new Promise((resolve) => {
                    // do some work
                    resolve({
                      name: args.name
                    });
                  });
              },

              // This is how to receive incoming headers
              HeadersAwareFunction: function(args, cb, headers) {
                  return {
                      name: headers.Token
                  };
              },

              // You can also inspect the original `req`
              reallyDetailedFunction: function(args, cb, headers, req) {
                  console.log('SOAP `reallyDetailedFunction` request from ' + req.connection.remoteAddress);
                  return {
                      name: headers.Token
                  };
              }
          }
      }
  };

  var xml = require('fs').readFileSync('myservice.wsdl', 'utf8');

  //http server example
  var server = http.createServer(function(request,response) {
      response.end('404: Not Found: ' + request.url);
  });

  server.listen(8000);
  soap.listen(server, '/wsdl', myService, xml, function(){
    console.log('server initialized');
  });

  //express server example
  var app = express();
  //body parser middleware are supported (optional)
  app.use(bodyParser.raw({type: function(){return true;}, limit: '5mb'}));
  app.listen(8001, function(){
      //Note: /wsdl route will be handled by soap module
      //and all other routes & middleware will continue to work
      soap.listen(app, '/wsdl', myService, xml, function(){
        console.log('server initialized');
      });
  });

```

--------------------------------

### Client.service.port.method(args, callback, options, extraHeaders) API Reference

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Documents the `Client.service.port.method` signature for calling a SOAP method using a specific service and port. It includes parameters for arguments, callback, options, and additional HTTP headers.

```APIDOC
Client.*service*.*port*.*method*(args, callback[, options[, extraHeaders]]):
  args: Object - Arguments that generate an XML document inside of the SOAP Body section.
  callback: Function
  options: Object - See Client.*method*(args, callback, options) for description.
  extraHeaders: Object - Sets HTTP headers for the WSDL request.
```

--------------------------------

### node-soap Server Events Reference

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This section documents the events emitted by `node-soap` server instances. It details the 'request', 'response', and 'headers' events, including their callback signatures and the sequence in which they are triggered.

```APIDOC
Server instances emit the following events:

* request - Emitted for every received messages.
  The signature of the callback is `function(request, methodName)`.
* response - Emitted before sending SOAP response.
  The signature of the callback is `function(response, methodName)`.
* headers - Emitted when the SOAP Headers are not empty.
  The signature of the callback is `function(headers, methodName)`.

The sequence order of the calls is `request`, `headers` and then the dedicated
service method.
```

--------------------------------

### Client.methodAsync(args, options) API Reference

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Documents the asynchronous `Client.methodAsync` signature. It takes `args` and `options`, returning a Promise for non-blocking SOAP service interaction.

```APIDOC
Client.*method*Async(args, options):
  args: Object - Arguments that generate an XML document inside of the SOAP Body section.
  options: Object - See Client.*method*(args, callback, options) for description.
```

--------------------------------

### Apply Basic Authentication Security in node-soap

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

Demonstrates how to configure Basic Authentication for a node-soap client using a username and password.

```javascript
client.setSecurity(new soap.BasicAuthSecurity('username', 'password'));
```

--------------------------------

### WSSecurity Constructor Options

Source: https://github.com/vpulim/node-soap/blob/master/Readme.md

This section details the optional properties available for the options object when instantiating WSSecurity. These properties allow customization of the WS-Security UsernameToken, including password type, timestamp, nonce, and actor attributes, providing flexibility to meet specific security requirements.

```APIDOC
WSSecurity Constructor Options:
  passwordType: string ('PasswordDigest' or 'PasswordText', default: 'PasswordText')
  hasTimeStamp: boolean (default: true) - Adds Timestamp element.
  hasTokenCreated: boolean (default: true) - Adds Created element.
  hasNonce: boolean (default: false) - Adds Nonce element.
  mustUnderstand: boolean (default: false) - Adds mustUnderstand=1 attribute to security tag.
  actor: string (default: '') - Adds Actor attribute with given value to security tag.
```