conductor-node 8.3.0 → 8.4.1

package/README.md

@@ -158,16 +158,17 @@ const accountAddInput: QbdTypes.AccountAdd = {
 
 ## Error Handling
 
-The `ConductorError` has the following properties:
+The `ConductorError` and its subclasses have the following properties:
 
 ```ts
 {
   // 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.
-  developerMessage: string;
+  // 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.
@@ -177,15 +178,15 @@ The `ConductorError` has the following properties:
 
 ### Error Types
 
-The error object you receive will have one of the following category types:
+The error object you receive will have one of the following error types:
 
-| Type                    | Description                                                                               |
-| ----------------------- | ----------------------------------------------------------------------------------------- |
-| `authentication_error`  | Conductor can't authenticate you with the information provided. E.g. incorrect API key.   |
-| `connection_error`      | There was a network problem between your server and Conductor.                            |
-| `integration_error`     | An error occurred on the third-party integration's end while processing your request.     |
-| `internal_error`        | Something went wrong on Conductor's end. (These are rare.)                                |
-| `invalid_request_error` | You made an API call with the wrong parameters, in the wrong state, or in an invalid way. |
+| Type                           | Description                                                                                      |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| `ConductorIntegrationError`    | An error occurred on the third-party integration's end while processing your end-user's request. |
+| `ConductorInvalidRequestError` | You made an API call with the wrong parameters, in the wrong state, or in an invalid way.        |
+| `ConductorAuthenticationError` | Conductor cannot authenticate you with the credentials you provided. E.g., an incorrect API key. |
+| `ConductorConnectionError`     | There was a network problem between the client (on your server) and Conductor's servers.         |
+| `ConductorInternalError`       | Something went wrong on Conductor's end. (These are rare.)                                       |
 
 ### Example
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "conductor-node",
-    "version": "8.3.0",
+    "version": "8.4.1",
     "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,73 @@
+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 {
+    /**
+     * 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 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 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/errors.js

@@ -0,0 +1,115 @@
+"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 {
+    /**
+     * 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 end-user-friendly error message to display in your app.
+     */
+    endUserMessage;
+    /**
+     * The HTTP status code of the response that included the error.
+     */
+    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;

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

@@ -1,7 +1,7 @@
-import { 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 {
     [key: string]: unknown;
 }, R>(operationName: string, variables: V | undefined, operation: (variables: V | undefined) => Promise<R>, verbose: boolean): Promise<R>;
-export declare function generateConductorError(error: Error): ConductorError;
+export declare function wrapError(error: Error): ConductorError;

package/dist/src/graphql/graphqlOperationWrapper.js

@@ -3,9 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateConductorError = exports.graphqlOperationWrapper = exports.wrapGraphqlOperations = void 0;
+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) {
@@ -45,7 +45,7 @@ async function graphqlOperationWrapper(operationName, variables, operation, verb
         return result;
     }
     catch (error) {
-        const conductorError = generateConductorError(error);
+        const conductorError = wrapError(error);
         if (verbose) {
             const errorLog = {
                 duration: getDurationString(startTime),
@@ -59,49 +59,44 @@ async function graphqlOperationWrapper(operationName, variables, operation, verb
     }
 }
 exports.graphqlOperationWrapper = graphqlOperationWrapper;
-function generateConductorError(error) {
+function wrapError(error) {
     if (error instanceof graphql_request_1.ClientError) {
         const { response } = error;
         if ([404, 502, 503].includes(response.status)) {
-            return new error_1.ConductorError({
-                type: "connection_error",
-                code: error_1.DEFAULT_ERROR_CODE,
-                developerMessage: `The Conductor server returned a ${response.status} error, which may indicate that the server is down. Please alert the Conductor team if this error persists.`,
+            return (0, errors_1.generateConductorError)({
+                type: "CONNECTION_ERROR",
+                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,
             });
         }
         const nestedError = response.errors?.[0];
-        if (nestedError?.extensions["code"] === "GRAPHQL_VALIDATION_FAILED") {
-            return new error_1.ConductorError({
-                type: "temp",
-                code: error_1.DEFAULT_ERROR_CODE,
-                developerMessage: `The Conductor server is no longer compatible with your version of "${package_json_1.default.name}". Please run "yarn upgrade ${package_json_1.default.name} --latest" to update.`,
-                statusCode: response.status,
-            });
-        }
-        // TODO: Integrate with new error attributes.
-        const errorMessage = nestedError?.message ??
-            // Though `ClientError.response.error` is *not* defined in the type
-            // definition, we've seen it occur (e.g., attempting to access the
-            // `development` environment when `ngrok` is not running locally).
-            response["error"];
-        console.log("***********************");
-        if (errorMessage !== undefined) {
-            return new error_1.ConductorError({
-                type: "temp",
-                code: error_1.DEFAULT_ERROR_CODE,
-                developerMessage: errorMessage,
+        const errorExtensions = nestedError?.extensions;
+        if (errorExtensions) {
+            if (errorExtensions["code"] === "GRAPHQL_VALIDATION_FAILED") {
+                return (0, errors_1.generateConductorError)({
+                    type: "INVALID_REQUEST_ERROR",
+                    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,
+                });
+            }
+            return (0, errors_1.generateConductorError)({
+                type: errorExtensions["type"],
+                code: errorExtensions["code"],
+                message: nestedError.message,
+                endUserMessage: errorExtensions["endUserMessage"],
                 statusCode: response.status,
             });
         }
     }
-    return new error_1.ConductorError({
-        type: "temp",
-        code: error_1.DEFAULT_ERROR_CODE,
-        developerMessage: "Invalid JSON received from the Conductor API.",
+    return (0, errors_1.generateConductorError)({
+        type: "INTERNAL_ERROR",
+        code: "INVALID_JSON_RESPONSE",
+        message: "Invalid JSON received from the Conductor API.",
     });
 }
-exports.generateConductorError = generateConductorError;
+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,4 +1,5 @@
 import Client from "./Client";
 export default Client;
 export { type ClientOptions } from "./Client";
+export * from "./errors";
 export * as QbdTypes from "./integrations/qbd/qbdTypes";

package/dist/src/index.js

@@ -15,6 +15,9 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 var __importStar = (this && this.__importStar) || function (mod) {
     if (mod && mod.__esModule) return mod;
     var result = {};
@@ -31,4 +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("./errors"), exports);
 exports.QbdTypes = __importStar(require("./integrations/qbd/qbdTypes"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conductor-node",
-  "version": "8.3.0",
+  "version": "8.4.1",
   "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,18 +0,0 @@
-export declare const DEFAULT_ERROR_CODE = "CONDUCTOR__INTERNAL_SERVER_ERROR";
-export declare const DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please try again later.";
-interface ConductorRawError {
-    readonly type: string;
-    readonly code: string;
-    readonly developerMessage: string;
-    readonly endUserMessage?: string;
-    readonly statusCode?: number;
-}
-export declare class ConductorError extends Error {
-    readonly type: string;
-    readonly code: string;
-    readonly developerMessage: string;
-    readonly endUserMessage: string;
-    readonly statusCode: number | undefined;
-    constructor(raw: ConductorRawError);
-}
-export {};

package/dist/src/error.js

@@ -1,22 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConductorError = exports.DEFAULT_END_USER_MESSAGE = exports.DEFAULT_ERROR_CODE = void 0;
-exports.DEFAULT_ERROR_CODE = "CONDUCTOR__INTERNAL_SERVER_ERROR";
-exports.DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please try again later.";
-class ConductorError extends Error {
-    type;
-    code;
-    developerMessage;
-    endUserMessage;
-    statusCode;
-    constructor(raw) {
-        super(raw.developerMessage);
-        this.name = "ConductorError";
-        this.type = raw.type;
-        this.code = raw.code;
-        this.developerMessage = raw.developerMessage;
-        this.endUserMessage = raw.endUserMessage ?? exports.DEFAULT_END_USER_MESSAGE;
-        this.statusCode = raw.statusCode;
-    }
-}
-exports.ConductorError = ConductorError;