@sdflc/backend-helpers 1.0.148 → 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.
@@ -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 };
@@ -8,5 +8,6 @@ export * from './DiscordWebhookGw';
8
8
  export * from './HubSpotGw';
9
9
  export * from './MailchimpGw';
10
10
  export * from './QuickBooksGw';
11
+ export * from './GoogleSheetsGw';
11
12
  export * from './HttpWebhookGw';
12
13
  export * from './guardedFetch';
@@ -8,5 +8,6 @@ export * from './DiscordWebhookGw';
8
8
  export * from './HubSpotGw';
9
9
  export * from './MailchimpGw';
10
10
  export * from './QuickBooksGw';
11
+ export * from './GoogleSheetsGw';
11
12
  export * from './HttpWebhookGw';
12
13
  export * from './guardedFetch';
@@ -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;
@@ -8,5 +8,6 @@ export * from './DiscordWebhookGw';
8
8
  export * from './HubSpotGw';
9
9
  export * from './MailchimpGw';
10
10
  export * from './QuickBooksGw';
11
+ export * from './GoogleSheetsGw';
11
12
  export * from './HttpWebhookGw';
12
13
  export * from './guardedFetch';
@@ -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);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sdflc/backend-helpers",
3
- "version": "1.0.148",
3
+ "version": "1.0.149",
4
4
  "description": "Set of helper functions and classes to simplify building backend apps within @sdflc ecosystem",
5
5
  "type": "commonjs",
6
6
  "exports": {