@an5/adapters 0.1.0

package/typescript/googlesheets/adapter.ts

@@ -0,0 +1,167 @@
+import { google, sheets_v4 } from 'googleapis';
+import { An5SheetsAdapterConfig, resolveConfig } from './config';
+import { execQuery } from './sqlExecutor';
+import { SheetsTableClient } from './tableClient';
+import { SheetMeta } from './types';
+import { withRetry } from './retry';
+
+// ─── Adapter ──────────────────────────────────────────────────────────────────
+
+export class An5SheetsAdapter {
+  private sheets: sheets_v4.Sheets | null = null;
+  config: ReturnType<typeof resolveConfig>;
+  private sheetsCache: Promise<SheetMeta[]> | null = null;
+
+  constructor(config: An5SheetsAdapterConfig) {
+    this.config = resolveConfig(config);
+  }
+
+  async getSheets(): Promise<sheets_v4.Sheets> {
+    if (!this.sheets) {
+      const auth = new google.auth.JWT({
+        email: this.config.clientEmail,
+        key: this.config.privateKey,
+        scopes: ['https://www.googleapis.com/auth/spreadsheets'],
+      });
+      this.sheets = google.sheets({ version: 'v4', auth });
+    }
+    return this.sheets;
+  }
+
+  private async getApi() {
+    return this.getSheets();
+  }
+
+  invalidateCache(): void {
+    this.sheetsCache = null;
+  }
+
+  async listSheets(): Promise<string[]> {
+    const api = await this.getApi();
+    const res = await withRetry(() =>
+      api.spreadsheets.get({
+        spreadsheetId: this.config.spreadsheetId,
+        fields: 'sheets.properties.title',
+      })
+    );
+    return (res.data.sheets || []).map(s => s.properties?.title || '');
+  }
+
+  async getSheetMeta(name: string): Promise<SheetMeta | null> {
+    const api = await this.getApi();
+    if (this.sheetsCache == null) {
+      this.sheetsCache = withRetry(async () => {
+        const res = await api.spreadsheets.get({
+          spreadsheetId: this.config.spreadsheetId,
+          fields: 'sheets.properties',
+        });
+        return (res.data.sheets || []).map(s => ({
+          sheetId: s.properties?.sheetId ?? -1,
+          title: s.properties?.title ?? '',
+        })).filter(m => m.sheetId >= 0);
+      });
+    }
+    const all = await this.sheetsCache;
+    return all.find(m => m.title === name) || null;
+  }
+
+  async deleteSheet(name: string): Promise<void> {
+    const meta = await this.getSheetMeta(name);
+    if (!meta) throw new Error(`Sheet "${name}" not found`);
+    const api = await this.getApi();
+    await withRetry(() =>
+      api.spreadsheets.batchUpdate({
+        spreadsheetId: this.config.spreadsheetId,
+        requestBody: {
+          requests: [{ deleteSheet: { sheetId: meta.sheetId } }],
+        },
+      })
+    );
+    this.invalidateCache();
+  }
+
+  async $connect(): Promise<void> {
+    await this.getSheets();
+  }
+
+  async $disconnect(): Promise<void> {
+    this.sheets = null;
+    this.sheetsCache = null;
+  }
+
+  async exec<T = any>(query: string, params?: Record<string, any>): Promise<T[]> {
+    return execQuery(this, query, params, undefined, undefined) as Promise<T[]>;
+  }
+
+  async $queryRawUnsafe<T = any>(query: string, ...values: any[]): Promise<T[]> {
+    const params: Record<string, any> = {};
+    values.forEach((v, i) => { params[`p_${i}`] = v; });
+    const resolved = query.replace(/@p_(\d+)/g, (_, i) => `@p_${i}`);
+    return execQuery(this, resolved, params, undefined, undefined) as Promise<T[]>;
+  }
+
+  async $executeRaw(query: string, ...values: any[]): Promise<number> {
+    const params: Record<string, any> = {};
+    values.forEach((v, i) => { params[`p_${i}`] = v; });
+    const resolved = query.replace(/@p_(\d+)/g, (_, i) => `@p_${i}`);
+    return execQuery(this, resolved, params, undefined, undefined) as Promise<number>;
+  }
+
+  async $executeRawUnsafe(query: string, ...values: any[]): Promise<number> {
+    return this.$executeRaw(query, ...values);
+  }
+
+  async $transaction<R>(fn: (tx: An5SheetsAdapter) => Promise<R>, _options?: { timeout?: number }): Promise<R>;
+  async $transaction<R>(list: Promise<R>[]): Promise<R[]>;
+  async $transaction(fn: any, _options?: any): Promise<any> {
+    if (typeof fn === 'function') return fn(this);
+    return Promise.all(fn);
+  }
+
+  table<T = any>(modelName: string): SheetsTableClient<T> {
+    return new SheetsTableClient<T>(this, modelName, this.config.sheetMapping);
+  }
+
+  // ── Raw range access ──────────────────────────────────────────────────────
+
+  async readRange<T = any>(range: string): Promise<T[][]> {
+    const api = await this.getApi();
+    const res = await withRetry(() =>
+      api.spreadsheets.values.get({
+        spreadsheetId: this.config.spreadsheetId,
+        range,
+      })
+    );
+    return (res.data.values || []) as T[][];
+  }
+
+  async writeRange(range: string, values: any[][]): Promise<void> {
+    const api = await this.getApi();
+    await withRetry(() =>
+      api.spreadsheets.values.update({
+        spreadsheetId: this.config.spreadsheetId,
+        range,
+        valueInputOption: 'RAW',
+        requestBody: { values },
+      })
+    );
+  }
+
+  async appendRange(range: string, values: any[][]): Promise<void> {
+    const api = await this.getApi();
+    await withRetry(() =>
+      api.spreadsheets.values.append({
+        spreadsheetId: this.config.spreadsheetId,
+        range,
+        valueInputOption: 'RAW',
+        insertDataOption: 'INSERT_ROWS',
+        requestBody: { values },
+      })
+    );
+  }
+}
+// ─── Factory ──────────────────────────────────────────────────────────────────
+
+export function createAn5SheetsAdapter(config: An5SheetsAdapterConfig): An5SheetsAdapter {
+  return new An5SheetsAdapter(config);
+}

