conductor-node 11.0.3 → 11.0.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 +6 -267
- package/dist/package.json +1 -1
- package/dist/src/interceptors/errorHandling.js +7 -2
- package/dist/src/interceptors/logging.js +3 -1
- package/dist/src/resources/EndUsersResource.d.ts +3 -0
- package/dist/src/utils/error.d.ts +6 -1
- package/dist/src/utils/error.js +9 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,29 +1,10 @@
|
|
|
1
1
|
# [Conductor](https://conductor.is/) - The best QuickBooks Desktop integration on the planet
|
|
2
2
|
|
|
3
|
-
Execute _any_ read or write
|
|
3
|
+
Execute _any_ read or write QuickBooks Desktop API through async TypeScript and receive a fully-typed response.
|
|
4
4
|
|
|
5
5
|
<!-- markdownlint-disable MD033 -->
|
|
6
6
|
<img src="https://user-images.githubusercontent.com/170023/213273732-83dd6881-0b36-4787-820b-bd55cdc8444f.jpg" alt="qbd" width="600"/>
|
|
7
7
|
|
|
8
|
-
## Table of Contents
|
|
9
|
-
|
|
10
|
-
1. [Requirements](#requirements)
|
|
11
|
-
2. [Installation](#installation)
|
|
12
|
-
3. [Usage](#usage)
|
|
13
|
-
4. [APIs](#apis)
|
|
14
|
-
5. [TypeScript](#typescript)
|
|
15
|
-
6. [Error Handling](#error-handling)
|
|
16
|
-
|
|
17
|
-
## Requirements
|
|
18
|
-
|
|
19
|
-
1. A Conductor API key. Please visit [our website](https://conductor.is/) to join the private beta.
|
|
20
|
-
|
|
21
|
-
## Installation
|
|
22
|
-
|
|
23
|
-
```sh
|
|
24
|
-
yarn add conductor-node
|
|
25
|
-
```
|
|
26
|
-
|
|
27
8
|
## Usage
|
|
28
9
|
|
|
29
10
|
```ts
|
|
@@ -43,251 +24,9 @@ const newAccount = await conductor.qbd.account.add(endUsers[0].id, {
|
|
|
43
24
|
});
|
|
44
25
|
```
|
|
45
26
|
|
|
46
|
-
##
|
|
47
|
-
|
|
48
|
-
### `qbd.*`
|
|
49
|
-
|
|
50
|
-
Executes any QuickBooks Desktop (QBD) API against the specified end-user. See the official [QuickBooks Desktop API Reference](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop) for a complete list of available APIs.
|
|
51
|
-
|
|
52
|
-
```ts
|
|
53
|
-
const qbdAccount = await conductor.qbd.account.add(endUserId, {
|
|
54
|
-
Name: "Test Account",
|
|
55
|
-
AccountType: "Bank",
|
|
56
|
-
OpenBalance: "100",
|
|
57
|
-
});
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
### `endUsers.create(input: EndUserCreateInput)`
|
|
61
|
-
|
|
62
|
-
Creates a new end-user.
|
|
63
|
-
|
|
64
|
-
```ts
|
|
65
|
-
const newEndUser = await conductor.endUsers.create({
|
|
66
|
-
// Your end-user's unique ID in *your* database. Must be
|
|
67
|
-
// distinct from your other end-users.
|
|
68
|
-
sourceId: "1234-abcd",
|
|
69
|
-
// Your end-user's email address.
|
|
70
|
-
email: "danny@constructionco.com",
|
|
71
|
-
// Your end-user's company name shown elsewhere in Conductor.
|
|
72
|
-
name: "Construction Corp",
|
|
73
|
-
});
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
The response looks like the following:
|
|
77
|
-
|
|
78
|
-
```ts
|
|
79
|
-
{
|
|
80
|
-
// ❗ Save this `id` to your database for executing requests to this
|
|
81
|
-
// end-user's integration(s) in the future.
|
|
82
|
-
id: 'end_usr_1234abcd',
|
|
83
|
-
sourceId: "1234-abcd",
|
|
84
|
-
email: 'danny@construction.com',
|
|
85
|
-
name: 'Construction Corp',
|
|
86
|
-
}
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
### `endUsers.list()`
|
|
90
|
-
|
|
91
|
-
Returns a list of all end-users associated with your Conductor account.
|
|
92
|
-
|
|
93
|
-
```ts
|
|
94
|
-
const endUsers = await conductor.endUsers.list();
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
### `endUsers.retrieve(id: string)`
|
|
98
|
-
|
|
99
|
-
Retrieves the specified end-User.
|
|
100
|
-
|
|
101
|
-
```ts
|
|
102
|
-
const endUser = await conductor.endUsers.retrieve(endUserId);
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
### `endUsers.ping(id: string, integrationSlug: string)`
|
|
106
|
-
|
|
107
|
-
Checks whether the specified integration-connection can connect and process requests end-to-end.
|
|
108
|
-
|
|
109
|
-
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.
|
|
110
|
-
|
|
111
|
-
Using `async`/`await`:
|
|
112
|
-
|
|
113
|
-
```ts
|
|
114
|
-
try {
|
|
115
|
-
await conductor.endUsers.ping(endUserId, "quickbooks-desktop");
|
|
116
|
-
} catch (error) {
|
|
117
|
-
if (error instanceof ConductorError) {
|
|
118
|
-
// Update your app's UI to display `error.userFacingMessage`.
|
|
119
|
-
}
|
|
120
|
-
// ...
|
|
121
|
-
}
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
Or in the form of a rejected promise:
|
|
125
|
-
|
|
126
|
-
```ts
|
|
127
|
-
conductor.endUsers.ping(endUserId, "quickbooks-desktop").catch((error) => {
|
|
128
|
-
if (error instanceof ConductorError) {
|
|
129
|
-
// Update your app's UI to display `error.userFacingMessage`.
|
|
130
|
-
}
|
|
131
|
-
// ...
|
|
132
|
-
});
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
## TypeScript
|
|
136
|
-
|
|
137
|
-
Access the entire QuickBooks Desktop API through TypeScript. The `qbd.*` APIs are fully typed with inline documentation and will autocomplete in your editor.
|
|
138
|
-
|
|
139
|
-
To access the QBD types directly, import them from `conductor-node` like so:
|
|
140
|
-
|
|
141
|
-
```ts
|
|
142
|
-
import { QbdTypes } from "conductor-node";
|
|
143
|
-
|
|
144
|
-
const accountAddInput: QbdTypes.AccountAdd = {
|
|
145
|
-
Name: "Test Account",
|
|
146
|
-
AccountType: "Bank",
|
|
147
|
-
OpenBalance: "100",
|
|
148
|
-
};
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
## Error Handling
|
|
152
|
-
|
|
153
|
-
### `ConductorError`
|
|
154
|
-
|
|
155
|
-
All errors thrown by the Conductor API are instances of `ConductorError` or its subclasses. These errors have the following properties:
|
|
156
|
-
|
|
157
|
-
| Property | Type | Description |
|
|
158
|
-
| ------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
159
|
-
| `message` | `string` | The developer error message for your logs. |
|
|
160
|
-
| `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.". |
|
|
161
|
-
| `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"`. |
|
|
162
|
-
| `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. |
|
|
163
|
-
| `httpStatusCode` | `number` or `undefined` | The HTTP status code of the response that included the error. |
|
|
164
|
-
| `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. |
|
|
165
|
-
| `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. |
|
|
166
|
-
| `headers` | `object` or `undefined` | The headers of the response that included the error. |
|
|
167
|
-
|
|
168
|
-
### Error Types
|
|
169
|
-
|
|
170
|
-
The error object you receive will have one of the following error types:
|
|
171
|
-
|
|
172
|
-
| Name | Description |
|
|
173
|
-
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
174
|
-
| `ConductorIntegrationError` | Raised when the third-party integration encounters an error while processing the end-user's request. This often results from an issue with the request or data handling that requires your attention to resolve.<br><br>E.g., a `ListID` you provided was not found in QuickBooks Desktop, or an accounting value you supplied did not adhere to the integration's accounting rules.<br><br>Refer to `error.integrationCode` for the error code returned by the integration, if available. |
|
|
175
|
-
| `ConductorIntegrationConnectionError` | Raised when a connection error occurs with the third-party integration on the end-user's side. This typically indicates an issue with the end-user's integration-connection or configuration, which they must resolve. In other words, you cannot take action to fix these errors.<br><br>E.g., QuickBooks Web Connector (QBWC) failed to connect to QuickBooks Desktop on the end-user's computer.<br><br>Refer to `error.integrationCode` for the error code returned by the integration connector, if available.<br><br>❗ We recommend _not_ triggering alerts for these errors because only the end-user can fix them. See [Global Error Handling](#global-error-handling) for an example of this. |
|
|
176
|
-
| `ConductorInvalidRequestError` | Raised when you make an API call with the wrong parameters, in the wrong state, or in an invalid way. |
|
|
177
|
-
| `ConductorAuthenticationError` | Raised when Conductor cannot authenticate you with the credentials you provided. E.g., an incorrect API key. |
|
|
178
|
-
| `ConductorPermissionError` | Raised when you attempt to access a resource that is not allowed. |
|
|
179
|
-
| `ConductorConnectionError` | Raised when there was a network problem between the client (on your server) and Conductor's servers. E.g., a downed network or a bad TLS certificate. |
|
|
180
|
-
| `ConductorInternalError` | Raised when something went wrong on Conductor's end. (These are rare.) |
|
|
181
|
-
|
|
182
|
-
### Specific Error Handling
|
|
183
|
-
|
|
184
|
-
If you need special handling for specific errors, you can wrap individual API calls, as shown below.
|
|
185
|
-
|
|
186
|
-
Using `async`/`await`:
|
|
187
|
-
|
|
188
|
-
```ts
|
|
189
|
-
try {
|
|
190
|
-
const newAccount = await conductor.qbd.account.add(endUserId, {
|
|
191
|
-
Name: "Test Account",
|
|
192
|
-
AccountType: "Bank",
|
|
193
|
-
OpenBalance: "100",
|
|
194
|
-
});
|
|
195
|
-
} catch (error) {
|
|
196
|
-
if (error instanceof ConductorError) {
|
|
197
|
-
// Check `error.code`, `error.integrationCode`, etc., for special handling.
|
|
198
|
-
} else {
|
|
199
|
-
// ...
|
|
200
|
-
}
|
|
201
|
-
}
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
Or in the form of a rejected promise:
|
|
205
|
-
|
|
206
|
-
```ts
|
|
207
|
-
conductor.qbd.account
|
|
208
|
-
.add(endUserId, {
|
|
209
|
-
Name: "Test Account",
|
|
210
|
-
AccountType: "Bank",
|
|
211
|
-
OpenBalance: "100",
|
|
212
|
-
})
|
|
213
|
-
.then((newAccount) => {
|
|
214
|
-
// ...
|
|
215
|
-
})
|
|
216
|
-
.catch((error) => {
|
|
217
|
-
if (error instanceof ConductorError) {
|
|
218
|
-
// Check `error.code`, `error.integrationCode`, etc., for special handling.
|
|
219
|
-
} else {
|
|
220
|
-
// ...
|
|
221
|
-
}
|
|
222
|
-
});
|
|
223
|
-
```
|
|
224
|
-
|
|
225
|
-
### Global Error Handling
|
|
226
|
-
|
|
227
|
-
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:
|
|
228
|
-
|
|
229
|
-
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.
|
|
230
|
-
2. For all `ConductorError` instances, transmit the full error object to your error-tracking service (e.g., Sentry):
|
|
231
|
-
- 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.
|
|
232
|
-
- Send an **error** for all other `ConductorError` instances, such as an invalid API key.
|
|
233
|
-
|
|
234
|
-
For example, using an [Express error handler](https://expressjs.com/en/guide/error-handling.html#writing-error-handlers):
|
|
235
|
-
|
|
236
|
-
```ts
|
|
237
|
-
import * as Sentry from "@sentry/node";
|
|
238
|
-
import {
|
|
239
|
-
ConductorError,
|
|
240
|
-
ConductorIntegrationConnectionError,
|
|
241
|
-
} from "conductor-node";
|
|
242
|
-
// ...
|
|
243
|
-
app.use((error, req, res, next) => {
|
|
244
|
-
if (error instanceof ConductorError) {
|
|
245
|
-
Sentry.captureException(error, {
|
|
246
|
-
level:
|
|
247
|
-
error instanceof ConductorIntegrationConnectionError
|
|
248
|
-
? "warning"
|
|
249
|
-
: "error",
|
|
250
|
-
});
|
|
251
|
-
// Return a different error message for your end-user to see in your
|
|
252
|
-
// app's UI.
|
|
253
|
-
res.status(500).send({ error: { message: error.userFacingMessage } });
|
|
254
|
-
} else {
|
|
255
|
-
// ...
|
|
256
|
-
}
|
|
257
|
-
});
|
|
258
|
-
```
|
|
259
|
-
|
|
260
|
-
Or using [Apollo Server's error handler](https://apollographql.com/docs/apollo-server/data/errors/#for-client-responses):
|
|
27
|
+
## Documentation
|
|
261
28
|
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
import {
|
|
267
|
-
ConductorError,
|
|
268
|
-
ConductorIntegrationConnectionError,
|
|
269
|
-
} from "conductor-node";
|
|
270
|
-
// ...
|
|
271
|
-
const server = new ApolloServer({
|
|
272
|
-
// ...
|
|
273
|
-
formatError: (formattedError, error) => {
|
|
274
|
-
const origError = unwrapResolverError(error);
|
|
275
|
-
if (origError instanceof ConductorError) {
|
|
276
|
-
Sentry.captureException(origError, {
|
|
277
|
-
level:
|
|
278
|
-
origError instanceof ConductorIntegrationConnectionError
|
|
279
|
-
? "warning"
|
|
280
|
-
: "error",
|
|
281
|
-
});
|
|
282
|
-
return {
|
|
283
|
-
...formattedError,
|
|
284
|
-
// Return a different error message for your end-user to see in
|
|
285
|
-
// your app's UI.
|
|
286
|
-
message: origError.userFacingMessage,
|
|
287
|
-
};
|
|
288
|
-
}
|
|
289
|
-
// ...
|
|
290
|
-
return formattedError;
|
|
291
|
-
},
|
|
292
|
-
});
|
|
293
|
-
```
|
|
29
|
+
1. [Getting Started](https://docs.conductor.is/getting-started)
|
|
30
|
+
2. [API Reference](https://docs.conductor.is/apis)
|
|
31
|
+
3. [QuickBooks Desktop](https://docs.conductor.is/quickbooks-desktop)
|
|
32
|
+
4. [Error Handling](https://docs.conductor.is/error-handling)
|
package/dist/package.json
CHANGED
|
@@ -12,6 +12,8 @@ function addErrorHandlingInterceptors(httpClient) {
|
|
|
12
12
|
const errorData = error.response.data;
|
|
13
13
|
if ((0, error_1.isWellFormedConductorServerError)(errorData)) {
|
|
14
14
|
throw (0, error_1.generateConductorErrorFromType)({
|
|
15
|
+
// The request ID is already in the response body, so no need to
|
|
16
|
+
// copy it from the headers.
|
|
15
17
|
...errorData.error,
|
|
16
18
|
httpStatusCode: error.response.status,
|
|
17
19
|
headers,
|
|
@@ -21,9 +23,12 @@ function addErrorHandlingInterceptors(httpClient) {
|
|
|
21
23
|
message: "Invalid JSON received from the Conductor API.",
|
|
22
24
|
code: "INVALID_JSON_RESPONSE",
|
|
23
25
|
httpStatusCode: error.status ?? axios_1.HttpStatusCode.InternalServerError,
|
|
24
|
-
// @ts-expect-error -- `error.response.headers`
|
|
26
|
+
// @ts-expect-error -- `error.response.headers` always exists as an `AxiosHeaders` instance.
|
|
25
27
|
requestId: error.response.headers.get("request-id"),
|
|
26
28
|
headers,
|
|
29
|
+
// Include to understand why `isWellFormedConductorServerError()`
|
|
30
|
+
// failed.
|
|
31
|
+
raw: errorData,
|
|
27
32
|
});
|
|
28
33
|
}
|
|
29
34
|
if (error.code === axios_1.AxiosError.ECONNABORTED) {
|
|
@@ -41,7 +46,7 @@ function addErrorHandlingInterceptors(httpClient) {
|
|
|
41
46
|
// Conductor API is offline) or an error ocurred when setting up the
|
|
42
47
|
// request (e.g., no network connection).
|
|
43
48
|
throw new error_1.ConductorConnectionError({
|
|
44
|
-
message:
|
|
49
|
+
message: `An error occurred with our connection to Conductor: ${error.message}`,
|
|
45
50
|
code: error.code ?? "NETWORK_ERROR",
|
|
46
51
|
httpStatusCode: error.status,
|
|
47
52
|
});
|
|
@@ -24,7 +24,9 @@ function addLoggingInterceptors(httpClient, verbose) {
|
|
|
24
24
|
// NOTE: We cannot include duration because we lack access to
|
|
25
25
|
// `AxiosError.config` because we already wrapped the error.
|
|
26
26
|
if (verbose) {
|
|
27
|
-
|
|
27
|
+
// No prefix "Conductor error:" because the error already includes a
|
|
28
|
+
// prefix (e.g., `ConductorConnectionError`).
|
|
29
|
+
console.log(stringifyForLogs(error));
|
|
28
30
|
}
|
|
29
31
|
throw error;
|
|
30
32
|
});
|
|
@@ -25,6 +25,9 @@ export interface EndUser {
|
|
|
25
25
|
}
|
|
26
26
|
export type EndUserCreateInput = Pick<EndUser, "email" | "name" | "sourceId">;
|
|
27
27
|
export interface EndUserPingOutput {
|
|
28
|
+
/**
|
|
29
|
+
* The time, in milliseconds, that it took to ping the connection.
|
|
30
|
+
*/
|
|
28
31
|
readonly duration: number;
|
|
29
32
|
}
|
|
30
33
|
export default class EndUsersResource extends BaseResource {
|
|
@@ -8,6 +8,7 @@ export interface ConductorErrorOptions {
|
|
|
8
8
|
readonly integrationCode?: string | undefined;
|
|
9
9
|
readonly requestId?: string | undefined;
|
|
10
10
|
readonly headers?: Record<string, string>;
|
|
11
|
+
readonly raw?: unknown;
|
|
11
12
|
}
|
|
12
13
|
/**
|
|
13
14
|
* The raw REST error response that Conductor's API returns.
|
|
@@ -89,7 +90,11 @@ export declare abstract class ConductorError extends Error {
|
|
|
89
90
|
*/
|
|
90
91
|
readonly headers: Record<string, string> | undefined;
|
|
91
92
|
/**
|
|
92
|
-
* The
|
|
93
|
+
* The raw REST error response that Conductor's API returned.
|
|
94
|
+
*/
|
|
95
|
+
protected readonly raw: unknown;
|
|
96
|
+
/**
|
|
97
|
+
* Conductor's internal representation of `type` for debugging.
|
|
93
98
|
*/
|
|
94
99
|
protected readonly rawType: string;
|
|
95
100
|
constructor(options: ConductorErrorOptions);
|
package/dist/src/utils/error.js
CHANGED
|
@@ -80,7 +80,11 @@ class ConductorError extends Error {
|
|
|
80
80
|
*/
|
|
81
81
|
headers;
|
|
82
82
|
/**
|
|
83
|
-
* The
|
|
83
|
+
* The raw REST error response that Conductor's API returned.
|
|
84
|
+
*/
|
|
85
|
+
raw;
|
|
86
|
+
/**
|
|
87
|
+
* Conductor's internal representation of `type` for debugging.
|
|
84
88
|
*/
|
|
85
89
|
rawType;
|
|
86
90
|
constructor(options) {
|
|
@@ -105,6 +109,10 @@ class ConductorError extends Error {
|
|
|
105
109
|
this.integrationCode = options.integrationCode;
|
|
106
110
|
this.requestId = options.requestId;
|
|
107
111
|
this.headers = options.headers;
|
|
112
|
+
// Only set `raw` if provided instead of always setting it to `options`
|
|
113
|
+
// because the latter is usually a near duplicate of `this`, which we don't
|
|
114
|
+
// want to log unless necessary.
|
|
115
|
+
this.raw = options.raw;
|
|
108
116
|
this.rawType = options.type;
|
|
109
117
|
}
|
|
110
118
|
}
|