conductor-node 10.5.1 → 10.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +16 -16
  2. package/dist/package.json +1 -1
  3. package/dist/src/integrations/qbd/QbdIntegration.js +1 -1
  4. package/dist/src/resources/EndUsersResource.d.ts +2 -2
  5. package/dist/src/resources/EndUsersResource.js +2 -2
  6. package/dist/src/resources/IntegrationConnectionsResource.d.ts +3 -17
  7. package/dist/src/resources/IntegrationConnectionsResource.js +2 -16
  8. package/dist/src/utils/error.d.ts +17 -5
  9. package/dist/src/utils/error.js +20 -7
  10. package/package.json +1 -1
package/README.md CHANGED
@@ -98,7 +98,7 @@ const qbdConnection =
98
98
 
99
99
  Checks whether the specified integration-connection can connect and process requests end-to-end.
100
100
 
101
- If the connection fails, the error we encountered will be thrown as a [`ConductorError`](#error-handling) (like any request). This information is useful for showing a "connection status" indicator in your app. If an error occurs, we recommend displaying the property `error.endUserMessage` to your end-user in your app's UI.
101
+ If the connection fails, the error we encountered will be thrown as a [`ConductorError`](#error-handling) (like any request). This information is useful for showing a "connection status" indicator in your app. If an error occurs, we strongly recommend displaying the property `error.userFriendlyMessage` to your end-user in your app's UI.
102
102
 
103
103
  Using `async`/`await`:
104
104
 
@@ -107,7 +107,7 @@ try {
107
107
  await conductor.integrationConnections.ping(qbdConnectionId);
108
108
  } catch (error) {
109
109
  if (error instanceof ConductorError) {
110
- // Update your app's UI to display `error.endUserMessage`.
110
+ // Update your app's UI to display `error.userFriendlyMessage`.
111
111
  }
112
112
  // ...
113
113
  }
@@ -118,7 +118,7 @@ Or in the form of a rejected promise:
118
118
  ```ts
119
119
  conductor.integrationConnections.ping(qbdConnectionId).catch((error) => {
120
120
  if (error instanceof ConductorError) {
121
- // Update your app's UI to display `error.endUserMessage`.
121
+ // Update your app's UI to display `error.userFriendlyMessage`.
122
122
  }
123
123
  // ...
124
124
  });
@@ -158,16 +158,16 @@ const accountAddInput: QbdTypes.AccountAdd = {
158
158
 
159
159
  All errors thrown by the Conductor API are instances of `ConductorError` or its subclasses. These errors have the following properties:
160
160
 
161
- | Property | Type | Description |
162
- | ----------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
163
- | `message` | `string` | The developer-friendly error message for your logs. |
164
- | `endUserMessage` | `string` | The end-user-friendly error message to display in your app's UI to your end-users.<br><br>This value exists for _every_ error. E.g., for a QBD connection error, it might recommend the end-user to check that their QuickBooks Desktop is open and that they're logged in. But if a Conductor API key is expired, e.g., this message will just say "An internal server error occurred. Please try again later.". |
165
- | `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"`. |
166
- | `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. |
167
- | `httpStatusCode` | `number` or `undefined` | The HTTP status code of the response that included the error. |
168
- | `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. |
169
- | `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. |
170
- | `headers` | `object` or `undefined` | The headers of the response that included the error. |
161
+ | Property | Type | Description |
162
+ | --------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
163
+ | `message` | `string` | The developer-friendly error message for your logs. |
164
+ | `userFriendlyMessage` | `string` | The user-friendly error message, written specifically for displaying to your end-users in your app's UI.<br><br>This value exists for _every_ error. E.g., for a QBD connection error, it might recommend the end-user to check that their QuickBooks Desktop is open and that they're logged in. But if a Conductor API key is expired, e.g., this message will just say "An internal server error occurred. Please try again later.". |
165
+ | `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"`. |
166
+ | `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. |
167
+ | `httpStatusCode` | `number` or `undefined` | The HTTP status code of the response that included the error. |
168
+ | `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. |
169
+ | `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. |
170
+ | `headers` | `object` or `undefined` | The headers of the response that included the error. |
171
171
 
172
172
  ### Error Types
173
173
 
@@ -230,7 +230,7 @@ conductor.qbd.account
230
230
 
231
231
  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:
232
232
 
233
- 1. For any `ConductorError` instance, display the `error.endUserMessage` property to the end-user in your app's UI while logging the complete error object.
233
+ 1. For any `ConductorError` instance, display the `error.userFriendlyMessage` property to the end-user in your app's UI while logging the complete error object.
234
234
  2. For all `ConductorError` instances, transmit the full error object to your error-tracking service (e.g., Sentry):
235
235
  - 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.
236
236
  - Send an **error** for all other `ConductorError` instances, such as an invalid API key.
@@ -254,7 +254,7 @@ app.use((error, req, res, next) => {
254
254
  });
255
255
  // Return a different error message for your end-user to see in your
256
256
  // app's UI.
257
- res.status(500).send({ error: { message: error.endUserMessage } });
257
+ res.status(500).send({ error: { message: error.userFriendlyMessage } });
258
258
  } else {
259
259
  // ...
260
260
  }
@@ -287,7 +287,7 @@ const server = new ApolloServer({
287
287
  ...formattedError,
288
288
  // Return a different error message for your end-user to see in
289
289
  // your app's UI.
290
- message: origError.endUserMessage,
290
+ message: origError.userFriendlyMessage,
291
291
  };
292
292
  }
293
293
  // ...
package/dist/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "conductor-node",
3
- "version": "10.5.1",
3
+ "version": "10.5.3",
4
4
  "description": "Easily integrate the entire QuickBooks Desktop API using fully-typed async TypeScript",
5
5
  "keywords": [
6
6
  "QuickBooks Desktop",
package/dist/src/integrations/qbd/QbdIntegration.js CHANGED
@@ -2450,7 +2450,7 @@ class QbdIntegration extends BaseIntegration_1.default {
2450
2450
  if (responseBody === undefined) {
2451
2451
  throw new error_1.ConductorIntegrationError({
2452
2452
  message: "No response received from QuickBooks Desktop.",
2453
- endUserMessage: "No response received from QuickBooks Desktop.",
2453
+ userFriendlyMessage: "No response received from QuickBooks Desktop.",
2454
2454
  code: "QBD_NO_RESPONSE",
2455
2455
  });
2456
2456
  }
package/dist/src/resources/EndUsersResource.d.ts CHANGED
@@ -48,8 +48,8 @@ export default class EndUsersResource extends BaseResource {
48
48
  * If the connection fails, the error we encountered will be thrown as a
49
49
  * `ConductorError` (like any request). This information is useful for showing
50
50
  * a "connection status" indicator in your app. If an error occurs, we
51
- * recommend displaying the property `error.endUserMessage` to your end-user
52
- * in your app's UI.
51
+ * strongly recommend displaying the property `error.userFriendlyMessage` to
52
+ * your end-user in your app's UI.
53
53
  *
54
54
  * @param endUserId The ID of the end-user to ping.
55
55
  * @param integrationSlug The integration identifier for the
package/dist/src/resources/EndUsersResource.js CHANGED
@@ -34,8 +34,8 @@ class EndUsersResource extends BaseResource_1.default {
34
34
  * If the connection fails, the error we encountered will be thrown as a
35
35
  * `ConductorError` (like any request). This information is useful for showing
36
36
  * a "connection status" indicator in your app. If an error occurs, we
37
- * recommend displaying the property `error.endUserMessage` to your end-user
38
- * in your app's UI.
37
+ * strongly recommend displaying the property `error.userFriendlyMessage` to
38
+ * your end-user in your app's UI.
39
39
  *
40
40
  * @param endUserId The ID of the end-user to ping.
41
41
  * @param integrationSlug The integration identifier for the
package/dist/src/resources/IntegrationConnectionsResource.d.ts CHANGED
@@ -22,7 +22,7 @@ export interface IntegrationConnection {
22
22
  createdAt: string;
23
23
  }
24
24
  /**
25
- * @deprecated Instead use `conductor.endUsers.create()`.
25
+ * @deprecated Use `conductor.endUsers.create()` instead.
26
26
  */
27
27
  export interface IntegrationConnectionCreateOldInput {
28
28
  /**
@@ -57,9 +57,7 @@ export default class IntegrationConnectionsResource extends BaseResource {
57
57
  */
58
58
  list(): Promise<IntegrationConnection[]>;
59
59
  /**
60
- * Creates a new integration-connection.
61
- *
62
- * @deprecated Instead use `conductor.endUsers.create({ ... })`.
60
+ * @deprecated Use `conductor.endUsers.create({ ... })` instead.
63
61
  */
64
62
  create(input: IntegrationConnectionCreateOldInput): Promise<IntegrationConnection>;
65
63
  /**
@@ -67,19 +65,7 @@ export default class IntegrationConnectionsResource extends BaseResource {
67
65
  */
68
66
  retrieve(id: IntegrationConnection["id"]): Promise<IntegrationConnection>;
69
67
  /**
70
- * Checks whether the specified integration-connection can connect and process
71
- * requests end-to-end.
72
- *
73
- * If the connection fails, the error we encountered will be thrown as a
74
- * `ConductorError` (like any request). This information is useful for showing
75
- * a "connection status" indicator in your app. If an error occurs, we
76
- * recommend displaying the property `error.endUserMessage` to your end-user
77
- * in your app's UI.
78
- *
79
- * @param id The integration-connection ID.
80
- * @returns The ping result with the duration in milliseconds.
81
- *
82
- * @deprecated Instead use `conductor.endUsers.ping(id, "quickbooks-desktop")`.
68
+ * @deprecated Use `conductor.endUsers.ping(id, "quickbooks-desktop")` instead.
83
69
  */
84
70
  ping(id: IntegrationConnection["id"]): Promise<IntegrationConnectionPingOutput>;
85
71
  }
package/dist/src/resources/IntegrationConnectionsResource.js CHANGED
@@ -23,9 +23,7 @@ class IntegrationConnectionsResource extends BaseResource_1.default {
23
23
  return data;
24
24
  }
25
25
  /**
26
- * Creates a new integration-connection.
27
- *
28
- * @deprecated Instead use `conductor.endUsers.create({ ... })`.
26
+ * @deprecated Use `conductor.endUsers.create({ ... })` instead.
29
27
  */
30
28
  async create(input) {
31
29
  const endUser = await this.client.endUsers.create({
@@ -48,19 +46,7 @@ class IntegrationConnectionsResource extends BaseResource_1.default {
48
46
  return data;
49
47
  }
50
48
  /**
51
- * Checks whether the specified integration-connection can connect and process
52
- * requests end-to-end.
53
- *
54
- * If the connection fails, the error we encountered will be thrown as a
55
- * `ConductorError` (like any request). This information is useful for showing
56
- * a "connection status" indicator in your app. If an error occurs, we
57
- * recommend displaying the property `error.endUserMessage` to your end-user
58
- * in your app's UI.
59
- *
60
- * @param id The integration-connection ID.
61
- * @returns The ping result with the duration in milliseconds.
62
- *
63
- * @deprecated Instead use `conductor.endUsers.ping(id, "quickbooks-desktop")`.
49
+ * @deprecated Use `conductor.endUsers.ping(id, "quickbooks-desktop")` instead.
64
50
  */
65
51
  async ping(id) {
66
52
  if (id.startsWith("int_conn")) {
package/dist/src/utils/error.d.ts CHANGED
@@ -1,7 +1,11 @@
1
- export declare const DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please try again later.";
1
+ export declare const DEFAULT_USER_FRIENDLY_MESSAGE = "An internal server error occurred. Please try again later.";
2
2
  export interface ConductorErrorOptions {
3
3
  readonly message: string;
4
+ /**
5
+ * @deprecated Use `userFriendlyMessage` instead.
6
+ */
4
7
  readonly endUserMessage?: string;
8
+ readonly userFriendlyMessage?: string;
5
9
  readonly type: string;
6
10
  readonly code: string;
7
11
  readonly httpStatusCode?: number | undefined;
@@ -15,7 +19,11 @@ export interface ConductorErrorOptions {
15
19
  export interface ConductorServerError {
16
20
  readonly error: {
17
21
  readonly message: string;
18
- readonly endUserMessage: string;
22
+ /**
23
+ * @deprecated Use `userFriendlyMessage` instead.
24
+ */
25
+ readonly endUserMessage?: string;
26
+ readonly userFriendlyMessage: string;
19
27
  readonly type: string;
20
28
  readonly code: string;
21
29
  readonly httpStatusCode: number;
@@ -34,8 +42,12 @@ export declare abstract class ConductorError extends Error {
34
42
  */
35
43
  readonly message: string;
36
44
  /**
37
- * The end-user-friendly error message to display in your app's UI to your
38
- * end-users.
45
+ * @deprecated Use `userFriendlyMessage` instead.
46
+ */
47
+ readonly endUserMessage: string;
48
+ /**
49
+ * The user-friendly error message, written specifically for displaying to
50
+ * your end-users in your app's UI.
39
51
  *
40
52
  * This value exists for *every* error. E.g., for a QBD connection error, it
41
53
  * might recommend the end-user to check that their QuickBooks Desktop is open
@@ -43,7 +55,7 @@ export declare abstract class ConductorError extends Error {
43
55
  * this message will just say "An internal server error occurred. Please try
44
56
  * again later.".
45
57
  */
46
- readonly endUserMessage: string;
58
+ readonly userFriendlyMessage: string;
47
59
  /**
48
60
  * Categorizes the error.
49
61
  *
package/dist/src/utils/error.js CHANGED
@@ -1,14 +1,16 @@
1
1
  "use strict";
2
2
  /* eslint-disable max-classes-per-file -- Use one module for all error classes. */
3
3
  Object.defineProperty(exports, "__esModule", { value: true });
4
- 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;
4
+ exports.generateConductorErrorFromType = exports.ConductorUnknownError = exports.ConductorInternalError = exports.ConductorConnectionError = exports.ConductorPermissionError = exports.ConductorAuthenticationError = exports.ConductorInvalidRequestError = exports.ConductorIntegrationConnectionError = exports.ConductorIntegrationError = exports.ConductorError = exports.isWellFormedConductorServerError = exports.DEFAULT_USER_FRIENDLY_MESSAGE = void 0;
5
5
  // Matches server-side value.
6
- exports.DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please try again later.";
6
+ exports.DEFAULT_USER_FRIENDLY_MESSAGE = "An internal server error occurred. Please try again later.";
7
7
  function isWellFormedConductorServerError(error) {
8
8
  return (error instanceof Object &&
9
9
  typeof error.error === "object" &&
10
10
  typeof error.error.message === "string" &&
11
- typeof error.error.endUserMessage === "string" &&
11
+ (typeof error.error.endUserMessage === "string" ||
12
+ typeof error.error.userFriendlyMessage ===
13
+ "string") &&
12
14
  typeof error.error.type === "string" &&
13
15
  typeof error.error.code === "string" &&
14
16
  typeof error.error.httpStatusCode === "number");
@@ -24,8 +26,12 @@ class ConductorError extends Error {
24
26
  */
25
27
  message;
26
28
  /**
27
- * The end-user-friendly error message to display in your app's UI to your
28
- * end-users.
29
+ * @deprecated Use `userFriendlyMessage` instead.
30
+ */
31
+ endUserMessage;
32
+ /**
33
+ * The user-friendly error message, written specifically for displaying to
34
+ * your end-users in your app's UI.
29
35
  *
30
36
  * This value exists for *every* error. E.g., for a QBD connection error, it
31
37
  * might recommend the end-user to check that their QuickBooks Desktop is open
@@ -33,7 +39,7 @@ class ConductorError extends Error {
33
39
  * this message will just say "An internal server error occurred. Please try
34
40
  * again later.".
35
41
  */
36
- endUserMessage;
42
+ userFriendlyMessage;
37
43
  /**
38
44
  * Categorizes the error.
39
45
  *
@@ -97,7 +103,14 @@ class ConductorError extends Error {
97
103
  // instantiated with the wrong options.
98
104
  this.type = this.constructor.name;
99
105
  this.message = options.message;
100
- this.endUserMessage = options.endUserMessage ?? exports.DEFAULT_END_USER_MESSAGE;
106
+ this.endUserMessage =
107
+ options.endUserMessage ??
108
+ options.userFriendlyMessage ??
109
+ exports.DEFAULT_USER_FRIENDLY_MESSAGE;
110
+ this.userFriendlyMessage =
111
+ options.userFriendlyMessage ??
112
+ options.endUserMessage ??
113
+ exports.DEFAULT_USER_FRIENDLY_MESSAGE;
101
114
  this.code = options.code;
102
115
  this.httpStatusCode = options.httpStatusCode;
103
116
  this.integrationCode = options.integrationCode;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "conductor-node",
3
- "version": "10.5.1",
3
+ "version": "10.5.3",
4
4
  "description": "Easily integrate the entire QuickBooks Desktop API using fully-typed async TypeScript",
5
5
  "keywords": [
6
6
  "QuickBooks Desktop",