conductor-node 8.6.3 → 8.6.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.
Files changed (5) hide show
  1. package/README.md +16 -21
  2. package/dist/package.json +1 -1
  3. package/dist/src/errors.d.ts +32 -14
  4. package/dist/src/errors.js +33 -15
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -158,27 +158,20 @@ const accountAddInput: QbdTypes.AccountAdd = {
158
158
 
159
159
  ## Error Handling
160
160
 
161
- Any error thrown by the Conductor API will be an instance of `ConductorError` or one of its subclasses, which all have the following properties:
161
+ ### `ConductorError`
162
162
 
163
- ```ts
164
- {
165
- // The error type.
166
- type: string;
167
- // The unique error code. This is useful for adding special handling
168
- // for specific errors.
169
- code: string;
170
- // The developer error message for your logs.
171
- message: string;
172
- // The end-user-friendly error message to display in your app.
173
- endUserMessage: string;
174
- // The error code provided by the third-party integration when `type`
175
- // is `ConductorIntegrationError`. This is useful for adding special
176
- // handling for specific errors from the third-party integration.
177
- integrationCode: string | undefined;
178
- // The HTTP status code of the response that included the error.
179
- httpStatusCode: number | undefined;
180
- }
181
- ```
163
+ Any and every error thrown by the Conductor API will be an instance of `ConductorError` or one of its subclasses, which all have the following properties:
164
+
165
+ | Property | Type | Description |
166
+ | ----------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
167
+ | `type` | `string` | The error type, which 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"`. |
168
+ | `code` | `string` | The unique error code from Conductor, which is useful for adding special handling for specific errors. E.g., `"INTEGRATION_CONNECTION_MISSING"`, `"API_KEY_INVALID"`, or `"QBD_REQUEST_ERROR"`.<br><br>By comparison, `type` is more general and categorizes the error. |
169
+ | `message` | `string` | The developer-friendly error message for your logs. |
170
+ | `endUserMessage` | `string` | The end-user-friendly error message to display in your app's UI for your end-user to see.<br><br>This value exists for _every_ error. E.g., if it's 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, this message will just say "An internal server error occurred. Please try again later.". |
171
+ | `integrationCode` | `string` or `undefined` | The unique error code supplied by the third-party integration for errors that come from the integration (i.e., instances of `ConductorIntegrationError`). This is useful for adding special handling for specific errors from the third-party integration.<br><br>E.g., QuickBooks Desktop might return an error with `integrationCode` for something specific to its accounting logic. The integration's corresponding message for this code would be in `error.message`.<br><br>The third-party integration's error codes are not standardized, so you should not rely on this code to be the same across integrations. |
172
+ | `httpStatusCode` | `number` or `undefined` | The HTTP status code of the response that included the error. You probably won't need this. |
173
+
174
+ _Would any additional error properties be helpful?_ Let me know. Some potential additions: `request` for the original API request, `integrationKey` (e.g., `"quickbooks-desktop"`), or `integrationConnectionId`.
182
175
 
183
176
  ### Error Types
184
177
 
@@ -192,7 +185,7 @@ The error object you receive will have one of the following error types:
192
185
  | `ConductorConnectionError` | There was a network problem between the client (on your server) and Conductor's servers. |
193
186
  | `ConductorInternalError` | Something went wrong on Conductor's end. (These are rare.) |
194
187
 
195
- ### Special Handling
188
+ ### Specific Error Handling
196
189
 
197
190
  If you need special handling for specific errors, you can wrap individual API calls, as shown below.
198
191
 
@@ -292,3 +285,5 @@ const server = new ApolloServer({
292
285
  },
293
286
  });
