conductor-node 10.5.3 → 10.5.5
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.
- package/README.md +16 -16
- package/dist/package.json +1 -1
- package/dist/src/integrations/qbd/QbdIntegration.js +4 -1
- package/dist/src/resources/EndUsersResource.d.ts +1 -1
- package/dist/src/resources/EndUsersResource.js +1 -1
- package/dist/src/resources/IntegrationConnectionsResource.js +1 -0
- package/dist/src/utils/error.d.ts +5 -17
- package/dist/src/utils/error.js +8 -19
- 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 strongly recommend displaying the property `error.
|
|
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.userFacingMessage` 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.
|
|
110
|
+
// Update your app's UI to display `error.userFacingMessage`.
|
|
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.
|
|
121
|
+
// Update your app's UI to display `error.userFacingMessage`.
|
|
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
|
|
162
|
-
|
|
|
163
|
-
| `message`
|
|
164
|
-
| `
|
|
165
|
-
| `type`
|
|
166
|
-
| `code`
|
|
167
|
-
| `httpStatusCode`
|
|
168
|
-
| `integrationCode`
|
|
169
|
-
| `requestId`
|
|
170
|
-
| `headers`
|
|
161
|
+
| Property | Type | Description |
|
|
162
|
+
| ------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
163
|
+
| `message` | `string` | The developer error message for your logs. |
|
|
164
|
+
| `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.". |
|
|
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.
|
|
233
|
+
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.
|
|
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.
|
|
257
|
+
res.status(500).send({ error: { message: error.userFacingMessage } });
|
|
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.
|
|
290
|
+
message: origError.userFacingMessage,
|
|
291
291
|
};
|
|
292
292
|
}
|
|
293
293
|
// ...
|
package/dist/package.json
CHANGED
|
@@ -2443,6 +2443,9 @@ class QbdIntegration extends BaseIntegration_1.default {
|
|
|
2443
2443
|
query: async (endUserId, params) => this.sendRequestWrapper(endUserId, { WorkersCompCodeQueryRq: params }, "WorkersCompCodeQueryRs", "WorkersCompCodeRet"),
|
|
2444
2444
|
};
|
|
2445
2445
|
async sendRequestWrapper(endUserId, params, responseWrapperKey, responseBodyKey) {
|
|
2446
|
+
if (endUserId.startsWith("int_conn")) {
|
|
2447
|
+
console.warn("Deprecation warning: `int_conn` Conductor ID format used. Support for this format will be removed in a future release. Please use the new `end_usr` format.");
|
|
2448
|
+
}
|
|
2446
2449
|
const response = (endUserId.startsWith("int_conn")
|
|
2447
2450
|
? await this.sendRequestDeprecated(endUserId, params)
|
|
2448
2451
|
: await this.sendRequest(endUserId, "quickbooks-desktop", params));
|
|
@@ -2450,7 +2453,7 @@ class QbdIntegration extends BaseIntegration_1.default {
|
|
|
2450
2453
|
if (responseBody === undefined) {
|
|
2451
2454
|
throw new error_1.ConductorIntegrationError({
|
|
2452
2455
|
message: "No response received from QuickBooks Desktop.",
|
|
2453
|
-
|
|
2456
|
+
userFacingMessage: "No response received from QuickBooks Desktop.",
|
|
2454
2457
|
code: "QBD_NO_RESPONSE",
|
|
2455
2458
|
});
|
|
2456
2459
|
}
|
|
@@ -48,7 +48,7 @@ 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
|
-
* strongly recommend displaying the property `error.
|
|
51
|
+
* strongly recommend displaying the property `error.userFacingMessage` to
|
|
52
52
|
* your end-user in your app's UI.
|
|
53
53
|
*
|
|
54
54
|
* @param endUserId The ID of the end-user to ping.
|
|
@@ -34,7 +34,7 @@ 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
|
-
* strongly recommend displaying the property `error.
|
|
37
|
+
* strongly recommend displaying the property `error.userFacingMessage` to
|
|
38
38
|
* your end-user in your app's UI.
|
|
39
39
|
*
|
|
40
40
|
* @param endUserId The ID of the end-user to ping.
|
|
@@ -50,6 +50,7 @@ class IntegrationConnectionsResource extends BaseResource_1.default {
|
|
|
50
50
|
*/
|
|
51
51
|
async ping(id) {
|
|
52
52
|
if (id.startsWith("int_conn")) {
|
|
53
|
+
console.warn("Deprecation warning: `int_conn` Conductor ID format used. Support for this format will be removed in a future release. Please use the new `end_usr` format.");
|
|
53
54
|
const { data } = await this.httpClient.get(`${this.ROUTE}/${id}/ping`);
|
|
54
55
|
return data;
|
|
55
56
|
}
|
|
@@ -1,11 +1,7 @@
|
|
|
1
|
-
export declare const
|
|
1
|
+
export declare const DEFAULT_USER_FACING_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
|
-
*/
|
|
7
|
-
readonly endUserMessage?: string;
|
|
8
|
-
readonly userFriendlyMessage?: string;
|
|
4
|
+
readonly userFacingMessage?: string;
|
|
9
5
|
readonly type: string;
|
|
10
6
|
readonly code: string;
|
|
11
7
|
readonly httpStatusCode?: number | undefined;
|
|
@@ -19,11 +15,7 @@ export interface ConductorErrorOptions {
|
|
|
19
15
|
export interface ConductorServerError {
|
|
20
16
|
readonly error: {
|
|
21
17
|
readonly message: string;
|
|
22
|
-
|
|
23
|
-
* @deprecated Use `userFriendlyMessage` instead.
|
|
24
|
-
*/
|
|
25
|
-
readonly endUserMessage?: string;
|
|
26
|
-
readonly userFriendlyMessage: string;
|
|
18
|
+
readonly userFacingMessage: string;
|
|
27
19
|
readonly type: string;
|
|
28
20
|
readonly code: string;
|
|
29
21
|
readonly httpStatusCode: number;
|
|
@@ -38,13 +30,9 @@ export declare function isWellFormedConductorServerError(error: unknown): error
|
|
|
38
30
|
*/
|
|
39
31
|
export declare abstract class ConductorError extends Error {
|
|
40
32
|
/**
|
|
41
|
-
* The developer
|
|
33
|
+
* The developer error message for your logs.
|
|
42
34
|
*/
|
|
43
35
|
readonly message: string;
|
|
44
|
-
/**
|
|
45
|
-
* @deprecated Use `userFriendlyMessage` instead.
|
|
46
|
-
*/
|
|
47
|
-
readonly endUserMessage: string;
|
|
48
36
|
/**
|
|
49
37
|
* The user-friendly error message, written specifically for displaying to
|
|
50
38
|
* your end-users in your app's UI.
|
|
@@ -55,7 +43,7 @@ export declare abstract class ConductorError extends Error {
|
|
|
55
43
|
* this message will just say "An internal server error occurred. Please try
|
|
56
44
|
* again later.".
|
|
57
45
|
*/
|
|
58
|
-
readonly
|
|
46
|
+
readonly userFacingMessage: string;
|
|
59
47
|
/**
|
|
60
48
|
* Categorizes the error.
|
|
61
49
|
*
|
package/dist/src/utils/error.js
CHANGED
|
@@ -1,16 +1,15 @@
|
|
|
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.
|
|
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_FACING_MESSAGE = void 0;
|
|
5
5
|
// Matches server-side value.
|
|
6
|
-
exports.
|
|
6
|
+
exports.DEFAULT_USER_FACING_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
|
-
|
|
12
|
-
|
|
13
|
-
"string") &&
|
|
11
|
+
typeof error.error.userFacingMessage ===
|
|
12
|
+
"string" &&
|
|
14
13
|
typeof error.error.type === "string" &&
|
|
15
14
|
typeof error.error.code === "string" &&
|
|
16
15
|
typeof error.error.httpStatusCode === "number");
|
|
@@ -22,13 +21,9 @@ exports.isWellFormedConductorServerError = isWellFormedConductorServerError;
|
|
|
22
21
|
*/
|
|
23
22
|
class ConductorError extends Error {
|
|
24
23
|
/**
|
|
25
|
-
* The developer
|
|
24
|
+
* The developer error message for your logs.
|
|
26
25
|
*/
|
|
27
26
|
message;
|
|
28
|
-
/**
|
|
29
|
-
* @deprecated Use `userFriendlyMessage` instead.
|
|
30
|
-
*/
|
|
31
|
-
endUserMessage;
|
|
32
27
|
/**
|
|
33
28
|
* The user-friendly error message, written specifically for displaying to
|
|
34
29
|
* your end-users in your app's UI.
|
|
@@ -39,7 +34,7 @@ class ConductorError extends Error {
|
|
|
39
34
|
* this message will just say "An internal server error occurred. Please try
|
|
40
35
|
* again later.".
|
|
41
36
|
*/
|
|
42
|
-
|
|
37
|
+
userFacingMessage;
|
|
43
38
|
/**
|
|
44
39
|
* Categorizes the error.
|
|
45
40
|
*
|
|
@@ -103,14 +98,8 @@ class ConductorError extends Error {
|
|
|
103
98
|
// instantiated with the wrong options.
|
|
104
99
|
this.type = this.constructor.name;
|
|
105
100
|
this.message = options.message;
|
|
106
|
-
this.
|
|
107
|
-
options.
|
|
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
|
+
this.userFacingMessage =
|
|
102
|
+
options.userFacingMessage ?? exports.DEFAULT_USER_FACING_MESSAGE;
|
|
114
103
|
this.code = options.code;
|
|
115
104
|
this.httpStatusCode = options.httpStatusCode;
|
|
116
105
|
this.integrationCode = options.integrationCode;
|