conductor-node 8.6.2 → 8.6.4

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,27 +158,18 @@ const accountAddInput: QbdTypes.AccountAdd = {
 
 ## Error Handling
 
-The `ConductorError` and its subclasses have the following properties:
+Any and every error thrown by the Conductor API will be an instance of `ConductorError` or one of its subclasses, which all have the following properties:
 
-```ts
-{
-  // The error type.
-  type: string;
-  // The unique error code. This is useful for adding special handling
-  // for specific errors.
-  code: string;
-  // The developer error message for your logs.
-  message: string;
-  // The end-user-friendly error message to display in your app.
-  endUserMessage: string;
-  // 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;
-}
-```
+| Property          | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`            | `string` | The error type, which categorizes the error. See [Error Types](#error-types) below.<br><br>This value is the same as the subclass name. E.g., `"ConductorIntegrationError"` or `"ConductorInvalidRequestError"`.                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `code`            | `string` | The unique error code from Conductor, which is useful for adding special handling for specific errors. E.g., `"INTEGRATION_CONNECTION_MISSING"`, `"API_KEY_INVALID"`, or `"QBD_REQUEST_ERROR"`.<br><br>By comparison, `type` is more general and categorizes the error.                                                                                                                                                                                                                                                                                                                                                   |
+| `message`         | `string` | The developer-friendly error message for your logs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `endUserMessage`  | `string` | The end-user-friendly error message to display in your app's UI for your end-user to see.<br><br>This value exists for _every_ error. E.g., if it's a QBD connection error, it might recommend the end-user to check that their QuickBooks Desktop is open and that they're logged in. But if a Conductor API key is expired, this message will just say "An internal server error occurred. Please try again later.".                                                                                                                                                                                                    |
+| `integrationCode` | `string` | The unique error code supplied by the third-party integration for errors that come from the integration (i.e., instances of `ConductorIntegrationError`). This is useful for adding special handling for specific errors from the third-party integration.<br><br>E.g., QuickBooks Desktop might return an error with `integrationCode` for something specific to its accounting logic. The integration's corresponding message for this code would be in `error.message`.<br><br>The third-party integration's error codes are not standardized, so you should not rely on this code to be the same across integrations. |
+| `httpStatusCode`  | `number` | The HTTP status code of the response that included the error. You probably won't need this.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+
+_Would any additional error properties be helpful?_ Let me know. Some potential additions: `request` for the original API request, `integrationKey` (e.g., `"quickbooks-desktop"`), or `integrationConnectionId`.
 
 ### Error Types
 
@@ -194,7 +185,7 @@ The error object you receive will have one of the following error types:
 
 ### Special Handling
 
-If you need special handling for specific errors, you can wrap individual API calls as shown below.
+If you need special handling for specific errors, you can wrap individual API calls, as shown below.
 
 In the form of a rejected promise:
 
@@ -237,14 +228,14 @@ try {
 
 ### Global Error Handling
 
-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:
+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:
-   - 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.
+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 can do this with Express:
+For example, using an Express error handler:
 
 ```ts
 import * as Sentry from "@sentry/node";
@@ -263,7 +254,7 @@ app.use((error, req, res, next) => {
 });
 ```
 
-And here is how you can do this with Apollo Server:
+Or using Apollo Server's error handler:
 
 ```ts
 import { ApolloServer } from "@apollo/server";

package/dist/package.json

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

@@ -20,40 +20,58 @@ export interface ConductorRawGraphqlError {
  */
 export declare class ConductorError extends Error {
     /**
-     * The error type.
+     * The error type, which categorizes the error.
+     *
+     * This value is the same as the subclass name. E.g.,
+     * `"ConductorIntegrationError"` or `"ConductorInvalidRequestError"`.
      */
     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.
+     * The unique error code from Conductor, which is useful for adding special
+     * handling for specific errors. E.g., `"INTEGRATION_CONNECTION_MISSING"`,
+     * `"API_KEY_INVALID"`, or `"QBD_REQUEST_ERROR"`.
+     *
+     * By comparison, `type` is more general and categorizes the error.
      */
     readonly code: string;
     /**
      * The developer-friendly error message for your logs.
-     *
-     * (Defined in the base class but documented here for completeness.)
      */
+    readonly message: string;
     /**
-     * The end-user-friendly error message to display in your app.
+     * The end-user-friendly error message to display in your app's UI for your
+     * end-user to see.
+     *
+     * This value exists for *every* error. E.g., if it's a QBD connection error,
+     * it might recommend the end-user to check that their QuickBooks Desktop is
+     * open and that they're logged in. But if a Conductor API key is expired,
+     * this message will just say "An internal server error occurred. Please try
+     * again later.".
      */
     readonly endUserMessage: string;
     /**
-     * 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 unique error code supplied by the third-party integration for errors
+     * that come from the integration (i.e., instances of
+     * `ConductorIntegrationError`). This is useful for adding special handling
+     * for specific errors from the third-party integration.
+     *
+     * E.g., QuickBooks Desktop might return an error with `integrationCode` for
+     * something specific to its accounting logic. The integration's corresponding
+     * message for this code would be in `error.message`.
      *
      * 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;
     /**
-     * The HTTP status code of the response that included the error.
+     * The HTTP status code of the response that included the error. You probably
+     * won't need this.
      */
     readonly httpStatusCode: number | undefined;
+    /**
+     * The internal representation of `type` for debugging.
+     */
+    protected readonly rawType: string;
     protected constructor(options: ConductorErrorOptions);
 }
 type ConductorErrorOptionsWithoutType = Omit<ConductorErrorOptions, "type">;

package/dist/src/errors.js

@@ -9,41 +9,58 @@ exports.DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please tr
  */
 class ConductorError extends Error {
     /**
-     * The error type.
+     * The error type, which categorizes the error.
+     *
+     * This value is the same as the subclass name. E.g.,
+     * `"ConductorIntegrationError"` or `"ConductorInvalidRequestError"`.
      */
     type;
     /**
-     * The raw error type for internal debugging.
-     */
-    rawType;
-    /**
-     * The unique error code. This is useful for adding special handling
-     * for specific errors.
+     * The unique error code from Conductor, which is useful for adding special
+     * handling for specific errors. E.g., `"INTEGRATION_CONNECTION_MISSING"`,
+     * `"API_KEY_INVALID"`, or `"QBD_REQUEST_ERROR"`.
+     *
+     * By comparison, `type` is more general and categorizes the error.
      */
     code;
     /**
      * The developer-friendly error message for your logs.
-     *
-     * (Defined in the base class but documented here for completeness.)
      */
-    // public readonly message: string;
+    message;
     /**
-     * The end-user-friendly error message to display in your app.
+     * The end-user-friendly error message to display in your app's UI for your
+     * end-user to see.
+     *
+     * This value exists for *every* error. E.g., if it's a QBD connection error,
+     * it might recommend the end-user to check that their QuickBooks Desktop is
+     * open and that they're logged in. But if a Conductor API key is expired,
+     * this message will just say "An internal server error occurred. Please try
+     * again later.".
      */
     endUserMessage;
     /**
-     * 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 unique error code supplied by the third-party integration for errors
+     * that come from the integration (i.e., instances of
+     * `ConductorIntegrationError`). This is useful for adding special handling
+     * for specific errors from the third-party integration.
+     *
+     * E.g., QuickBooks Desktop might return an error with `integrationCode` for
+     * something specific to its accounting logic. The integration's corresponding
+     * message for this code would be in `error.message`.
      *
      * 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;
     /**
-     * The HTTP status code of the response that included the error.
+     * The HTTP status code of the response that included the error. You probably
+     * won't need this.
      */
     httpStatusCode;
+    /**
+     * The internal representation of `type` for debugging.
+     */
+    rawType;
     constructor(options) {
         super(options.message);
         // Set `name` to the constructor name so that the error appears in logs as
@@ -58,6 +75,7 @@ class ConductorError extends Error {
         this.type = this.constructor.name;
         this.rawType = options.type;
         this.code = options.code;
+        this.message = options.message;
         this.endUserMessage = options.endUserMessage ?? exports.DEFAULT_END_USER_MESSAGE;
         this.integrationCode = options.integrationCode;
         this.httpStatusCode = options.httpStatusCode;

package/package.json

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