conductor-node 10.1.0 → 10.2.0

package/README.md

@@ -92,9 +92,8 @@ The response looks like the following:
 Retrieves the specified integration-connection.
 
 ```ts
-const qbdConnection = await conductor.integrationConnections.retrieve(
-  qbdConnectionId,
-);
+const qbdConnection =
+  await conductor.integrationConnections.retrieve(qbdConnectionId);
 ```
 
 ### `integrationConnections.ping(id: string)`
@@ -179,9 +178,10 @@ The error object you receive will have one of the following error types:
 | Name                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `ConductorIntegrationError`           | Raised when the third-party integration encounters an error while processing the end-user's request. This often results from an issue with the request or data handling that requires your attention to resolve.<br><br>E.g., a `ListID` you provided was not found in QuickBooks Desktop, or an accounting value you supplied did not adhere to the integration's accounting rules.<br><br>Refer to `error.integrationCode` for the error code returned by the integration, if available.                                                                                                                                                                                                               |
-| `ConductorIntegrationConnectionError` | 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 words, you cannot take action to fix these errors.<br><br>E.g., QuickBooks Web Connector (QBWC) failed to connect to QuickBooks Desktop on the end-user's computer.<br><br>Refer to `error.integrationCode` for the error code returned by the integration connector, if available.<br><br>❗ We recommend _not_ alerting your team for these errors because only the end-user can fix them. See [Global Error Handling](#global-error-handling) for an example of this. |
+| `ConductorIntegrationConnectionError` | 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 words, you cannot take action to fix these errors.<br><br>E.g., QuickBooks Web Connector (QBWC) failed to connect to QuickBooks Desktop on the end-user's computer.<br><br>Refer to `error.integrationCode` for the error code returned by the integration connector, if available.<br><br>❗ We recommend _not_ alerting your team for these errors because only the end-user can fix them. See [Global Error Handling](#global-error-handling) for an example of this. |
 | `ConductorInvalidRequestError`        | Raised when you make an API call with the wrong parameters, in the wrong state, or in an invalid way.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `ConductorAuthenticationError`        | Raised when Conductor cannot authenticate you with the credentials you provided. E.g., an incorrect API key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `ConductorPermissionError`            | Raised when you attempt to access a resource that is not allowed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `ConductorConnectionError`            | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `ConductorInternalError`              | Raised when something went wrong on Conductor's end. (These are rare.)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 

package/dist/package.json

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

package/dist/src/Client.d.ts

@@ -1,12 +1,16 @@
 import QbdIntegration from "./integrations/qbd/QbdIntegration";
+import EndUsersResource from "./resources/EndUsersResource";
 import IntegrationConnectionsResource from "./resources/IntegrationConnectionsResource";
 import { getServerUrlForEnvironment } from "./utils/http";
 export interface ClientOptions {
-    /** Logs each request, response, and error. */
+    /**
+     * Enables logging each request, response, and error.
+     */
     readonly verbose?: boolean;
     readonly serverEnvironment?: Parameters<typeof getServerUrlForEnvironment>[0];
 }
 export default class Client {
+    readonly endUsers: EndUsersResource;
     readonly integrationConnections: IntegrationConnectionsResource;
     /** QuickBooks Desktop integration. */
     readonly qbd: QbdIntegration;

package/dist/src/Client.js

@@ -7,11 +7,13 @@ const package_json_1 = __importDefault(require("./../package.json"));
 const QbdIntegration_1 = __importDefault(require("./integrations/qbd/QbdIntegration"));
 const errorHandling_1 = require("./interceptors/errorHandling");
 const logging_1 = require("./interceptors/logging");
+const EndUsersResource_1 = __importDefault(require("./resources/EndUsersResource"));
 const IntegrationConnectionsResource_1 = __importDefault(require("./resources/IntegrationConnectionsResource"));
 const checkForUpdates_1 = require("./utils/checkForUpdates");
 const http_1 = require("./utils/http");
 const axios_1 = __importDefault(require("axios"));
 class Client {
+    endUsers;
     integrationConnections;
     /** QuickBooks Desktop integration. */
     qbd;
@@ -19,6 +21,7 @@ class Client {
     constructor(apiKey, { verbose = false, serverEnvironment = "production" } = {}) {
         (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.qbd = new QbdIntegration_1.default(this.httpClient);
     }

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

@@ -114,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
@@ -143,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,7 +1,7 @@
 "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) {
@@ -129,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
@@ -167,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.
@@ -214,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.1.0",
+  "version": "10.2.0",
   "description": "Easily integrate the entire QuickBooks Desktop API using fully-typed async TypeScript",
   "license": "MIT",
   "type": "commonjs",