@an5/adapters 0.2.9 → 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')
@@ -275,7 +294,8 @@ class An5Adapter {
         else if (forDialect.startsWith('mysql://') || forDialect.startsWith('mariadb://')) {
             this._engineType = 'mysql';
         }
-        else if (forDialect.startsWith('sqlite://')
+        else if (forDialect === ':memory:'
+            || forDialect.startsWith('sqlite:')
             || SQLITE_FILE_SUFFIXES.some((suffix) => forDialect.endsWith(suffix))) {
             this._engineType = 'sqlite';
         }
@@ -716,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
@@ -778,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];
@@ -835,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++) {
@@ -849,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;
@@ -865,7 +889,7 @@ class AdapterTableClient {
                 count++;
             }
             catch (e) {
-                if (!args.skipDuplicates)
+                if (!args.skipDuplicates || !isDuplicateKeyError(e, this.dialect))
                     throw e;
             }
         }
@@ -1045,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");
@@ -1075,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';
 }
@@ -68,9 +78,10 @@ function parseWhere(modelName, where, params, dialect, prefix = '', ctx) {
     if (!where)
         return '';
     const conditions = [];
+    const relations = ctx?.relationMap?.[modelName] || {};
     const cleanWhere = {};
     for (const [key, value] of Object.entries(where)) {
-        if (key.includes('_') &&
+        if (key.includes('_') && !relations[key] &&
             value && typeof value === 'object' &&
             !(value instanceof Date) &&
             !isOperatorValue(value)) {
@@ -80,13 +91,13 @@ function parseWhere(modelName, where, params, dialect, prefix = '', ctx) {
             cleanWhere[key] = value;
         }
     }
-    const relations = ctx?.relationMap?.[modelName] || {};
     const colPrefix = ctx?.colPrefix || '';
     for (const [key, value] of Object.entries(cleanWhere)) {
+        if (value === undefined)
+            continue;
         if (key === 'OR' && Array.isArray(value)) {
-            const sub = value.map((v, i) => parseWhere(modelName, v, params, dialect, `${prefix}or_${i}_`, ctx)).filter(Boolean);
-            if (sub.length > 0)
-                conditions.push(`(${sub.join(' OR ')})`);
+            const sub = value.map((v, i) => parseWhere(modelName, v, params, dialect, `${prefix}or_${i}_`, ctx) || '1=1');
+            conditions.push(sub.length > 0 ? `(${sub.join(' OR ')})` : '1=0');
         }
         else if (key === 'AND') {
             const items = Array.isArray(value) ? value : [value];
@@ -96,12 +107,12 @@ function parseWhere(modelName, where, params, dialect, prefix = '', ctx) {
         }
         else if (key === 'NOT') {
             const items = Array.isArray(value) ? value : [value];
-            const sub = items.map((v, i) => parseWhere(modelName, v, params, dialect, `${prefix}not_${i}_`, ctx)).filter(Boolean);
+            const sub = items.map((v, i) => parseWhere(modelName, v, params, dialect, `${prefix}not_${i}_`, ctx) || '1=1');
             if (sub.length > 0)
-                conditions.push(`NOT (${sub.join(' AND ')})`);
+                conditions.push(`NOT (${sub.join(' OR ')})`);
         }
         else if (relations[key] && value && typeof value === 'object') {
-            const clause = buildRelationClause(relations[key], value, modelName, params, dialect, prefix, ctx);
+            const clause = buildRelationClause(relations[key], value, modelName, params, dialect, `${prefix}${key}_`, ctx);
             if (clause)
                 conditions.push(clause);
         }
@@ -118,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}`);
                     }
                 }
@@ -135,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 {
@@ -186,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 {
@@ -195,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}`);
             }
         }
     }