package/typescript/googlesheets/an5SheetsAdapter.d.ts

@@ -0,0 +1,3 @@
+export { An5SheetsAdapter, createAn5SheetsAdapter } from './adapter';
+export { SheetsTableClient } from './tableClient';
+export { An5SheetsAdapterConfig } from './config';

package/typescript/googlesheets/an5SheetsAdapter.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SheetsTableClient = exports.createAn5SheetsAdapter = exports.An5SheetsAdapter = void 0;
+var adapter_1 = require("./adapter");
+Object.defineProperty(exports, "An5SheetsAdapter", { enumerable: true, get: function () { return adapter_1.An5SheetsAdapter; } });
+Object.defineProperty(exports, "createAn5SheetsAdapter", { enumerable: true, get: function () { return adapter_1.createAn5SheetsAdapter; } });
+var tableClient_1 = require("./tableClient");
+Object.defineProperty(exports, "SheetsTableClient", { enumerable: true, get: function () { return tableClient_1.SheetsTableClient; } });

package/typescript/googlesheets/an5SheetsAdapter.ts

@@ -0,0 +1,3 @@
+export { An5SheetsAdapter, createAn5SheetsAdapter } from './adapter';
+export { SheetsTableClient } from './tableClient';
+export { An5SheetsAdapterConfig } from './config';

package/typescript/googlesheets/config.d.ts

@@ -0,0 +1,17 @@
+export interface An5SheetsAdapterConfig {
+    spreadsheetId: string;
+    clientEmail?: string;
+    privateKey?: string;
+    credentials?: {
+        client_email: string;
+        private_key: string;
+    };
+    sheetMapping?: Record<string, string>;
+}
+export declare function normalizeKey(key: string): string;
+export declare function resolveConfig(config: An5SheetsAdapterConfig): {
+    spreadsheetId: string;
+    clientEmail: string;
+    privateKey: string;
+    sheetMapping: Record<string, string> | undefined;
+};

