@sdflc/backend-helpers 1.0.147 → 1.0.149
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 +1 -1
- package/build/esm/gateways/GoogleSheetsGw.d.ts +85 -0
- package/build/esm/gateways/GoogleSheetsGw.js +302 -0
- package/build/esm/gateways/QuickBooksGw.d.ts +1 -0
- package/build/esm/gateways/QuickBooksGw.js +6 -0
- package/build/esm/gateways/index.d.ts +1 -0
- package/build/esm/gateways/index.js +1 -0
- package/build/gateways/GoogleSheetsGw.d.ts +85 -0
- package/build/gateways/GoogleSheetsGw.js +309 -0
- package/build/gateways/QuickBooksGw.d.ts +1 -0
- package/build/gateways/QuickBooksGw.js +6 -0
- package/build/gateways/index.d.ts +1 -0
- package/build/gateways/index.js +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -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
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { OpResult } from '@sdflc/api-helpers';
|
|
2
|
+
import { BaseExternalApiGatewayPropsInterface } from '../interfaces';
|
|
3
|
+
import { BaseExternalApiGateway, ExternalApiReply } from './BaseExternalApiGateway';
|
|
4
|
+
export interface GoogleSheetsSettings {
|
|
5
|
+
/** The service account's email (`…@<project>.iam.gserviceaccount.com`) — what the host shares the sheet with. */
|
|
6
|
+
clientEmail: string;
|
|
7
|
+
/** The service account's private key (PEM, as in its JSON key; `\n` escapes are read as line breaks). */
|
|
8
|
+
privateKey: string;
|
|
9
|
+
}
|
|
10
|
+
/** A tab as `getSpreadsheet` names it. */
|
|
11
|
+
export interface GoogleSheetTab {
|
|
12
|
+
sheetId: number;
|
|
13
|
+
title: string;
|
|
14
|
+
index: number;
|
|
15
|
+
rowCount: number;
|
|
16
|
+
columnCount: number;
|
|
17
|
+
frozenRowCount: number;
|
|
18
|
+
}
|
|
19
|
+
/** A spreadsheet as `getSpreadsheet` answers it. */
|
|
20
|
+
export interface GoogleSpreadsheet {
|
|
21
|
+
spreadsheetId: string;
|
|
22
|
+
title: string;
|
|
23
|
+
tabs: GoogleSheetTab[];
|
|
24
|
+
}
|
|
25
|
+
/** One range to write: an A1 range (`googleSheetRange`) and its rows. */
|
|
26
|
+
export interface GoogleSheetValues {
|
|
27
|
+
range: string;
|
|
28
|
+
values: unknown[][];
|
|
29
|
+
}
|
|
30
|
+
export declare const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
|
|
31
|
+
export declare const GOOGLE_SHEETS_API_URL = "https://sheets.googleapis.com/v4/spreadsheets";
|
|
32
|
+
/** The only scope the writer needs — the spreadsheets shared with the account, nothing else of the host's Drive. */
|
|
33
|
+
export declare const GOOGLE_SHEETS_SCOPE = "https://www.googleapis.com/auth/spreadsheets";
|
|
34
|
+
/**
|
|
35
|
+
* The spreadsheet id in what a host pasted — the address of the sheet (`…/spreadsheets/d/<id>/edit#gid=0`) or the id
|
|
36
|
+
* itself — or '' when it is neither. Pure.
|
|
37
|
+
*/
|
|
38
|
+
export declare const googleSpreadsheetIdOf: (raw: unknown) => string;
|
|
39
|
+
/** A tab's name inside an A1 range: always quoted, a quote doubled (`It's` → `'It''s'`). Pure. */
|
|
40
|
+
export declare const googleSheetRange: (title: string, a1?: string) => string;
|
|
41
|
+
/** A column's letters from its 1-based number (1 → A, 27 → AA). Pure. */
|
|
42
|
+
export declare const googleSheetColumn: (n: number) => string;
|
|
43
|
+
/** Forget every cached access token (a test; a key revoked). */
|
|
44
|
+
export declare const forgetGoogleSheetsTokens: () => void;
|
|
45
|
+
declare class GoogleSheetsGw extends BaseExternalApiGateway<GoogleSheetsSettings> {
|
|
46
|
+
constructor(props?: BaseExternalApiGatewayPropsInterface<GoogleSheetsSettings>);
|
|
47
|
+
protected validateSettings(settings: Partial<GoogleSheetsSettings>): string[];
|
|
48
|
+
protected secretValues(): string[];
|
|
49
|
+
/** Google's error shapes: the API's `{ error: { code, message, status } }`, the token endpoint's `{ error, error_description }`. */
|
|
50
|
+
protected errorMessageOf(reply: ExternalApiReply): string;
|
|
51
|
+
private pemOf;
|
|
52
|
+
private cacheKey;
|
|
53
|
+
/** The signed assertion a token is asked for with, or null when the key cannot sign. */
|
|
54
|
+
private assertion;
|
|
55
|
+
/**
|
|
56
|
+
* A live access token for the account — the cached one, else a new one from Google (`fresh`: never the cached one).
|
|
57
|
+
* OK with `{ accessToken, expiresAt }`. Never throws.
|
|
58
|
+
*/
|
|
59
|
+
accessToken(fresh?: boolean): Promise<OpResult>;
|
|
60
|
+
/** One API call with the account's token; a 401 forgets it and tries once more with a new one. */
|
|
61
|
+
private call;
|
|
62
|
+
private badId;
|
|
63
|
+
/**
|
|
64
|
+
* The spreadsheet's title and tabs (each with its size and frozen rows) — readable only when it is shared with the
|
|
65
|
+
* account (403 FORBIDDEN otherwise; 404 NOT_FOUND when there is no such spreadsheet). OK with a `GoogleSpreadsheet`.
|
|
66
|
+
*/
|
|
67
|
+
getSpreadsheet(spreadsheetId: string): Promise<OpResult>;
|
|
68
|
+
/**
|
|
69
|
+
* The values of several ranges in ONE read, in the order asked, row by row, unformatted (a number stays a number);
|
|
70
|
+
* trailing empty cells and rows are left out, as Google does. OK with `{ valueRanges: [{ range, values }] }`.
|
|
71
|
+
*/
|
|
72
|
+
batchGetValues(spreadsheetId: string, ranges: string[]): Promise<OpResult>;
|
|
73
|
+
/**
|
|
74
|
+
* Structural changes in ONE request, all or none (add a tab, grow one, freeze its header, format cells) — Google's
|
|
75
|
+
* `spreadsheets.batchUpdate` requests as given. OK with `{ replies }`.
|
|
76
|
+
*/
|
|
77
|
+
batchUpdate(spreadsheetId: string, requests: Record<string, unknown>[]): Promise<OpResult>;
|
|
78
|
+
/**
|
|
79
|
+
* Many ranges written in ONE request, all or none — RAW unless told otherwise (nothing typed becomes a formula, a
|
|
80
|
+
* date or a number it was not). A range past the tab's size is refused by Google: grow the tab first (`batchUpdate`
|
|
81
|
+
* with `appendDimension`). OK with `{ updatedCells, updatedRanges }`.
|
|
82
|
+
*/
|
|
83
|
+
batchUpdateValues(spreadsheetId: string, data: GoogleSheetValues[], valueInputOption?: 'RAW' | 'USER_ENTERED'): Promise<OpResult>;
|
|
84
|
+
}
|
|
85
|
+
export { GoogleSheetsGw };
|
|
@@ -0,0 +1,302 @@
|
|
|
1
|
+
// ./src/gateways/GoogleSheetsGw.ts
|
|
2
|
+
//
|
|
3
|
+
// Google Sheets (https://developers.google.com/workspace/sheets/api/reference/rest) as a SERVICE ACCOUNT — the calls that
|
|
4
|
+
// keep a spreadsheet the host shared with us up to date: what tabs it has, the cells a write needs to see (a header row,
|
|
5
|
+
// an id column), tabs added or grown, and many ranges written in one request.
|
|
6
|
+
//
|
|
7
|
+
// const sheets = new GoogleSheetsGw().configure({ clientEmail, privateKey }); // from the service account's JSON key
|
|
8
|
+
// const book = await sheets.getSpreadsheet(googleSpreadsheetIdOf(pastedUrl));
|
|
9
|
+
// await sheets.batchUpdate(id, [{ addSheet: { properties: { title: 'Guests' } } }]);
|
|
10
|
+
// await sheets.batchUpdateValues(id, [{ range: googleSheetRange('Guests', 'A1'), values: [['ID', 'Name']] }]);
|
|
11
|
+
//
|
|
12
|
+
// The host shares their spreadsheet with the service account's email (as Editor); nothing else is needed on their side —
|
|
13
|
+
// no OAuth, no consent screen. The gateway signs a JWT with the account's private key and trades it for an access token
|
|
14
|
+
// (an hour), kept per account in this process and renewed a minute before it ends.
|
|
15
|
+
//
|
|
16
|
+
// ⚠ The private key, the signed assertion and every access token are scrubbed out of every error and reply.
|
|
17
|
+
// ⚠ Values are written RAW by default: a guest named `=IMPORTXML(…)` stays text, never a formula in the host's sheet.
|
|
18
|
+
// ⚠ QUOTA: Google counts a service account as ONE user — 60 reads and 60 writes a minute for every spreadsheet it writes,
|
|
19
|
+
// whoever owns them (a batch is one request). Pacing is the caller's; a 429 is TOO_MANY_REQUESTS.
|
|
20
|
+
// ⚠ A call refused with 401 forgets the cached token and is tried once more with a new one (a key rotated meanwhile).
|
|
21
|
+
import { Buffer } from 'buffer';
|
|
22
|
+
import { createHash, createSign } from 'crypto';
|
|
23
|
+
import { OP_RESULT_CODES, OpResult } from '@sdflc/api-helpers';
|
|
24
|
+
import { BaseExternalApiGateway } from './BaseExternalApiGateway';
|
|
25
|
+
export const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
|
|
26
|
+
export const GOOGLE_SHEETS_API_URL = 'https://sheets.googleapis.com/v4/spreadsheets';
|
|
27
|
+
/** The only scope the writer needs — the spreadsheets shared with the account, nothing else of the host's Drive. */
|
|
28
|
+
export const GOOGLE_SHEETS_SCOPE = 'https://www.googleapis.com/auth/spreadsheets';
|
|
29
|
+
/** How long before its end a cached token is replaced. */
|
|
30
|
+
const TOKEN_MARGIN_MS = 60_000;
|
|
31
|
+
const text = (value) => String(value ?? '').trim();
|
|
32
|
+
const base64Url = (value) => Buffer.from(value).toString('base64').replace(/=+$/, '').replace(/\+/g, '-').replace(/\//g, '_');
|
|
33
|
+
/** A spreadsheet id: Google's are 44 characters of letters, digits, `-` and `_` (accepted from 20 to 128). */
|
|
34
|
+
const SPREADSHEET_ID = /^[A-Za-z0-9_-]{20,128}$/;
|
|
35
|
+
/**
|
|
36
|
+
* The spreadsheet id in what a host pasted — the address of the sheet (`…/spreadsheets/d/<id>/edit#gid=0`) or the id
|
|
37
|
+
* itself — or '' when it is neither. Pure.
|
|
38
|
+
*/
|
|
39
|
+
export const googleSpreadsheetIdOf = (raw) => {
|
|
40
|
+
const value = text(raw);
|
|
41
|
+
const inUrl = /\/spreadsheets\/d\/([A-Za-z0-9_-]+)/.exec(value);
|
|
42
|
+
const id = inUrl ? inUrl[1] : value;
|
|
43
|
+
return SPREADSHEET_ID.test(id) ? id : '';
|
|
44
|
+
};
|
|
45
|
+
/** A tab's name inside an A1 range: always quoted, a quote doubled (`It's` → `'It''s'`). Pure. */
|
|
46
|
+
export const googleSheetRange = (title, a1 = '') => {
|
|
47
|
+
const quoted = `'${String(title ?? '').replace(/'/g, "''")}'`;
|
|
48
|
+
return a1 ? `${quoted}!${a1}` : quoted;
|
|
49
|
+
};
|
|
50
|
+
/** A column's letters from its 1-based number (1 → A, 27 → AA). Pure. */
|
|
51
|
+
export const googleSheetColumn = (n) => {
|
|
52
|
+
let left = Math.max(1, Math.floor(Number(n) || 1));
|
|
53
|
+
let out = '';
|
|
54
|
+
while (left > 0) {
|
|
55
|
+
const rem = (left - 1) % 26;
|
|
56
|
+
out = String.fromCharCode(65 + rem) + out;
|
|
57
|
+
left = Math.floor((left - 1) / 26);
|
|
58
|
+
}
|
|
59
|
+
return out;
|
|
60
|
+
};
|
|
61
|
+
/** Access tokens by service account (a fingerprint of its email and key) — every gateway in the process shares them. */
|
|
62
|
+
const tokens = new Map();
|
|
63
|
+
/** Forget every cached access token (a test; a key revoked). */
|
|
64
|
+
export const forgetGoogleSheetsTokens = () => {
|
|
65
|
+
tokens.clear();
|
|
66
|
+
};
|
|
67
|
+
class GoogleSheetsGw extends BaseExternalApiGateway {
|
|
68
|
+
constructor(props) {
|
|
69
|
+
super({ baseUrl: GOOGLE_SHEETS_API_URL, ...(props ?? {}) });
|
|
70
|
+
}
|
|
71
|
+
validateSettings(settings) {
|
|
72
|
+
const problems = [];
|
|
73
|
+
if (!/^[^@\s]+@[^@\s]+\.iam\.gserviceaccount\.com$/i.test(text(settings.clientEmail))) {
|
|
74
|
+
problems.push('the client email is missing or not a service account (…@….iam.gserviceaccount.com)');
|
|
75
|
+
}
|
|
76
|
+
if (!/-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(this.pemOf(settings.privateKey))) {
|
|
77
|
+
problems.push('the private key is missing or not a PEM key');
|
|
78
|
+
}
|
|
79
|
+
return problems;
|
|
80
|
+
}
|
|
81
|
+
secretValues() {
|
|
82
|
+
const pem = this.pemOf(this.settings.privateKey);
|
|
83
|
+
// The key's body lines too: a reply never carries the PEM whole, but an echo of a line must not leave either.
|
|
84
|
+
const lines = pem.split('\n').filter((line) => line.length >= 16 && !line.startsWith('-----'));
|
|
85
|
+
return pem ? [pem, text(this.settings.privateKey), ...lines] : [];
|
|
86
|
+
}
|
|
87
|
+
/** Google's error shapes: the API's `{ error: { code, message, status } }`, the token endpoint's `{ error, error_description }`. */
|
|
88
|
+
errorMessageOf(reply) {
|
|
89
|
+
const body = reply.body;
|
|
90
|
+
if (body && typeof body === 'object') {
|
|
91
|
+
if (body.error && typeof body.error === 'object') {
|
|
92
|
+
return ([body.error.status, body.error.message].filter(Boolean).join(': ').slice(0, 500) || `HTTP ${reply.status}`);
|
|
93
|
+
}
|
|
94
|
+
if (typeof body.error === 'string') {
|
|
95
|
+
return [body.error, body.error_description].filter(Boolean).join(': ').slice(0, 500);
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
return super.errorMessageOf(reply);
|
|
99
|
+
}
|
|
100
|
+
pemOf(raw) {
|
|
101
|
+
return text(raw).replace(/\\n/g, '\n');
|
|
102
|
+
}
|
|
103
|
+
cacheKey() {
|
|
104
|
+
return createHash('sha256')
|
|
105
|
+
.update(`${text(this.settings.clientEmail).toLowerCase()}\n${this.pemOf(this.settings.privateKey)}`)
|
|
106
|
+
.digest('hex');
|
|
107
|
+
}
|
|
108
|
+
/** The signed assertion a token is asked for with, or null when the key cannot sign. */
|
|
109
|
+
assertion(nowMs) {
|
|
110
|
+
const iat = Math.floor(nowMs / 1000);
|
|
111
|
+
const head = base64Url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
|
|
112
|
+
const claims = base64Url(JSON.stringify({
|
|
113
|
+
iss: text(this.settings.clientEmail),
|
|
114
|
+
scope: GOOGLE_SHEETS_SCOPE,
|
|
115
|
+
aud: GOOGLE_TOKEN_URL,
|
|
116
|
+
iat,
|
|
117
|
+
exp: iat + 3600,
|
|
118
|
+
}));
|
|
119
|
+
try {
|
|
120
|
+
const signature = createSign('RSA-SHA256').update(`${head}.${claims}`).sign(this.pemOf(this.settings.privateKey));
|
|
121
|
+
return `${head}.${claims}.${base64Url(signature)}`;
|
|
122
|
+
}
|
|
123
|
+
catch {
|
|
124
|
+
return null;
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* A live access token for the account — the cached one, else a new one from Google (`fresh`: never the cached one).
|
|
129
|
+
* OK with `{ accessToken, expiresAt }`. Never throws.
|
|
130
|
+
*/
|
|
131
|
+
async accessToken(fresh = false) {
|
|
132
|
+
if (!this.isConfigured()) {
|
|
133
|
+
return this.notConfigured();
|
|
134
|
+
}
|
|
135
|
+
const key = this.cacheKey();
|
|
136
|
+
const now = Date.now();
|
|
137
|
+
const cached = tokens.get(key);
|
|
138
|
+
if (!fresh && cached && cached.until - TOKEN_MARGIN_MS > now) {
|
|
139
|
+
return OpResult.ok([{ accessToken: cached.token, expiresAt: new Date(cached.until).toISOString() }]);
|
|
140
|
+
}
|
|
141
|
+
const jwt = this.assertion(now);
|
|
142
|
+
if (!jwt) {
|
|
143
|
+
return OpResult.fail(OP_RESULT_CODES.VALIDATION_FAILED, null, 'The private key could not sign (is it the whole key from the JSON file?)');
|
|
144
|
+
}
|
|
145
|
+
const result = await this.requestWithRetries({
|
|
146
|
+
url: GOOGLE_TOKEN_URL,
|
|
147
|
+
method: 'POST',
|
|
148
|
+
headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
|
|
149
|
+
body: new URLSearchParams({ grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer', assertion: jwt }),
|
|
150
|
+
secrets: [jwt],
|
|
151
|
+
});
|
|
152
|
+
if (result.didFail()) {
|
|
153
|
+
tokens.delete(key);
|
|
154
|
+
return result;
|
|
155
|
+
}
|
|
156
|
+
// ⓘ The reply is scrubbed of the request's secrets only — the token itself is new, so it arrives whole.
|
|
157
|
+
const body = result.getDataFirst()?.body ?? {};
|
|
158
|
+
const accessToken = text(body.access_token);
|
|
159
|
+
if (!accessToken) {
|
|
160
|
+
return OpResult.fail(OP_RESULT_CODES.FAILED, null, 'Google answered without an access token');
|
|
161
|
+
}
|
|
162
|
+
const until = now + (Number(body.expires_in) > 0 ? Number(body.expires_in) : 3600) * 1000;
|
|
163
|
+
tokens.set(key, { token: accessToken, until });
|
|
164
|
+
return OpResult.ok([{ accessToken, expiresAt: new Date(until).toISOString() }]);
|
|
165
|
+
}
|
|
166
|
+
/** One API call with the account's token; a 401 forgets it and tries once more with a new one. */
|
|
167
|
+
async call(method, path, json) {
|
|
168
|
+
let result = OpResult.fail(OP_RESULT_CODES.FAILED, null, 'Not called');
|
|
169
|
+
for (let attempt = 0; attempt < 2; attempt++) {
|
|
170
|
+
const token = await this.accessToken(attempt > 0);
|
|
171
|
+
if (token.didFail()) {
|
|
172
|
+
return token;
|
|
173
|
+
}
|
|
174
|
+
const accessToken = String(token.getDataFirst().accessToken);
|
|
175
|
+
result = await this.requestWithRetries({
|
|
176
|
+
url: `${this.baseUrl}${path}`,
|
|
177
|
+
method,
|
|
178
|
+
headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
|
|
179
|
+
...(json === undefined ? {} : { json }),
|
|
180
|
+
secrets: [accessToken],
|
|
181
|
+
});
|
|
182
|
+
if (result.getCode() !== OP_RESULT_CODES.UNAUTHORIZED) {
|
|
183
|
+
return result;
|
|
184
|
+
}
|
|
185
|
+
tokens.delete(this.cacheKey());
|
|
186
|
+
}
|
|
187
|
+
return result;
|
|
188
|
+
}
|
|
189
|
+
badId(spreadsheetId) {
|
|
190
|
+
return SPREADSHEET_ID.test(text(spreadsheetId))
|
|
191
|
+
? null
|
|
192
|
+
: OpResult.fail(OP_RESULT_CODES.VALIDATION_FAILED, null, 'The spreadsheet id is not one');
|
|
193
|
+
}
|
|
194
|
+
/**
|
|
195
|
+
* The spreadsheet's title and tabs (each with its size and frozen rows) — readable only when it is shared with the
|
|
196
|
+
* account (403 FORBIDDEN otherwise; 404 NOT_FOUND when there is no such spreadsheet). OK with a `GoogleSpreadsheet`.
|
|
197
|
+
*/
|
|
198
|
+
async getSpreadsheet(spreadsheetId) {
|
|
199
|
+
if (!this.isConfigured()) {
|
|
200
|
+
return this.notConfigured();
|
|
201
|
+
}
|
|
202
|
+
const bad = this.badId(spreadsheetId);
|
|
203
|
+
if (bad) {
|
|
204
|
+
return bad;
|
|
205
|
+
}
|
|
206
|
+
const fields = 'spreadsheetId,properties.title,sheets.properties(sheetId,title,index,gridProperties(rowCount,columnCount,frozenRowCount))';
|
|
207
|
+
const result = await this.call('GET', `/${text(spreadsheetId)}?fields=${encodeURIComponent(fields)}`);
|
|
208
|
+
if (result.didFail()) {
|
|
209
|
+
return result;
|
|
210
|
+
}
|
|
211
|
+
const body = result.getDataFirst()?.body ?? {};
|
|
212
|
+
const book = {
|
|
213
|
+
spreadsheetId: text(body.spreadsheetId) || text(spreadsheetId),
|
|
214
|
+
title: text(body.properties?.title),
|
|
215
|
+
tabs: (Array.isArray(body.sheets) ? body.sheets : []).map((s) => ({
|
|
216
|
+
sheetId: Number(s?.properties?.sheetId) || 0,
|
|
217
|
+
title: String(s?.properties?.title ?? ''),
|
|
218
|
+
index: Number(s?.properties?.index) || 0,
|
|
219
|
+
rowCount: Number(s?.properties?.gridProperties?.rowCount) || 0,
|
|
220
|
+
columnCount: Number(s?.properties?.gridProperties?.columnCount) || 0,
|
|
221
|
+
frozenRowCount: Number(s?.properties?.gridProperties?.frozenRowCount) || 0,
|
|
222
|
+
})),
|
|
223
|
+
};
|
|
224
|
+
return OpResult.ok([book]);
|
|
225
|
+
}
|
|
226
|
+
/**
|
|
227
|
+
* The values of several ranges in ONE read, in the order asked, row by row, unformatted (a number stays a number);
|
|
228
|
+
* trailing empty cells and rows are left out, as Google does. OK with `{ valueRanges: [{ range, values }] }`.
|
|
229
|
+
*/
|
|
230
|
+
async batchGetValues(spreadsheetId, ranges) {
|
|
231
|
+
if (!this.isConfigured()) {
|
|
232
|
+
return this.notConfigured();
|
|
233
|
+
}
|
|
234
|
+
const bad = this.badId(spreadsheetId);
|
|
235
|
+
const wanted = (ranges ?? []).map((r) => String(r ?? '')).filter(Boolean);
|
|
236
|
+
if (bad || wanted.length === 0) {
|
|
237
|
+
return bad ?? OpResult.fail(OP_RESULT_CODES.VALIDATION_FAILED, null, 'At least one range is needed');
|
|
238
|
+
}
|
|
239
|
+
const params = new URLSearchParams();
|
|
240
|
+
for (const range of wanted) {
|
|
241
|
+
params.append('ranges', range);
|
|
242
|
+
}
|
|
243
|
+
params.set('majorDimension', 'ROWS');
|
|
244
|
+
params.set('valueRenderOption', 'UNFORMATTED_VALUE');
|
|
245
|
+
const result = await this.call('GET', `/${text(spreadsheetId)}/values:batchGet?${params.toString()}`);
|
|
246
|
+
if (result.didFail()) {
|
|
247
|
+
return result;
|
|
248
|
+
}
|
|
249
|
+
const got = result.getDataFirst()?.body?.valueRanges;
|
|
250
|
+
const valueRanges = wanted.map((range, i) => ({
|
|
251
|
+
range,
|
|
252
|
+
values: Array.isArray(got?.[i]?.values) ? got[i].values : [],
|
|
253
|
+
}));
|
|
254
|
+
return OpResult.ok([{ valueRanges }]);
|
|
255
|
+
}
|
|
256
|
+
/**
|
|
257
|
+
* Structural changes in ONE request, all or none (add a tab, grow one, freeze its header, format cells) — Google's
|
|
258
|
+
* `spreadsheets.batchUpdate` requests as given. OK with `{ replies }`.
|
|
259
|
+
*/
|
|
260
|
+
async batchUpdate(spreadsheetId, requests) {
|
|
261
|
+
if (!this.isConfigured()) {
|
|
262
|
+
return this.notConfigured();
|
|
263
|
+
}
|
|
264
|
+
const bad = this.badId(spreadsheetId);
|
|
265
|
+
const list = (requests ?? []).filter((r) => r && typeof r === 'object');
|
|
266
|
+
if (bad || list.length === 0) {
|
|
267
|
+
return bad ?? OpResult.fail(OP_RESULT_CODES.VALIDATION_FAILED, null, 'At least one request is needed');
|
|
268
|
+
}
|
|
269
|
+
const result = await this.call('POST', `/${text(spreadsheetId)}:batchUpdate`, { requests: list });
|
|
270
|
+
return result.didFail() ? result : OpResult.ok([{ replies: result.getDataFirst()?.body?.replies ?? [] }]);
|
|
271
|
+
}
|
|
272
|
+
/**
|
|
273
|
+
* Many ranges written in ONE request, all or none — RAW unless told otherwise (nothing typed becomes a formula, a
|
|
274
|
+
* date or a number it was not). A range past the tab's size is refused by Google: grow the tab first (`batchUpdate`
|
|
275
|
+
* with `appendDimension`). OK with `{ updatedCells, updatedRanges }`.
|
|
276
|
+
*/
|
|
277
|
+
async batchUpdateValues(spreadsheetId, data, valueInputOption = 'RAW') {
|
|
278
|
+
if (!this.isConfigured()) {
|
|
279
|
+
return this.notConfigured();
|
|
280
|
+
}
|
|
281
|
+
const bad = this.badId(spreadsheetId);
|
|
282
|
+
const list = (data ?? []).filter((d) => text(d?.range) && Array.isArray(d?.values));
|
|
283
|
+
if (bad || list.length === 0) {
|
|
284
|
+
return bad ?? OpResult.fail(OP_RESULT_CODES.VALIDATION_FAILED, null, 'At least one range with values is needed');
|
|
285
|
+
}
|
|
286
|
+
const result = await this.call('POST', `/${text(spreadsheetId)}/values:batchUpdate`, {
|
|
287
|
+
valueInputOption: valueInputOption === 'USER_ENTERED' ? 'USER_ENTERED' : 'RAW',
|
|
288
|
+
data: list.map((d) => ({ range: d.range, majorDimension: 'ROWS', values: d.values })),
|
|
289
|
+
});
|
|
290
|
+
if (result.didFail()) {
|
|
291
|
+
return result;
|
|
292
|
+
}
|
|
293
|
+
const body = result.getDataFirst()?.body ?? {};
|
|
294
|
+
return OpResult.ok([
|
|
295
|
+
{
|
|
296
|
+
updatedCells: Number(body.totalUpdatedCells) || 0,
|
|
297
|
+
updatedRanges: (body.responses ?? []).length || list.length,
|
|
298
|
+
},
|
|
299
|
+
]);
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
export { GoogleSheetsGw };
|
|
@@ -94,6 +94,7 @@ declare class QuickBooksGw extends BaseExternalApiGateway<QuickBooksSettings> {
|
|
|
94
94
|
createCustomer(company: QuickBooksCompany, customer: {
|
|
95
95
|
displayName: string;
|
|
96
96
|
email?: string | null;
|
|
97
|
+
currency?: string | null;
|
|
97
98
|
}, requestId: string): Promise<OpResult>;
|
|
98
99
|
/** A sale paid at once (the body as Intuit takes it — `Line`, `DepositToAccountRef`, …). */
|
|
99
100
|
createSalesReceipt(company: QuickBooksCompany, receipt: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
@@ -306,12 +306,18 @@ class QuickBooksGw extends BaseExternalApiGateway {
|
|
|
306
306
|
/** A customer by display name (unique in the company across customers, vendors and employees). */
|
|
307
307
|
createCustomer(company, customer, requestId) {
|
|
308
308
|
const displayName = quickBooksNameOf(customer?.displayName);
|
|
309
|
+
const currency = text(customer?.currency).toUpperCase();
|
|
309
310
|
if (!displayName) {
|
|
310
311
|
return Promise.resolve(OpResult.fail(OP_RESULT_CODES.VALIDATION_FAILED, null, 'A customer needs a name'));
|
|
311
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
|
+
}
|
|
312
316
|
return this.create(company, 'Customer', {
|
|
313
317
|
DisplayName: displayName,
|
|
314
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 } } : {}),
|
|
315
321
|
}, requestId);
|
|
316
322
|
}
|
|
317
323
|
/** A sale paid at once (the body as Intuit takes it — `Line`, `DepositToAccountRef`, …). */
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { OpResult } from '@sdflc/api-helpers';
|
|
2
|
+
import { BaseExternalApiGatewayPropsInterface } from '../interfaces';
|
|
3
|
+
import { BaseExternalApiGateway, ExternalApiReply } from './BaseExternalApiGateway';
|
|
4
|
+
export interface GoogleSheetsSettings {
|
|
5
|
+
/** The service account's email (`…@<project>.iam.gserviceaccount.com`) — what the host shares the sheet with. */
|
|
6
|
+
clientEmail: string;
|
|
7
|
+
/** The service account's private key (PEM, as in its JSON key; `\n` escapes are read as line breaks). */
|
|
8
|
+
privateKey: string;
|
|
9
|
+
}
|
|
10
|
+
/** A tab as `getSpreadsheet` names it. */
|
|
11
|
+
export interface GoogleSheetTab {
|
|
12
|
+
sheetId: number;
|
|
13
|
+
title: string;
|
|
14
|
+
index: number;
|
|
15
|
+
rowCount: number;
|
|
16
|
+
columnCount: number;
|
|
17
|
+
frozenRowCount: number;
|
|
18
|
+
}
|
|
19
|
+
/** A spreadsheet as `getSpreadsheet` answers it. */
|
|
20
|
+
export interface GoogleSpreadsheet {
|
|
21
|
+
spreadsheetId: string;
|
|
22
|
+
title: string;
|
|
23
|
+
tabs: GoogleSheetTab[];
|
|
24
|
+
}
|
|
25
|
+
/** One range to write: an A1 range (`googleSheetRange`) and its rows. */
|
|
26
|
+
export interface GoogleSheetValues {
|
|
27
|
+
range: string;
|
|
28
|
+
values: unknown[][];
|
|
29
|
+
}
|
|
30
|
+
export declare const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
|
|
31
|
+
export declare const GOOGLE_SHEETS_API_URL = "https://sheets.googleapis.com/v4/spreadsheets";
|
|
32
|
+
/** The only scope the writer needs — the spreadsheets shared with the account, nothing else of the host's Drive. */
|
|
33
|
+
export declare const GOOGLE_SHEETS_SCOPE = "https://www.googleapis.com/auth/spreadsheets";
|
|
34
|
+
/**
|
|
35
|
+
* The spreadsheet id in what a host pasted — the address of the sheet (`…/spreadsheets/d/<id>/edit#gid=0`) or the id
|
|
36
|
+
* itself — or '' when it is neither. Pure.
|
|
37
|
+
*/
|
|
38
|
+
export declare const googleSpreadsheetIdOf: (raw: unknown) => string;
|
|
39
|
+
/** A tab's name inside an A1 range: always quoted, a quote doubled (`It's` → `'It''s'`). Pure. */
|
|
40
|
+
export declare const googleSheetRange: (title: string, a1?: string) => string;
|
|
41
|
+
/** A column's letters from its 1-based number (1 → A, 27 → AA). Pure. */
|
|
42
|
+
export declare const googleSheetColumn: (n: number) => string;
|
|
43
|
+
/** Forget every cached access token (a test; a key revoked). */
|
|
44
|
+
export declare const forgetGoogleSheetsTokens: () => void;
|
|
45
|
+
declare class GoogleSheetsGw extends BaseExternalApiGateway<GoogleSheetsSettings> {
|
|
46
|
+
constructor(props?: BaseExternalApiGatewayPropsInterface<GoogleSheetsSettings>);
|
|
47
|
+
protected validateSettings(settings: Partial<GoogleSheetsSettings>): string[];
|
|
48
|
+
protected secretValues(): string[];
|
|
49
|
+
/** Google's error shapes: the API's `{ error: { code, message, status } }`, the token endpoint's `{ error, error_description }`. */
|
|
50
|
+
protected errorMessageOf(reply: ExternalApiReply): string;
|
|
51
|
+
private pemOf;
|
|
52
|
+
private cacheKey;
|
|
53
|
+
/** The signed assertion a token is asked for with, or null when the key cannot sign. */
|
|
54
|
+
private assertion;
|
|
55
|
+
/**
|
|
56
|
+
* A live access token for the account — the cached one, else a new one from Google (`fresh`: never the cached one).
|
|
57
|
+
* OK with `{ accessToken, expiresAt }`. Never throws.
|
|
58
|
+
*/
|
|
59
|
+
accessToken(fresh?: boolean): Promise<OpResult>;
|
|
60
|
+
/** One API call with the account's token; a 401 forgets it and tries once more with a new one. */
|
|
61
|
+
private call;
|
|
62
|
+
private badId;
|
|
63
|
+
/**
|
|
64
|
+
* The spreadsheet's title and tabs (each with its size and frozen rows) — readable only when it is shared with the
|
|
65
|
+
* account (403 FORBIDDEN otherwise; 404 NOT_FOUND when there is no such spreadsheet). OK with a `GoogleSpreadsheet`.
|
|
66
|
+
*/
|
|
67
|
+
getSpreadsheet(spreadsheetId: string): Promise<OpResult>;
|
|
68
|
+
/**
|
|
69
|
+
* The values of several ranges in ONE read, in the order asked, row by row, unformatted (a number stays a number);
|
|
70
|
+
* trailing empty cells and rows are left out, as Google does. OK with `{ valueRanges: [{ range, values }] }`.
|
|
71
|
+
*/
|
|
72
|
+
batchGetValues(spreadsheetId: string, ranges: string[]): Promise<OpResult>;
|
|
73
|
+
/**
|
|
74
|
+
* Structural changes in ONE request, all or none (add a tab, grow one, freeze its header, format cells) — Google's
|
|
75
|
+
* `spreadsheets.batchUpdate` requests as given. OK with `{ replies }`.
|
|
76
|
+
*/
|
|
77
|
+
batchUpdate(spreadsheetId: string, requests: Record<string, unknown>[]): Promise<OpResult>;
|
|
78
|
+
/**
|
|
79
|
+
* Many ranges written in ONE request, all or none — RAW unless told otherwise (nothing typed becomes a formula, a
|
|
80
|
+
* date or a number it was not). A range past the tab's size is refused by Google: grow the tab first (`batchUpdate`
|
|
81
|
+
* with `appendDimension`). OK with `{ updatedCells, updatedRanges }`.
|
|
82
|
+
*/
|
|
83
|
+
batchUpdateValues(spreadsheetId: string, data: GoogleSheetValues[], valueInputOption?: 'RAW' | 'USER_ENTERED'): Promise<OpResult>;
|
|
84
|
+
}
|
|
85
|
+
export { GoogleSheetsGw };
|
|
@@ -0,0 +1,309 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.GoogleSheetsGw = exports.forgetGoogleSheetsTokens = exports.googleSheetColumn = exports.googleSheetRange = exports.googleSpreadsheetIdOf = exports.GOOGLE_SHEETS_SCOPE = exports.GOOGLE_SHEETS_API_URL = exports.GOOGLE_TOKEN_URL = void 0;
|
|
4
|
+
// ./src/gateways/GoogleSheetsGw.ts
|
|
5
|
+
//
|
|
6
|
+
// Google Sheets (https://developers.google.com/workspace/sheets/api/reference/rest) as a SERVICE ACCOUNT — the calls that
|
|
7
|
+
// keep a spreadsheet the host shared with us up to date: what tabs it has, the cells a write needs to see (a header row,
|
|
8
|
+
// an id column), tabs added or grown, and many ranges written in one request.
|
|
9
|
+
//
|
|
10
|
+
// const sheets = new GoogleSheetsGw().configure({ clientEmail, privateKey }); // from the service account's JSON key
|
|
11
|
+
// const book = await sheets.getSpreadsheet(googleSpreadsheetIdOf(pastedUrl));
|
|
12
|
+
// await sheets.batchUpdate(id, [{ addSheet: { properties: { title: 'Guests' } } }]);
|
|
13
|
+
// await sheets.batchUpdateValues(id, [{ range: googleSheetRange('Guests', 'A1'), values: [['ID', 'Name']] }]);
|
|
14
|
+
//
|
|
15
|
+
// The host shares their spreadsheet with the service account's email (as Editor); nothing else is needed on their side —
|
|
16
|
+
// no OAuth, no consent screen. The gateway signs a JWT with the account's private key and trades it for an access token
|
|
17
|
+
// (an hour), kept per account in this process and renewed a minute before it ends.
|
|
18
|
+
//
|
|
19
|
+
// ⚠ The private key, the signed assertion and every access token are scrubbed out of every error and reply.
|
|
20
|
+
// ⚠ Values are written RAW by default: a guest named `=IMPORTXML(…)` stays text, never a formula in the host's sheet.
|
|
21
|
+
// ⚠ QUOTA: Google counts a service account as ONE user — 60 reads and 60 writes a minute for every spreadsheet it writes,
|
|
22
|
+
// whoever owns them (a batch is one request). Pacing is the caller's; a 429 is TOO_MANY_REQUESTS.
|
|
23
|
+
// ⚠ A call refused with 401 forgets the cached token and is tried once more with a new one (a key rotated meanwhile).
|
|
24
|
+
const buffer_1 = require("buffer");
|
|
25
|
+
const crypto_1 = require("crypto");
|
|
26
|
+
const api_helpers_1 = require("@sdflc/api-helpers");
|
|
27
|
+
const BaseExternalApiGateway_1 = require("./BaseExternalApiGateway");
|
|
28
|
+
exports.GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
|
|
29
|
+
exports.GOOGLE_SHEETS_API_URL = 'https://sheets.googleapis.com/v4/spreadsheets';
|
|
30
|
+
/** The only scope the writer needs — the spreadsheets shared with the account, nothing else of the host's Drive. */
|
|
31
|
+
exports.GOOGLE_SHEETS_SCOPE = 'https://www.googleapis.com/auth/spreadsheets';
|
|
32
|
+
/** How long before its end a cached token is replaced. */
|
|
33
|
+
const TOKEN_MARGIN_MS = 60_000;
|
|
34
|
+
const text = (value) => String(value ?? '').trim();
|
|
35
|
+
const base64Url = (value) => buffer_1.Buffer.from(value).toString('base64').replace(/=+$/, '').replace(/\+/g, '-').replace(/\//g, '_');
|
|
36
|
+
/** A spreadsheet id: Google's are 44 characters of letters, digits, `-` and `_` (accepted from 20 to 128). */
|
|
37
|
+
const SPREADSHEET_ID = /^[A-Za-z0-9_-]{20,128}$/;
|
|
38
|
+
/**
|
|
39
|
+
* The spreadsheet id in what a host pasted — the address of the sheet (`…/spreadsheets/d/<id>/edit#gid=0`) or the id
|
|
40
|
+
* itself — or '' when it is neither. Pure.
|
|
41
|
+
*/
|
|
42
|
+
const googleSpreadsheetIdOf = (raw) => {
|
|
43
|
+
const value = text(raw);
|
|
44
|
+
const inUrl = /\/spreadsheets\/d\/([A-Za-z0-9_-]+)/.exec(value);
|
|
45
|
+
const id = inUrl ? inUrl[1] : value;
|
|
46
|
+
return SPREADSHEET_ID.test(id) ? id : '';
|
|
47
|
+
};
|
|
48
|
+
exports.googleSpreadsheetIdOf = googleSpreadsheetIdOf;
|
|
49
|
+
/** A tab's name inside an A1 range: always quoted, a quote doubled (`It's` → `'It''s'`). Pure. */
|
|
50
|
+
const googleSheetRange = (title, a1 = '') => {
|
|
51
|
+
const quoted = `'${String(title ?? '').replace(/'/g, "''")}'`;
|
|
52
|
+
return a1 ? `${quoted}!${a1}` : quoted;
|
|
53
|
+
};
|
|
54
|
+
exports.googleSheetRange = googleSheetRange;
|
|
55
|
+
/** A column's letters from its 1-based number (1 → A, 27 → AA). Pure. */
|
|
56
|
+
const googleSheetColumn = (n) => {
|
|
57
|
+
let left = Math.max(1, Math.floor(Number(n) || 1));
|
|
58
|
+
let out = '';
|
|
59
|
+
while (left > 0) {
|
|
60
|
+
const rem = (left - 1) % 26;
|
|
61
|
+
out = String.fromCharCode(65 + rem) + out;
|
|
62
|
+
left = Math.floor((left - 1) / 26);
|
|
63
|
+
}
|
|
64
|
+
return out;
|
|
65
|
+
};
|
|
66
|
+
exports.googleSheetColumn = googleSheetColumn;
|
|
67
|
+
/** Access tokens by service account (a fingerprint of its email and key) — every gateway in the process shares them. */
|
|
68
|
+
const tokens = new Map();
|
|
69
|
+
/** Forget every cached access token (a test; a key revoked). */
|
|
70
|
+
const forgetGoogleSheetsTokens = () => {
|
|
71
|
+
tokens.clear();
|
|
72
|
+
};
|
|
73
|
+
exports.forgetGoogleSheetsTokens = forgetGoogleSheetsTokens;
|
|
74
|
+
class GoogleSheetsGw extends BaseExternalApiGateway_1.BaseExternalApiGateway {
|
|
75
|
+
constructor(props) {
|
|
76
|
+
super({ baseUrl: exports.GOOGLE_SHEETS_API_URL, ...(props ?? {}) });
|
|
77
|
+
}
|
|
78
|
+
validateSettings(settings) {
|
|
79
|
+
const problems = [];
|
|
80
|
+
if (!/^[^@\s]+@[^@\s]+\.iam\.gserviceaccount\.com$/i.test(text(settings.clientEmail))) {
|
|
81
|
+
problems.push('the client email is missing or not a service account (…@….iam.gserviceaccount.com)');
|
|
82
|
+
}
|
|
83
|
+
if (!/-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(this.pemOf(settings.privateKey))) {
|
|
84
|
+
problems.push('the private key is missing or not a PEM key');
|
|
85
|
+
}
|
|
86
|
+
return problems;
|
|
87
|
+
}
|
|
88
|
+
secretValues() {
|
|
89
|
+
const pem = this.pemOf(this.settings.privateKey);
|
|
90
|
+
// The key's body lines too: a reply never carries the PEM whole, but an echo of a line must not leave either.
|
|
91
|
+
const lines = pem.split('\n').filter((line) => line.length >= 16 && !line.startsWith('-----'));
|
|
92
|
+
return pem ? [pem, text(this.settings.privateKey), ...lines] : [];
|
|
93
|
+
}
|
|
94
|
+
/** Google's error shapes: the API's `{ error: { code, message, status } }`, the token endpoint's `{ error, error_description }`. */
|
|
95
|
+
errorMessageOf(reply) {
|
|
96
|
+
const body = reply.body;
|
|
97
|
+
if (body && typeof body === 'object') {
|
|
98
|
+
if (body.error && typeof body.error === 'object') {
|
|
99
|
+
return ([body.error.status, body.error.message].filter(Boolean).join(': ').slice(0, 500) || `HTTP ${reply.status}`);
|
|
100
|
+
}
|
|
101
|
+
if (typeof body.error === 'string') {
|
|
102
|
+
return [body.error, body.error_description].filter(Boolean).join(': ').slice(0, 500);
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
return super.errorMessageOf(reply);
|
|
106
|
+
}
|
|
107
|
+
pemOf(raw) {
|
|
108
|
+
return text(raw).replace(/\\n/g, '\n');
|
|
109
|
+
}
|
|
110
|
+
cacheKey() {
|
|
111
|
+
return (0, crypto_1.createHash)('sha256')
|
|
112
|
+
.update(`${text(this.settings.clientEmail).toLowerCase()}\n${this.pemOf(this.settings.privateKey)}`)
|
|
113
|
+
.digest('hex');
|
|
114
|
+
}
|
|
115
|
+
/** The signed assertion a token is asked for with, or null when the key cannot sign. */
|
|
116
|
+
assertion(nowMs) {
|
|
117
|
+
const iat = Math.floor(nowMs / 1000);
|
|
118
|
+
const head = base64Url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
|
|
119
|
+
const claims = base64Url(JSON.stringify({
|
|
120
|
+
iss: text(this.settings.clientEmail),
|
|
121
|
+
scope: exports.GOOGLE_SHEETS_SCOPE,
|
|
122
|
+
aud: exports.GOOGLE_TOKEN_URL,
|
|
123
|
+
iat,
|
|
124
|
+
exp: iat + 3600,
|
|
125
|
+
}));
|
|
126
|
+
try {
|
|
127
|
+
const signature = (0, crypto_1.createSign)('RSA-SHA256').update(`${head}.${claims}`).sign(this.pemOf(this.settings.privateKey));
|
|
128
|
+
return `${head}.${claims}.${base64Url(signature)}`;
|
|
129
|
+
}
|
|
130
|
+
catch {
|
|
131
|
+
return null;
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* A live access token for the account — the cached one, else a new one from Google (`fresh`: never the cached one).
|
|
136
|
+
* OK with `{ accessToken, expiresAt }`. Never throws.
|
|
137
|
+
*/
|
|
138
|
+
async accessToken(fresh = false) {
|
|
139
|
+
if (!this.isConfigured()) {
|
|
140
|
+
return this.notConfigured();
|
|
141
|
+
}
|
|
142
|
+
const key = this.cacheKey();
|
|
143
|
+
const now = Date.now();
|
|
144
|
+
const cached = tokens.get(key);
|
|
145
|
+
if (!fresh && cached && cached.until - TOKEN_MARGIN_MS > now) {
|
|
146
|
+
return api_helpers_1.OpResult.ok([{ accessToken: cached.token, expiresAt: new Date(cached.until).toISOString() }]);
|
|
147
|
+
}
|
|
148
|
+
const jwt = this.assertion(now);
|
|
149
|
+
if (!jwt) {
|
|
150
|
+
return api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED, null, 'The private key could not sign (is it the whole key from the JSON file?)');
|
|
151
|
+
}
|
|
152
|
+
const result = await this.requestWithRetries({
|
|
153
|
+
url: exports.GOOGLE_TOKEN_URL,
|
|
154
|
+
method: 'POST',
|
|
155
|
+
headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
|
|
156
|
+
body: new URLSearchParams({ grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer', assertion: jwt }),
|
|
157
|
+
secrets: [jwt],
|
|
158
|
+
});
|
|
159
|
+
if (result.didFail()) {
|
|
160
|
+
tokens.delete(key);
|
|
161
|
+
return result;
|
|
162
|
+
}
|
|
163
|
+
// ⓘ The reply is scrubbed of the request's secrets only — the token itself is new, so it arrives whole.
|
|
164
|
+
const body = result.getDataFirst()?.body ?? {};
|
|
165
|
+
const accessToken = text(body.access_token);
|
|
166
|
+
if (!accessToken) {
|
|
167
|
+
return api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.FAILED, null, 'Google answered without an access token');
|
|
168
|
+
}
|
|
169
|
+
const until = now + (Number(body.expires_in) > 0 ? Number(body.expires_in) : 3600) * 1000;
|
|
170
|
+
tokens.set(key, { token: accessToken, until });
|
|
171
|
+
return api_helpers_1.OpResult.ok([{ accessToken, expiresAt: new Date(until).toISOString() }]);
|
|
172
|
+
}
|
|
173
|
+
/** One API call with the account's token; a 401 forgets it and tries once more with a new one. */
|
|
174
|
+
async call(method, path, json) {
|
|
175
|
+
let result = api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.FAILED, null, 'Not called');
|
|
176
|
+
for (let attempt = 0; attempt < 2; attempt++) {
|
|
177
|
+
const token = await this.accessToken(attempt > 0);
|
|
178
|
+
if (token.didFail()) {
|
|
179
|
+
return token;
|
|
180
|
+
}
|
|
181
|
+
const accessToken = String(token.getDataFirst().accessToken);
|
|
182
|
+
result = await this.requestWithRetries({
|
|
183
|
+
url: `${this.baseUrl}${path}`,
|
|
184
|
+
method,
|
|
185
|
+
headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
|
|
186
|
+
...(json === undefined ? {} : { json }),
|
|
187
|
+
secrets: [accessToken],
|
|
188
|
+
});
|
|
189
|
+
if (result.getCode() !== api_helpers_1.OP_RESULT_CODES.UNAUTHORIZED) {
|
|
190
|
+
return result;
|
|
191
|
+
}
|
|
192
|
+
tokens.delete(this.cacheKey());
|
|
193
|
+
}
|
|
194
|
+
return result;
|
|
195
|
+
}
|
|
196
|
+
badId(spreadsheetId) {
|
|
197
|
+
return SPREADSHEET_ID.test(text(spreadsheetId))
|
|
198
|
+
? null
|
|
199
|
+
: api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED, null, 'The spreadsheet id is not one');
|
|
200
|
+
}
|
|
201
|
+
/**
|
|
202
|
+
* The spreadsheet's title and tabs (each with its size and frozen rows) — readable only when it is shared with the
|
|
203
|
+
* account (403 FORBIDDEN otherwise; 404 NOT_FOUND when there is no such spreadsheet). OK with a `GoogleSpreadsheet`.
|
|
204
|
+
*/
|
|
205
|
+
async getSpreadsheet(spreadsheetId) {
|
|
206
|
+
if (!this.isConfigured()) {
|
|
207
|
+
return this.notConfigured();
|
|
208
|
+
}
|
|
209
|
+
const bad = this.badId(spreadsheetId);
|
|
210
|
+
if (bad) {
|
|
211
|
+
return bad;
|
|
212
|
+
}
|
|
213
|
+
const fields = 'spreadsheetId,properties.title,sheets.properties(sheetId,title,index,gridProperties(rowCount,columnCount,frozenRowCount))';
|
|
214
|
+
const result = await this.call('GET', `/${text(spreadsheetId)}?fields=${encodeURIComponent(fields)}`);
|
|
215
|
+
if (result.didFail()) {
|
|
216
|
+
return result;
|
|
217
|
+
}
|
|
218
|
+
const body = result.getDataFirst()?.body ?? {};
|
|
219
|
+
const book = {
|
|
220
|
+
spreadsheetId: text(body.spreadsheetId) || text(spreadsheetId),
|
|
221
|
+
title: text(body.properties?.title),
|
|
222
|
+
tabs: (Array.isArray(body.sheets) ? body.sheets : []).map((s) => ({
|
|
223
|
+
sheetId: Number(s?.properties?.sheetId) || 0,
|
|
224
|
+
title: String(s?.properties?.title ?? ''),
|
|
225
|
+
index: Number(s?.properties?.index) || 0,
|
|
226
|
+
rowCount: Number(s?.properties?.gridProperties?.rowCount) || 0,
|
|
227
|
+
columnCount: Number(s?.properties?.gridProperties?.columnCount) || 0,
|
|
228
|
+
frozenRowCount: Number(s?.properties?.gridProperties?.frozenRowCount) || 0,
|
|
229
|
+
})),
|
|
230
|
+
};
|
|
231
|
+
return api_helpers_1.OpResult.ok([book]);
|
|
232
|
+
}
|
|
233
|
+
/**
|
|
234
|
+
* The values of several ranges in ONE read, in the order asked, row by row, unformatted (a number stays a number);
|
|
235
|
+
* trailing empty cells and rows are left out, as Google does. OK with `{ valueRanges: [{ range, values }] }`.
|
|
236
|
+
*/
|
|
237
|
+
async batchGetValues(spreadsheetId, ranges) {
|
|
238
|
+
if (!this.isConfigured()) {
|
|
239
|
+
return this.notConfigured();
|
|
240
|
+
}
|
|
241
|
+
const bad = this.badId(spreadsheetId);
|
|
242
|
+
const wanted = (ranges ?? []).map((r) => String(r ?? '')).filter(Boolean);
|
|
243
|
+
if (bad || wanted.length === 0) {
|
|
244
|
+
return bad ?? api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED, null, 'At least one range is needed');
|
|
245
|
+
}
|
|
246
|
+
const params = new URLSearchParams();
|
|
247
|
+
for (const range of wanted) {
|
|
248
|
+
params.append('ranges', range);
|
|
249
|
+
}
|
|
250
|
+
params.set('majorDimension', 'ROWS');
|
|
251
|
+
params.set('valueRenderOption', 'UNFORMATTED_VALUE');
|
|
252
|
+
const result = await this.call('GET', `/${text(spreadsheetId)}/values:batchGet?${params.toString()}`);
|
|
253
|
+
if (result.didFail()) {
|
|
254
|
+
return result;
|
|
255
|
+
}
|
|
256
|
+
const got = result.getDataFirst()?.body?.valueRanges;
|
|
257
|
+
const valueRanges = wanted.map((range, i) => ({
|
|
258
|
+
range,
|
|
259
|
+
values: Array.isArray(got?.[i]?.values) ? got[i].values : [],
|
|
260
|
+
}));
|
|
261
|
+
return api_helpers_1.OpResult.ok([{ valueRanges }]);
|
|
262
|
+
}
|
|
263
|
+
/**
|
|
264
|
+
* Structural changes in ONE request, all or none (add a tab, grow one, freeze its header, format cells) — Google's
|
|
265
|
+
* `spreadsheets.batchUpdate` requests as given. OK with `{ replies }`.
|
|
266
|
+
*/
|
|
267
|
+
async batchUpdate(spreadsheetId, requests) {
|
|
268
|
+
if (!this.isConfigured()) {
|
|
269
|
+
return this.notConfigured();
|
|
270
|
+
}
|
|
271
|
+
const bad = this.badId(spreadsheetId);
|
|
272
|
+
const list = (requests ?? []).filter((r) => r && typeof r === 'object');
|
|
273
|
+
if (bad || list.length === 0) {
|
|
274
|
+
return bad ?? api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED, null, 'At least one request is needed');
|
|
275
|
+
}
|
|
276
|
+
const result = await this.call('POST', `/${text(spreadsheetId)}:batchUpdate`, { requests: list });
|
|
277
|
+
return result.didFail() ? result : api_helpers_1.OpResult.ok([{ replies: result.getDataFirst()?.body?.replies ?? [] }]);
|
|
278
|
+
}
|
|
279
|
+
/**
|
|
280
|
+
* Many ranges written in ONE request, all or none — RAW unless told otherwise (nothing typed becomes a formula, a
|
|
281
|
+
* date or a number it was not). A range past the tab's size is refused by Google: grow the tab first (`batchUpdate`
|
|
282
|
+
* with `appendDimension`). OK with `{ updatedCells, updatedRanges }`.
|
|
283
|
+
*/
|
|
284
|
+
async batchUpdateValues(spreadsheetId, data, valueInputOption = 'RAW') {
|
|
285
|
+
if (!this.isConfigured()) {
|
|
286
|
+
return this.notConfigured();
|
|
287
|
+
}
|
|
288
|
+
const bad = this.badId(spreadsheetId);
|
|
289
|
+
const list = (data ?? []).filter((d) => text(d?.range) && Array.isArray(d?.values));
|
|
290
|
+
if (bad || list.length === 0) {
|
|
291
|
+
return bad ?? api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED, null, 'At least one range with values is needed');
|
|
292
|
+
}
|
|
293
|
+
const result = await this.call('POST', `/${text(spreadsheetId)}/values:batchUpdate`, {
|
|
294
|
+
valueInputOption: valueInputOption === 'USER_ENTERED' ? 'USER_ENTERED' : 'RAW',
|
|
295
|
+
data: list.map((d) => ({ range: d.range, majorDimension: 'ROWS', values: d.values })),
|
|
296
|
+
});
|
|
297
|
+
if (result.didFail()) {
|
|
298
|
+
return result;
|
|
299
|
+
}
|
|
300
|
+
const body = result.getDataFirst()?.body ?? {};
|
|
301
|
+
return api_helpers_1.OpResult.ok([
|
|
302
|
+
{
|
|
303
|
+
updatedCells: Number(body.totalUpdatedCells) || 0,
|
|
304
|
+
updatedRanges: (body.responses ?? []).length || list.length,
|
|
305
|
+
},
|
|
306
|
+
]);
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
exports.GoogleSheetsGw = GoogleSheetsGw;
|
|
@@ -94,6 +94,7 @@ declare class QuickBooksGw extends BaseExternalApiGateway<QuickBooksSettings> {
|
|
|
94
94
|
createCustomer(company: QuickBooksCompany, customer: {
|
|
95
95
|
displayName: string;
|
|
96
96
|
email?: string | null;
|
|
97
|
+
currency?: string | null;
|
|
97
98
|
}, requestId: string): Promise<OpResult>;
|
|
98
99
|
/** A sale paid at once (the body as Intuit takes it — `Line`, `DepositToAccountRef`, …). */
|
|
99
100
|
createSalesReceipt(company: QuickBooksCompany, receipt: Record<string, unknown>, requestId: string): Promise<OpResult>;
|
|
@@ -311,12 +311,18 @@ class QuickBooksGw extends BaseExternalApiGateway_1.BaseExternalApiGateway {
|
|
|
311
311
|
/** A customer by display name (unique in the company across customers, vendors and employees). */
|
|
312
312
|
createCustomer(company, customer, requestId) {
|
|
313
313
|
const displayName = (0, exports.quickBooksNameOf)(customer?.displayName);
|
|
314
|
+
const currency = text(customer?.currency).toUpperCase();
|
|
314
315
|
if (!displayName) {
|
|
315
316
|
return Promise.resolve(api_helpers_1.OpResult.fail(api_helpers_1.OP_RESULT_CODES.VALIDATION_FAILED, null, 'A customer needs a name'));
|
|
316
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
|
+
}
|
|
317
321
|
return this.create(company, 'Customer', {
|
|
318
322
|
DisplayName: displayName,
|
|
319
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 } } : {}),
|
|
320
326
|
}, requestId);
|
|
321
327
|
}
|
|
322
328
|
/** A sale paid at once (the body as Intuit takes it — `Line`, `DepositToAccountRef`, …). */
|
package/build/gateways/index.js
CHANGED
|
@@ -24,5 +24,6 @@ __exportStar(require("./DiscordWebhookGw"), exports);
|
|
|
24
24
|
__exportStar(require("./HubSpotGw"), exports);
|
|
25
25
|
__exportStar(require("./MailchimpGw"), exports);
|
|
26
26
|
__exportStar(require("./QuickBooksGw"), exports);
|
|
27
|
+
__exportStar(require("./GoogleSheetsGw"), exports);
|
|
27
28
|
__exportStar(require("./HttpWebhookGw"), exports);
|
|
28
29
|
__exportStar(require("./guardedFetch"), exports);
|