postgresdk 0.10.0 → 0.10.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 postgresdk contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -178,9 +178,46 @@ const filtered = await sdk.users.list({
     deleted_at: { $is: null }              // NULL checks
   }
 });
+
+// OR logic - match any condition
+const results = await sdk.users.list({
+  where: {
+    $or: [
+      { email: { $ilike: '%@gmail.com' } },
+      { email: { $ilike: '%@yahoo.com' } },
+      { status: 'premium' }
+    ]
+  }
+});
+
+// Complex queries with AND/OR
+const complex = await sdk.users.list({
+  where: {
+    status: 'active',  // Implicit AND at root level
+    $or: [
+      { age: { $lt: 18 } },
+      { age: { $gt: 65 } }
+    ]
+  }
+});
+
+// Nested logic (2 levels)
+const nested = await sdk.users.list({
+  where: {
+    $and: [
+      {
+        $or: [
+          { firstName: { $ilike: '%john%' } },
+          { lastName: { $ilike: '%john%' } }
+        ]
+      },
+      { status: 'active' }
+    ]
+  }
+});
 ```
 
-See the generated SDK documentation for all available operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$like`, `$ilike`, `$is`, `$isNot`.
+See the generated SDK documentation for all available operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$like`, `$ilike`, `$is`, `$isNot`, `$or`, `$and`.
 
 ## Authentication
 

package/dist/cli.js

@@ -1302,6 +1302,53 @@ function generateUnifiedContractMarkdown(contract) {
   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");
@@ -2387,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) {
@@ -2416,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;
 
@@ -2564,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}";
@@ -2766,7 +2834,14 @@ 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}
@@ -2813,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}";
 `;
@@ -2886,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;
@@ -3033,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
@@ -3354,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}
 };
@@ -3369,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 = {
@@ -3404,7 +3514,14 @@ export function safe<T extends (c: any) => any>(handler: T) {
 
 // src/emit-where-types.ts
 function emitWhereTypes() {
-  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.
+ */
 
 /**
  * WHERE clause operators for filtering
@@ -3442,11 +3559,26 @@ export type WhereOperator<T> = {
 export type WhereCondition<T> = T | WhereOperator<T>;
 
 /**
- * WHERE clause type for a given table type
+ * Field-level WHERE conditions (without logical operators)
  */
-export type Where<T> = {
+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>[] })[];
+};
 `;
 }
 
@@ -3464,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 ----
@@ -3621,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}";
@@ -3755,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}",
@@ -3859,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
  */
@@ -3868,136 +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 === undefined) {
-          // Skip undefined values
-          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++;
-        }
+    // Add user-provided where conditions
+    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
     };
   }
 }

package/dist/index.js

@@ -1301,6 +1301,53 @@ function generateUnifiedContractMarkdown(contract) {
   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");
@@ -1627,7 +1674,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) {
@@ -1656,7 +1710,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;
 
@@ -1804,7 +1865,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}";
@@ -2006,7 +2074,14 @@ 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}
@@ -2053,7 +2128,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}";
 `;
@@ -2126,7 +2208,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;
@@ -2273,7 +2362,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
@@ -2594,7 +2690,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}
 };
@@ -2609,7 +2712,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 = {
@@ -2644,7 +2754,14 @@ export function safe<T extends (c: any) => any>(handler: T) {
 
 // src/emit-where-types.ts
 function emitWhereTypes() {
-  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.
+ */
 
 /**
  * WHERE clause operators for filtering
@@ -2682,11 +2799,26 @@ export type WhereOperator<T> = {
 export type WhereCondition<T> = T | WhereOperator<T>;
 
 /**
- * WHERE clause type for a given table type
+ * Field-level WHERE conditions (without logical operators)
  */
-export type Where<T> = {
+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>[] })[];
+};
 `;
 }
 
@@ -2704,7 +2836,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 ----
@@ -2861,7 +3000,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}";
@@ -2995,7 +3141,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}",
@@ -3099,6 +3252,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
  */
@@ -3108,136 +3410,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 === undefined) {
-          // Skip undefined values
-          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++;
-        }
+    // Add user-provided where conditions
+    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
     };
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresdk",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Generate a typed server/client SDK from a Postgres schema (includes, Zod, Hono).",
   "type": "module",
   "bin": {
@@ -22,7 +22,7 @@
   },
   "scripts": {
     "build": "bun build src/cli.ts src/index.ts --outdir dist --target node --format esm --external=pg --external=zod --external=hono --external=prompts --external=node:* && tsc -p tsconfig.build.json --emitDeclarationOnly",
-    "test": "bun test:init && bun test:gen && bun test test/test-where-clause.test.ts && bun test:gen-with-tests && bun test:pull && bun test:typecheck && bun test:drizzle-e2e",
+    "test": "bun test:init && bun test:gen && bun test test/test-where-clause.test.ts && bun test test/test-where-or-and.test.ts && bun test:gen-with-tests && bun test:pull && bun test:typecheck && bun test:drizzle-e2e",
     "test:init": "bun test/test-init.ts",
     "test:gen": "bun test/test-gen.ts",
     "test:gen-with-tests": "bun test/test-gen-with-tests.ts",
@@ -53,7 +53,16 @@
     "typescript": "^5.5.0",
     "vitest": "^3.2.4"
   },
+  "author": "Ben Honda <ben@theadpharm.com>",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adpharm/postgresdk.git"
+  },
+  "homepage": "https://github.com/adpharm/postgresdk#readme",
+  "bugs": {
+    "url": "https://github.com/adpharm/postgresdk/issues"
+  },
   "keywords": [
     "postgres",
     "sdk",