@an5/adapters 0.1.0

package/typescript/googlesheets/parseConnectionString.ts

@@ -0,0 +1,44 @@
+import type { An5SheetsAdapterConfig } from './config';
+
+/**
+ * Parse a `googlesheets://` connection string into An5SheetsAdapterConfig.
+ *
+ * Format:
+ *   googlesheets://spreadsheetId;clientEmail=xxx;privateKey=xxx
+ *   googlesheets://spreadsheetId;clientEmail=xxx;privateKey=xxx;sheetMapping=users:Users,orders:Orders
+ *
+ * The privateKey must be URL-encoded (use encodeURIComponent on the raw key).
+ */
+export function parseSheetsConnectionString(url: string): An5SheetsAdapterConfig {
+  const clean = url.replace(/^googlesheets:\/\//, '');
+  const parts = clean.split(';');
+
+  const spreadsheetId = parts[0].trim();
+  const config: Record<string, string> = {};
+
+  for (let i = 1; i < parts.length; i++) {
+    const part = parts[i].trim();
+    if (!part) continue;
+    const eqIdx = part.indexOf('=');
+    if (eqIdx === -1) continue;
+    const key = part.slice(0, eqIdx).trim().toLowerCase();
+    const value = decodeURIComponent(part.slice(eqIdx + 1).trim());
+    config[key] = value;
+  }
+
+  const result: An5SheetsAdapterConfig = { spreadsheetId };
+
+  if (config.clientemail) result.clientEmail = config.clientemail;
+  if (config.privatekey) result.privateKey = config.privatekey;
+
+  if (config.sheetmapping) {
+    const mapping: Record<string, string> = {};
+    for (const pair of config.sheetmapping.split(',')) {
+      const [k, v] = pair.split(':');
+      if (k && v) mapping[k.trim()] = v.trim();
+    }
+    result.sheetMapping = mapping;
+  }
+
+  return result;
+}

package/typescript/googlesheets/retry.d.ts

@@ -0,0 +1,3 @@
+export declare const MAX_RETRIES = 3;
+export declare const BASE_DELAY = 1000;
+export declare function withRetry<T>(fn: () => Promise<T>, attempt?: number): Promise<T>;

package/typescript/googlesheets/retry.js

@@ -0,0 +1,26 @@
+"use strict";
+// ─── Retry helper ─────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASE_DELAY = exports.MAX_RETRIES = void 0;
+exports.withRetry = withRetry;
+exports.MAX_RETRIES = 3;
+exports.BASE_DELAY = 1000;
+async function withRetry(fn, attempt = 1) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        const code = err?.code || err?.status || err?.response?.status;
+        if ((code === 429 || code === 500 || code === 503) && attempt <= exports.MAX_RETRIES) {
+            const delay = exports.BASE_DELAY * Math.pow(2, attempt - 1) + Math.random() * 500;
+            await new Promise(r => setTimeout(r, delay));
+            return withRetry(fn, attempt + 1);
+        }
+        if (code === 403 && err?.errors?.[0]?.reason === 'rateLimitExceeded' && attempt <= exports.MAX_RETRIES) {
+            const delay = exports.BASE_DELAY * Math.pow(2, attempt - 1) + Math.random() * 500;
+            await new Promise(r => setTimeout(r, delay));
+            return withRetry(fn, attempt + 1);
+        }
+        throw err;
+    }
+}

package/typescript/googlesheets/retry.ts

@@ -0,0 +1,23 @@
+// ─── Retry helper ─────────────────────────────────────────────────────────────
+
+export const MAX_RETRIES = 3;
+export const BASE_DELAY = 1000;
+
+export async function withRetry<T>(fn: () => Promise<T>, attempt = 1): Promise<T> {
+  try {
+    return await fn();
+  } catch (err: any) {
+    const code = err?.code || err?.status || err?.response?.status;
+    if ((code === 429 || code === 500 || code === 503) && attempt <= MAX_RETRIES) {
+      const delay = BASE_DELAY * Math.pow(2, attempt - 1) + Math.random() * 500;
+      await new Promise(r => setTimeout(r, delay));
+      return withRetry(fn, attempt + 1);
+    }
+    if (code === 403 && err?.errors?.[0]?.reason === 'rateLimitExceeded' && attempt <= MAX_RETRIES) {
+      const delay = BASE_DELAY * Math.pow(2, attempt - 1) + Math.random() * 500;
+      await new Promise(r => setTimeout(r, delay));
+      return withRetry(fn, attempt + 1);
+    }
+    throw err;
+  }
+}

