conductor-node 10.5.0 → 10.5.2

package/README.md

@@ -98,7 +98,7 @@ const qbdConnection =
 
 Checks 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`](#error-handling) (like any request). This information is useful for showing a "connection status" indicator in your app. If an error occurs, we recommend displaying the property `error.endUserMessage` to your end-user in your app's UI.
+If the connection fails, the error we encountered will be thrown as a [`ConductorError`](#error-handling) (like any request). This information is useful for showing a "connection status" indicator in your app. If an error occurs, we strongly recommend displaying the property `error.userFriendlyMessage` to your end-user in your app's UI.
 
 Using `async`/`await`:
 
@@ -107,7 +107,7 @@ try {
   await conductor.integrationConnections.ping(qbdConnectionId);
 } catch (error) {
   if (error instanceof ConductorError) {
-    // Update your app's UI to display `error.endUserMessage`.
+    // Update your app's UI to display `error.userFriendlyMessage`.
   }
   // ...
 }
@@ -118,7 +118,7 @@ Or in the form of a rejected promise:
 ```ts
 conductor.integrationConnections.ping(qbdConnectionId).catch((error) => {
   if (error instanceof ConductorError) {
-    // Update your app's UI to display `error.endUserMessage`.
+    // Update your app's UI to display `error.userFriendlyMessage`.
   }
   // ...
 });
