postgresdk 0.6.5 → 0.6.7

package/dist/index.js

@@ -1736,6 +1736,7 @@ function emitHonoRouter(tables, hasAuth, useJsExtensions) {
   return `/* Generated. Do not edit. */
 import { Hono } from "hono";
 import { SDK_MANIFEST } from "./sdk-bundle${ext}";
+import { getApiContract } from "./api-contract${ext}";
 ${imports}
 ${hasAuth ? `export { authMiddleware } from "./auth${ext}";` : ""}
 
@@ -1797,6 +1798,29 @@ ${registrations}
     });
   });
   
+  // API Contract endpoints - describes the entire API
+  router.get("/api/contract", (c) => {
+    const format = c.req.query("format") || "json";
+    
+    if (format === "markdown") {
+      return c.text(getApiContract("markdown") as string, 200, {
+        "Content-Type": "text/markdown; charset=utf-8"
+      });
+    }
+    
+    return c.json(getApiContract("json"));
+  });
+  
+  router.get("/api/contract.json", (c) => {
+    return c.json(getApiContract("json"));
+  });
+  
+  router.get("/api/contract.md", (c) => {
+    return c.text(getApiContract("markdown") as string, 200, {
+      "Content-Type": "text/markdown; charset=utf-8"
+    });
+  });
+  
   return router;
 }
 
@@ -2074,35 +2098,44 @@ function emitTableTest(table, clientPath, framework = "vitest") {
   const Type = pascal(table.name);
   const tableName = table.name;
   const imports = getFrameworkImports(framework);
-  const sampleData = generateSampleData(table);
-  const updateData = generateUpdateData(table);
+  const hasForeignKeys = table.fks.length > 0;
+  const foreignKeySetup = hasForeignKeys ? generateForeignKeySetup(table, clientPath) : null;
+  const sampleData = generateSampleDataFromSchema(table, hasForeignKeys);
+  const updateData = generateUpdateDataFromSchema(table);
   return `${imports}
 import { SDK } from '${clientPath}';
 import type { Insert${Type}, Update${Type}, Select${Type} } from '${clientPath}/types/${tableName}';
+${foreignKeySetup?.imports || ""}
 
 /**
  * Basic tests for ${tableName} table operations
  * 
  * These tests demonstrate basic CRUD operations.
- * The test data is auto-generated and may need adjustment for your specific schema.
+ * The test data is auto-generated based on your schema.
  * 
- * If tests fail due to validation errors:
- * 1. Check which fields are required by your API
- * 2. Update the test data below to match your schema requirements
- * 3. Consider adding your own business logic tests in separate files
+ * If tests fail:
+ * 1. Check the error messages for missing required fields
+ * 2. Update the test data below to match your business requirements
+ * 3. Consider adding custom tests for business logic in separate files
  */
 describe('${Type} SDK Operations', () => {
   let sdk: SDK;
   let createdId: string;
+  ${foreignKeySetup?.variables || ""}
   
-  beforeAll(() => {
+  beforeAll(async () => {
     sdk = new SDK({ 
       baseUrl: process.env.API_URL || 'http://localhost:3000',
       auth: process.env.API_KEY ? { apiKey: process.env.API_KEY } : undefined
     });
+    ${foreignKeySetup?.setup || ""}
+  });
+  
+  ${hasForeignKeys && foreignKeySetup?.cleanup ? `afterAll(async () => {
+    ${foreignKeySetup.cleanup}
   });
   
-  ${generateTestCases(table, sampleData, updateData)}
+  ` : ""}${generateTestCases(table, sampleData, updateData, hasForeignKeys)}
 });
 `;
 }
@@ -2196,6 +2229,7 @@ version: '3.8'
 services:
   postgres:
     image: postgres:17-alpine
+    container_name: postgresdk-test-database
     environment:
       POSTGRES_USER: testuser
       POSTGRES_PASSWORD: testpass
@@ -2234,7 +2268,39 @@ set -e
 
 SCRIPT_DIR="$( cd "$( dirname "\${BASH_SOURCE[0]}" )" && pwd )"
 
-echo "\uD83D\uDC33 Starting test database..."
+# Cleanup function to ensure database is stopped
+cleanup() {
+  echo ""
+  echo "\uD83E\uDDF9 Cleaning up..."
+  if [ ! -z "\${SERVER_PID}" ]; then
+    echo "   Stopping API server..."
+    kill $SERVER_PID 2>/dev/null || true
+  fi
+  echo "   Stopping test database..."
+  docker-compose -f "$SCRIPT_DIR/docker-compose.yml" stop 2>/dev/null || true
+  echo "   Done!"
+}
+
+# Set up cleanup trap
+trap cleanup EXIT INT TERM
+
+# Check for existing PostgreSQL container or connection
+echo "\uD83D\uDD0D Checking for existing database connections..."
+if docker ps | grep -q "5432->5432"; then
+  echo "⚠️  Found existing PostgreSQL container on port 5432"
+  echo "   Stopping existing container..."
+  docker ps --filter "publish=5432" --format "{{.ID}}" | xargs -r docker stop
+  sleep 2
+fi
+
+# Clean up any existing test database container
+if docker ps -a | grep -q "postgresdk-test-database"; then
+  echo "\uD83E\uDDF9 Cleaning up existing test database container..."
+  docker-compose -f "$SCRIPT_DIR/docker-compose.yml" down -v
+  sleep 2
+fi
+
+echo "\uD83D\uDC33 Starting fresh test database..."
 cd "$SCRIPT_DIR"
 docker-compose up -d --wait
 
@@ -2256,11 +2322,11 @@ echo "⚠️  TODO: Uncomment and customize the API server startup command below
 echo ""
 echo "  # Example for Node.js/Bun:"
 echo "  # cd ../.. && npm run dev &"
-echo "  # SERVER_PID=$!"
+echo "  # SERVER_PID=\\$!"
 echo ""
 echo "  # Example for custom server file:"
 echo "  # cd ../.. && node server.js &"
-echo "  # SERVER_PID=$!"
+echo "  # SERVER_PID=\\$!"
 echo ""
 echo "  Please edit this script to start your API server."
 echo ""
@@ -2278,12 +2344,6 @@ ${getTestCommand(framework, runCommand)}
 
 TEST_EXIT_CODE=$?
 
-# Cleanup
-# if [ ! -z "\${SERVER_PID}" ]; then
-#   echo "\uD83D\uDED1 Stopping API server..."
-#   kill $SERVER_PID 2>/dev/null || true
-# fi
-
 if [ $TEST_EXIT_CODE -eq 0 ]; then
   echo "✅ Tests completed successfully!"
 else
@@ -2294,12 +2354,76 @@ echo ""
 echo "\uD83D\uDCCA Test results saved to:"
 echo "  $TEST_RESULTS_DIR/"
 echo ""
-echo "To stop the test database, run:"
-echo "  cd $SCRIPT_DIR && docker-compose down"
+echo "\uD83D\uDCA1 Tips:"
+echo "  - Database will be stopped automatically on script exit"
+echo "  - To manually stop the database: docker-compose -f $SCRIPT_DIR/docker-compose.yml down"
+echo "  - To reset the database: docker-compose -f $SCRIPT_DIR/docker-compose.yml down -v"
 
 exit $TEST_EXIT_CODE
 `;
 }
+function generateForeignKeySetup(table, clientPath) {
+  const imports = [];
+  const variables = [];
+  const setupStatements = [];
+  const cleanupStatements = [];
+  const foreignTables = new Set;
+  for (const fk of table.fks) {
+    const foreignTable = fk.toTable;
+    if (!foreignTables.has(foreignTable)) {
+      foreignTables.add(foreignTable);
+      const ForeignType = pascal(foreignTable);
+      imports.push(`import type { Insert${ForeignType} } from '${clientPath}/types/${foreignTable}';`);
+      variables.push(`let ${foreignTable}Id: string;`);
+      setupStatements.push(`
+    // Create parent ${foreignTable} record for foreign key reference
+    const ${foreignTable}Data: Insert${ForeignType} = ${generateMinimalDataForTable(foreignTable)};
+    const created${ForeignType} = await sdk.${foreignTable}.create(${foreignTable}Data);
+    ${foreignTable}Id = created${ForeignType}.id;`);
+      cleanupStatements.push(`
+    // Clean up parent ${foreignTable} record
+    if (${foreignTable}Id) {
+      try {
+        await sdk.${foreignTable}.delete(${foreignTable}Id);
+      } catch (e) {
+        // Parent might already be deleted due to cascading
+      }
+    }`);
+    }
+  }
+  return {
+    imports: imports.join(`
+`),
+    variables: variables.join(`
+  `),
+    setup: setupStatements.join(""),
+    cleanup: cleanupStatements.join("")
+  };
+}
+function generateMinimalDataForTable(tableName) {
+  if (tableName.includes("author")) {
+    return `{ name: 'Test Author' }`;
+  }
+  if (tableName.includes("book")) {
+    return `{ title: 'Test Book' }`;
+  }
+  if (tableName.includes("tag")) {
+    return `{ name: 'Test Tag' }`;
+  }
+  if (tableName.includes("user")) {
+    return `{ name: 'Test User', email: 'test@example.com' }`;
+  }
+  if (tableName.includes("category") || tableName.includes("categories")) {
+    return `{ name: 'Test Category' }`;
+  }
+  if (tableName.includes("product")) {
+    return `{ name: 'Test Product', price: 10.99 }`;
+  }
+  if (tableName.includes("order")) {
+    return `{ total: 100.00, status: 'pending' }`;
+  }
+  return `{ name: 'Test ${pascal(tableName)}' }`;
+}
 function getTestCommand(framework, baseCommand) {
   switch (framework) {
     case "vitest":
@@ -2307,7 +2431,7 @@ function getTestCommand(framework, baseCommand) {
     case "jest":
       return `${baseCommand} --json --outputFile="$TEST_RESULTS_DIR/results-\${TIMESTAMP}.json" "$@"`;
     case "bun":
-      return `${baseCommand} "$@" 2>&1 | tee "$TEST_RESULTS_DIR/results-\${TIMESTAMP}.txt"`;
+      return `NO_COLOR=1 ${baseCommand} "$@" 2>&1 | tee "$TEST_RESULTS_DIR/results-\${TIMESTAMP}.txt"`;
     default:
       return `${baseCommand} "$@"`;
   }
@@ -2324,22 +2448,45 @@ function getFrameworkImports(framework) {
       return "import { describe, it, expect, beforeAll, afterAll } from 'vitest';";
   }
 }
-function generateSampleData(table) {
+function generateSampleDataFromSchema(table, hasForeignKeys = false) {
   const fields = [];
-  for (const col of table.columns) {
-    if (col.name === "id" && col.hasDefault) {
-      continue;
+  const foreignKeyColumns = new Map;
+  if (hasForeignKeys) {
+    for (const fk of table.fks) {
+      for (let i = 0;i < fk.from.length; i++) {
+        const fromCol = fk.from[i];
+        if (fromCol) {
+          foreignKeyColumns.set(fromCol, fk.toTable);
+        }
+      }
     }
-    if ((col.name === "created_at" || col.name === "updated_at") && col.hasDefault) {
-      continue;
+  }
+  for (const col of table.columns) {
+    if (col.hasDefault) {
+      const autoGenerated = ["id", "created_at", "updated_at", "created", "updated", "modified_at"];
+      if (autoGenerated.includes(col.name.toLowerCase())) {
+        continue;
+      }
     }
-    if (col.name === "deleted_at") {
+    if (col.name === "deleted_at" || col.name === "deleted") {
       continue;
     }
-    const isImportant = col.name.endsWith("_id") || col.name.endsWith("_by") || col.name.includes("email") || col.name.includes("name") || col.name.includes("phone") || col.name.includes("address") || col.name.includes("description") || col.name.includes("color") || col.name.includes("type") || col.name.includes("status") || col.name.includes("subject");
-    if (!col.nullable || isImportant) {
-      const value = getSampleValue(col.pgType, col.name);
-      fields.push(`    ${col.name}: ${value}`);
+    if (!col.nullable) {
+      const foreignTable = foreignKeyColumns.get(col.name);
+      if (foreignTable) {
+        fields.push(`    ${col.name}: ${foreignTable}Id`);
+      } else {
+        const value = generateValueForColumn(col);
+        fields.push(`    ${col.name}: ${value}`);
+      }
+    } else {
+      const foreignTable = foreignKeyColumns.get(col.name);
+      if (foreignTable) {
+        fields.push(`    ${col.name}: ${foreignTable}Id`);
+      } else if (shouldIncludeNullableColumn(col)) {
+        const value = generateValueForColumn(col);
+        fields.push(`    ${col.name}: ${value}`);
+      }
     }
   }
   return fields.length > 0 ? `{
@@ -2347,14 +2494,23 @@ ${fields.join(`,
 `)}
   }` : "{}";
 }
-function generateUpdateData(table) {
+function generateUpdateDataFromSchema(table) {
   const fields = [];
   for (const col of table.columns) {
-    if (col.hasDefault || col.name === "id" || col.name === "created_at" || col.name === "updated_at") {
+    if (table.pk.includes(col.name) || col.hasDefault) {
+      const autoGenerated = ["id", "created_at", "updated_at", "created", "updated", "modified_at"];
+      if (autoGenerated.includes(col.name.toLowerCase())) {
+        continue;
+      }
+    }
+    if (col.name.endsWith("_id")) {
       continue;
     }
-    if (!col.nullable && fields.length === 0) {
-      const value = getSampleValue(col.pgType, col.name, true);
+    if (col.name === "deleted_at" || col.name === "deleted") {
+      continue;
+    }
+    if (!col.nullable || shouldIncludeNullableColumn(col)) {
+      const value = generateValueForColumn(col, true);
       fields.push(`    ${col.name}: ${value}`);
       break;
     }
@@ -2364,59 +2520,107 @@ ${fields.join(`,
 `)}
   }` : "{}";
 }
-function getSampleValue(type, name, isUpdate = false) {
-  const suffix = isUpdate ? ' + " (updated)"' : "";
-  if (name.endsWith("_id") || name.endsWith("_by")) {
-    return `'550e8400-e29b-41d4-a716-446655440000'`;
-  }
+function shouldIncludeNullableColumn(col) {
+  const importantPatterns = [
+    "_id",
+    "_by",
+    "email",
+    "name",
+    "title",
+    "description",
+    "phone",
+    "address",
+    "status",
+    "type",
+    "category",
+    "price",
+    "amount",
+    "quantity",
+    "url",
+    "slug"
+  ];
+  const name = col.name.toLowerCase();
+  return importantPatterns.some((pattern) => name.includes(pattern));
+}
+function generateValueForColumn(col, isUpdate = false) {
+  const name = col.name.toLowerCase();
+  const type = col.pgType.toLowerCase();
   if (name.includes("email")) {
     return `'test${isUpdate ? ".updated" : ""}@example.com'`;
   }
-  if (name === "color") {
-    return `'#${isUpdate ? "FF0000" : "0000FF"}'`;
+  if (name.includes("phone")) {
+    return `'555-${isUpdate ? "0200" : "0100"}'`;
   }
-  if (name === "gender") {
-    return `'${isUpdate ? "F" : "M"}'`;
+  if (name.includes("url") || name.includes("website")) {
+    return `'https://example.com${isUpdate ? "/updated" : ""}'`;
   }
-  if (name.includes("phone")) {
-    return `'${isUpdate ? "555-0200" : "555-0100"}'`;
+  if (name.includes("password")) {
+    return `'hashedPassword123'`;
+  }
+  if (name === "name" || name.includes("_name") || name.includes("name_")) {
+    return `'Test ${pascal(col.name)}${isUpdate ? " Updated" : ""}'`;
+  }
+  if (name === "title" || name.includes("title")) {
+    return `'Test Title${isUpdate ? " Updated" : ""}'`;
+  }
+  if (name.includes("description") || name === "bio" || name === "about") {
+    return `'Test description${isUpdate ? " updated" : ""}'`;
   }
-  if (name.includes("address")) {
-    return `'123 ${isUpdate ? "Updated" : "Test"} Street'`;
+  if (name === "slug") {
+    return `'test-slug${isUpdate ? "-updated" : ""}'`;
   }
-  if (name === "type" || name === "status") {
+  if (name === "status") {
     return `'${isUpdate ? "updated" : "active"}'`;
   }
-  if (name === "subject") {
-    return `'Test Subject${isUpdate ? " Updated" : ""}'`;
+  if (name === "type" || name === "kind" || name === "category") {
+    return `'${isUpdate ? "type2" : "type1"}'`;
+  }
+  if (name === "color" || name === "colour") {
+    return `'${isUpdate ? "#FF0000" : "#0000FF"}'`;
+  }
+  if (name === "gender") {
+    return `'${isUpdate ? "F" : "M"}'`;
   }
-  if (name.includes("name") || name.includes("title")) {
-    return `'Test ${pascal(name)}'${suffix}`;
+  if (name.includes("price") || name === "cost" || name === "amount") {
+    return isUpdate ? "99.99" : "10.50";
   }
-  if (name.includes("description") || name.includes("bio") || name.includes("content")) {
-    return `'Test description'${suffix}`;
+  if (name === "quantity" || name === "count" || name.includes("qty")) {
+    return isUpdate ? "5" : "1";
   }
-  if (name.includes("preferences") || name.includes("settings")) {
-    return `'Test preferences'${suffix}`;
+  if (name === "age") {
+    return isUpdate ? "30" : "25";
   }
-  if (name.includes("restrictions") || name.includes("dietary")) {
-    return `['vegetarian']`;
+  if (name.includes("percent") || name === "rate" || name === "ratio") {
+    return isUpdate ? "0.75" : "0.5";
   }
-  if (name.includes("location") || name.includes("clinic")) {
-    return `'Test Location'${suffix}`;
+  if (name.includes("latitude") || name === "lat") {
+    return "40.7128";
   }
-  if (name.includes("specialty")) {
-    return `'General'`;
+  if (name.includes("longitude") || name === "lng" || name === "lon") {
+    return "-74.0060";
   }
-  if (name.includes("tier")) {
-    return `'Standard'`;
+  if (type.includes("date") || type.includes("timestamp")) {
+    if (name.includes("birth") || name === "dob") {
+      return `new Date('1990-01-01')`;
+    }
+    if (name.includes("end") || name.includes("expire")) {
+      return `new Date('2025-12-31')`;
+    }
+    if (name.includes("start") || name.includes("begin")) {
+      return `new Date('2024-01-01')`;
+    }
+    return `new Date()`;
   }
   switch (type) {
     case "text":
     case "varchar":
     case "char":
-      return `'test_value'${suffix}`;
+    case "character varying":
+      return `'test_value${isUpdate ? "_updated" : ""}'`;
     case "int":
+    case "int2":
+    case "int4":
+    case "int8":
     case "integer":
     case "smallint":
     case "bigint":
@@ -2426,30 +2630,55 @@ function getSampleValue(type, name, isUpdate = false) {
     case "real":
     case "double precision":
     case "float":
+    case "float4":
+    case "float8":
       return isUpdate ? "99.99" : "10.50";
     case "boolean":
     case "bool":
       return isUpdate ? "false" : "true";
-    case "date":
-      return `'2024-01-01'`;
-    case "timestamp":
-    case "timestamptz":
-      return `new Date().toISOString()`;
     case "json":
     case "jsonb":
-      return `{ key: 'value' }`;
+      return `{ key: '${isUpdate ? "updated" : "value"}' }`;
     case "uuid":
       return `'${isUpdate ? "550e8400-e29b-41d4-a716-446655440001" : "550e8400-e29b-41d4-a716-446655440000"}'`;
-    case "text[]":
-    case "varchar[]":
-      return `['item1', 'item2']`;
+    case "inet":
+      return `'${isUpdate ? "192.168.1.2" : "192.168.1.1"}'`;
+    case "cidr":
+      return `'192.168.1.0/24'`;
+    case "macaddr":
+      return `'08:00:2b:01:02:0${isUpdate ? "4" : "3"}'`;
+    case "xml":
+      return `'<root>${isUpdate ? "updated" : "value"}</root>'`;
     default:
-      return `'test'`;
+      if (type.endsWith("[]")) {
+        const baseType = type.slice(0, -2);
+        if (baseType === "text" || baseType === "varchar") {
+          return `['item1', 'item2${isUpdate ? "_updated" : ""}']`;
+        }
+        if (baseType === "int" || baseType === "integer") {
+          return `[1, 2, ${isUpdate ? "3" : ""}]`;
+        }
+        return `[]`;
+      }
+      return `'test${isUpdate ? "_updated" : ""}'`;
   }
 }
-function generateTestCases(table, sampleData, updateData) {
+function generateTestCases(table, sampleData, updateData, hasForeignKeys = false) {
   const Type = pascal(table.name);
   const hasData = sampleData !== "{}";
+  const isJunctionTable = table.pk.length > 1 && table.columns.every((col) => table.pk.includes(col.name) || col.name.endsWith("_id"));
+  if (isJunctionTable) {
+    return `it('should create a ${table.name} relationship', async () => {
+    // This is a junction table for M:N relationships
+    // Test data depends on parent records created in other tests
+    expect(true).toBe(true);
+  });
+  
+  it('should list ${table.name} relationships', async () => {
+    const list = await sdk.${table.name}.list({ limit: 10 });
+    expect(Array.isArray(list)).toBe(true);
+  });`;
+  }
   return `it('should create a ${table.name}', async () => {
     const data: Insert${Type} = ${sampleData};
     ${hasData ? `
@@ -2506,6 +2735,280 @@ function generateTestCases(table, sampleData, updateData) {
   });` : ""}`;
 }
 
+// src/emit-api-contract.ts
+function generateApiContract(model, config) {
+  const resources = [];
+  const relationships = [];
+  for (const table of Object.values(model.tables)) {
+    resources.push(generateResourceContract(table, model));
+    for (const fk of table.fks) {
+      relationships.push({
+        from: table.name,
+        to: fk.toTable,
+        type: "many-to-one",
+        description: `Each ${table.name} belongs to one ${fk.toTable}`
+      });
+    }
+  }
+  const contract = {
+    version: "1.0.0",
+    generatedAt: new Date().toISOString(),
+    description: "Auto-generated API contract describing all available endpoints, resources, and their relationships",
+    resources,
+    relationships
+  };
+  if (config.auth?.strategy && config.auth.strategy !== "none") {
+    contract.authentication = {
+      type: config.auth.strategy,
+      description: getAuthDescription(config.auth.strategy)
+    };
+  }
+  return contract;
+}
+function generateResourceContract(table, model) {
+  const Type = pascal(table.name);
+  const basePath = `/v1/${table.name}`;
+  const endpoints = [
+    {
+      method: "GET",
+      path: basePath,
+      description: `List all ${table.name} records with optional filtering, sorting, and pagination`,
+      queryParameters: {
+        limit: "number - Maximum number of records to return (default: 50)",
+        offset: "number - Number of records to skip for pagination",
+        order_by: "string - Field to sort by",
+        order_dir: "string - Sort direction (asc or desc)",
+        include: "string - Comma-separated list of related resources to include",
+        ...generateFilterParams(table)
+      },
+      responseBody: `Array<${Type}>`
+    },
+    {
+      method: "GET",
+      path: `${basePath}/:id`,
+      description: `Get a single ${table.name} record by ID`,
+      queryParameters: {
+        include: "string - Comma-separated list of related resources to include"
+      },
+      responseBody: `${Type}`
+    },
+    {
+      method: "POST",
+      path: basePath,
+      description: `Create a new ${table.name} record`,
+      requestBody: `Insert${Type}`,
+      responseBody: `${Type}`
+    },
+    {
+      method: "PATCH",
+      path: `${basePath}/:id`,
+      description: `Update an existing ${table.name} record`,
+      requestBody: `Update${Type}`,
+      responseBody: `${Type}`
+    },
+    {
+      method: "DELETE",
+      path: `${basePath}/:id`,
+      description: `Delete a ${table.name} record`,
+      responseBody: `${Type}`
+    }
+  ];
+  const fields = table.columns.map((col) => generateFieldContract(col, table));
+  return {
+    name: Type,
+    tableName: table.name,
+    description: `Resource for managing ${table.name} records`,
+    endpoints,
+    fields
+  };
+}
+function generateFieldContract(column, table) {
+  const field = {
+    name: column.name,
+    type: postgresTypeToJsonType(column.pgType),
+    required: !column.nullable && !column.hasDefault,
+    description: generateFieldDescription(column, table)
+  };
+  const fk = table.fks.find((fk2) => fk2.from.length === 1 && fk2.from[0] === column.name);
+  if (fk) {
+    field.foreignKey = {
+      table: fk.toTable,
+      field: fk.to[0] || "id"
+    };
+  }
+  return field;
+}
+function generateFieldDescription(column, table) {
+  const descriptions = [];
+  descriptions.push(`${postgresTypeToJsonType(column.pgType)} field`);
+  if (column.name === "id") {
+    descriptions.push("Unique identifier");
+  } else if (column.name === "created_at") {
+    descriptions.push("Timestamp when the record was created");
+  } else if (column.name === "updated_at") {
+    descriptions.push("Timestamp when the record was last updated");
+  } else if (column.name === "deleted_at") {
+    descriptions.push("Soft delete timestamp");
+  } else if (column.name.endsWith("_id")) {
+    const relatedTable = column.name.slice(0, -3);
+    descriptions.push(`Reference to ${relatedTable}`);
+  } else if (column.name.includes("email")) {
+    descriptions.push("Email address");
+  } else if (column.name.includes("phone")) {
+    descriptions.push("Phone number");
+  } else if (column.name.includes("name")) {
+    descriptions.push("Name field");
+  } else if (column.name.includes("description")) {
+    descriptions.push("Description text");
+  } else if (column.name.includes("status")) {
+    descriptions.push("Status indicator");
+  } else if (column.name.includes("price") || column.name.includes("amount") || column.name.includes("total")) {
+    descriptions.push("Monetary value");
+  }
+  if (!column.nullable && !column.hasDefault) {
+    descriptions.push("(required)");
+  } else if (column.nullable) {
+    descriptions.push("(optional)");
+  }
+  return descriptions.join(" - ");
+}
+function postgresTypeToJsonType(pgType) {
+  switch (pgType) {
+    case "int":
+    case "integer":
+    case "smallint":
+    case "bigint":
+    case "decimal":
+    case "numeric":
+    case "real":
+    case "double precision":
+    case "float":
+      return "number";
+    case "boolean":
+    case "bool":
+      return "boolean";
+    case "date":
+    case "timestamp":
+    case "timestamptz":
+      return "date/datetime";
+    case "json":
+    case "jsonb":
+      return "object";
+    case "uuid":
+      return "uuid";
+    case "text[]":
+    case "varchar[]":
+      return "array<string>";
+    case "int[]":
+    case "integer[]":
+      return "array<number>";
+    default:
+      return "string";
+  }
+}
+function generateFilterParams(table) {
+  const filters = {};
+  for (const col of table.columns) {
+    const type = postgresTypeToJsonType(col.pgType);
+    filters[col.name] = `${type} - Filter by exact ${col.name} value`;
+    if (type === "number" || type === "date/datetime") {
+      filters[`${col.name}_gt`] = `${type} - Filter where ${col.name} is greater than`;
+      filters[`${col.name}_gte`] = `${type} - Filter where ${col.name} is greater than or equal`;
+      filters[`${col.name}_lt`] = `${type} - Filter where ${col.name} is less than`;
+      filters[`${col.name}_lte`] = `${type} - Filter where ${col.name} is less than or equal`;
+    }
+    if (type === "string") {
+      filters[`${col.name}_like`] = `string - Filter where ${col.name} contains text (case-insensitive)`;
+    }
+  }
+  return filters;
+}
+function getAuthDescription(strategy) {
+  switch (strategy) {
+    case "jwt":
+      return "JWT Bearer token authentication. Include token in Authorization header: 'Bearer <token>'";
+    case "apiKey":
+      return "API Key authentication. Include key in the configured header (e.g., 'x-api-key')";
+    default:
+      return "Custom authentication strategy";
+  }
+}
+function generateApiContractMarkdown(contract) {
+  const lines = [];
+  lines.push("# API Contract");
+  lines.push("");
+  lines.push(contract.description);
+  lines.push("");
+  lines.push(`**Version:** ${contract.version}`);
+  lines.push(`**Generated:** ${new Date(contract.generatedAt).toLocaleString()}`);
+  lines.push("");
+  if (contract.authentication) {
+    lines.push("## Authentication");
+    lines.push("");
+    lines.push(`**Type:** ${contract.authentication.type}`);
+    lines.push("");
+    lines.push(contract.authentication.description);
+    lines.push("");
+  }
+  lines.push("## Resources");
+  lines.push("");
+  for (const resource of contract.resources) {
+    lines.push(`### ${resource.name}`);
+    lines.push("");
+    lines.push(resource.description);
+    lines.push("");
+    lines.push("**Endpoints:**");
+    lines.push("");
+    for (const endpoint of resource.endpoints) {
+      lines.push(`- \`${endpoint.method} ${endpoint.path}\` - ${endpoint.description}`);
+    }
+    lines.push("");
+    lines.push("**Fields:**");
+    lines.push("");
+    for (const field of resource.fields) {
+      const required = field.required ? " *(required)*" : "";
+      const fk = field.foreignKey ? ` → ${field.foreignKey.table}` : "";
+      lines.push(`- \`${field.name}\` (${field.type})${required}${fk} - ${field.description}`);
+    }
+    lines.push("");
+  }
+  if (contract.relationships.length > 0) {
+    lines.push("## Relationships");
+    lines.push("");
+    for (const rel of contract.relationships) {
+      lines.push(`- **${rel.from}** → **${rel.to}** (${rel.type}): ${rel.description}`);
+    }
+    lines.push("");
+  }
+  return lines.join(`
+`);
+}
+function emitApiContract(model, config) {
+  const contract = generateApiContract(model, config);
+  const contractJson = JSON.stringify(contract, null, 2);
+  return `/**
+ * API Contract
+ * 
+ * This module exports the API contract that describes all available
+ * endpoints, resources, and their relationships.
+ */
+
+export const apiContract = ${contractJson};
+
+export const apiContractMarkdown = \`${generateApiContractMarkdown(contract).replace(/`/g, "\\`")}\`;
+
+/**
+ * Helper to get the contract in different formats
+ */
+export function getApiContract(format: 'json' | 'markdown' = 'json') {
+  if (format === 'markdown') {
+    return apiContractMarkdown;
+  }
+  return apiContract;
+}
+`;
+}
+
 // src/types.ts
 function normalizeAuthConfig(input) {
   if (!input)
@@ -2649,6 +3152,10 @@ async function generate(configPath) {
     path: join(serverDir, "sdk-bundle.ts"),
     content: emitSdkBundle(clientFiles, clientDir)
   });
+  files.push({
+    path: join(serverDir, "api-contract.ts"),
+    content: emitApiContract(model, cfg)
+  });
   if (generateTests) {
     console.log("\uD83E\uDDEA Generating tests...");
     const relativeClientPath = relative(testDir, clientDir);