conductor-node 8.6.4 → 8.6.6

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 +21 -19
  2. package/dist/package.json +4 -2
  3. package/dist/src/errors.d.ts +9 -6
  4. package/dist/src/errors.js +9 -6
  5. package/package.json +4 -2
package/README.md CHANGED
@@ -158,32 +158,32 @@ const accountAddInput: QbdTypes.AccountAdd = {
158
158
 
159
159
  ## Error Handling
160
160
 
161
- 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:
161
+ ### `ConductorError`
162
162
 
163
- | Property | Type | Description |
164
- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
165
- | `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"`. |
166
- | `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. |
167
- | `message` | `string` | The developer-friendly error message for your logs. |
168
- | `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.". |
169
- | `integrationCode` | `string` | 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. |
170
- | `httpStatusCode` | `number` | The HTTP status code of the response that included the error. You probably won't need this. |
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:
171
164
 
172
- _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`.
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, e.g., 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 error message for this code is 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
173
 
174
174
  ### Error Types
175
175
 
176
176
  The error object you receive will have one of the following error types:
177
177
 
178
- | Type | Description |
179
- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
180
- | `ConductorIntegrationError` | An error occurred on the third-party integration's end while processing your end-user's request. E.g., cannot connect to QuickBooks Desktop on your end-user's computer. |
181
- | `ConductorInvalidRequestError` | You made an API call with the wrong parameters, in the wrong state, or in an invalid way. |
182
- | `ConductorAuthenticationError` | Conductor cannot authenticate you with the credentials you provided. E.g., an incorrect API key. |
183
- | `ConductorConnectionError` | There was a network problem between the client (on your server) and Conductor's servers. |
184
- | `ConductorInternalError` | Something went wrong on Conductor's end. (These are rare.) |
178
+ | Type | Description |
179
+ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
180
+ | `ConductorIntegrationError` | The third-party integration's return an error while processing your end-user's request. E.g., cannot connect to QuickBooks Desktop on your end-user's computer.<br><br>See `error.integrationCode` for the error code that the third-party integration returned. |
181
+ | `ConductorInvalidRequestError` | You made an API call with the wrong parameters, in the wrong state, or in an invalid way. |
182
+ | `ConductorAuthenticationError` | Conductor cannot authenticate you with the credentials you provided. E.g., an incorrect API key. |
183
+ | `ConductorConnectionError` | There was a network problem between the client (on your server) and Conductor's servers. |
184
+ | `ConductorInternalError` | Something went wrong on Conductor's end. (These are rare.) |
185
185
 
186
- ### Special Handling
186
+ ### Specific Error Handling
187
187
 
188
188
  If you need special handling for specific errors, you can wrap individual API calls, as shown below.
189
189
 
@@ -230,7 +230,7 @@ try {
230
230
 
231
231
  We do _not_ expect you to individually wrap every API call like the examples above. Instead, we recommend your server use a single global error handler, 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), where you do the following:
232
232
 
233
- 1. Ensure your app's UI shows your end-user the property `error.endUserMessage` for any `ConductorError` instance for any Conductor request while you log the rest of the error object.
233
+ 1. Ensure your app's UI shows your end-user the property `error.endUserMessage` for any `ConductorError` instance while you log the rest of the error object.
234
234
  2. Send the entire error object to your error-tracking service (e.g., Sentry) for all `ConductorError` instances:
235
235
  - Send a **warning** for instances of `ConductorIntegrationError`, which are your end-user's fault; e.g., cannot connect to QBD on your end-user's computer.
236
236
  - Send an **error** for all other `ConductorError` instances; e.g., invalid API key.
@@ -283,3 +283,5 @@ const server = new ApolloServer({
283
283
  },
284
284
  });
285
285
  ```
286
+
287
+ 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.4",
3
+ "version": "8.6.6",
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",
@@ -17,7 +17,9 @@
17
17
  "postpack": "rm -rf dist",
18
18
  "clean": "rm -rf dist package conductor-node-*.tgz tsconfig.tsbuildinfo",
19
19
  "gen:graphql": "yarn graphql-codegen --config ./src/graphql/codegenConfig.ts",
20
- "diff": "yarn pack && npm diff --diff=conductor-node@latest --diff=conductor-node-v$(node -p \"require('./package.json').version\").tgz && yarn clean"
20
+ "diff": "yarn pack && npm diff --diff=conductor-node@latest --diff=conductor-node-v$(node -p \"require('./package.json').version\").tgz && yarn clean",
21
+ "prepublishOnly": "yarn test",
22
+ "test": "yarn --cwd ../.. test ./packages/client"
21
23
  },