package/typescript/googlesheets/config.js

@@ -0,0 +1,29 @@
+"use strict";
+// ─── Config ───────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeKey = normalizeKey;
+exports.resolveConfig = resolveConfig;
+function normalizeKey(key) {
+    if (key.includes('PRIVATE KEY'))
+        return key;
+    const lines = key.split('\\n').join('\n');
+    if (lines.includes('PRIVATE KEY'))
+        return lines;
+    return `-----BEGIN PRIVATE KEY-----\n${lines}\n-----END PRIVATE KEY-----`;
+}
+function resolveConfig(config) {
+    if (config.credentials) {
+        return {
+            spreadsheetId: config.spreadsheetId,
+            clientEmail: config.credentials.client_email,
+            privateKey: normalizeKey(config.credentials.private_key),
+            sheetMapping: config.sheetMapping,
+        };
+    }
+    return {
+        spreadsheetId: config.spreadsheetId,
+        clientEmail: config.clientEmail,
+        privateKey: normalizeKey(config.privateKey),
+        sheetMapping: config.sheetMapping,
+    };
+}

package/typescript/googlesheets/config.ts

@@ -0,0 +1,33 @@
+// ─── Config ───────────────────────────────────────────────────────────────────
+
+export interface An5SheetsAdapterConfig {
+  spreadsheetId: string;
+  clientEmail?: string;
+  privateKey?: string;
+  credentials?: { client_email: string; private_key: string };
+  sheetMapping?: Record<string, string>;
+}
+
+export function normalizeKey(key: string): string {
+  if (key.includes('PRIVATE KEY')) return key;
+  const lines = key.split('\\n').join('\n');
+  if (lines.includes('PRIVATE KEY')) return lines;
+  return `-----BEGIN PRIVATE KEY-----\n${lines}\n-----END PRIVATE KEY-----`;
+}
+
+export function resolveConfig(config: An5SheetsAdapterConfig) {
+  if (config.credentials) {
+    return {
+      spreadsheetId: config.spreadsheetId,
+      clientEmail: config.credentials.client_email,
+      privateKey: normalizeKey(config.credentials.private_key),
+      sheetMapping: config.sheetMapping,
+    };
+  }
+  return {
+    spreadsheetId: config.spreadsheetId,
+    clientEmail: config.clientEmail!,
+    privateKey: normalizeKey(config.privateKey!),
+    sheetMapping: config.sheetMapping,
+  };
+}

package/typescript/googlesheets/helpers.d.ts

@@ -0,0 +1,9 @@
+export declare function esc(name: string): string;
+export declare function resolveSheetName(modelName: string, mapping?: Record<string, string>): string;
+export declare function matchWhere(row: Record<string, any>, where: any): boolean;
+export declare function buildOrderBy(orderBy: any): string;
+export declare function sortRows(rows: Record<string, any>[], orderBy: string): Record<string, any>[];
+export declare function coerceCell(raw: any, fieldMeta?: {
+    ts?: string;
+    sql?: string;
+}): any;