@@ -158,16 +158,16 @@ const accountAddInput: QbdTypes.AccountAdd = {
 
 All errors thrown by the Conductor API are instances of `ConductorError` or its subclasses. These errors have the following properties:
 
-| Property          | Type                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ----------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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 to your end-users.<br><br>This value exists for _every_ error. E.g., for a QBD connection error, it might recommend the end-user to check that their QuickBooks Desktop is open and that they're logged in. But if a Conductor API key is expired, e.g., this message will just say "An internal server error occurred. Please try again later.".                                                                                                                                                      |
-| `type`            | `string`                | Categorizes the error. See [Error Types](#error-types) below.<br><br>This value is the same as the subclass name. E.g., `"ConductorIntegrationError"` or `"ConductorInvalidRequestError"`.                                                                                                                                                                                                                                                                                                                                                                             |
-| `code`            | `string`                | The unique error code from Conductor, which is useful for adding special handling for specific errors. E.g., `"RESOURCE_MISSING"`, `"API_KEY_INVALID"`, or `"QBD_REQUEST_ERROR"`.<br><br>In contrast, `type` is more general and categorizes the error.                                                                                                                                                                                                                                                                                                                |
-| `httpStatusCode`  | `number` or `undefined` | The HTTP status code of the response that included the error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `integrationCode` | `string` or `undefined` | The unique error code supplied by the third-party integration for errors returned by the integration (i.e., `ConductorIntegrationError`) or integration connector (i.e., `ConductorIntegrationConnectorError`). This is useful for adding special handling for specific errors from the third-party integration or connector.<br><br>The integration's corresponding error message for this code is in `error.message`.<br><br>The third-party integrations' error codes are not standardized, so you should not rely on this code to be the same across integrations. |
-| `requestId`       | `string` or `undefined` | The unique identifier for the request that caused the error.<br><br>If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.                                                                                                                                                                                                                                                                                                                                                                  |
-| `headers`         | `object` or `undefined` | The headers of the response that included the error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Property              | Type                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| --------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `message`             | `string`                | The developer-friendly error message for your logs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `userFriendlyMessage` | `string`                | The user-friendly error message, written specifically for displaying to your end-users in your app's UI.<br><br>This value exists for _every_ error. E.g., for a QBD connection error, it might recommend the end-user to check that their QuickBooks Desktop is open and that they're logged in. But if a Conductor API key is expired, e.g., this message will just say "An internal server error occurred. Please try again later.".                                                                                                                                |
+| `type`                | `string`                | Categorizes the error. See [Error Types](#error-types) below.<br><br>This value is the same as the subclass name. E.g., `"ConductorIntegrationError"` or `"ConductorInvalidRequestError"`.                                                                                                                                                                                                                                                                                                                                                                             |
+| `code`                | `string`                | The unique error code from Conductor, which is useful for adding special handling for specific errors. E.g., `"RESOURCE_MISSING"`, `"API_KEY_INVALID"`, or `"QBD_REQUEST_ERROR"`.<br><br>In contrast, `type` is more general and categorizes the error.                                                                                                                                                                                                                                                                                                                |
+| `httpStatusCode`      | `number` or `undefined` | The HTTP status code of the response that included the error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `integrationCode`     | `string` or `undefined` | The unique error code supplied by the third-party integration for errors returned by the integration (i.e., `ConductorIntegrationError`) or integration connector (i.e., `ConductorIntegrationConnectorError`). This is useful for adding special handling for specific errors from the third-party integration or connector.<br><br>The integration's corresponding error message for this code is in `error.message`.<br><br>The third-party integrations' error codes are not standardized, so you should not rely on this code to be the same across integrations. |
+| `requestId`           | `string` or `undefined` | The unique identifier for the request that caused the error.<br><br>If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.                                                                                                                                                                                                                                                                                                                                                                  |
+| `headers`             | `object` or `undefined` | The headers of the response that included the error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
 ### Error Types
 
@@ -230,7 +230,7 @@ conductor.qbd.account
 
 It is unnecessary to wrap each API call individually, as demonstrated in the examples above. Instead, we suggest implementing a Global 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. For any `ConductorError` instance, display the `error.endUserMessage` property to the end-user in your app's UI while logging the complete error object.
+1. For any `ConductorError` instance, display the `error.userFriendlyMessage` 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.
@@ -254,7 +254,7 @@ app.use((error, req, res, next) => {
     });
     // Return a different error message for your end-user to see in your
     // app's UI.
-    res.status(500).send({ error: { message: error.endUserMessage } });
+    res.status(500).send({ error: { message: error.userFriendlyMessage } });
   } else {
     // ...
   }
@@ -287,7 +287,7 @@ const server = new ApolloServer({
         ...formattedError,
         // Return a different error message for your end-user to see in
         // your app's UI.
-        message: origError.endUserMessage,
+        message: origError.userFriendlyMessage,
       };
     }
     // ...

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "conductor-node",
-    "version": "10.5.0",
+    "version": "10.5.2",
     "description": "Easily integrate the entire QuickBooks Desktop API using fully-typed async TypeScript",
     "keywords": [
         "QuickBooks Desktop",

package/dist/src/Client.js

@@ -22,7 +22,7 @@ class Client {
         (0, checkForUpdates_1.checkForUpdates)();
         this.httpClient = this.createHttpClient(apiKey, verbose, serverEnvironment);
         this.endUsers = new EndUsersResource_1.default(this.httpClient);
-        this.integrationConnections = new IntegrationConnectionsResource_1.default(this.httpClient);
+        this.integrationConnections = new IntegrationConnectionsResource_1.default(this);
         this.qbd = new QbdIntegration_1.default(this.httpClient);
     }
     createHttpClient(apiKey, verbose, serverEnvironment) {

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

@@ -2450,7 +2450,7 @@ class QbdIntegration extends BaseIntegration_1.default {
         if (responseBody === undefined) {
             throw new error_1.ConductorIntegrationError({
                 message: "No response received from QuickBooks Desktop.",
-                endUserMessage: "No response received from QuickBooks Desktop.",
+                userFriendlyMessage: "No response received from QuickBooks Desktop.",
                 code: "QBD_NO_RESPONSE",
             });
         }

package/dist/src/resources/EndUsersResource.d.ts

@@ -48,8 +48,8 @@ export default class EndUsersResource extends BaseResource {
      * If the connection fails, the error we encountered will be thrown as a
      * `ConductorError` (like any request). This information is useful for showing
      * a "connection status" indicator in your app. If an error occurs, we
-     * recommend displaying the property `error.endUserMessage` to your end-user
-     * in your app's UI.
+     * strongly recommend displaying the property `error.userFriendlyMessage` to
+     * your end-user in your app's UI.
      *
      * @param endUserId The ID of the end-user to ping.
      * @param integrationSlug The integration identifier for the

package/dist/src/resources/EndUsersResource.js

@@ -34,8 +34,8 @@ class EndUsersResource extends BaseResource_1.default {
      * If the connection fails, the error we encountered will be thrown as a
      * `ConductorError` (like any request). This information is useful for showing
      * a "connection status" indicator in your app. If an error occurs, we
-     * recommend displaying the property `error.endUserMessage` to your end-user
-     * in your app's UI.
+     * strongly recommend displaying the property `error.userFriendlyMessage` to
+     * your end-user in your app's UI.
      *
      * @param endUserId The ID of the end-user to ping.
      * @param integrationSlug The integration identifier for the

package/dist/src/resources/IntegrationConnectionAuthSessionsResource.d.ts

@@ -38,9 +38,9 @@ export interface IntegrationConnectionAuthSessionCreateInput {
 export default class IntegrationConnectionAuthSessionsResource extends BaseResource {
     protected readonly ROUTE = "/integration-connection-auth-sessions";
     /**
-     * Creates an auth `session for launch the client-side Integration Connection
-     * authentication flow. Use the returned session’s `clientSecret` to launch
-     * the auth flow using `conductor-react`.
+     * Creates an auth session for launching the client-side
+     * integration-connection authentication flow. Use the returned session’s
+     * `clientSecret` to launch the auth flow using Conductor.js.
      */
     create(input: IntegrationConnectionAuthSessionCreateInput): Promise<IntegrationConnectionAuthSession>;
     /**

package/dist/src/resources/IntegrationConnectionAuthSessionsResource.js

@@ -7,9 +7,9 @@ const BaseResource_1 = __importDefault(require("../resources/BaseResource"));
 class IntegrationConnectionAuthSessionsResource extends BaseResource_1.default {
     ROUTE = "/integration-connection-auth-sessions";
     /**
-     * Creates an auth `session for launch the client-side Integration Connection
-     * authentication flow. Use the returned session’s `clientSecret` to launch
-     * the auth flow using `conductor-react`.
+     * Creates an auth session for launching the client-side
+     * integration-connection authentication flow. Use the returned session’s
+     * `clientSecret` to launch the auth flow using Conductor.js.
      */
     async create(input) {
         const { data } = await this.httpClient.post(this.ROUTE, input);

package/dist/src/resources/IntegrationConnectionsResource.d.ts

@@ -1,6 +1,6 @@
+import type Client from "../Client";
 import BaseResource from "../resources/BaseResource";
 import IntegrationConnectionAuthSessionsResource from "../resources/IntegrationConnectionAuthSessionsResource";
-import type { AxiosInstance } from "axios";
 export type IntegrationSlug = "quickbooks-desktop";
 export interface IntegrationConnection {
     /**
@@ -22,8 +22,7 @@ export interface IntegrationConnection {
     createdAt: string;
 }
 /**
- * @deprecated We will soon remove this endpoint as we migrate to the new
- * end-user + auth-session model.
+ * @deprecated Use `conductor.endUsers.create()` instead.
  */
 export interface IntegrationConnectionCreateOldInput {
     /**
@@ -51,13 +50,14 @@ export interface IntegrationConnectionPingOutput {
 export default class IntegrationConnectionsResource extends BaseResource {
     readonly authSessions: IntegrationConnectionAuthSessionsResource;
     protected readonly ROUTE = "/integration-connections";
-    constructor(httpClient: AxiosInstance);
+    private readonly client;
+    constructor(client: Client);
     /**
      * Returns a list of all integration-connections of all your end-users.
      */
     list(): Promise<IntegrationConnection[]>;
     /**
-     * Creates a new integration-connection.
+     * @deprecated Use `conductor.endUsers.create({ ... })` instead.
      */
     create(input: IntegrationConnectionCreateOldInput): Promise<IntegrationConnection>;
     /**
@@ -65,17 +65,7 @@ export default class IntegrationConnectionsResource extends BaseResource {
      */
     retrieve(id: IntegrationConnection["id"]): Promise<IntegrationConnection>;
     /**
-     * Checks 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` (like any request). This information is useful for showing
-     * a "connection status" indicator in your app. If an error occurs, we
-     * recommend displaying the property `error.endUserMessage` to your end-user
-     * in your app's UI.
-     *
-     * @param id The integration-connection ID.
-     * @returns The ping result with the duration in milliseconds.
+     * @deprecated Use `conductor.endUsers.ping(id, "quickbooks-desktop")` instead.
      */
     ping(id: IntegrationConnection["id"]): Promise<IntegrationConnectionPingOutput>;
 }

package/dist/src/resources/IntegrationConnectionsResource.js

@@ -8,8 +8,11 @@ const IntegrationConnectionAuthSessionsResource_1 = __importDefault(require("../
 class IntegrationConnectionsResource extends BaseResource_1.default {
     authSessions;
     ROUTE = "/integration-connections";
-    constructor(httpClient) {
-        super(httpClient);
+    client;
+    constructor(client) {
+        // @ts-expect-error -- Temporary hack.
+        super(client.httpClient);
+        this.client = client;
         this.authSessions = new IntegrationConnectionAuthSessionsResource_1.default(this.httpClient);
     }
     /**
@@ -20,11 +23,20 @@ class IntegrationConnectionsResource extends BaseResource_1.default {
         return data;
     }
     /**
-     * Creates a new integration-connection.
+     * @deprecated Use `conductor.endUsers.create({ ... })` instead.
      */
     async create(input) {
-        const { data } = await this.httpClient.post(this.ROUTE, input);
-        return data;
+        const endUser = await this.client.endUsers.create({
+            sourceId: input.endUserSourceId,
+            email: input.endUserEmail,
+            name: input.endUserCompanyName,
+        });
+        return {
+            id: endUser.id,
+            endUserId: endUser.id,
+            integrationSlug: input.integrationSlug,
+            createdAt: endUser.createdAt,
+        };
     }
     /**
      * Retrieves the specified integration-connection.
@@ -34,21 +46,14 @@ class IntegrationConnectionsResource extends BaseResource_1.default {
         return data;
     }
     /**
-     * Checks 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` (like any request). This information is useful for showing
-     * a "connection status" indicator in your app. If an error occurs, we
-     * recommend displaying the property `error.endUserMessage` to your end-user
-     * in your app's UI.
-     *
-     * @param id The integration-connection ID.
-     * @returns The ping result with the duration in milliseconds.
+     * @deprecated Use `conductor.endUsers.ping(id, "quickbooks-desktop")` instead.
      */
     async ping(id) {
-        const { data } = await this.httpClient.get(`${this.ROUTE}/${id}/ping`);
-        return data;
+        if (id.startsWith("int_conn")) {
+            const { data } = await this.httpClient.get(`${this.ROUTE}/${id}/ping`);
+            return data;
+        }
+        return this.client.endUsers.ping(id, "quickbooks-desktop");
     }
 }
 exports.default = IntegrationConnectionsResource;

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

@@ -1,7 +1,11 @@
-export declare const DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please try again later.";
+export declare const DEFAULT_USER_FRIENDLY_MESSAGE = "An internal server error occurred. Please try again later.";
 export interface ConductorErrorOptions {
     readonly message: string;
+    /**
+     * @deprecated Use `userFriendlyMessage` instead.
+     */
     readonly endUserMessage?: string;
+    readonly userFriendlyMessage?: string;
     readonly type: string;
     readonly code: string;
     readonly httpStatusCode?: number | undefined;
@@ -15,12 +19,16 @@ export interface ConductorErrorOptions {
 export interface ConductorServerError {
     readonly error: {
         readonly message: string;
+        /**
+         * @deprecated Use `userFriendlyMessage` instead.
+         */
         readonly endUserMessage: string;
+        readonly userFriendlyMessage: string;
         readonly type: string;
         readonly code: string;
         readonly httpStatusCode: number;
         readonly integrationCode?: string;
-        readonly requestId?: string;
+        readonly requestId: string;
     };
 }
 export declare function isWellFormedConductorServerError(error: unknown): error is ConductorServerError;
@@ -34,8 +42,12 @@ export declare abstract class ConductorError extends Error {
      */
     readonly message: string;
     /**
-     * The end-user-friendly error message to display in your app's UI to your
-     * end-users.
+     * @deprecated Use `userFriendlyMessage` instead.
+     */
+    readonly endUserMessage: string;
+    /**
+     * The user-friendly error message, written specifically for displaying to
+     * your end-users in your app's UI.
      *
      * This value exists for *every* error. E.g., for a QBD connection error, it
      * might recommend the end-user to check that their QuickBooks Desktop is open
@@ -43,7 +55,7 @@ export declare abstract class ConductorError extends Error {
      * this message will just say "An internal server error occurred. Please try
      * again later.".
      */
-    readonly endUserMessage: string;
+    readonly userFriendlyMessage: string;
     /**
      * Categorizes the error.
      *

package/dist/src/utils/error.js

@@ -1,14 +1,16 @@
 "use strict";
 /* eslint-disable max-classes-per-file -- Use one module for all error classes. */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateConductorErrorFromType = exports.ConductorUnknownError = exports.ConductorInternalError = exports.ConductorConnectionError = exports.ConductorPermissionError = exports.ConductorAuthenticationError = exports.ConductorInvalidRequestError = exports.ConductorIntegrationConnectionError = exports.ConductorIntegrationError = exports.ConductorError = exports.isWellFormedConductorServerError = exports.DEFAULT_END_USER_MESSAGE = void 0;
+exports.generateConductorErrorFromType = exports.ConductorUnknownError = exports.ConductorInternalError = exports.ConductorConnectionError = exports.ConductorPermissionError = exports.ConductorAuthenticationError = exports.ConductorInvalidRequestError = exports.ConductorIntegrationConnectionError = exports.ConductorIntegrationError = exports.ConductorError = exports.isWellFormedConductorServerError = exports.DEFAULT_USER_FRIENDLY_MESSAGE = void 0;
 // Matches server-side value.
-exports.DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please try again later.";
+exports.DEFAULT_USER_FRIENDLY_MESSAGE = "An internal server error occurred. Please try again later.";
 function isWellFormedConductorServerError(error) {
     return (error instanceof Object &&
         typeof error.error === "object" &&
         typeof error.error.message === "string" &&
-        typeof error.error.endUserMessage === "string" &&
+        (typeof error.error.endUserMessage === "string" ||
+            typeof error.error.userFriendlyMessage ===
+                "string") &&
         typeof error.error.type === "string" &&
         typeof error.error.code === "string" &&
         typeof error.error.httpStatusCode === "number");
@@ -24,8 +26,12 @@ class ConductorError extends Error {
      */
     message;
     /**
-     * The end-user-friendly error message to display in your app's UI to your
-     * end-users.
+     * @deprecated Use `userFriendlyMessage` instead.
+     */
+    endUserMessage;
+    /**
+     * The user-friendly error message, written specifically for displaying to
+     * your end-users in your app's UI.
      *
      * This value exists for *every* error. E.g., for a QBD connection error, it
      * might recommend the end-user to check that their QuickBooks Desktop is open
@@ -33,7 +39,7 @@ class ConductorError extends Error {
      * this message will just say "An internal server error occurred. Please try
      * again later.".
      */
-    endUserMessage;
+    userFriendlyMessage;
     /**
      * Categorizes the error.
      *
@@ -97,7 +103,14 @@ class ConductorError extends Error {
         //    instantiated with the wrong options.
         this.type = this.constructor.name;
         this.message = options.message;
-        this.endUserMessage = options.endUserMessage ?? exports.DEFAULT_END_USER_MESSAGE;
+        this.endUserMessage =
+            options.endUserMessage ??
+                options.userFriendlyMessage ??
+                exports.DEFAULT_USER_FRIENDLY_MESSAGE;
+        this.userFriendlyMessage =
+            options.userFriendlyMessage ??
+                options.endUserMessage ??
+                exports.DEFAULT_USER_FRIENDLY_MESSAGE;
         this.code = options.code;
         this.httpStatusCode = options.httpStatusCode;
         this.integrationCode = options.integrationCode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conductor-node",
-  "version": "10.5.0",
+  "version": "10.5.2",
   "description": "Easily integrate the entire QuickBooks Desktop API using fully-typed async TypeScript",
   "keywords": [
     "QuickBooks Desktop",