conductor-node 7.5.0 → 8.0.0

package/README.md

@@ -42,9 +42,11 @@ Create a new integration-connection.
 const newQbdConnection = await conductor.createIntegrationConnection({
   // The identifier of the third-party platform to integrate.
   integrationKey: "quickbooks-desktop",
+  // Your end-user's unique ID in your product's database. Must be distinct
+  // from your other connections for the same integration.
+  endUserSourceId: "1234-abcd",
   // Your end-user's email address for identification only. No emails
-  // will be sent. Must be distinct from your other connections for the
-  // same `integrationKey`.
+  // will be sent.
   endUserEmail: "danny@constructionco.com",
   // Your end-user's company name that will be shown elsewhere in Conductor.
   endUserCompanyName: "Construction Corp",
@@ -69,6 +71,7 @@ The response includes the following:
     // this end-user's integration in the future.
     id: '{UUID}',
     integrationKey: 'quickbooks-desktop',
+    endUserSourceId: "1234-abcd",
     endUserEmail: 'danny@constructionco.com',
     endUserCompanyName: 'Construction Corp',
     lastHeartbeatAt: null

package/dist/package.json

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

@@ -9,7 +9,6 @@ export interface ClientOptions {
 export default class Client {
     /** QuickBooks Desktop integration. */
     readonly qbd: QbdIntegration;
-    private readonly verbose;
     private readonly graphqlClient;
     private readonly graphqlOperations;
     constructor(apiKey: string, { verbose, serverEnvironment }?: ClientOptions);
@@ -26,12 +25,13 @@ export default class Client {
      * @param integrationConnectionId The ID of the integration connection.
      * @returns result Object with the following properties:
      * @returns result.isConnected Whether we can connect to the end-user's QBD.
-     * @returns result.devErrorMessage If `isConnected=false`, this will be the
-     * corresponding error message for the developer; e.g., "The end-user's
-     * computer is likely off".
-     * @returns result.endUserErrorMessage  If `isConnected=false`, this will be
-     * the corresponding error message for the end-user; e.g., "Please ensure your
-     * computer is on and QuickBooks Desktop is open".
+     * @returns result.error If `isConnected=false`, this will be an object with
+     * the following properties:
+     * @returns result.error.code The unique error code.
+     * @returns result.error.developerMessage The technical error message for the
+     * developer.
+     * @returns result.error.endUserMessage The user-friendly error message to
+     * display to the the end-user.
      */
     getConnectionStatus(integrationConnectionId: GraphqlGetConnectionStatusQueryVariables["integrationConnectionId"]): Promise<GraphqlGetConnectionStatusQuery["integrationConnection"]["connectionStatus"]>;
     /**
@@ -40,9 +40,11 @@ export default class Client {
      * @param input - The input object to create the integration connection.
      * @param input.integrationKey The identifier of the third-party platform to
      * integrate.
+     * @param input.endUserSourceId Your end-user's unique ID in your product's
+     * database. Must be distinct from your other connections for the same
+     * integration.
      * @param input.endUserEmail Your end-user's email address for identification
-     * only. No emails will be sent. Must be distinct from your other connections
-     * for the same integration.
+     * only. No emails will be sent.
      * @param input.endUserCompanyName Your end-user's company name that will be
      * shown elsewhere in Conductor.
      * @returns The newly created integration connection.
@@ -50,8 +52,6 @@ export default class Client {
     createIntegrationConnection(input: GraphqlCreateIntegrationConnectionInput & {
         integrationKey: "quickbooks-desktop";
     }): Promise<GraphqlCreateIntegrationConnectionMutation["createIntegrationConnection"]>;
+    /** Not intended for public use. */
     sendIntegrationRequest(input: GraphqlSendIntegrationRequestInput): Promise<GraphqlSendIntegrationRequestMutation["sendIntegrationRequest"]["response"]>;
-    private graphqlOperationWrapper;
-    private reformatError;
-    private checkForUpdates;
 }

package/dist/src/Client.js

@@ -4,34 +4,26 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 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 checkForUpdates_1 = __importDefault(require("./utils/checkForUpdates"));
 const environment_1 = require("./utils/environment");
-const chalk_1 = __importDefault(require("chalk"));
 const graphql_request_1 = require("graphql-request");
-const node_child_process_1 = require("node:child_process");
 class Client {
     /** QuickBooks Desktop integration. */
     qbd;
-    verbose;
     graphqlClient;
     graphqlOperations;
     constructor(apiKey, { verbose = false, serverEnvironment = "production" } = {}) {
-        this.checkForUpdates();
-        this.verbose = verbose;
+        (0, checkForUpdates_1.default)();
         this.graphqlClient = new graphql_request_1.GraphQLClient(`${(0, environment_1.getServerUrlForEnvironment)(serverEnvironment)}/graphql`, {
             headers: {
                 Authorization: `Bearer ${apiKey}`,
                 "User-Agent": `${package_json_1.default.name}/${package_json_1.default.version} (Node.js ${process.version}; ${process.platform} ${process.arch})`,
             },
         });
-        this.graphqlOperations = (0, operationTypes_1.getSdk)(this.graphqlClient);
-        Object.entries(this.graphqlOperations).forEach(([operationName, operation]) => {
-            // @ts-expect-error -- `operationName` is a key of `this.gqlOperations`.
-            this.graphqlOperations[operationName] = async (variables) => this.graphqlOperationWrapper(operationName, variables, 
-            // @ts-expect-error -- It is safe to call `operation` with `variables`.
-            operation);
-        });
+        this.graphqlOperations = (0, graphqlOperationWrapper_1.wrapGraphqlOperations)((0, operationTypes_1.getSdk)(this.graphqlClient), verbose);
         this.qbd = new QbdIntegration_1.default(this);
     }
     async getIntegrationConnection(integrationConnectionId) {
@@ -55,12 +47,13 @@ class Client {
      * @param integrationConnectionId The ID of the integration connection.
      * @returns result Object with the following properties:
      * @returns result.isConnected Whether we can connect to the end-user's QBD.
-     * @returns result.devErrorMessage If `isConnected=false`, this will be the
-     * corresponding error message for the developer; e.g., "The end-user's
-     * computer is likely off".
-     * @returns result.endUserErrorMessage  If `isConnected=false`, this will be
-     * the corresponding error message for the end-user; e.g., "Please ensure your
-     * computer is on and QuickBooks Desktop is open".
+     * @returns result.error If `isConnected=false`, this will be an object with
+     * the following properties:
+     * @returns result.error.code The unique error code.
+     * @returns result.error.developerMessage The technical error message for the
+     * developer.
+     * @returns result.error.endUserMessage The user-friendly error message to
+     * display to the the end-user.
      */
     async getConnectionStatus(integrationConnectionId) {
         return this.graphqlOperations
@@ -73,9 +66,11 @@ class Client {
      * @param input - The input object to create the integration connection.
      * @param input.integrationKey The identifier of the third-party platform to
      * integrate.
+     * @param input.endUserSourceId Your end-user's unique ID in your product's
+     * database. Must be distinct from your other connections for the same
+     * integration.
      * @param input.endUserEmail Your end-user's email address for identification
-     * only. No emails will be sent. Must be distinct from your other connections
-     * for the same integration.
+     * only. No emails will be sent.
      * @param input.endUserCompanyName Your end-user's company name that will be
      * shown elsewhere in Conductor.
      * @returns The newly created integration connection.
@@ -85,84 +80,12 @@ class Client {
             .createIntegrationConnection({ input })
             .then((result) => result.createIntegrationConnection);
     }
-    // TODO: Hide this method from the dev-user while still allowing the
-    // integration clients to access it.
+    // TODO: Find a way to make this private.
+    /** Not intended for public use. */
     async sendIntegrationRequest(input) {
         return this.graphqlOperations
             .sendIntegrationRequest({ input })
             .then((result) => result.sendIntegrationRequest.response);
     }
-    async graphqlOperationWrapper(operationName, variables, operation) {
-        const graphqlInfo = {
-            operationName,
-            input: variables
-                ? Object.keys(variables).length === 1 && "input" in variables
-                    ? variables["input"] // Flatten the input if it only has one key called "input".
-                    : variables
-                : {},
-        };
-        if (this.verbose) {
-            console.log(`Conductor request start: ${JSON.stringify(graphqlInfo, undefined, 2)}`);
-        }
-        const startTime = Date.now();
-        try {
-            const result = await operation(variables);
-            if (this.verbose) {
-                const responseInfo = {
-                    duration: `${(Date.now() - startTime) / 1000}s`,
-                    ...graphqlInfo,
-                };
-                const responseString = JSON.stringify(responseInfo, undefined, 2);
-                console.log(`Conductor response: ${responseString}`);
-            }
-            return result;
-        }
-        catch (error) {
-            const formattedError = this.reformatError(error);
-            if (this.verbose) {
-                const errorInfo = {
-                    duration: `${(Date.now() - startTime) / 1000}s`,
-                    error: String(formattedError),
-                    ...graphqlInfo,
-                };
-                const errorString = JSON.stringify(errorInfo, undefined, 2);
-                console.log(`Conductor error: ${errorString}`);
-            }
-            throw formattedError;
-        }
-    }
-    reformatError(error) {
-        if (error instanceof graphql_request_1.ClientError) {
-            const { response } = error;
-            if ([404, 502, 503].includes(response.status)) {
-                return new Error(`The Conductor server returned a ${response.status} error, which may indicate that the server is down. Please alert the Conductor team if this error persists.`);
-            }
-            const nestedError = response.errors?.[0];
-            if (nestedError?.extensions["code"] === "GRAPHQL_VALIDATION_FAILED") {
-                return new Error(`The Conductor server is no longer compatible with your version of "${package_json_1.default.name}". Please run "yarn upgrade ${package_json_1.default.name}@latest --latest" to update.`);
-            }
-            const errorMessage = nestedError?.message ??
-                // Though `ClientError.response.error` is *not* defined in the type
-                // definition, we've seen it occur (e.g., attempting to access the
-                // `development` environment when `ngrok` is not running locally).
-                response["error"];
-            if (errorMessage !== undefined) {
-                return new Error(errorMessage);
-            }
-        }
-        return error;
-    }
-    checkForUpdates() {
-        if (environment_1.currentEnvironment.isTest) {
-            return;
-        }
-        const currentVersion = package_json_1.default.version;
-        const latestVersion = (0, node_child_process_1.execSync)(`yarn info ${package_json_1.default.name} version`)
-            .toString()
-            .trim();
-        if (currentVersion !== latestVersion) {
-            console.warn(chalk_1.default.yellow(`⚠️ A new version of Conductor is available! You are using "${package_json_1.default.name}" version ${currentVersion} but the latest version is ${latestVersion}. Please run "yarn upgrade ${package_json_1.default.name} --latest" to update.`));
-        }
-    }
 }
 exports.default = Client;

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

@@ -26,6 +26,7 @@ export type Scalars = {
 export type GraphqlCreateIntegrationConnectionInput = {
     endUserCompanyName: Scalars["String"];
     endUserEmail: Scalars["String"];
+    endUserSourceId: Scalars["String"];
     integrationKey: Scalars["String"];
 };
 export type GraphqlSendIntegrationRequestInput = {
@@ -35,6 +36,7 @@ export type GraphqlSendIntegrationRequestInput = {
 export type GraphqlIntegrationConnectionFragment = {
     id: string;
     integrationKey: string;
+    endUserSourceId: string;
     endUserEmail: string;
     endUserCompanyName: string;
     lastHeartbeatAt: Date | null;
@@ -51,6 +53,7 @@ export type GraphqlGetIntegrationConnectionQuery = {
     integrationConnection: {
         id: string;
         integrationKey: string;
+        endUserSourceId: string;
         endUserEmail: string;
         endUserCompanyName: string;
         lastHeartbeatAt: Date | null;
@@ -63,6 +66,7 @@ export type GraphqlGetIntegrationConnectionsQuery = {
     integrationConnections: Array<{
         id: string;
         integrationKey: string;
+        endUserSourceId: string;
         endUserEmail: string;
         endUserCompanyName: string;
         lastHeartbeatAt: Date | null;
@@ -93,6 +97,7 @@ export type GraphqlCreateIntegrationConnectionMutation = {
         integrationConnection: {
             id: string;
             integrationKey: string;
+            endUserSourceId: string;
             endUserEmail: string;
             endUserCompanyName: string;
             lastHeartbeatAt: Date | null;
@@ -107,7 +112,7 @@ export type GraphqlSendIntegrationRequestMutation = {
         response: object;
     };
 };
-export declare const IntegrationConnectionFragmentDoc = "\n    fragment IntegrationConnection on IntegrationConnection {\n  id\n  integrationKey\n  endUserEmail\n  endUserCompanyName\n  lastHeartbeatAt\n}\n    ";
+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;

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

@@ -5,6 +5,7 @@ exports.IntegrationConnectionFragmentDoc = `
     fragment IntegrationConnection on IntegrationConnection {
   id
   integrationKey
+  endUserSourceId
   endUserEmail
   endUserCompanyName
   lastHeartbeatAt

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

@@ -0,0 +1,6 @@
+import type { getSdk } from "../graphql/__generated__/operationTypes";
+export declare function wrapGraphqlOperations<T extends ReturnType<typeof getSdk>>(graphqlOperations: T, verbose: boolean): T;
+export declare function graphqlOperationWrapper<V extends {
+    [key: string]: unknown;
+}, R>(operationName: string, variables: V | undefined, operation: (variables: V | undefined) => Promise<R>, verbose: boolean): Promise<R>;
+export declare function formatGraphqlError(error: Error): Error;

package/dist/src/graphql/graphqlOperationWrapper.js

@@ -0,0 +1,86 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatGraphqlError = exports.graphqlOperationWrapper = exports.wrapGraphqlOperations = void 0;
+const package_json_1 = __importDefault(require("../../package.json"));
+const graphql_request_1 = require("graphql-request");
+const node_util_1 = __importDefault(require("node:util"));
+function wrapGraphqlOperations(graphqlOperations, verbose) {
+    return Object.fromEntries(Object.entries(graphqlOperations).map(([operationName, operation]) => [
+        operationName,
+        async (variables) => graphqlOperationWrapper(operationName, 
+        // @ts-expect-error -- It is safe to call `operation` with `variables`.
+        variables, operation, verbose),
+    ]));
+}
+exports.wrapGraphqlOperations = wrapGraphqlOperations;
+async function graphqlOperationWrapper(operationName, variables, operation, verbose) {
+    const graphqlInfo = {
+        operationName,
+        input: variables
+            ? Object.keys(variables).length === 1 && "input" in variables
+                ? variables["input"] // Flatten the input if it only has one key called "input".
+                : variables
+            : {},
+    };
+    if (verbose) {
+        console.log(`Conductor request sent: ${node_util_1.default.inspect(graphqlInfo, {
+            depth: undefined,
+        })}`);
+    }
+    const startTime = Date.now();
+    try {
+        const result = await operation(variables);
+        if (verbose) {
+            const responseInfo = {
+                duration: getDurationString(startTime),
+                ...graphqlInfo,
+            };
+            const responseString = node_util_1.default.inspect(responseInfo, { depth: undefined });
+            console.log(`Conductor response: ${responseString}`);
+        }
+        return result;
+    }
+    catch (error) {
+        const formattedError = formatGraphqlError(error);
+        if (verbose) {
+            const errorInfo = {
+                duration: getDurationString(startTime),
+                error: String(formattedError),
+                ...graphqlInfo,
+            };
+            const errorString = node_util_1.default.inspect(errorInfo, { depth: undefined });
+            console.log(`Conductor error: ${errorString}`);
+        }
+        throw formattedError;
+    }
+}
+exports.graphqlOperationWrapper = graphqlOperationWrapper;
+function formatGraphqlError(error) {
+    if (error instanceof graphql_request_1.ClientError) {
+        const { response } = error;
+        if ([404, 502, 503].includes(response.status)) {
+            return new Error(`The Conductor server returned a ${response.status} error, which may indicate that the server is down. Please alert the Conductor team if this error persists.`);
+        }
+        const nestedError = response.errors?.[0];
+        if (nestedError?.extensions["code"] === "GRAPHQL_VALIDATION_FAILED") {
+            return new Error(`The Conductor server is no longer compatible with your version of "${package_json_1.default.name}". Please run "yarn upgrade ${package_json_1.default.name}@latest --latest" to update.`);
+        }
+        const errorMessage = nestedError?.message ??
+            // Though `ClientError.response.error` is *not* defined in the type
+            // definition, we've seen it occur (e.g., attempting to access the
+            // `development` environment when `ngrok` is not running locally).
+            response["error"];
+        if (errorMessage !== undefined) {
+            return new Error(errorMessage);
+        }
+    }
+    return error;
+}
+exports.formatGraphqlError = formatGraphqlError;
+function getDurationString(startTime) {
+    const duration = Date.now() - startTime;
+    return `${Math.round(duration / 10) / 100}s`;
+}

package/dist/src/utils/checkForUpdates.d.ts

@@ -0,0 +1 @@
+export default function checkForUpdates(): void;

package/dist/src/utils/checkForUpdates.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const package_json_1 = __importDefault(require("../../package.json"));
+const environment_1 = require("../utils/environment");
+const chalk_1 = __importDefault(require("chalk"));
+const node_child_process_1 = require("node:child_process");
+function checkForUpdates() {
+    if (environment_1.currentEnvironment.isTest) {
+        return;
+    }
+    const currentVersion = package_json_1.default.version;
+    const latestVersion = (0, node_child_process_1.execSync)(`yarn info ${package_json_1.default.name} version`)
+        .toString()
+        .trim();
+    if (currentVersion !== latestVersion) {
+        console.warn(chalk_1.default.yellow(`⚠️ A new version of Conductor is available! You are using "${package_json_1.default.name}" version ${currentVersion} but the latest version is ${latestVersion}. Please run "yarn upgrade ${package_json_1.default.name} --latest" to update.`));
+    }
+}
+exports.default = checkForUpdates;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conductor-node",
-  "version": "7.5.0",
+  "version": "8.0.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/utils/testConstants.d.ts

@@ -1,2 +0,0 @@
-export declare const CONDUCTOR_TEST_API_KEY = "063d95bc-a6f7-4b4b-841d-8007648a3112";
-export declare const CONDUCTOR_TEST_QBD_CONNECTION_ID = "49ee2e46-ec5a-40a0-8c37-43913994b2a9";

package/dist/src/utils/testConstants.js

@@ -1,5 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CONDUCTOR_TEST_QBD_CONNECTION_ID = exports.CONDUCTOR_TEST_API_KEY = void 0;
-exports.CONDUCTOR_TEST_API_KEY = "063d95bc-a6f7-4b4b-841d-8007648a3112";
-exports.CONDUCTOR_TEST_QBD_CONNECTION_ID = "49ee2e46-ec5a-40a0-8c37-43913994b2a9";