conductor-node 8.6.5 → 9.0.0

package/README.md

@@ -167,23 +167,21 @@ Any and every error thrown by the Conductor API will be an instance of `Conducto
 | `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` or `undefined` | 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. |
+| `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.".                                                                                                                                                                                              |
+| `integrationCode` | `string` or `undefined` | 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 error message for this code is 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` or `undefined` | 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
 
 The error object you receive will have one of the following error types:
 
-| Type                           | Description                                                                                                                                                              |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `ConductorIntegrationError`    | An error occurred on the third-party integration's end while processing your end-user's request. E.g., cannot connect to QuickBooks Desktop on your end-user's computer. |
-| `ConductorInvalidRequestError` | You made an API call with the wrong parameters, in the wrong state, or in an invalid way.                                                                                |
-| `ConductorAuthenticationError` | Conductor cannot authenticate you with the credentials you provided. E.g., an incorrect API key.                                                                         |
-| `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.)                                                                                                               |
+| Type                           | Description                                                                                                                                                                                                                                                      |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ConductorIntegrationError`    | The third-party integration's return an error while processing your end-user's request. E.g., cannot connect to QuickBooks Desktop on your end-user's computer.<br><br>See `error.integrationCode` for the error code that the third-party integration returned. |
+| `ConductorInvalidRequestError` | You made an API call with the wrong parameters, in the wrong state, or in an invalid way.                                                                                                                                                                        |
+| `ConductorAuthenticationError` | Conductor cannot authenticate you with the credentials you provided. E.g., an incorrect API key.                                                                                                                                                                 |
+| `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.)                                                                                                                                                                                                       |
 
 ### Specific Error Handling
 
