conductor-node 9.1.0 → 9.1.2

package/README.md

@@ -160,14 +160,14 @@ const accountAddInput: QbdTypes.AccountAdd = {
 
 ### `ConductorError`
 
-Any error ever thrown by the Conductor API will be an instance of `ConductorError` or one of its subclasses, which all have the following properties:
+All errors thrown by the Conductor API are instances of `ConductorError` or its subclasses. These errors have the following properties:
 
 | 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.                                                                                                                                                                                                                                                                                                |
+| `type`            | `string`                | 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>In contrast, `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, e.g., this message will just say "An internal server error occurred. Please try again later.".                                                                                                                                           |
+| `endUserMessage`  | `string`                | The end-user-friendly error message to display in your app's UI to your end-users.<br><br>This value exists for _every_ error. E.g., for 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, e.g., this message will just say "An internal server error occurred. Please try again later.".                                                                                                                                                      |
 | `integrationCode` | `string` or `undefined` | The unique error code supplied by the third-party integration for errors returned by the integration (i.e., `ConductorIntegrationError`) or integration connector (i.e., `ConductorIntegrationConnectorError`). This is useful for adding special handling for specific errors from the third-party integration or connector.<br><br>The integration's corresponding error message for this code is in `error.message`.<br><br>The third-party integrations' error codes are not standardized, so you should not rely on this code to be the same across integrations. |
 | `httpStatusCode`  | `number` or `undefined` | The HTTP status code of the response that included the error. You probably won't need this.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
@@ -175,14 +175,14 @@ Any error ever thrown by the Conductor API will be an instance of `ConductorErro
 
 The error object you receive will have one of the following error types:
 
-| Type                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ConductorIntegrationError`           | Raised when the third-party integration returned an error while processing your end-user's request. Most likely, something is wrong with your request or data handling that you must fix.<br><br>E.g., a `ListID` you provided was not found in QuickBooks Desktop, or an accounting value you provided failed the integration's accounting rules.<br><br>See `error.integrationCode` (above) for the error code that the integration returned, if any.                                                                                                                                                                                         |
-| `ConductorIntegrationConnectionError` | Raised when an error occurred connecting to the third-party integration on behalf of the end-user. Most likely, something is wrong with the end-user's connection or configuration that _the end-user must fix_, not you. <br><br>E.g., QuickBooks Web Connector (QBWC) failed to connect to QuickBooks Desktop on the end-user's computer.<br><br>See `error.integrationCode` (above) for the error code that the integration connector returned, if any.<br><br>❗ We recommend _not_ alerting your team for these errors because only the end-user can fix them. See [Global Error Handling](#global-error-handling) for an example of this. |
-| `ConductorInvalidRequestError`        | Raised when you make an API call with the wrong parameters, in the wrong state, or in an invalid way.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `ConductorAuthenticationError`        | Raised when Conductor cannot authenticate you with the credentials you provided. E.g., an incorrect API key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `ConductorConnectionError`            | Raised when there was a network problem between the client (on your server) and Conductor's servers. E.g., a downed network or a bad TLS certificate.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `ConductorInternalError`              | Raised when something went wrong on Conductor's end. (These are rare.)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Type                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ConductorIntegrationError`           | Raised when the third-party integration encounters an error while processing the end-user's request. This often results from an issue with the request or data handling that requires your attention to resolve.<br><br>E.g., a `ListID` you provided was not found in QuickBooks Desktop, or an accounting value you supplied did not adhere to the integration's accounting rules.<br><br>Refer to `error.integrationCode` for the error code returned by the integration, if available.                                                                                                                                                                                                                         |
+| `ConductorIntegrationConnectionError` | Raised when a connection error occurs with the third-party integration on the end-user's side. This typically indicates an issue with the end-user's integration connection or configuration, which they must resolve. In other words, you cannot take action to fix these errors.<br><br>E.g., QuickBooks Web Connector (QBWC) failed to connect to QuickBooks Desktop on the end-user's computer.<br><br>Refer to `error.integrationCode` for the error code returned by the integration connector, if available.<br><br>❗ We recommend _not_ alerting your team for these errors because only the end-user can fix them. See [Centralized Error Handling](#centralized-error-handling) for an example of this. |
+| `ConductorInvalidRequestError`        | Raised when you make an API call with the wrong parameters, in the wrong state, or in an invalid way.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `ConductorAuthenticationError`        | Raised when Conductor cannot authenticate you with the credentials you provided. E.g., an incorrect API key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `ConductorConnectionError`            | Raised when there was a network problem between the client (on your server) and Conductor's servers. E.g., a downed network or a bad TLS certificate.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `ConductorInternalError`              | Raised when something went wrong on Conductor's end. (These are rare.)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 
 ### Specific Error Handling
 
@@ -227,14 +227,14 @@ conductor.qbd.account
   });
 ```
 
-### Global Error Handling
+### Centralized Error Handling
 
-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:
+It is unnecessary to wrap each API call individually, as demonstrated in the examples above. Instead, we suggest implementing a centralized error handler for your server, 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). Within this handler, perform the following actions:
 
-1. Ensure your app's UI shows your end-user the property `error.endUserMessage` for any `ConductorError` instance 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 `ConductorIntegrationConnectionError`, which only the end-user can fix; e.g., failed to connect to QuickBooks Desktop on your end-user's computer.
-   - Send an **error** for all other `ConductorError` instances; e.g., invalid API key.
+1. For any `ConductorError` instance, display the `error.endUserMessage` property to the end-user in your app's UI while logging the complete error object.
+2. For all `ConductorError` instances, transmit the full error object to your error-tracking service (e.g., Sentry):
+   - Send a **warning** for instances of `ConductorIntegrationConnectionError`, which are not actionable by you and can only be resolved by the end-user; for example, failure to connect to QuickBooks Desktop on the end-user's computer.
+   - Send an **error** for all other `ConductorError` instances, such as an invalid API key.
 
 For example, using an Express error handler:
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "conductor-node",
-    "version": "9.1.0",
+    "version": "9.1.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/Client.d.ts

@@ -1,6 +1,6 @@
 import type { GraphqlCreateIntegrationConnectionInput, GraphqlCreateIntegrationConnectionMutation, GraphqlGetIntegrationConnectionQuery, GraphqlGetIntegrationConnectionQueryVariables, GraphqlGetIntegrationConnectionsQuery, GraphqlPingIntegrationConnectionMutation, GraphqlPingIntegrationConnectionMutationVariables } from "./graphql/__generated__/operationTypes";
 import QbdIntegration from "./integrations/qbd/QbdIntegration";
-import { getServerUrlForEnvironment } from "./utils";
+import { getServerUrlForEnvironment } from "./utils/misc";
 export interface ClientOptions {
     /** Logs each request and response. */
     readonly verbose?: boolean;

package/dist/src/Client.js

@@ -7,7 +7,7 @@ const package_json_1 = __importDefault(require("./../package.json"));
 const graphqlOperationWrapper_1 = require("./graphql/graphqlOperationWrapper");
 const operationTypes_1 = require("./graphql/__generated__/operationTypes");
 const QbdIntegration_1 = __importDefault(require("./integrations/qbd/QbdIntegration"));
-const utils_1 = require("./utils");
+const misc_1 = require("./utils/misc");
 const graphql_request_1 = require("graphql-request");
 class Client {
     /** QuickBooks Desktop integration. */
@@ -15,8 +15,8 @@ class Client {
     graphqlClient;
     graphqlOperations;
     constructor(apiKey, { verbose = false, serverEnvironment = "production" } = {}) {
-        (0, utils_1.checkForUpdates)();
-        this.graphqlClient = new graphql_request_1.GraphQLClient(`${(0, utils_1.getServerUrlForEnvironment)(serverEnvironment)}/graphql`, { headers: this.createHeaders(apiKey) });
+        (0, misc_1.checkForUpdates)();
+        this.graphqlClient = new graphql_request_1.GraphQLClient(`${(0, misc_1.getServerUrlForEnvironment)(serverEnvironment)}/graphql`, { headers: this.createHeaders(apiKey) });
         this.graphqlOperations = (0, graphqlOperationWrapper_1.wrapGraphqlOperations)((0, operationTypes_1.getSdk)(this.graphqlClient), verbose);
         this.qbd = new QbdIntegration_1.default(this.graphqlOperations);
     }

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

@@ -1,5 +1,5 @@
-import type { ConductorError } from "../error";
 import type { getSdk } from "../graphql/__generated__/operationTypes";
+import type { ConductorError } from "../utils/error";
 export declare function wrapGraphqlOperations<T extends ReturnType<typeof getSdk>>(graphqlOperations: T, verbose: boolean): T;
 export declare function graphqlOperationWrapper<V extends {
     [key: string]: unknown;

package/dist/src/graphql/graphqlOperationWrapper.js

@@ -5,7 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.wrapError = exports.getDurationString = exports.graphqlOperationWrapper = exports.wrapGraphqlOperations = void 0;
 const package_json_1 = __importDefault(require("../../package.json"));
-const error_1 = require("../error");
+const error_1 = require("../utils/error");
 const graphql_request_1 = require("graphql-request");
 const node_util_1 = __importDefault(require("node:util"));
 function wrapGraphqlOperations(graphqlOperations, verbose) {

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 import Client from "./Client";
 export default Client;
 export { type ClientOptions } from "./Client";
-export * from "./error";
 export * as QbdTypes from "./integrations/qbd/qbdTypes";
+export * from "./utils/error";

package/dist/src/index.js

@@ -15,9 +15,6 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
 var __importStar = (this && this.__importStar) || function (mod) {
     if (mod && mod.__esModule) return mod;
     var result = {};
@@ -25,6 +22,9 @@ var __importStar = (this && this.__importStar) || function (mod) {
     __setModuleDefault(result, mod);
     return result;
 };
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -34,5 +34,5 @@ exports.QbdTypes = void 0;
 const Client_1 = __importDefault(require("./Client"));
 // eslint-disable-next-line unicorn/prefer-export-from -- We need `Client` to be the default export, which is impossible to define with `export from`.
 exports.default = Client_1.default;
-__exportStar(require("./error"), exports);
 exports.QbdTypes = __importStar(require("./integrations/qbd/qbdTypes"));
+__exportStar(require("./utils/error"), exports);

package/dist/src/integrations/qbd/QbdIntegration.js

@@ -3,8 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const error_1 = require("../../error");
 const BaseIntegration_1 = __importDefault(require("../../integrations/BaseIntegration"));
+const error_1 = require("../../utils/error");
 class QbdIntegration extends BaseIntegration_1.default {
     account = {
         /**

package/dist/src/{error.d.ts → utils/error.d.ts}

@@ -20,7 +20,7 @@ export interface ConductorGraphqlError {
  */
 export declare class ConductorError extends Error {
     /**
-     * The error type, which categorizes the error.
+     * Categorizes the error.
      *
      * This value is the same as the subclass name. E.g.,
      * `"ConductorIntegrationError"` or `"ConductorInvalidRequestError"`.
@@ -31,7 +31,7 @@ export declare class ConductorError extends Error {
      * 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.
+     * In contrast, `type` is more general and categorizes the error.
      */
     readonly code: string;
     /**
@@ -39,14 +39,14 @@ export declare class ConductorError extends Error {
      */
     readonly message: string;
     /**
-     * The end-user-friendly error message to display in your app's UI for your
-     * end-user to see.
+     * The end-user-friendly error message to display in your app's UI to your
+     * end-users.
      *
-     * 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,
-     * e.g., this message will just say "An internal server error occurred. Please
-     * try again later.".
+     * This value exists for *every* error. E.g., for 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, e.g.,
+     * this message will just say "An internal server error occurred. Please try
+     * again later.".
      */
     readonly endUserMessage: string;
     /**
@@ -76,30 +76,32 @@ export declare class ConductorError extends Error {
 }
 type ConductorErrorOptionsWithoutType = Omit<ConductorErrorOptions, "type">;
 /**
- * Raised when the third-party integration returned an error while processing
- * your end-user's request. Most likely, something is wrong with your request or
- * data handling that you must fix.
+ * Raised when the third-party integration encounters an error while processing
+ * the end-user's request. This often results from an issue with the request or
+ * data handling that requires your attention to resolve.
  *
  * E.g., a `ListID` you provided was not found in QuickBooks Desktop, or an
- * accounting value you provided failed the integration's accounting rules.
+ * accounting value you supplied did not adhere to the integration's accounting
+ * rules.
  *
- * See `error.integrationCode` for the error code that the integration returned,
- * if any.
+ * Refer to `error.integrationCode` for the error code returned by the
+ * integration, if available.
  */
 export declare class ConductorIntegrationError extends ConductorError {
     static readonly rawType = "INTEGRATION_ERROR";
     constructor(options: ConductorErrorOptionsWithoutType);
 }
 /**
- * Raised when an error occurred connecting to the third-party integration on
- * behalf of the end-user. Most likely, something is wrong with the end-user's
- * connection or configuration that the end-user must fix, not you.
+ * Raised when a connection error occurs with the third-party integration on the
+ * end-user's side. This typically indicates an issue with the end-user's
+ * integration connection or configuration, which they must resolve. In other
+ * words, you cannot take action to fix these errors.
  *
  * E.g., QuickBooks Web Connector (QBWC) failed to connect to QuickBooks Desktop
  * on the end-user's computer.
  *
- * See `error.integrationCode` for the error code that the integration connector
- * returned, if any.
+ * Refer to `error.integrationCode` for the error code returned by the
+ * integration connector, if available.
  */
 export declare class ConductorIntegrationConnectionError extends ConductorError {
     static readonly rawType = "INTEGRATION_CONNECTION_ERROR";

package/dist/src/{error.js → utils/error.js}

@@ -10,7 +10,7 @@ exports.DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please tr
  */
 class ConductorError extends Error {
     /**
-     * The error type, which categorizes the error.
+     * Categorizes the error.
      *
      * This value is the same as the subclass name. E.g.,
      * `"ConductorIntegrationError"` or `"ConductorInvalidRequestError"`.
@@ -21,7 +21,7 @@ class ConductorError extends Error {
      * 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.
+     * In contrast, `type` is more general and categorizes the error.
      */
     code;
     /**
@@ -29,14 +29,14 @@ class ConductorError extends Error {
      */
     message;
     /**
-     * The end-user-friendly error message to display in your app's UI for your
-     * end-user to see.
+     * The end-user-friendly error message to display in your app's UI to your
+     * end-users.
      *
-     * 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,
-     * e.g., this message will just say "An internal server error occurred. Please
-     * try again later.".
+     * This value exists for *every* error. E.g., for 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, e.g.,
+     * this message will just say "An internal server error occurred. Please try
+     * again later.".
      */
     endUserMessage;
     /**
@@ -84,15 +84,16 @@ class ConductorError extends Error {
 }
 exports.ConductorError = ConductorError;
 /**
- * Raised when the third-party integration returned an error while processing
- * your end-user's request. Most likely, something is wrong with your request or
- * data handling that you must fix.
+ * Raised when the third-party integration encounters an error while processing
+ * the end-user's request. This often results from an issue with the request or
+ * data handling that requires your attention to resolve.
  *
  * E.g., a `ListID` you provided was not found in QuickBooks Desktop, or an
- * accounting value you provided failed the integration's accounting rules.
+ * accounting value you supplied did not adhere to the integration's accounting
+ * rules.
  *
- * See `error.integrationCode` for the error code that the integration returned,
- * if any.
+ * Refer to `error.integrationCode` for the error code returned by the
+ * integration, if available.
  */
 class ConductorIntegrationError extends ConductorError {
     static rawType = "INTEGRATION_ERROR";
@@ -102,15 +103,16 @@ class ConductorIntegrationError extends ConductorError {
 }
 exports.ConductorIntegrationError = ConductorIntegrationError;
 /**
- * Raised when an error occurred connecting to the third-party integration on
- * behalf of the end-user. Most likely, something is wrong with the end-user's
- * connection or configuration that the end-user must fix, not you.
+ * Raised when a connection error occurs with the third-party integration on the
+ * end-user's side. This typically indicates an issue with the end-user's
+ * integration connection or configuration, which they must resolve. In other
+ * words, you cannot take action to fix these errors.
  *
  * E.g., QuickBooks Web Connector (QBWC) failed to connect to QuickBooks Desktop
  * on the end-user's computer.
  *
- * See `error.integrationCode` for the error code that the integration connector
- * returned, if any.
+ * Refer to `error.integrationCode` for the error code returned by the
+ * integration connector, if available.
  */
 class ConductorIntegrationConnectionError extends ConductorError {
     static rawType = "INTEGRATION_CONNECTION_ERROR";

package/dist/src/{utils.d.ts → utils/misc.d.ts}

@@ -1,2 +1,2 @@
 export declare function checkForUpdates(): void;
-export declare function getServerUrlForEnvironment(environment: "development" | "production"): string;
+export declare function getServerUrlForEnvironment(environment: "development" | "production" | "test"): string;

package/dist/src/{utils.js → utils/misc.js}

@@ -4,7 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getServerUrlForEnvironment = exports.checkForUpdates = void 0;
-const package_json_1 = __importDefault(require("./../package.json"));
+const package_json_1 = __importDefault(require("../../package.json"));
 const node_child_process_1 = require("node:child_process");
 function checkForUpdates() {
     const currentVersion = package_json_1.default.version;

package/package.json

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