conductor-node 8.4.1 → 8.5.1

package/README.md

@@ -164,15 +164,19 @@ The `ConductorError` and its subclasses have the following properties:
 {
   // The error type.
   type: string;
-  // The unique error code. This is useful for adding special handling for
-  // specific errors.
+  // The unique error code. This is useful for adding special handling
+  // for specific errors.
   code: string;
-  // The error message for your logs.
+  // The developer 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;
 }
 ```
 
@@ -180,13 +184,13 @@ The `ConductorError` and its subclasses have the following properties:
 
 The error object you receive will have one of the following error types:
 
-| 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.)                                       |
+| Type                           | Description                                                                                                                                                              |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ConductorIntegrationError`    | An error occurred on the third-party integration's end while processing your end-user's request. E.g., cannot connect to QuickBooks Desktop on your end-user's computer. |
+| `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
 
@@ -201,7 +205,14 @@ try {
   });
 } catch (error) {
   if (error instanceof ConductorError) {
-    // Update your app's UI to display `error.endUserMessage`.
+    // TODO: Update your app's UI to display `error.endUserMessage`.
+
+    // RECOMMENDED: Send a *warning* to Sentry for integration-errors, which are
+    // your end-user's fault (e.g., cannot connect to QBD on your end-user's
+    // computer) or an *error* for other errors (e.g., invalid API key).
+    Sentry.captureException(error, {
+      level: error instanceof ConductorIntegrationError ? "warning" : "error",
+    });
   }
   // ...
 }
@@ -221,7 +232,8 @@ conductor.qbd.account
   })
   .catch((error) => {
     if (error instanceof ConductorError) {
-      // Update your app's UI to display `error.endUserMessage`.
+      // TODO: Update your app's UI to display `error.endUserMessage`.
+      // ...
     }
     // ...
   });

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "conductor-node",
-    "version": "8.4.1",
+    "version": "8.5.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

@@ -1,10 +1,11 @@
 export declare const DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please try again later.";
 export interface ConductorErrorOptions {
-    readonly type: string;
+    readonly rawType: string;
     readonly code: string;
     readonly message: string;
     readonly endUserMessage?: string;
-    readonly statusCode?: number;
+    readonly httpStatusCode?: number;
+    readonly integrationCode?: string;
 }
 /**
  * The base error from which all other more specific Conductor errors derive.
@@ -24,6 +25,11 @@ export declare class ConductorError extends Error {
      * 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.
      */
@@ -31,43 +37,65 @@ export declare class ConductorError extends Error {
     /**
      * The HTTP status code of the response that included the error.
      */
-    readonly statusCode: number | undefined;
-    constructor(options: ConductorErrorOptions);
+    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.
+ * processing your end-user's request. E.g., cannot 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 generateConductorError(rawConductorError: ConductorErrorOptions): ConductorError;
+export declare function generateConductorErrorFromType(options: ConductorErrorOptions): ConductorError;
+export {};

package/dist/src/errors.js

@@ -1,7 +1,7 @@
 "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.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.
@@ -21,6 +21,12 @@ class ConductorError extends Error {
      * 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.
      */
@@ -28,7 +34,16 @@ class ConductorError extends Error {
     /**
      * The HTTP status code of the response that included the error.
      */
-    statusCode;
+    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
@@ -41,19 +56,24 @@ class ConductorError extends Error {
         //    `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.rawType = options.rawType;
         this.code = options.code;
         this.endUserMessage = options.endUserMessage ?? exports.DEFAULT_END_USER_MESSAGE;
-        this.statusCode = options.statusCode;
+        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.
+ * processing your end-user's request. E.g., cannot 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;
 /**
@@ -61,6 +81,10 @@ exports.ConductorIntegrationError = ConductorIntegrationError;
  * 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;
 /**
@@ -68,6 +92,10 @@ exports.ConductorInvalidRequestError = ConductorInvalidRequestError;
  * 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;
 /**
@@ -75,12 +103,20 @@ exports.ConductorAuthenticationError = ConductorAuthenticationError;
  * 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;
 /**
@@ -88,28 +124,33 @@ exports.ConductorInternalError = ConductorInternalError;
  * 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 generateConductorError(rawConductorError) {
-    switch (rawConductorError.type) {
-        case "INTEGRATION_ERROR": {
-            return new ConductorIntegrationError(rawConductorError);
+function generateConductorErrorFromType(options) {
+    switch (options.rawType) {
+        case ConductorIntegrationError.rawType: {
+            return new ConductorIntegrationError(options);
         }
-        case "INVALID_REQUEST_ERROR": {
-            return new ConductorInvalidRequestError(rawConductorError);
+        case ConductorInvalidRequestError.rawType: {
+            return new ConductorInvalidRequestError(options);
         }
-        case "AUTHENTICATION_ERROR": {
-            return new ConductorAuthenticationError(rawConductorError);
+        case ConductorAuthenticationError.rawType: {
+            return new ConductorAuthenticationError(options);
         }
-        case "CONNECTION_ERROR": {
-            return new ConductorConnectionError(rawConductorError);
+        case ConductorConnectionError.rawType: {
+            return new ConductorConnectionError(options);
         }
-        case "INTERNAL_ERROR": {
-            return new ConductorInternalError(rawConductorError);
+        case ConductorInternalError.rawType: {
+            return new ConductorInternalError(options);
         }
         default: {
-            return new ConductorUnknownError(rawConductorError);
+            return new ConductorUnknownError(options);
         }
     }
 }
-exports.generateConductorError = generateConductorError;
+exports.generateConductorErrorFromType = generateConductorErrorFromType;

package/dist/src/graphql/graphqlOperationWrapper.js

@@ -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, errors_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, errors_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, errors_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, errors_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/package.json

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