@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`, `createRefundReceipt`, `createPurchase` (a fee leaving an account).
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
- tokensOf(body) {
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 refreshToken = text(body?.refresh_token);
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) — the new tokens are not
156
- // among them, so they arrive intact.
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
- tokensOf(body) {
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 refreshToken = text(body?.refresh_token);
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) — the new tokens are not
161
- // among them, so they arrive intact.
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;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sdflc/backend-helpers",
3
- "version": "1.0.146",
3
+ "version": "1.0.148",
4
4
  "description": "Set of helper functions and classes to simplify building backend apps within @sdflc ecosystem",
5
5
  "type": "commonjs",
6
6
  "exports": {