@an5/adapters 0.2.10 → 0.2.11

package/README.md

@@ -276,8 +276,38 @@ db.transaction(perform_transfer)
 | `groupBy(args)` | Group by fields with aggregations and pagination |
 | `vectorSearch(args)` | Semantic vector similarity search |
 
+Generated TypeScript field metadata marks schema primary keys with `isId: true`.
+SQL and Google Sheets `create` use this marker to identify custom primary-key
+names before falling back to `id` or `...Id` for older metadata. Regenerate the
+client to enable this behavior for existing custom-key schemas.
+
+`createMany` uses a bulk statement when every row supplies the same columns.
+Rows with different column sets or missing generated UUID keys are inserted
+individually so omitted columns retain their defaults and UUID keys are assigned. Bulk failures are propagated without retrying
+individual rows. Wrap mixed-column inserts in `$transaction` when they must
+succeed or roll back together.
+
+For SQL adapters, `skipDuplicates: true` skips only unique or primary-key
+violations. Connection failures and other constraint errors are propagated.
+Google Sheets does not enforce unique constraints; this flag does not deduplicate
+sheet rows, and failed batch appends are propagated without individual retries.
+
+For SQL adapters, `findMany` and `groupBy` accept `skip` without `take` to
+return all remaining rows or groups. Supply `orderBy` for stable row pagination;
+`groupBy` orders by its grouping fields when pagination has no explicit ordering.
+With relation metadata configured, `groupBy.where` supports the same relation
+filters as `findMany.where`, including `some`, `none`, `every`, `is`, and `isNot`.
+
 ---
 
 ## License
 
 MIT
