@sdflc/backend-helpers 1.0.146 → 1.0.148
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
CHANGED
|
@@ -1216,7 +1216,7 @@ request). `configure()` **replaces** the settings; it never merges them.
|
|
|
1216
1216
|
| [`DiscordWebhookGw`](#discordwebhookgw) | `webhookUrl`, `username?`, `avatarUrl?` | `postMessage(message)` | `{ messageId }` |
|
|
1217
1217
|
| [`HubSpotGw`](#hubspotgw) | `accessToken` | `upsertContact(contact)`, `addToList`, `addNote`, `listStaticLists`, `getList`, `verify` | `{ contactId, created }` … |
|
|
1218
1218
|
| [`MailchimpGw`](#mailchimpgw) | `apiKey` | `upsertMember(audienceId, member)`, `addTags`, `addNote`, `listAudiences`, `getAudience` | `{ memberId, status }` … |
|
|
1219
|
-
| [`QuickBooksGw`](#quickbooksgw) | `clientId`, `clientSecret`, `environment?` | `authorizeUrl`, `exchangeCode`, `refreshTokens`, `revoke`, `query`, `createItem`, `createSalesReceipt`, `createRefundReceipt`, `createPurchase` … | the tokens / the record |
|
|
1219
|
+
| [`QuickBooksGw`](#quickbooksgw) | `clientId`, `clientSecret`, `environment?` | `authorizeUrl`, `exchangeCode`, `refreshTokens`, `revoke`, `query`, `createItem`, `createSalesReceipt`, `createRefundReceipt`, `createPurchase`, `createJournalEntry` … | the tokens / the record |
|
|
1220
1220
|
| [`HttpWebhookGw`](#httpwebhookgw) | `url`, `method?`, `headers?`, `signingSecret?` | `send(request)` | `{ status, body }` |
|
|
1221
1221
|
|
|
1222
1222
|
Every operation answers the same way:
|
|
@@ -1399,7 +1399,7 @@ await qb.refreshTokens(refreshToken); // ⚠ returns a NEW refresh token — sto
|
|
|
1399
1399
|
await qb.revoke(refreshToken); // disconnect
|
|
1400
1400
|
```
|
|
1401
1401
|
|
|
1402
|
-
- Also `companyInfo`, `preferences`, `createCustomer
|
|
1402
|
+
- Also `companyInfo`, `preferences`, `createCustomer` (`currency?` — a multicurrency customer's, fixed once made), `createRefundReceipt`, `createPurchase` (a fee leaving an account), `createJournalEntry` (debits and credits on any accounts).
|
|
1403
1403
|
- **Every create takes a request id** (Intuit's `requestid`, 1–50 characters): Intuit answers a repeat with the first
|
|
1404
1404
|
result, so the base class's retries never book twice. Refused before sending without one.
|
|
1405
1405
|
- An expired access token comes back `UNAUTHORIZED` (not retried) — refresh and try once more. Intuit's faults (upper- or
|
|
@@ -54,6 +54,11 @@ declare class QuickBooksGw extends BaseExternalApiGateway<QuickBooksSettings> {
|
|
|
54
54
|
private basicAuth;
|
|
55
55
|
private badCompany;
|
|
56
56
|
private companyCall;
|
|
57
|
+
/**
|
|
58
|
+
* ⚠ `sentRefreshToken`: Intuit returns the SAME refresh token until it rotates it (about once a day), and every reply is
|
|
59
|
+
* scrubbed of the values the call sent — so an unchanged token arrives as `***`. It is the one we sent; storing `***`
|
|
60
|
+
* instead ended the connection at the next refresh (`invalid_grant`).
|
|
61
|
+
*/
|
|
57
62
|
private tokensOf;
|
|
58
63
|
private tokenCall;
|
|
59
64
|
/** Where to send the host to connect a company (Intuit's consent screen). Pure; '' when the gateway is not configured. */
|
|
@@ -77,7 +82,7 @@ declare class QuickBooksGw extends BaseExternalApiGateway<QuickBooksSettings> {
|
|
|
77
82
|
companyInfo(company: QuickBooksCompany): Promise<OpResult>;
|
|
78
83
|
/** The company's preferences (sales tax on, multicurrency, home currency). OK with the raw `Preferences`. */
|
|
79
84
|
preferences(company: QuickBooksCompany): Promise<OpResult>;
|
|
80
|
-
/** Creates one record of `entity` (Item, Customer, SalesReceipt, RefundReceipt, Purchase). OK with the record. */
|
|
85
|
+
/** Creates one record of `entity` (Item, Customer, SalesReceipt, RefundReceipt, Purchase, JournalEntry). OK with the record. */
|
|
81
86
|
private create;
|
|
82
87
|
/** A Service item booked on an income account (`IncomeAccountRef`) — a sales line's account is its item's. */
|
|
83
88
|
createItem(company: QuickBooksCompany, item: {
|
|
@@ -89,6 +94,7 @@ declare class QuickBooksGw extends BaseExternalApiGateway<QuickBooksSettings> {
|
|
|
89
94
|
createCustomer(company: QuickBooksCompany, customer: {
|
|
90
95
|
displayName: string;
|
|
91
96
|
email?: string | null;
|
|
97
|
+
currency?: string | null;
|
|
92
98
|
}, requestId: string): Promise<OpResult>;
|
|
93
99
|
/** A sale paid at once (the body as Intuit takes it — `Line`, `DepositToAccountRef`, …). */
|
|
94
100
|
createSalesReceipt(company: QuickBooksCompany, receipt: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
@@ -96,5 +102,10 @@ declare class QuickBooksGw extends BaseExternalApiGateway<QuickBooksSettings> {
|
|
|
96
102
|
createRefundReceipt(company: QuickBooksCompany, receipt: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
97
103
|
/** Money that went out of an account — a processor's or a platform's fee (`AccountRef` it left, expense lines). */
|
|
98
104
|
createPurchase(company: QuickBooksCompany, purchase: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
105
|
+
/**
|
|
106
|
+
* A journal entry (the body as Intuit takes it — `Line` of `JournalEntryLineDetail` debits and credits, which must
|
|
107
|
+
* balance). Unlike a Purchase it may draw on any account type: a fee kept out of an Undeposited Funds deposit, say.
|
|
108
|
+
*/
|
|
109
|
+
createJournalEntry(company: QuickBooksCompany, entry: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
99
110
|
}
|
|
100
111
|
export { QuickBooksGw };
|
|
@@ -118,9 +118,15 @@ class QuickBooksGw extends BaseExternalApiGateway {
|
|
|
118
118
|
secrets: [text(company.accessToken)],
|
|
119
119
|
});
|
|
120
120
|
}
|
|
121
|
-
|
|
121
|
+
/**
|
|
122
|
+
* ⚠ `sentRefreshToken`: Intuit returns the SAME refresh token until it rotates it (about once a day), and every reply is
|
|
123
|
+
* scrubbed of the values the call sent — so an unchanged token arrives as `***`. It is the one we sent; storing `***`
|
|
124
|
+
* instead ended the connection at the next refresh (`invalid_grant`).
|
|
125
|
+
*/
|
|
126
|
+
tokensOf(body, sentRefreshToken = '') {
|
|
122
127
|
const accessToken = text(body?.access_token);
|
|
123
|
-
const
|
|
128
|
+
const returned = text(body?.refresh_token);
|
|
129
|
+
const refreshToken = returned === '***' && sentRefreshToken ? sentRefreshToken : returned;
|
|
124
130
|
if (!accessToken || !refreshToken) {
|
|
125
131
|
return null;
|
|
126
132
|
}
|
|
@@ -135,6 +141,8 @@ class QuickBooksGw extends BaseExternalApiGateway {
|
|
|
135
141
|
};
|
|
136
142
|
}
|
|
137
143
|
async tokenCall(form, secrets) {
|
|
144
|
+
// ⓘ What `tokensOf` restores when the reply was scrubbed of it (see there).
|
|
145
|
+
const sentRefreshToken = form.grant_type === 'refresh_token' ? text(form.refresh_token) : '';
|
|
138
146
|
if (!this.isConfigured()) {
|
|
139
147
|
return this.notConfigured();
|
|
140
148
|
}
|
|
@@ -152,9 +160,9 @@ class QuickBooksGw extends BaseExternalApiGateway {
|
|
|
152
160
|
if (result.didFail()) {
|
|
153
161
|
return result;
|
|
154
162
|
}
|
|
155
|
-
// ⓘ The reply is scrubbed of the values this call SENT (the code, the old refresh token)
|
|
156
|
-
//
|
|
157
|
-
const tokens = this.tokensOf(result.getDataFirst()?.body);
|
|
163
|
+
// ⓘ The reply is scrubbed of the values this call SENT (the code, the old refresh token). A new token arrives intact;
|
|
164
|
+
// an UNCHANGED refresh token arrives as `***` and is put back (`tokensOf`).
|
|
165
|
+
const tokens = this.tokensOf(result.getDataFirst()?.body, sentRefreshToken);
|
|
158
166
|
return tokens
|
|
159
167
|
? OpResult.ok([tokens])
|
|
160
168
|
: OpResult.fail(OP_RESULT_CODES.FAILED, null, 'Intuit answered without the tokens');
|
|
@@ -260,7 +268,7 @@ class QuickBooksGw extends BaseExternalApiGateway {
|
|
|
260
268
|
const result = await this.companyCall(company, 'GET', '/preferences', {});
|
|
261
269
|
return result.didFail() ? result : OpResult.ok([result.getDataFirst()?.body?.Preferences ?? {}]);
|
|
262
270
|
}
|
|
263
|
-
/** Creates one record of `entity` (Item, Customer, SalesReceipt, RefundReceipt, Purchase). OK with the record. */
|
|
271
|
+
/** Creates one record of `entity` (Item, Customer, SalesReceipt, RefundReceipt, Purchase, JournalEntry). OK with the record. */
|
|
264
272
|
async create(company, entity, body, requestId) {
|
|
265
273
|
if (!this.isConfigured()) {
|
|
266
274
|
return this.notConfigured();
|
|
@@ -298,12 +306,18 @@ class QuickBooksGw extends BaseExternalApiGateway {
|
|
|
298
306
|
/** A customer by display name (unique in the company across customers, vendors and employees). */
|
|
299
307
|
createCustomer(company, customer, requestId) {
|
|
300
308
|
const displayName = quickBooksNameOf(customer?.displayName);
|
|
309
|
+
const currency = text(customer?.currency).toUpperCase();
|
|
301
310
|
if (!displayName) {
|
|
302
311
|
return Promise.resolve(OpResult.fail(OP_RESULT_CODES.VALIDATION_FAILED, null, 'A customer needs a name'));
|
|
303
312
|
}
|
|
313
|
+
if (currency && !/^[A-Z]{3}$/.test(currency)) {
|
|
314
|
+
return Promise.resolve(OpResult.fail(OP_RESULT_CODES.VALIDATION_FAILED, null, 'A customer currency is a three-letter code'));
|
|
315
|
+
}
|
|
304
316
|
return this.create(company, 'Customer', {
|
|
305
317
|
DisplayName: displayName,
|
|
306
318
|
...(text(customer.email).includes('@') ? { PrimaryEmailAddr: { Address: text(customer.email) } } : {}),
|
|
319
|
+
// ⓘ Multicurrency: a customer's currency is set when it is made and never changes (Intuit) — with none, the home one.
|
|
320
|
+
...(currency ? { CurrencyRef: { value: currency } } : {}),
|
|
307
321
|
}, requestId);
|
|
308
322
|
}
|
|
309
323
|
/** A sale paid at once (the body as Intuit takes it — `Line`, `DepositToAccountRef`, …). */
|
|
@@ -318,5 +332,12 @@ class QuickBooksGw extends BaseExternalApiGateway {
|
|
|
318
332
|
createPurchase(company, purchase, requestId) {
|
|
319
333
|
return this.create(company, 'Purchase', purchase, requestId);
|
|
320
334
|
}
|
|
335
|
+
/**
|
|
336
|
+
* A journal entry (the body as Intuit takes it — `Line` of `JournalEntryLineDetail` debits and credits, which must
|
|
337
|
+
* balance). Unlike a Purchase it may draw on any account type: a fee kept out of an Undeposited Funds deposit, say.
|
|
338
|
+
*/
|
|
339
|
+
createJournalEntry(company, entry, requestId) {
|
|
340
|
+
return this.create(company, 'JournalEntry', entry, requestId);
|
|
341
|
+
}
|
|
321
342
|
}
|
|
322
343
|
export { QuickBooksGw };
|
|
@@ -54,6 +54,11 @@ declare class QuickBooksGw extends BaseExternalApiGateway<QuickBooksSettings> {
|
|
|
54
54
|
private basicAuth;
|
|
55
55
|
private badCompany;
|
|
56
56
|
private companyCall;
|
|
57
|
+
/**
|
|
58
|
+
* ⚠ `sentRefreshToken`: Intuit returns the SAME refresh token until it rotates it (about once a day), and every reply is
|
|
59
|
+
* scrubbed of the values the call sent — so an unchanged token arrives as `***`. It is the one we sent; storing `***`
|
|
60
|
+
* instead ended the connection at the next refresh (`invalid_grant`).
|
|
61
|
+
*/
|
|
57
62
|
private tokensOf;
|
|
58
63
|
private tokenCall;
|
|
59
64
|
/** Where to send the host to connect a company (Intuit's consent screen). Pure; '' when the gateway is not configured. */
|
|
@@ -77,7 +82,7 @@ declare class QuickBooksGw extends BaseExternalApiGateway<QuickBooksSettings> {
|
|
|
77
82
|
companyInfo(company: QuickBooksCompany): Promise<OpResult>;
|
|
78
83
|
/** The company's preferences (sales tax on, multicurrency, home currency). OK with the raw `Preferences`. */
|
|
79
84
|
preferences(company: QuickBooksCompany): Promise<OpResult>;
|
|
80
|
-
/** Creates one record of `entity` (Item, Customer, SalesReceipt, RefundReceipt, Purchase). OK with the record. */
|
|
85
|
+
/** Creates one record of `entity` (Item, Customer, SalesReceipt, RefundReceipt, Purchase, JournalEntry). OK with the record. */
|
|
81
86
|
private create;
|
|
82
87
|
/** A Service item booked on an income account (`IncomeAccountRef`) — a sales line's account is its item's. */
|
|
83
88
|
createItem(company: QuickBooksCompany, item: {
|
|
@@ -89,6 +94,7 @@ declare class QuickBooksGw extends BaseExternalApiGateway<QuickBooksSettings> {
|
|
|
89
94
|
createCustomer(company: QuickBooksCompany, customer: {
|
|
90
95
|
displayName: string;
|
|
91
96
|
email?: string | null;
|
|
97
|
+
currency?: string | null;
|
|
92
98
|
}, requestId: string): Promise<OpResult>;
|
|
93
99
|
/** A sale paid at once (the body as Intuit takes it — `Line`, `DepositToAccountRef`, …). */
|
|
94
100
|
createSalesReceipt(company: QuickBooksCompany, receipt: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
@@ -96,5 +102,10 @@ declare class QuickBooksGw extends BaseExternalApiGateway<QuickBooksSettings> {
|
|
|
96
102
|
createRefundReceipt(company: QuickBooksCompany, receipt: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
97
103
|
/** Money that went out of an account — a processor's or a platform's fee (`AccountRef` it left, expense lines). */
|
|
98
104
|
createPurchase(company: QuickBooksCompany, purchase: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
105
|
+
/**
|
|
106
|
+
* A journal entry (the body as Intuit takes it — `Line` of `JournalEntryLineDetail` debits and credits, which must
|
|
107
|
+
* balance). Unlike a Purchase it may draw on any account type: a fee kept out of an Undeposited Funds deposit, say.
|
|
108
|
+
*/
|
|
109
|
+
createJournalEntry(company: QuickBooksCompany, entry: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
99
110
|
}
|
|
100
111
|
export { QuickBooksGw };
|
|
@@ -123,9 +123,15 @@ class QuickBooksGw extends BaseExternalApiGateway_1.BaseExternalApiGateway {
|
|
|
123
123
|
secrets: [text(company.accessToken)],
|
|
124
124
|
});
|
|
125
125
|
}
|
|
126
|
-
|
|
126
|
+
/**
|
|
127
|
+
* ⚠ `sentRefreshToken`: Intuit returns the SAME refresh token until it rotates it (about once a day), and every reply is
|
|
128
|
+
* scrubbed of the values the call sent — so an unchanged token arrives as `***`. It is the one we sent; storing `***`
|
|
129
|
+
* instead ended the connection at the next refresh (`invalid_grant`).
|
|
130
|
+
*/
|
|
131
|
+
tokensOf(body, sentRefreshToken = '') {
|
|
127
132
|
const accessToken = text(body?.access_token);
|
|
128
|
-
const
|
|
133
|
+
const returned = text(body?.refresh_token);
|
|
134
|
+
const refreshToken = returned === '***' && sentRefreshToken ? sentRefreshToken : returned;
|
|
129
135
|
if (!accessToken || !refreshToken) {
|
|
130
136
|
return null;
|
|
131
137
|
}
|
|
@@ -140,6 +146,8 @@ class QuickBooksGw extends BaseExternalApiGateway_1.BaseExternalApiGateway {
|
|
|
140
146
|
};
|
|
141
147
|
}
|
|
142
148
|
async tokenCall(form, secrets) {
|
|
149
|
+
// ⓘ What `tokensOf` restores when the reply was scrubbed of it (see there).
|
|
150
|
+
const sentRefreshToken = form.grant_type === 'refresh_token' ? text(form.refresh_token) : '';
|
|
143
151
|
if (!this.isConfigured()) {
|
|
144
152
|
return this.notConfigured();
|
|
145
153
|
}
|
|
@@ -157,9 +165,9 @@ class QuickBooksGw extends BaseExternalApiGateway_1.BaseExternalApiGateway {
|
|
|
157
165
|
if (result.didFail()) {
|
|
158
166
|
return result;
|
|
159
167
|
}
|
|
160
|
-
// ⓘ The reply is scrubbed of the values this call SENT (the code, the old refresh token)
|
|
161
|
-
//
|
|
162
|
-
const tokens = this.tokensOf(result.getDataFirst()?.body);
|
|
168
|
+
// ⓘ The reply is scrubbed of the values this call SENT (the code, the old refresh token). A new token arrives intact;
|
|
169
|
+
// an UNCHANGED refresh token arrives as `***` and is put back (`tokensOf`).
|
|
170
|
+
const tokens = this.tokensOf(result.getDataFirst()?.body, sentRefreshToken);
|
|
163
171
|
return tokens
|
|
164
172
|
? api_helpers_1.OpResult.ok([tokens])
|
|
165
173
|
: api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.FAILED, null, 'Intuit answered without the tokens');
|
|
@@ -265,7 +273,7 @@ class QuickBooksGw extends BaseExternalApiGateway_1.BaseExternalApiGateway {
|
|
|
265
273
|
const result = await this.companyCall(company, 'GET', '/preferences', {});
|
|
266
274
|
return result.didFail() ? result : api_helpers_1.OpResult.ok([result.getDataFirst()?.body?.Preferences ?? {}]);
|
|
267
275
|
}
|
|
268
|
-
/** Creates one record of `entity` (Item, Customer, SalesReceipt, RefundReceipt, Purchase). OK with the record. */
|
|
276
|
+
/** Creates one record of `entity` (Item, Customer, SalesReceipt, RefundReceipt, Purchase, JournalEntry). OK with the record. */
|
|
269
277
|
async create(company, entity, body, requestId) {
|
|
270
278
|
if (!this.isConfigured()) {
|
|
271
279
|
return this.notConfigured();
|
|
@@ -303,12 +311,18 @@ class QuickBooksGw extends BaseExternalApiGateway_1.BaseExternalApiGateway {
|
|
|
303
311
|
/** A customer by display name (unique in the company across customers, vendors and employees). */
|
|
304
312
|
createCustomer(company, customer, requestId) {
|
|
305
313
|
const displayName = (0, exports.quickBooksNameOf)(customer?.displayName);
|
|
314
|
+
const currency = text(customer?.currency).toUpperCase();
|
|
306
315
|
if (!displayName) {
|
|
307
316
|
return Promise.resolve(api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED, null, 'A customer needs a name'));
|
|
308
317
|
}
|
|
318
|
+
if (currency && !/^[A-Z]{3}$/.test(currency)) {
|
|
319
|
+
return Promise.resolve(api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED, null, 'A customer currency is a three-letter code'));
|
|
320
|
+
}
|
|
309
321
|
return this.create(company, 'Customer', {
|
|
310
322
|
DisplayName: displayName,
|
|
311
323
|
...(text(customer.email).includes('@') ? { PrimaryEmailAddr: { Address: text(customer.email) } } : {}),
|
|
324
|
+
// ⓘ Multicurrency: a customer's currency is set when it is made and never changes (Intuit) — with none, the home one.
|
|
325
|
+
...(currency ? { CurrencyRef: { value: currency } } : {}),
|
|
312
326
|
}, requestId);
|
|
313
327
|
}
|
|
314
328
|
/** A sale paid at once (the body as Intuit takes it — `Line`, `DepositToAccountRef`, …). */
|
|
@@ -323,5 +337,12 @@ class QuickBooksGw extends BaseExternalApiGateway_1.BaseExternalApiGateway {
|
|
|
323
337
|
createPurchase(company, purchase, requestId) {
|
|
324
338
|
return this.create(company, 'Purchase', purchase, requestId);
|
|
325
339
|
}
|
|
340
|
+
/**
|
|
341
|
+
* A journal entry (the body as Intuit takes it — `Line` of `JournalEntryLineDetail` debits and credits, which must
|
|
342
|
+
* balance). Unlike a Purchase it may draw on any account type: a fee kept out of an Undeposited Funds deposit, say.
|
|
343
|
+
*/
|
|
344
|
+
createJournalEntry(company, entry, requestId) {
|
|
345
|
+
return this.create(company, 'JournalEntry', entry, requestId);
|
|
346
|
+
}
|
|
326
347
|
}
|
|
327
348
|
exports.QuickBooksGw = QuickBooksGw;
|