@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
- 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();
@@ -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
- 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();
@@ -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;
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.147",
4
4
  "description": "Set of helper functions and classes to simplify building backend apps within @sdflc ecosystem",
5
5
  "type": "commonjs",
6
6
  "exports": {