package/typescript/googlesheets/helpers.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.esc = esc;
+exports.resolveSheetName = resolveSheetName;
+exports.matchWhere = matchWhere;
+exports.buildOrderBy = buildOrderBy;
+exports.sortRows = sortRows;
+exports.coerceCell = coerceCell;
+const metadata_1 = require("../base/metadata");
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function esc(name) {
+    return name.includes(' ') || /[^\w]/.test(name) ? `'${name.replace(/'/g, "''")}'` : name;
+}
+function resolveSheetName(modelName, mapping) {
+    if (mapping?.[modelName])
+        return mapping[modelName];
+    const modelToTable = (0, metadata_1.getModelToTable)();
+    return modelToTable[modelName] || modelName;
+}
+function matchWhere(row, where) {
+    if (!where)
+        return true;
+    const cleanWhere = {};
+    for (const [key, value] of Object.entries(where)) {
+        if (key.includes('_') &&
+            value && typeof value === 'object' &&
+            !(value instanceof Date) &&
+            !value.in && !value.contains &&
+            !value.not && !value.gte &&
+            !value.lte && !value.gt && !value.lt) {
+            Object.assign(cleanWhere, value);
+        }
+        else {
+            cleanWhere[key] = value;
+        }
+    }
+    for (const [key, value] of Object.entries(cleanWhere)) {
+        if (key === 'OR' && Array.isArray(value)) {
+            if (!value.some((v) => matchWhere(row, v)))
+                return false;
+            continue;
+        }
+        if (key === 'AND' && Array.isArray(value)) {
+            if (!value.every((v) => matchWhere(row, v)))
+                return false;
+            continue;
+        }
+        const cellVal = row[key];
+        if (value === null) {
+            if (cellVal !== null && cellVal !== undefined)
+                return false;
+        }
+        else if (typeof value === 'object' && !(value instanceof Date)) {
+            const v = value;
+            if (v.not !== undefined) {
+                if (v.not === null) {
+                    if (cellVal === null || cellVal === undefined)
+                        return false;
+                }
+                else if (cellVal == v.not)
+                    return false;
+            }
+            if (v.equals !== undefined && cellVal != v.equals)
+                return false;
+            if (v.contains !== undefined && (!cellVal || !String(cellVal).includes(v.contains)))
+                return false;
+            if (v.startsWith !== undefined && (!cellVal || !String(cellVal).startsWith(v.startsWith)))
+                return false;
+            if (v.endsWith !== undefined && (!cellVal || !String(cellVal).endsWith(v.endsWith)))
+                return false;
+            if (v.gte !== undefined && !(Number(cellVal) >= Number(v.gte)))
+                return false;
+            if (v.lte !== undefined && !(Number(cellVal) <= Number(v.lte)))
+                return false;
+            if (v.gt !== undefined && !(Number(cellVal) > Number(v.gt)))
+                return false;
+            if (v.lt !== undefined && !(Number(cellVal) < Number(v.lt)))
+                return false;
+            if (v.in !== undefined) {
+                if (!Array.isArray(v.in) || !v.in.includes(cellVal))
+                    return false;
+            }
+        }
+        else {
+            if (cellVal != value)
+                return false;
+        }
+    }
+    return true;
+}
+function buildOrderBy(orderBy) {
+    if (!orderBy)
+        return '';
+    const entries = Array.isArray(orderBy) ? orderBy : [orderBy];
+    const parts = [];
+    for (const entry of entries) {
+        for (const [key, dir] of Object.entries(entry)) {
+            parts.push(`${key} ${dir.toUpperCase()}`);
+        }
+    }
+    return parts.join(', ');
+}
+function sortRows(rows, orderBy) {
+    if (!orderBy)
+        return rows;
+    const clauses = orderBy.split(',').map(c => c.trim());
+    return [...rows].sort((a, b) => {
+        for (const clause of clauses) {
+            const [field, dir] = clause.split(/\s+/);
+            const direction = dir?.toUpperCase() === 'DESC' ? -1 : 1;
+            const aVal = a[field];
+            const bVal = b[field];
+            if (aVal == null && bVal == null)
+                continue;
+            if (aVal == null)
+                return 1 * direction;
+            if (bVal == null)
+                return -1 * direction;
+            if (aVal < bVal)
+                return -1 * direction;
+            if (aVal > bVal)
+                return 1 * direction;
+        }
+        return 0;
+    });
+}
+function coerceCell(raw, fieldMeta) {
+    if (raw === undefined || raw === '')
+        return null;
+    if (raw instanceof Date)
+        return raw.toISOString();
+    if (fieldMeta) {
+        const tsType = (fieldMeta.ts || '').toLowerCase().replace('?', '');
+        if (['number', 'int', 'float', 'double', 'decimal'].includes(tsType)) {
+            const n = Number(raw);
+            return isNaN(n) ? raw : n;
+        }
+        if (tsType === 'boolean' || tsType === 'bool') {
+            if (raw === 'true' || raw === true)
+                return true;
+            if (raw === 'false' || raw === false)
+                return false;
+        }
+    }
+    if (typeof raw === 'string' && /^-?\d+\.?\d*$/.test(raw.trim()) && !/^0\d/.test(raw.trim())) {
+        const n = Number(raw);
+        if (!isNaN(n) && String(n) === raw.trim())
+            return n;
+    }
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    return raw;
+}

