@an5/adapters 0.2.1 → 0.2.3

package/typescript/an5Adapter.js

@@ -2,15 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAdapter = exports.AdapterTableClient = exports.An5AdapterTx = exports.An5Adapter = exports.setAdapterMetadata = void 0;
 exports.createAn5Adapter = createAn5Adapter;
-const crypto_1 = require("crypto");
+const uuid_1 = require("./base/uuid");
 const googlesheets_1 = require("./googlesheets");
 const parseConnectionString_1 = require("./googlesheets/parseConnectionString");
 const sql_1 = require("./base/sql");
 const metadata_1 = require("./base/metadata");
-const mssql_1 = require("./mssql");
-const postgres_1 = require("./postgres");
-const mysql_1 = require("./mysql");
-const sqlite_1 = require("./sqlite");
 var metadata_2 = require("./base/metadata");
 Object.defineProperty(exports, "setAdapterMetadata", { enumerable: true, get: function () { return metadata_2.setAdapterMetadata; } });
 function isSheetsConfig(config) {
@@ -18,9 +14,23 @@ function isSheetsConfig(config) {
 }
 // ─── An5Adapter ────────────────────────────────────────────────────────────────────
 class An5Adapter {
-    get dialect() { return this.sheetsAdapter ? 'googlesheets' : this.requireEngine().dialect; }
+    get dialect() {
+        if (this.sheetsAdapter)
+            return 'googlesheets';
+        if (this._engine)
+            return this._engine.dialect;
+        if (this._engineType === 'postgres')
+            return 'postgres';
+        if (this._engineType === 'mysql')
+            return 'mysql';
+        if (this._engineType === 'sqlite')
+            return 'sqlite';
+        return 'mssql';
+    }
     constructor(adapterConfig) {
-        this.engine = null;
+        this._engine = null;
+        this._engineType = null;
+        this._engineConfig = null;
         this.sheetsAdapter = null;
         if (isSheetsConfig(adapterConfig)) {
             this.sheetsAdapter = new googlesheets_1.An5SheetsAdapter(adapterConfig);
@@ -31,23 +41,48 @@ class An5Adapter {
             this.sheetsAdapter = new googlesheets_1.An5SheetsAdapter((0, parseConnectionString_1.parseSheetsConnectionString)(cs));
             return;
         }
+        this._engineConfig = adapterConfig;
         if (cs.startsWith('postgres://') || cs.startsWith('postgresql://')) {
-            this.engine = new postgres_1.PostgresEngine(adapterConfig);
+            this._engineType = 'postgres';
         }
         else if (cs.startsWith('mysql://') || cs.startsWith('mariadb://')) {
-            this.engine = new mysql_1.MysqlEngine(adapterConfig);
+            this._engineType = 'mysql';
         }
         else if (cs.startsWith('sqlite://') || cs.endsWith('.sqlite') || cs.endsWith('.db')) {
-            this.engine = new sqlite_1.SqliteEngine(adapterConfig);
+            this._engineType = 'sqlite';
         }
         else {
-            this.engine = new mssql_1.MssqlEngine(adapterConfig);
+            this._engineType = 'mssql';
         }
     }
-    requireEngine() {
-        if (!this.engine)
+    async requireEngine() {
+        if (!this._engine && this._engineType) {
+            switch (this._engineType) {
+                case 'postgres': {
+                    const { PostgresEngine } = require('./postgres.js');
+                    this._engine = new PostgresEngine(this._engineConfig);
+                    break;
+                }
+                case 'mysql': {
+                    const { MysqlEngine } = require('./mysql.js');
+                    this._engine = new MysqlEngine(this._engineConfig);
+                    break;
+                }
+                case 'sqlite': {
+                    const { SqliteEngine } = require('./sqlite.js');
+                    this._engine = new SqliteEngine(this._engineConfig);
+                    break;
+                }
+                case 'mssql': {
+                    const { MssqlEngine } = require('./mssql.js');
+                    this._engine = new MssqlEngine(this._engineConfig);
+                    break;
+                }
+            }
+        }
+        if (!this._engine)
             throw new Error('SQL engine is not available for Google Sheets adapter');
-        return this.engine;
+        return this._engine;
     }
     requireSheetsAdapter() {
         if (!this.sheetsAdapter)
@@ -57,19 +92,19 @@ class An5Adapter {
     async exec(query, params) {
         if (this.sheetsAdapter)
             return this.sheetsAdapter.exec(query, params);
-        return this.requireEngine().exec(query, params);
+        return (await this.requireEngine()).exec(query, params);
     }
     /** INTERNAL: used by AdapterTableClient for DML statements needing row count */
     async _executeRaw(query, params) {
-        return this.requireEngine().executeRaw(query, params);
+        return (await this.requireEngine()).executeRaw(query, params);
     }
     /** Execute a raw query with positional values → @p_0, @p_1, ... per dialect */
     async $queryRawUnsafe(query, ...values) {
         if (this.sheetsAdapter)
             return this.sheetsAdapter.$queryRawUnsafe(query, ...values);
+        const engine = await this.requireEngine();
         const params = {};
         values.forEach((v, i) => { params[`p_${i}`] = v; });
-        // Normalise external positional placeholders → @p_N so each engine can re-transform
         let q = query;
         if (this.dialect === 'postgres') {
             let idx = 0;
@@ -79,11 +114,12 @@ class An5Adapter {
             let idx = 0;
             q = q.replace(/\?/g, () => `@p_${idx++}`);
         }
-        return this.exec(q, params);
+        return engine.exec(q, params);
     }
     async $executeRaw(query, ...values) {
         if (this.sheetsAdapter)
             return this.sheetsAdapter.$executeRaw(query, ...values);
+        const engine = await this.requireEngine();
         const params = {};
         values.forEach((v, i) => { params[`p_${i}`] = v; });
         let q = query;
@@ -95,7 +131,7 @@ class An5Adapter {
             let idx = 0;
             q = q.replace(/\?/g, () => `@p_${idx++}`);
         }
-        return this.requireEngine().executeRaw(q, params);
+        return engine.executeRaw(q, params);
     }
     async $executeRawUnsafe(query, ...values) {
         return this.$executeRaw(query, ...values);
@@ -103,19 +139,20 @@ class An5Adapter {
     async $connect() {
         if (this.sheetsAdapter)
             return this.sheetsAdapter.$connect();
-        await this.requireEngine().connect();
+        await (await this.requireEngine()).connect();
     }
     async $disconnect() {
         if (this.sheetsAdapter)
             return this.sheetsAdapter.$disconnect();
-        await this.requireEngine().disconnect();
+        await (await this.requireEngine()).disconnect();
     }
     async $transaction(fn, _options) {
         if (this.sheetsAdapter)
             return this.sheetsAdapter.$transaction(fn, _options);
         if (Array.isArray(fn))
             return Promise.all(fn);
-        const handle = await this.requireEngine().beginTransaction();
+        const engine = await this.requireEngine();
+        const handle = await engine.beginTransaction();
         const txAdapter = new An5AdapterTx(handle, this.dialect);
         try {
             const result = await fn(txAdapter);
@@ -267,7 +304,7 @@ class AdapterTableClient {
             const normalizedType = String(rawType).toLowerCase();
             const isStringType = ['string', 'uuid', 'uniqueidentifier', 'nvarchar', 'varchar', 'text'].includes(normalizedType);
             if (isStringType && !data[idFieldName])
-                data[idFieldName] = (0, crypto_1.randomUUID)();
+                data[idFieldName] = (0, uuid_1.generateUUID)();
         }
         const cols = Object.keys(data).filter(k => data[k] !== undefined);
         const params = {};

package/typescript/base/uuid.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Cross-platform UUID generator safe for both Browser and Node.js environments.
+ * Uses crypto.randomUUID() when available, with a standard RFC4122 v4 fallback.
+ */
+export declare function generateUUID(): string;

package/typescript/base/uuid.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateUUID = generateUUID;
+/**
+ * Cross-platform UUID generator safe for both Browser and Node.js environments.
+ * Uses crypto.randomUUID() when available, with a standard RFC4122 v4 fallback.
+ */
+function generateUUID() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}

package/typescript/browser.d.ts

@@ -0,0 +1,5 @@
+export { An5SheetsAdapter, SheetsTableClient, createAn5SheetsAdapter } from './googlesheets';
+export type { An5SheetsAdapterConfig } from './googlesheets';
+export type { An5AdapterConfig, Dialect } from './base/types';
+export { getFieldsForModel, getModelToTable, setAdapterMetadata } from './base/metadata';
+export type { AdapterMetadata } from './base/metadata';

package/typescript/browser.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setAdapterMetadata = exports.getModelToTable = exports.getFieldsForModel = exports.createAn5SheetsAdapter = exports.SheetsTableClient = exports.An5SheetsAdapter = void 0;
+// Browser-safe entry — no SQL engine imports
+var googlesheets_1 = require("./googlesheets");
+Object.defineProperty(exports, "An5SheetsAdapter", { enumerable: true, get: function () { return googlesheets_1.An5SheetsAdapter; } });
+Object.defineProperty(exports, "SheetsTableClient", { enumerable: true, get: function () { return googlesheets_1.SheetsTableClient; } });
+Object.defineProperty(exports, "createAn5SheetsAdapter", { enumerable: true, get: function () { return googlesheets_1.createAn5SheetsAdapter; } });
+var metadata_1 = require("./base/metadata");
+Object.defineProperty(exports, "getFieldsForModel", { enumerable: true, get: function () { return metadata_1.getFieldsForModel; } });
+Object.defineProperty(exports, "getModelToTable", { enumerable: true, get: function () { return metadata_1.getModelToTable; } });
+Object.defineProperty(exports, "setAdapterMetadata", { enumerable: true, get: function () { return metadata_1.setAdapterMetadata; } });

package/typescript/googlesheets/adapter.d.ts

@@ -7,7 +7,7 @@ export declare class An5SheetsAdapter {
     config: ReturnType<typeof resolveConfig>;
     private sheetsCache;
     constructor(config: An5SheetsAdapterConfig);
-    private get isOAuth();
+    private get isFetchMode();
     getSheets(): Promise<any>;
     private getApi;
     invalidateCache(): void;

package/typescript/googlesheets/adapter.js

@@ -2,17 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.An5SheetsAdapter = void 0;
 exports.createAn5SheetsAdapter = createAn5SheetsAdapter;
-const googleapis_1 = require("googleapis");
 const config_1 = require("./config");
 const sqlExecutor_1 = require("./sqlExecutor");
 const tableClient_1 = require("./tableClient");
 const retry_1 = require("./retry");
-// ─── Fetch-based API proxy for OAuth Access Token (browser-compatible) ────────
-function createFetchApi(spreadsheetId, accessToken) {
+// ─── Fetch-based API proxy for OAuth Access Token / API Key (browser-compatible) ──
+function createFetchApi(spreadsheetId, accessToken, apiKey) {
     const base = `https://sheets.googleapis.com/v4/spreadsheets/${spreadsheetId}`;
-    const headers = { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' };
+    const headers = { 'Content-Type': 'application/json' };
+    if (accessToken) {
+        headers['Authorization'] = `Bearer ${accessToken}`;
+    }
     async function request(method, path, body) {
-        const url = path.startsWith('http') ? path : `${base}${path}`;
+        let url = path.startsWith('http') ? path : `${base}${path}`;
+        if (apiKey) {
+            const sep = url.includes('?') ? '&' : '?';
+            url += `${sep}key=${encodeURIComponent(apiKey)}`;
+        }
         const opts = { method, headers };
         if (body)
             opts.body = JSON.stringify(body);
@@ -74,23 +80,28 @@ class An5SheetsAdapter {
         this.sheetsCache = null;
         this.config = (0, config_1.resolveConfig)(config);
     }
-    get isOAuth() {
-        return !!this.config.accessToken;
+    get isFetchMode() {
+        return !!this.config.accessToken || !!this.config.apiKey;
     }
     async getSheets() {
-        if (this.isOAuth) {
+        if (this.isFetchMode) {
             if (!this.fetchApi) {
-                this.fetchApi = createFetchApi(this.config.spreadsheetId, this.config.accessToken);
+                this.fetchApi = createFetchApi(this.config.spreadsheetId, this.config.accessToken, this.config.apiKey);
             }
             return this.fetchApi;
         }
+        const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
+        if (isBrowser) {
+            throw new Error('Google Sheets adapter in browser mode requires "accessToken" or "apiKey" configuration.');
+        }
         if (!this.sheets) {
-            const auth = new googleapis_1.google.auth.JWT({
+            const { google } = await import('googleapis');
+            const auth = new google.auth.JWT({
                 email: this.config.clientEmail,
                 key: this.config.privateKey,
                 scopes: ['https://www.googleapis.com/auth/spreadsheets'],
             });
-            this.sheets = googleapis_1.google.sheets({ version: 'v4', auth });
+            this.sheets = google.sheets({ version: 'v4', auth });
         }
         return this.sheets;
     }

package/typescript/googlesheets/an5SheetsAdapter.d.ts

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

package/typescript/googlesheets/config.d.ts

@@ -11,11 +11,14 @@ export interface An5SheetsAdapterConfig {
      * When provided, the adapter uses raw fetch() instead of googleapis JWT, making it compatible
      * with browser environments. Mutually exclusive with clientEmail/privateKey/credentials. */
     accessToken?: string;
+    /** Google API key for browser-based API access. */
+    apiKey?: string;
 }
 export declare function normalizeKey(key: string): string;
 export declare function resolveConfig(config: An5SheetsAdapterConfig): {
     spreadsheetId: string;
-    accessToken: string;
+    accessToken: string | undefined;
+    apiKey: string | undefined;
     sheetMapping: Record<string, string> | undefined;
     clientEmail?: undefined;
     privateKey?: undefined;
@@ -25,4 +28,5 @@ export declare function resolveConfig(config: An5SheetsAdapterConfig): {
     privateKey: string;
     sheetMapping: Record<string, string> | undefined;
     accessToken?: undefined;
+    apiKey?: undefined;
 };

package/typescript/googlesheets/config.js

@@ -12,10 +12,11 @@ function normalizeKey(key) {
     return `-----BEGIN PRIVATE KEY-----\n${lines}\n-----END PRIVATE KEY-----`;
 }
 function resolveConfig(config) {
-    if (config.accessToken) {
+    if (config.accessToken || config.apiKey) {
         return {
             spreadsheetId: config.spreadsheetId,
             accessToken: config.accessToken,
+            apiKey: config.apiKey,
             sheetMapping: config.sheetMapping,
         };
     }

package/typescript/googlesheets/helpers.js

@@ -45,6 +45,12 @@ function matchWhere(row, where) {
                 return false;
             continue;
         }
+        if (key === 'NOT') {
+            const notClauses = Array.isArray(value) ? value : [value];
+            if (notClauses.some((v) => matchWhere(row, v)))
+                return false;
+            continue;
+        }
         const cellVal = row[key];
         if (value === null) {
             if (cellVal !== null && cellVal !== undefined)
@@ -52,22 +58,30 @@ function matchWhere(row, where) {
         }
         else if (typeof value === 'object' && !(value instanceof Date)) {
             const v = value;
+            const caseInsensitive = v.mode === 'insensitive';
+            const normalize = (s) => caseInsensitive ? String(s ?? '').toLowerCase() : s;
             if (v.not !== undefined) {
                 if (v.not === null) {
                     if (cellVal === null || cellVal === undefined)
                         return false;
                 }
-                else if (cellVal == v.not)
+                else if (normalize(cellVal) == normalize(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)))
+            if (v.equals !== undefined && normalize(cellVal) != normalize(v.equals))
                 return false;
+            if (v.contains !== undefined) {
+                if (!cellVal || !normalize(String(cellVal)).includes(normalize(v.contains)))
+                    return false;
+            }
+            if (v.startsWith !== undefined) {
+                if (!cellVal || !normalize(String(cellVal)).startsWith(normalize(v.startsWith)))
+                    return false;
+            }
+            if (v.endsWith !== undefined) {
+                if (!cellVal || !normalize(String(cellVal)).endsWith(normalize(v.endsWith)))
+                    return false;
+            }
             if (v.gte !== undefined && !(Number(cellVal) >= Number(v.gte)))
                 return false;
             if (v.lte !== undefined && !(Number(cellVal) <= Number(v.lte)))
@@ -77,11 +91,16 @@ function matchWhere(row, where) {
             if (v.lt !== undefined && !(Number(cellVal) < Number(v.lt)))
                 return false;
             if (v.in !== undefined) {
-                if (!Array.isArray(v.in) || !v.in.includes(cellVal))
+                if (!Array.isArray(v.in) || !v.in.some((item) => item == cellVal))
+                    return false;
+            }
+            if (v.notIn !== undefined) {
+                if (Array.isArray(v.notIn) && v.notIn.some((item) => item == cellVal))
                     return false;
             }
         }
         else {
+            // loose equality to handle string/number coercion from sheet cells
             if (cellVal != value)
                 return false;
         }

package/typescript/googlesheets/index.d.ts

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

package/typescript/googlesheets/parseConnectionString.js

@@ -31,6 +31,10 @@ function parseSheetsConnectionString(url) {
         result.clientEmail = config.clientemail;
     if (config.privatekey)
         result.privateKey = config.privatekey;
+    if (config.accesstoken)
+        result.accessToken = config.accesstoken;
+    if (config.apikey)
+        result.apiKey = config.apikey;
     if (config.sheetmapping) {
         const mapping = {};
         for (const pair of config.sheetmapping.split(',')) {

package/typescript/googlesheets/retry.d.ts

@@ -1,3 +1,25 @@
-export declare const MAX_RETRIES = 3;
+export declare const MAX_RETRIES = 5;
 export declare const BASE_DELAY = 1000;
+export declare const MAX_DELAY = 32000;
+export declare const MAX_CONCURRENCY = 4;
+export declare const RATE_LIMIT_RPS = 0.9;
+declare class TokenBucket {
+    private tokens;
+    private lastRefill;
+    private readonly ratePerMs;
+    private readonly capacity;
+    constructor(ratePerSecond: number, capacity: number);
+    /** Wait until a token is available, then consume one. */
+    acquire(): Promise<void>;
+}
+declare class ConcurrencyLimiter {
+    private readonly max;
+    private running;
+    private queue;
+    constructor(max: number);
+    acquire(): Promise<void>;
+    release(): void;
+}
 export declare function withRetry<T>(fn: () => Promise<T>, attempt?: number): Promise<T>;
+/** Expose for testing / custom configurations */
+export { TokenBucket, ConcurrencyLimiter };

package/typescript/googlesheets/retry.js

@@ -1,19 +1,83 @@
 "use strict";
-// ─── Retry helper ─────────────────────────────────────────────────────────────
+// ─── Rate Limit & Retry helper ─────────────────────────────────────────────────
+//
+// Google Sheets API quota (default): 100 requests per 100 seconds per project.
+// Strategy:
+//   1. Token-bucket rate limiter  — proactively throttles before hitting quota
+//   2. Concurrency limiter         — max N parallel requests to avoid burst
+//   3. Exponential backoff + jitter — reactive recovery when 429/403/5xx hit
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BASE_DELAY = exports.MAX_RETRIES = void 0;
+exports.ConcurrencyLimiter = exports.TokenBucket = exports.RATE_LIMIT_RPS = exports.MAX_CONCURRENCY = exports.MAX_DELAY = exports.BASE_DELAY = exports.MAX_RETRIES = void 0;
 exports.withRetry = withRetry;
-exports.MAX_RETRIES = 3;
-exports.BASE_DELAY = 1000;
-function isRateLimitError(err) {
+// ─── Config ────────────────────────────────────────────────────────────────────
+exports.MAX_RETRIES = 5;
+exports.BASE_DELAY = 1000; // ms
+exports.MAX_DELAY = 32000; // ms cap for backoff
+exports.MAX_CONCURRENCY = 4; // parallel in-flight requests
+exports.RATE_LIMIT_RPS = 0.9; // tokens/second (stay under 1 req/s safely)
+// ─── Token Bucket ──────────────────────────────────────────────────────────────
+class TokenBucket {
+    constructor(ratePerSecond, capacity) {
+        this.ratePerMs = ratePerSecond / 1000;
+        this.capacity = capacity;
+        this.tokens = capacity;
+        this.lastRefill = Date.now();
+    }
+    /** Wait until a token is available, then consume one. */
+    async acquire() {
+        while (true) {
+            const now = Date.now();
+            const elapsed = now - this.lastRefill;
+            this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.ratePerMs);
+            this.lastRefill = now;
+            if (this.tokens >= 1) {
+                this.tokens -= 1;
+                return;
+            }
+            // Wait for enough time to refill one token
+            const waitMs = Math.ceil((1 - this.tokens) / this.ratePerMs);
+            await new Promise(r => setTimeout(r, waitMs));
+        }
+    }
+}
+exports.TokenBucket = TokenBucket;
+// ─── Concurrency Limiter ───────────────────────────────────────────────────────
+class ConcurrencyLimiter {
+    constructor(max) {
+        this.max = max;
+        this.running = 0;
+        this.queue = [];
+    }
+    async acquire() {
+        if (this.running < this.max) {
+            this.running++;
+            return;
+        }
+        await new Promise(resolve => this.queue.push(resolve));
+        this.running++;
+    }
+    release() {
+        this.running--;
+        if (this.queue.length > 0) {
+            const next = this.queue.shift();
+            next();
+        }
+    }
+}
+exports.ConcurrencyLimiter = ConcurrencyLimiter;
+// ─── Singleton shared across all adapter instances ─────────────────────────────
+const _bucket = new TokenBucket(exports.RATE_LIMIT_RPS, 10);
+const _concurrency = new ConcurrencyLimiter(exports.MAX_CONCURRENCY);
+// ─── Error classification ──────────────────────────────────────────────────────
+function isRetryableError(err) {
     const code = err?.code || err?.status || err?.response?.status;
     if (code === 429)
         return true;
-    if (code === 500 || code === 503)
+    if (code === 500 || code === 503 || code === 502)
         return true;
     if (code === 403) {
         const reason = err?.errors?.[0]?.reason || '';
-        if (reason === 'rateLimitExceeded')
+        if (reason === 'rateLimitExceeded' || reason === 'userRateLimitExceeded')
             return true;
         if (typeof err?.body === 'string' && err.body.includes('rateLimitExceeded'))
             return true;
@@ -22,18 +86,30 @@ function isRateLimitError(err) {
     }
     return false;
 }
+function getRetryDelay(err, attempt) {
+    // Honour server-provided Retry-After
+    if (err?.retryAfter)
+        return err.retryAfter * 1000;
+    // Full jitter exponential backoff: random in [0, min(cap, base * 2^attempt)]
+    const cap = Math.min(exports.MAX_DELAY, exports.BASE_DELAY * Math.pow(2, attempt));
+    return Math.random() * cap;
+}
+// ─── Public API ────────────────────────────────────────────────────────────────
 async function withRetry(fn, attempt = 1) {
+    await _bucket.acquire();
+    await _concurrency.acquire();
     try {
         return await fn();
     }
     catch (err) {
-        if (isRateLimitError(err) && attempt <= exports.MAX_RETRIES) {
-            const delay = err.retryAfter
-                ? err.retryAfter * 1000
-                : exports.BASE_DELAY * Math.pow(2, attempt - 1) + Math.random() * 500;
+        if (isRetryableError(err) && attempt <= exports.MAX_RETRIES) {
+            const delay = getRetryDelay(err, attempt);
             await new Promise(r => setTimeout(r, delay));
             return withRetry(fn, attempt + 1);
         }
         throw err;
     }
+    finally {
+        _concurrency.release();
+    }
 }

package/typescript/googlesheets/tableClient.d.ts

@@ -30,6 +30,7 @@ export declare class SheetsTableClient<T = any> {
     count(args?: {
         where?: any;
     }): Promise<number>;
+    private assignId;
     create(args: {
         data: Partial<T>;
     }): Promise<T>;