conductor-node 10.0.2 → 10.2.0

package/dist/src/interceptors/errorHandling.js

@@ -8,17 +8,22 @@ function addErrorHandlingInterceptors(httpClient) {
         // The request was made and the server responded with a status code that
         // falls out of the range of 2xx.
         if (error.response) {
+            const headers = { ...error.response.headers };
             const errorData = error.response.data;
-            if (!(0, error_1.isWellFormedConductorServerError)(errorData)) {
-                throw new error_1.ConductorInternalError({
-                    code: "INVALID_JSON_RESPONSE",
-                    message: "Invalid JSON received from the Conductor API.",
-                    httpStatusCode: error.status ?? axios_1.HttpStatusCode.InternalServerError,
+            if ((0, error_1.isWellFormedConductorServerError)(errorData)) {
+                throw (0, error_1.generateConductorErrorFromType)({
+                    ...errorData.error,
+                    httpStatusCode: error.response.status,
+                    headers,
                 });
             }
-            throw (0, error_1.generateConductorErrorFromType)({
-                ...errorData.error,
-                httpStatusCode: error.response.status,
+            throw new error_1.ConductorInternalError({
+                message: "Invalid JSON received from the Conductor API.",
+                code: "INVALID_JSON_RESPONSE",
+                httpStatusCode: error.status ?? axios_1.HttpStatusCode.InternalServerError,
+                // @ts-expect-error -- `error.response.headers` is always an `AxiosHeaders` instance.
+                requestId: error.response.headers.get("request-id"),
+                headers,
             });
         }
         if (error.code === axios_1.AxiosError.ECONNABORTED) {
@@ -27,8 +32,8 @@ function addErrorHandlingInterceptors(httpClient) {
                 message += ` (${error.config.timeout}ms)`;
             }
             throw new error_1.ConductorConnectionError({
-                code: error.code,
                 message,
+                code: error.code,
                 httpStatusCode: error.status ?? axios_1.HttpStatusCode.RequestTimeout,
             });
         }
@@ -36,8 +41,8 @@ function addErrorHandlingInterceptors(httpClient) {
         // Conductor API is offline) or an error ocurred when setting up the
         // request (e.g., no network connection).
         throw new error_1.ConductorConnectionError({
-            code: error.code ?? "NETWORK_ERROR",
             message: "An error occurred with our connection to Conductor.",
+            code: error.code ?? "NETWORK_ERROR",
             httpStatusCode: error.status,
         });
     });

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

@@ -0,0 +1,41 @@
+import BaseResource from "../resources/BaseResource";
+export interface EndUser {
+    /**
+     * The unique identifier for the object.
+     */
+    id: string;
+    /**
+     * Your end-user's unique ID in your database. Must be distinct from
+     * your other end-users.
+     */
+    sourceId: string;
+    /**
+     * Your end-user's email address for identification only. No emails will be
+     * sent.
+     */
+    email: string;
+    /**
+     * Your end-user's company name that will be shown elsewhere in Conductor.
+     */
+    name: string;
+    /**
+     * The time at which the object was created.
+     */
+    createdAt: string;
+}
+export type EndUserCreateInput = Pick<EndUser, "email" | "name" | "sourceId">;
+export default class EndUsersResource extends BaseResource {
+    protected readonly ROUTE = "/end-users";
+    /**
+     * Returns a list of your end-users.
+     */
+    list(): Promise<EndUser[]>;
+    /**
+     * Creates a new end-user.
+     */
+    create(input: EndUserCreateInput): Promise<EndUser>;
+    /**
+     * Retrieves the specified end-user.
+     */
+    retrieve(id: EndUser["id"]): Promise<EndUser>;
+}

package/dist/src/resources/EndUsersResource.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const BaseResource_1 = __importDefault(require("../resources/BaseResource"));
+class EndUsersResource extends BaseResource_1.default {
+    ROUTE = "/end-users";
+    /**
+     * Returns a list of your end-users.
+     */
+    async list() {
+        const { data } = await this.httpClient.get(this.ROUTE);
+        return data;
+    }
+    /**
+     * Creates a new end-user.
+     */
+    async create(input) {
+        const { data } = await this.httpClient.post(this.ROUTE, input);
+        return data;
+    }
+    /**
+     * Retrieves the specified end-user.
+     */
+    async retrieve(id) {
+        const { data } = await this.httpClient.get(`${this.ROUTE}/${id}`);
+        return data;
+    }
+}
+exports.default = EndUsersResource;

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

@@ -0,0 +1,50 @@
+import BaseResource from "../resources/BaseResource";
+export interface IntegrationConnectionAuthSession {
+    /**
+     * The unique identifier for the object.
+     */
+    id: string;
+    /**
+     * The ID of the end-user for whom to create an integration-connection in this
+     * auth session.
+     */
+    endUserId: string;
+    /**
+     * The value that you will pass to the client to launch the authentication flow.
+     */
+    clientSecret: string;
+    /**
+     * The URL to which to redirect the end-user to return to your app after
+     * completing the authentication flow.
+     */
+    returnUrl: string;
+    /**
+     * The time at which the auth-session expires.
+     */
+    expiresAt: string;
+}
+export interface IntegrationConnectionAuthSessionCreateInput {
+    /**
+     * The ID of the end-user for whom to create an integration-connection in this
+     * auth session.
+     */
+    endUserId: string;
+    /**
+     * The URL to which to redirect the end-user to return to your app after
+     * completing the authentication flow.
+     */
+    returnUrl: string;
+}
+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`.
+     */
+    create(input: IntegrationConnectionAuthSessionCreateInput): Promise<IntegrationConnectionAuthSession>;
+    /**
+     * Retrieves the specified integration-connection-auth-session.
+     */
+    retrieve(id: IntegrationConnectionAuthSession["id"]): Promise<IntegrationConnectionAuthSession>;
+}

package/dist/src/resources/IntegrationConnectionAuthSessionsResource.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+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`.
+     */
+    async create(input) {
+        const { data } = await this.httpClient.post(this.ROUTE, input);
+        return data;
+    }
+    /**
+     * Retrieves the specified integration-connection-auth-session.
+     */
+    async retrieve(id) {
+        const { data } = await this.httpClient.get(`${this.ROUTE}/${id}`);
+        return data;
+    }
+}
+exports.default = IntegrationConnectionAuthSessionsResource;

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

@@ -1,45 +1,67 @@
 import BaseResource from "../resources/BaseResource";
+import IntegrationConnectionAuthSessionsResource from "../resources/IntegrationConnectionAuthSessionsResource";
+import type { AxiosInstance } from "axios";
 export interface IntegrationConnection {
+    /**
+     * The unique identifier for the object.
+     */
     id: string;
+    /**
+     * The ID of the end-user who owns this integration-connection.
+     */
+    endUserId: string;
+    /**
+     * The identifier of the third-party platform to integrate (e.g.,
+     * "quickbooks-desktop").
+     */
+    integrationKey: string;
+    /**
+     * The time at which the object was created.
+     */
+    createdAt: string;
+}
+/**
+ * @deprecated We will soon remove this endpoint as we migrate to the new
+ * end-user + auth-session model.
+ */
+export interface IntegrationConnectionCreateInput {
+    /**
+     * The identifier of the third-party platform to integrate (e.g.,
+     * "quickbooks-desktop").
+     */
     integrationKey: string;
+    /**
+     * Your end-user's unique ID in your product's database. Must be distinct from
+     * your other connections for the same integration.
+     */
     endUserSourceId: string;
+    /**
+     * Your end-user's email address for identification only. No emails will be
+     * sent.
+     */
     endUserEmail: string;
+    /**
+     * Your end-user's company name that will be shown elsewhere in Conductor.
+     */
     endUserCompanyName: string;
 }
-export type CreateIntegrationConnectionInput = Pick<IntegrationConnection, "endUserCompanyName" | "endUserEmail" | "endUserSourceId" | "integrationKey">;
-export interface PingIntegrationConnectionOutput {
+export interface IntegrationConnectionPingOutput {
     duration: number;
 }
 export default class IntegrationConnectionsResource extends BaseResource {
+    readonly authSessions: IntegrationConnectionAuthSessionsResource;
     protected readonly ROUTE = "/integration-connections";
+    constructor(httpClient: AxiosInstance);
     /**
-     * Returns a list of all integration-connections associated with your
-     * Conductor account.
-     *
-     * @returns Your integration-connections.
+     * Returns a list of all integration-connections of all your end-users.
      */
     list(): Promise<IntegrationConnection[]>;
     /**
      * Creates a new integration-connection.
-     *
-     * @param input The input object to create the integration-connection.
-     * @param input.integrationKey The identifier of the third-party platform to
-     * integrate (e.g., "quickbooks-desktop").
-     * @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.
-     * @param input.endUserCompanyName Your end-user's company name that will be
-     * shown elsewhere in Conductor.
-     * @returns The newly created integration-connection.
-     */
-    create(input: CreateIntegrationConnectionInput): Promise<IntegrationConnection>;
+     */
+    create(input: IntegrationConnectionCreateInput): Promise<IntegrationConnection>;
     /**
      * Retrieves the specified integration-connection.
-     *
-     * @param id The integration-connection ID.
-     * @returns The integration-connection.
      */
     retrieve(id: IntegrationConnection["id"]): Promise<IntegrationConnection>;
     /**
@@ -55,5 +77,5 @@ export default class IntegrationConnectionsResource extends BaseResource {
      * @param id The integration-connection ID.
      * @returns The ping result with the duration in milliseconds.
      */
-    ping(id: IntegrationConnection["id"]): Promise<PingIntegrationConnectionOutput>;
+    ping(id: IntegrationConnection["id"]): Promise<IntegrationConnectionPingOutput>;
 }

package/dist/src/resources/IntegrationConnectionsResource.js

@@ -4,13 +4,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const BaseResource_1 = __importDefault(require("../resources/BaseResource"));
+const IntegrationConnectionAuthSessionsResource_1 = __importDefault(require("../resources/IntegrationConnectionAuthSessionsResource"));
 class IntegrationConnectionsResource extends BaseResource_1.default {
+    authSessions;
     ROUTE = "/integration-connections";
+    constructor(httpClient) {
+        super(httpClient);
+        this.authSessions = new IntegrationConnectionAuthSessionsResource_1.default(this.httpClient);
+    }
     /**
-     * Returns a list of all integration-connections associated with your
-     * Conductor account.
-     *
-     * @returns Your integration-connections.
+     * Returns a list of all integration-connections of all your end-users.
      */
     async list() {
         const { data } = await this.httpClient.get(this.ROUTE);
@@ -18,18 +21,6 @@ class IntegrationConnectionsResource extends BaseResource_1.default {
     }
     /**
      * Creates a new integration-connection.
-     *
-     * @param input The input object to create the integration-connection.
-     * @param input.integrationKey The identifier of the third-party platform to
-     * integrate (e.g., "quickbooks-desktop").
-     * @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.
-     * @param input.endUserCompanyName Your end-user's company name that will be
-     * shown elsewhere in Conductor.
-     * @returns The newly created integration-connection.
      */
     async create(input) {
         const { data } = await this.httpClient.post(this.ROUTE, input);
@@ -37,9 +28,6 @@ class IntegrationConnectionsResource extends BaseResource_1.default {
     }
     /**
      * Retrieves the specified integration-connection.
-     *
-     * @param id The integration-connection ID.
-     * @returns The integration-connection.
      */
     async retrieve(id) {
         const { data } = await this.httpClient.get(`${this.ROUTE}/${id}`);

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

@@ -1,23 +1,26 @@
 export declare const DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please try again later.";
 export interface ConductorErrorOptions {
+    readonly message: string;
+    readonly endUserMessage?: string;
     readonly type: string;
     readonly code: string;
     readonly httpStatusCode?: number | undefined;
-    readonly message: string;
-    readonly endUserMessage?: string;
     readonly integrationCode?: string | undefined;
+    readonly requestId?: string | undefined;
+    readonly headers?: Record<string, string>;
 }
 /**
  * The raw REST error response that Conductor's API returns.
  */
 export interface ConductorServerError {
     readonly error: {
+        readonly message: string;
+        readonly endUserMessage: string;
         readonly type: string;
         readonly code: string;
         readonly httpStatusCode: number;
-        readonly message: string;
-        readonly endUserMessage: string;
         readonly integrationCode?: string;
+        readonly requestId?: string;
     };
 }
 export declare function isWellFormedConductorServerError(error: unknown): error is ConductorServerError;
@@ -26,6 +29,21 @@ export declare function isWellFormedConductorServerError(error: unknown): error
  * Specifically for errors that Conductor's API returned.
  */
 export declare abstract class ConductorError extends Error {
+    /**
+     * The developer-friendly error message for your logs.
+     */
+    readonly message: string;
+    /**
+     * The end-user-friendly error message to display in your app's UI to your
+     * end-users.
+     *
+     * 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.".
+     */
+    readonly endUserMessage: string;
     /**
      * Categorizes the error.
      *
@@ -42,25 +60,9 @@ export declare abstract class ConductorError extends Error {
      */
     readonly code: string;
     /**
-     * The HTTP status code of the response that included the error. You probably
-     * won't need this.
+     * The HTTP status code of the response that included the error.
      */
     readonly httpStatusCode: number | undefined;
-    /**
-     * The developer-friendly error message for your logs.
-     */
-    readonly message: string;
-    /**
-     * The end-user-friendly error message to display in your app's UI to your
-     * end-users.
-     *
-     * 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.".
-     */
-    readonly endUserMessage: string;
     /**
      * The unique error code supplied by the third-party integration for errors
      * returned by the integration (i.e., `ConductorIntegrationError`) or
@@ -75,6 +77,17 @@ export declare abstract class ConductorError extends Error {
      * should not rely on this code to be the same across integrations.
      */
     readonly integrationCode: string | undefined;
+    /**
+     * The unique request identifier of the API request that caused the error.
+     *
+     * If you need to contact us about a specific request, providing the request
+     * identifier will ensure the fastest possible resolution.
+     */
+    readonly requestId: string | undefined;
+    /**
+     * The HTTP headers of the response that included the error.
+     */
+    readonly headers: Record<string, string> | undefined;
     /**
      * The internal representation of `type` for debugging.
      */
@@ -101,7 +114,7 @@ export declare class ConductorIntegrationError extends ConductorError {
 /**
  * Raised when a connection error occurs with the third-party integration on the
  * end-user's side. This typically indicates an issue with the end-user's
- * integration connection or configuration, which they must resolve. In other
+ * integration-connection or configuration, which they must resolve. In other
  * words, you cannot take action to fix these errors.
  *
  * E.g., QuickBooks Web Connector (QBWC) failed to connect to QuickBooks Desktop
@@ -130,6 +143,13 @@ export declare class ConductorAuthenticationError extends ConductorError {
     static readonly rawType = "AUTHENTICATION_ERROR";
     constructor(options: ConductorErrorOptionsWithoutType);
 }
+/**
+ * Raised when you attempt to access a resource that is not allowed.
+ */
+export declare class ConductorPermissionError extends ConductorError {
+    static readonly rawType = "PERMISSION_ERROR";
+    constructor(options: ConductorErrorOptionsWithoutType);
+}
 /**
  * Raised when there was a network problem between the client (on your server)
  * and Conductor's servers. E.g., a downed network or a bad TLS certificate.

package/dist/src/utils/error.js

@@ -1,17 +1,17 @@
 "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.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_END_USER_MESSAGE = void 0;
 // Matches server-side value.
 exports.DEFAULT_END_USER_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.type === "string" &&
         typeof error.error.code === "string" &&
-        typeof error.error.httpStatusCode === "number" &&
-        typeof error.error.message === "string" &&
-        typeof error.error.endUserMessage === "string");
+        typeof error.error.httpStatusCode === "number");
 }
 exports.isWellFormedConductorServerError = isWellFormedConductorServerError;
 /**
@@ -19,6 +19,21 @@ exports.isWellFormedConductorServerError = isWellFormedConductorServerError;
  * Specifically for errors that Conductor's API returned.
  */
 class ConductorError extends Error {
+    /**
+     * The developer-friendly error message for your logs.
+     */
+    message;
+    /**
+     * The end-user-friendly error message to display in your app's UI to your
+     * end-users.
+     *
+     * 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.".
+     */
+    endUserMessage;
     /**
      * Categorizes the error.
      *
@@ -35,25 +50,9 @@ class ConductorError extends Error {
      */
     code;
     /**
-     * The HTTP status code of the response that included the error. You probably
-     * won't need this.
+     * The HTTP status code of the response that included the error.
      */
     httpStatusCode;
-    /**
-     * The developer-friendly error message for your logs.
-     */
-    message;
-    /**
-     * The end-user-friendly error message to display in your app's UI to your
-     * end-users.
-     *
-     * 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.".
-     */
-    endUserMessage;
     /**
      * The unique error code supplied by the third-party integration for errors
      * returned by the integration (i.e., `ConductorIntegrationError`) or
@@ -68,6 +67,17 @@ class ConductorError extends Error {
      * should not rely on this code to be the same across integrations.
      */
     integrationCode;
+    /**
+     * The unique request identifier of the API request that caused the error.
+     *
+     * If you need to contact us about a specific request, providing the request
+     * identifier will ensure the fastest possible resolution.
+     */
+    requestId;
+    /**
+     * The HTTP headers of the response that included the error.
+     */
+    headers;
     /**
      * The internal representation of `type` for debugging.
      */
@@ -86,12 +96,14 @@ class ConductorError extends Error {
         //    `ConductorError` always have the correct `type` even if they are
         //    instantiated with the wrong options.
         this.type = this.constructor.name;
-        this.rawType = options.type;
-        this.code = options.code;
-        this.httpStatusCode = options.httpStatusCode;
         this.message = options.message;
         this.endUserMessage = options.endUserMessage ?? exports.DEFAULT_END_USER_MESSAGE;
+        this.code = options.code;
+        this.httpStatusCode = options.httpStatusCode;
         this.integrationCode = options.integrationCode;
+        this.requestId = options.requestId;
+        this.headers = options.headers;
+        this.rawType = options.type;
     }
 }
 exports.ConductorError = ConductorError;
@@ -117,7 +129,7 @@ exports.ConductorIntegrationError = ConductorIntegrationError;
 /**
  * Raised when a connection error occurs with the third-party integration on the
  * end-user's side. This typically indicates an issue with the end-user's
- * integration connection or configuration, which they must resolve. In other
+ * integration-connection or configuration, which they must resolve. In other
  * words, you cannot take action to fix these errors.
  *
  * E.g., QuickBooks Web Connector (QBWC) failed to connect to QuickBooks Desktop
@@ -155,6 +167,16 @@ class ConductorAuthenticationError extends ConductorError {
     }
 }
 exports.ConductorAuthenticationError = ConductorAuthenticationError;
+/**
+ * Raised when you attempt to access a resource that is not allowed.
+ */
+class ConductorPermissionError extends ConductorError {
+    static rawType = "PERMISSION_ERROR";
+    constructor(options) {
+        super({ ...options, type: ConductorPermissionError.rawType });
+    }
+}
+exports.ConductorPermissionError = ConductorPermissionError;
 /**
  * Raised when there was a network problem between the client (on your server)
  * and Conductor's servers. E.g., a downed network or a bad TLS certificate.
@@ -202,6 +224,9 @@ function generateConductorErrorFromType(options) {
         case ConductorAuthenticationError.rawType: {
             return new ConductorAuthenticationError(options);
         }
+        case ConductorPermissionError.rawType: {
+            return new ConductorPermissionError(options);
+        }
         case ConductorConnectionError.rawType: {
             return new ConductorConnectionError(options);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conductor-node",
-  "version": "10.0.2",
+  "version": "10.2.0",
   "description": "Easily integrate the entire QuickBooks Desktop API using fully-typed async TypeScript",
   "license": "MIT",
   "type": "commonjs",