@prismatic-io/spectral 5.2.0 → 5.2.1

package/dist/clients/soap/types.d.ts

@@ -1,32 +1,31 @@
 import { Connection } from "../../index";
-import { Client, IMTOMAttachments } from "soap";
+import { IMTOMAttachments } from "soap";
+/**
+ * SOAPConnection takes standard connection fields, and adds an optional `wsdlDefinitionUrl` field.
+ */
 export interface SOAPConnection extends Connection {
     fields: {
         [key: string]: unknown;
         wsdlDefinitionUrl?: string;
     };
 }
+/**
+ * This function determines if the object presented is a SOAP connection with a `wsdlDefinitionUrl` field.
+ * @param connection The connection to test
+ * @returns This function returns true if the connection is a SOAPConnection, and false otherwise.
+ */
 export declare const isSOAPConnection: (connection: unknown) => connection is SOAPConnection;
-export interface GetClient {
-    (connection: SOAPConnection): Promise<Client>;
-    (wsdlDefinition: string): Promise<Client>;
-}
+/**
+ * SOAP requests return a 4-tuple or 5-tuple with the response first, the XML response second, headers third, and the XML request fourth, and optional message attachments fifth.
+ */
+export declare type SOAPResponse = [any, any, any, any, IMTOMAttachments?];
+/**
+ * Overload the `soapRequest` function to take a variety of types of arguments.
+ */
 export interface SOAPRequest {
-    (params: RequestParams): Promise<[any, any, any, any, IMTOMAttachments?]>;
-    (params: RequestParams, methodParams: Record<string, unknown>): Promise<[
-        any,
-        any,
-        any,
-        any,
-        IMTOMAttachments?
-    ]>;
-    (params: RequestParams, methodParams: undefined): Promise<[
-        any,
-        any,
-        any,
-        any,
-        IMTOMAttachments?
-    ]>;
+    (params: RequestParams): Promise<SOAPResponse>;
+    (params: RequestParams, methodParams: Record<string, unknown>): Promise<SOAPResponse>;
+    (params: RequestParams, methodParams: undefined): Promise<SOAPResponse>;
 }
 export interface RequestParams {
     wsdlParam: SOAPConnection | string;
@@ -56,6 +55,11 @@ export interface BasicAuthConnection extends Connection {
         loginMethod: unknown;
     };
 }
