conductor-node 8.2.4 → 8.3.0

package/README.md

@@ -2,8 +2,18 @@
 
 Execute _any_ read or write [QuickBooks Desktop API](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop) through async TypeScript and receive a fully-typed response.
 
+<!-- markdownlint-disable MD033 -->
 <img src="https://user-images.githubusercontent.com/170023/213273732-83dd6881-0b36-4787-820b-bd55cdc8444f.jpg" alt="qbd" width="600"/>
 
+## Table of Contents
+
+1. [Requirements](#requirements)
+2. [Installation](#installation)
+3. [Usage](#usage)
+4. [APIs](#apis)
+5. [TypeScript](#typescript)
+6. [Error Handling](#error-handling)
+
 ## Requirements
 
 1. A Conductor API key from Danny.
@@ -34,7 +44,7 @@ const newAccount = await conductor.qbd.account.add(qbdConnections[0].id, {
 });
 ```
 
-## `Conductor` APIs
+## APIs
 
 ### `createIntegrationConnection(input: CreateIntegrationConnectionInput)`
 
@@ -100,34 +110,39 @@ const qbdConnection = await conductor.getIntegrationConnectionById(
 );
 ```
 
-### `getConnectionStatus(id: string)`
+### `pingIntegrationConnection(id: string)`
 
-Check whether we can successfully connect to the end-user's QBD instance.
+Check whether the specified integration-connection can connect and process requests end-to-end.
 
-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.
+If the connection fails, the error we encountered will be thrown as a [`ConductorError`](#error-handling). This information is useful for showing a "connection status" indicator in your app.
+
+In the form of a rejected promise:
 
 ```ts
-const connectionStatus = await conductor.getConnectionStatus(qbdConnectionId);
+conductor.pingIntegrationConnection(qbdConnectionId).catch((error) => {
+  if (error instanceof ConductorError) {
+    // Update your app's UI to display `error.endUserMessage`.
+  }
+  // ...
+});
 ```
 
-The response includes the following:
+Or using `async`/`await`:
 
 ```ts
-{
-  // Whether we can connect to the end-user's QuickBooks Desktop.
-  isConnected: false,
-  // If `isConnected=false`, an `error` like the following will exist:
-  error: {
-    code: "QBWC_CONNECTION_ERROR",
-    developerMessage: "QBWC Error 0x80040408: Could not start QuickBooks.",
-    endUserMessage: "An error occurred while connecting to QuickBooks Desktop. Please ensure QuickBooks Desktop is running and the correct company file is open, then try again.",
+try {
+  await conductor.pingIntegrationConnection(qbdConnectionId);
+} catch (error) {
+  if (error instanceof ConductorError) {
+    // Update your app's UI to display `error.endUserMessage`.
   }
+  // ...
 }
 ```
 
 ## TypeScript
 
-Access the full QuickBooks Desktop API through TypeScript. The `qbd.*` APIs are fully-typed with inline documentation and will autocomplete in your editor.
+Access the full QuickBooks Desktop API through TypeScript. The `qbd.*` APIs are fully typed with inline documentation and will autocomplete in your editor.
 
 To manually access the QBD types, import them from `conductor-node` like so:
 
@@ -140,3 +155,73 @@ const accountAddInput: QbdTypes.AccountAdd = {
   OpenBalance: "100",
 };
 ```
+
+## Error Handling
+
+The `ConductorError` has the following properties:
+
+```ts
+{
+  // The error type.
+  type: string;
+  // The error code.
+  code: string;
+  // The developer-friendly error message for your logs.
+  developerMessage: string;
+  // The end-user-friendly error message to display in your app.
+  endUserMessage: string;
+  // The HTTP status code.
+  statusCode: number | undefined;
+}
+```
+
+### Error Types
+
+The error object you receive will have one of the following category types:
+
+| Type                    | Description                                                                               |
+| ----------------------- | ----------------------------------------------------------------------------------------- |
+| `authentication_error`  | Conductor can't authenticate you with the information provided. E.g. incorrect API key.   |
+| `connection_error`      | There was a network problem between your server and Conductor.                            |
+| `integration_error`     | An error occurred on the third-party integration's end while processing your request.     |
+| `internal_error`        | Something went wrong on Conductor's end. (These are rare.)                                |
+| `invalid_request_error` | You made an API call with the wrong parameters, in the wrong state, or in an invalid way. |
+
+### Example
+
+Using `async`/`await`:
+
+```ts
+try {
+  const newAccount = await conductor.qbd.account.add(qbdConnectionId, {
+    Name: "Test Account",
+    AccountType: "Bank",
+    OpenBalance: "100",
+  });
+} catch (error) {
+  if (error instanceof ConductorError) {
+    // Update your app's UI to display `error.endUserMessage`.
+  }
+  // ...
+}
+```
+
+Or in the form of a rejected promise:
+
+```ts
+conductor.qbd.account
+  .add(qbdConnectionId, {
+    Name: "Test Account",
+    AccountType: "Bank",
+    OpenBalance: "100",
+  })
+  .then((newAccount) => {
+    // ...
+  })
+  .catch((error) => {
+    if (error instanceof ConductorError) {
+      // Update your app's UI to display `error.endUserMessage`.
+    }
+    // ...
+  });
+```

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "conductor-node",
-    "version": "8.2.4",
+    "version": "8.3.0",
     "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,4 +1,4 @@
-import type { GraphqlCreateIntegrationConnectionInput, GraphqlCreateIntegrationConnectionMutation, GraphqlGetConnectionStatusQuery, GraphqlGetConnectionStatusQueryVariables, GraphqlGetIntegrationConnectionQuery, GraphqlGetIntegrationConnectionQueryVariables, GraphqlGetIntegrationConnectionsQuery } from "./graphql/__generated__/operationTypes";
+import type { GraphqlCreateIntegrationConnectionInput, GraphqlCreateIntegrationConnectionMutation, GraphqlGetConnectionStatusQuery, GraphqlGetConnectionStatusQueryVariables, GraphqlGetIntegrationConnectionQuery, GraphqlGetIntegrationConnectionQueryVariables, GraphqlGetIntegrationConnectionsQuery, GraphqlPingIntegrationConnectionMutation, GraphqlPingIntegrationConnectionMutationVariables } from "./graphql/__generated__/operationTypes";
 import QbdIntegration from "./integrations/qbd/QbdIntegration";
 import { getServerUrlForEnvironment } from "./utils";
 export interface ClientOptions {
@@ -62,5 +62,14 @@ export default class Client {
     createIntegrationConnection(input: GraphqlCreateIntegrationConnectionInput & {
         integrationKey: "quickbooks-desktop";
     }): Promise<GraphqlCreateIntegrationConnectionMutation["createIntegrationConnection"]["integrationConnection"]>;
+    /**
+     * Check whether the specified integration-connection can connect and process
+     * requests end-to-end.
+     *
+     * If the connection fails, the error we encountered will be thrown as a
+     * `ConductorError`. This information is useful for showing a "connection
+     * status" indicator in your app.
+     */
+    pingIntegrationConnection(integrationConnectionId: GraphqlPingIntegrationConnectionMutationVariables["input"]["integrationConnectionId"]): Promise<GraphqlPingIntegrationConnectionMutation["pingIntegrationConnection"]>;
     private createHeaders;
 }

package/dist/src/Client.js

@@ -84,6 +84,19 @@ class Client {
             .createIntegrationConnection({ input })
             .then((result) => result.createIntegrationConnection.integrationConnection);
     }
+    /**
+     * Check whether the specified integration-connection can connect and process
+     * requests end-to-end.
+     *
+     * If the connection fails, the error we encountered will be thrown as a
+     * `ConductorError`. This information is useful for showing a "connection
+     * status" indicator in your app.
+     */
+    async pingIntegrationConnection(integrationConnectionId) {
+        return this.graphqlOperations
+            .pingIntegrationConnection({ input: { integrationConnectionId } })
+            .then((result) => result.pingIntegrationConnection);
+    }
     createHeaders(apiKey) {
         return {
             Authorization: `Bearer ${apiKey}`,

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

@@ -29,6 +29,9 @@ export type GraphqlCreateIntegrationConnectionInput = {
     endUserSourceId: Scalars["String"];
     integrationKey: Scalars["String"];
 };
+export type GraphqlPingIntegrationConnectionInput = {
+    integrationConnectionId: Scalars["ID"];
+};
 export type GraphqlSendIntegrationRequestInput = {
     integrationConnectionId: Scalars["ID"];
     requestObject: Scalars["JSONObject"];
@@ -105,6 +108,14 @@ export type GraphqlCreateIntegrationConnectionMutation = {
         };
     };
 };
+export type GraphqlPingIntegrationConnectionMutationVariables = Exact<{
+    input: GraphqlPingIntegrationConnectionInput;
+}>;
+export type GraphqlPingIntegrationConnectionMutation = {
+    pingIntegrationConnection: {
+        duration: number;
+    };
+};
 export type GraphqlSendIntegrationRequestMutationVariables = Exact<{
     input: GraphqlSendIntegrationRequestInput;
 }>;
@@ -119,6 +130,7 @@ 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    ";
 export type SdkFunctionWrapper = <T>(action: (requestHeaders?: Record<string, string>) => Promise<T>, operationName: string, operationType?: string) => Promise<T>;
 export declare function getSdk(client: GraphQLClient, withWrapper?: SdkFunctionWrapper): {
@@ -126,6 +138,7 @@ export declare function getSdk(client: GraphQLClient, withWrapper?: SdkFunctionW
     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>;
 };
 export type Sdk = ReturnType<typeof getSdk>;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSdk = exports.SendIntegrationRequestDocument = exports.CreateIntegrationConnectionDocument = exports.GetConnectionStatusDocument = exports.GetIntegrationConnectionsDocument = exports.GetIntegrationConnectionDocument = exports.UserErrorFragmentDoc = exports.IntegrationConnectionFragmentDoc = void 0;
+exports.getSdk = exports.SendIntegrationRequestDocument = exports.PingIntegrationConnectionDocument = exports.CreateIntegrationConnectionDocument = exports.GetConnectionStatusDocument = exports.GetIntegrationConnectionsDocument = exports.GetIntegrationConnectionDocument = exports.UserErrorFragmentDoc = exports.IntegrationConnectionFragmentDoc = void 0;
 exports.IntegrationConnectionFragmentDoc = `
     fragment IntegrationConnection on IntegrationConnection {
   id
@@ -53,6 +53,13 @@ exports.CreateIntegrationConnectionDocument = `
   }
 }
     ${exports.IntegrationConnectionFragmentDoc}`;
+exports.PingIntegrationConnectionDocument = `
+    mutation pingIntegrationConnection($input: PingIntegrationConnectionInput!) {
+  pingIntegrationConnection(input: $input) {
+    duration
+  }
+}
+    `;
 exports.SendIntegrationRequestDocument = `
     mutation sendIntegrationRequest($input: SendIntegrationRequestInput!) {
   sendIntegrationRequest(input: $input) {
@@ -75,6 +82,9 @@ function getSdk(client, withWrapper = defaultWrapper) {
         createIntegrationConnection(variables, requestHeaders) {
             return withWrapper((wrappedRequestHeaders) => client.request(exports.CreateIntegrationConnectionDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "createIntegrationConnection", "mutation");
         },
+        pingIntegrationConnection(variables, requestHeaders) {
+            return withWrapper((wrappedRequestHeaders) => client.request(exports.PingIntegrationConnectionDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "pingIntegrationConnection", "mutation");
+        },
         sendIntegrationRequest(variables, requestHeaders) {
             return withWrapper((wrappedRequestHeaders) => client.request(exports.SendIntegrationRequestDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "sendIntegrationRequest", "mutation");
         },

package/dist/src/graphql/graphqlOperationWrapper.js

@@ -85,6 +85,7 @@ function generateConductorError(error) {
             // definition, we've seen it occur (e.g., attempting to access the
             // `development` environment when `ngrok` is not running locally).
             response["error"];
+        console.log("***********************");
         if (errorMessage !== undefined) {
             return new error_1.ConductorError({
                 type: "temp",

package/package.json

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