@an5/adapters 0.2.9 → 0.2.11

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[] {
@@ -317,7 +335,8 @@ export class An5Adapter {
     } else if (forDialect.startsWith('mysql://') || forDialect.startsWith('mariadb://')) {
       this._engineType = 'mysql';
     } else if (
-      forDialect.startsWith('sqlite://')
+      forDialect === ':memory:'
+      || forDialect.startsWith('sqlite:')
       || SQLITE_FILE_SUFFIXES.some((suffix) => forDialect.endsWith(suffix))
     ) {
       this._engineType = 'sqlite';
@@ -788,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}`;
@@ -853,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) {
@@ -917,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[] = [];
 
@@ -933,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 };
   }
@@ -1131,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(', ');
@@ -1150,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';
 }
@@ -88,10 +97,11 @@ export function parseWhere(
   if (!where) return '';
   const conditions: string[] = [];
 
+  const relations = ctx?.relationMap?.[modelName] || {};
   const cleanWhere: Record<string, any> = {};
   for (const [key, value] of Object.entries(where)) {
     if (
-      key.includes('_') &&
+      key.includes('_') && !relations[key] &&
       value && typeof value === 'object' &&
       !(value instanceof Date) &&
       !isOperatorValue(value)
@@ -102,23 +112,23 @@ export function parseWhere(
     }
   }
 
-  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];
       const sub = items.map((v, i) => parseWhere(modelName, v, params, dialect, `${prefix}and_${i}_`, ctx)).filter(Boolean);
       if (sub.length > 0) conditions.push(`(${sub.join(' AND ')})`);
     } 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);
-      if (sub.length > 0) conditions.push(`NOT (${sub.join(' AND ')})`);
+      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(' 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);
     } else {
       const pname = sanitizeParamName(`${prefix}${key}`);
@@ -131,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');
@@ -158,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}`);
       }
     }
   }
@@ -203,28 +211,28 @@ function buildRelationClause(
 
   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}`);
     }
   } 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)}`);
     }
   }
 

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

@@ -21,9 +21,7 @@ export function matchWhere(row: Record<string, any>, where: any): boolean {
       key.includes('_') &&
       value && typeof value === 'object' &&
       !(value instanceof Date) &&
-      !(value as any).in && !(value as any).contains &&
-      !(value as any).not && !(value as any).gte &&
-      !(value as any).lte && !(value as any).gt && !(value as any).lt
+      !['equals', 'in', 'notIn', 'contains', 'startsWith', 'endsWith', 'not', 'gte', 'lte', 'gt', 'lt'].some(op => op in value)
     ) {
       Object.assign(cleanWhere, value);
     } else {
@@ -32,12 +30,14 @@ export function matchWhere(row: Record<string, any>, where: any): boolean {
   }
 
   for (const [key, value] of Object.entries(cleanWhere)) {
+    if (value === undefined) continue;
     if (key === 'OR' && Array.isArray(value)) {
       if (!value.some((v: any) => matchWhere(row, v))) return false;
       continue;
     }
-    if (key === 'AND' && Array.isArray(value)) {
-      if (!value.every((v: any) => matchWhere(row, v))) return false;
+    if (key === 'AND') {
+      const clauses = Array.isArray(value) ? value : [value];
+      if (!clauses.every((v: any) => matchWhere(row, v))) return false;
       continue;
     }
     if (key === 'NOT') {
@@ -57,17 +57,20 @@ export function matchWhere(row: Record<string, any>, where: any): boolean {
 
       if (v.not !== undefined) {
         if (v.not === null) { 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))) return false;
+        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))) return false;
+        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))) return false;
+        if (cellVal === null || cellVal === undefined || !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))) return false;

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

package/typescript/src/sqlite/engine.ts

@@ -14,7 +14,8 @@ export class SqliteEngine implements QueryEngine {
     if (!BetterSqlite3) throw new Error('better-sqlite3 package is required for SQLite support. Run: npm install better-sqlite3');
     this.filePath = (adapterConfig.connectionString ?? '')
       .replace(/^sqlite:\/\/\//i, '/')
-      .replace(/^sqlite:\/\//i, '');
+      .replace(/^sqlite:\/\//i, '')
+      .replace(/^sqlite:/i, '');
   }
 
   private getDb(): any {