conductor-node 8.4.0 → 8.5.0

package/README.md

@@ -164,14 +164,19 @@ The `ConductorError` and its subclasses have the following properties:
 {
   // The error type.
   type: string;
-  // The error code.
+  // The unique error code. This is useful for adding special handling
+  // for specific errors.
   code: string;
-  // The developer-friendly error message for your logs.
+  // The error message for your logs.
   message: string;
   // The end-user-friendly error message to display in your app.
   endUserMessage: string;
-  // The HTTP status code.
-  statusCode: number | undefined;
+  // The HTTP status code of the response that included the error.
+  httpStatusCode: number | undefined;
+  // The error code provided by the third-party integration when `type`
+  // is `ConductorIntegrationError`. This is useful for adding special
+  // handling for specific errors from the third-party integration.
+  integrationCode: string | undefined;
 }
 ```
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "conductor-node",
-    "version": "8.4.0",
+    "version": "8.5.0",
     "description": "Easily integrate with the entire QuickBooks Desktop API with fully-typed async TypeScript",
     "author": "Danny Nemer <hi@DannyNemer.com>",
     "license": "MIT",

package/dist/src/errors.d.ts

@@ -0,0 +1,101 @@
+export declare const DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please try again later.";
+export interface ConductorErrorOptions {
+    readonly rawType: string;
+    readonly code: string;
+    readonly message: string;
+    readonly endUserMessage?: string;
+    readonly httpStatusCode?: number;
+    readonly integrationCode?: string;
+}
+/**
+ * The base error from which all other more specific Conductor errors derive.
+ * Specifically for errors returned from Conductor's API.
+ */
+export declare class ConductorError extends Error {
+    /**
+     * The error type.
+     */
+    readonly type: string;
+    /**
+     * The raw error type for internal debugging.
+     */
+    readonly rawType: string;
+    /**
+     * The unique error code. This is useful for adding special handling
+     * for specific errors.
+     */
+    readonly code: string;
+    /**
+     * The developer-friendly error message for your logs.
+     *
+     * (Defined in the base class but documented here for completeness.)
+     */
+    /**
+     * The end-user-friendly error message to display in your app.
+     */
+    readonly endUserMessage: string;
+    /**
+     * The HTTP status code of the response that included the error.
+     */
+    readonly httpStatusCode: number | undefined;
+    /**
+     * The error code provided by the third-party integration when `type` is
+     * `ConductorIntegrationError`. This is useful for adding special handling for
+     * specific errors from the third-party integration.
+     *
+     * The third-party integration's error codes are not standardized, so you
+     * should not rely on this code to be the same across integrations.
+     */
+    readonly integrationCode: string | undefined;
+    protected constructor(options: ConductorErrorOptions);
+}
+type ConductorErrorOptionsWithoutRawType = Omit<ConductorErrorOptions, "rawType">;
+/**
+ * Raised when an error occurs on the third-party integration's end while
+ * processing your end-user's request. E.g., QBWC failed to connect to
+ * QuickBooks Desktop on the end-user's computer.
+ */
+export declare class ConductorIntegrationError extends ConductorError {
+    static readonly rawType: string;
+    constructor(options: ConductorErrorOptionsWithoutRawType);
+}
+/**
+ * Raised when you make an API call with the wrong parameters, in the wrong
+ * state, or in an invalid way.
+ */
+export declare class ConductorInvalidRequestError extends ConductorError {
+    static readonly rawType = "INVALID_REQUEST_ERROR";
+    constructor(options: ConductorErrorOptionsWithoutRawType);
+}
+/**
+ * Raised when Conductor cannot authenticate you with the credentials you
+ * provided. E.g., an incorrect API key.
+ */
+export declare class ConductorAuthenticationError extends ConductorError {
+    static readonly rawType = "AUTHENTICATION_ERROR";
+    constructor(options: ConductorErrorOptionsWithoutRawType);
+}
+/**
+ * Raised when there is a network problem between the client (on your server)
+ * and Conductor's servers. E.g., a downed network or a bad TLS certificate.
+ */
+export declare class ConductorConnectionError extends ConductorError {
+    static readonly rawType = "CONNECTION_ERROR";
+    constructor(options: ConductorErrorOptionsWithoutRawType);
+}
+/**
+ * Raised when something goes wrong on Conductor's end. (These are rare.)
+ */
+export declare class ConductorInternalError extends ConductorError {
+    static readonly rawType = "INTERNAL_ERROR";
+    constructor(options: ConductorErrorOptionsWithoutRawType);
+}
+/**
+ * Raised as a fallback for any other error from Conductor that no other error
+ * type captures.
+ */
+export declare class ConductorUnknownError extends ConductorError {
+    constructor(options: ConductorErrorOptions);
+}
+export declare function generateConductorErrorFromType(options: ConductorErrorOptions): ConductorError;
+export {};

package/dist/src/errors.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateConductorErrorFromType = exports.ConductorUnknownError = exports.ConductorInternalError = exports.ConductorConnectionError = exports.ConductorAuthenticationError = exports.ConductorInvalidRequestError = exports.ConductorIntegrationError = exports.ConductorError = exports.DEFAULT_END_USER_MESSAGE = void 0;
+/* eslint-disable max-classes-per-file -- Use one module for all error classes. */
+exports.DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please try again later.";
+/**
+ * The base error from which all other more specific Conductor errors derive.
+ * Specifically for errors returned from Conductor's API.
+ */
+class ConductorError extends Error {
+    /**
+     * The error type.
+     */
+    type;
+    /**
+     * The raw error type for internal debugging.
+     */
+    rawType;
+    /**
+     * The unique error code. This is useful for adding special handling
+     * for specific errors.
+     */
+    code;
+    /**
+     * The developer-friendly error message for your logs.
+     *
+     * (Defined in the base class but documented here for completeness.)
+     */
+    // public readonly message: string;
+    /**
+     * The end-user-friendly error message to display in your app.
+     */
+    endUserMessage;
+    /**
+     * The HTTP status code of the response that included the error.
+     */
+    httpStatusCode;
+    /**
+     * The error code provided by the third-party integration when `type` is
+     * `ConductorIntegrationError`. This is useful for adding special handling for
+     * specific errors from the third-party integration.
+     *
+     * The third-party integration's error codes are not standardized, so you
+     * should not rely on this code to be the same across integrations.
+     */
+    integrationCode;
+    constructor(options) {
+        super(options.message);
+        // Set `name` to the constructor name so that the error appears in logs as
+        // `[ConductorError: foo]` instead of `[Error: foo]`.
+        this.name = this.constructor.name;
+        // 1. Set `type`, even though it's redundant with `name`, because `name`
+        //    does not appear when doing `console.log(error)` unlike all other
+        //    properties we set.
+        // 2. Set `type` to the constructor name to ensure that subclasses of
+        //    `ConductorError` always have the correct `type` even if they are
+        //    instantiated with the wrong options.
+        this.type = this.constructor.name;
+        this.rawType = options.rawType;
+        this.code = options.code;
+        this.endUserMessage = options.endUserMessage ?? exports.DEFAULT_END_USER_MESSAGE;
+        this.httpStatusCode = options.httpStatusCode;
+        this.integrationCode = options.integrationCode;
+    }
+}
+exports.ConductorError = ConductorError;
+/**
+ * Raised when an error occurs on the third-party integration's end while
+ * processing your end-user's request. E.g., QBWC failed to connect to
+ * QuickBooks Desktop on the end-user's computer.
+ */
+class ConductorIntegrationError extends ConductorError {
+    static rawType = "INTEGRATION_ERROR";
+    constructor(options) {
+        super({ ...options, rawType: ConductorIntegrationError.rawType });
+    }
+}
+exports.ConductorIntegrationError = ConductorIntegrationError;
+/**
+ * Raised when you make an API call with the wrong parameters, in the wrong
+ * state, or in an invalid way.
+ */
+class ConductorInvalidRequestError extends ConductorError {
+    static rawType = "INVALID_REQUEST_ERROR";
+    constructor(options) {
+        super({ ...options, rawType: ConductorInvalidRequestError.rawType });
+    }
+}
+exports.ConductorInvalidRequestError = ConductorInvalidRequestError;
+/**
+ * Raised when Conductor cannot authenticate you with the credentials you
+ * provided. E.g., an incorrect API key.
+ */
+class ConductorAuthenticationError extends ConductorError {
+    static rawType = "AUTHENTICATION_ERROR";
+    constructor(options) {
+        super({ ...options, rawType: ConductorAuthenticationError.rawType });
+    }
+}
+exports.ConductorAuthenticationError = ConductorAuthenticationError;
+/**
+ * Raised when there is a network problem between the client (on your server)
+ * and Conductor's servers. E.g., a downed network or a bad TLS certificate.
+ */
+class ConductorConnectionError extends ConductorError {
+    static rawType = "CONNECTION_ERROR";
+    constructor(options) {
+        super({ ...options, rawType: ConductorConnectionError.rawType });
+    }
+}
+exports.ConductorConnectionError = ConductorConnectionError;
+/**
+ * Raised when something goes wrong on Conductor's end. (These are rare.)
+ */
+class ConductorInternalError extends ConductorError {
+    static rawType = "INTERNAL_ERROR";
+    constructor(options) {
+        super({ ...options, rawType: ConductorInternalError.rawType });
+    }
+}
+exports.ConductorInternalError = ConductorInternalError;
+/**
+ * Raised as a fallback for any other error from Conductor that no other error
+ * type captures.
+ */
+class ConductorUnknownError extends ConductorError {
+    // Override the `protected` constructor in the base class even though we are
+    // not overriding `rawType`.
+    constructor(options) {
+        super(options);
+    }
+}
+exports.ConductorUnknownError = ConductorUnknownError;
+function generateConductorErrorFromType(options) {
+    switch (options.rawType) {
+        case ConductorIntegrationError.rawType: {
+            return new ConductorIntegrationError(options);
+        }
+        case ConductorInvalidRequestError.rawType: {
+            return new ConductorInvalidRequestError(options);
+        }
+        case ConductorAuthenticationError.rawType: {
+            return new ConductorAuthenticationError(options);
+        }
+        case ConductorConnectionError.rawType: {
+            return new ConductorConnectionError(options);
+        }
+        case ConductorInternalError.rawType: {
+            return new ConductorInternalError(options);
+        }
+        default: {
+            return new ConductorUnknownError(options);
+        }
+    }
+}
+exports.generateConductorErrorFromType = generateConductorErrorFromType;

package/dist/src/graphql/graphqlOperationWrapper.d.ts

@@ -1,4 +1,4 @@
-import type { ConductorError } from "../error";
+import type { ConductorError } from "../errors";
 import type { getSdk } from "../graphql/__generated__/operationTypes";
 export declare function wrapGraphqlOperations<T extends ReturnType<typeof getSdk>>(graphqlOperations: T, verbose: boolean): T;
 export declare function graphqlOperationWrapper<V extends {

package/dist/src/graphql/graphqlOperationWrapper.js

@@ -5,7 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.wrapError = exports.graphqlOperationWrapper = exports.wrapGraphqlOperations = void 0;
 const package_json_1 = __importDefault(require("../../package.json"));
-const error_1 = require("../error");
+const errors_1 = require("../errors");
 const graphql_request_1 = require("graphql-request");
 const node_util_1 = __importDefault(require("node:util"));
 function wrapGraphqlOperations(graphqlOperations, verbose) {
@@ -59,45 +59,42 @@ async function graphqlOperationWrapper(operationName, variables, operation, verb
     }
 }
 exports.graphqlOperationWrapper = graphqlOperationWrapper;
+function getDurationString(startTime) {
+    const duration = Date.now() - startTime;
+    return `${Math.round(duration / 10) / 100}s`;
+}
 function wrapError(error) {
     if (error instanceof graphql_request_1.ClientError) {
         const { response } = error;
         if ([404, 502, 503].includes(response.status)) {
-            return (0, error_1.generateConductorError)({
-                type: "CONNECTION_ERROR",
+            return new errors_1.ConductorConnectionError({
                 code: "SERVER_UNAVAILABLE",
                 message: `The Conductor server returned a ${response.status} error, which may indicate that the server is unavailable. Please alert the Conductor team if this error persists.`,
-                statusCode: response.status,
+                httpStatusCode: response.status,
             });
         }
         const nestedError = response.errors?.[0];
         const errorExtensions = nestedError?.extensions;
         if (errorExtensions) {
             if (errorExtensions["code"] === "GRAPHQL_VALIDATION_FAILED") {
-                return (0, error_1.generateConductorError)({
-                    type: "INVALID_REQUEST_ERROR",
+                return new errors_1.ConductorInvalidRequestError({
                     code: "CLIENT_OUTDATED",
                     message: `Your version of "${package_json_1.default.name}" is not longer compatible with the Conductor server. Please run "yarn upgrade ${package_json_1.default.name} --latest" to update.`,
-                    statusCode: response.status,
+                    httpStatusCode: response.status,
                 });
             }
-            return (0, error_1.generateConductorError)({
-                type: errorExtensions["type"],
+            return (0, errors_1.generateConductorErrorFromType)({
+                rawType: errorExtensions["type"],
                 code: errorExtensions["code"],
                 message: nestedError.message,
                 endUserMessage: errorExtensions["endUserMessage"],
-                statusCode: response.status,
+                httpStatusCode: response.status,
             });
         }
     }
-    return (0, error_1.generateConductorError)({
-        type: "INTERNAL_ERROR",
+    return new errors_1.ConductorInternalError({
         code: "INVALID_JSON_RESPONSE",
         message: "Invalid JSON received from the Conductor API.",
     });
 }
 exports.wrapError = wrapError;
-function getDurationString(startTime) {
-    const duration = Date.now() - startTime;
-    return `${Math.round(duration / 10) / 100}s`;
-}

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 import Client from "./Client";
 export default Client;
 export { type ClientOptions } from "./Client";
-export * from "./error";
+export * from "./errors";
 export * as QbdTypes from "./integrations/qbd/qbdTypes";

package/dist/src/index.js

@@ -34,5 +34,5 @@ exports.QbdTypes = void 0;
 const Client_1 = __importDefault(require("./Client"));
 // eslint-disable-next-line unicorn/prefer-export-from -- We need `Client` to be the default export, which is impossible to define with `export from`.
 exports.default = Client_1.default;
-__exportStar(require("./error"), exports);
+__exportStar(require("./errors"), exports);
 exports.QbdTypes = __importStar(require("./integrations/qbd/qbdTypes"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conductor-node",
-  "version": "8.4.0",
+  "version": "8.5.0",
   "description": "Easily integrate with the entire QuickBooks Desktop API with fully-typed async TypeScript",
   "author": "Danny Nemer <hi@DannyNemer.com>",
   "license": "MIT",

package/dist/src/error.d.ts

@@ -1,57 +0,0 @@
-export declare const DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please try again later.";
-export interface ConductorErrorOptions {
-    readonly type: string;
-    readonly code: string;
-    readonly message: string;
-    readonly endUserMessage?: string;
-    readonly statusCode?: number;
-}
-/**
- * The base error from which all other more specific Conductor errors derive.
- * Specifically for errors returned from Conductor's API.
- */
-export declare class ConductorError extends Error {
-    readonly type: string;
-    readonly rawType: string;
-    readonly code: string;
-    readonly endUserMessage: string;
-    readonly statusCode: number | undefined;
-    constructor(options: ConductorErrorOptions);
-}
-/**
- * Raised when an error occurs on the third-party integration's end while
- * processing your end-user's request. E.g., QBWC failed to connect to
- * QuickBooks Desktop on the end-user's computer.
- */
-export declare class ConductorIntegrationError extends ConductorError {
-}
-/**
- * Raised when you make an API call with the wrong parameters, in the wrong
- * state, or in an invalid way.
- */
-export declare class ConductorInvalidRequestError extends ConductorError {
-}
-/**
- * Raised when Conductor cannot authenticate you with the credentials you
- * provided. E.g., an incorrect API key.
- */
-export declare class ConductorAuthenticationError extends ConductorError {
-}
-/**
- * Raised when there is a network problem between the client (on your server)
- * and Conductor's servers. E.g., a downed network or a bad TLS certificate.
- */
-export declare class ConductorConnectionError extends ConductorError {
-}
-/**
- * Raised when something goes wrong on Conductor's end. (These are rare.)
- */
-export declare class ConductorInternalError extends ConductorError {
-}
-/**
- * Raised as a fallback for any other error from Conductor that no other error
- * type captures.
- */
-export declare class ConductorUnknownError extends ConductorError {
-}
-export declare function generateConductorError(rawConductorError: ConductorErrorOptions): ConductorError;

package/dist/src/error.js

@@ -1,99 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateConductorError = exports.ConductorUnknownError = exports.ConductorInternalError = exports.ConductorConnectionError = exports.ConductorAuthenticationError = exports.ConductorInvalidRequestError = exports.ConductorIntegrationError = exports.ConductorError = exports.DEFAULT_END_USER_MESSAGE = void 0;
-/* eslint-disable max-classes-per-file -- Keep the error classes together */
-exports.DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please try again later.";
-/**
- * The base error from which all other more specific Conductor errors derive.
- * Specifically for errors returned from Conductor's API.
- */
-class ConductorError extends Error {
-    type;
-    rawType;
-    code;
-    endUserMessage;
-    statusCode;
-    constructor(options) {
-        super(options.message);
-        // Set `name` to the constructor name so that the error appears in logs as
-        // `[ConductorError: foo]` instead of `[Error: foo]`.
-        this.name = this.constructor.name;
-        // 1. Set `type`, even though it's redundant with `name`, because `name`
-        //    does not appear when doing `console.log(error)` unlike all other
-        //    properties we set.
-        // 2. Set `type` to the constructor name to ensure that subclasses of
-        //    `ConductorError` always have the correct `type` even if they are
-        //    instantiated with the wrong options.
-        this.type = this.constructor.name;
-        this.rawType = options.type;
-        this.code = options.code;
-        this.endUserMessage = options.endUserMessage ?? exports.DEFAULT_END_USER_MESSAGE;
-        this.statusCode = options.statusCode;
-    }
-}
-exports.ConductorError = ConductorError;
-/**
- * Raised when an error occurs on the third-party integration's end while
- * processing your end-user's request. E.g., QBWC failed to connect to
- * QuickBooks Desktop on the end-user's computer.
- */
-class ConductorIntegrationError extends ConductorError {
-}
-exports.ConductorIntegrationError = ConductorIntegrationError;
-/**
- * Raised when you make an API call with the wrong parameters, in the wrong
- * state, or in an invalid way.
- */
-class ConductorInvalidRequestError extends ConductorError {
-}
-exports.ConductorInvalidRequestError = ConductorInvalidRequestError;
-/**
- * Raised when Conductor cannot authenticate you with the credentials you
- * provided. E.g., an incorrect API key.
- */
-class ConductorAuthenticationError extends ConductorError {
-}
-exports.ConductorAuthenticationError = ConductorAuthenticationError;
-/**
- * Raised when there is a network problem between the client (on your server)
- * and Conductor's servers. E.g., a downed network or a bad TLS certificate.
- */
-class ConductorConnectionError extends ConductorError {
-}
-exports.ConductorConnectionError = ConductorConnectionError;
-/**
- * Raised when something goes wrong on Conductor's end. (These are rare.)
- */
-class ConductorInternalError extends ConductorError {
-}
-exports.ConductorInternalError = ConductorInternalError;
-/**
- * Raised as a fallback for any other error from Conductor that no other error
- * type captures.
- */
-class ConductorUnknownError extends ConductorError {
-}
-exports.ConductorUnknownError = ConductorUnknownError;
-function generateConductorError(rawConductorError) {
-    switch (rawConductorError.type) {
-        case "INTEGRATION_ERROR": {
-            return new ConductorIntegrationError(rawConductorError);
-        }
-        case "INVALID_REQUEST_ERROR": {
-            return new ConductorInvalidRequestError(rawConductorError);
-        }
-        case "AUTHENTICATION_ERROR": {
-            return new ConductorAuthenticationError(rawConductorError);
-        }
-        case "CONNECTION_ERROR": {
-            return new ConductorConnectionError(rawConductorError);
-        }
-        case "INTERNAL_ERROR": {
-            return new ConductorInternalError(rawConductorError);
-        }
-        default: {
-            return new ConductorUnknownError(rawConductorError);
-        }
-    }
-}
-exports.generateConductorError = generateConductorError;