@an5/adapters 0.2.5 → 0.2.9

package/typescript/src/googlesheets/helpers.ts

@@ -1,143 +1,144 @@
-import { getModelToTable } from '../base/metadata';
-
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-
-export function esc(name: string): string {
-  return name.includes(' ') || /[^\w]/.test(name) ? `'${name.replace(/'/g, "''")}'` : name;
-}
-
-export function resolveSheetName(modelName: string, mapping?: Record<string, string>): string {
-  if (mapping?.[modelName]) return mapping[modelName];
-  const modelToTable = getModelToTable();
-  return modelToTable[modelName] || modelName;
-}
-
-export function matchWhere(row: Record<string, any>, where: any): boolean {
-  if (!where) return true;
-
-  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)) {
-      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;
-      continue;
-    }
-    if (key === 'NOT') {
-      const notClauses = Array.isArray(value) ? value : [value];
-      if (notClauses.some((v: any) => matchWhere(row, v))) return false;
-      continue;
-    }
-
-    const cellVal = row[key];
-
-    if (value === null) {
-      if (cellVal !== null && cellVal !== undefined) return false;
-    } else if (typeof value === 'object' && !(value instanceof Date)) {
-      const v = value as any;
-      const caseInsensitive = v.mode === 'insensitive';
-      const normalize = (s: any) => caseInsensitive ? String(s ?? '').toLowerCase() : s;
-
-      if (v.not !== undefined) {
-        if (v.not === null) { if (cellVal === null || cellVal === undefined) 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 (v.startsWith !== undefined) {
-        if (!cellVal || !normalize(String(cellVal)).startsWith(normalize(v.startsWith))) return false;
-      }
-      if (v.endsWith !== undefined) {
-        if (!cellVal || !normalize(String(cellVal)).endsWith(normalize(v.endsWith))) return false;
-      }
-      if (v.gte !== undefined && !(Number(cellVal) >= Number(v.gte))) return false;
-      if (v.lte !== undefined && !(Number(cellVal) <= Number(v.lte))) return false;
-      if (v.gt !== undefined && !(Number(cellVal) > Number(v.gt))) return false;
-      if (v.lt !== undefined && !(Number(cellVal) < Number(v.lt))) return false;
-      if (v.in !== undefined) {
-        if (!Array.isArray(v.in) || !v.in.some((item: any) => item == cellVal)) return false;
-      }
-      if (v.notIn !== undefined) {
-        if (Array.isArray(v.notIn) && v.notIn.some((item: any) => item == cellVal)) return false;
-      }
-    } else {
-      // loose equality to handle string/number coercion from sheet cells
-      if (cellVal != value) return false;
-    }
-  }
-  return true;
-}
-
-
-export function buildOrderBy(orderBy: any): 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(`${key} ${String(dir || 'asc').toUpperCase()}`);
-    }
-  }
-  return parts.join(', ');
-}
-
-export function sortRows(rows: Record<string, any>[], orderBy: string): Record<string, any>[] {
-  if (!orderBy) return rows;
-  const clauses = orderBy.split(',').map(c => c.trim());
-  return [...rows].sort((a, b) => {
-    for (const clause of clauses) {
-      const [field, dir] = clause.split(/\s+/);
-      const direction = dir?.toUpperCase() === 'DESC' ? -1 : 1;
-      const aVal = a[field];
-      const bVal = b[field];
-      if (aVal == null && bVal == null) continue;
-      if (aVal == null) return 1 * direction;
-      if (bVal == null) return -1 * direction;
-      if (aVal < bVal) return -1 * direction;
-      if (aVal > bVal) return 1 * direction;
-    }
-    return 0;
-  });
-}
-
-export function coerceCell(raw: any, fieldMeta?: { ts?: string; sql?: string }): any {
-  if (raw === undefined || raw === '') return null;
-  if (raw instanceof Date) return raw.toISOString();
-  if (fieldMeta) {
-    const tsType = (fieldMeta.ts || '').toLowerCase().replace('?', '');
-    if (['number', 'int', 'float', 'double', 'decimal'].includes(tsType)) {
-      const n = Number(raw);
-      return isNaN(n) ? raw : n;
-    }
-    if (tsType === 'boolean' || tsType === 'bool') {
-      if (raw === 'true' || raw === true) return true;
-      if (raw === 'false' || raw === false) return false;
-    }
-  }
-  if (typeof raw === 'string' && /^-?\d+\.?\d*$/.test(raw.trim()) && !/^0\d/.test(raw.trim())) {
-    const n = Number(raw);
-    if (!isNaN(n) && String(n) === raw.trim()) return n;
-  }
-  if (raw === 'true') return true;
-  if (raw === 'false') return false;
-  return raw;
-}
+import { getModelToTable } from '../base/metadata';
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+export function esc(name: string): string {
+  return name.includes(' ') || /[^\w]/.test(name) ? `'${name.replace(/'/g, "''")}'` : name;
+}
+
+export function resolveSheetName(modelName: string, mapping?: Record<string, string>): string {
+  if (mapping?.[modelName]) return mapping[modelName];
+  const modelToTable = getModelToTable();
+  return modelToTable[modelName] || modelName;
+}
+
+export function matchWhere(row: Record<string, any>, where: any): boolean {
+  if (!where) return true;
+
+  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)) {
+      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;
+      continue;
+    }
+    if (key === 'NOT') {
+      const notClauses = Array.isArray(value) ? value : [value];
+      if (notClauses.some((v: any) => matchWhere(row, v))) return false;
+      continue;
+    }
+
+    const cellVal = row[key];
+
+    if (value === null) {
+      if (cellVal !== null && cellVal !== undefined) return false;
+    } else if (typeof value === 'object' && !(value instanceof Date)) {
+      const v = value as any;
+      const caseInsensitive = v.mode === 'insensitive';
+      const normalize = (s: any) => caseInsensitive ? String(s ?? '').toLowerCase() : s;
+
+      if (v.not !== undefined) {
+        if (v.not === null) { if (cellVal === null || cellVal === undefined) 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 (v.startsWith !== undefined) {
+        if (!cellVal || !normalize(String(cellVal)).startsWith(normalize(v.startsWith))) return false;
+      }
+      if (v.endsWith !== undefined) {
+        if (!cellVal || !normalize(String(cellVal)).endsWith(normalize(v.endsWith))) return false;
+      }
+      if (v.gte !== undefined && !(Number(cellVal) >= Number(v.gte))) return false;
+      if (v.lte !== undefined && !(Number(cellVal) <= Number(v.lte))) return false;
+      if (v.gt !== undefined && !(Number(cellVal) > Number(v.gt))) return false;
+      if (v.lt !== undefined && !(Number(cellVal) < Number(v.lt))) return false;
+      if (v.in !== undefined) {
+        if (!Array.isArray(v.in) || !v.in.some((item: any) => item == cellVal)) return false;
+      }
+      if (v.notIn !== undefined) {
+        if (Array.isArray(v.notIn) && v.notIn.some((item: any) => item == cellVal)) return false;
+      }
+    } else {
+      // loose equality to handle string/number coercion from sheet cells
+      if (cellVal != value) return false;
+    }
+  }
+  return true;
+}
+
+
+export function buildOrderBy(orderBy: any): 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(`${key} ${String(dir || 'asc').toUpperCase()}`);
+    }
+  }
+  return parts.join(', ');
+}
+
+export function sortRows(rows: Record<string, any>[], orderBy: string): Record<string, any>[] {
+  if (!orderBy) return rows;
+  const clauses = orderBy.split(',').map(c => c.trim());
+  return [...rows].sort((a, b) => {
+    for (const clause of clauses) {
+      const [field, dir] = clause.split(/\s+/);
+      if (field === undefined) continue;
+      const direction = dir?.toUpperCase() === 'DESC' ? -1 : 1;
+      const aVal = a[field];
+      const bVal = b[field];
+      if (aVal == null && bVal == null) continue;
+      if (aVal == null) return 1 * direction;
+      if (bVal == null) return -1 * direction;
+      if (aVal < bVal) return -1 * direction;
+      if (aVal > bVal) return 1 * direction;
+    }
+    return 0;
+  });
+}
+
+export function coerceCell(raw: any, fieldMeta?: { ts?: string; sql?: string }): any {
+  if (raw === undefined || raw === '') return null;
+  if (raw instanceof Date) return raw.toISOString();
+  if (fieldMeta) {
+    const tsType = (fieldMeta.ts || '').toLowerCase().replace('?', '');
+    if (['number', 'int', 'float', 'double', 'decimal'].includes(tsType)) {
+      const n = Number(raw);
+      return isNaN(n) ? raw : n;
+    }
+    if (tsType === 'boolean' || tsType === 'bool') {
+      if (raw === 'true' || raw === true) return true;
+      if (raw === 'false' || raw === false) return false;
+    }
+  }
+  if (typeof raw === 'string' && /^-?\d+\.?\d*$/.test(raw.trim()) && !/^0\d/.test(raw.trim())) {
+    const n = Number(raw);
+    if (!isNaN(n) && String(n) === raw.trim()) return n;
+  }
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  return raw;
+}

