conductor-node 9.1.1 → 9.1.3

package/README.md

@@ -175,14 +175,14 @@ All errors thrown by the Conductor API are instances of `ConductorError` or its
 
 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. This is likely due to an issue 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 integration 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.1",
+    "version": "9.1.3",
     "description": "Easily integrate with the entire QuickBooks Desktop API with fully-typed async TypeScript",
     "author": "Danny Nemer <hi@DannyNemer.com>",
     "license": "MIT",
@@ -12,8 +12,8 @@
         "dist/package.json"
     ],
     "scripts": {
-        "prepack": "yarn tsc && yarn delete-compiled-tests && yarn tsc-alias --verbose",
-        "delete-compiled-tests": "rm -rf `find ./dist -type d -name __tests__` ./dist/src/utils/testing.*",
+        "prepack": "yarn tsc && yarn delete-compiled-dev-files && yarn tsc-alias --verbose",
+        "delete-compiled-dev-files": "rm -rf `find ./dist -type d -name __tests__` ./dist/src/utils/testing.* ./dist/src/graphql/codegenConfig.*",
         "postpack": "rm -rf dist",
         "clean": "rm -rf dist package conductor-node-*.tgz tsconfig.tsbuildinfo",
         "gen:graphql": "yarn graphql-codegen --config=./src/graphql/codegenConfig.ts",

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}

@@ -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. This is likely due to an issue 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
- * integration 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}

@@ -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. This is likely due to an issue 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
- * integration 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.1",
+  "version": "9.1.3",
   "description": "Easily integrate with the entire QuickBooks Desktop API with fully-typed async TypeScript",
   "author": "Danny Nemer <hi@DannyNemer.com>",
   "license": "MIT",
@@ -12,8 +12,8 @@
     "dist/package.json"
   ],
   "scripts": {
-    "prepack": "yarn tsc && yarn delete-compiled-tests && yarn tsc-alias --verbose",
-    "delete-compiled-tests": "rm -rf `find ./dist -type d -name __tests__` ./dist/src/utils/testing.*",
+    "prepack": "yarn tsc && yarn delete-compiled-dev-files && yarn tsc-alias --verbose",
+    "delete-compiled-dev-files": "rm -rf `find ./dist -type d -name __tests__` ./dist/src/utils/testing.* ./dist/src/graphql/codegenConfig.*",
     "postpack": "rm -rf dist",
     "clean": "rm -rf dist package conductor-node-*.tgz tsconfig.tsbuildinfo",
     "gen:graphql": "yarn graphql-codegen --config=./src/graphql/codegenConfig.ts",

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

@@ -1,3 +0,0 @@
-import type { CodegenConfig } from "@graphql-codegen/cli";
-declare const codegenConfig: CodegenConfig;
-export default codegenConfig;

package/dist/src/graphql/codegenConfig.js

@@ -1,45 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const codegenConfig = {
-    schema: "../server/src/graphql/__generated__/schema.graphql",
-    hooks: { afterOneFileWrite: ["yarn prettier --write"] },
-    documents: ["./src/graphql/operations.graphql"],
-    ignoreNoDocuments: true,
-    generates: {
-        "./src/graphql/__generated__/operationTypes.ts": {
-            plugins: [
-                "typescript",
-                "typescript-operations",
-                "typescript-graphql-request",
-                {
-                    add: {
-                        content: [
-                            "/* eslint-disable eslint-comments/no-unlimited-disable -- Auto-generated */",
-                            "/* eslint-disable -- Auto-generated */",
-                        ].join("\n"),
-                    },
-                },
-            ],
-            config: {
-                // Avoid including `__typename` in objects we return to dev-users.
-                skipTypename: true,
-                // Use `import type {}` rather than `import {}`.
-                useTypeImports: true,
-                // Only emit types used in `operations.graphql`. This avoids confusion
-                // by creating types with more fields than the client actually returns
-                // (e.g. `IntegrationConnection` vs. `IntegrationConnectionFragment`)).
-                onlyOperationTypes: true,
-                avoidOptionals: true,
-                typesPrefix: "Graphql",
-                // Avoid adding `graphql-tag` as a client dependency.
-                documentMode: "string",
-                scalars: {
-                    DateTime: "Date",
-                    JSONObject: "object",
-                },
-                strictScalars: true,
-            },
-        },
-    },
-};
-exports.default = codegenConfig;