conductor-node 8.6.1 → 8.6.2

package/README.md

@@ -171,12 +171,12 @@ The `ConductorError` and its subclasses have the following properties:
   message: string;
   // The end-user-friendly error message to display in your app.
   endUserMessage: string;
-  // 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;
+  // The HTTP status code of the response that included the error.
+  httpStatusCode: number | undefined;
 }
 ```
 
@@ -192,7 +192,9 @@ 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.)                                                                                                               |
 
-### Example
+### Special Handling
+
+If you need special handling for specific errors, you can wrap individual API calls as shown below.
 
 In the form of a rejected promise:
 
@@ -208,7 +210,7 @@ conductor.qbd.account
   })
   .catch((error) => {
     if (error instanceof ConductorError) {
-      // Update your app's UI to display `error.endUserMessage`.
+      // Check `error.code`, `error.integrationCode`, etc., for special handling.
     } else {
       // ...
     }
@@ -226,27 +228,28 @@ try {
   });
 } catch (error) {
   if (error instanceof ConductorError) {
-    // Update your app's UI to display `error.endUserMessage`.
+    // Check `error.code`, `error.integrationCode`, etc., for special handling.
   } else {
     // ...
   }
 }
 ```
 
-### 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`.
+### Global Error Handling
 
-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:
+We do not expect you to individually wrap every API call like the examples above. Instead, 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), where 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.
+   - 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.
+   - Send an **error** for all other `ConductorError` instances; e.g., invalid API key.
 
-For example, here is how you might do this in Express:
+For example, here is how you can do this with Express:
 
 ```ts
+import * as Sentry from "@sentry/node";
+import { ConductorError, ConductorIntegrationError } from "conductor-node";
+// ...
 app.use((error, req, res, next) => {
   if (error instanceof ConductorError) {
     Sentry.captureException(error, {
@@ -260,14 +263,16 @@ app.use((error, req, res, next) => {
 });
 ```
 
-And here is how you might do this in Apollo Server:
+And here is how you can do this with Apollo Server:
 
 ```ts
+import { ApolloServer } from "@apollo/server";
 import { unwrapResolverError } from "@apollo/server/errors";
-
+import * as Sentry from "@sentry/node";
+import { ConductorError, ConductorIntegrationError } from "conductor-node";
+// ...
 const server = new ApolloServer({
-  typeDefs,
-  resolvers,
+  // ...
   formatError: (formattedError, error) => {
     const origError = unwrapResolverError(error);
     if (origError instanceof ConductorError) {
@@ -275,17 +280,14 @@ const server = new ApolloServer({
         level:
           origError instanceof ConductorIntegrationError ? "warning" : "error",
       });
-      // Return a different error message for your end-user to see in your app's UI.
       return {
         ...formattedError,
+        // Return a different error message for your end-user to see in
+        // your app's UI.
         message: origError.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.6.1",
+    "version": "8.6.2",
     "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

@@ -4,8 +4,8 @@ export interface ConductorErrorOptions {
     readonly code: string;
     readonly message: string;
     readonly endUserMessage?: string;
-    readonly httpStatusCode?: number;
     readonly integrationCode?: string;
+    readonly httpStatusCode?: number;
 }
 /**
  * The raw GraphQL error that Conductor's API returns.
@@ -41,10 +41,6 @@ export declare class ConductorError extends Error {
      * 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
@@ -54,6 +50,10 @@ export declare class ConductorError extends Error {
      * should not rely on this code to be the same across integrations.
      */
     readonly integrationCode: string | undefined;
+    /**
+     * The HTTP status code of the response that included the error.
+     */
+    readonly httpStatusCode: number | undefined;
     protected constructor(options: ConductorErrorOptions);
 }
 type ConductorErrorOptionsWithoutType = Omit<ConductorErrorOptions, "type">;

package/dist/src/errors.js

@@ -31,10 +31,6 @@ class ConductorError extends Error {
      * 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
@@ -44,6 +40,10 @@ class ConductorError extends Error {
      * should not rely on this code to be the same across integrations.
      */
     integrationCode;
+    /**
+     * The HTTP status code of the response that included the error.
+     */
+    httpStatusCode;
     constructor(options) {
         super(options.message);
         // Set `name` to the constructor name so that the error appears in logs as
@@ -59,8 +59,8 @@ class ConductorError extends Error {
         this.rawType = options.type;
         this.code = options.code;
         this.endUserMessage = options.endUserMessage ?? exports.DEFAULT_END_USER_MESSAGE;
-        this.httpStatusCode = options.httpStatusCode;
         this.integrationCode = options.integrationCode;
+        this.httpStatusCode = options.httpStatusCode;
     }
 }
 exports.ConductorError = ConductorError;

package/package.json

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