package/typescript/googlesheets/helpers.ts

@@ -0,0 +1,124 @@
+import { getModelToTable } from '../base/metadata';
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+export function esc(name: string): string {
+  return name.includes(' ') || /[^\w]/.test(name) ? `'${name.replace(/'/g, "''")}'` : name;
+}
+
+export function resolveSheetName(modelName: string, mapping?: Record<string, string>): string {
+  if (mapping?.[modelName]) return mapping[modelName];
+  const modelToTable = getModelToTable();
+  return modelToTable[modelName] || modelName;
+}
+
+export function matchWhere(row: Record<string, any>, where: any): boolean {
+  if (!where) return true;
+
+  const cleanWhere: Record<string, any> = {};
+  for (const [key, value] of Object.entries(where)) {
+    if (
+      key.includes('_') &&
+      value && typeof value === 'object' &&
+      !(value instanceof Date) &&
+      !(value as any).in && !(value as any).contains &&
+      !(value as any).not && !(value as any).gte &&
+      !(value as any).lte && !(value as any).gt && !(value as any).lt
+    ) {
+      Object.assign(cleanWhere, value);
+    } else {
+      cleanWhere[key] = value;
+    }
+  }
+
+  for (const [key, value] of Object.entries(cleanWhere)) {
+    if (key === 'OR' && Array.isArray(value)) {
+      if (!value.some((v: any) => matchWhere(row, v))) return false;
+      continue;
+    }
+    if (key === 'AND' && Array.isArray(value)) {
+      if (!value.every((v: any) => matchWhere(row, v))) return false;
+      continue;
+    }
+
+    const cellVal = row[key];
+
+    if (value === null) {
+      if (cellVal !== null && cellVal !== undefined) return false;
+    } else if (typeof value === 'object' && !(value instanceof Date)) {
+      const v = value as any;
+      if (v.not !== undefined) {
+        if (v.not === null) { if (cellVal === null || cellVal === undefined) return false; }
+        else if (cellVal == v.not) return false;
+      }
+      if (v.equals !== undefined && cellVal != v.equals) return false;
+      if (v.contains !== undefined && (!cellVal || !String(cellVal).includes(v.contains))) return false;
+      if (v.startsWith !== undefined && (!cellVal || !String(cellVal).startsWith(v.startsWith))) return false;
+      if (v.endsWith !== undefined && (!cellVal || !String(cellVal).endsWith(v.endsWith))) return false;
+      if (v.gte !== undefined && !(Number(cellVal) >= Number(v.gte))) return false;
+      if (v.lte !== undefined && !(Number(cellVal) <= Number(v.lte))) return false;
+      if (v.gt !== undefined && !(Number(cellVal) > Number(v.gt))) return false;
+      if (v.lt !== undefined && !(Number(cellVal) < Number(v.lt))) return false;
+      if (v.in !== undefined) {
+        if (!Array.isArray(v.in) || !v.in.includes(cellVal)) return false;
+      }
+    } else {
+      if (cellVal != value) return false;
+    }
+  }
+  return true;
+}
+
+export function buildOrderBy(orderBy: any): string {
+  if (!orderBy) return '';
+  const entries = Array.isArray(orderBy) ? orderBy : [orderBy];
+  const parts: string[] = [];
+  for (const entry of entries) {
+    for (const [key, dir] of Object.entries(entry)) {
+      parts.push(`${key} ${(dir as string).toUpperCase()}`);
+    }
+  }
+  return parts.join(', ');
+}
+
+export function sortRows(rows: Record<string, any>[], orderBy: string): Record<string, any>[] {
+  if (!orderBy) return rows;
+  const clauses = orderBy.split(',').map(c => c.trim());
+  return [...rows].sort((a, b) => {
+    for (const clause of clauses) {
+      const [field, dir] = clause.split(/\s+/);
+      const direction = dir?.toUpperCase() === 'DESC' ? -1 : 1;
+      const aVal = a[field];
+      const bVal = b[field];
+      if (aVal == null && bVal == null) continue;
+      if (aVal == null) return 1 * direction;
+      if (bVal == null) return -1 * direction;
+      if (aVal < bVal) return -1 * direction;
+      if (aVal > bVal) return 1 * direction;
+    }
+    return 0;
+  });
+}
+
+export function coerceCell(raw: any, fieldMeta?: { ts?: string; sql?: string }): any {
+  if (raw === undefined || raw === '') return null;
+  if (raw instanceof Date) return raw.toISOString();
+  if (fieldMeta) {
+    const tsType = (fieldMeta.ts || '').toLowerCase().replace('?', '');
+    if (['number', 'int', 'float', 'double', 'decimal'].includes(tsType)) {
+      const n = Number(raw);
+      return isNaN(n) ? raw : n;
+    }
+    if (tsType === 'boolean' || tsType === 'bool') {
+      if (raw === 'true' || raw === true) return true;
+      if (raw === 'false' || raw === false) return false;
+    }
+  }
+  if (typeof raw === 'string' && /^-?\d+\.?\d*$/.test(raw.trim()) && !/^0\d/.test(raw.trim())) {
+    const n = Number(raw);
+    if (!isNaN(n) && String(n) === raw.trim()) return n;
+  }
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  return raw;
+}