+/**
+ * This function determines if the object presented is a Basic Auth connection with `username`, `password`, and `loginMethod` fields.
+ * @param connection The connection to test
+ * @returns This function returns true if the connection is a SOAPConnection, and false otherwise.
+ */
 export declare const isBasicAuthConnection: (connection: Connection) => connection is BasicAuthConnection;
 export interface SOAPAuth {
     (connection: BasicAuthConnection, wsdlDefinition: string): Promise<any>;

package/dist/clients/soap/types.js

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isBasicAuthConnection = exports.isSOAPConnection = void 0;
+/**
+ * This function determines if the object presented is a SOAP connection with a `wsdlDefinitionUrl` field.
+ * @param connection The connection to test
+ * @returns This function returns true if the connection is a SOAPConnection, and false otherwise.
+ */
 const isSOAPConnection = (connection) => {
     var _a;
     if (typeof connection === "object" && connection !== null)
@@ -8,6 +13,11 @@ const isSOAPConnection = (connection) => {
     return false;
 };
 exports.isSOAPConnection = isSOAPConnection;
+/**
+ * This function determines if the object presented is a Basic Auth connection with `username`, `password`, and `loginMethod` fields.
+ * @param connection The connection to test
+ * @returns This function returns true if the connection is a SOAPConnection, and false otherwise.
+ */
 const isBasicAuthConnection = (connection) => {
     const { fields } = connection;
     return ("username" in fields && "password" in fields && "loginMethod" in fields);

package/dist/clients/soap/utils.d.ts

@@ -1,13 +1,12 @@
-import { ClientOverrides, GenerateHeader, GetClient, SOAPAuth, SOAPRequest, DescribeWSDL } from "./types";
+import { ClientOverrides, GenerateHeader, SOAPAuth, SOAPConnection, SOAPRequest, DescribeWSDL } from "./types";
 import { Client } from "soap";
-export declare const describeWSDL: DescribeWSDL;
 declare const _default: {
+    describeWSDL: DescribeWSDL;
     generateHeader: GenerateHeader;
-    getSOAPClient: GetClient;
     getSOAPAuth: SOAPAuth;
+    getSOAPClient: <T extends string | SOAPConnection = string | SOAPConnection>(wsdlParam: T) => Promise<Client>;
     getWSDL: (wsdlDefinitionURL: string) => Promise<string>;
     overrideClientDefaults: (client: Client, overrides: ClientOverrides) => void;
     soapRequest: SOAPRequest;
-    describeWSDL: DescribeWSDL;
 };
 export default _default;

package/dist/clients/soap/utils.js

@@ -12,10 +12,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.describeWSDL = void 0;
 /* eslint-disable @typescript-eslint/no-unsafe-return */
-/* eslint-disable @typescript-eslint/no-unsafe-member-access */
-/* eslint-disable @typescript-eslint/no-unsafe-call */
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
 const types_1 = require("./types");
 const index_1 = require("../../index");
@@ -23,18 +20,25 @@ const soap_1 = require("soap");
 const axios_1 = __importDefault(require("axios"));
 const promises_1 = require("fs/promises");
 const uuid_1 = require("uuid");
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Optionally log out SOAP requests and responses for debugging purposes
+ *
+ * @param client A SOAP client that generates requests and responses
+ */
 const debugRequest = (client) => {
     console.debug(client.lastRequest);
     console.debug(client.lastResponse);
 };
+/**
+ * This function takes either the URL of a WSDL or the XML defining a WSDL, and returns an object describing the methods and attributes defined in the WSDL.
+ *
+ * @param wsdlParam Either the URL where a WSDL is stored, or the XML defining a WSDL.
+ * @returns An object containing the methods and attributes defined in a WSDL
+ */
 const describeWSDL = (wsdlParam) => __awaiter(void 0, void 0, void 0, function* () {
-    let client;
-    if (types_1.isSOAPConnection(wsdlParam)) {
-        client = yield getSOAPClient(wsdlParam);
-    }
-    else {
-        client = yield getSOAPClient(index_1.util.types.toString(wsdlParam));
-    }
+    const client = yield getSOAPClient(types_1.isSOAPConnection(wsdlParam) ? wsdlParam : index_1.util.types.toString(wsdlParam));
     try {
         const result = client.describe();
         return result;
@@ -43,7 +47,11 @@ const describeWSDL = (wsdlParam) => __awaiter(void 0, void 0, void 0, function*
         throw new Error("Unable to parse WSDL Services due to circular references");
     }
 });
-exports.describeWSDL = describeWSDL;
+/**
+ * Fetch a WSDL from a URL
+ * @param wsdlDefinitionURL The URL where the WSDL is stored
+ * @returns The WSDL's raw XML
+ */
 const getWSDL = (wsdlDefinitionURL) => __awaiter(void 0, void 0, void 0, function* () {
     const httpClient = axios_1.default.create({
         baseURL: wsdlDefinitionURL,
@@ -52,10 +60,15 @@ const getWSDL = (wsdlDefinitionURL) => __awaiter(void 0, void 0, void 0, functio
     const { data } = yield httpClient.get("");
     return index_1.util.types.toString(data);
 });
+/**
+ * Create a SOAP client given a WSDL or SOAPConnection
+ * @param wsdlParam a SOAPConnection or XML defining a WSDL
+ * @returns An HTTP client configured to query a SOAP-based API
+ */
 const getSOAPClient = (wsdlParam) => __awaiter(void 0, void 0, void 0, function* () {
     if (typeof wsdlParam === "string") {
         const wsdl = index_1.util.types.toString(wsdlParam);
-        const filePath = `/tmp/${uuid_1.v4()}.wsdl`;
+        const filePath = path_1.default.join(os_1.default.tmpdir(), `${uuid_1.v4()}.wsdl`);
         yield promises_1.writeFile(filePath, wsdl);
         const client = yield soap_1.createClientAsync(filePath);
         yield promises_1.rm(filePath);
@@ -74,6 +87,11 @@ const getSOAPClient = (wsdlParam) => __awaiter(void 0, void 0, void 0, function*
         throw new Error("WSDL Definition or the Connection field 'wsdlDefinitionURL' must be supplied.");
     }
 });
+/**
+ * Override some HTTP client defaults
+ * @param client The client to override
+ * @param overrides An endpoint URL or SOAP headers to override
+ */
 const overrideClientDefaults = (client, overrides) => {
     const { endpointURL, soapHeaders } = overrides;
     if (endpointURL) {
@@ -85,14 +103,14 @@ const overrideClientDefaults = (client, overrides) => {
         });
     }
 };
+/**
+ * Make a request to a SOAP-based API
+ * @param param0
+ * @param methodParams Parameters to pass to the specified SOAP method
+ * @returns The results from the SOAP request, including the full XML of the request and response
+ */
 const soapRequest = ({ wsdlParam, method, overrides, debug }, methodParams) => __awaiter(void 0, void 0, void 0, function* () {
-    let client;
-    if (types_1.isSOAPConnection(wsdlParam)) {
-        client = yield getSOAPClient(wsdlParam);
-    }
-    else {
-        client = yield getSOAPClient(wsdlParam);
-    }
+    const client = yield getSOAPClient(types_1.isSOAPConnection(wsdlParam) ? wsdlParam : index_1.util.types.toString(wsdlParam));
     if (overrides) {
         overrideClientDefaults(client, overrides);
     }
@@ -114,17 +132,19 @@ const soapRequest = ({ wsdlParam, method, overrides, debug }, methodParams) => _
         if (index_1.util.types.isBool(debug) && debug) {
             debugRequest(client);
         }
+        console.warn("Please verify that the method you specified exists in the WSDL specification.");
         throw error;
     }
 });
+/**
+ * Create a SOAP header
+ * @param wsdlParam A SOAPConnection or XML definition of a WSDL
+ * @param headerPayload The contents of a header XML node
+ * @param headerOptions Attributes for a header XML node, like namespace or xmlns
+ * @returns
+ */
 const generateHeader = (wsdlParam, headerPayload, headerOptions) => __awaiter(void 0, void 0, void 0, function* () {
-    let client;
-    if (types_1.isSOAPConnection(wsdlParam)) {
-        client = yield getSOAPClient(wsdlParam);
-    }
-    else {
-        client = yield getSOAPClient(wsdlParam);
-    }
+    const client = yield getSOAPClient(types_1.isSOAPConnection(wsdlParam) ? wsdlParam : index_1.util.types.toString(wsdlParam));
     let options = [];
     if (headerOptions) {
         options = Object.values(headerOptions);
@@ -132,6 +152,12 @@ const generateHeader = (wsdlParam, headerPayload, headerOptions) => __awaiter(vo
     const index = client.addSoapHeader(headerPayload, "", ...options);
     return client.getSoapHeaders()[index];
 });
+/**
+ * Fetch authentication information for a SOAPConnection
+ * @param connection The SOAPConnection
+ * @param wsdlDefinition The XML WSDL definition
+ * @returns
+ */
 const getSOAPAuth = (connection, wsdlDefinition) => __awaiter(void 0, void 0, void 0, function* () {
     if (types_1.isBasicAuthConnection(connection) && wsdlDefinition) {
         const { fields: { username, password, loginMethod }, } = connection;
@@ -155,11 +181,11 @@ const getSOAPAuth = (connection, wsdlDefinition) => __awaiter(void 0, void 0, vo
     }
 });
 exports.default = {
+    describeWSDL,
     generateHeader,
-    getSOAPClient,
     getSOAPAuth,
+    getSOAPClient,
     getWSDL,
     overrideClientDefaults,
     soapRequest,
-    describeWSDL: exports.describeWSDL,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismatic-io/spectral",
-  "version": "5.2.0",
+  "version": "5.2.1",
   "description": "Utility library for building Prismatic components",
   "keywords": [
     "prismatic"