conductor-node 8.6.1 → 8.6.3

package/README.md

@@ -48,7 +48,7 @@ const newAccount = await conductor.qbd.account.add(qbdConnections[0].id, {
 
 ### `createIntegrationConnection(input: CreateIntegrationConnectionInput)`
 
-Create a new integration-connection.
+Creates a new integration-connection.
 
 ```ts
 const newQbdConnection = await conductor.createIntegrationConnection({
@@ -82,7 +82,7 @@ The response looks like the following:
 
 ### `qbd.*`
 
-Execute any QuickBooks Desktop (QBD) API against a specific integration-connection id. See the official [QuickBooks Desktop API Reference](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop) for a full list of available APIs.
+Executes any QuickBooks Desktop (QBD) API against a specific integration-connection id. See the official [QuickBooks Desktop API Reference](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop) for a complete list of available APIs.
 
 ```ts
 const newAccount = await conductor.qbd.account.add(qbdConnectionId, {
@@ -94,7 +94,7 @@ const newAccount = await conductor.qbd.account.add(qbdConnectionId, {
 
 ### `getIntegrationConnections()`
 
-Fetch all authorized integration-connections.
+Fetches all authorized integration-connections.
 
 ```ts
 const qbdConnections = await conductor.getIntegrationConnections();
@@ -102,7 +102,7 @@ const qbdConnections = await conductor.getIntegrationConnections();
 
 ### `getIntegrationConnectionById(id: string)`
 
-Fetch a single integration-connection by id.
+Fetches a single integration-connection by id.
 
 ```ts
 const qbdConnection = await conductor.getIntegrationConnectionById(
@@ -112,9 +112,9 @@ const qbdConnection = await conductor.getIntegrationConnectionById(
 
 ### `pingIntegrationConnection(id: string)`
 
-Check whether the specified integration-connection can connect and process requests end-to-end.
+Checks whether the specified integration-connection can connect and process requests end-to-end.
 
-If the connection fails, the error we encountered will be thrown as a [`ConductorError`](#error-handling). This information is useful for showing a "connection status" indicator in your app.
+If the connection fails, the error we encountered will be thrown as a [`ConductorError`](#error-handling). This information is useful for showing a "connection status" indicator in your app. If an error occurs, we recommend displaying the property `error.endUserMessage` to your end-user in your app's UI.
 
 In the form of a rejected promise:
 
@@ -142,7 +142,7 @@ try {
 
 ## TypeScript
 
-Access the full QuickBooks Desktop API through TypeScript. The `qbd.*` APIs are fully typed with inline documentation and will autocomplete in your editor.
+Access the entire QuickBooks Desktop API through TypeScript. The `qbd.*` APIs are fully typed with inline documentation and will autocomplete in your editor.
 
 To manually access the QBD types, import them from `conductor-node` like so:
 
@@ -158,7 +158,7 @@ const accountAddInput: QbdTypes.AccountAdd = {
 
 ## Error Handling
 
-The `ConductorError` and its subclasses have the following properties:
+Any error thrown by the Conductor API will be an instance of `ConductorError` or one of its subclasses, which all have the following properties:
 
 ```ts
 {
@@ -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, we recommend your server use a single global error handler, such as [`app.use((error, ...) => { ... })` 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 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.
+1. Ensure your app's UI shows your end-user the property `error.endUserMessage` for any `ConductorError` instance for any Conductor request while you log the rest of the error object.
+2. Send the entire error object to your error-tracking service (e.g., Sentry) for all `ConductorError` instances:
+   - Send a **warning** 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, using an Express error handler:
 
 ```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:
+Or using Apollo Server's error handler:
 
 ```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.3",
     "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/Client.d.ts

@@ -2,7 +2,7 @@ import type { GraphqlCreateIntegrationConnectionInput, GraphqlCreateIntegrationC
 import QbdIntegration from "./integrations/qbd/QbdIntegration";
 import { getServerUrlForEnvironment } from "./utils";
 export interface ClientOptions {
-    /** Log each request and response. */
+    /** Logs each request and response. */
     readonly verbose?: boolean;
     readonly serverEnvironment?: Parameters<typeof getServerUrlForEnvironment>[0];
 }
@@ -13,20 +13,20 @@ export default class Client {
     private readonly graphqlOperations;
     constructor(apiKey: string, { verbose, serverEnvironment }?: ClientOptions);
     /**
-     * Fetch the specified integration-connection.
+     * Fetches the specified integration-connection.
      *
      * @param integrationConnectionId The integration-connection ID.
      * @returns The integration-connection.
      */
     getIntegrationConnection(integrationConnectionId: GraphqlGetIntegrationConnectionQueryVariables["integrationConnectionId"]): Promise<GraphqlGetIntegrationConnectionQuery["integrationConnection"]>;
     /**
-     * Fetch all integration-connections associated with your Conductor account.
+     * Fetches all integration-connections associated with your Conductor account.
      *
      * @returns The integration-connections.
      */
     getIntegrationConnections(): Promise<GraphqlGetIntegrationConnectionsQuery["integrationConnections"]>;
     /**
-     * Check whether we can successfully connect to the end-user's QBD instance.
+     * Checks whether we can successfully connect to the end-user's QBD instance.
      *
      * Unlike `lastHeartbeatAt`, which only checks if QBWC is running (i.e., is
      * the user's computer on), this check fails if the user's computer is on but
@@ -35,8 +35,8 @@ export default class Client {
      *
      * @param integrationConnectionId The ID of the integration-connection.
      * @returns The result object with the following properties:
-     * - isConnected - Whether we can connect to the end-user's QBD.
-     * - error - If `isConnected=false`, this will be an object with the following
+     * - isConnected: Whether we can connect to the end-user's QBD.
+     * - error: If `isConnected=false`, this will be an object with the following
      *   properties:
      *   - error.code - The unique error code.
      *   - error.developerMessage - The technical error message for the developer.
@@ -45,7 +45,7 @@ export default class Client {
      */
     getConnectionStatus(integrationConnectionId: GraphqlGetConnectionStatusQueryVariables["integrationConnectionId"]): Promise<GraphqlGetConnectionStatusQuery["integrationConnection"]["connectionStatus"]>;
     /**
-     * Create a new integration-connection.
+     * Creates a new integration-connection.
      *
      * @param input - The input object to create the integration-connection.
      * @param input.integrationKey The identifier of the third-party platform to
@@ -63,12 +63,13 @@ export default class Client {
         integrationKey: "quickbooks-desktop";
     }): Promise<GraphqlCreateIntegrationConnectionMutation["createIntegrationConnection"]["integrationConnection"]>;
     /**
-     * Check whether the specified integration-connection can connect and process
+     * Checks whether the specified integration-connection can connect and process
      * requests end-to-end.
      *
      * If the connection fails, the error we encountered will be thrown as a
      * `ConductorError`. This information is useful for showing a "connection
-     * status" indicator in your app.
+     * status" indicator in your app. If an error occurs, we recommend displaying
+     * the property `error.endUserMessage` to your end-user in your app's UI.
      */
     pingIntegrationConnection(integrationConnectionId: GraphqlPingIntegrationConnectionMutationVariables["input"]["integrationConnectionId"]): Promise<GraphqlPingIntegrationConnectionMutation["pingIntegrationConnection"]>;
     private createHeaders;

package/dist/src/Client.js

@@ -21,7 +21,7 @@ class Client {
         this.qbd = new QbdIntegration_1.default(this.graphqlOperations);
     }
     /**
-     * Fetch the specified integration-connection.
+     * Fetches the specified integration-connection.
      *
      * @param integrationConnectionId The integration-connection ID.
      * @returns The integration-connection.
@@ -32,7 +32,7 @@ class Client {
             .then((result) => result.integrationConnection);
     }
     /**
-     * Fetch all integration-connections associated with your Conductor account.
+     * Fetches all integration-connections associated with your Conductor account.
      *
      * @returns The integration-connections.
      */
@@ -42,7 +42,7 @@ class Client {
             .then((result) => result.integrationConnections);
     }
     /**
-     * Check whether we can successfully connect to the end-user's QBD instance.
+     * Checks whether we can successfully connect to the end-user's QBD instance.
      *
      * Unlike `lastHeartbeatAt`, which only checks if QBWC is running (i.e., is
      * the user's computer on), this check fails if the user's computer is on but
@@ -51,8 +51,8 @@ class Client {
      *
      * @param integrationConnectionId The ID of the integration-connection.
      * @returns The result object with the following properties:
-     * - isConnected - Whether we can connect to the end-user's QBD.
-     * - error - If `isConnected=false`, this will be an object with the following
+     * - isConnected: Whether we can connect to the end-user's QBD.
+     * - error: If `isConnected=false`, this will be an object with the following
      *   properties:
      *   - error.code - The unique error code.
      *   - error.developerMessage - The technical error message for the developer.
@@ -65,7 +65,7 @@ class Client {
             .then((result) => result.integrationConnection.connectionStatus);
     }
     /**
-     * Create a new integration-connection.
+     * Creates a new integration-connection.
      *
      * @param input - The input object to create the integration-connection.
      * @param input.integrationKey The identifier of the third-party platform to
@@ -85,12 +85,13 @@ class Client {
             .then((result) => result.createIntegrationConnection.integrationConnection);
     }
     /**
-     * Check whether the specified integration-connection can connect and process
+     * Checks whether the specified integration-connection can connect and process
      * requests end-to-end.
      *
      * If the connection fails, the error we encountered will be thrown as a
      * `ConductorError`. This information is useful for showing a "connection
-     * status" indicator in your app.
+     * status" indicator in your app. If an error occurs, we recommend displaying
+     * the property `error.endUserMessage` to your end-user in your app's UI.
      */
     async pingIntegrationConnection(integrationConnectionId) {
         return this.graphqlOperations

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.3",
   "description": "Easily integrate with the entire QuickBooks Desktop API with fully-typed async TypeScript",
   "author": "Danny Nemer <hi@DannyNemer.com>",
   "license": "MIT",