package/typescript/googlesheets/sqlExecutor.d.ts

@@ -0,0 +1,12 @@
+import type { An5SheetsAdapter } from './adapter';
+export type ExecResult = any[] | number;
+export declare function execQuery(adapter: An5SheetsAdapter, query: string, params: Record<string, any> | undefined, _modelMap?: Record<string, string>, _sheetId?: string): Promise<ExecResult>;
+export declare function substParams(sql: string, params?: Record<string, any>): {
+    text: string;
+    values: any[];
+};
+export declare function matchRowSQL(row: Record<string, any>, whereText: string, values: any[]): boolean;
+export declare function extractColsAndVals(sql: string, params?: Record<string, any>): {
+    cols: string[];
+    vals: any[];
+};

package/typescript/googlesheets/sqlExecutor.js

@@ -0,0 +1,306 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.execQuery = execQuery;
+exports.substParams = substParams;
+exports.matchRowSQL = matchRowSQL;
+exports.extractColsAndVals = extractColsAndVals;
+const helpers_1 = require("./helpers");
+const retry_1 = require("./retry");
+async function execQuery(adapter, query, params, _modelMap, _sheetId) {
+    const q = query.trim();
+    const upper = q.toUpperCase();
+    if (upper.startsWith('SELECT'))
+        return execSelect(adapter, q, params);
+    if (upper.startsWith('INSERT'))
+        return execInsert(adapter, q, params);
+    if (upper.startsWith('UPDATE'))
+        return execUpdate(adapter, q, params);
+    if (upper.startsWith('DELETE'))
+        return execDelete(adapter, q, params);
+    // Fallback: treat as raw range or sheet name
+    const range = q.includes('!') ? q : (0, helpers_1.esc)(q) + '!A:ZZ';
+    const raw = await adapter.readRange(range);
+    return raw;
+}
+function substParams(sql, params) {
+    if (!params)
+        return { text: sql, values: [] };
+    const values = [];
+    const text = sql.replace(/@(\w+)/g, (_, name) => {
+        if (params[name] !== undefined) {
+            const idx = values.length;
+            values.push(params[name]);
+            return `?${idx}`;
+        }
+        return `@${name}`;
+    });
+    return { text, values };
+}
+function matchRowSQL(row, whereText, values) {
+    if (!whereText)
+        return true;
+    const trimmed = whereText.trim();
+    // Handle simple AND conditions: field = ?0 AND field2 = ?1
+    const parts = trimmed.split(/\s+AND\s+/i);
+    for (const part of parts) {
+        const m = part.match(/^(.+?)\s*(=|!=|<>|>|<|>=|<=|LIKE|CONTAINS)\s*(.+)$/i);
+        if (!m)
+            continue;
+        const field = m[1].trim().replace(/[[\]]/g, '');
+        const op = m[2].toUpperCase();
+        const valRef = m[3].trim();
+        const val = valRef.startsWith('?') ? values[parseInt(valRef.slice(1))] : valRef.replace(/^['"]|['"]$/g, '');
+        const cell = row[field];
+        switch (op) {
+            case '=':
+                if (cell != val)
+                    return false;
+                break;
+            case '!=':
+            case '<>':
+                if (cell == val)
+                    return false;
+                break;
+            case '>':
+                if (!(Number(cell) > Number(val)))
+                    return false;
+                break;
+            case '<':
+                if (!(Number(cell) < Number(val)))
+                    return false;
+                break;
+            case '>=':
+                if (!(Number(cell) >= Number(val)))
+                    return false;
+                break;
+            case '<=':
+                if (!(Number(cell) <= Number(val)))
+                    return false;
+                break;
+            case 'LIKE':
+                if (!cell || !String(cell).toLowerCase().includes(String(val).toLowerCase().replace(/%/g, '')))
+                    return false;
+                break;
+            case 'CONTAINS':
+                if (!cell || !String(cell).includes(String(val)))
+                    return false;
+                break;
+        }
+    }
+    return true;
+}
+function extractColsAndVals(sql, params) {
+    const cols = [];
+    const vals = [];
+    const colMatch = sql.match(/\(([^)]+)\)\s*VALUES/i);
+    if (colMatch) {
+        const rawCols = colMatch[1].split(',').map(c => c.trim().replace(/[[\]]/g, ''));
+        // Find actual values
+        const valMatch = sql.substring(colMatch.index + colMatch[0].length).match(/\(([^)]+)\)/);
+        if (valMatch) {
+            const rawVals = valMatch[1].split(',').map(v => v.trim());
+            for (let i = 0; i < rawCols.length; i++) {
+                cols.push(rawCols[i]);
+                const rv = rawVals[i];
+                if (rv.startsWith('@') && params && params[rv.slice(1)] !== undefined) {
+                    vals.push(params[rv.slice(1)]);
+                }
+                else {
+                    vals.push(rv.replace(/^['"]|['"]$/g, ''));
+                }
+            }
+        }
+    }
+    return { cols, vals };
+}
+async function execSelect(adapter, query, params) {
+    const m = query.match(/SELECT\s+(.+?)\s+FROM\s+(?:'([^']+)'|"([^"]+)"|(\S+))\s*(?:WHERE\s+(.+))?$/i);
+    if (!m) {
+        // Try reading as raw range
+        const raw = await adapter.readRange((0, helpers_1.esc)(query.replace(/^SELECT\s+\*\s+FROM\s+/i, '').trim()) + '!A:ZZ');
+        const headers = raw[0] || [];
+        return raw.slice(1).map(r => {
+            const obj = {};
+            headers.forEach((h, i) => { obj[h] = r[i] ?? null; });
+            return obj;
+        });
+    }
+    const sheetName = m[2] || m[3] || m[4];
+    const whereClause = m[5];
+    const raw = await adapter.readRange((0, helpers_1.esc)(sheetName) + '!A:ZZ');
+    if (raw.length < 1)
+        return [];
+    const headers = raw[0];
+    const fieldList = m[1].trim();
+    const selectAll = fieldList === '*';
+    const rows = raw.slice(1).map(row => {
+        const obj = {};
+        headers.forEach((h, i) => { obj[h] = row[i] ?? null; });
+        return obj;
+    });
+    if (!whereClause)
+        return selectAll ? rows : rows.map(r => pickFields(r, fieldList, headers));
+    const { text, values } = substParams(query, params);
+    // Extract just the WHERE part
+    const whereParts = query.match(/WHERE\s+(.+)$/i);
+    const whereText = whereParts ? whereParts[1] : '';
+    const { text: whereSubst, values: whereVals } = substParams(whereText, params);
+    const result = rows.filter(r => matchRowSQL(r, whereSubst, whereVals));
+    return selectAll ? result : result.map(r => pickFields(r, fieldList, headers));
+}
+function pickFields(row, fieldList, headers) {
+    const fields = fieldList.split(',').map(f => f.trim().replace(/[[\]]/g, ''));
+    const obj = {};
+    fields.forEach(f => { obj[f] = row[f]; });
+    return obj;
+}
+async function execInsert(adapter, query, params) {
+    const m = query.match(/INSERT\s+INTO\s+(?:'([^']+)'|"([^"]+)"|(\S+))\s*(.*)/i);
+    if (!m)
+        throw new Error('Invalid INSERT syntax');
+    const sheetName = m[1] || m[2] || m[3];
+    const { cols, vals } = extractColsAndVals(query, params);
+    if (cols.length === 0)
+        throw new Error('Cannot extract columns from INSERT');
+    // Ensure headers exist
+    const raw = await adapter.readRange((0, helpers_1.esc)(sheetName) + '!A1:ZZ1');
+    const existingHeaders = (raw[0] || []);
+    let headers = existingHeaders.length > 0 ? existingHeaders : cols;
+    if (existingHeaders.length === 0) {
+        // Write headers first
+        const api = await adapter.getSheets();
+        await (0, retry_1.withRetry)(() => api.spreadsheets.values.update({
+            spreadsheetId: adapter.config.spreadsheetId,
+            range: (0, helpers_1.esc)(sheetName) + '!A1',
+            valueInputOption: 'RAW',
+            requestBody: { values: [cols] },
+        }));
+        headers = cols;
+    }
+    const rowData = {};
+    cols.forEach((c, i) => { rowData[c] = vals[i]; });
+    for (const h of headers) {
+        if (rowData[h] === undefined)
+            rowData[h] = null;
+    }
+    const rowVals = headers.map(h => {
+        const v = rowData[h];
+        if (v === null || v === undefined)
+            return '';
+        if (v instanceof Date)
+            return v.toISOString();
+        return String(v);
+    });
+    await adapter.appendRange((0, helpers_1.esc)(sheetName) + '!A:A', [rowVals]);
+    return 1;
+}
+async function execUpdate(adapter, query, params) {
+    const m = query.match(/UPDATE\s+(?:'([^']+)'|"([^"]+)"|(\S+))\s+SET\s+(.+?)(?:\s+WHERE\s+(.+))?$/i);
+    if (!m)
+        throw new Error('Invalid UPDATE syntax');
+    const sheetName = m[1] || m[2] || m[3];
+    const setClause = m[4];
+    const whereClause = m[5];
+    // Parse SET clause
+    const setPairs = setClause.split(',').map(p => p.trim());
+    const setFields = [];
+    const setVals = [];
+    for (const pair of setPairs) {
+        const sm = pair.match(/^(\w+)\s*=\s*(.+)$/i);
+        if (!sm)
+            continue;
+        setFields.push(sm[1].replace(/[[\]]/g, ''));
+        const rv = sm[2].trim();
+        if (rv.startsWith('@') && params && params[rv.slice(1)] !== undefined) {
+            setVals.push(params[rv.slice(1)]);
+        }
+        else {
+            setVals.push(rv.replace(/^['"]|['"]$/g, ''));
+        }
+    }
+    // Read data
+    const range = (0, helpers_1.esc)(sheetName) + '!A:ZZ';
+    const raw = await adapter.readRange(range);
+    if (raw.length < 1)
+        return 0;
+    const headers = raw[0];
+    const rows = raw.slice(1);
+    // Determine which rows to update
+    const { text: whereSubst, values: whereVals } = substParams(whereClause || '', params);
+    let count = 0;
+    for (let i = 0; i < rows.length; i++) {
+        const row = {};
+        headers.forEach((h, j) => { row[h] = rows[i][j] ?? null; });
+        row.__row = i + 2;
+        if (whereClause && !matchRowSQL(row, whereSubst, whereVals))
+            continue;
+        // Apply SET values
+        setFields.forEach((f, idx) => { row[f] = setVals[idx]; });
+        const updated = headers.map(h => {
+            const v = row[h];
+            if (v === null || v === undefined)
+                return '';
+            if (v instanceof Date)
+                return v.toISOString();
+            return String(v);
+        });
+        await adapter.writeRange((0, helpers_1.esc)(sheetName) + `!A${row.__row}`, [updated]);
+        count++;
+    }
+    return count;
+}
+async function execDelete(adapter, query, params) {
+    const m = query.match(/DELETE\s+FROM\s+(?:'([^']+)'|"([^"]+)"|(\S+))\s*(?:WHERE\s+(.+))?$/i);
+    if (!m)
+        throw new Error('Invalid DELETE syntax');
+    const sheetName = m[1] || m[2] || m[3];
+    const whereClause = m[4];
+    const meta = await adapter.getSheetMeta(sheetName);
+    if (!meta)
+        return 0;
+    if (!whereClause) {
+        // Delete all rows (keep headers)
+        const api = await adapter.getSheets();
+        await (0, retry_1.withRetry)(() => api.spreadsheets.batchUpdate({
+            spreadsheetId: adapter.config.spreadsheetId,
+            requestBody: {
+                requests: [{
+                        deleteDimension: {
+                            range: { sheetId: meta.sheetId, dimension: 'ROWS', startIndex: 1, endIndex: 999999 },
+                        },
+                    }],
+            },
+        }));
+        return -1; // unknown count
+    }
+    // Read and find matching rows
+    const raw = await adapter.readRange((0, helpers_1.esc)(sheetName) + '!A:ZZ');
+    if (raw.length < 1)
+        return 0;
+    const headers = raw[0];
+    const { text: whereSubst, values: whereVals } = substParams(whereClause, params);
+    const toDelete = [];
+    for (let i = 1; i < raw.length; i++) {
+        const row = {};
+        headers.forEach((h, j) => { row[h] = raw[i][j] ?? null; });
+        if (matchRowSQL(row, whereSubst, whereVals)) {
+            toDelete.push(i + 1);
+        }
+    }
+    // Delete from bottom to top
+    toDelete.sort((a, b) => b - a);
+    for (const rowIdx of toDelete) {
+        const api = await adapter.getSheets();
+        await (0, retry_1.withRetry)(() => api.spreadsheets.batchUpdate({
+            spreadsheetId: adapter.config.spreadsheetId,
+            requestBody: {
+                requests: [{
+                        deleteDimension: {
+                            range: { sheetId: meta.sheetId, dimension: 'ROWS', startIndex: rowIdx - 1, endIndex: rowIdx },
+                        },
+                    }],
+            },
+        }));
+    }
+    return toDelete.length;
+}