@@ -232,7 +230,7 @@ try {
 
 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` for any `ConductorError` instance for any Conductor request while you log the rest of the error object.
+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 `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.

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "conductor-node",
-    "version": "8.6.5",
+    "version": "9.0.0",
     "description": "Easily integrate with the entire QuickBooks Desktop API with fully-typed async TypeScript",
     "author": "Danny Nemer <hi@DannyNemer.com>",
     "license": "MIT",
@@ -16,8 +16,11 @@
         "delete-compiled-tests": "rm -rf `find ./dist -type d -name __tests__` ./dist/src/utils/testing.*",
         "postpack": "rm -rf dist",
         "clean": "rm -rf dist package conductor-node-*.tgz tsconfig.tsbuildinfo",
-        "gen:graphql": "yarn graphql-codegen --config ./src/graphql/codegenConfig.ts",
-        "diff": "yarn pack && npm diff --diff=conductor-node@latest --diff=conductor-node-v$(node -p \"require('./package.json').version\").tgz && yarn clean"
+        "gen:graphql": "yarn graphql-codegen --config=./src/graphql/codegenConfig.ts",
+        "diff": "yarn pack && npm diff --diff=conductor-node@latest --diff=conductor-node-v$(node -p \"require('./package.json').version\").tgz && yarn clean",
+        "prepublishOnly": "yarn test",
+        "test": "yarn --cwd=../.. test ./packages/client",
+        "jest": "yarn --cwd=../../ jest"
     },
     "engines": {
         "node": ">=16"

package/dist/src/Client.d.ts

@@ -1,4 +1,4 @@
-import type { GraphqlCreateIntegrationConnectionInput, GraphqlCreateIntegrationConnectionMutation, GraphqlGetConnectionStatusQuery, GraphqlGetConnectionStatusQueryVariables, GraphqlGetIntegrationConnectionQuery, GraphqlGetIntegrationConnectionQueryVariables, GraphqlGetIntegrationConnectionsQuery, GraphqlPingIntegrationConnectionMutation, GraphqlPingIntegrationConnectionMutationVariables } from "./graphql/__generated__/operationTypes";
+import type { GraphqlCreateIntegrationConnectionInput, GraphqlCreateIntegrationConnectionMutation, GraphqlGetIntegrationConnectionQuery, GraphqlGetIntegrationConnectionQueryVariables, GraphqlGetIntegrationConnectionsQuery, GraphqlPingIntegrationConnectionMutation, GraphqlPingIntegrationConnectionMutationVariables } from "./graphql/__generated__/operationTypes";
 import QbdIntegration from "./integrations/qbd/QbdIntegration";
 import { getServerUrlForEnvironment } from "./utils";
 export interface ClientOptions {
@@ -25,25 +25,6 @@ export default class Client {
      * @returns The integration-connections.
      */
     getIntegrationConnections(): Promise<GraphqlGetIntegrationConnectionsQuery["integrationConnections"]>;
-    /**
-     * 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
-     * QBD is not running, the wrong company file is open, or there is a modal
-     * dialog open in QBD.
-     *
-     * @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
-     *   properties:
-     *   - error.code - The unique error code.
-     *   - error.developerMessage - The technical error message for the developer.
-     *   - error.endUserMessage - The user-friendly error message to display to
-     *     the the end-user.
-     */
-    getConnectionStatus(integrationConnectionId: GraphqlGetConnectionStatusQueryVariables["integrationConnectionId"]): Promise<GraphqlGetConnectionStatusQuery["integrationConnection"]["connectionStatus"]>;
     /**
      * Creates a new integration-connection.
      *

package/dist/src/Client.js

@@ -41,29 +41,6 @@ class Client {
             .getIntegrationConnections()
             .then((result) => result.integrationConnections);
     }
-    /**
-     * 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
-     * QBD is not running, the wrong company file is open, or there is a modal
-     * dialog open in QBD.
-     *
-     * @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
-     *   properties:
-     *   - error.code - The unique error code.
-     *   - error.developerMessage - The technical error message for the developer.
-     *   - error.endUserMessage - The user-friendly error message to display to
-     *     the the end-user.
-     */
-    async getConnectionStatus(integrationConnectionId) {
-        return this.graphqlOperations
-            .getConnectionStatus({ integrationConnectionId })
-            .then((result) => result.integrationConnection.connectionStatus);
-    }
     /**
      * Creates a new integration-connection.
      *

package/dist/src/errors.d.ts

@@ -45,8 +45,8 @@ export declare class ConductorError extends Error {
      * 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.".
+     * e.g., this message will just say "An internal server error occurred. Please
+     * try again later.".
      */
     readonly endUserMessage: string;
     /**
@@ -57,7 +57,7 @@ export declare class ConductorError extends Error {
      *
      * 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`.
+     * error message for this code is 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.
@@ -76,9 +76,12 @@ export declare class ConductorError extends Error {
 }
 type ConductorErrorOptionsWithoutType = Omit<ConductorErrorOptions, "type">;
 /**
- * Raised when an error occurs on the third-party integration's end while
- * processing your end-user's request. E.g., cannot connect to QuickBooks
- * Desktop on the end-user's computer.
+ * Raised when the third-party integration returned an error while processing
+ * your end-user's request. E.g., cannot connect to QuickBooks Desktop on the
+ * end-user's computer.
+ *
+ * See `error.integrationCode` for the error code that the third-party
+ * integration returned.
  */
 export declare class ConductorIntegrationError extends ConductorError {
     static readonly rawType: string;

package/dist/src/errors.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateConductorErrorFromType = exports.ConductorUnknownError = exports.ConductorInternalError = exports.ConductorConnectionError = exports.ConductorAuthenticationError = exports.ConductorInvalidRequestError = exports.ConductorIntegrationError = exports.ConductorError = exports.DEFAULT_END_USER_MESSAGE = void 0;
 /* eslint-disable max-classes-per-file -- Use one module for all error classes. */
+// Matches server-side default value.
 exports.DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please try again later.";
 /**
  * The base error from which all other more specific Conductor errors derive.
@@ -34,8 +35,8 @@ class ConductorError extends Error {
      * 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.".
+     * e.g., this message will just say "An internal server error occurred. Please
+     * try again later.".
      */
     endUserMessage;
     /**
@@ -46,7 +47,7 @@ class ConductorError extends Error {
      *
      * 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`.
+     * error message for this code is 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.
@@ -83,9 +84,12 @@ class ConductorError extends Error {
 }
 exports.ConductorError = ConductorError;
 /**
- * Raised when an error occurs on the third-party integration's end while
- * processing your end-user's request. E.g., cannot connect to QuickBooks
- * Desktop on the end-user's computer.
+ * Raised when the third-party integration returned an error while processing
+ * your end-user's request. E.g., cannot connect to QuickBooks Desktop on the
+ * end-user's computer.
+ *
+ * See `error.integrationCode` for the error code that the third-party
+ * integration returned.
  */
 class ConductorIntegrationError extends ConductorError {
     static rawType = "INTEGRATION_ERROR";

package/dist/src/graphql/__generated__/operationTypes.d.ts

@@ -47,11 +47,6 @@ export type GraphqlIntegrationConnectionFragment = {
     endUserCompanyName: string;
     lastHeartbeatAt: Date | null;
 };
-export type GraphqlUserErrorFragment = {
-    code: string;
-    developerMessage: string;
-    endUserMessage: string;
-};
 export type GraphqlGetIntegrationConnectionQueryVariables = Exact<{
     integrationConnectionId: Scalars["ID"];
 }>;
@@ -78,21 +73,6 @@ export type GraphqlGetIntegrationConnectionsQuery = {
         lastHeartbeatAt: Date | null;
     }>;
 };
-export type GraphqlGetConnectionStatusQueryVariables = Exact<{
-    integrationConnectionId: Scalars["ID"];
-}>;
-export type GraphqlGetConnectionStatusQuery = {
-    integrationConnection: {
-        connectionStatus: {
-            isConnected: boolean;
-            error: {
-                code: string;
-                developerMessage: string;
-                endUserMessage: string;
-            } | null;
-        };
-    };
-};
 export type GraphqlCreateIntegrationConnectionMutationVariables = Exact<{
     input: GraphqlCreateIntegrationConnectionInput;
 }>;
@@ -125,10 +105,8 @@ export type GraphqlSendIntegrationRequestMutation = {
     };
 };
 export declare const IntegrationConnectionFragmentDoc = "\n    fragment IntegrationConnection on IntegrationConnection {\n  id\n  integrationKey\n  endUserSourceId\n  endUserEmail\n  endUserCompanyName\n  lastHeartbeatAt\n}\n    ";
-export declare const UserErrorFragmentDoc = "\n    fragment UserError on UserError {\n  code\n  developerMessage\n  endUserMessage\n}\n    ";
 export declare const GetIntegrationConnectionDocument: string;
 export declare const GetIntegrationConnectionsDocument: string;
-export declare const GetConnectionStatusDocument: string;
 export declare const CreateIntegrationConnectionDocument: string;
 export declare const PingIntegrationConnectionDocument = "\n    mutation pingIntegrationConnection($input: PingIntegrationConnectionInput!) {\n  pingIntegrationConnection(input: $input) {\n    duration\n  }\n}\n    ";
 export declare const SendIntegrationRequestDocument = "\n    mutation sendIntegrationRequest($input: SendIntegrationRequestInput!) {\n  sendIntegrationRequest(input: $input) {\n    response\n  }\n}\n    ";
@@ -136,7 +114,6 @@ export type SdkFunctionWrapper = <T>(action: (requestHeaders?: Record<string, st
 export declare function getSdk(client: GraphQLClient, withWrapper?: SdkFunctionWrapper): {
     getIntegrationConnection(variables: GraphqlGetIntegrationConnectionQueryVariables, requestHeaders?: (Record<string, string> | Dom.Headers | string[][]) | undefined): Promise<GraphqlGetIntegrationConnectionQuery>;
     getIntegrationConnections(variables?: GraphqlGetIntegrationConnectionsQueryVariables, requestHeaders?: (Record<string, string> | Dom.Headers | string[][]) | undefined): Promise<GraphqlGetIntegrationConnectionsQuery>;
-    getConnectionStatus(variables: GraphqlGetConnectionStatusQueryVariables, requestHeaders?: (Record<string, string> | Dom.Headers | string[][]) | undefined): Promise<GraphqlGetConnectionStatusQuery>;
     createIntegrationConnection(variables: GraphqlCreateIntegrationConnectionMutationVariables, requestHeaders?: (Record<string, string> | Dom.Headers | string[][]) | undefined): Promise<GraphqlCreateIntegrationConnectionMutation>;
     pingIntegrationConnection(variables: GraphqlPingIntegrationConnectionMutationVariables, requestHeaders?: (Record<string, string> | Dom.Headers | string[][]) | undefined): Promise<GraphqlPingIntegrationConnectionMutation>;
     sendIntegrationRequest(variables: GraphqlSendIntegrationRequestMutationVariables, requestHeaders?: (Record<string, string> | Dom.Headers | string[][]) | undefined): Promise<GraphqlSendIntegrationRequestMutation>;

package/dist/src/graphql/__generated__/operationTypes.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSdk = exports.SendIntegrationRequestDocument = exports.PingIntegrationConnectionDocument = exports.CreateIntegrationConnectionDocument = exports.GetConnectionStatusDocument = exports.GetIntegrationConnectionsDocument = exports.GetIntegrationConnectionDocument = exports.UserErrorFragmentDoc = exports.IntegrationConnectionFragmentDoc = void 0;
+exports.getSdk = exports.SendIntegrationRequestDocument = exports.PingIntegrationConnectionDocument = exports.CreateIntegrationConnectionDocument = exports.GetIntegrationConnectionsDocument = exports.GetIntegrationConnectionDocument = exports.IntegrationConnectionFragmentDoc = void 0;
 exports.IntegrationConnectionFragmentDoc = `
     fragment IntegrationConnection on IntegrationConnection {
   id
@@ -11,13 +11,6 @@ exports.IntegrationConnectionFragmentDoc = `
   lastHeartbeatAt
 }
     `;
-exports.UserErrorFragmentDoc = `
-    fragment UserError on UserError {
-  code
-  developerMessage
-  endUserMessage
-}
-    `;
 exports.GetIntegrationConnectionDocument = `
     query getIntegrationConnection($integrationConnectionId: ID!) {
   integrationConnection(id: $integrationConnectionId) {
@@ -32,18 +25,6 @@ exports.GetIntegrationConnectionsDocument = `
   }
 }
     ${exports.IntegrationConnectionFragmentDoc}`;
-exports.GetConnectionStatusDocument = `
-    query getConnectionStatus($integrationConnectionId: ID!) {
-  integrationConnection(id: $integrationConnectionId) {
-    connectionStatus {
-      isConnected
-      error {
-        ...UserError
-      }
-    }
-  }
-}
-    ${exports.UserErrorFragmentDoc}`;
 exports.CreateIntegrationConnectionDocument = `
     mutation createIntegrationConnection($input: CreateIntegrationConnectionInput!) {
   createIntegrationConnection(input: $input) {
@@ -76,9 +57,6 @@ function getSdk(client, withWrapper = defaultWrapper) {
         getIntegrationConnections(variables, requestHeaders) {
             return withWrapper((wrappedRequestHeaders) => client.request(exports.GetIntegrationConnectionsDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "getIntegrationConnections", "query");
         },
-        getConnectionStatus(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.request(exports.GetConnectionStatusDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "getConnectionStatus", "query");
-        },
         createIntegrationConnection(variables, requestHeaders) {
             return withWrapper((wrappedRequestHeaders) => client.request(exports.CreateIntegrationConnectionDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "createIntegrationConnection", "mutation");
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conductor-node",
-  "version": "8.6.5",
+  "version": "9.0.0",
   "description": "Easily integrate with the entire QuickBooks Desktop API with fully-typed async TypeScript",
   "author": "Danny Nemer <hi@DannyNemer.com>",
   "license": "MIT",
@@ -16,8 +16,11 @@
     "delete-compiled-tests": "rm -rf `find ./dist -type d -name __tests__` ./dist/src/utils/testing.*",
     "postpack": "rm -rf dist",
     "clean": "rm -rf dist package conductor-node-*.tgz tsconfig.tsbuildinfo",
-    "gen:graphql": "yarn graphql-codegen --config ./src/graphql/codegenConfig.ts",
-    "diff": "yarn pack && npm diff --diff=conductor-node@latest --diff=conductor-node-v$(node -p \"require('./package.json').version\").tgz && yarn clean"
+    "gen:graphql": "yarn graphql-codegen --config=./src/graphql/codegenConfig.ts",
+    "diff": "yarn pack && npm diff --diff=conductor-node@latest --diff=conductor-node-v$(node -p \"require('./package.json').version\").tgz && yarn clean",
+    "prepublishOnly": "yarn test",
+    "test": "yarn --cwd=../.. test ./packages/client",
+    "jest": "yarn --cwd=../../ jest"
   },
   "engines": {
     "node": ">=16"