package/typescript/googlesheets/index.d.ts

@@ -0,0 +1,2 @@
+export { An5SheetsAdapter, SheetsTableClient, createAn5SheetsAdapter, An5SheetsAdapterConfig } from './an5SheetsAdapter';
+export { parseSheetsConnectionString } from './parseConnectionString';

package/typescript/googlesheets/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSheetsConnectionString = exports.createAn5SheetsAdapter = exports.SheetsTableClient = exports.An5SheetsAdapter = void 0;
+var an5SheetsAdapter_1 = require("./an5SheetsAdapter");
+Object.defineProperty(exports, "An5SheetsAdapter", { enumerable: true, get: function () { return an5SheetsAdapter_1.An5SheetsAdapter; } });
+Object.defineProperty(exports, "SheetsTableClient", { enumerable: true, get: function () { return an5SheetsAdapter_1.SheetsTableClient; } });
+Object.defineProperty(exports, "createAn5SheetsAdapter", { enumerable: true, get: function () { return an5SheetsAdapter_1.createAn5SheetsAdapter; } });
+var parseConnectionString_1 = require("./parseConnectionString");
+Object.defineProperty(exports, "parseSheetsConnectionString", { enumerable: true, get: function () { return parseConnectionString_1.parseSheetsConnectionString; } });

package/typescript/googlesheets/index.ts

@@ -0,0 +1,2 @@
+export { An5SheetsAdapter, SheetsTableClient, createAn5SheetsAdapter, An5SheetsAdapterConfig } from './an5SheetsAdapter';
+export { parseSheetsConnectionString } from './parseConnectionString';

package/typescript/googlesheets/parseConnectionString.d.ts

@@ -0,0 +1,11 @@
+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 declare function parseSheetsConnectionString(url: string): An5SheetsAdapterConfig;

package/typescript/googlesheets/parseConnectionString.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSheetsConnectionString = parseSheetsConnectionString;
+/**
+ * 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).
+ */
+function parseSheetsConnectionString(url) {
+    const clean = url.replace(/^googlesheets:\/\//, '');
+    const parts = clean.split(';');
+    const spreadsheetId = parts[0].trim();
+    const config = {};
+    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 = { spreadsheetId };
+    if (config.clientemail)
+        result.clientEmail = config.clientemail;
+    if (config.privatekey)
+        result.privateKey = config.privatekey;
+    if (config.sheetmapping) {
+        const mapping = {};
+        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;
+}