conductor-node 8.5.3 → 8.6.0

package/README.md

@@ -192,14 +192,8 @@ The error object you receive will have one of the following error types:
 | `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.)                                                                                                               |
 
-### Alerting
-
-We recommend sending a **warning** to your error-tracking service (e.g., Sentry) for instances of `ConductorIntegrationError`, which are your end-user's fault (e.g., cannot connect to QBD on your end-user's computer) and sending an **error** for all other errors (e.g., invalid API key).
-
 ### Example
 
-**NOTE:** We do not expect you to individually implement error handling as shown below for every API call. Ideally, we recommend implementing error handling in a single place in your app, such as a global error handler.
-
 In the form of a rejected promise:
 
 ```ts
@@ -238,3 +232,64 @@ try {
   }
 }
 ```
+
+### Integration
+
+**NOTE:** We do not expect you to individually wrap every API call like the examples above. Instead, you should only need to wrap a specific Conductor API request when adding special handling for specific errors, such as checking the property `error.code`.
+
+Ideally, if your server does not already, we expect you to have a single global error handler, such as [`app.use((error, req, res, next) => { ... })` in Express](https://expressjs.com/en/guide/error-handling.html#writing-error-handlers), or [`formatError` in Apollo Server](https://apollographql.com/docs/apollo-server/data/errors/#for-client-responses). In such a handler, you can do the following:
+
+1. Ensure your app's UI shows your end-user the property `error.endUserMessage` of any `ConductorError` instance for any Conductor request while you log the rest.
+2. Send the full error object to your error-tracking service (e.g., Sentry) for all `ConductorError` instances, for which we recommend:
+   1. Send a **warning** to your error-tracking service for instances of `ConductorIntegrationError`, which are your end-user's fault; e.g., cannot connect to QBD on your end-user's computer.
+   2. Send an **error** for all other `ConductorError` instances; e.g., invalid API key.
+
+For example, here is how you might do this in Express:
+
+```ts
+app.use((error, req, res, next) => {
+  if (error instanceof ConductorError) {
+    Sentry.captureException(error, {
+      level: error instanceof ConductorIntegrationError ? "warning" : "error",
+    });
+    // Return a different error message for your end-user to see in your app's UI.
+    res.status(500).send({ error: { message: error.endUserMessage } });
+  } else {
+    // ...
+  }
+});
+```
+
+And here is how you might do this in Apollo Server:
+
+```ts
+import { unwrapResolverError } from "@apollo/server/errors";
+
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  formatError: (formattedError, error) => {
+    const originalError = unwrapResolverError(originalErrorWrapped);
+
+    if (originalError instanceof ConductorError) {
+      Sentry.captureException(originalError, {
+        level:
+          originalError instanceof ConductorIntegrationError
+            ? "warning"
+            : "error",
+      });
+      // Return a different error message for your end-user to see in your app's UI.
+      return {
+        ...formattedError,
+        message: originalError.endUserMessage,
+      };
+    } else {
+      // ...
+    }
+
+    // Otherwise return the formatted error. This error can also
+    // be manipulated in other ways, as long as it's returned.
+    return formattedError;
+  },
+});
+```

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "conductor-node",
-    "version": "8.5.3",
+    "version": "8.6.0",
     "description": "Easily integrate with the entire QuickBooks Desktop API with fully-typed async TypeScript",
     "author": "Danny Nemer <hi@DannyNemer.com>",
     "license": "MIT",
@@ -24,13 +24,13 @@
     },
     "dependencies": {
         "graphql": "^16.6.0",
-        "graphql-request": "^5.0.0"
+        "graphql-request": "~5.1.0"
     },
     "devDependencies": {
-        "@graphql-codegen/add": "^3.2.1",
-        "@graphql-codegen/cli": "^2.13.11",
+        "@graphql-codegen/add": "^4.0.1",
+        "@graphql-codegen/cli": "^3.2.1",
         "@graphql-codegen/typescript-graphql-request": "^4.5.8",
-        "@graphql-codegen/typescript-operations": "^2.5.6",
+        "@graphql-codegen/typescript-operations": "^3.0.1",
         "tsc-alias": "^1.7.0"
     },
     "keywords": [

package/dist/src/errors.d.ts

@@ -1,15 +1,22 @@
 export declare const DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please try again later.";
 export interface ConductorErrorOptions {
-    readonly rawType: string;
+    readonly type: string;
     readonly code: string;
     readonly message: string;
     readonly endUserMessage?: string;
     readonly httpStatusCode?: number;
     readonly integrationCode?: string;
 }
+/**
+ * The raw GraphQL error that Conductor's API returns.
+ */
+export interface ConductorRawGraphqlError {
+    readonly message: string;
+    readonly extensions: Omit<ConductorErrorOptions, "httpStatusCode" | "message">;
+}
 /**
  * The base error from which all other more specific Conductor errors derive.
- * Specifically for errors returned from Conductor's API.
+ * Specifically for errors that Conductor's API returned.
  */
 export declare class ConductorError extends Error {
     /**
@@ -49,7 +56,7 @@ export declare class ConductorError extends Error {
     readonly integrationCode: string | undefined;
     protected constructor(options: ConductorErrorOptions);
 }
-type ConductorErrorOptionsWithoutRawType = Omit<ConductorErrorOptions, "rawType">;
+type ConductorErrorOptionsWithoutType = Omit<ConductorErrorOptions, "type">;
 /**
  * Raised when an error occurs on the third-party integration's end while
  * processing your end-user's request. E.g., cannot connect to QuickBooks
@@ -57,7 +64,7 @@ type ConductorErrorOptionsWithoutRawType = Omit<ConductorErrorOptions, "rawType"
  */
 export declare class ConductorIntegrationError extends ConductorError {
     static readonly rawType: string;
-    constructor(options: ConductorErrorOptionsWithoutRawType);
+    constructor(options: ConductorErrorOptionsWithoutType);
 }
 /**
  * Raised when you make an API call with the wrong parameters, in the wrong
@@ -65,7 +72,7 @@ export declare class ConductorIntegrationError extends ConductorError {
  */
 export declare class ConductorInvalidRequestError extends ConductorError {
     static readonly rawType = "INVALID_REQUEST_ERROR";
-    constructor(options: ConductorErrorOptionsWithoutRawType);
+    constructor(options: ConductorErrorOptionsWithoutType);
 }
 /**
  * Raised when Conductor cannot authenticate you with the credentials you
@@ -73,7 +80,7 @@ export declare class ConductorInvalidRequestError extends ConductorError {
  */
 export declare class ConductorAuthenticationError extends ConductorError {
     static readonly rawType = "AUTHENTICATION_ERROR";
-    constructor(options: ConductorErrorOptionsWithoutRawType);
+    constructor(options: ConductorErrorOptionsWithoutType);
 }
 /**
  * Raised when there is a network problem between the client (on your server)
@@ -81,14 +88,14 @@ export declare class ConductorAuthenticationError extends ConductorError {
  */
 export declare class ConductorConnectionError extends ConductorError {
     static readonly rawType = "CONNECTION_ERROR";
-    constructor(options: ConductorErrorOptionsWithoutRawType);
+    constructor(options: ConductorErrorOptionsWithoutType);
 }
 /**
  * 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);
+    constructor(options: ConductorErrorOptionsWithoutType);
 }
 /**
  * Raised as a fallback for any other error from Conductor that no other error

package/dist/src/errors.js

@@ -5,7 +5,7 @@ exports.generateConductorErrorFromType = exports.ConductorUnknownError = exports
 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.
+ * Specifically for errors that Conductor's API returned.
  */
 class ConductorError extends Error {
     /**
@@ -56,7 +56,7 @@ 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.rawType;
+        this.rawType = options.type;
         this.code = options.code;
         this.endUserMessage = options.endUserMessage ?? exports.DEFAULT_END_USER_MESSAGE;
         this.httpStatusCode = options.httpStatusCode;
@@ -72,7 +72,7 @@ exports.ConductorError = ConductorError;
 class ConductorIntegrationError extends ConductorError {
     static rawType = "INTEGRATION_ERROR";
     constructor(options) {
-        super({ ...options, rawType: ConductorIntegrationError.rawType });
+        super({ ...options, type: ConductorIntegrationError.rawType });
     }
 }
 exports.ConductorIntegrationError = ConductorIntegrationError;
@@ -83,7 +83,7 @@ exports.ConductorIntegrationError = ConductorIntegrationError;
 class ConductorInvalidRequestError extends ConductorError {
     static rawType = "INVALID_REQUEST_ERROR";
     constructor(options) {
-        super({ ...options, rawType: ConductorInvalidRequestError.rawType });
+        super({ ...options, type: ConductorInvalidRequestError.rawType });
     }
 }
 exports.ConductorInvalidRequestError = ConductorInvalidRequestError;
@@ -94,7 +94,7 @@ exports.ConductorInvalidRequestError = ConductorInvalidRequestError;
 class ConductorAuthenticationError extends ConductorError {
     static rawType = "AUTHENTICATION_ERROR";
     constructor(options) {
-        super({ ...options, rawType: ConductorAuthenticationError.rawType });
+        super({ ...options, type: ConductorAuthenticationError.rawType });
     }
 }
 exports.ConductorAuthenticationError = ConductorAuthenticationError;
@@ -105,7 +105,7 @@ exports.ConductorAuthenticationError = ConductorAuthenticationError;
 class ConductorConnectionError extends ConductorError {
     static rawType = "CONNECTION_ERROR";
     constructor(options) {
-        super({ ...options, rawType: ConductorConnectionError.rawType });
+        super({ ...options, type: ConductorConnectionError.rawType });
     }
 }
 exports.ConductorConnectionError = ConductorConnectionError;
@@ -115,7 +115,7 @@ exports.ConductorConnectionError = ConductorConnectionError;
 class ConductorInternalError extends ConductorError {
     static rawType = "INTERNAL_ERROR";
     constructor(options) {
-        super({ ...options, rawType: ConductorInternalError.rawType });
+        super({ ...options, type: ConductorInternalError.rawType });
     }
 }
 exports.ConductorInternalError = ConductorInternalError;
@@ -132,7 +132,7 @@ class ConductorUnknownError extends ConductorError {
 }
 exports.ConductorUnknownError = ConductorUnknownError;
 function generateConductorErrorFromType(options) {
-    switch (options.rawType) {
+    switch (options.type) {
         case ConductorIntegrationError.rawType: {
             return new ConductorIntegrationError(options);
         }

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

@@ -4,4 +4,5 @@ export declare function wrapGraphqlOperations<T extends ReturnType<typeof getSdk
 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 getDurationString(startTime: number): string;
 export declare function wrapError(error: Error): ConductorError;

package/dist/src/graphql/graphqlOperationWrapper.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.wrapError = exports.graphqlOperationWrapper = exports.wrapGraphqlOperations = void 0;
+exports.wrapError = exports.getDurationString = exports.graphqlOperationWrapper = exports.wrapGraphqlOperations = void 0;
 const package_json_1 = __importDefault(require("../../package.json"));
 const errors_1 = require("../errors");
 const graphql_request_1 = require("graphql-request");
@@ -18,7 +18,7 @@ function wrapGraphqlOperations(graphqlOperations, verbose) {
 }
 exports.wrapGraphqlOperations = wrapGraphqlOperations;
 async function graphqlOperationWrapper(operationName, variables, operation, verbose) {
-    const graphqlLog = {
+    const graphqlInfo = {
         operationName,
         input: variables
             ? Object.keys(variables).length === 1 && "input" in variables
@@ -27,7 +27,7 @@ async function graphqlOperationWrapper(operationName, variables, operation, verb
             : {},
     };
     if (verbose) {
-        console.log(`Conductor request start: ${node_util_1.default.inspect(graphqlLog, {
+        console.log(`Conductor request start: ${node_util_1.default.inspect(graphqlInfo, {
             depth: undefined,
         })}`);
     }
@@ -37,7 +37,7 @@ async function graphqlOperationWrapper(operationName, variables, operation, verb
         if (verbose) {
             const responseLog = {
                 duration: getDurationString(startTime),
-                ...graphqlLog,
+                ...graphqlInfo,
             };
             const responseString = node_util_1.default.inspect(responseLog, { depth: undefined });
             console.log(`Conductor request complete: ${responseString}`);
@@ -50,7 +50,7 @@ async function graphqlOperationWrapper(operationName, variables, operation, verb
             const errorLog = {
                 duration: getDurationString(startTime),
                 error: String(conductorError),
-                ...graphqlLog,
+                ...graphqlInfo,
             };
             const errorString = node_util_1.default.inspect(errorLog, { depth: undefined });
             console.log(`Conductor error: ${errorString}`);
@@ -63,6 +63,7 @@ function getDurationString(startTime) {
     const duration = Date.now() - startTime;
     return `${Math.round(duration / 10) / 100}s`;
 }
+exports.getDurationString = getDurationString;
 function wrapError(error) {
     if (error instanceof graphql_request_1.ClientError) {
         const { response } = error;
@@ -83,12 +84,19 @@ function wrapError(error) {
                     httpStatusCode: response.status,
                 });
             }
+            // Do *not* bother validating if this error is a Conductor error:
+            // 1. We know this is a `ClientError`, so `message` and `httpStatusCode`
+            //    exist.
+            // 2. We know this is a GraphQL error, so `code` likely exists either from
+            //    Conductor or Apollo.
+            // 3. If `type` is absent, then `generateConductorErrorFromType` will
+            //    default to `ConductorUnknownError`.
+            // 4. If `endUserMessage` is absent, then `ConductorError` will use a
+            //    default value.
             return (0, errors_1.generateConductorErrorFromType)({
-                rawType: errorExtensions["type"],
-                code: errorExtensions["code"],
                 message: nestedError.message,
-                endUserMessage: errorExtensions["endUserMessage"],
                 httpStatusCode: response.status,
+                ...errorExtensions,
             });
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conductor-node",
-  "version": "8.5.3",
+  "version": "8.6.0",
   "description": "Easily integrate with the entire QuickBooks Desktop API with fully-typed async TypeScript",
   "author": "Danny Nemer <hi@DannyNemer.com>",
   "license": "MIT",
@@ -24,13 +24,13 @@
   },
   "dependencies": {
     "graphql": "^16.6.0",
-    "graphql-request": "^5.0.0"
+    "graphql-request": "~5.1.0"
   },
   "devDependencies": {
-    "@graphql-codegen/add": "^3.2.1",
-    "@graphql-codegen/cli": "^2.13.11",
+    "@graphql-codegen/add": "^4.0.1",
+    "@graphql-codegen/cli": "^3.2.1",
     "@graphql-codegen/typescript-graphql-request": "^4.5.8",
-    "@graphql-codegen/typescript-operations": "^2.5.6",
+    "@graphql-codegen/typescript-operations": "^3.0.1",
     "tsc-alias": "^1.7.0"
   },
   "keywords": [