conductor-node 11.0.3 → 11.0.5

package/README.md

@@ -1,28 +1,9 @@
 # [Conductor](https://conductor.is/) - The best QuickBooks Desktop integration on the planet
 
-Execute _any_ read or write [QuickBooks Desktop API](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop) through async TypeScript and receive a fully-typed response.
+Execute _any_ read or write QuickBooks Desktop API through async TypeScript and receive a fully-typed response.
 
 <!-- markdownlint-disable MD033 -->
-<img src="https://user-images.githubusercontent.com/170023/213273732-83dd6881-0b36-4787-820b-bd55cdc8444f.jpg" alt="qbd" width="600"/>
-
-## Table of Contents
-
-1. [Requirements](#requirements)
-2. [Installation](#installation)
-3. [Usage](#usage)
-4. [APIs](#apis)
-5. [TypeScript](#typescript)
-6. [Error Handling](#error-handling)
-
-## Requirements
-
-1. A Conductor API key. Please visit [our website](https://conductor.is/) to join the private beta.
-
-## Installation
-
-```sh
-yarn add conductor-node
-```
+<img src="https://user-images.githubusercontent.com/170023/213273732-83dd6881-0b36-4787-820b-bd55cdc8444f.jpg" alt="QuickBooks Desktop autocomplete" width="600"/>
 
 ## Usage
 
@@ -30,12 +11,12 @@ yarn add conductor-node
 import Conductor from "conductor-node";
 
 // Instantiate `Conductor` with your account's secret key.
-const conductor = new Conductor("sk_test_...");
+const conductor = new Conductor("{{YOUR_SECRET_KEY}}");
 
-// Fetch all authorized end-users.
+// Fetch all authorized EndUsers.
 const endUsers = await conductor.endUsers.list();
 
-// Execute any QBD API against your end-user.
+// Execute any QBD API against your EndUser.
 const newAccount = await conductor.qbd.account.add(endUsers[0].id, {
   Name: "Test Account",
   AccountType: "Bank",
@@ -43,251 +24,9 @@ const newAccount = await conductor.qbd.account.add(endUsers[0].id, {
 });
 ```
 
-## APIs
-
-### `qbd.*`
-
-Executes any QuickBooks Desktop (QBD) API against the specified end-user. See the official [QuickBooks Desktop API Reference](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop) for a complete list of available APIs.
-
-```ts
-const qbdAccount = await conductor.qbd.account.add(endUserId, {
-  Name: "Test Account",
-  AccountType: "Bank",
-  OpenBalance: "100",
-});
-```
-
-### `endUsers.create(input: EndUserCreateInput)`
-
-Creates a new end-user.
-
-```ts
-const newEndUser = await conductor.endUsers.create({
-  // Your end-user's unique ID in *your* database. Must be
-  // distinct from your other end-users.
-  sourceId: "1234-abcd",
-  // Your end-user's email address.
-  email: "danny@constructionco.com",
-  // Your end-user's company name shown elsewhere in Conductor.
-  name: "Construction Corp",
-});
-```
-
-The response looks like the following:
-
-```ts
-{
-  // ❗ Save this `id` to your database for executing requests to this
-  // end-user's integration(s) in the future.
-  id: 'end_usr_1234abcd',
-  sourceId: "1234-abcd",
-  email: 'danny@construction.com',
-  name: 'Construction Corp',
-}
-```
-
-### `endUsers.list()`
-
-Returns a list of all end-users associated with your Conductor account.
-
-```ts
-const endUsers = await conductor.endUsers.list();
-```
-
-### `endUsers.retrieve(id: string)`
-
-Retrieves the specified end-User.
-
-```ts
-const endUser = await conductor.endUsers.retrieve(endUserId);
-```
-
-### `endUsers.ping(id: string, integrationSlug: string)`
-
-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 strongly recommend displaying the property `error.userFacingMessage` to your end-user in your app's UI.
-
-Using `async`/`await`:
-
-```ts
-try {
-  await conductor.endUsers.ping(endUserId, "quickbooks-desktop");
-} catch (error) {
-  if (error instanceof ConductorError) {
-    // Update your app's UI to display `error.userFacingMessage`.
-  }
-  // ...
-}
-```
-
-Or in the form of a rejected promise:
-
-```ts
-conductor.endUsers.ping(endUserId, "quickbooks-desktop").catch((error) => {
-  if (error instanceof ConductorError) {
-    // Update your app's UI to display `error.userFacingMessage`.
-  }
-  // ...
-});
-```
-
-## TypeScript
-
-Access the entire QuickBooks Desktop API through TypeScript. The `qbd.*` APIs are fully typed with inline documentation and will autocomplete in your editor.
-
-To access the QBD types directly, import them from `conductor-node` like so:
-
-```ts
-import { QbdTypes } from "conductor-node";
-
-const accountAddInput: QbdTypes.AccountAdd = {
-  Name: "Test Account",
-  AccountType: "Bank",
-  OpenBalance: "100",
-};
-```
-
-## Error Handling
-
-### `ConductorError`
-
-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 error message for your logs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `userFacingMessage` | `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
-
-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_ triggering alerts 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.)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-
-### Specific Error Handling
-
-If you need special handling for specific errors, you can wrap individual API calls, as shown below.
-
-Using `async`/`await`:
-
-```ts
-try {
-  const newAccount = await conductor.qbd.account.add(endUserId, {
-    Name: "Test Account",
-    AccountType: "Bank",
-    OpenBalance: "100",
-  });
-} catch (error) {
-  if (error instanceof ConductorError) {
-    // Check `error.code`, `error.integrationCode`, etc., for special handling.
-  } else {
-    // ...
-  }
-}
-```
-
-Or in the form of a rejected promise:
-
-```ts
-conductor.qbd.account
-  .add(endUserId, {
-    Name: "Test Account",
-    AccountType: "Bank",
-    OpenBalance: "100",
-  })
-  .then((newAccount) => {
-    // ...
-  })
-  .catch((error) => {
-    if (error instanceof ConductorError) {
-      // Check `error.code`, `error.integrationCode`, etc., for special handling.
-    } else {
-      // ...
-    }
-  });
-```
-
-### Global Error Handling
-
-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.userFacingMessage` 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.
-
-For example, using an [Express error handler](https://expressjs.com/en/guide/error-handling.html#writing-error-handlers):
-
-```ts
-import * as Sentry from "@sentry/node";
-import {
-  ConductorError,
-  ConductorIntegrationConnectionError,
-} from "conductor-node";
-// ...
-app.use((error, req, res, next) => {
-  if (error instanceof ConductorError) {
-    Sentry.captureException(error, {
-      level:
-        error instanceof ConductorIntegrationConnectionError
-          ? "warning"
-          : "error",
-    });
-    // Return a different error message for your end-user to see in your
-    // app's UI.
-    res.status(500).send({ error: { message: error.userFacingMessage } });
-  } else {
-    // ...
-  }
-});
-```
-
-Or using [Apollo Server's error handler](https://apollographql.com/docs/apollo-server/data/errors/#for-client-responses):
+## Documentation
 
-```ts
-import { ApolloServer } from "@apollo/server";
-import { unwrapResolverError } from "@apollo/server/errors";
-import * as Sentry from "@sentry/node";
-import {
-  ConductorError,
-  ConductorIntegrationConnectionError,
-} from "conductor-node";
-// ...
-const server = new ApolloServer({
-  // ...
-  formatError: (formattedError, error) => {
-    const origError = unwrapResolverError(error);
-    if (origError instanceof ConductorError) {
-      Sentry.captureException(origError, {
-        level:
-          origError instanceof ConductorIntegrationConnectionError
-            ? "warning"
-            : "error",
-      });
-      return {
-        ...formattedError,
-        // Return a different error message for your end-user to see in
-        // your app's UI.
-        message: origError.userFacingMessage,
-      };
-    }
-    // ...
-    return formattedError;
-  },
-});
-```
+1. [Getting Started](https://docs.conductor.is/getting-started)
+2. [API Reference](https://docs.conductor.is/apis)
+3. [QuickBooks Desktop](https://docs.conductor.is/quickbooks-desktop)
+4. [Error Handling](https://docs.conductor.is/error-handling)

package/dist/package.json

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

package/dist/src/Client.d.ts

@@ -1,17 +1,17 @@
 import QbdIntegration from "./integrations/qbd/QbdIntegration";
+import AuthSessionsResource from "./resources/AuthSessionsResource";
 import EndUsersResource from "./resources/EndUsersResource";
 import IntegrationConnectionsResource from "./resources/IntegrationConnectionsResource";
-import { getServerUrlForEnvironment } from "./utils/http";
 export interface ClientOptions {
     /**
      * 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;
+    readonly authSessions: AuthSessionsResource;
     /**
      * Executes any QuickBooks Desktop (QBD) API against the specified end-user.
      * See the official [QuickBooks Desktop API
@@ -20,7 +20,7 @@ export default class Client {
      */
     readonly qbd: QbdIntegration;
     private readonly httpClient;
-    constructor(apiKey: string, { verbose, serverEnvironment }?: ClientOptions);
+    constructor(apiKey: string, { verbose }?: ClientOptions);
     private createHttpClient;
     private createHeaders;
 }

package/dist/src/Client.js

@@ -7,6 +7,7 @@ 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 AuthSessionsResource_1 = __importDefault(require("./resources/AuthSessionsResource"));
 const EndUsersResource_1 = __importDefault(require("./resources/EndUsersResource"));
 const IntegrationConnectionsResource_1 = __importDefault(require("./resources/IntegrationConnectionsResource"));
 const checkForUpdates_1 = require("./utils/checkForUpdates");
@@ -15,6 +16,7 @@ const axios_1 = __importDefault(require("axios"));
 class Client {
     endUsers;
     integrationConnections;
+    authSessions;
     /**
      * Executes any QuickBooks Desktop (QBD) API against the specified end-user.
      * See the official [QuickBooks Desktop API
@@ -23,16 +25,17 @@ class Client {
      */
     qbd;
     httpClient;
-    constructor(apiKey, { verbose = false, serverEnvironment = "production" } = {}) {
+    constructor(apiKey, { verbose = false } = {}) {
         (0, checkForUpdates_1.checkForUpdates)();
-        this.httpClient = this.createHttpClient(apiKey, verbose, serverEnvironment);
+        this.httpClient = this.createHttpClient(apiKey, verbose);
         this.endUsers = new EndUsersResource_1.default(this.httpClient);
         this.integrationConnections = new IntegrationConnectionsResource_1.default(this.httpClient);
+        this.authSessions = new AuthSessionsResource_1.default(this.httpClient);
         this.qbd = new QbdIntegration_1.default(this.httpClient);
     }
-    createHttpClient(apiKey, verbose, serverEnvironment) {
+    createHttpClient(apiKey, verbose) {
         const httpClient = axios_1.default.create({
-            baseURL: `${(0, http_1.getServerUrlForEnvironment)(serverEnvironment)}/v1`,
+            baseURL: `${(0, http_1.getApiServerUrlForEnvironment)()}/v1`,
             headers: this.createHeaders(apiKey),
             timeout: 0, // No timeout (default).
         });

package/dist/src/integrations/BaseIntegration.js

@@ -7,7 +7,7 @@ class BaseIntegration {
     }
     /** Not intended for public use. */
     async sendRequest(endUserId, integrationSlug, payload) {
-        const { data } = await this.httpClient.post(`/end-users/${endUserId}/send-request/${integrationSlug}`, payload);
+        const { data } = await this.httpClient.post(`/end_users/${endUserId}/request/${integrationSlug}`, payload);
         return data;
     }
 }

package/dist/src/interceptors/errorHandling.js

@@ -12,6 +12,8 @@ function addErrorHandlingInterceptors(httpClient) {
             const errorData = error.response.data;
             if ((0, error_1.isWellFormedConductorServerError)(errorData)) {
                 throw (0, error_1.generateConductorErrorFromType)({
+                    // The request ID is already in the response body, so no need to
+                    // copy it from the headers.
                     ...errorData.error,
                     httpStatusCode: error.response.status,
                     headers,
@@ -21,9 +23,12 @@ function addErrorHandlingInterceptors(httpClient) {
                 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.
+                // @ts-expect-error -- `error.response.headers` always exists as an `AxiosHeaders` instance.
                 requestId: error.response.headers.get("request-id"),
                 headers,
+                // Include to understand why `isWellFormedConductorServerError()`
+                // failed.
+                raw: errorData,
             });
         }
         if (error.code === axios_1.AxiosError.ECONNABORTED) {
@@ -41,7 +46,7 @@ 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({
-            message: "An error occurred with our connection to Conductor.",
+            message: `An error occurred with our connection to Conductor: ${error.message}`,
             code: error.code ?? "NETWORK_ERROR",
             httpStatusCode: error.status,
         });

package/dist/src/interceptors/logging.js

@@ -24,7 +24,9 @@ function addLoggingInterceptors(httpClient, verbose) {
         // NOTE: We cannot include duration because we lack access to
         // `AxiosError.config` because we already wrapped the error.
         if (verbose) {
-            console.log("Conductor error:", stringifyForLogs(error));
+            // No prefix "Conductor error:" because the error already includes a
+            // prefix (e.g., `ConductorConnectionError`).
+            console.log(stringifyForLogs(error));
         }
         throw error;
     });

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

@@ -0,0 +1,52 @@
+import BaseResource from "../resources/BaseResource";
+export interface AuthSession {
+    /**
+     * The unique identifier for the object.
+     */
+    readonly id: string;
+    /**
+     * The ID of the EndUser for whom to create an IntegrationConnection in this
+     * AuthSession.
+     */
+    readonly endUserId: string;
+    /**
+     * The value that you will pass to the client to launch the authentication
+     * flow.
+     */
+    readonly clientSecret: string;
+    /**
+     * The time at which this AuthSession expires.
+     */
+    readonly expiresAt: string;
+}
+export interface AuthSessionCreateInput {
+    /**
+     * Your Conductor publishable key, which we use to create the session's
+     * `authUrl`.
+     */
+    readonly publishableKey: string;
+    /**
+     * The ID of the EndUser for whom to create the IntegrationConnection.
+     */
+    readonly endUserId: string;
+}
+export interface AuthSessionCreateOutput extends AuthSession {
+    /**
+     * The URL of the authentication flow for the specified EndUser to set up the
+     * IntegrationConnection.
+     */
+    readonly authUrl: string;
+}
+export default class AuthSessionsResource extends BaseResource {
+    protected readonly ROUTE = "/auth_sessions";
+    /**
+     * Creates an AuthSession for launching the client-side IntegrationConnection
+     * authentication flow. Use the returned session’s `clientSecret` to launch
+     * the auth flow using Conductor.js.
+     */
+    create(input: AuthSessionCreateInput): Promise<AuthSessionCreateOutput>;
+    /**
+     * Retrieves the specified AuthSession.
+     */
+    retrieve(id: AuthSession["id"]): Promise<AuthSession>;
+}

package/dist/src/resources/{IntegrationConnectionAuthSessionsResource.js → AuthSessionsResource.js}

@@ -4,23 +4,23 @@ var __importDefault = (this && this.__importDefault) || function (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";
+class AuthSessionsResource extends BaseResource_1.default {
+    ROUTE = "/auth_sessions";
     /**
-     * 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.
+     * Creates an AuthSession for launching the client-side IntegrationConnection
+     * 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);
         return data;
     }
     /**
-     * Retrieves the specified integration-connection-auth-session.
+     * Retrieves the specified AuthSession.
      */
     async retrieve(id) {
         const { data } = await this.httpClient.get(`${this.ROUTE}/${id}`);
         return data;
     }
 }
-exports.default = IntegrationConnectionAuthSessionsResource;
+exports.default = AuthSessionsResource;

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

@@ -25,24 +25,27 @@ export interface EndUser {
 }
 export type EndUserCreateInput = Pick<EndUser, "email" | "name" | "sourceId">;
 export interface EndUserPingOutput {
+    /**
+     * The time, in milliseconds, that it took to ping the connection.
+     */
     readonly duration: number;
 }
 export default class EndUsersResource extends BaseResource {
-    protected readonly ROUTE = "/end-users";
+    protected readonly ROUTE = "/end_users";
     /**
-     * Returns a list of your end-users.
+     * Returns a list of your EndUsers.
      */
     list(): Promise<EndUser[]>;
     /**
-     * Creates a new end-user.
+     * Creates a new EndUser.
      */
     create(input: EndUserCreateInput): Promise<EndUser>;
     /**
-     * Retrieves the specified end-user.
+     * Retrieves the specified EndUser.
      */
     retrieve(id: EndUser["id"]): Promise<EndUser>;
     /**
-     * Checks whether the specified integration-connection can connect and process
+     * Checks whether the specified IntegrationConnection can connect and process
      * requests end-to-end.
      *
      * If the connection fails, the error we encountered will be thrown as a
@@ -52,8 +55,8 @@ export default class EndUsersResource extends BaseResource {
      * your end-user in your app's UI.
      *
      * @param id The ID of the end-user to ping.
-     * @param integrationSlug The integration identifier for the
-     * integration-connection to ping.
+     * @param integrationSlug The integration identifier for the end-user's
+     * connection you want to ping (e.g. "quickbooks-desktop").
      * @returns The ping result with the duration in milliseconds.
      */
     ping(id: EndUser["id"], integrationSlug: IntegrationSlug): Promise<EndUserPingOutput>;

package/dist/src/resources/EndUsersResource.js

@@ -5,30 +5,30 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const BaseResource_1 = __importDefault(require("../resources/BaseResource"));
 class EndUsersResource extends BaseResource_1.default {
-    ROUTE = "/end-users";
+    ROUTE = "/end_users";
     /**
-     * Returns a list of your end-users.
+     * Returns a list of your EndUsers.
      */
     async list() {
         const { data } = await this.httpClient.get(this.ROUTE);
         return data;
     }
     /**
-     * Creates a new end-user.
+     * Creates a new EndUser.
      */
     async create(input) {
         const { data } = await this.httpClient.post(this.ROUTE, input);
         return data;
     }
     /**
-     * Retrieves the specified end-user.
+     * Retrieves the specified EndUser.
      */
     async retrieve(id) {
         const { data } = await this.httpClient.get(`${this.ROUTE}/${id}`);
         return data;
     }
     /**
-     * Checks whether the specified integration-connection can connect and process
+     * Checks whether the specified IntegrationConnection can connect and process
      * requests end-to-end.
      *
      * If the connection fails, the error we encountered will be thrown as a
@@ -38,8 +38,8 @@ class EndUsersResource extends BaseResource_1.default {
      * your end-user in your app's UI.
      *
      * @param id The ID of the end-user to ping.
-     * @param integrationSlug The integration identifier for the
-     * integration-connection to ping.
+     * @param integrationSlug The integration identifier for the end-user's
+     * connection you want to ping (e.g. "quickbooks-desktop").
      * @returns The ping result with the duration in milliseconds.
      */
     async ping(id, integrationSlug) {

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

@@ -1,6 +1,4 @@
 import BaseResource from "../resources/BaseResource";
-import IntegrationConnectionAuthSessionsResource from "../resources/IntegrationConnectionAuthSessionsResource";
-import type { AxiosInstance } from "axios";
 export type IntegrationSlug = "quickbooks-desktop";
 export interface IntegrationConnection {
     /**
@@ -8,7 +6,7 @@ export interface IntegrationConnection {
      */
     readonly id: string;
     /**
-     * The ID of the end-user who owns this integration-connection.
+     * The ID of the EndUser who owns this IntegrationConnection.
      */
     readonly endUserId: string;
     /**
@@ -25,15 +23,13 @@ export interface IntegrationConnectionPingOutput {
     readonly duration: number;
 }
 export default class IntegrationConnectionsResource extends BaseResource {
-    readonly authSessions: IntegrationConnectionAuthSessionsResource;
-    protected readonly ROUTE = "/integration-connections";
-    constructor(httpClient: AxiosInstance);
+    protected readonly ROUTE = "/integration_connections";
     /**
-     * Returns a list of all integration-connections of all your end-users.
+     * Returns a list of all IntegrationConnections of all your EndUsers.
      */
     list(): Promise<IntegrationConnection[]>;
     /**
-     * Retrieves the specified integration-connection.
+     * Retrieves the specified IntegrationConnection.
      */
     retrieve(id: IntegrationConnection["id"]): Promise<IntegrationConnection>;
 }

package/dist/src/resources/IntegrationConnectionsResource.js

@@ -4,23 +4,17 @@ 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);
-    }
+    ROUTE = "/integration_connections";
     /**
-     * Returns a list of all integration-connections of all your end-users.
+     * Returns a list of all IntegrationConnections of all your EndUsers.
      */
     async list() {
         const { data } = await this.httpClient.get(this.ROUTE);
         return data;
     }
     /**
-     * Retrieves the specified integration-connection.
+     * Retrieves the specified IntegrationConnection.
      */
     async retrieve(id) {
         const { data } = await this.httpClient.get(`${this.ROUTE}/${id}`);

package/dist/src/utils/checkForUpdates.js

@@ -7,6 +7,9 @@ exports.checkForUpdates = void 0;
 const package_json_1 = __importDefault(require("../../package.json"));
 const node_child_process_1 = __importDefault(require("node:child_process"));
 function checkForUpdates() {
+    if (process.env.NODE_ENV === "test") {
+        return;
+    }
     // Exit early if npm is not installed.
     try {
         node_child_process_1.default.execSync("which npm");

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

@@ -8,6 +8,7 @@ export interface ConductorErrorOptions {
     readonly integrationCode?: string | undefined;
     readonly requestId?: string | undefined;
     readonly headers?: Record<string, string>;
+    readonly raw?: unknown;
 }
 /**
  * The raw REST error response that Conductor's API returns.
@@ -89,7 +90,11 @@ export declare abstract class ConductorError extends Error {
      */
     readonly headers: Record<string, string> | undefined;
     /**
-     * The internal representation of `type` for debugging.
+     * The raw REST error response that Conductor's API returned.
+     */
+    protected readonly raw: unknown;
+    /**
+     * Conductor's internal representation of `type` for debugging.
      */
     protected readonly rawType: string;
     constructor(options: ConductorErrorOptions);
@@ -114,7 +119,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
+ * IntegrationConnection 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

package/dist/src/utils/error.js

@@ -80,7 +80,11 @@ class ConductorError extends Error {
      */
     headers;
     /**
-     * The internal representation of `type` for debugging.
+     * The raw REST error response that Conductor's API returned.
+     */
+    raw;
+    /**
+     * Conductor's internal representation of `type` for debugging.
      */
     rawType;
     constructor(options) {
@@ -105,6 +109,10 @@ class ConductorError extends Error {
         this.integrationCode = options.integrationCode;
         this.requestId = options.requestId;
         this.headers = options.headers;
+        // Only set `raw` if provided instead of always setting it to `options`
+        // because the latter is usually a near duplicate of `this`, which we don't
+        // want to log unless necessary.
+        this.raw = options.raw;
         this.rawType = options.type;
     }
 }
@@ -131,7 +139,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
+ * IntegrationConnection 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

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

@@ -1 +1 @@
-export declare function getServerUrlForEnvironment(environment: "development" | "production" | "test"): string;
+export declare function getApiServerUrlForEnvironment(): string;

package/dist/src/utils/http.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getServerUrlForEnvironment = void 0;
-function getServerUrlForEnvironment(environment) {
-    if (environment === "production") {
-        return "https://api.conductor.is";
+exports.getApiServerUrlForEnvironment = void 0;
+function getApiServerUrlForEnvironment() {
+    // Do not check if `NODE_ENV` is "production" because that requires the
+    // developer to have set `NODE_ENV` to use `conductor` as expected.
+    if (["development", "test"].includes(process.env.NODE_ENV)) {
+        return "http://localhost:4000";
     }
-    return "http://localhost:4000";
+    return "https://api.conductor.is";
 }
-exports.getServerUrlForEnvironment = getServerUrlForEnvironment;
+exports.getApiServerUrlForEnvironment = getApiServerUrlForEnvironment;

package/package.json

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

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

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