@everystack/api 0.1.0

package/src/handler/index.ts

@@ -0,0 +1,1545 @@
+/**
+ * Creates a PostgREST-compatible HTTP handler from a Drizzle db instance and schema.
+ *
+ * Usage:
+ *   import { createHandler } from 'everystack/handler';
+ *   const handler = createHandler(db, schema);
+ *   // Mount as Expo Router API route or any Web Standard handler
+ */
+
+import { eq, ne, gt, gte, lt, lte, like, ilike, isNull, isNotNull, inArray, and, or, not, asc, desc, sql } from 'drizzle-orm';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type DrizzleDb = any;
+type DrizzleTable = any;
+type DrizzleColumn = any;
+
+type Schema = Record<string, DrizzleTable>;
+
+type Handler = (request: Request) => Promise<Response>;
+
+export interface RoleConfig {
+  /** Role required for GET requests on this table */
+  read: string;
+  /** Role required for POST/PATCH/DELETE requests on this table */
+  write: string;
+}
+
+export interface AuthConfig {
+  /** Verify a Bearer token and return the user payload, or null if invalid */
+  verifyToken: (token: string) => Promise<Record<string, unknown> | null>;
+  /** HTTP methods that don't require authentication (e.g., ['GET'] for public reads) */
+  publicRoutes: string[];
+  /** RPC function names that don't require authentication (e.g., ['health', 'issues']) */
+  publicRpc?: string[];
+  /** Called after successful authentication with the user payload */
+  onAuthenticated?: (user: Record<string, unknown>) => void;
+  /** Verify client credentials and return client metadata, or null if invalid.
+   *  When configured, client headers are required on every request (including public routes). */
+  verifyClient?: (clientId: string, clientSecret: string) => Promise<Record<string, unknown> | null>;
+  /** Custom header names for client credentials.
+   *  Defaults: { id: 'X-Client-Id', secret: 'X-Client-Secret' } */
+  clientHeaders?: { id: string; secret: string };
+  /** Called after successful client authentication with the client payload */
+  onClientAuthenticated?: (client: Record<string, unknown>) => void;
+  /** Per-table role requirements. Key is table name or '*' for wildcard default.
+   *  When set, overrides publicRoutes for tables that have an entry. */
+  roles?: Record<string, RoleConfig>;
+  /** Ordered role hierarchy, lowest to highest privilege.
+   *  Default: ['public', 'authenticated', 'admin'] */
+  roleHierarchy?: string[];
+  /** Field in the user payload containing the role string. Default: 'role' */
+  roleField?: string;
+}
+
+export interface RelationConfig {
+  /** Target table name (must exist in the schema) */
+  table: string;
+  /** Column on the source table (e.g., 'authorId' for posts.authorId → authors.id) */
+  from: string;
+  /** Column on the target table (e.g., 'id') */
+  to: string;
+  /** If true, this is a one-to-many relation (returns array). Default: false (many-to-one, returns object) */
+  many?: boolean;
+}
+
+export interface SoftDeleteConfig {
+  /** Column name for soft-delete timestamp. Default: 'deletedAt' */
+  column?: string;
+  /** Tables with soft-delete enabled. If omitted, all tables with the column are treated as soft-delete. */
+  tables?: string[];
+}
+
+export interface HookConfig {
+  /** Called before INSERT. Can modify the body (e.g., inject userId). Throw to abort. */
+  beforeCreate?: (body: Record<string, unknown>, user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<Record<string, unknown>>;
+  /** Called after INSERT with the returned row. Fire-and-forget. */
+  afterCreate?: (row: Record<string, unknown>, user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<void>;
+  /** Called before UPDATE. Can modify the body. Throw to abort. */
+  beforeUpdate?: (body: Record<string, unknown>, user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<Record<string, unknown>>;
+  /** Called after UPDATE with all returned rows. Fire-and-forget. */
+  afterUpdate?: (rows: Record<string, unknown>[], user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<void>;
+  /** Called before DELETE. Throw to abort. */
+  beforeDelete?: (user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<void>;
+  /** Called after DELETE with all deleted rows. Fire-and-forget. */
+  afterDelete?: (rows: Record<string, unknown>[], user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<void>;
+}
+
+/** Cache-Control header configuration for different response categories. */
+export interface CacheConfig {
+  /** Public GET responses (role-based reads allowed without auth).
+   *  Default: 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5' */
+  public?: string;
+  /** Authenticated/private responses.
+   *  Default: 'private, no-store' */
+  private?: string;
+}
+
+export interface HandlerOptions {
+  auth?: AuthConfig;
+  rpc?: Record<string, (body: unknown, user?: Record<string, unknown> | null, client?: Record<string, unknown> | null) => Promise<unknown>>;
+  /** Relation definitions for resource embedding: { [sourceTable]: { [relationName]: RelationConfig } } */
+  relations?: Record<string, Record<string, RelationConfig>>;
+  /** Base path to strip from request URL (e.g., '/api' when mounted at /api/[...path]) */
+  basePath?: string;
+  /** Enable soft-delete: DELETE becomes UPDATE SET deleted_at, reads filter deleted rows */
+  softDelete?: SoftDeleteConfig;
+  /** Drizzle schema relations — enables JOIN queries via db.query API instead of batch WHERE IN */
+  drizzleRelations?: Record<string, unknown>;
+  /** Compute PostgreSQL session variables from the authenticated user.
+   *  When provided, queries are wrapped in a transaction with set_config() calls
+   *  so RLS policies can reference the user context. */
+  pgSettings?: (user: Record<string, unknown> | null, client?: Record<string, unknown> | null) => Record<string, string>;
+  /** Per-table lifecycle hooks for mutations. */
+  hooks?: Record<string, HookConfig>;
+  /** API naming convention for query params, request bodies, and responses.
+   *  'snake_case': accept snake_case inbound, return snake_case outbound.
+   *  Default: use Drizzle property names as-is (typically camelCase). */
+  naming?: 'camelCase' | 'snake_case';
+  /** Override default Cache-Control headers for API responses. */
+  cache?: CacheConfig;
+}
+
+function getSoftDeleteColumn(table: DrizzleTable, options?: HandlerOptions): DrizzleColumn | null {
+  if (!options?.softDelete) return null;
+  const colName = options.softDelete.column || 'deletedAt';
+  return getColumn(table, colName);
+}
+
+function isSoftDeleteTable(tableName: string, table: DrizzleTable, options?: HandlerOptions): boolean {
+  if (!options?.softDelete) return false;
+  if (options.softDelete.tables) {
+    return options.softDelete.tables.includes(tableName);
+  }
+  // Auto-detect: table has the soft-delete column
+  return getSoftDeleteColumn(table, options) != null;
+}
+
+/**
+ * Execute a function with pgSettings applied in the same transaction.
+ *
+ * set_config(key, value, true) is LOCAL — transaction-scoped. Without a
+ * wrapping transaction the settings and the query may hit different pooled
+ * connections, losing RLS context. This helper ensures they share one.
+ *
+ * The 'role' key is special — it maps to SET LOCAL ROLE instead of set_config.
+ * This is required for PostgreSQL RLS policies that use TO role_name clauses.
+ * Without SET ROLE, the connection stays as the superuser/owner and BYPASSRLS
+ * silently disables all row-level security policies.
+ */
+async function executeWithSettings<T>(
+  db: DrizzleDb,
+  settings: Record<string, string> | undefined,
+  fn: (dbOrTx: DrizzleDb) => Promise<T>,
+): Promise<T> {
+  if (settings && Object.keys(settings).length > 0) {
+    return db.transaction(async (tx: DrizzleDb) => {
+      const role = settings['role'];
+      if (role) {
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(role)) {
+          throw new Error(`Invalid role name: ${role}`);
+        }
+        await tx.execute(sql.raw(`SET LOCAL ROLE ${role}`));
+      }
+      for (const [key, value] of Object.entries(settings)) {
+        if (key !== 'role' && value !== undefined && value !== '') {
+          await tx.execute(sql`SELECT set_config(${key}, ${value}, true)`);
+        }
+      }
+      return fn(tx);
+    });
+  }
+  return fn(db);
+}
+
+/**
+ * Determine the role required for a given table + HTTP method.
+ * Resolution: roles[tableName] → roles['*'] → null (use publicRoutes fallback).
+ */
+function getRequiredRole(
+  tableName: string,
+  method: string,
+  auth?: AuthConfig,
+): string | null {
+  if (!auth?.roles) return null;
+  const config = auth.roles[tableName] ?? auth.roles['*'];
+  if (!config) return null;
+  return method === 'GET' ? config.read : config.write;
+}
+
+/**
+ * Check whether userRole meets or exceeds requiredRole in the hierarchy.
+ * Both in hierarchy → index comparison. Otherwise → exact string match.
+ */
+function hasRole(
+  userRole: string,
+  requiredRole: string,
+  hierarchy: string[],
+): boolean {
+  const requiredIndex = hierarchy.indexOf(requiredRole);
+  const userIndex = hierarchy.indexOf(userRole);
+  if (requiredIndex !== -1 && userIndex !== -1) {
+    return userIndex >= requiredIndex;
+  }
+  return userRole === requiredRole;
+}
+
+/**
+ * Extract Bearer token from request and verify it.
+ * Returns { user, error } — error is a Response (401) if auth fails.
+ */
+async function verifyUserToken(
+  request: Request,
+  auth: AuthConfig,
+): Promise<{ user: Record<string, unknown> | null; error: Response | null }> {
+  const authHeader = request.headers.get('Authorization');
+  const token = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : null;
+
+  if (!token) {
+    return { user: null, error: json({ message: 'Authentication required: no auth token provided' }, 401) };
+  }
+
+  let user: Record<string, unknown> | null;
+  try {
+    user = await auth.verifyToken(token);
+  } catch {
+    return { user: null, error: json({ message: 'Authentication failed: invalid or expired token' }, 401) };
+  }
+
+  if (!user) {
+    return { user: null, error: json({ message: 'Authentication failed: invalid or expired token' }, 401) };
+  }
+
+  return { user, error: null };
+}
+
+/**
+ * Perform role-based auth check. Returns { user, error }.
+ *
+ * - 'public' → no token required (extracts user if token present for pgSettings)
+ * - 'authenticated' → any valid JWT
+ * - named role → valid JWT + role >= required in hierarchy
+ */
+async function checkRoleAuth(
+  requiredRole: string,
+  request: Request,
+  auth: AuthConfig,
+): Promise<{ user: Record<string, unknown> | null; error: Response | null }> {
+  if (requiredRole === 'public') {
+    return { user: null, error: null };
+  }
+
+  const result = await verifyUserToken(request, auth);
+  if (result.error) return result;
+
+  // 'authenticated' means any valid JWT — role claim is irrelevant
+  if (requiredRole === 'authenticated') {
+    return result;
+  }
+
+  // Named role: check hierarchy
+  const hierarchy = auth.roleHierarchy ?? ['public', 'authenticated', 'admin'];
+  const roleField = auth.roleField ?? 'role';
+  const userRole = String(result.user![roleField] ?? '');
+
+  if (!hasRole(userRole, requiredRole, hierarchy)) {
+    return {
+      user: result.user,
+      error: json({ message: `Insufficient permissions: requires ${requiredRole} role` }, 403),
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Determine the Cache-Control header for a GET response based on role config.
+ * - pgSettings configured → private header (per-user data via RLS)
+ * - read: 'public' → public header
+ * - Any other role → private header
+ * - No roles config → null (let server package set its default)
+ *
+ * Headers are configurable via options.cache. Defaults:
+ * - public: 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5'
+ * - private: 'private, no-store'
+ */
+function getCacheControl(tableName: string, options?: HandlerOptions): string | null {
+  const publicHeader = options?.cache?.public ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5';
+  const privateHeader = options?.cache?.private ?? 'private, no-store';
+
+  if (options?.pgSettings) return privateHeader;
+  if (!options?.auth?.roles) return null;
+  const requiredRole = getRequiredRole(tableName, 'GET', options.auth);
+  if (requiredRole === null) return null;
+  if (requiredRole === 'public') return publicHeader;
+  return privateHeader;
+}
+
+/**
+ * Serialize roles config into a compact JSON manifest for CloudFront KVS.
+ * Format: { "__tables__": ["posts", ...], "*": { "r": "public", "w": "authenticated" }, ... }
+ */
+export function serializeRolesManifest(
+  schema: Schema,
+  roles: Record<string, RoleConfig>,
+): string {
+  const manifest: Record<string, unknown> = { __tables__: Object.keys(schema) };
+  for (const [key, config] of Object.entries(roles)) {
+    manifest[key] = { r: config.read, w: config.write };
+  }
+  return JSON.stringify(manifest);
+}
+
+// --- Naming convention helpers ---
+
+function toCamelCase(str: string): string {
+  return str.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+function toSnakeCase(str: string): string {
+  return str.replace(/[A-Z]/g, c => `_${c.toLowerCase()}`);
+}
+
+function transformKeys(data: unknown, fn: (key: string) => string): unknown {
+  if (Array.isArray(data)) {
+    return data.map(item => transformKeys(item, fn));
+  }
+  if (data !== null && typeof data === 'object' && !(data instanceof Date)) {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
+      result[fn(key)] = transformKeys(value, fn);
+    }
+    return result;
+  }
+  return data;
+}
+
+function transformResponse(data: unknown, options?: HandlerOptions): unknown {
+  if (!options?.naming || options.naming === 'camelCase') return data;
+  return transformKeys(data, toSnakeCase);
+}
+
+function transformBodyKeys(body: Record<string, unknown>, table: DrizzleTable): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(body)) {
+    if (table[key]) {
+      result[key] = value;
+    } else if (key.includes('_')) {
+      const camelKey = toCamelCase(key);
+      result[table[camelKey] ? camelKey : key] = value;
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOptions): Handler {
+  const tableNames = new Set(Object.keys(schema));
+
+  return async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    let pathname = url.pathname;
+    if (options?.basePath) {
+      const base = options.basePath.replace(/\/+$/, '');
+      if (pathname.startsWith(base)) {
+        pathname = pathname.slice(base.length);
+      }
+    }
+    const pathSegments = pathname.replace(/^\/+/, '').split('/').filter(Boolean);
+    const method = request.method.toUpperCase();
+
+    // Phase 1: Client auth (if configured) — identifies which app is calling
+    let user: Record<string, unknown> | null = null;
+    let client: Record<string, unknown> | null = null;
+    if (options?.auth?.verifyClient) {
+      const idHeader = options.auth.clientHeaders?.id ?? 'X-Client-Id';
+      const secretHeader = options.auth.clientHeaders?.secret ?? 'X-Client-Secret';
+      const clientId = request.headers.get(idHeader);
+      const clientSecret = request.headers.get(secretHeader);
+
+      if (!clientId || !clientSecret) {
+        return json({ message: 'Client authentication required: missing client credentials' }, 401);
+      }
+
+      try {
+        client = await options.auth.verifyClient(clientId, clientSecret);
+      } catch {
+        return json({ message: 'Client authentication failed: invalid client credentials' }, 401);
+      }
+
+      if (!client) {
+        return json({ message: 'Client authentication failed: invalid client credentials' }, 401);
+      }
+
+      if (options.auth.onClientAuthenticated) {
+        options.auth.onClientAuthenticated(client);
+      }
+    }
+
+    // Root path — table listing, always public
+    if (pathSegments.length === 0) {
+      return json({ tables: Array.from(tableNames) }, 200);
+    }
+
+    // RPC path — uses publicRoutes/publicRpc for auth, not table roles
+    if (pathSegments[0] === 'rpc') {
+      if (options?.auth) {
+        const isPublicMethod = options.auth.publicRoutes.includes(method);
+        const isPublicRpc = pathSegments[1]
+          && options.auth.publicRpc?.includes(pathSegments[1]);
+        if (!isPublicMethod && !isPublicRpc) {
+          const result = await verifyUserToken(request, options.auth);
+          if (result.error) return result.error;
+          user = result.user;
+          if (user && options.auth.onAuthenticated) {
+            options.auth.onAuthenticated(user);
+          }
+        }
+      }
+
+      const fnName = pathSegments[1];
+      if (options?.rpc && fnName && options.rpc[fnName]) {
+        const body = method === 'POST' ? await request.json().catch(() => ({})) : {};
+        const result = await options.rpc[fnName](body, user, client);
+        return json(result, 200);
+      }
+      return json({ message: 'Function not found' }, 404);
+    }
+
+    const tableName = pathSegments[0];
+
+    if (!tableNames.has(tableName)) {
+      return json({ message: `Table '${tableName}' not found` }, 404);
+    }
+
+    // Phase 2: User auth (role-aware) — now we know the table name
+    if (options?.auth) {
+      const requiredRole = getRequiredRole(tableName, method, options.auth);
+
+      if (requiredRole !== null) {
+        // Role-based path
+        const result = await checkRoleAuth(requiredRole, request, options.auth);
+        if (result.error) return result.error;
+        user = result.user;
+      } else {
+        // Legacy path: fall back to publicRoutes
+        const isPublicMethod = options.auth.publicRoutes.includes(method);
+        if (!isPublicMethod) {
+          const result = await verifyUserToken(request, options.auth);
+          if (result.error) return result.error;
+          user = result.user;
+        }
+      }
+
+      if (user && options.auth.onAuthenticated) {
+        options.auth.onAuthenticated(user);
+      }
+    }
+
+    // Compute pgSettings after auth (user now resolved)
+    const settings = options?.pgSettings?.(user, client);
+    const table = schema[tableName];
+
+    return executeWithSettings(db, settings, async (dbOrTx) => {
+      if (method === 'GET') {
+        const cacheControl = getCacheControl(tableName, options);
+        return handleGet(dbOrTx, schema, table, tableName, url.searchParams, request, options, cacheControl);
+      }
+
+      if (method === 'POST') {
+        return handlePost(dbOrTx, table, tableName, request, options, user, client);
+      }
+
+      if (method === 'PATCH') {
+        return handlePatch(dbOrTx, table, tableName, request, url.searchParams, options, user, client);
+      }
+
+      if (method === 'DELETE') {
+        return handleDelete(dbOrTx, table, tableName, url.searchParams, options, user, client);
+      }
+
+      return json({ message: `Method ${method} not allowed` }, 405);
+    });
+  };
+}
+
+/**
+ * Convert parsed embeds to Drizzle's `with` clause format for relational queries.
+ * { name: 'author', columns: null } → { author: true }
+ * { name: 'author', columns: ['name'] } → { author: { columns: { name: true } } }
+ */
+function buildWithClause(
+  embeds: EmbedRequest[],
+  tableRelations: Record<string, RelationConfig>,
+): Record<string, any> | undefined {
+  if (embeds.length === 0) return undefined;
+
+  const withClause: Record<string, any> = {};
+  let hasEmbedded = false;
+
+  for (const embed of embeds) {
+    if (!tableRelations[embed.name]) continue;
+    hasEmbedded = true;
+
+    if (embed.columns === null) {
+      withClause[embed.name] = true;
+    } else {
+      const columns: Record<string, boolean> = {};
+      for (const col of embed.columns) {
+        columns[col] = true;
+      }
+      withClause[embed.name] = { columns };
+    }
+  }
+
+  return hasEmbedded ? withClause : undefined;
+}
+
+/**
+ * Convert column names array to Drizzle's `columns` selection format.
+ * ['id', 'title'] → { id: true, title: true }
+ * null → undefined (all columns)
+ */
+function buildColumnsSelection(columns: string[] | null): Record<string, boolean> | undefined {
+  if (!columns) return undefined;
+  const result: Record<string, boolean> = {};
+  for (const col of columns) {
+    result[col] = true;
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+/**
+ * Build a Drizzle select object for aggregate queries.
+ * Maps aggregate fields to sql expressions and group-by columns to column refs.
+ */
+function buildAggregateSelect(
+  table: DrizzleTable,
+  aggregates: AggregateField[],
+  groupColumns: string[],
+): Record<string, any> {
+  const selection: Record<string, any> = {};
+
+  for (const colName of groupColumns) {
+    const col = getColumn(table, colName);
+    if (col) selection[colName] = col;
+  }
+
+  for (const agg of aggregates) {
+    if (agg.fn === 'count' && !agg.column) {
+      selection[agg.alias] = sql<number>`count(*)`;
+    } else if (agg.column) {
+      const col = getColumn(table, agg.column);
+      if (!col) continue;
+      switch (agg.fn) {
+        case 'count':
+          selection[agg.alias] = sql<number>`count(${col})`;
+          break;
+        case 'sum':
+          selection[agg.alias] = sql<number>`sum(${col})`;
+          break;
+        case 'avg':
+          selection[agg.alias] = sql<number>`avg(${col})`;
+          break;
+        case 'min':
+          selection[agg.alias] = sql<number>`min(${col})`;
+          break;
+        case 'max':
+          selection[agg.alias] = sql<number>`max(${col})`;
+          break;
+      }
+    }
+  }
+
+  return selection;
+}
+
+/**
+ * Serialize aggregate result rows: convert BigInt/string values to Number
+ * for aggregate fields only (group-by column values left untouched).
+ */
+function serializeAggregateRows(
+  rows: Record<string, unknown>[],
+  aggregates: AggregateField[],
+): Record<string, unknown>[] {
+  const aggAliases = new Set(aggregates.map(a => a.alias));
+  return rows.map(row => {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(row)) {
+      if (aggAliases.has(key) && (typeof value === 'bigint' || typeof value === 'string')) {
+        result[key] = Number(value);
+      } else {
+        result[key] = value;
+      }
+    }
+    return result;
+  });
+}
+
+async function handleGet(
+  db: DrizzleDb,
+  schema: Schema,
+  table: DrizzleTable,
+  tableName: string,
+  params: URLSearchParams,
+  request: Request,
+  options?: HandlerOptions,
+  cacheControl?: string | null,
+): Promise<Response> {
+  const limitVal = params.has('limit') ? parseInt(params.get('limit')!, 10) : 1000;
+  const offsetVal = params.has('offset') ? parseInt(params.get('offset')!, 10) : 0;
+  const orderParam = params.get('order');
+  const selectParam = params.get('select');
+
+  // Check if client wants exact count (expensive — requires separate COUNT query)
+  const prefer = request.headers.get('Prefer') || '';
+  const wantExactCount = prefer.includes('count=exact');
+
+  // Parse select parameter for relation embedding and aggregates
+  let { columns, embeds, aggregates } = parseSelectParam(selectParam, options?.relations?.[tableName]);
+
+  // Resolve snake_case select column names to Drizzle camelCase properties
+  if (options?.naming === 'snake_case' && columns) {
+    columns = columns.map(col => {
+      if (table[col]) return col;
+      const camelCol = toCamelCase(col);
+      return table[camelCol] ? camelCol : col;
+    });
+  }
+
+  // Parse PostgREST filters (including or()/and() logical groups and not. negation)
+  const conditions = buildAllConditions(table, params);
+
+  // Soft-delete: filter deleted records unless ?deleted=include|only
+  if (isSoftDeleteTable(tableName, table, options)) {
+    const sdCol = getSoftDeleteColumn(table, options);
+    if (sdCol) {
+      const deletedParam = params.get('deleted');
+      if (deletedParam === 'only') {
+        conditions.push(isNotNull(sdCol));
+      } else if (deletedParam !== 'include') {
+        // Default: exclude deleted records
+        conditions.push(isNull(sdCol));
+      }
+    }
+  }
+
+  // Aggregate query path: SELECT count(*), sum(amount), ... GROUP BY platform
+  if (aggregates.length > 0) {
+    if (embeds.length > 0) {
+      return json({ message: 'Aggregate functions cannot be used with relation embedding' }, 400);
+    }
+
+    const groupColumns = columns || [];
+    const selectObj = buildAggregateSelect(table, aggregates, groupColumns);
+
+    let query: any = db.select(selectObj).from(table);
+
+    if (conditions.length === 1) {
+      query = query.where(conditions[0]);
+    } else if (conditions.length > 1) {
+      query = query.where(and(...conditions));
+    }
+
+    if (groupColumns.length > 0) {
+      const groupByRefs = groupColumns.map(c => getColumn(table, c)).filter(Boolean);
+      if (groupByRefs.length > 0) {
+        query = query.groupBy(...groupByRefs);
+      }
+    }
+
+    if (orderParam) {
+      const orderExpr = buildOrderBy(table, orderParam);
+      if (orderExpr) query = query.orderBy(orderExpr);
+    }
+
+    query = query.limit(limitVal).offset(offsetVal);
+
+    const aggRows = await query;
+    const serialized = serializeAggregateRows(aggRows as Record<string, unknown>[], aggregates);
+
+    const rowCount = serialized.length;
+    let contentRange: string;
+    if (rowCount === 0) {
+      contentRange = '*/*';
+    } else {
+      contentRange = `${offsetVal}-${offsetVal + rowCount - 1}/*`;
+    }
+
+    const aggHeaders: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'Content-Range': contentRange,
+    };
+    if (cacheControl) aggHeaders['Cache-Control'] = cacheControl;
+
+    return new Response(JSON.stringify(transformResponse(serialized, options)), {
+      status: 200,
+      headers: aggHeaders,
+    });
+  }
+
+  // Detect if Drizzle relational query (JOINs) should be used
+  const tableRelations = options?.relations?.[tableName];
+  const useRelationalQuery = embeds.length > 0
+    && tableRelations
+    && options?.drizzleRelations
+    && (db as any).query?.[tableName];
+
+  let rows: unknown[];
+
+  if (useRelationalQuery) {
+    // JOIN path — single query via Drizzle relational API (db.query.findMany)
+    const queryOptions: Record<string, any> = {
+      limit: limitVal,
+      offset: offsetVal,
+    };
+
+    const colSelection = buildColumnsSelection(columns);
+    if (colSelection) queryOptions.columns = colSelection;
+
+    const withClause = buildWithClause(embeds, tableRelations!);
+    if (withClause) queryOptions.with = withClause;
+
+    if (conditions.length === 1) {
+      queryOptions.where = conditions[0];
+    } else if (conditions.length > 1) {
+      queryOptions.where = and(...conditions);
+    }
+
+    if (orderParam) {
+      const orderExpr = buildOrderBy(table, orderParam);
+      if (orderExpr) queryOptions.orderBy = orderExpr;
+    }
+
+    rows = await (db as any).query[tableName].findMany(queryOptions);
+  } else {
+    // Batch path — standard select + separate relation queries
+    let query: any = db.select().from(table);
+
+    if (conditions.length === 1) {
+      query = query.where(conditions[0]);
+    } else if (conditions.length > 1) {
+      query = query.where(and(...conditions));
+    }
+
+    if (orderParam) {
+      const orderExpr = buildOrderBy(table, orderParam);
+      if (orderExpr) {
+        query = query.orderBy(orderExpr);
+      }
+    }
+
+    query = query.limit(limitVal).offset(offsetVal);
+    rows = await query;
+  }
+
+  // Content-Range header: PostgREST convention for pagination metadata
+  let total: string = '*';
+  if (wantExactCount) {
+    let countQuery: any = db.select({ count: sql<number>`count(*)` }).from(table);
+    if (conditions.length === 1) {
+      countQuery = countQuery.where(conditions[0]);
+    } else if (conditions.length > 1) {
+      countQuery = countQuery.where(and(...conditions));
+    }
+    const [{ count }] = await countQuery;
+    total = String(count);
+  }
+
+  const rowCount = (rows as unknown[]).length;
+  let contentRange: string;
+  if (rowCount === 0) {
+    contentRange = `*/${total}`;
+  } else {
+    const rangeStart = offsetVal;
+    const rangeEnd = offsetVal + rowCount - 1;
+    contentRange = `${rangeStart}-${rangeEnd}/${total}`;
+  }
+
+  // Resolve relation embeds (batch path only — JOIN path already has nested data)
+  let responseData: unknown[] = rows as unknown[];
+  if (!useRelationalQuery && embeds.length > 0 && rowCount > 0) {
+    responseData = await resolveEmbeds(db, schema, tableName, rows as Record<string, unknown>[], embeds, options!);
+  }
+
+  // Apply column selection (batch path only — JOIN path handles via queryOptions.columns)
+  if (!useRelationalQuery && columns) {
+    responseData = (responseData as Record<string, unknown>[]).map(row => {
+      const filtered: Record<string, unknown> = {};
+      for (const col of columns) {
+        if (col in row) {
+          filtered[col] = row[col];
+        }
+      }
+      for (const embed of embeds) {
+        if (embed.name in row) {
+          filtered[embed.name] = row[embed.name];
+        }
+      }
+      return filtered;
+    });
+  }
+
+  const getHeaders: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'Content-Range': contentRange,
+  };
+  if (cacheControl) getHeaders['Cache-Control'] = cacheControl;
+
+  return new Response(JSON.stringify(transformResponse(responseData, options)), {
+    status: 200,
+    headers: getHeaders,
+  });
+}
+
+/**
+ * Parse select param to separate plain columns from relation embeds.
+ * Examples:
+ *   "*,author(*)" → columns: null (all), embeds: [{ name: 'author', columns: null }]
+ *   "id,title,author(name)" → columns: ['id','title'], embeds: [{ name: 'author', columns: ['name'] }]
+ */
+interface EmbedRequest {
+  name: string;
+  columns: string[] | null; // null = all columns (*)
+}
+
+type AggregateFunction = 'count' | 'sum' | 'avg' | 'min' | 'max';
+
+interface AggregateField {
+  alias: string;
+  fn: AggregateFunction;
+  column: string | null; // null for bare count()
+}
+
+// Pattern: optional_alias:optional_column.function()
+// Matches: count(), amount.sum(), total:amount.sum(), row_count:count()
+const AGG_REGEX = /^(?:(\w+):)?(?:(\w+)\.)?(count|sum|avg|min|max)\(\)$/;
+
+function parseSelectParam(
+  selectParam: string | null,
+  tableRelations?: Record<string, RelationConfig>,
+): { columns: string[] | null; embeds: EmbedRequest[]; aggregates: AggregateField[] } {
+  if (!selectParam) {
+    return { columns: null, embeds: [], aggregates: [] };
+  }
+
+  const embeds: EmbedRequest[] = [];
+  const columns: string[] = [];
+  const aggregates: AggregateField[] = [];
+  let hasWildcard = false;
+
+  // Parse: split on commas, but respect parentheses
+  const parts = splitSelectParam(selectParam);
+
+  for (const part of parts) {
+    // Check for aggregate pattern first: count(), amount.sum(), total:amount.sum()
+    const aggMatch = part.match(AGG_REGEX);
+    if (aggMatch) {
+      const alias = aggMatch[1] || aggMatch[3]; // explicit alias or function name
+      const column = aggMatch[2] || null;
+      const fn = aggMatch[3] as AggregateFunction;
+      aggregates.push({ alias, fn, column });
+      continue;
+    }
+
+    const embedMatch = part.match(/^(\w+)\((.+)\)$/);
+    if (embedMatch && tableRelations && embedMatch[1] in tableRelations) {
+      const name = embedMatch[1];
+      const innerSelect = embedMatch[2].trim();
+      embeds.push({
+        name,
+        columns: innerSelect === '*' ? null : innerSelect.split(',').map(c => c.trim()),
+      });
+    } else if (part === '*') {
+      hasWildcard = true;
+    } else {
+      columns.push(part);
+    }
+  }
+
+  return {
+    columns: hasWildcard ? null : (columns.length > 0 ? columns : null),
+    embeds,
+    aggregates,
+  };
+}
+
+/**
+ * Split select param respecting parentheses:
+ * "id,title,author(name,email),comments(*)" → ["id", "title", "author(name,email)", "comments(*)"]
+ */
+function splitSelectParam(param: string): string[] {
+  const parts: string[] = [];
+  let current = '';
+  let depth = 0;
+
+  for (const char of param) {
+    if (char === '(') {
+      depth++;
+      current += char;
+    } else if (char === ')') {
+      depth--;
+      current += char;
+    } else if (char === ',' && depth === 0) {
+      parts.push(current.trim());
+      current = '';
+    } else {
+      current += char;
+    }
+  }
+
+  if (current.trim()) {
+    parts.push(current.trim());
+  }
+
+  return parts;
+}
+
+/**
+ * Resolve relation embeds by fetching related rows and nesting them.
+ */
+async function resolveEmbeds(
+  db: DrizzleDb,
+  schema: Schema,
+  tableName: string,
+  rows: Record<string, unknown>[],
+  embeds: EmbedRequest[],
+  options: HandlerOptions,
+): Promise<Record<string, unknown>[]> {
+  const tableRelations = options.relations?.[tableName];
+  if (!tableRelations) return rows;
+
+  // Clone rows to avoid mutation
+  const result = rows.map(r => ({ ...r }));
+
+  for (const embed of embeds) {
+    const relationConfig = tableRelations[embed.name];
+    if (!relationConfig) continue;
+
+    const targetTable = schema[relationConfig.table];
+    if (!targetTable) continue;
+
+    const targetColumn = getColumn(targetTable, relationConfig.to);
+    if (!targetColumn) continue;
+
+    // Build soft-delete filter for the target table
+    const targetSdCol = isSoftDeleteTable(relationConfig.table, targetTable, options)
+      ? getSoftDeleteColumn(targetTable, options)
+      : null;
+
+    if (relationConfig.many) {
+      // One-to-many: source.from is the PK, target.to is the FK
+      // Collect all source PKs
+      const sourceValues = result
+        .map(r => r[relationConfig.from])
+        .filter(v => v != null);
+
+      if (sourceValues.length === 0) {
+        // No values to match — set empty arrays
+        for (const row of result) {
+          row[embed.name] = [];
+        }
+        continue;
+      }
+
+      // Fetch all related rows in one query
+      const embedConditions: any[] = [inArray(targetColumn, sourceValues as string[])];
+      if (targetSdCol) embedConditions.push(isNull(targetSdCol));
+
+      const relatedRows: Record<string, unknown>[] = await db
+        .select()
+        .from(targetTable)
+        .where(embedConditions.length === 1 ? embedConditions[0] : and(...embedConditions));
+
+      // Group by FK value and assign to each source row
+      for (const row of result) {
+        const sourceVal = row[relationConfig.from];
+        const matched = relatedRows.filter(r => r[relationConfig.to] === sourceVal);
+        row[embed.name] = embed.columns
+          ? matched.map(r => pickColumns(r, embed.columns!))
+          : matched;
+      }
+    } else {
+      // Many-to-one: source.from is the FK, target.to is the PK
+      // Collect all FK values
+      const fkValues = result
+        .map(r => r[relationConfig.from])
+        .filter(v => v != null);
+
+      if (fkValues.length === 0) {
+        // All FKs are null — set null
+        for (const row of result) {
+          row[embed.name] = null;
+        }
+        continue;
+      }
+
+      // Fetch all referenced rows in one query (batch, no N+1)
+      const embedConditions: any[] = [inArray(targetColumn, fkValues as string[])];
+      if (targetSdCol) embedConditions.push(isNull(targetSdCol));
+
+      const relatedRows: Record<string, unknown>[] = await db
+        .select()
+        .from(targetTable)
+        .where(embedConditions.length === 1 ? embedConditions[0] : and(...embedConditions));
+
+      // Index by target key for O(1) lookup
+      const index = new Map<unknown, Record<string, unknown>>();
+      for (const r of relatedRows) {
+        index.set(r[relationConfig.to], r);
+      }
+
+      // Assign to each source row
+      for (const row of result) {
+        const fkVal = row[relationConfig.from];
+        if (fkVal == null) {
+          row[embed.name] = null;
+        } else {
+          const related = index.get(fkVal) || null;
+          row[embed.name] = related && embed.columns ? pickColumns(related, embed.columns) : related;
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+function pickColumns(row: Record<string, unknown>, columns: string[]): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const col of columns) {
+    if (col in row) {
+      result[col] = row[col];
+    }
+  }
+  return result;
+}
+
+async function handlePost(
+  db: DrizzleDb,
+  table: DrizzleTable,
+  tableName: string,
+  request: Request,
+  options?: HandlerOptions,
+  user: Record<string, unknown> | null = null,
+  client: Record<string, unknown> | null = null,
+): Promise<Response> {
+  let body: Record<string, unknown>;
+  try {
+    body = await request.json();
+  } catch {
+    return json({ message: 'Invalid JSON body' }, 400);
+  }
+
+  // Map body keys to Drizzle property names when naming convention is active
+  if (options?.naming === 'snake_case') {
+    body = transformBodyKeys(body, table);
+  }
+
+  const hook = options?.hooks?.[tableName];
+
+  if (hook?.beforeCreate) {
+    try {
+      body = await hook.beforeCreate(body, user, client);
+    } catch {
+      return json({ message: 'Hook error' }, 500);
+    }
+  }
+
+  const rows = await db.insert(table).values(body).returning();
+
+  if (hook?.afterCreate && rows.length > 0) {
+    try { await hook.afterCreate(rows[0], user, client); } catch {}
+  }
+
+  return json(transformResponse(rows[0], options), 201);
+}
+
+async function handlePatch(
+  db: DrizzleDb,
+  table: DrizzleTable,
+  tableName: string,
+  request: Request,
+  params: URLSearchParams,
+  options?: HandlerOptions,
+  user: Record<string, unknown> | null = null,
+  client: Record<string, unknown> | null = null,
+): Promise<Response> {
+  let body: Record<string, unknown>;
+  try {
+    body = await request.json();
+  } catch {
+    return json({ message: 'Invalid JSON body' }, 400);
+  }
+
+  // Map body keys to Drizzle property names when naming convention is active
+  if (options?.naming === 'snake_case') {
+    body = transformBodyKeys(body, table);
+  }
+
+  const hook = options?.hooks?.[tableName];
+
+  if (hook?.beforeUpdate) {
+    try {
+      body = await hook.beforeUpdate(body, user, client);
+    } catch {
+      return json({ message: 'Hook error' }, 500);
+    }
+  }
+
+  const conditions = buildAllConditions(table, params);
+
+  // Soft-delete: exclude deleted records from updates
+  if (isSoftDeleteTable(tableName, table, options)) {
+    const sdCol = getSoftDeleteColumn(table, options);
+    if (sdCol) conditions.push(isNull(sdCol));
+  }
+
+  let query: any = db.update(table).set(body);
+
+  if (conditions.length === 1) {
+    query = query.where(conditions[0]);
+  } else if (conditions.length > 1) {
+    query = query.where(and(...conditions));
+  }
+
+  const rows = await query.returning();
+
+  if (hook?.afterUpdate && rows.length > 0) {
+    try { await hook.afterUpdate(rows, user, client); } catch {}
+  }
+
+  return json(transformResponse(rows, options), 200);
+}
+
+async function handleDelete(
+  db: DrizzleDb,
+  table: DrizzleTable,
+  tableName: string,
+  params: URLSearchParams,
+  options?: HandlerOptions,
+  user: Record<string, unknown> | null = null,
+  client: Record<string, unknown> | null = null,
+): Promise<Response> {
+  const filters = parseFilters(params);
+  const hasLogicalGroup = params.has('or') || params.has('and');
+
+  // Safety: require at least one filter to prevent accidental mass deletion
+  if (filters.length === 0 && !hasLogicalGroup) {
+    return json({ message: 'DELETE requires at least one filter to prevent accidental mass deletion' }, 400);
+  }
+
+  const hook = options?.hooks?.[tableName];
+
+  if (hook?.beforeDelete) {
+    try {
+      await hook.beforeDelete(user, client);
+    } catch {
+      return json({ message: 'Hook error' }, 500);
+    }
+  }
+
+  const conditions = buildAllConditions(table, params);
+
+  // Soft-delete: convert DELETE to UPDATE SET deleted_at = NOW()
+  if (isSoftDeleteTable(tableName, table, options)) {
+    const sdCol = getSoftDeleteColumn(table, options);
+    if (sdCol) {
+      // Only soft-delete records that aren't already deleted
+      conditions.push(isNull(sdCol));
+      const colName = options?.softDelete?.column || 'deletedAt';
+      let query: any = db.update(table).set({ [colName]: new Date() });
+
+      if (conditions.length === 1) {
+        query = query.where(conditions[0]);
+      } else {
+        query = query.where(and(...conditions));
+      }
+
+      const rows = await query.returning();
+
+      if (hook?.afterDelete && rows.length > 0) {
+        try { await hook.afterDelete(rows, user, client); } catch {}
+      }
+
+      return json(transformResponse(rows, options), 200);
+    }
+  }
+
+  // Hard delete (no soft-delete configured for this table)
+  let query: any = db.delete(table);
+
+  if (conditions.length === 1) {
+    query = query.where(conditions[0]);
+  } else {
+    query = query.where(and(...conditions));
+  }
+
+  const rows = await query.returning();
+
+  if (hook?.afterDelete && rows.length > 0) {
+    try { await hook.afterDelete(rows, user, client); } catch {}
+  }
+
+  return json(transformResponse(rows, options), 200);
+}
+
+interface JsonPath {
+  baseColumn: string;
+  steps: Array<{ key: string; asText: boolean }>;
+}
+
+interface Filter {
+  column: string;
+  operator: string;
+  value: string;
+  negated?: boolean;
+  jsonPath?: JsonPath;
+}
+
+function getColumn(table: DrizzleTable, columnName: string): DrizzleColumn | null {
+  // Drizzle tables store columns directly as properties
+  if (table[columnName]) return table[columnName];
+
+  // Try camelCase → snake_case lookup
+  const snakeCase = columnName.replace(/[A-Z]/g, c => `_${c.toLowerCase()}`);
+  if (table[snakeCase]) return table[snakeCase];
+
+  // Try snake_case → camelCase lookup (for Rails-origin databases)
+  if (columnName.includes('_')) {
+    const camelCase = toCamelCase(columnName);
+    if (table[camelCase]) return table[camelCase];
+  }
+
+  return null;
+}
+
+/**
+ * Parse a column name that may contain JSON path operators (-> and ->>).
+ * Returns null if the column has no JSON path operators.
+ *
+ * Examples:
+ *   "metadata->>theme"       → { baseColumn: "metadata", steps: [{ key: "theme", asText: true }] }
+ *   "data->settings->>mode"  → { baseColumn: "data", steps: [{ key: "settings", asText: false }, { key: "mode", asText: true }] }
+ *   "name"                   → null
+ */
+function parseJsonPath(column: string): JsonPath | null {
+  if (!column.includes('->')) return null;
+
+  const steps: Array<{ key: string; asText: boolean }> = [];
+  let remaining = column;
+
+  // Tokenize by splitting on arrow operators (->> and ->)
+  const parts: string[] = [];
+  const operators: boolean[] = []; // true = asText (->>), false = JSON (->)
+
+  while (remaining.length > 0) {
+    const textIdx = remaining.indexOf('->>');
+    const jsonIdx = remaining.indexOf('->');
+
+    if (jsonIdx === -1) {
+      // No more arrows
+      parts.push(remaining);
+      break;
+    }
+
+    if (textIdx === jsonIdx) {
+      // ->> found at same position as -> (because ->> starts with ->)
+      parts.push(remaining.substring(0, textIdx));
+      operators.push(true);
+      remaining = remaining.substring(textIdx + 3);
+    } else {
+      // -> found (not ->>)
+      parts.push(remaining.substring(0, jsonIdx));
+      operators.push(false);
+      remaining = remaining.substring(jsonIdx + 2);
+    }
+  }
+
+  if (parts.length < 2) return null;
+
+  const baseColumn = parts[0];
+  for (let i = 1; i < parts.length; i++) {
+    steps.push({ key: parts[i], asText: operators[i - 1] });
+  }
+
+  return { baseColumn, steps };
+}
+
+/**
+ * Build a SQL condition for a JSON path filter.
+ * Generates expressions like: "metadata"->>'theme' = 'dark'
+ */
+function buildJsonCondition(table: DrizzleTable, filter: Filter): any {
+  const jp = filter.jsonPath!;
+  const baseCol = getColumn(table, jp.baseColumn);
+  if (!baseCol) return null;
+
+  // Build the JSON path expression
+  let expr: any = sql`${baseCol}`;
+  for (const step of jp.steps) {
+    const arrow = step.asText ? sql.raw(`->>'${step.key}'`) : sql.raw(`->'${step.key}'`);
+    expr = sql`${expr}${arrow}`;
+  }
+
+  // Apply operator
+  let condition: any = null;
+
+  switch (filter.operator) {
+    case 'eq':
+      condition = sql`${expr} = ${filter.value}`;
+      break;
+    case 'neq':
+      condition = sql`${expr} != ${filter.value}`;
+      break;
+    case 'gt':
+      condition = sql`(${expr})::numeric > ${filter.value}::numeric`;
+      break;
+    case 'gte':
+      condition = sql`(${expr})::numeric >= ${filter.value}::numeric`;
+      break;
+    case 'lt':
+      condition = sql`(${expr})::numeric < ${filter.value}::numeric`;
+      break;
+    case 'lte':
+      condition = sql`(${expr})::numeric <= ${filter.value}::numeric`;
+      break;
+    case 'like':
+      condition = sql`${expr} LIKE ${filter.value.replace(/\*/g, '%')}`;
+      break;
+    case 'ilike':
+      condition = sql`${expr} ILIKE ${filter.value.replace(/\*/g, '%')}`;
+      break;
+    case 'is':
+      if (filter.value === 'null') condition = sql`${expr} IS NULL`;
+      else if (filter.value === 'not.null') condition = sql`${expr} IS NOT NULL`;
+      break;
+    case 'in': {
+      const values = filter.value.replace(/^\(/, '').replace(/\)$/, '').split(',');
+      const placeholders = values.map(v => sql`${v}`);
+      condition = sql`${expr} IN (${sql.join(placeholders, sql`, `)})`;
+      break;
+    }
+    default:
+      return null;
+  }
+
+  if (condition && filter.negated) {
+    if (filter.operator === 'is' && filter.value === 'null') {
+      return sql`${expr} IS NOT NULL`;
+    }
+    return sql`NOT (${condition})`;
+  }
+
+  return condition;
+}
+
+function buildCondition(table: DrizzleTable, filter: Filter): any {
+  if (filter.jsonPath) {
+    return buildJsonCondition(table, filter);
+  }
+
+  const column = getColumn(table, filter.column);
+  if (!column) return null;
+
+  let condition: any = null;
+
+  switch (filter.operator) {
+    case 'eq':
+      condition = eq(column, filter.value);
+      break;
+    case 'neq':
+      condition = ne(column, filter.value);
+      break;
+    case 'gt':
+      condition = gt(column, filter.value);
+      break;
+    case 'gte':
+      condition = gte(column, filter.value);
+      break;
+    case 'lt':
+      condition = lt(column, filter.value);
+      break;
+    case 'lte':
+      condition = lte(column, filter.value);
+      break;
+    case 'like':
+      // PostgREST uses * for wildcard, SQL uses %
+      condition = like(column, filter.value.replace(/\*/g, '%'));
+      break;
+    case 'ilike':
+      condition = ilike(column, filter.value.replace(/\*/g, '%'));
+      break;
+    case 'is':
+      if (filter.value === 'null') condition = isNull(column);
+      else if (filter.value === 'not.null') condition = isNotNull(column);
+      break;
+    case 'in': {
+      // PostgREST format: in.(val1,val2,val3)
+      const values = filter.value.replace(/^\(/, '').replace(/\)$/, '').split(',');
+      condition = inArray(column, values);
+      break;
+    }
+    default:
+      return null;
+  }
+
+  // Apply negation
+  if (condition && filter.negated) {
+    // Special case: not.is.null → isNotNull (cleaner SQL)
+    if (filter.operator === 'is' && filter.value === 'null') {
+      return isNotNull(column);
+    }
+    return not(condition);
+  }
+
+  return condition;
+}
+
+function buildOrderBy(table: DrizzleTable, orderParam: string): any {
+  // Format: column.direction (e.g., created_at.desc)
+  const dotIndex = orderParam.lastIndexOf('.');
+  if (dotIndex === -1) return null;
+
+  const columnName = orderParam.substring(0, dotIndex);
+  const direction = orderParam.substring(dotIndex + 1);
+
+  const column = getColumn(table, columnName);
+  if (!column) return null;
+
+  return direction === 'desc' ? desc(column) : asc(column);
+}
+
+function parseFilters(params: URLSearchParams): Filter[] {
+  const filters: Filter[] = [];
+  const reserved = new Set(['limit', 'offset', 'order', 'select', 'deleted', 'or', 'and']);
+
+  for (const [key, value] of params.entries()) {
+    if (reserved.has(key)) continue;
+
+    // Check for NOT modifier: not.eq.value → negated=true, operator=eq
+    let negated = false;
+    let remaining = value;
+    if (remaining.startsWith('not.')) {
+      negated = true;
+      remaining = remaining.slice(4);
+    }
+
+    // PostgREST format: column=operator.value
+    const dotIndex = remaining.indexOf('.');
+    if (dotIndex === -1) continue;
+
+    const operator = remaining.substring(0, dotIndex);
+    const filterValue = remaining.substring(dotIndex + 1);
+
+    const jsonPath = parseJsonPath(key);
+    filters.push({
+      column: jsonPath ? jsonPath.baseColumn : key,
+      operator,
+      value: filterValue,
+      negated,
+      ...(jsonPath ? { jsonPath } : {}),
+    });
+  }
+
+  return filters;
+}
+
+/**
+ * Parse a logical group value into individual filters.
+ * Input: "(status.eq.draft,status.eq.pending)" → [{column:'status', operator:'eq', value:'draft'}, ...]
+ */
+function parseLogicalGroup(value: string): Filter[] {
+  let content = value;
+  if (content.startsWith('(') && content.endsWith(')')) {
+    content = content.slice(1, -1);
+  }
+
+  const filters: Filter[] = [];
+  for (const part of content.split(',')) {
+    const dotIndex = part.indexOf('.');
+    if (dotIndex === -1) continue;
+
+    const column = part.substring(0, dotIndex);
+    const rest = part.substring(dotIndex + 1);
+
+    let negated = false;
+    let remaining = rest;
+    if (remaining.startsWith('not.')) {
+      negated = true;
+      remaining = remaining.slice(4);
+    }
+
+    const opDot = remaining.indexOf('.');
+    if (opDot === -1) continue;
+
+    const operator = remaining.substring(0, opDot);
+    const filterValue = remaining.substring(opDot + 1);
+    const jsonPath = parseJsonPath(column);
+    filters.push({
+      column: jsonPath ? jsonPath.baseColumn : column,
+      operator,
+      value: filterValue,
+      negated,
+      ...(jsonPath ? { jsonPath } : {}),
+    });
+  }
+  return filters;
+}
+
+/**
+ * Build all WHERE conditions from query params, including individual filters
+ * and or()/and() logical groups.
+ */
+function buildAllConditions(table: DrizzleTable, params: URLSearchParams): any[] {
+  const filters = parseFilters(params);
+  const conditions = filters.map(f => buildCondition(table, f)).filter(Boolean);
+
+  const orParam = params.get('or');
+  if (orParam) {
+    const orFilters = parseLogicalGroup(orParam);
+    const orConditions = orFilters.map(f => buildCondition(table, f)).filter(Boolean);
+    if (orConditions.length > 0) {
+      conditions.push(or(...orConditions));
+    }
+  }
+
+  const andParam = params.get('and');
+  if (andParam) {
+    const andFilters = parseLogicalGroup(andParam);
+    const andConditions = andFilters.map(f => buildCondition(table, f)).filter(Boolean);
+    if (andConditions.length > 0) {
+      conditions.push(and(...andConditions));
+    }
+  }
+
+  return conditions;
+}
+
+function json(data: unknown, status: number): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}