package/typescript/src/googlesheets/index.ts

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

package/typescript/src/googlesheets/parseConnectionString.ts

@@ -1,46 +1,48 @@
-import type { An5SheetsAdapterConfig } from './config';
-
-/**
- * Parse a `googlesheets://` connection string into An5SheetsAdapterConfig.
- *
- * Format:
- *   googlesheets://spreadsheetId;clientEmail=xxx;privateKey=xxx
- *   googlesheets://spreadsheetId;clientEmail=xxx;privateKey=xxx;sheetMapping=users:Users,orders:Orders
- *
- * The privateKey must be URL-encoded (use encodeURIComponent on the raw key).
- */
-export function parseSheetsConnectionString(url: string): An5SheetsAdapterConfig {
-  const clean = url.replace(/^googlesheets:\/\//, '');
-  const parts = clean.split(';');
-
-  const spreadsheetId = parts[0].trim();
-  const config: Record<string, string> = {};
-
-  for (let i = 1; i < parts.length; i++) {
-    const part = parts[i].trim();
-    if (!part) continue;
-    const eqIdx = part.indexOf('=');
-    if (eqIdx === -1) continue;
-    const key = part.slice(0, eqIdx).trim().toLowerCase();
-    const value = decodeURIComponent(part.slice(eqIdx + 1).trim());
-    config[key] = value;
-  }
-
-  const result: An5SheetsAdapterConfig = { spreadsheetId };
-
-  if (config.clientemail) result.clientEmail = config.clientemail;
-  if (config.privatekey) result.privateKey = config.privatekey;
-  if (config.accesstoken) result.accessToken = config.accesstoken;
-  if (config.apikey) result.apiKey = config.apikey;
-
-  if (config.sheetmapping) {
-    const mapping: Record<string, string> = {};
-    for (const pair of config.sheetmapping.split(',')) {
-      const [k, v] = pair.split(':');
-      if (k && v) mapping[k.trim()] = v.trim();
-    }
-    result.sheetMapping = mapping;
-  }
-
-  return result;
-}
+import type { An5SheetsAdapterConfig } from './config';
+
+/**
+ * Parse a `googlesheets://` connection string into An5SheetsAdapterConfig.
+ *
+ * Format:
+ *   googlesheets://spreadsheetId;clientEmail=xxx;privateKey=xxx
+ *   googlesheets://spreadsheetId;clientEmail=xxx;privateKey=xxx;sheetMapping=users:Users,orders:Orders
+ *
+ * The privateKey must be URL-encoded (use encodeURIComponent on the raw key).
+ */
+export function parseSheetsConnectionString(url: string): An5SheetsAdapterConfig {
+  const clean = url.replace(/^googlesheets:\/\//, '');
+  const parts = clean.split(';');
+
+  const spreadsheetId = (parts[0] ?? '').trim();
+  const config: Record<string, string> = {};
+
+  for (let i = 1; i < parts.length; i++) {
+    const rawPart = parts[i];
+    if (rawPart === undefined) continue;
+    const part = rawPart.trim();
+    if (!part) continue;
+    const eqIdx = part.indexOf('=');
+    if (eqIdx === -1) continue;
+    const key = part.slice(0, eqIdx).trim().toLowerCase();
+    const value = decodeURIComponent(part.slice(eqIdx + 1).trim());
+    config[key] = value;
+  }
+
+  const result: An5SheetsAdapterConfig = { spreadsheetId };
+
+  if (config.clientemail) result.clientEmail = config.clientemail;
+  if (config.privatekey) result.privateKey = config.privatekey;
+  if (config.accesstoken) result.accessToken = config.accesstoken;
+  if (config.apikey) result.apiKey = config.apikey;
+
+  if (config.sheetmapping) {
+    const mapping: Record<string, string> = {};
+    for (const pair of config.sheetmapping.split(',')) {
+      const [k, v] = pair.split(':');
+      if (k && v) mapping[k.trim()] = v.trim();
+    }
+    result.sheetMapping = mapping;
+  }
+
+  return result;
+}

package/typescript/src/googlesheets/retry.ts

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