@sdflc/backend-helpers 1.0.146 → 1.0.147
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`, `createRefundReceipt`, `createPurchase` (a fee leaving an account).
|
|
1402
|
+
- Also `companyInfo`, `preferences`, `createCustomer`, `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: {
|
|
@@ -96,5 +101,10 @@ declare class QuickBooksGw extends BaseExternalApiGateway<QuickBooksSettings> {
|
|
|
96
101
|
createRefundReceipt(company: QuickBooksCompany, receipt: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
97
102
|
/** Money that went out of an account — a processor's or a platform's fee (`AccountRef` it left, expense lines). */
|
|
98
103
|
createPurchase(company: QuickBooksCompany, purchase: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
104
|
+
/**
|
|
105
|
+
* A journal entry (the body as Intuit takes it — `Line` of `JournalEntryLineDetail` debits and credits, which must
|
|
106
|
+
* balance). Unlike a Purchase it may draw on any account type: a fee kept out of an Undeposited Funds deposit, say.
|
|
107
|
+
*/
|
|
108
|
+
createJournalEntry(company: QuickBooksCompany, entry: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
99
109
|
}
|
|
100
110
|
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();
|
|
@@ -318,5 +326,12 @@ class QuickBooksGw extends BaseExternalApiGateway {
|
|
|
318
326
|
createPurchase(company, purchase, requestId) {
|
|
319
327
|
return this.create(company, 'Purchase', purchase, requestId);
|
|
320
328
|
}
|
|
329
|
+
/**
|
|
330
|
+
* A journal entry (the body as Intuit takes it — `Line` of `JournalEntryLineDetail` debits and credits, which must
|
|
331
|
+
* balance). Unlike a Purchase it may draw on any account type: a fee kept out of an Undeposited Funds deposit, say.
|
|
332
|
+
*/
|
|
333
|
+
createJournalEntry(company, entry, requestId) {
|
|
334
|
+
return this.create(company, 'JournalEntry', entry, requestId);
|
|
335
|
+
}
|
|
321
336
|
}
|
|
322
337
|
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: {
|
|
@@ -96,5 +101,10 @@ declare class QuickBooksGw extends BaseExternalApiGateway<QuickBooksSettings> {
|
|
|
96
101
|
createRefundReceipt(company: QuickBooksCompany, receipt: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
97
102
|
/** Money that went out of an account — a processor's or a platform's fee (`AccountRef` it left, expense lines). */
|
|
98
103
|
createPurchase(company: QuickBooksCompany, purchase: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
104
|
+
/**
|
|
105
|
+
* A journal entry (the body as Intuit takes it — `Line` of `JournalEntryLineDetail` debits and credits, which must
|
|
106
|
+
* balance). Unlike a Purchase it may draw on any account type: a fee kept out of an Undeposited Funds deposit, say.
|
|
107
|
+
*/
|
|
108
|
+
createJournalEntry(company: QuickBooksCompany, entry: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
99
109
|
}
|
|
100
110
|
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();
|
|
@@ -323,5 +331,12 @@ class QuickBooksGw extends BaseExternalApiGateway_1.BaseExternalApiGateway {
|
|
|
323
331
|
createPurchase(company, purchase, requestId) {
|
|
324
332
|
return this.create(company, 'Purchase', purchase, requestId);
|
|
325
333
|
}
|
|
334
|
+
/**
|
|
335
|
+
* A journal entry (the body as Intuit takes it — `Line` of `JournalEntryLineDetail` debits and credits, which must
|
|
336
|
+
* balance). Unlike a Purchase it may draw on any account type: a fee kept out of an Undeposited Funds deposit, say.
|
|
337
|
+
*/
|
|
338
|
+
createJournalEntry(company, entry, requestId) {
|
|
339
|
+
return this.create(company, 'JournalEntry', entry, requestId);
|
|
340
|
+
}
|
|
326
341
|
}
|
|
327
342
|
exports.QuickBooksGw = QuickBooksGw;
|