conductor-node 10.5.3 → 10.5.4
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 +1 -1
- package/dist/src/resources/EndUsersResource.d.ts +1 -1
- package/dist/src/resources/EndUsersResource.js +1 -1
- package/dist/src/utils/error.d.ts +8 -8
- package/dist/src/utils/error.js +11 -11
- 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
|
@@ -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
|
-
|
|
2453
|
+
userFacingMessage: "No response received from QuickBooks Desktop.",
|
|
2454
2454
|
code: "QBD_NO_RESPONSE",
|
|
2455
2455
|
});
|
|
2456
2456
|
}
|
|
@@ -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.
|
|
@@ -1,11 +1,11 @@
|
|
|
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
4
|
/**
|
|
5
|
-
* @deprecated Use `
|
|
5
|
+
* @deprecated Use `userFacingMessage` instead.
|
|
6
6
|
*/
|
|
7
7
|
readonly endUserMessage?: string;
|
|
8
|
-
readonly
|
|
8
|
+
readonly userFacingMessage?: string;
|
|
9
9
|
readonly type: string;
|
|
10
10
|
readonly code: string;
|
|
11
11
|
readonly httpStatusCode?: number | undefined;
|
|
@@ -20,10 +20,10 @@ export interface ConductorServerError {
|
|
|
20
20
|
readonly error: {
|
|
21
21
|
readonly message: string;
|
|
22
22
|
/**
|
|
23
|
-
* @deprecated Use `
|
|
23
|
+
* @deprecated Use `userFacingMessage` instead.
|
|
24
24
|
*/
|
|
25
25
|
readonly endUserMessage?: string;
|
|
26
|
-
readonly
|
|
26
|
+
readonly userFacingMessage: string;
|
|
27
27
|
readonly type: string;
|
|
28
28
|
readonly code: string;
|
|
29
29
|
readonly httpStatusCode: number;
|
|
@@ -38,11 +38,11 @@ export declare function isWellFormedConductorServerError(error: unknown): error
|
|
|
38
38
|
*/
|
|
39
39
|
export declare abstract class ConductorError extends Error {
|
|
40
40
|
/**
|
|
41
|
-
* The developer
|
|
41
|
+
* The developer error message for your logs.
|
|
42
42
|
*/
|
|
43
43
|
readonly message: string;
|
|
44
44
|
/**
|
|
45
|
-
* @deprecated Use `
|
|
45
|
+
* @deprecated Use `userFacingMessage` instead.
|
|
46
46
|
*/
|
|
47
47
|
readonly endUserMessage: string;
|
|
48
48
|
/**
|
|
@@ -55,7 +55,7 @@ export declare abstract class ConductorError extends Error {
|
|
|
55
55
|
* this message will just say "An internal server error occurred. Please try
|
|
56
56
|
* again later.".
|
|
57
57
|
*/
|
|
58
|
-
readonly
|
|
58
|
+
readonly userFacingMessage: string;
|
|
59
59
|
/**
|
|
60
60
|
* Categorizes the error.
|
|
61
61
|
*
|
package/dist/src/utils/error.js
CHANGED
|
@@ -1,15 +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
11
|
(typeof error.error.endUserMessage === "string" ||
|
|
12
|
-
typeof error.error.
|
|
12
|
+
typeof error.error.userFacingMessage ===
|
|
13
13
|
"string") &&
|
|
14
14
|
typeof error.error.type === "string" &&
|
|
15
15
|
typeof error.error.code === "string" &&
|
|
@@ -22,11 +22,11 @@ exports.isWellFormedConductorServerError = isWellFormedConductorServerError;
|
|
|
22
22
|
*/
|
|
23
23
|
class ConductorError extends Error {
|
|
24
24
|
/**
|
|
25
|
-
* The developer
|
|
25
|
+
* The developer error message for your logs.
|
|
26
26
|
*/
|
|
27
27
|
message;
|
|
28
28
|
/**
|
|
29
|
-
* @deprecated Use `
|
|
29
|
+
* @deprecated Use `userFacingMessage` instead.
|
|
30
30
|
*/
|
|
31
31
|
endUserMessage;
|
|
32
32
|
/**
|
|
@@ -39,7 +39,7 @@ class ConductorError extends Error {
|
|
|
39
39
|
* this message will just say "An internal server error occurred. Please try
|
|
40
40
|
* again later.".
|
|
41
41
|
*/
|
|
42
|
-
|
|
42
|
+
userFacingMessage;
|
|
43
43
|
/**
|
|
44
44
|
* Categorizes the error.
|
|
45
45
|
*
|
|
@@ -105,12 +105,12 @@ class ConductorError extends Error {
|
|
|
105
105
|
this.message = options.message;
|
|
106
106
|
this.endUserMessage =
|
|
107
107
|
options.endUserMessage ??
|
|
108
|
-
options.
|
|
109
|
-
exports.
|
|
110
|
-
this.
|
|
111
|
-
options.
|
|
108
|
+
options.userFacingMessage ??
|
|
109
|
+
exports.DEFAULT_USER_FACING_MESSAGE;
|
|
110
|
+
this.userFacingMessage =
|
|
111
|
+
options.userFacingMessage ??
|
|
112
112
|
options.endUserMessage ??
|
|
113
|
-
exports.
|
|
113
|
+
exports.DEFAULT_USER_FACING_MESSAGE;
|
|
114
114
|
this.code = options.code;
|
|
115
115
|
this.httpStatusCode = options.httpStatusCode;
|
|
116
116
|
this.integrationCode = options.integrationCode;
|