+
+### Google Sheets desktop OAuth
+
+Google Sheets connections accept `accessToken`, `refreshToken`, `oauthClientId`, optional `oauthClientSecret`, and `tokenExpiresAt` (Unix milliseconds). The VS Code connection UI can generate and store this URI after browser sign-in and spreadsheet selection. Values in the semicolon-delimited URI must be URL encoded. Keep offline credentials in secure storage; do not commit them.
+
+The adapter refreshes expired access tokens before requests, shares concurrent refresh requests, and retries authentication failures once after refreshing. Revoked credentials report a reconnect error. Existing service account, API key and access-token-only configurations remain supported.
+
+For web applications, use a Google Web OAuth client and per-user access tokens. The browser adapter rejects offline desktop credentials and service account private keys. A browser connection manager must handle account selection, token reacquisition and SQLite persistence; see the [browser connection design](https://an5orm.github.io/docs/guides/browser-connections/).

package/dist/an5Adapter.js

@@ -28,38 +28,57 @@ function sanitizeParamName(name) {
     const cleaned = String(name).replace(/[^A-Za-z0-9_]/g, '_');
     return /^[A-Za-z]/.test(cleaned) ? cleaned : `p_${cleaned}`;
 }
+/** Match only unique/primary-key violations, never general constraint errors. */
+function isDuplicateKeyError(error, dialect) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const e = error;
+    if (dialect === 'postgres')
+        return e.code === '23505';
+    if (dialect === 'mysql')
+        return e.code === 'ER_DUP_ENTRY' || e.errno === 1062;
+    if (dialect === 'sqlite') {
+        return e.code === 'SQLITE_CONSTRAINT_UNIQUE' || e.code === 'SQLITE_CONSTRAINT_PRIMARYKEY'
+            || e.errcode === 2067 || e.errcode === 1555;
+    }
+    if (dialect === 'mssql') {
+        const number = e.number ?? e.originalError?.info?.number;
+        return number === 2601 || number === 2627;
+    }
+    return false;
+}
 function appendUpdateSet(sets, params, col, val, dialect) {
     const quoted = (0, sql_1.quote)(col, dialect);
     const safeCol = sanitizeParamName(col);
     if (val && typeof val === 'object' && !(val instanceof Date)) {
         if (val.increment !== undefined) {
-            sets.push(`${quoted} = ${quoted} + @s_${safeCol}_inc`);
-            params[`s_${safeCol}_inc`] = val.increment;
+            const p = (0, sql_1.bindParam)(params, `s_${safeCol}_inc`, val.increment);
+            sets.push(`${quoted} = ${quoted} + @${p}`);
             return;
         }
         if (val.decrement !== undefined) {
-            sets.push(`${quoted} = ${quoted} - @s_${safeCol}_dec`);
-            params[`s_${safeCol}_dec`] = val.decrement;
+            const p = (0, sql_1.bindParam)(params, `s_${safeCol}_dec`, val.decrement);
+            sets.push(`${quoted} = ${quoted} - @${p}`);
             return;
         }
         if (val.multiply !== undefined) {
-            sets.push(`${quoted} = ${quoted} * @s_${safeCol}_mul`);
-            params[`s_${safeCol}_mul`] = val.multiply;
+            const p = (0, sql_1.bindParam)(params, `s_${safeCol}_mul`, val.multiply);
+            sets.push(`${quoted} = ${quoted} * @${p}`);
             return;
         }
         if (val.divide !== undefined) {
-            sets.push(`${quoted} = ${quoted} / @s_${safeCol}_div`);
-            params[`s_${safeCol}_div`] = val.divide;
+            const p = (0, sql_1.bindParam)(params, `s_${safeCol}_div`, val.divide);
+            sets.push(`${quoted} = ${quoted} / @${p}`);
             return;
         }
         if (val.set !== undefined) {
-            sets.push(`${quoted} = @s_${safeCol}_set`);
-            params[`s_${safeCol}_set`] = val.set;
+            const p = (0, sql_1.bindParam)(params, `s_${safeCol}_set`, val.set);
+            sets.push(`${quoted} = @${p}`);
             return;
         }
     }
-    sets.push(`${quoted} = @s_${safeCol}`);
-    params[`s_${safeCol}`] = val;
+    const p = (0, sql_1.bindParam)(params, `s_${safeCol}`, val);
+    sets.push(`${quoted} = @${p}`);
 }
 function selectedAggregateFields(fields) {
     if (!fields || typeof fields !== 'object')
@@ -717,7 +736,8 @@ class AdapterTableClient {
                     query += ` WHERE ${whereSql}`;
                 if (orderSql)
                     query += ` ${orderSql}`;
-                query += ` LIMIT ${take ?? 'ALL'} OFFSET ${skip}`;
+                const limit = take ?? (this.dialect === 'sqlite' ? '-1' : this.dialect === 'mysql' ? '18446744073709551615' : 'ALL');
+                query += ` LIMIT ${limit} OFFSET ${skip}`;
             }
             else {
                 // mssql requires ORDER BY before OFFSET/FETCH
@@ -779,9 +799,7 @@ class AdapterTableClient {
             }
         }
         const fields = (0, metadata_1.getFieldsForModel)(this.modelName);
-        const idFieldName = Object.prototype.hasOwnProperty.call(fields, 'id')
-            ? 'id'
-            : Object.keys(fields).find((name) => name.endsWith('_id') || name.endsWith('Id') || name.toLowerCase() === 'id');
+        const idFieldName = (0, metadata_1.resolveIdField)(fields);
         const data = { ...rawData };
         if (idFieldName) {
             const fieldDef = fields[idFieldName];
@@ -836,8 +854,18 @@ class AdapterTableClient {
         if (firstRow === undefined)
             return { count: 0 };
         const firstCols = Object.keys(firstRow).filter(k => firstRow[k] !== undefined);
-        // Bulk INSERT for the common case (same columns, no skipDuplicates)
-        if (firstCols.length > 0 && !args.skipDuplicates) {
+        const sameColumns = args.data.every(row => {
+            const cols = Object.keys(row).filter(k => row[k] !== undefined);
+            return cols.length === firstCols.length && firstCols.every(col => cols.includes(col));
+        });
+        const fields = (0, metadata_1.getFieldsForModel)(this.modelName);
+        const idFieldName = (0, metadata_1.resolveIdField)(fields);
+        const idDef = idFieldName ? fields[idFieldName] : undefined;
+        const idType = typeof idDef === 'string' ? idDef : (idDef?.ts || idDef?.sql || idDef?.type || '');
+        const generatesId = ['string', 'uuid', 'uniqueidentifier', 'nvarchar', 'varchar', 'text'].includes(String(idType).toLowerCase());
+        const needsGeneratedId = idFieldName && generatesId && args.data.some(row => !row[idFieldName]);
+        // Rows needing generated IDs follow create's default handling.
+        if (firstCols.length > 0 && sameColumns && !needsGeneratedId && !args.skipDuplicates) {
             const params = {};
             const rowPlaceholders = [];
             for (let r = 0; r < args.data.length; r++) {
@@ -850,13 +878,8 @@ class AdapterTableClient {
                 rowPlaceholders.push(`(${vals.join(', ')})`);
             }
             const query = `INSERT INTO ${this.tableName} (${firstCols.map(c => (0, sql_1.quote)(c, this.dialect)).join(', ')}) VALUES ${rowPlaceholders.join(', ')}`;
-            try {
-                await this.doExecuteRaw(query, params);
-                return { count: args.data.length };
-            }
-            catch {
-                // fallback below if bulk fails (e.g. mixed column sets)
-            }
+            await this.doExecuteRaw(query, params);
+            return { count: args.data.length };
         }
         // Row-by-row fallback
         let count = 0;
@@ -866,7 +889,7 @@ class AdapterTableClient {
                 count++;
             }
             catch (e) {
-                if (!args.skipDuplicates)
+                if (!args.skipDuplicates || !isDuplicateKeyError(e, this.dialect))
                     throw e;
             }
         }
@@ -1046,7 +1069,7 @@ class AdapterTableClient {
     }
     async groupBy(args) {
         const params = {};
-        const whereSql = (0, sql_1.parseWhere)(this.modelName, args?.where, params, this.dialect);
+        const whereSql = (0, sql_1.parseWhere)(this.modelName, args?.where, params, this.dialect, '', this.whereContext());
         const byFields = normalizeByFields(args?.by);
         if (byFields.length === 0)
             throw new Error("groupBy requires 'by' fields");
@@ -1076,9 +1099,8 @@ class AdapterTableClient {
             const skip = toNonNegativeInt(args?.skip);
             const take = toNonNegativeInt(args?.take, 1);
             if (this.dialect === 'postgres' || this.dialect === 'mysql' || this.dialect === 'sqlite') {
-                if (hasTake)
-                    query += ` LIMIT ${take}`;
-                query += ` OFFSET ${skip}`;
+                const limit = hasTake ? take : (this.dialect === 'sqlite' ? '-1' : this.dialect === 'mysql' ? '18446744073709551615' : 'ALL');
+                query += ` LIMIT ${limit} OFFSET ${skip}`;
             }
             else {
                 query += ` OFFSET ${skip} ROWS`;

package/dist/base/metadata.d.ts

@@ -11,6 +11,8 @@ export interface ModelFieldMeta {
     isId?: boolean;
     [key: string]: any;
 }
+/** Prefer schema primary-key metadata; retain name inference for legacy clients. */
+export declare function resolveIdField(fields: Record<string, any>): string | undefined;
 export interface AdapterMetadata {
     modelToTable?: Record<string, string>;
     modelFields?: Record<string, any>;

package/dist/base/metadata.js

@@ -1,11 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveIdField = resolveIdField;
 exports.setAdapterMetadata = setAdapterMetadata;
 exports.getModelToTable = getModelToTable;
 exports.getFieldsForModel = getFieldsForModel;
 exports.getRelationMap = getRelationMap;
 exports.getRelationsForModel = getRelationsForModel;
 exports.createAdapterProxy = createAdapterProxy;
+/** Prefer schema primary-key metadata; retain name inference for legacy clients. */
+function resolveIdField(fields) {
+    const primaryKey = Object.keys(fields).find(name => fields[name]?.isId === true);
+    if (primaryKey)
+        return primaryKey;
+    if (Object.prototype.hasOwnProperty.call(fields, 'id'))
+        return 'id';
+    return Object.keys(fields).find(name => name.endsWith('_id') || name.endsWith('Id') || name.toLowerCase() === 'id');
+}
 let modelToTable = {};
 let modelFields = {};
 let relationMap = {};

package/dist/base/sql.d.ts

@@ -3,6 +3,8 @@ import type { RelationDef } from './metadata';
 export declare function quote(name: string, dialect: Dialect): string;
 /** Quote a full table reference (may already be quoted, and may contain schema parts). */
 export declare function quoteTable(name: string, dialect: Dialect): string;
+/** Allocate parameters without overwriting values from sibling clauses. */
+export declare function bindParam(params: Record<string, any>, name: string, value: any): string;
 export interface WhereContext {
     /** Relations of the current model keyed by relation name. */
     relationMap?: Record<string, Record<string, RelationDef>>;

package/dist/base/sql.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.quote = quote;
 exports.quoteTable = quoteTable;
+exports.bindParam = bindParam;
 exports.parseWhere = parseWhere;
 exports.buildOrderBy = buildOrderBy;
 // ─── Quoting ───────────────────────────────────────────────────────────────────────
@@ -38,6 +39,15 @@ function sanitizeParamName(name) {
     const cleaned = String(name).replace(/[^A-Za-z0-9_]/g, '_');
     return /^[A-Za-z]/.test(cleaned) ? cleaned : `p_${cleaned}`;
 }
+/** Allocate parameters without overwriting values from sibling clauses. */
+function bindParam(params, name, value) {
+    let candidate = name;
+    let suffix = 1;
+    while (Object.prototype.hasOwnProperty.call(params, candidate))
+        candidate = `${name}_${suffix++}`;
+    params[candidate] = value;
+    return candidate;
+}
 function normalizeSortDirection(dir) {
     return typeof dir === 'string' && dir.toUpperCase() === 'DESC' ? 'DESC' : 'ASC';
 }
@@ -119,15 +129,12 @@ function parseWhere(modelName, where, params, dialect, prefix = '', ctx) {
                         conditions.push(`${col} IS NOT NULL`);
                     }
                     else if (v.not && typeof v.not === 'object' && !(v.not instanceof Date) && !Array.isArray(v.not)) {
-                        const nestedParams = {};
-                        const nestedSql = parseWhere(modelName, { [key]: v.not }, nestedParams, dialect, `${prefix}${key}_not_`, ctx);
-                        Object.assign(params, nestedParams);
+                        const nestedSql = parseWhere(modelName, { [key]: v.not }, params, dialect, `${prefix}${key}_not_`, ctx);
                         if (nestedSql)
                             conditions.push(`NOT (${nestedSql})`);
                     }
                     else {
-                        const p = `${pname}_not`;
-                        params[p] = v.not;
+                        const p = bindParam(params, `${pname}_not`, v.not);
                         conditions.push(`${col} <> @${p}`);
                     }
                 }
@@ -136,49 +143,41 @@ function parseWhere(modelName, where, params, dialect, prefix = '', ctx) {
                         conditions.push(`${col} IS NULL`);
                     }
                     else {
-                        const p = `${pname}_eq`;
-                        params[p] = v.equals;
+                        const p = bindParam(params, `${pname}_eq`, v.equals);
                         conditions.push(`${col} = @${p}`);
                     }
                 }
                 if (v.contains !== undefined) {
-                    const p = `${pname}_co`;
-                    params[p] = `%${v.contains}%`;
+                    const p = bindParam(params, `${pname}_co`, `%${v.contains}%`);
                     conditions.push(`${col} LIKE @${p}`);
                 }
                 if (v.startsWith !== undefined) {
-                    const p = `${pname}_sw`;
-                    params[p] = `${v.startsWith}%`;
+                    const p = bindParam(params, `${pname}_sw`, `${v.startsWith}%`);
                     conditions.push(`${col} LIKE @${p}`);
                 }
                 if (v.endsWith !== undefined) {
-                    const p = `${pname}_ew`;
-                    params[p] = `%${v.endsWith}`;
+                    const p = bindParam(params, `${pname}_ew`, `%${v.endsWith}`);
                     conditions.push(`${col} LIKE @${p}`);
                 }
                 if (v.gte !== undefined) {
-                    const p = `${pname}_gte`;
-                    params[p] = v.gte;
+                    const p = bindParam(params, `${pname}_gte`, v.gte);
                     conditions.push(`${col} >= @${p}`);
                 }
                 if (v.lte !== undefined) {
-                    const p = `${pname}_lte`;
-                    params[p] = v.lte;
+                    const p = bindParam(params, `${pname}_lte`, v.lte);
                     conditions.push(`${col} <= @${p}`);
                 }
                 if (v.gt !== undefined) {
-                    const p = `${pname}_gt`;
-                    params[p] = v.gt;
+                    const p = bindParam(params, `${pname}_gt`, v.gt);
                     conditions.push(`${col} > @${p}`);
                 }
                 if (v.lt !== undefined) {
-                    const p = `${pname}_lt`;
-                    params[p] = v.lt;
+                    const p = bindParam(params, `${pname}_lt`, v.lt);
                     conditions.push(`${col} < @${p}`);
                 }
                 if (v.in !== undefined) {
                     if (Array.isArray(v.in) && v.in.length > 0) {
-                        const ps = v.in.map((x, i) => { const p = `${pname}_in${i}`; params[p] = x; return `@${p}`; });
+                        const ps = v.in.map((x, i) => { const p = bindParam(params, `${pname}_in${i}`, x); return `@${p}`; });
                         conditions.push(`${col} IN (${ps.join(', ')})`);
                     }
                     else {
@@ -187,7 +186,7 @@ function parseWhere(modelName, where, params, dialect, prefix = '', ctx) {
                 }
                 if (v.notIn !== undefined) {
                     if (Array.isArray(v.notIn) && v.notIn.length > 0) {
-                        const ps = v.notIn.map((x, i) => { const p = `${pname}_notin${i}`; params[p] = x; return `@${p}`; });
+                        const ps = v.notIn.map((x, i) => { const p = bindParam(params, `${pname}_notin${i}`, x); return `@${p}`; });
                         conditions.push(`${col} NOT IN (${ps.join(', ')})`);
                     }
                     else {
@@ -196,8 +195,8 @@ function parseWhere(modelName, where, params, dialect, prefix = '', ctx) {
                 }
             }
             else {
-                params[pname] = value;
-                conditions.push(`${col} = @${pname}`);
+                const p = bindParam(params, pname, value);
+                conditions.push(`${col} = @${p}`);
             }
         }
     }

package/dist/googlesheets/adapter.js

@@ -3,27 +3,31 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.An5SheetsAdapter = void 0;
 exports.createAn5SheetsAdapter = createAn5SheetsAdapter;
 const config_1 = require("./config");
+const oauth_1 = require("./oauth");
 const sqlExecutor_1 = require("./sqlExecutor");
 const tableClient_1 = require("./tableClient");
 const retry_1 = require("./retry");
 const metadata_1 = require("../base/metadata");
 // ─── Fetch-based API proxy for OAuth Access Token / API Key (browser-compatible) ──
-function createFetchApi(spreadsheetId, accessToken, apiKey) {
+function createFetchApi(spreadsheetId, accessToken, apiKey, oauth = { spreadsheetId }) {
     const base = `https://sheets.googleapis.com/v4/spreadsheets/${spreadsheetId}`;
     const headers = { 'Content-Type': 'application/json' };
-    if (accessToken) {
-        headers['Authorization'] = `Bearer ${accessToken}`;
-    }
+    const tokenProvider = (0, oauth_1.sheetsTokenProvider)({ ...oauth, ...(accessToken ? { accessToken } : {}) });
     async function request(method, path, body) {
         let url = path.startsWith('http') ? path : `${base}${path}`;
         if (apiKey) {
             const sep = url.includes('?') ? '&' : '?';
             url += `${sep}key=${encodeURIComponent(apiKey)}`;
         }
-        const opts = { method, headers };
+        const token = await tokenProvider();
+        const opts = { method, headers: { ...headers, ...(token ? { Authorization: `Bearer ${token}` } : {}) } };
         if (body)
             opts.body = JSON.stringify(body);
-        const res = await fetch(url, opts);
+        let res = await fetch(url, opts);
+        if (res.status === 401 && oauth.refreshToken) {
+            const refreshed = await tokenProvider(true);
+            res = await fetch(url, { ...opts, headers: { ...headers, Authorization: `Bearer ${refreshed}` } });
+        }
         if (!res.ok) {
             const text = await res.text().catch(() => '');
             const err = new Error(`Google Sheets API error (${res.status}): ${text}`);
@@ -79,17 +83,21 @@ class An5SheetsAdapter {
         this.sheets = null;
         this.fetchApi = null;
         this.sheetsCache = null;
+        const browser = typeof window !== 'undefined' || (typeof self !== 'undefined' && typeof process === 'undefined');
+        if (browser && (config.refreshToken || config.oauthClientSecret || config.privateKey || config.credentials)) {
+            throw new Error('Browser Google Sheets connections require a user access token. Keep desktop OAuth refresh tokens and service account keys outside the browser.');
+        }
         this.config = (0, config_1.resolveConfig)(config);
         // Dynamic model access (`db.user` / `db.User`), same as An5Adapter.
         return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
     }
     get isFetchMode() {
-        return !!this.config.accessToken || !!this.config.apiKey;
+        return !!this.config.accessToken || !!this.config.refreshToken || !!this.config.apiKey;
     }
     async getSheets() {
         if (this.isFetchMode) {
             if (!this.fetchApi) {
-                this.fetchApi = createFetchApi(this.config.spreadsheetId, this.config.accessToken, this.config.apiKey);
+                this.fetchApi = createFetchApi(this.config.spreadsheetId, this.config.accessToken, this.config.apiKey, this.config);
             }
             return this.fetchApi;
         }

package/dist/googlesheets/config.d.ts

@@ -11,6 +11,11 @@ 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;
+    /** Offline desktop OAuth credentials. Keep these in secure storage, never source control. */
+    refreshToken?: string;
+    oauthClientId?: string;
+    oauthClientSecret?: string;
+    tokenExpiresAt?: number;
     /** Google API key for browser-based API access. */
     apiKey?: string;
 }
@@ -18,12 +23,20 @@ export declare function normalizeKey(key: string): string;
 export declare function resolveConfig(config: An5SheetsAdapterConfig): {
     spreadsheetId: string;
     accessToken: string | undefined;
+    refreshToken: string | undefined;
+    oauthClientId: string | undefined;
+    oauthClientSecret: string | undefined;
+    tokenExpiresAt: number | undefined;
     apiKey: string | undefined;
     sheetMapping: Record<string, string> | undefined;
     clientEmail?: never;
     privateKey?: never;
 } | {
     accessToken?: never;
+    refreshToken?: never;
+    oauthClientId?: never;
+    oauthClientSecret?: never;
+    tokenExpiresAt?: never;
     apiKey?: never;
     spreadsheetId: string;
     clientEmail: string;

package/dist/googlesheets/config.js

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

package/dist/googlesheets/oauth.d.ts

@@ -0,0 +1,3 @@
+import type { An5SheetsAdapterConfig } from './config';
+/** Deduplicate refresh requests within an adapter; do not expose token responses. */
+export declare function sheetsTokenProvider(config: An5SheetsAdapterConfig): (force?: boolean) => Promise<string | undefined>;

package/dist/googlesheets/oauth.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sheetsTokenProvider = sheetsTokenProvider;
+/** Deduplicate refresh requests within an adapter; do not expose token responses. */
+function sheetsTokenProvider(config) {
+    let token = config.accessToken;
+    let expiresAt = config.tokenExpiresAt;
+    let pending;
+    return async (force = false) => {
+        if (token && !force && (expiresAt === undefined || expiresAt > Date.now() + 60000))
+            return token;
+        if (!config.refreshToken || !config.oauthClientId) {
+            if (force || expiresAt !== undefined)
+                throw new Error('Google access expired. Reconnect your Google account.');
+            return token;
+        }
+        if (!pending)
+            pending = (async () => {
+                try {
+                    const response = await fetch('https://oauth2.googleapis.com/token', {
+                        method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                        body: new URLSearchParams({ grant_type: 'refresh_token', client_id: config.oauthClientId, refresh_token: config.refreshToken, ...(config.oauthClientSecret ? { client_secret: config.oauthClientSecret } : {}) }),
+                        signal: AbortSignal.timeout(20000),
+                    });
+                    if (!response.ok)
+                        throw new Error();
+                    const result = await response.json();
+                    if (!result.access_token || typeof result.access_token !== 'string' || typeof result.expires_in !== 'number' || !Number.isFinite(result.expires_in) || result.expires_in <= 0)
+                        throw new Error();
+                    token = result.access_token;
+                    expiresAt = Date.now() + result.expires_in * 1000;
+                    return token;
+                }
+                catch {
+                    throw new Error('Google access expired or was revoked. Reconnect your Google account.');
+                }
+                finally {
+                    pending = undefined;
+                }
+            })();
+        return pending;
+    };
+}

package/dist/googlesheets/parseConnectionString.js

@@ -36,6 +36,18 @@ function parseSheetsConnectionString(url) {
         result.privateKey = config.privatekey;
     if (config.accesstoken)
         result.accessToken = config.accesstoken;
+    if (config.refreshtoken)
+        result.refreshToken = config.refreshtoken;
+    if (config.oauthclientid)
+        result.oauthClientId = config.oauthclientid;
+    if (config.oauthclientsecret)
+        result.oauthClientSecret = config.oauthclientsecret;
+    if (config.tokenexpiresat) {
+        const expiry = Number(config.tokenexpiresat);
+        if (!Number.isFinite(expiry) || expiry < 0)
+            throw new Error('Invalid OAuth token expiry.');
+        result.tokenExpiresAt = expiry;
+    }
     if (config.apikey)
         result.apiKey = config.apikey;
     if (config.sheetmapping) {

package/dist/googlesheets/tableClient.js

@@ -6,11 +6,6 @@ const metadata_1 = require("../base/metadata");
 const helpers_1 = require("./helpers");
 const retry_1 = require("./retry");
 // ─── Utility ──────────────────────────────────────────────────────────────────
-function resolveIdField(fields) {
-    if (Object.prototype.hasOwnProperty.call(fields, 'id'))
-        return 'id';
-    return Object.keys(fields).find(name => name.endsWith('_id') || name.endsWith('Id') || name.toLowerCase() === 'id');
-}
 // ─── Table Client ─────────────────────────────────────────────────────────────
 class SheetsTableClient {
     constructor(adapter, modelName, sheetMapping) {
@@ -156,7 +151,7 @@ class SheetsTableClient {
         return rows.length;
     }
     assignId(data, fields) {
-        const idFieldName = resolveIdField(fields);
+        const idFieldName = (0, metadata_1.resolveIdField)(fields);
         if (!idFieldName)
             return;
         const fieldDef = fields[idFieldName];
@@ -201,23 +196,10 @@ class SheetsTableClient {
             }
             return this.rowToValues(data, headers);
         });
-        try {
-            await this.adapter.appendRange(`${this.escSheetName}!A:A`, batchValues);
-            return { count: batchValues.length };
-        }
-        catch (e) {
-            if (!args.skipDuplicates)
-                throw e;
-            let count = 0;
-            for (const row of args.data) {
-                try {
-                    await this.create({ data: row });
-                    count++;
-                }
-                catch { /* skip */ }
-            }
-            return { count };
-        }
+        // Sheets has no unique constraints. An append failure must propagate;
+        // retrying individual rows could duplicate a batch the service accepted.
+        await this.adapter.appendRange(`${this.escSheetName}!A:A`, batchValues);
+        return { count: batchValues.length };
     }
     async update(args) {
         const { headers, rows } = await this.readAllRows();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@an5/adapters",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "Standalone language adapters for AN5 ORM - TypeScript, Python, .NET, Go, Rust, and Google Sheets query execution.",
   "license": "MIT",
   "main": "dist/index.js",
@@ -58,7 +58,7 @@
     "pretest": "npm run build",
     "prepack": "npm run build",
     "build:python": "(python -m build --outdir dist-py || python3 -m build --outdir dist-py)",
-    "test": "node test/unit.test.js && node test/package.test.js && node test/nbase.test.js && node --test test/version-sync.test.js && node --test test/query-semantics.test.js && node test/query-relations.integration.test.js",
+    "test": "node test/unit.test.js && node test/package.test.js && node test/nbase.test.js && node --test test/version-sync.test.js && node --test test/query-semantics.test.js && node test/query-relations.integration.test.js && node --test test/sheets-oauth.test.js",
     "test:package:smoke": "node scripts/package-smoke.js",
     "test:integration:live": "node test/live-db.integration.test.js && node test/query-relations.integration.test.js",
     "test:python": "node scripts/python-tests.js",
@@ -75,17 +75,22 @@
     "@types/mssql": "^9.1.8",
     "@types/node": "^20.11.0",
     "@types/pg": "^8.11.0",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "better-sqlite3": "^11.5.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
-    "mysql2": "^3.0.0"
+    "mysql2": "^3.0.0",
+    "better-sqlite3": "^11.0.0"
   },
   "peerDependenciesMeta": {
     "mysql2": {
       "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
     }
   }
 }

package/typescript/src/an5Adapter.ts

@@ -26,10 +26,11 @@ import {
   type NBaseAdapterConfig,
   type NBaseVectorClient,
 } from './nbase';
-import { buildOrderBy, parseWhere, quote } from './base/sql';
+import { bindParam, buildOrderBy, parseWhere, quote } from './base/sql';
 import {
   createAdapterProxy,
   getFieldsForModel,
+  resolveIdField,
   getModelToTable,
   getRelationMap,
   getRelationsForModel,
@@ -51,39 +52,56 @@ function sanitizeParamName(name: string): string {
   return /^[A-Za-z]/.test(cleaned) ? cleaned : `p_${cleaned}`;
 }
 
+/** Match only unique/primary-key violations, never general constraint errors. */
+function isDuplicateKeyError(error: unknown, dialect: Dialect): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const e = error as any;
+  if (dialect === 'postgres') return e.code === '23505';
+  if (dialect === 'mysql') return e.code === 'ER_DUP_ENTRY' || e.errno === 1062;
+  if (dialect === 'sqlite') {
+    return e.code === 'SQLITE_CONSTRAINT_UNIQUE' || e.code === 'SQLITE_CONSTRAINT_PRIMARYKEY'
+      || e.errcode === 2067 || e.errcode === 1555;
+  }
+  if (dialect === 'mssql') {
+    const number = e.number ?? e.originalError?.info?.number;
+    return number === 2601 || number === 2627;
+  }
+  return false;
+}
+
 function appendUpdateSet(sets: string[], params: Record<string, any>, col: string, val: any, dialect: Dialect): void {
   const quoted = quote(col, dialect);
   const safeCol = sanitizeParamName(col);
   if (val && typeof val === 'object' && !(val instanceof Date)) {
     if (val.increment !== undefined) {
-      sets.push(`${quoted} = ${quoted} + @s_${safeCol}_inc`);
-      params[`s_${safeCol}_inc`] = val.increment;
+      const p = bindParam(params, `s_${safeCol}_inc`, val.increment);
+      sets.push(`${quoted} = ${quoted} + @${p}`);
       return;
     }
     if (val.decrement !== undefined) {
-      sets.push(`${quoted} = ${quoted} - @s_${safeCol}_dec`);
-      params[`s_${safeCol}_dec`] = val.decrement;
+      const p = bindParam(params, `s_${safeCol}_dec`, val.decrement);
+      sets.push(`${quoted} = ${quoted} - @${p}`);
       return;
     }
     if (val.multiply !== undefined) {
-      sets.push(`${quoted} = ${quoted} * @s_${safeCol}_mul`);
-      params[`s_${safeCol}_mul`] = val.multiply;
+      const p = bindParam(params, `s_${safeCol}_mul`, val.multiply);
+      sets.push(`${quoted} = ${quoted} * @${p}`);
       return;
     }
     if (val.divide !== undefined) {
-      sets.push(`${quoted} = ${quoted} / @s_${safeCol}_div`);
-      params[`s_${safeCol}_div`] = val.divide;
+      const p = bindParam(params, `s_${safeCol}_div`, val.divide);
+      sets.push(`${quoted} = ${quoted} / @${p}`);
       return;
     }
     if (val.set !== undefined) {
-      sets.push(`${quoted} = @s_${safeCol}_set`);
-      params[`s_${safeCol}_set`] = val.set;
+      const p = bindParam(params, `s_${safeCol}_set`, val.set);
+      sets.push(`${quoted} = @${p}`);
       return;
     }
   }
 
-  sets.push(`${quoted} = @s_${safeCol}`);
-  params[`s_${safeCol}`] = val;
+  const p = bindParam(params, `s_${safeCol}`, val);
+  sets.push(`${quoted} = @${p}`);
 }
 
 function selectedAggregateFields(fields: any): string[] {
@@ -789,7 +807,8 @@ export class AdapterTableClient<T = any> {
         query = `SELECT ${cols} FROM ${this.tableName}`;
         if (whereSql) query += ` WHERE ${whereSql}`;
         if (orderSql) query += ` ${orderSql}`;
-        query += ` LIMIT ${take ?? 'ALL'} OFFSET ${skip}`;
+        const limit = take ?? (this.dialect === 'sqlite' ? '-1' : this.dialect === 'mysql' ? '18446744073709551615' : 'ALL');
+        query += ` LIMIT ${limit} OFFSET ${skip}`;
       } else {
         // mssql requires ORDER BY before OFFSET/FETCH
         query = `SELECT ${cols} FROM ${this.tableName}${this.nolock}`;
@@ -854,9 +873,7 @@ export class AdapterTableClient<T = any> {
     }
 
     const fields = getFieldsForModel(this.modelName);
-    const idFieldName = Object.prototype.hasOwnProperty.call(fields, 'id')
-      ? 'id'
-      : Object.keys(fields).find((name) => name.endsWith('_id') || name.endsWith('Id') || name.toLowerCase() === 'id');
+    const idFieldName = resolveIdField(fields);
 
     const data: any = { ...rawData };
     if (idFieldName) {
@@ -918,8 +935,20 @@ export class AdapterTableClient<T = any> {
     if (firstRow === undefined) return { count: 0 };
     const firstCols = Object.keys(firstRow).filter(k => (firstRow as any)[k] !== undefined);
 
-    // Bulk INSERT for the common case (same columns, no skipDuplicates)
-    if (firstCols.length > 0 && !args.skipDuplicates) {
+    const sameColumns = args.data.every(row => {
+      const cols = Object.keys(row).filter(k => (row as any)[k] !== undefined);
+      return cols.length === firstCols.length && firstCols.every(col => cols.includes(col));
+    });
+
+    const fields = getFieldsForModel(this.modelName);
+    const idFieldName = resolveIdField(fields);
+    const idDef = idFieldName ? fields[idFieldName] : undefined;
+    const idType = typeof idDef === 'string' ? idDef : (idDef?.ts || idDef?.sql || idDef?.type || '');
+    const generatesId = ['string', 'uuid', 'uniqueidentifier', 'nvarchar', 'varchar', 'text'].includes(String(idType).toLowerCase());
+    const needsGeneratedId = idFieldName && generatesId && args.data.some(row => !(row as any)[idFieldName]);
+
+    // Rows needing generated IDs follow create's default handling.
+    if (firstCols.length > 0 && sameColumns && !needsGeneratedId && !args.skipDuplicates) {
       const params: Record<string, any> = {};
       const rowPlaceholders: string[] = [];
 
@@ -934,19 +963,15 @@ export class AdapterTableClient<T = any> {
       }
 
       const query = `INSERT INTO ${this.tableName} (${firstCols.map(c => quote(c, this.dialect)).join(', ')}) VALUES ${rowPlaceholders.join(', ')}`;
-      try {
-        await this.doExecuteRaw(query, params);
-        return { count: args.data.length };
-      } catch {
-        // fallback below if bulk fails (e.g. mixed column sets)
-      }
+      await this.doExecuteRaw(query, params);
+      return { count: args.data.length };
     }
 
     // Row-by-row fallback
     let count = 0;
     for (const row of args.data) {
       try { await this.create({ data: row }); count++; }
-      catch (e) { if (!args.skipDuplicates) throw e; }
+      catch (e) { if (!args.skipDuplicates || !isDuplicateKeyError(e, this.dialect)) throw e; }
     }
     return { count };
   }
@@ -1132,7 +1157,7 @@ export class AdapterTableClient<T = any> {
 
   async groupBy(args: any): Promise<any[]> {
     const params: Record<string, any> = {};
-    const whereSql = parseWhere(this.modelName, args?.where, params, this.dialect);
+    const whereSql = parseWhere(this.modelName, args?.where, params, this.dialect, '', this.whereContext());
     const byFields = normalizeByFields(args?.by);
     if (byFields.length === 0) throw new Error("groupBy requires 'by' fields");
     const byCols = byFields.map((b: string) => quote(b, this.dialect)).join(', ');
@@ -1151,8 +1176,8 @@ export class AdapterTableClient<T = any> {
       const skip = toNonNegativeInt(args?.skip);
       const take = toNonNegativeInt(args?.take, 1);
       if (this.dialect === 'postgres' || this.dialect === 'mysql' || this.dialect === 'sqlite') {
-        if (hasTake) query += ` LIMIT ${take}`;
-        query += ` OFFSET ${skip}`;
+        const limit = hasTake ? take : (this.dialect === 'sqlite' ? '-1' : this.dialect === 'mysql' ? '18446744073709551615' : 'ALL');
+        query += ` LIMIT ${limit} OFFSET ${skip}`;
       } else {
         query += ` OFFSET ${skip} ROWS`;
         if (hasTake) query += ` FETCH NEXT ${take} ROWS ONLY`;

package/typescript/src/base/metadata.ts

@@ -13,6 +13,14 @@ export interface ModelFieldMeta {
   [key: string]: any;
 }
 
+/** Prefer schema primary-key metadata; retain name inference for legacy clients. */
+export function resolveIdField(fields: Record<string, any>): string | undefined {
+  const primaryKey = Object.keys(fields).find(name => fields[name]?.isId === true);
+  if (primaryKey) return primaryKey;
+  if (Object.prototype.hasOwnProperty.call(fields, 'id')) return 'id';
+  return Object.keys(fields).find(name => name.endsWith('_id') || name.endsWith('Id') || name.toLowerCase() === 'id');
+}
+
 export interface AdapterMetadata {
   modelToTable?: Record<string, string>;
   modelFields?: Record<string, any>;

package/typescript/src/base/sql.ts

@@ -39,6 +39,15 @@ function sanitizeParamName(name: string): string {
   return /^[A-Za-z]/.test(cleaned) ? cleaned : `p_${cleaned}`;
 }
 
+/** Allocate parameters without overwriting values from sibling clauses. */
+export function bindParam(params: Record<string, any>, name: string, value: any): string {
+  let candidate = name;
+  let suffix = 1;
+  while (Object.prototype.hasOwnProperty.call(params, candidate)) candidate = `${name}_${suffix++}`;
+  params[candidate] = value;
+  return candidate;
+}
+
 function normalizeSortDirection(dir: unknown): 'ASC' | 'DESC' {
   return typeof dir === 'string' && dir.toUpperCase() === 'DESC' ? 'DESC' : 'ASC';
 }
@@ -132,26 +141,24 @@ export function parseWhere(
         if (v.not !== undefined) {
           if (v.not === null) { conditions.push(`${col} IS NOT NULL`); }
           else if (v.not && typeof v.not === 'object' && !(v.not instanceof Date) && !Array.isArray(v.not)) {
-            const nestedParams: Record<string, any> = {};
-            const nestedSql = parseWhere(modelName, { [key]: v.not }, nestedParams, dialect, `${prefix}${key}_not_`, ctx);
-            Object.assign(params, nestedParams);
+            const nestedSql = parseWhere(modelName, { [key]: v.not }, params, dialect, `${prefix}${key}_not_`, ctx);
             if (nestedSql) conditions.push(`NOT (${nestedSql})`);
-          } else { const p = `${pname}_not`; params[p] = v.not; conditions.push(`${col} <> @${p}`); }
+          } else { const p = bindParam(params, `${pname}_not`, v.not); conditions.push(`${col} <> @${p}`); }
         }
         if (v.equals !== undefined) {
           if (v.equals === null) { conditions.push(`${col} IS NULL`); }
-          else { const p = `${pname}_eq`; params[p] = v.equals; conditions.push(`${col} = @${p}`); }
+          else { const p = bindParam(params, `${pname}_eq`, v.equals); conditions.push(`${col} = @${p}`); }
         }
-        if (v.contains !== undefined) { const p = `${pname}_co`; params[p] = `%${v.contains}%`; conditions.push(`${col} LIKE @${p}`); }
-        if (v.startsWith !== undefined) { const p = `${pname}_sw`; params[p] = `${v.startsWith}%`; conditions.push(`${col} LIKE @${p}`); }
-        if (v.endsWith !== undefined) { const p = `${pname}_ew`; params[p] = `%${v.endsWith}`; conditions.push(`${col} LIKE @${p}`); }
-        if (v.gte !== undefined) { const p = `${pname}_gte`; params[p] = v.gte; conditions.push(`${col} >= @${p}`); }
-        if (v.lte !== undefined) { const p = `${pname}_lte`; params[p] = v.lte; conditions.push(`${col} <= @${p}`); }
-        if (v.gt !== undefined) { const p = `${pname}_gt`; params[p] = v.gt; conditions.push(`${col} > @${p}`); }
-        if (v.lt !== undefined) { const p = `${pname}_lt`; params[p] = v.lt; conditions.push(`${col} < @${p}`); }
+        if (v.contains !== undefined) { const p = bindParam(params, `${pname}_co`, `%${v.contains}%`); conditions.push(`${col} LIKE @${p}`); }
+        if (v.startsWith !== undefined) { const p = bindParam(params, `${pname}_sw`, `${v.startsWith}%`); conditions.push(`${col} LIKE @${p}`); }
+        if (v.endsWith !== undefined) { const p = bindParam(params, `${pname}_ew`, `%${v.endsWith}`); conditions.push(`${col} LIKE @${p}`); }
+        if (v.gte !== undefined) { const p = bindParam(params, `${pname}_gte`, v.gte); conditions.push(`${col} >= @${p}`); }
+        if (v.lte !== undefined) { const p = bindParam(params, `${pname}_lte`, v.lte); conditions.push(`${col} <= @${p}`); }
+        if (v.gt !== undefined) { const p = bindParam(params, `${pname}_gt`, v.gt); conditions.push(`${col} > @${p}`); }
+        if (v.lt !== undefined) { const p = bindParam(params, `${pname}_lt`, v.lt); conditions.push(`${col} < @${p}`); }
         if (v.in !== undefined) {
           if (Array.isArray(v.in) && v.in.length > 0) {
-            const ps = v.in.map((x: any, i: number) => { const p = `${pname}_in${i}`; params[p] = x; return `@${p}`; });
+            const ps = v.in.map((x: any, i: number) => { const p = bindParam(params, `${pname}_in${i}`, x); return `@${p}`; });
             conditions.push(`${col} IN (${ps.join(', ')})`);
           } else {
             conditions.push('1=0');
@@ -159,15 +166,15 @@ export function parseWhere(
         }
         if (v.notIn !== undefined) {
           if (Array.isArray(v.notIn) && v.notIn.length > 0) {
-            const ps = v.notIn.map((x: any, i: number) => { const p = `${pname}_notin${i}`; params[p] = x; return `@${p}`; });
+            const ps = v.notIn.map((x: any, i: number) => { const p = bindParam(params, `${pname}_notin${i}`, x); return `@${p}`; });
             conditions.push(`${col} NOT IN (${ps.join(', ')})`);
           } else {
             conditions.push('1=1');
           }
         }
       } else {
-        params[pname] = value;
-        conditions.push(`${col} = @${pname}`);
+        const p = bindParam(params, pname, value);
+        conditions.push(`${col} = @${p}`);
       }
     }
   }

package/typescript/src/googlesheets/adapter.ts

@@ -1,4 +1,5 @@
 import { An5SheetsAdapterConfig, resolveConfig } from './config';
+import { sheetsTokenProvider } from './oauth';
 import type { sheets_v4 } from 'googleapis';
 import { execQuery } from './sqlExecutor';
 import { SheetsTableClient } from './tableClient';
@@ -8,12 +9,10 @@ import { createAdapterProxy } from '../base/metadata';
 
 // ─── Fetch-based API proxy for OAuth Access Token / API Key (browser-compatible) ──
 
-function createFetchApi(spreadsheetId: string, accessToken?: string, apiKey?: string) {
+function createFetchApi(spreadsheetId: string, accessToken?: string, apiKey?: string, oauth: An5SheetsAdapterConfig = { spreadsheetId }) {
   const base = `https://sheets.googleapis.com/v4/spreadsheets/${spreadsheetId}`;
   const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-  if (accessToken) {
-    headers['Authorization'] = `Bearer ${accessToken}`;
-  }
+  const tokenProvider = sheetsTokenProvider({ ...oauth, ...(accessToken ? { accessToken } : {}) });
 
   async function request<T>(method: string, path: string, body?: any): Promise<T> {
     let url = path.startsWith('http') ? path : `${base}${path}`;
@@ -21,9 +20,14 @@ function createFetchApi(spreadsheetId: string, accessToken?: string, apiKey?: st
       const sep = url.includes('?') ? '&' : '?';
       url += `${sep}key=${encodeURIComponent(apiKey)}`;
     }
-    const opts: RequestInit = { method, headers };
+    const token = await tokenProvider();
+    const opts: RequestInit = { method, headers: { ...headers, ...(token ? { Authorization: `Bearer ${token}` } : {}) } };
     if (body) opts.body = JSON.stringify(body);
-    const res = await fetch(url, opts);
+    let res = await fetch(url, opts);
+    if (res.status === 401 && oauth.refreshToken) {
+      const refreshed = await tokenProvider(true);
+      res = await fetch(url, { ...opts, headers: { ...headers, Authorization: `Bearer ${refreshed}` } });
+    }
     if (!res.ok) {
       const text = await res.text().catch(() => '');
       const err = new Error(`Google Sheets API error (${res.status}): ${text}`);
@@ -85,13 +89,17 @@ export class An5SheetsAdapter {
   private sheetsCache: Promise<SheetMeta[]> | null = null;
 
   constructor(config: An5SheetsAdapterConfig) {
+    const browser = typeof window !== 'undefined' || (typeof self !== 'undefined' && typeof process === 'undefined');
+    if (browser && (config.refreshToken || config.oauthClientSecret || config.privateKey || config.credentials)) {
+      throw new Error('Browser Google Sheets connections require a user access token. Keep desktop OAuth refresh tokens and service account keys outside the browser.');
+    }
     this.config = resolveConfig(config);
     // Dynamic model access (`db.user` / `db.User`), same as An5Adapter.
     return createAdapterProxy(this, (name) => this.table(name));
   }
 
   private get isFetchMode(): boolean {
-    return !!(this.config as any).accessToken || !!(this.config as any).apiKey;
+    return !!(this.config as any).accessToken || !!(this.config as any).refreshToken || !!(this.config as any).apiKey;
   }
 
   async getSheets(): Promise<any> {
@@ -100,7 +108,8 @@ export class An5SheetsAdapter {
         this.fetchApi = createFetchApi(
           this.config.spreadsheetId,
           (this.config as any).accessToken,
-          (this.config as any).apiKey
+          (this.config as any).apiKey,
+          this.config as An5SheetsAdapterConfig
         );
       }
       return this.fetchApi;

package/typescript/src/googlesheets/config.ts

@@ -10,6 +10,11 @@ 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;
+  /** Offline desktop OAuth credentials. Keep these in secure storage, never source control. */
+  refreshToken?: string;
+  oauthClientId?: string;
+  oauthClientSecret?: string;
+  tokenExpiresAt?: number;
   /** Google API key for browser-based API access. */
   apiKey?: string;
 }
@@ -22,10 +27,14 @@ export function normalizeKey(key: string): string {
 }
 
 export function resolveConfig(config: An5SheetsAdapterConfig) {
-  if (config.accessToken || config.apiKey) {
+  if (config.accessToken || config.refreshToken || config.apiKey) {
     return {
       spreadsheetId: config.spreadsheetId,
       accessToken: config.accessToken,
+      refreshToken: config.refreshToken,
+      oauthClientId: config.oauthClientId,
+      oauthClientSecret: config.oauthClientSecret,
+      tokenExpiresAt: config.tokenExpiresAt,
       apiKey: config.apiKey,
       sheetMapping: config.sheetMapping,
     };

package/typescript/src/googlesheets/oauth.ts

@@ -0,0 +1,31 @@
+import type { An5SheetsAdapterConfig } from './config';
+
+/** Deduplicate refresh requests within an adapter; do not expose token responses. */
+export function sheetsTokenProvider(config: An5SheetsAdapterConfig) {
+  let token = config.accessToken;
+  let expiresAt = config.tokenExpiresAt;
+  let pending: Promise<string> | undefined;
+  return async (force = false): Promise<string | undefined> => {
+    if (token && !force && (expiresAt === undefined || expiresAt > Date.now() + 60000)) return token;
+    if (!config.refreshToken || !config.oauthClientId) {
+      if (force || expiresAt !== undefined) throw new Error('Google access expired. Reconnect your Google account.');
+      return token;
+    }
+    if (!pending) pending = (async () => {
+      try {
+        const response = await fetch('https://oauth2.googleapis.com/token', {
+          method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: new URLSearchParams({ grant_type: 'refresh_token', client_id: config.oauthClientId!, refresh_token: config.refreshToken!, ...(config.oauthClientSecret ? { client_secret: config.oauthClientSecret } : {}) }),
+          signal: AbortSignal.timeout(20000),
+        });
+        if (!response.ok) throw new Error();
+        const result = await response.json() as { access_token?: string; expires_in?: number };
+        if (!result.access_token || typeof result.access_token !== 'string' || typeof result.expires_in !== 'number' || !Number.isFinite(result.expires_in) || result.expires_in <= 0) throw new Error();
+        token = result.access_token; expiresAt = Date.now() + result.expires_in * 1000;
+        return token;
+      } catch { throw new Error('Google access expired or was revoked. Reconnect your Google account.'); }
+      finally { pending = undefined; }
+    })();
+    return pending;
+  };
+}

package/typescript/src/googlesheets/parseConnectionString.ts

@@ -33,6 +33,14 @@ export function parseSheetsConnectionString(url: string): An5SheetsAdapterConfig
   if (config.clientemail) result.clientEmail = config.clientemail;
   if (config.privatekey) result.privateKey = config.privatekey;
   if (config.accesstoken) result.accessToken = config.accesstoken;
+  if (config.refreshtoken) result.refreshToken = config.refreshtoken;
+  if (config.oauthclientid) result.oauthClientId = config.oauthclientid;
+  if (config.oauthclientsecret) result.oauthClientSecret = config.oauthclientsecret;
+  if (config.tokenexpiresat) {
+    const expiry = Number(config.tokenexpiresat);
+    if (!Number.isFinite(expiry) || expiry < 0) throw new Error('Invalid OAuth token expiry.');
+    result.tokenExpiresAt = expiry;
+  }
   if (config.apikey) result.apiKey = config.apikey;
 
   if (config.sheetmapping) {

package/typescript/src/googlesheets/tableClient.ts

@@ -1,18 +1,11 @@
 import { generateUUID } from '../base/uuid';
-import { getFieldsForModel } from '../base/metadata';
+import { getFieldsForModel, resolveIdField } from '../base/metadata';
 import type { An5SheetsAdapter } from './adapter';
 import { buildOrderBy, coerceCell, esc, matchWhere, resolveSheetName, sortRows } from './helpers';
 import { withRetry } from './retry';
 
 // ─── Utility ──────────────────────────────────────────────────────────────────
 
-function resolveIdField(fields: Record<string, any>): string | undefined {
-  if (Object.prototype.hasOwnProperty.call(fields, 'id')) return 'id';
-  return Object.keys(fields).find(
-    name => name.endsWith('_id') || name.endsWith('Id') || name.toLowerCase() === 'id'
-  );
-}
-
 // ─── Table Client ─────────────────────────────────────────────────────────────
 
 export class SheetsTableClient<T = any> {
@@ -227,17 +220,10 @@ export class SheetsTableClient<T = any> {
       return this.rowToValues(data, headers);
     });
 
-    try {
-      await this.adapter.appendRange(`${this.escSheetName}!A:A`, batchValues);
-      return { count: batchValues.length };
-    } catch (e) {
-      if (!args.skipDuplicates) throw e;
-      let count = 0;
-      for (const row of args.data) {
-        try { await this.create({ data: row }); count++; } catch { /* skip */ }
-      }
-      return { count };
-    }
+    // Sheets has no unique constraints. An append failure must propagate;
+    // retrying individual rows could duplicate a batch the service accepted.
+    await this.adapter.appendRange(`${this.escSheetName}!A:A`, batchValues);
+    return { count: batchValues.length };
   }
 
   async update(args: { where: any; data: Partial<T> }): Promise<T> {