@an5/adapters 0.1.0

package/typescript/base/sql.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.quote = quote;
+exports.parseWhere = parseWhere;
+exports.buildOrderBy = buildOrderBy;
+// ─── Quoting ───────────────────────────────────────────────────────────────────────
+function quote(name, dialect) {
+    if (dialect === 'postgres') {
+        if (name.startsWith('[') && name.endsWith(']'))
+            return `"${name.slice(1, -1)}"`;
+        if (name.startsWith('"'))
+            return name;
+        return `"${name}"`;
+    }
+    if (dialect === 'mysql') {
+        if (name.startsWith('[') && name.endsWith(']'))
+            return `\`${name.slice(1, -1)}\``;
+        if (name.startsWith('`'))
+            return name;
+        return `\`${name}\``;
+    }
+    // mssql / sqlite
+    return name.startsWith('[') ? name : `[${name}]`;
+}
+// ─── Where clause builder ──────────────────────────────────────────────────────────
+function parseWhere(modelName, where, params, dialect, prefix = '') {
+    if (!where)
+        return '';
+    const conditions = [];
+    const cleanWhere = {};
+    for (const [key, value] of Object.entries(where)) {
+        if (key.includes('_') &&
+            value && typeof value === 'object' &&
+            !(value instanceof Date) &&
+            !value.in && !value.contains &&
+            !value.not && !value.gte &&
+            !value.lte && !value.gt && !value.lt) {
+            Object.assign(cleanWhere, value);
+        }
+        else {
+            cleanWhere[key] = value;
+        }
+    }
+    for (const [key, value] of Object.entries(cleanWhere)) {
+        if (key === 'OR' && Array.isArray(value)) {
+            const sub = value.map((v, i) => parseWhere(modelName, v, params, dialect, `${prefix}or_${i}_`)).filter(Boolean);
+            if (sub.length > 0)
+                conditions.push(`(${sub.join(' OR ')})`);
+        }
+        else if (key === 'AND' && Array.isArray(value)) {
+            const sub = value.map((v, i) => parseWhere(modelName, v, params, dialect, `${prefix}and_${i}_`)).filter(Boolean);
+            if (sub.length > 0)
+                conditions.push(`(${sub.join(' AND ')})`);
+        }
+        else {
+            const pname = `${prefix}${key}`;
+            const col = quote(key, dialect);
+            if (value === null) {
+                conditions.push(`${col} IS NULL`);
+            }
+            else if (typeof value === 'object' && !(value instanceof Date)) {
+                const v = value;
+                if (v.not !== undefined) {
+                    if (v.not === null) {
+                        conditions.push(`${col} IS NOT NULL`);
+                    }
+                    else {
+                        const p = `${pname}_not`;
+                        params[p] = v.not;
+                        conditions.push(`${col} <> @${p}`);
+                    }
+                }
+                if (v.equals !== undefined) {
+                    const p = `${pname}_eq`;
+                    params[p] = 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.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}`; });
+                        conditions.push(`${col} IN (${ps.join(', ')})`);
+                    }
+                    else {
+                        conditions.push('1=0');
+                    }
+                }
+            }
+            else {
+                params[pname] = value;
+                conditions.push(`${col} = @${pname}`);
+            }
+        }
+    }
+    return conditions.join(' AND ');
+}
+// ─── Order by builder ──────────────────────────────────────────────────────────────
+function buildOrderBy(orderBy, dialect) {
+    if (!orderBy)
+        return '';
+    const entries = Array.isArray(orderBy) ? orderBy : [orderBy];
+    const parts = [];
+    for (const entry of entries) {
+        for (const [key, dir] of Object.entries(entry)) {
+            parts.push(`${quote(key, dialect)} ${dir.toUpperCase()}`);
+        }
+    }
+    return parts.length > 0 ? `ORDER BY ${parts.join(', ')}` : '';
+}

package/typescript/base/sql.ts

@@ -0,0 +1,98 @@
+import type { Dialect } from './types';
+
+// ─── Quoting ───────────────────────────────────────────────────────────────────────
+
+export function quote(name: string, dialect: Dialect): string {
+  if (dialect === 'postgres') {
+    if (name.startsWith('[') && name.endsWith(']')) return `"${name.slice(1, -1)}"`;
+    if (name.startsWith('"')) return name;
+    return `"${name}"`;
+  }
+  if (dialect === 'mysql') {
+    if (name.startsWith('[') && name.endsWith(']')) return `\`${name.slice(1, -1)}\``;
+    if (name.startsWith('`')) return name;
+    return `\`${name}\``;
+  }
+  // mssql / sqlite
+  return name.startsWith('[') ? name : `[${name}]`;
+}
+
+// ─── Where clause builder ──────────────────────────────────────────────────────────
+
+export function parseWhere(modelName: string, where: any, params: Record<string, any>, dialect: Dialect, prefix = ''): string {
+  if (!where) return '';
+  const conditions: string[] = [];
+
+  const cleanWhere: Record<string, any> = {};
+  for (const [key, value] of Object.entries(where)) {
+    if (
+      key.includes('_') &&
+      value && typeof value === 'object' &&
+      !(value instanceof Date) &&
+      !(value as any).in && !(value as any).contains &&
+      !(value as any).not && !(value as any).gte &&
+      !(value as any).lte && !(value as any).gt && !(value as any).lt
+    ) {
+      Object.assign(cleanWhere, value);
+    } else {
+      cleanWhere[key] = value;
+    }
+  }
+
+  for (const [key, value] of Object.entries(cleanWhere)) {
+    if (key === 'OR' && Array.isArray(value)) {
+      const sub = value.map((v, i) => parseWhere(modelName, v, params, dialect, `${prefix}or_${i}_`)).filter(Boolean);
+      if (sub.length > 0) conditions.push(`(${sub.join(' OR ')})`);
+    } else if (key === 'AND' && Array.isArray(value)) {
+      const sub = value.map((v, i) => parseWhere(modelName, v, params, dialect, `${prefix}and_${i}_`)).filter(Boolean);
+      if (sub.length > 0) conditions.push(`(${sub.join(' AND ')})`);
+    } else {
+      const pname = `${prefix}${key}`;
+      const col = quote(key, dialect);
+
+      if (value === null) {
+        conditions.push(`${col} IS NULL`);
+      } else if (typeof value === 'object' && !(value instanceof Date)) {
+        const v = value as any;
+        if (v.not !== undefined) {
+          if (v.not === null) { conditions.push(`${col} IS NOT NULL`); }
+          else { const p = `${pname}_not`; params[p] = v.not; conditions.push(`${col} <> @${p}`); }
+        }
+        if (v.equals !== undefined) { const p = `${pname}_eq`; params[p] = 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.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}`; });
+            conditions.push(`${col} IN (${ps.join(', ')})`);
+          } else {
+            conditions.push('1=0');
+          }
+        }
+      } else {
+        params[pname] = value;
+        conditions.push(`${col} = @${pname}`);
+      }
+    }
+  }
+  return conditions.join(' AND ');
+}
+
+// ─── Order by builder ──────────────────────────────────────────────────────────────
+
+export function buildOrderBy(orderBy: any, dialect: Dialect): string {
+  if (!orderBy) return '';
+  const entries = Array.isArray(orderBy) ? orderBy : [orderBy];
+  const parts: string[] = [];
+  for (const entry of entries) {
+    for (const [key, dir] of Object.entries(entry)) {
+      parts.push(`${quote(key, dialect)} ${(dir as string).toUpperCase()}`);
+    }
+  }
+  return parts.length > 0 ? `ORDER BY ${parts.join(', ')}` : '';
+}

package/typescript/base/types.d.ts

@@ -0,0 +1,21 @@
+export type Dialect = 'mssql' | 'postgres' | 'mysql' | 'sqlite' | 'googlesheets';
+export interface An5AdapterConfig {
+    connectionString: string;
+    poolMax?: number;
+    requestTimeout?: number;
+    connectionTimeout?: number;
+}
+export interface TransactionHandle {
+    exec<T>(query: string, params?: Record<string, any>): Promise<T[]>;
+    executeRaw(query: string, params?: Record<string, any>): Promise<number>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+}
+export interface QueryEngine {
+    dialect: Dialect;
+    exec<T>(query: string, params?: Record<string, any>): Promise<T[]>;
+    executeRaw(query: string, params?: Record<string, any>): Promise<number>;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    beginTransaction(): Promise<TransactionHandle>;
+}

package/typescript/base/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/typescript/base/types.ts

@@ -0,0 +1,24 @@
+export type Dialect = 'mssql' | 'postgres' | 'mysql' | 'sqlite' | 'googlesheets';
+
+export interface An5AdapterConfig {
+  connectionString: string;
+  poolMax?: number;
+  requestTimeout?: number;
+  connectionTimeout?: number;
+}
+
+export interface TransactionHandle {
+  exec<T>(query: string, params?: Record<string, any>): Promise<T[]>;
+  executeRaw(query: string, params?: Record<string, any>): Promise<number>;
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+}
+
+export interface QueryEngine {
+  dialect: Dialect;
+  exec<T>(query: string, params?: Record<string, any>): Promise<T[]>;
+  executeRaw(query: string, params?: Record<string, any>): Promise<number>;
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  beginTransaction(): Promise<TransactionHandle>;
+}

package/typescript/config.d.ts

@@ -0,0 +1,17 @@
+export interface LlmConfigData {
+    provider: string;
+    apiKey: string;
+    model?: string;
+    endpoint?: string;
+}
+export interface EmbeddingConfigData {
+    provider: string;
+    apiKey: string;
+    model?: string;
+    endpoint?: string;
+}
+export declare function resetAdapter(): void;
+export declare function getLlmConfig(): Promise<LlmConfigData | null>;
+export declare function setLlmConfig(data: LlmConfigData): Promise<void>;
+export declare function getEmbeddingConfig(): Promise<EmbeddingConfigData | null>;
+export declare function setEmbeddingConfig(data: EmbeddingConfigData): Promise<void>;

package/typescript/config.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetAdapter = resetAdapter;
+exports.getLlmConfig = getLlmConfig;
+exports.setLlmConfig = setLlmConfig;
+exports.getEmbeddingConfig = getEmbeddingConfig;
+exports.setEmbeddingConfig = setEmbeddingConfig;
+const an5Adapter_1 = require("./an5Adapter");
+let _adapter = null;
+function getAdapter() {
+    if (_adapter)
+        return _adapter;
+    const url = process.env.DATABASE_URL;
+    if (!url)
+        return null;
+    try {
+        _adapter = (0, an5Adapter_1.createAn5Adapter)({ connectionString: url });
+        return _adapter;
+    }
+    catch {
+        return null;
+    }
+}
+function resetAdapter() {
+    _adapter = null;
+}
+async function getLlmConfig() {
+    const adapter = getAdapter();
+    if (!adapter)
+        return null;
+    try {
+        const rows = await adapter.table('LlmConfig').findMany({
+            where: { isActive: true },
+        });
+        if (rows.length > 0) {
+            const c = rows[0];
+            return { provider: c.provider, apiKey: c.apiKey, model: c.model, endpoint: c.endpoint };
+        }
+    }
+    catch { }
+    return null;
+}
+async function setLlmConfig(data) {
+    const adapter = getAdapter();
+    if (!adapter)
+        throw new Error('DATABASE_URL not configured');
+    const existing = await adapter.table('LlmConfig').findFirst({ where: { isActive: true } });
+    if (existing) {
+        await adapter.table('LlmConfig').update({
+            where: { id: existing.id },
+            data: { ...data, updatedAt: new Date() },
+        });
+    }
+    else {
+        await adapter.table('LlmConfig').create({
+            data: { ...data, isActive: true, createdAt: new Date(), updatedAt: new Date() },
+        });
+    }
+}
+async function getEmbeddingConfig() {
+    const adapter = getAdapter();
+    if (!adapter)
+        return null;
+    try {
+        const rows = await adapter.table('EmbeddingConfig').findMany({
+            where: { isActive: true },
+        });
+        if (rows.length > 0) {
+            const c = rows[0];
+            return { provider: c.provider, apiKey: c.apiKey, model: c.model, endpoint: c.endpoint };
+        }
+    }
+    catch { }
+    return null;
+}
+async function setEmbeddingConfig(data) {
+    const adapter = getAdapter();
+    if (!adapter)
+        throw new Error('DATABASE_URL not configured');
+    const existing = await adapter.table('EmbeddingConfig').findFirst({ where: { isActive: true } });
+    if (existing) {
+        await adapter.table('EmbeddingConfig').update({
+            where: { id: existing.id },
+            data: { ...data, updatedAt: new Date() },
+        });
+    }
+    else {
+        await adapter.table('EmbeddingConfig').create({
+            data: { ...data, isActive: true, createdAt: new Date(), updatedAt: new Date() },
+        });
+    }
+}

package/typescript/config.ts

@@ -0,0 +1,95 @@
+import { createAn5Adapter, type AnyAdapter } from './an5Adapter';
+
+export interface LlmConfigData {
+  provider: string;
+  apiKey: string;
+  model?: string;
+  endpoint?: string;
+}
+
+export interface EmbeddingConfigData {
+  provider: string;
+  apiKey: string;
+  model?: string;
+  endpoint?: string;
+}
+
+let _adapter: AnyAdapter | null = null;
+
+function getAdapter(): AnyAdapter | null {
+  if (_adapter) return _adapter;
+  const url = process.env.DATABASE_URL;
+  if (!url) return null;
+  try {
+    _adapter = createAn5Adapter({ connectionString: url });
+    return _adapter;
+  } catch {
+    return null;
+  }
+}
+
+export function resetAdapter(): void {
+  _adapter = null;
+}
+
+export async function getLlmConfig(): Promise<LlmConfigData | null> {
+  const adapter = getAdapter();
+  if (!adapter) return null;
+  try {
+    const rows = await adapter.table<LlmConfigData>('LlmConfig').findMany({
+      where: { isActive: true },
+    });
+    if (rows.length > 0) {
+      const c = rows[0] as any;
+      return { provider: c.provider, apiKey: c.apiKey, model: c.model, endpoint: c.endpoint };
+    }
+  } catch {}
+  return null;
+}
+
+export async function setLlmConfig(data: LlmConfigData): Promise<void> {
+  const adapter = getAdapter();
+  if (!adapter) throw new Error('DATABASE_URL not configured');
+  const existing = await adapter.table('LlmConfig').findFirst({ where: { isActive: true } });
+  if (existing) {
+    await adapter.table('LlmConfig').update({
+      where: { id: (existing as any).id },
+      data: { ...data, updatedAt: new Date() },
+    });
+  } else {
+    await adapter.table('LlmConfig').create({
+      data: { ...data, isActive: true, createdAt: new Date(), updatedAt: new Date() },
+    });
+  }
+}
+
+export async function getEmbeddingConfig(): Promise<EmbeddingConfigData | null> {
+  const adapter = getAdapter();
+  if (!adapter) return null;
+  try {
+    const rows = await adapter.table<EmbeddingConfigData>('EmbeddingConfig').findMany({
+      where: { isActive: true },
+    });
+    if (rows.length > 0) {
+      const c = rows[0] as any;
+      return { provider: c.provider, apiKey: c.apiKey, model: c.model, endpoint: c.endpoint };
+    }
+  } catch {}
+  return null;
+}
+
+export async function setEmbeddingConfig(data: EmbeddingConfigData): Promise<void> {
+  const adapter = getAdapter();
+  if (!adapter) throw new Error('DATABASE_URL not configured');
+  const existing = await adapter.table('EmbeddingConfig').findFirst({ where: { isActive: true } });
+  if (existing) {
+    await adapter.table('EmbeddingConfig').update({
+      where: { id: (existing as any).id },
+      data: { ...data, updatedAt: new Date() },
+    });
+  } else {
+    await adapter.table('EmbeddingConfig').create({
+      data: { ...data, isActive: true, createdAt: new Date(), updatedAt: new Date() },
+    });
+  }
+}

package/typescript/googlesheets/adapter.d.ts

@@ -0,0 +1,31 @@
+import { sheets_v4 } from 'googleapis';
+import { An5SheetsAdapterConfig, resolveConfig } from './config';
+import { SheetsTableClient } from './tableClient';
+import { SheetMeta } from './types';
+export declare class An5SheetsAdapter {
+    private sheets;
+    config: ReturnType<typeof resolveConfig>;
+    private sheetsCache;
+    constructor(config: An5SheetsAdapterConfig);
+    getSheets(): Promise<sheets_v4.Sheets>;
+    private getApi;
+    invalidateCache(): void;
+    listSheets(): Promise<string[]>;
+    getSheetMeta(name: string): Promise<SheetMeta | null>;
+    deleteSheet(name: string): Promise<void>;
+    $connect(): Promise<void>;
+    $disconnect(): Promise<void>;
+    exec<T = any>(query: string, params?: Record<string, any>): Promise<T[]>;
+    $queryRawUnsafe<T = any>(query: string, ...values: any[]): Promise<T[]>;
+    $executeRaw(query: string, ...values: any[]): Promise<number>;
+    $executeRawUnsafe(query: string, ...values: any[]): Promise<number>;
+    $transaction<R>(fn: (tx: An5SheetsAdapter) => Promise<R>, _options?: {
+        timeout?: number;
+    }): Promise<R>;
+    $transaction<R>(list: Promise<R>[]): Promise<R[]>;
+    table<T = any>(modelName: string): SheetsTableClient<T>;
+    readRange<T = any>(range: string): Promise<T[][]>;
+    writeRange(range: string, values: any[][]): Promise<void>;
+    appendRange(range: string, values: any[][]): Promise<void>;
+}
+export declare function createAn5SheetsAdapter(config: An5SheetsAdapterConfig): An5SheetsAdapter;

package/typescript/googlesheets/adapter.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.An5SheetsAdapter = void 0;
+exports.createAn5SheetsAdapter = createAn5SheetsAdapter;
+const googleapis_1 = require("googleapis");
+const config_1 = require("./config");
+const sqlExecutor_1 = require("./sqlExecutor");
+const tableClient_1 = require("./tableClient");
+const retry_1 = require("./retry");
+// ─── Adapter ──────────────────────────────────────────────────────────────────
+class An5SheetsAdapter {
+    constructor(config) {
+        this.sheets = null;
+        this.sheetsCache = null;
+        this.config = (0, config_1.resolveConfig)(config);
+    }
+    async getSheets() {
+        if (!this.sheets) {
+            const auth = new googleapis_1.google.auth.JWT({
+                email: this.config.clientEmail,
+                key: this.config.privateKey,
+                scopes: ['https://www.googleapis.com/auth/spreadsheets'],
+            });
+            this.sheets = googleapis_1.google.sheets({ version: 'v4', auth });
+        }
+        return this.sheets;
+    }
+    async getApi() {
+        return this.getSheets();
+    }
+    invalidateCache() {
+        this.sheetsCache = null;
+    }
+    async listSheets() {
+        const api = await this.getApi();
+        const res = await (0, retry_1.withRetry)(() => api.spreadsheets.get({
+            spreadsheetId: this.config.spreadsheetId,
+            fields: 'sheets.properties.title',
+        }));
+        return (res.data.sheets || []).map(s => s.properties?.title || '');
+    }
+    async getSheetMeta(name) {
+        const api = await this.getApi();
+        if (this.sheetsCache == null) {
+            this.sheetsCache = (0, retry_1.withRetry)(async () => {
+                const res = await api.spreadsheets.get({
+                    spreadsheetId: this.config.spreadsheetId,
+                    fields: 'sheets.properties',
+                });
+                return (res.data.sheets || []).map(s => ({
+                    sheetId: s.properties?.sheetId ?? -1,
+                    title: s.properties?.title ?? '',
+                })).filter(m => m.sheetId >= 0);
+            });
+        }
+        const all = await this.sheetsCache;
+        return all.find(m => m.title === name) || null;
+    }
+    async deleteSheet(name) {
+        const meta = await this.getSheetMeta(name);
+        if (!meta)
+            throw new Error(`Sheet "${name}" not found`);
+        const api = await this.getApi();
+        await (0, retry_1.withRetry)(() => api.spreadsheets.batchUpdate({
+            spreadsheetId: this.config.spreadsheetId,
+            requestBody: {
+                requests: [{ deleteSheet: { sheetId: meta.sheetId } }],
+            },
+        }));
+        this.invalidateCache();
+    }
+    async $connect() {
+        await this.getSheets();
+    }
+    async $disconnect() {
+        this.sheets = null;
+        this.sheetsCache = null;
+    }
+    async exec(query, params) {
+        return (0, sqlExecutor_1.execQuery)(this, query, params, undefined, undefined);
+    }
+    async $queryRawUnsafe(query, ...values) {
+        const params = {};
+        values.forEach((v, i) => { params[`p_${i}`] = v; });
+        const resolved = query.replace(/@p_(\d+)/g, (_, i) => `@p_${i}`);
+        return (0, sqlExecutor_1.execQuery)(this, resolved, params, undefined, undefined);
+    }
+    async $executeRaw(query, ...values) {
+        const params = {};
+        values.forEach((v, i) => { params[`p_${i}`] = v; });
+        const resolved = query.replace(/@p_(\d+)/g, (_, i) => `@p_${i}`);
+        return (0, sqlExecutor_1.execQuery)(this, resolved, params, undefined, undefined);
+    }
+    async $executeRawUnsafe(query, ...values) {
+        return this.$executeRaw(query, ...values);
+    }
+    async $transaction(fn, _options) {
+        if (typeof fn === 'function')
+            return fn(this);
+        return Promise.all(fn);
+    }
+    table(modelName) {
+        return new tableClient_1.SheetsTableClient(this, modelName, this.config.sheetMapping);
+    }
+    // ── Raw range access ──────────────────────────────────────────────────────
+    async readRange(range) {
+        const api = await this.getApi();
+        const res = await (0, retry_1.withRetry)(() => api.spreadsheets.values.get({
+            spreadsheetId: this.config.spreadsheetId,
+            range,
+        }));
+        return (res.data.values || []);
+    }
+    async writeRange(range, values) {
+        const api = await this.getApi();
+        await (0, retry_1.withRetry)(() => api.spreadsheets.values.update({
+            spreadsheetId: this.config.spreadsheetId,
+            range,
+            valueInputOption: 'RAW',
+            requestBody: { values },
+        }));
+    }
+    async appendRange(range, values) {
+        const api = await this.getApi();
+        await (0, retry_1.withRetry)(() => api.spreadsheets.values.append({
+            spreadsheetId: this.config.spreadsheetId,
+            range,
+            valueInputOption: 'RAW',
+            insertDataOption: 'INSERT_ROWS',
+            requestBody: { values },
+        }));
+    }
+}
+exports.An5SheetsAdapter = An5SheetsAdapter;
+// ─── Factory ──────────────────────────────────────────────────────────────────
+function createAn5SheetsAdapter(config) {
+    return new An5SheetsAdapter(config);
+}