@@ -220,16 +220,16 @@ function buildRelationClause(relation, value, modelName, params, dialect, prefix
     const parts = [];
     if (isMany) {
         if (value.some !== undefined) {
-            const inner = buildInnerWhere(relation.modelName, value.some === null ? {} : value.some, params, dialect, prefix, ctx, childAlias);
+            const inner = buildInnerWhere(relation.modelName, value.some === null ? {} : value.some, params, dialect, `${prefix}some_`, ctx, childAlias);
             parts.push(buildExists(inner));
         }
         if (value.none !== undefined) {
-            const inner = buildInnerWhere(relation.modelName, value.none === null ? {} : value.none, params, dialect, prefix, ctx, childAlias);
+            const inner = buildInnerWhere(relation.modelName, value.none === null ? {} : value.none, params, dialect, `${prefix}none_`, ctx, childAlias);
             parts.push(`NOT ${buildExists(inner)}`);
         }
         if (value.every !== undefined) {
             // "every" = no related row violates the condition.
-            const inner = buildInnerWhere(relation.modelName, value.every === null ? {} : value.every, params, dialect, prefix, ctx, childAlias);
+            const inner = buildInnerWhere(relation.modelName, value.every === null ? {} : value.every, params, dialect, `${prefix}every_`, ctx, childAlias);
             const negated = inner ? `NOT (${inner})` : '';
             const violated = `EXISTS (SELECT 1 FROM ${childTable} AS ${childAlias} WHERE ${correlation}${negated ? ` AND ${negated}` : ' AND 1=0'})`;
             parts.push(`NOT ${violated}`);
@@ -237,12 +237,12 @@ function buildRelationClause(relation, value, modelName, params, dialect, prefix
     }
     else {
         if (value.is !== undefined) {
-            const inner = buildInnerWhere(relation.modelName, value.is === null ? {} : value.is, params, dialect, prefix, ctx, childAlias);
-            parts.push(buildExists(inner));
+            const inner = buildInnerWhere(relation.modelName, value.is === null ? {} : value.is, params, dialect, `${prefix}is_`, ctx, childAlias);
+            parts.push(value.is === null ? `NOT ${buildExists(inner)}` : buildExists(inner));
         }
         if (value.isNot !== undefined) {
-            const inner = buildInnerWhere(relation.modelName, value.isNot === null ? {} : value.isNot, params, dialect, prefix, ctx, childAlias);
-            parts.push(`NOT ${buildExists(inner)}`);
+            const inner = buildInnerWhere(relation.modelName, value.isNot === null ? {} : value.isNot, params, dialect, `${prefix}isNot_`, ctx, childAlias);
+            parts.push(value.isNot === null ? buildExists(inner) : `NOT ${buildExists(inner)}`);
         }
     }
     return parts.length > 0 ? parts.join(' AND ') : null;

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/helpers.js

@@ -25,9 +25,7 @@ function matchWhere(row, 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) {
+            !['equals', 'in', 'notIn', 'contains', 'startsWith', 'endsWith', 'not', 'gte', 'lte', 'gt', 'lt'].some(op => op in value)) {
             Object.assign(cleanWhere, value);
         }
         else {
@@ -35,13 +33,16 @@ function matchWhere(row, where) {
         }
     }
     for (const [key, value] of Object.entries(cleanWhere)) {
+        if (value === undefined)
+            continue;
         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)))
+        if (key === 'AND') {
+            const clauses = Array.isArray(value) ? value : [value];
+            if (!clauses.every((v) => matchWhere(row, v)))
                 return false;
             continue;
         }
@@ -65,21 +66,25 @@ function matchWhere(row, where) {
                     if (cellVal === null || cellVal === undefined)
                         return false;
                 }
+                else if (v.not && typeof v.not === 'object' && !(v.not instanceof Date) && !Array.isArray(v.not)) {
+                    if (matchWhere(row, { [key]: v.not }))
+                        return false;
+                }
                 else if (normalize(cellVal) == normalize(v.not))
                     return false;
             }
             if (v.equals !== undefined && normalize(cellVal) != normalize(v.equals))
                 return false;
             if (v.contains !== undefined) {
-                if (!cellVal || !normalize(String(cellVal)).includes(normalize(v.contains)))
+                if (cellVal === null || cellVal === undefined || !normalize(String(cellVal)).includes(normalize(v.contains)))
                     return false;
             }
             if (v.startsWith !== undefined) {
-                if (!cellVal || !normalize(String(cellVal)).startsWith(normalize(v.startsWith)))
+                if (cellVal === null || cellVal === undefined || !normalize(String(cellVal)).startsWith(normalize(v.startsWith)))
                     return false;
             }
             if (v.endsWith !== undefined) {
-                if (!cellVal || !normalize(String(cellVal)).endsWith(normalize(v.endsWith)))
+                if (cellVal === null || cellVal === undefined || !normalize(String(cellVal)).endsWith(normalize(v.endsWith)))
                     return false;
             }
             if (v.gte !== undefined && !(Number(cellVal) >= Number(v.gte)))

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>;