postgresdk 0.9.9 → 0.10.1

package/dist/cli.js

@@ -1170,6 +1170,187 @@ function generateUnifiedContractMarkdown(contract) {
       lines.push("");
     }
   }
+  lines.push("## Filtering with WHERE Clauses");
+  lines.push("");
+  lines.push("The SDK provides type-safe WHERE clause filtering with support for various operators.");
+  lines.push("");
+  lines.push("### Basic Filtering");
+  lines.push("");
+  lines.push("**Direct equality:**");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("// Find users with specific email");
+  lines.push("const users = await sdk.users.list({");
+  lines.push("  where: { email: 'user@example.com' }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// Multiple conditions (AND)");
+  lines.push("const activeUsers = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    status: 'active',");
+  lines.push("    role: 'admin'");
+  lines.push("  }");
+  lines.push("});");
+  lines.push("```");
+  lines.push("");
+  lines.push("### Comparison Operators");
+  lines.push("");
+  lines.push("Use comparison operators for numeric, date, and other comparable fields:");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("// Greater than / Less than");
+  lines.push("const adults = await sdk.users.list({");
+  lines.push("  where: { age: { $gt: 18 } }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// Range queries");
+  lines.push("const workingAge = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    age: { $gte: 18, $lte: 65 }");
+  lines.push("  }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// Not equal");
+  lines.push("const notPending = await sdk.orders.list({");
+  lines.push("  where: { status: { $ne: 'pending' } }");
+  lines.push("});");
+  lines.push("```");
+  lines.push("");
+  lines.push("### String Operators");
+  lines.push("");
+  lines.push("Pattern matching for string fields:");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("// Case-sensitive LIKE");
+  lines.push("const johnsmiths = await sdk.users.list({");
+  lines.push("  where: { name: { $like: '%Smith%' } }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// Case-insensitive ILIKE");
+  lines.push("const gmailUsers = await sdk.users.list({");
+  lines.push("  where: { email: { $ilike: '%@gmail.com' } }");
+  lines.push("});");
+  lines.push("```");
+  lines.push("");
+  lines.push("### Array Operators");
+  lines.push("");
+  lines.push("Filter by multiple possible values:");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("// IN - match any value in array");
+  lines.push("const specificUsers = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    id: { $in: ['id1', 'id2', 'id3'] }");
+  lines.push("  }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// NOT IN - exclude values");
+  lines.push("const nonSystemUsers = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    role: { $nin: ['admin', 'system'] }");
+  lines.push("  }");
+  lines.push("});");
+  lines.push("```");
+  lines.push("");
+  lines.push("### NULL Checks");
+  lines.push("");
+  lines.push("Check for null or non-null values:");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("// IS NULL");
+  lines.push("const activeRecords = await sdk.records.list({");
+  lines.push("  where: { deleted_at: { $is: null } }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// IS NOT NULL");
+  lines.push("const deletedRecords = await sdk.records.list({");
+  lines.push("  where: { deleted_at: { $isNot: null } }");
+  lines.push("});");
+  lines.push("```");
+  lines.push("");
+  lines.push("### Combining Operators");
+  lines.push("");
+  lines.push("Mix multiple operators for complex queries:");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("const filteredUsers = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    age: { $gte: 18, $lt: 65 },");
+  lines.push("    email: { $ilike: '%@company.com' },");
+  lines.push("    status: { $in: ['active', 'pending'] },");
+  lines.push("    deleted_at: { $is: null }");
+  lines.push("  },");
+  lines.push("  limit: 50,");
+  lines.push("  offset: 0");
+  lines.push("});");
+  lines.push("```");
+  lines.push("");
+  lines.push("### Available Operators");
+  lines.push("");
+  lines.push("| Operator | Description | Example | Types |");
+  lines.push("|----------|-------------|---------|-------|");
+  lines.push("| `$eq` | Equal to | `{ age: { $eq: 25 } }` | All |");
+  lines.push("| `$ne` | Not equal to | `{ status: { $ne: 'inactive' } }` | All |");
+  lines.push("| `$gt` | Greater than | `{ price: { $gt: 100 } }` | Number, Date |");
+  lines.push("| `$gte` | Greater than or equal | `{ age: { $gte: 18 } }` | Number, Date |");
+  lines.push("| `$lt` | Less than | `{ quantity: { $lt: 10 } }` | Number, Date |");
+  lines.push("| `$lte` | Less than or equal | `{ age: { $lte: 65 } }` | Number, Date |");
+  lines.push("| `$in` | In array | `{ id: { $in: ['a', 'b'] } }` | All |");
+  lines.push("| `$nin` | Not in array | `{ role: { $nin: ['admin'] } }` | All |");
+  lines.push("| `$like` | Pattern match (case-sensitive) | `{ name: { $like: '%John%' } }` | String |");
+  lines.push("| `$ilike` | Pattern match (case-insensitive) | `{ email: { $ilike: '%@GMAIL%' } }` | String |");
+  lines.push("| `$is` | IS NULL | `{ deleted_at: { $is: null } }` | Nullable fields |");
+  lines.push("| `$isNot` | IS NOT NULL | `{ created_by: { $isNot: null } }` | Nullable fields |");
+  lines.push("");
+  lines.push("### Logical Operators");
+  lines.push("");
+  lines.push("Combine conditions using `$or` and `$and` (supports 2 levels of nesting):");
+  lines.push("");
+  lines.push("| Operator | Description | Example |");
+  lines.push("|----------|-------------|---------|");
+  lines.push("| `$or` | Match any condition | `{ $or: [{ status: 'active' }, { role: 'admin' }] }` |");
+  lines.push("| `$and` | Match all conditions (explicit) | `{ $and: [{ age: { $gte: 18 } }, { status: 'verified' }] }` |");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("// OR - match any condition");
+  lines.push("const results = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    $or: [");
+  lines.push("      { email: { $ilike: '%@gmail.com' } },");
+  lines.push("      { status: 'premium' }");
+  lines.push("    ]");
+  lines.push("  }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// Mixed AND + OR (implicit AND at root level)");
+  lines.push("const complex = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    status: 'active',  // AND");
+  lines.push("    $or: [");
+  lines.push("      { age: { $lt: 18 } },");
+  lines.push("      { age: { $gt: 65 } }");
+  lines.push("    ]");
+  lines.push("  }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// Nested (2 levels max)");
+  lines.push("const nested = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    $and: [");
+  lines.push("      {");
+  lines.push("        $or: [");
+  lines.push("          { firstName: { $ilike: '%john%' } },");
+  lines.push("          { lastName: { $ilike: '%john%' } }");
+  lines.push("        ]");
+  lines.push("      },");
+  lines.push("      { status: 'active' }");
+  lines.push("    ]");
+  lines.push("  }");
+  lines.push("});");
+  lines.push("```");
+  lines.push("");
+  lines.push("**Note:** The WHERE clause types are fully type-safe. TypeScript will only allow operators that are valid for each field type.");
+  lines.push("");
   lines.push("## Resources");
   lines.push("");
   for (const resource of contract.resources) {
@@ -1826,115 +2007,131 @@ async function initCommand(args) {
 }
 var CONFIG_TEMPLATE = `/**
  * PostgreSDK Configuration
- * 
- * This file configures how postgresdk generates your SDK.
+ *
+ * This file configures how postgresdk generates your type-safe API and SDK
+ * from your PostgreSQL database schema.
+ *
+ * QUICK START:
+ *   1. Update the connectionString below
+ *   2. Run: postgresdk generate
+ *   3. Start using your generated SDK!
+ *
+ * CLI COMMANDS:
+ *   postgresdk init              Initialize this config file
+ *   postgresdk generate          Generate API and SDK from your database
+ *   postgresdk pull              Pull SDK from a remote API
+ *   postgresdk help              Show help and examples
+ *
  * Environment variables are automatically loaded from .env files.
  */
 
 export default {
   // ========== DATABASE CONNECTION (Required) ==========
-  
+
   /**
    * PostgreSQL connection string
    * Format: postgres://user:password@host:port/database
+   *
+   * Tip: Use environment variables to keep credentials secure
    */
   connectionString: process.env.DATABASE_URL || "postgres://user:password@localhost:5432/mydb",
-  
+
   // ========== BASIC OPTIONS ==========
-  
+
   /**
    * Database schema to introspect
-   * @default "public"
+   * Default: "public"
    */
   // schema: "public",
-  
+
   /**
    * Output directory for server-side code (routes, validators, etc.)
-   * @default "./api/server"
+   * Default: "./api/server"
    */
   // outServer: "./api/server",
-  
+
   /**
    * Output directory for client SDK
-   * @default "./api/client"
+   * Default: "./api/client"
    */
   // outClient: "./api/client",
-  
+
   // ========== ADVANCED OPTIONS ==========
-  
+
   /**
    * Column name for soft deletes. When set, DELETE operations will update
    * this column instead of removing rows.
-   * @default null (hard deletes)
-   * @example "deleted_at"
+   *
+   * Default: null (hard deletes)
+   * Example: "deleted_at"
    */
   // softDeleteColumn: null,
-  
+
   /**
    * Maximum depth for nested relationship includes to prevent infinite loops
-   * @default 2
+   * Default: 2
    */
   // includeMethodsDepth: 2,
-  
-  
+
+
   /**
    * Server framework for generated API routes
-   * - "hono": Lightweight, edge-compatible web framework (default)
-   * - "express": Traditional Node.js framework (planned)
-   * - "fastify": High-performance Node.js framework (planned)
-   * @default "hono"
+   * Options:
+   *   - "hono": Lightweight, edge-compatible web framework (default)
+   *   - "express": Traditional Node.js framework (planned)
+   *   - "fastify": High-performance Node.js framework (planned)
+   *
+   * Default: "hono"
    */
   // serverFramework: "hono",
-  
+
   /**
    * Use .js extensions in server imports (for Vercel Edge, Deno, etc.)
-   * @default false
+   * Default: false
    */
   // useJsExtensions: false,
-  
+
   /**
    * Use .js extensions in client SDK imports (rarely needed)
-   * @default false
+   * Default: false
    */
   // useJsExtensionsClient: false,
-  
+
   // ========== TEST GENERATION ==========
-  
+
   /**
-   * Generate basic SDK tests
-   * Uncomment to enable test generation with Docker setup
+   * Generate basic SDK tests with Docker setup
+   * Uncomment to enable test generation
    */
   // tests: {
   //   generate: true,
   //   output: "./api/tests",
   //   framework: "vitest"  // or "jest" or "bun"
   // },
-  
+
   // ========== AUTHENTICATION ==========
-  
+
   /**
    * Authentication configuration for your API
-   * 
-   * Simple syntax examples:
+   *
+   * SIMPLE SYNTAX (recommended):
    *   auth: { apiKey: process.env.API_KEY }
    *   auth: { jwt: process.env.JWT_SECRET }
-   * 
-   * Multiple API keys:
    *   auth: { apiKeys: [process.env.KEY1, process.env.KEY2] }
-   * 
-   * Full syntax for advanced options:
+   *
+   * FULL SYNTAX (advanced):
    */
   // auth: {
   //   // Strategy: "none" | "api-key" | "jwt-hs256"
   //   strategy: "none",
-  //   
+  //
   //   // For API Key authentication
   //   apiKeyHeader: "x-api-key",  // Header name for API key
   //   apiKeys: [                  // List of valid API keys
   //     process.env.API_KEY_1,
   //     process.env.API_KEY_2,
   //   ],
-  //   
+  //
   //   // For JWT (HS256) authentication
   //   jwt: {
   //     sharedSecret: process.env.JWT_SECRET,  // Secret for signing/verifying
@@ -1942,12 +2139,12 @@ export default {
   //     audience: "my-users",                  // Optional: validate 'aud' claim
   //   }
   // },
-  
+
   // ========== SDK DISTRIBUTION (Pull Configuration) ==========
-  
+
   /**
    * Configuration for pulling SDK from a remote API
-   * Used when running 'postgresdk pull' command
+   * Used when running: postgresdk pull
    */
   // pull: {
   //   from: "https://api.myapp.com",     // API URL to pull SDK from
@@ -2237,7 +2434,14 @@ function buildGraph(model) {
 
 // src/emit-include-spec.ts
 function emitIncludeSpec(graph) {
-  let out = `/* Generated. Do not edit. */
+  let out = `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 `;
   const tables = Object.keys(graph);
   for (const table of tables) {
@@ -2266,7 +2470,14 @@ function toPascal(s) {
 
 // src/emit-include-builder.ts
 function emitIncludeBuilder(graph, maxDepth) {
-  return `// Generated. Do not edit.
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 export const RELATION_GRAPH = ${JSON.stringify(graph, null, 2)} as const;
 type TableName = keyof typeof RELATION_GRAPH;
 
@@ -2414,7 +2625,14 @@ function emitHonoRoutes(table, _graph, opts) {
   const hasAuth = opts.authStrategy && opts.authStrategy !== "none";
   const ext = opts.useJsExtensions ? ".js" : "";
   const authImport = hasAuth ? `import { authMiddleware } from "../auth${ext}";` : "";
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 import { Hono } from "hono";
 import { z } from "zod";
 import { Insert${Type}Schema, Update${Type}Schema } from "../zod/${fileTableName}${ext}";
@@ -2594,7 +2812,7 @@ function emitClient(table, graph, opts, model) {
   let includeMethodsCode = "";
   for (const method of includeMethods) {
     const isGetByPk = method.name.startsWith("getByPk");
-    const baseParams = isGetByPk ? "" : `params?: Omit<{ limit?: number; offset?: number; where?: any; orderBy?: string; order?: "asc" | "desc"; }, "include">`;
+    const baseParams = isGetByPk ? "" : `params?: Omit<{ limit?: number; offset?: number; where?: Where<Select${Type}>; orderBy?: string; order?: "asc" | "desc"; }, "include">`;
     if (isGetByPk) {
       const pkWhere = hasCompositePk ? `{ ${safePk.map((col) => `${col}: pk.${col}`).join(", ")} }` : `{ ${safePk[0] || "id"}: pk }`;
       const baseReturnType = method.returnType.replace(" | null", "");
@@ -2616,8 +2834,16 @@ function emitClient(table, graph, opts, model) {
 `;
     }
   }
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 import { BaseClient } from "./base-client${ext}";
+import type { Where } from "./where-types${ext}";
 ${typeImports}
 ${otherTableImports.join(`
 `)}
@@ -2637,10 +2863,11 @@ export class ${Type}Client extends BaseClient {
     return this.get<Select${Type} | null>(\`\${this.resource}/\${path}\`);
   }
 
-  async list(params?: { 
-    limit?: number; 
+  async list(params?: {
+    include?: any;
+    limit?: number;
     offset?: number;
-    where?: any;
+    where?: Where<Select${Type}>;
     orderBy?: string;
     order?: "asc" | "desc";
   }): Promise<Select${Type}[]> {
@@ -2661,7 +2888,14 @@ ${includeMethodsCode}}
 }
 function emitClientIndex(tables, useJsExtensions) {
   const ext = useJsExtensions ? ".js" : "";
-  let out = `/* Generated. Do not edit. */
+  let out = `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 `;
   out += `import { BaseClient, type AuthConfig } from "./base-client${ext}";
 `;
@@ -2702,6 +2936,17 @@ export type { AuthConfig, HeaderMap, AuthHeadersProvider } from "./base-client${
   out += `export { BaseClient } from "./base-client${ext}";
 `;
   out += `
+// Include specification types for custom queries
+`;
+  out += `export type {
+`;
+  for (const t of tables) {
+    out += `  ${pascal(t.name)}IncludeSpec,
+`;
+  }
+  out += `} from "./include-spec${ext}";
+`;
+  out += `
 // Zod schemas for form validation
 `;
   for (const t of tables) {
@@ -2723,7 +2968,14 @@ export type { AuthConfig, HeaderMap, AuthHeadersProvider } from "./base-client${
 
 // src/emit-base-client.ts
 function emitBaseClient() {
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 
 export type HeaderMap = Record<string, string>;
 export type AuthHeadersProvider = () => Promise<HeaderMap> | HeaderMap;
@@ -2870,7 +3122,14 @@ function emitIncludeLoader(graph, model, maxDepth, useJsExtensions) {
     fkIndex[t.name] = t.fks.map((f) => ({ from: f.from, toTable: f.toTable, to: f.to }));
   }
   const ext = useJsExtensions ? ".js" : "";
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 import { RELATION_GRAPH } from "./include-builder${ext}";
 
 // Minimal types to keep the file self-contained
@@ -3191,7 +3450,14 @@ function emitTypes(table, opts) {
     return `  ${col.name}: ${valueType};`;
   }).join(`
 `);
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 export type Insert${Type} = {
 ${insertFields}
 };
@@ -3206,7 +3472,14 @@ ${selectFields}
 
 // src/emit-logger.ts
 function emitLogger() {
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 const DEBUG = process.env.SDK_DEBUG === "1" || process.env.SDK_DEBUG === "true";
 
 export const logger = {
@@ -3239,6 +3512,76 @@ export function safe<T extends (c: any) => any>(handler: T) {
 `;
 }
 
+// src/emit-where-types.ts
+function emitWhereTypes() {
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
+
+/**
+ * WHERE clause operators for filtering
+ */
+export type WhereOperator<T> = {
+  /** Equal to */
+  $eq?: T;
+  /** Not equal to */
+  $ne?: T;
+  /** Greater than */
+  $gt?: T;
+  /** Greater than or equal to */
+  $gte?: T;
+  /** Less than */
+  $lt?: T;
+  /** Less than or equal to */
+  $lte?: T;
+  /** In array */
+  $in?: T[];
+  /** Not in array */
+  $nin?: T[];
+  /** LIKE pattern match (strings only) */
+  $like?: T extends string ? string : never;
+  /** Case-insensitive LIKE (strings only) */
+  $ilike?: T extends string ? string : never;
+  /** IS NULL */
+  $is?: null;
+  /** IS NOT NULL */
+  $isNot?: null;
+};
+
+/**
+ * WHERE condition - can be a direct value or an operator object
+ */
+export type WhereCondition<T> = T | WhereOperator<T>;
+
+/**
+ * Field-level WHERE conditions (without logical operators)
+ */
+export type WhereFieldConditions<T> = {
+  [K in keyof T]?: WhereCondition<T[K]>;
+};
+
+/**
+ * WHERE clause type with support for $or/$and logical operators (2 levels max)
+ *
+ * Examples:
+ * - Basic OR: { $or: [{ name: 'Alice' }, { name: 'Bob' }] }
+ * - Mixed AND + OR: { status: 'active', $or: [{ age: { $gt: 65 } }, { age: { $lt: 18 } }] }
+ * - Nested (2 levels): { $and: [{ $or: [{ name: 'Alice' }, { name: 'Bob' }] }, { status: 'active' }] }
+ */
+export type Where<T> = WhereFieldConditions<T> & {
+  /** OR - at least one condition must be true */
+  $or?: (WhereFieldConditions<T>)[];
+  /** AND - all conditions must be true (alternative to implicit root-level AND) */
+  $and?: (WhereFieldConditions<T> | { $or?: WhereFieldConditions<T>[] })[];
+};
+`;
+}
+
 // src/emit-auth.ts
 function emitAuth(cfgAuth) {
   const strategy = cfgAuth?.strategy ?? "none";
@@ -3253,7 +3596,14 @@ function emitAuth(cfgAuth) {
   const JWT_SHARED_SECRET = JSON.stringify(jwtShared);
   const JWT_ISSUER = jwtIssuer === undefined ? "undefined" : JSON.stringify(jwtIssuer);
   const JWT_AUDIENCE = jwtAudience === undefined ? "undefined" : JSON.stringify(jwtAudience);
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 import type { Context, Next } from "hono";
 
 // ---- Config inlined by generator ----
@@ -3410,7 +3760,14 @@ function emitHonoRouter(tables, hasAuth, useJsExtensions) {
     return `export { register${Type}Routes } from "./routes/${name}${ext}";`;
   }).join(`
 `);
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 import { Hono } from "hono";
 import { SDK_MANIFEST } from "./sdk-bundle${ext}";
 import { getContract } from "./contract${ext}";
@@ -3544,7 +3901,14 @@ function emitSdkBundle(clientFiles, clientDir) {
   }
   const version = `1.0.0`;
   const generated = new Date().toISOString();
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 
 export const SDK_MANIFEST = {
   version: "${version}",
@@ -3648,6 +4012,155 @@ export async function getByPk(
   }
 }
 
+/**
+ * Build WHERE clause recursively, supporting $or/$and operators
+ * Returns { sql: string, params: any[], nextParamIndex: number }
+ */
+function buildWhereClause(
+  whereClause: any,
+  startParamIndex: number
+): { sql: string; params: any[]; nextParamIndex: number } {
+  const whereParts: string[] = [];
+  const whereParams: any[] = [];
+  let paramIndex = startParamIndex;
+
+  if (!whereClause || typeof whereClause !== 'object') {
+    return { sql: '', params: [], nextParamIndex: paramIndex };
+  }
+
+  // Separate logical operators from field conditions
+  const { $or, $and, ...fieldConditions } = whereClause;
+
+  // Process field-level conditions
+  for (const [key, value] of Object.entries(fieldConditions)) {
+    if (value === undefined) {
+      continue;
+    }
+
+    // Handle operator objects like { $gt: 5, $like: "%test%" }
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      for (const [op, opValue] of Object.entries(value)) {
+        if (opValue === undefined) continue;
+
+        switch (op) {
+          case '$eq':
+            whereParts.push(\`"\${key}" = $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$ne':
+            whereParts.push(\`"\${key}" != $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$gt':
+            whereParts.push(\`"\${key}" > $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$gte':
+            whereParts.push(\`"\${key}" >= $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$lt':
+            whereParts.push(\`"\${key}" < $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$lte':
+            whereParts.push(\`"\${key}" <= $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$in':
+            if (Array.isArray(opValue) && opValue.length > 0) {
+              whereParts.push(\`"\${key}" = ANY($\${paramIndex})\`);
+              whereParams.push(opValue);
+              paramIndex++;
+            }
+            break;
+          case '$nin':
+            if (Array.isArray(opValue) && opValue.length > 0) {
+              whereParts.push(\`"\${key}" != ALL($\${paramIndex})\`);
+              whereParams.push(opValue);
+              paramIndex++;
+            }
+            break;
+          case '$like':
+            whereParts.push(\`"\${key}" LIKE $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$ilike':
+            whereParts.push(\`"\${key}" ILIKE $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$is':
+            if (opValue === null) {
+              whereParts.push(\`"\${key}" IS NULL\`);
+            }
+            break;
+          case '$isNot':
+            if (opValue === null) {
+              whereParts.push(\`"\${key}" IS NOT NULL\`);
+            }
+            break;
+        }
+      }
+    } else if (value === null) {
+      // Direct null value
+      whereParts.push(\`"\${key}" IS NULL\`);
+    } else {
+      // Direct value (simple equality)
+      whereParts.push(\`"\${key}" = $\${paramIndex}\`);
+      whereParams.push(value);
+      paramIndex++;
+    }
+  }
+
+  // Handle $or operator
+  if ($or && Array.isArray($or)) {
+    if ($or.length === 0) {
+      // Empty OR is logically FALSE - matches nothing
+      whereParts.push('FALSE');
+    } else {
+      const orParts: string[] = [];
+      for (const orCondition of $or) {
+        const result = buildWhereClause(orCondition, paramIndex);
+        if (result.sql) {
+          orParts.push(result.sql);
+          whereParams.push(...result.params);
+          paramIndex = result.nextParamIndex;
+        }
+      }
+      if (orParts.length > 0) {
+        whereParts.push(\`(\${orParts.join(' OR ')})\`);
+      }
+    }
+  }
+
+  // Handle $and operator
+  if ($and && Array.isArray($and) && $and.length > 0) {
+    const andParts: string[] = [];
+    for (const andCondition of $and) {
+      const result = buildWhereClause(andCondition, paramIndex);
+      if (result.sql) {
+        andParts.push(result.sql);
+        whereParams.push(...result.params);
+        paramIndex = result.nextParamIndex;
+      }
+    }
+    if (andParts.length > 0) {
+      whereParts.push(\`(\${andParts.join(' AND ')})\`);
+    }
+  }
+
+  const sql = whereParts.join(' AND ');
+  return { sql, params: whereParams, nextParamIndex: paramIndex };
+}
+
 /**
  * LIST operation - Get multiple records with optional filters
  */
@@ -3657,60 +4170,54 @@ export async function listRecords(
 ): Promise<{ data?: any; error?: string; issues?: any; needsIncludes?: boolean; includeSpec?: any; status: number }> {
   try {
     const { where: whereClause, limit = 50, offset = 0, include } = params;
-    
+
     // Build WHERE clause
-    const whereParts: string[] = [];
-    const whereParams: any[] = [];
     let paramIndex = 1;
-    
+    const whereParts: string[] = [];
+    let whereParams: any[] = [];
+
     // Add soft delete filter if applicable
     if (ctx.softDeleteColumn) {
       whereParts.push(\`"\${ctx.softDeleteColumn}" IS NULL\`);
     }
-    
+
     // Add user-provided where conditions
-    if (whereClause && typeof whereClause === 'object') {
-      for (const [key, value] of Object.entries(whereClause)) {
-        if (value === null) {
-          whereParts.push(\`"\${key}" IS NULL\`);
-        } else if (value === undefined) {
-          // Skip undefined values
-          continue;
-        } else {
-          whereParts.push(\`"\${key}" = $\${paramIndex}\`);
-          whereParams.push(value);
-          paramIndex++;
-        }
+    if (whereClause) {
+      const result = buildWhereClause(whereClause, paramIndex);
+      if (result.sql) {
+        whereParts.push(result.sql);
+        whereParams = result.params;
+        paramIndex = result.nextParamIndex;
       }
     }
-    
+
     const whereSQL = whereParts.length > 0 ? \`WHERE \${whereParts.join(" AND ")}\` : "";
-    
+
     // Add limit and offset params
     const limitParam = \`$\${paramIndex}\`;
     const offsetParam = \`$\${paramIndex + 1}\`;
     const allParams = [...whereParams, limit, offset];
-    
+
     const text = \`SELECT * FROM "\${ctx.table}" \${whereSQL} LIMIT \${limitParam} OFFSET \${offsetParam}\`;
     log.debug(\`LIST \${ctx.table} SQL:\`, text, "params:", allParams);
-    
+
     const { rows } = await ctx.pg.query(text, allParams);
-    
+
     if (!include) {
       log.debug(\`LIST \${ctx.table} rows:\`, rows.length);
       return { data: rows, status: 200 };
     }
-    
+
     // Include logic will be handled by the include-loader
     // For now, just return the rows with a note that includes need to be applied
     log.debug(\`LIST \${ctx.table} include spec:\`, include);
     return { data: rows, needsIncludes: true, includeSpec: include, status: 200 };
   } catch (e: any) {
     log.error(\`LIST \${ctx.table} error:\`, e?.stack ?? e);
-    return { 
-      error: e?.message ?? "Internal error", 
+    return {
+      error: e?.message ?? "Internal error",
       ...(DEBUG ? { stack: e?.stack } : {}),
-      status: 500 
+      status: 500
     };
   }
 }
@@ -4612,6 +5119,7 @@ async function generate(configPath) {
   files.push({ path: join(clientDir, "include-spec.ts"), content: includeSpec });
   files.push({ path: join(clientDir, "params", "shared.ts"), content: emitSharedParamsZod() });
   files.push({ path: join(clientDir, "base-client.ts"), content: emitBaseClient() });
+  files.push({ path: join(clientDir, "where-types.ts"), content: emitWhereTypes() });
   files.push({
     path: join(serverDir, "include-builder.ts"),
     content: emitIncludeBuilder(graph, cfg.includeMethodsDepth || 2)