294
287
  ```
288
+
289
+ NOTE: In writing this, I realize that you might want to be alerted for integration errors unrelated to connections, such as QBD failing for accounting reasons. Perhaps I'll add the error type `ConductorIntegrationConnectionError` in the future.
package/dist/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "conductor-node",
3
- "version": "8.6.3",
3
+ "version": "8.6.5",
4
4
  "description": "Easily integrate with the entire QuickBooks Desktop API with fully-typed async TypeScript",
5
5
  "author": "Danny Nemer <hi@DannyNemer.com>",
6
6
  "license": "MIT",
package/dist/src/errors.d.ts CHANGED
@@ -20,40 +20,58 @@ export interface ConductorRawGraphqlError {
20
20
  */
21
21
  export declare class ConductorError extends Error {
22
22
  /**
23
- * The error type.
23
+ * The error type, which categorizes the error.
24
+ *
25
+ * This value is the same as the subclass name. E.g.,
26
+ * `"ConductorIntegrationError"` or `"ConductorInvalidRequestError"`.
24
27
  */
25
28
  readonly type: string;
26
29
  /**
27
- * The raw error type for internal debugging.
28
- */
29
- readonly rawType: string;
30
- /**
31
- * The unique error code. This is useful for adding special handling
32
- * for specific errors.
30
+ * The unique error code from Conductor, which is useful for adding special
31
+ * handling for specific errors. E.g., `"INTEGRATION_CONNECTION_MISSING"`,
32
+ * `"API_KEY_INVALID"`, or `"QBD_REQUEST_ERROR"`.
33
+ *
34
+ * By comparison, `type` is more general and categorizes the error.
33
35
  */
34
36
  readonly code: string;
35
37
  /**
36
38
  * The developer-friendly error message for your logs.
37
- *
38
- * (Defined in the base class but documented here for completeness.)
39
39
  */
40
+ readonly message: string;
40
41
  /**
41
- * The end-user-friendly error message to display in your app.
42
+ * The end-user-friendly error message to display in your app's UI for your
43
+ * end-user to see.
44
+ *
45
+ * This value exists for *every* error. E.g., if it's a QBD connection error,
46
+ * it might recommend the end-user to check that their QuickBooks Desktop is
47
+ * open and that they're logged in. But if a Conductor API key is expired,
48
+ * this message will just say "An internal server error occurred. Please try
49
+ * again later.".
42
50
  */
43
51
  readonly endUserMessage: string;
44
52
  /**
45
- * The error code provided by the third-party integration when `type` is
46
- * `ConductorIntegrationError`. This is useful for adding special handling for
47
- * specific errors from the third-party integration.
53
+ * The unique error code supplied by the third-party integration for errors
54
+ * that come from the integration (i.e., instances of
55
+ * `ConductorIntegrationError`). This is useful for adding special handling
56
+ * for specific errors from the third-party integration.
57
+ *
58
+ * E.g., QuickBooks Desktop might return an error with `integrationCode` for
59
+ * something specific to its accounting logic. The integration's corresponding
60
+ * message for this code would be in `error.message`.
48
61
  *
49
62
  * The third-party integration's error codes are not standardized, so you
50
63
  * should not rely on this code to be the same across integrations.
51
64
  */
52
65
  readonly integrationCode: string | undefined;
53
66
  /**
54
- * The HTTP status code of the response that included the error.
67
+ * The HTTP status code of the response that included the error. You probably
68
+ * won't need this.
55
69
  */
56
70
  readonly httpStatusCode: number | undefined;
71
+ /**
72
+ * The internal representation of `type` for debugging.
73
+ */
74
+ protected readonly rawType: string;
57
75
  protected constructor(options: ConductorErrorOptions);
58
76
  }
59
77
  type ConductorErrorOptionsWithoutType = Omit<ConductorErrorOptions, "type">;
package/dist/src/errors.js CHANGED
@@ -9,41 +9,58 @@ exports.DEFAULT_END_USER_MESSAGE = "An internal server error occurred. Please tr
9
9
  */
10
10
  class ConductorError extends Error {
11
11
  /**
12
- * The error type.
12
+ * The error type, which categorizes the error.
13
+ *
14
+ * This value is the same as the subclass name. E.g.,
15
+ * `"ConductorIntegrationError"` or `"ConductorInvalidRequestError"`.
13
16
  */
14
17
  type;
15
18
  /**
16
- * The raw error type for internal debugging.
17
- */
18
- rawType;
19
- /**
20
- * The unique error code. This is useful for adding special handling
21
- * for specific errors.
19
+ * The unique error code from Conductor, which is useful for adding special
20
+ * handling for specific errors. E.g., `"INTEGRATION_CONNECTION_MISSING"`,
21
+ * `"API_KEY_INVALID"`, or `"QBD_REQUEST_ERROR"`.
22
+ *
23
+ * By comparison, `type` is more general and categorizes the error.
22
24
  */
23
25
  code;
24
26
  /**
25
27
  * The developer-friendly error message for your logs.
26
- *
27
- * (Defined in the base class but documented here for completeness.)
28
28
  */
29
- // public readonly message: string;
29
+ message;
30
30
  /**
31
- * The end-user-friendly error message to display in your app.
31
+ * The end-user-friendly error message to display in your app's UI for your
32
+ * end-user to see.
33
+ *
34
+ * This value exists for *every* error. E.g., if it's a QBD connection error,
35
+ * it might recommend the end-user to check that their QuickBooks Desktop is
36
+ * open and that they're logged in. But if a Conductor API key is expired,
37
+ * this message will just say "An internal server error occurred. Please try
38
+ * again later.".
32
39
  */
33
40
  endUserMessage;
34
41
  /**
35
- * The error code provided by the third-party integration when `type` is
36
- * `ConductorIntegrationError`. This is useful for adding special handling for
37
- * specific errors from the third-party integration.
42
+ * The unique error code supplied by the third-party integration for errors
43
+ * that come from the integration (i.e., instances of
44
+ * `ConductorIntegrationError`). This is useful for adding special handling
45
+ * for specific errors from the third-party integration.
46
+ *
47
+ * E.g., QuickBooks Desktop might return an error with `integrationCode` for
48
+ * something specific to its accounting logic. The integration's corresponding
49
+ * message for this code would be in `error.message`.
38
50
  *
39
51
  * The third-party integration's error codes are not standardized, so you
40
52
  * should not rely on this code to be the same across integrations.
41
53
  */
42
54
  integrationCode;
43
55
  /**
44
- * The HTTP status code of the response that included the error.
56
+ * The HTTP status code of the response that included the error. You probably
57
+ * won't need this.
45
58
  */
46
59
  httpStatusCode;
60
+ /**
61
+ * The internal representation of `type` for debugging.
62
+ */
63
+ rawType;
47
64
  constructor(options) {
48
65
  super(options.message);
49
66
  // Set `name` to the constructor name so that the error appears in logs as
@@ -58,6 +75,7 @@ class ConductorError extends Error {
58
75
  this.type = this.constructor.name;
59
76
  this.rawType = options.type;
60
77
  this.code = options.code;
78
+ this.message = options.message;
61
79
  this.endUserMessage = options.endUserMessage ?? exports.DEFAULT_END_USER_MESSAGE;
62
80
  this.integrationCode = options.integrationCode;
63
81
  this.httpStatusCode = options.httpStatusCode;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "conductor-node",
3
- "version": "8.6.3",
3
+ "version": "8.6.5",
4
4
  "description": "Easily integrate with the entire QuickBooks Desktop API with fully-typed async TypeScript",
5
5
  "author": "Danny Nemer <hi@DannyNemer.com>",
6
6
  "license": "MIT",