22
24
  "engines": {
23
25
  "node": ">=16"
package/dist/src/errors.d.ts CHANGED
@@ -45,8 +45,8 @@ export declare class ConductorError extends Error {
45
45
  * This value exists for *every* error. E.g., if it's a QBD connection error,
46
46
  * it might recommend the end-user to check that their QuickBooks Desktop is
47
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.".
48
+ * e.g., this message will just say "An internal server error occurred. Please
49
+ * try again later.".
50
50
  */
51
51
  readonly endUserMessage: string;
52
52
  /**
@@ -57,7 +57,7 @@ export declare class ConductorError extends Error {
57
57
  *
58
58
  * E.g., QuickBooks Desktop might return an error with `integrationCode` for
59
59
  * something specific to its accounting logic. The integration's corresponding
60
- * message for this code would be in `error.message`.
60
+ * error message for this code is in `error.message`.
61
61
  *
62
62
  * The third-party integration's error codes are not standardized, so you
63
63
  * should not rely on this code to be the same across integrations.
@@ -76,9 +76,12 @@ export declare class ConductorError extends Error {
76
76
  }
77
77
  type ConductorErrorOptionsWithoutType = Omit<ConductorErrorOptions, "type">;
78
78
  /**
79
- * Raised when an error occurs on the third-party integration's end while
80
- * processing your end-user's request. E.g., cannot connect to QuickBooks
81
- * Desktop on the end-user's computer.
79
+ * Raised when the third-party integration returned an error while processing
80
+ * your end-user's request. E.g., cannot connect to QuickBooks Desktop on the
81
+ * end-user's computer.
82
+ *
83
+ * See `error.integrationCode` for the error code that the third-party
84
+ * integration returned.
82
85
  */
83
86
  export declare class ConductorIntegrationError extends ConductorError {
84
87
  static readonly rawType: string;
package/dist/src/errors.js CHANGED
@@ -34,8 +34,8 @@ class ConductorError extends Error {
34
34
  * This value exists for *every* error. E.g., if it's a QBD connection error,
35
35
  * it might recommend the end-user to check that their QuickBooks Desktop is
36
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.".
37
+ * e.g., this message will just say "An internal server error occurred. Please
38
+ * try again later.".
39
39
  */
40
40
  endUserMessage;
41
41
  /**
@@ -46,7 +46,7 @@ class ConductorError extends Error {
46
46
  *
47
47
  * E.g., QuickBooks Desktop might return an error with `integrationCode` for
48
48
  * something specific to its accounting logic. The integration's corresponding
49
- * message for this code would be in `error.message`.
49
+ * error message for this code is in `error.message`.
50
50
  *
51
51
  * The third-party integration's error codes are not standardized, so you
52
52
  * should not rely on this code to be the same across integrations.
@@ -83,9 +83,12 @@ class ConductorError extends Error {
83
83
  }
84
84
  exports.ConductorError = ConductorError;
85
85
  /**
86
- * Raised when an error occurs on the third-party integration's end while
87
- * processing your end-user's request. E.g., cannot connect to QuickBooks
88
- * Desktop on the end-user's computer.
86
+ * Raised when the third-party integration returned an error while processing
87
+ * your end-user's request. E.g., cannot connect to QuickBooks Desktop on the
88
+ * end-user's computer.
89
+ *
90
+ * See `error.integrationCode` for the error code that the third-party
91
+ * integration returned.
89
92
  */
90
93
  class ConductorIntegrationError extends ConductorError {
91
94
  static rawType = "INTEGRATION_ERROR";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "conductor-node",
3
- "version": "8.6.4",
3
+ "version": "8.6.6",
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",
@@ -17,7 +17,9 @@
17
17
  "postpack": "rm -rf dist",
18
18
  "clean": "rm -rf dist package conductor-node-*.tgz tsconfig.tsbuildinfo",
19
19
  "gen:graphql": "yarn graphql-codegen --config ./src/graphql/codegenConfig.ts",
20
- "diff": "yarn pack && npm diff --diff=conductor-node@latest --diff=conductor-node-v$(node -p \"require('./package.json').version\").tgz && yarn clean"
20
+ "diff": "yarn pack && npm diff --diff=conductor-node@latest --diff=conductor-node-v$(node -p \"require('./package.json').version\").tgz && yarn clean",
21
+ "prepublishOnly": "yarn test",
22
+ "test": "yarn --cwd ../.. test ./packages/client"
21
23
  },
22
24
  "engines": {
23
25
  "node": ">=16"