postgresdk 0.6.5 → 0.6.6

package/dist/cli.js

@@ -2006,6 +2006,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}";` : ""}
 
@@ -2067,6 +2068,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;
 }
 
@@ -2344,11 +2368,14 @@ function emitTableTest(table, clientPath, framework = "vitest") {
   const Type = pascal(table.name);
   const tableName = table.name;
   const imports = getFrameworkImports(framework);
-  const sampleData = generateSampleData(table);
+  const hasForeignKeys = table.fks.length > 0;
+  const foreignKeySetup = hasForeignKeys ? generateForeignKeySetup(table, clientPath) : null;
+  const sampleData = generateSampleData(table, hasForeignKeys);
   const updateData = generateUpdateData(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
@@ -2364,15 +2391,21 @@ import type { Insert${Type}, Update${Type}, Select${Type} } from '${clientPath}/
 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)}
 });
 `;
 }
@@ -2432,6 +2465,13 @@ export default defineConfig({
     testTimeout: 30000,
     hookTimeout: 30000,
     // The reporters are configured via CLI in the test script
+    // Force color output in terminal
+    pool: 'forks',
+    poolOptions: {
+      forks: {
+        singleFork: true,
+      }
+    }
   },
 });
 `;
@@ -2512,6 +2552,10 @@ docker-compose up -d --wait
 export TEST_DATABASE_URL="postgres://testuser:testpass@localhost:5432/testdb"
 export TEST_API_URL="http://localhost:3000"
 
+# Force color output for better terminal experience
+export FORCE_COLOR=1
+export CI=""
+
 # Wait for database to be ready
 echo "⏳ Waiting for database..."
 sleep 3
@@ -2570,16 +2614,67 @@ echo "  cd $SCRIPT_DIR && docker-compose down"
 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 = ${generateMinimalSampleData(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 generateMinimalSampleData(tableName) {
+  const commonPatterns = {
+    contacts: `{ name: 'Test Contact', email: 'test@example.com', gender: 'M', date_of_birth: new Date('1990-01-01'), emergency_contact: 'Emergency Contact', clinic_location: 'Main Clinic', specialty: 'General', fmv_tiering: 'Standard', flight_preferences: 'Economy', dietary_restrictions: [], special_accommodations: 'None' }`,
+    tags: `{ name: 'Test Tag' }`,
+    authors: `{ name: 'Test Author' }`,
+    books: `{ title: 'Test Book' }`,
+    users: `{ name: 'Test User', email: 'test@example.com' }`,
+    categories: `{ name: 'Test Category' }`,
+    products: `{ name: 'Test Product', price: 10.99 }`,
+    orders: `{ total: 100.00 }`
+  };
+  return commonPatterns[tableName] || `{ name: 'Test ${pascal(tableName)}' }`;
+}
 function getTestCommand(framework, baseCommand) {
   switch (framework) {
     case "vitest":
-      return `${baseCommand} --reporter=default --reporter=json --outputFile="$TEST_RESULTS_DIR/results-\${TIMESTAMP}.json" "$@"`;
+      return `FORCE_COLOR=1 ${baseCommand} --reporter=default --reporter=json --outputFile="$TEST_RESULTS_DIR/results-\${TIMESTAMP}.json" "$@"`;
     case "jest":
-      return `${baseCommand} --json --outputFile="$TEST_RESULTS_DIR/results-\${TIMESTAMP}.json" "$@"`;
+      return `FORCE_COLOR=1 ${baseCommand} --colors --json --outputFile="$TEST_RESULTS_DIR/results-\${TIMESTAMP}.json" "$@"`;
     case "bun":
-      return `${baseCommand} "$@" 2>&1 | tee "$TEST_RESULTS_DIR/results-\${TIMESTAMP}.txt"`;
+      return `FORCE_COLOR=1 ${baseCommand} "$@" 2>&1 | tee "$TEST_RESULTS_DIR/results-\${TIMESTAMP}.txt"`;
     default:
-      return `${baseCommand} "$@"`;
+      return `FORCE_COLOR=1 ${baseCommand} "$@"`;
   }
 }
 function getFrameworkImports(framework) {
@@ -2594,8 +2689,16 @@ function getFrameworkImports(framework) {
       return "import { describe, it, expect, beforeAll, afterAll } from 'vitest';";
   }
 }
-function generateSampleData(table) {
+function generateSampleData(table, hasForeignKeys = false) {
   const fields = [];
+  const foreignKeyColumns = new Map;
+  if (hasForeignKeys) {
+    for (const fk of table.fks) {
+      if (fk.from.length === 1 && fk.from[0]) {
+        foreignKeyColumns.set(fk.from[0], fk.toTable);
+      }
+    }
+  }
   for (const col of table.columns) {
     if (col.name === "id" && col.hasDefault) {
       continue;
@@ -2606,10 +2709,17 @@ function generateSampleData(table) {
     if (col.name === "deleted_at") {
       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);
+    if (!col.nullable) {
+      const foreignTable = foreignKeyColumns.get(col.name);
+      const value = foreignTable ? `${foreignTable}Id` : getSampleValue(col.pgType, col.name);
       fields.push(`    ${col.name}: ${value}`);
+    } else {
+      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 (isImportant) {
+        const foreignTable = foreignKeyColumns.get(col.name);
+        const value = foreignTable ? `${foreignTable}Id` : getSampleValue(col.pgType, col.name);
+        fields.push(`    ${col.name}: ${value}`);
+      }
     }
   }
   return fields.length > 0 ? `{
@@ -2681,6 +2791,18 @@ function getSampleValue(type, name, isUpdate = false) {
   if (name.includes("tier")) {
     return `'Standard'`;
   }
+  if (name.includes("emergency")) {
+    return `'Emergency Contact ${isUpdate ? "Updated" : "Name"}'`;
+  }
+  if (name === "date_of_birth" || name.includes("birth")) {
+    return `new Date('1990-01-01')`;
+  }
+  if (name.includes("accommodations")) {
+    return `'No special accommodations'`;
+  }
+  if (name.includes("flight")) {
+    return `'Economy'`;
+  }
   switch (type) {
     case "text":
     case "varchar":
@@ -2704,7 +2826,7 @@ function getSampleValue(type, name, isUpdate = false) {
       return `'2024-01-01'`;
     case "timestamp":
     case "timestamptz":
-      return `new Date().toISOString()`;
+      return `new Date()`;
     case "json":
     case "jsonb":
       return `{ key: 'value' }`;
@@ -2717,7 +2839,7 @@ function getSampleValue(type, name, isUpdate = false) {
       return `'test'`;
   }
 }
-function generateTestCases(table, sampleData, updateData) {
+function generateTestCases(table, sampleData, updateData, hasForeignKeys = false) {
   const Type = pascal(table.name);
   const hasData = sampleData !== "{}";
   return `it('should create a ${table.name}', async () => {
@@ -2776,6 +2898,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)
@@ -2919,6 +3315,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);

package/dist/emit-api-contract.d.ts

@@ -0,0 +1,60 @@
+import type { Model } from "./introspect";
+import type { Config, AuthConfig } from "./types";
+export interface ApiContract {
+    version: string;
+    generatedAt: string;
+    description: string;
+    authentication?: {
+        type: string;
+        description: string;
+    };
+    resources: ResourceContract[];
+    relationships: RelationshipContract[];
+}
+export interface ResourceContract {
+    name: string;
+    tableName: string;
+    description: string;
+    endpoints: EndpointContract[];
+    fields: FieldContract[];
+}
+export interface EndpointContract {
+    method: string;
+    path: string;
+    description: string;
+    requestBody?: any;
+    responseBody?: any;
+    queryParameters?: any;
+}
+export interface FieldContract {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string;
+    foreignKey?: {
+        table: string;
+        field: string;
+    };
+}
+export interface RelationshipContract {
+    from: string;
+    to: string;
+    type: "one-to-many" | "many-to-one" | "many-to-many";
+    description: string;
+}
+/**
+ * Generate a comprehensive API contract in JSON format
+ */
+export declare function generateApiContract(model: Model, config: Config & {
+    auth?: AuthConfig;
+}): ApiContract;
+/**
+ * Generate a human-readable markdown version of the contract
+ */
+export declare function generateApiContractMarkdown(contract: ApiContract): string;
+/**
+ * Emit the API contract as TypeScript code that can be served as an endpoint
+ */
+export declare function emitApiContract(model: Model, config: Config & {
+    auth?: AuthConfig;
+}): string;

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,11 +2098,14 @@ function emitTableTest(table, clientPath, framework = "vitest") {
   const Type = pascal(table.name);
   const tableName = table.name;
   const imports = getFrameworkImports(framework);
-  const sampleData = generateSampleData(table);
+  const hasForeignKeys = table.fks.length > 0;
+  const foreignKeySetup = hasForeignKeys ? generateForeignKeySetup(table, clientPath) : null;
+  const sampleData = generateSampleData(table, hasForeignKeys);
   const updateData = generateUpdateData(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
@@ -2094,15 +2121,21 @@ import type { Insert${Type}, Update${Type}, Select${Type} } from '${clientPath}/
 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)}
 });
 `;
 }
@@ -2162,6 +2195,13 @@ export default defineConfig({
     testTimeout: 30000,
     hookTimeout: 30000,
     // The reporters are configured via CLI in the test script
+    // Force color output in terminal
+    pool: 'forks',
+    poolOptions: {
+      forks: {
+        singleFork: true,
+      }
+    }
   },
 });
 `;
@@ -2242,6 +2282,10 @@ docker-compose up -d --wait
 export TEST_DATABASE_URL="postgres://testuser:testpass@localhost:5432/testdb"
 export TEST_API_URL="http://localhost:3000"
 
+# Force color output for better terminal experience
+export FORCE_COLOR=1
+export CI=""
+
 # Wait for database to be ready
 echo "⏳ Waiting for database..."
 sleep 3
@@ -2300,16 +2344,67 @@ echo "  cd $SCRIPT_DIR && docker-compose down"
 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 = ${generateMinimalSampleData(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 generateMinimalSampleData(tableName) {
+  const commonPatterns = {
+    contacts: `{ name: 'Test Contact', email: 'test@example.com', gender: 'M', date_of_birth: new Date('1990-01-01'), emergency_contact: 'Emergency Contact', clinic_location: 'Main Clinic', specialty: 'General', fmv_tiering: 'Standard', flight_preferences: 'Economy', dietary_restrictions: [], special_accommodations: 'None' }`,
+    tags: `{ name: 'Test Tag' }`,
+    authors: `{ name: 'Test Author' }`,
+    books: `{ title: 'Test Book' }`,
+    users: `{ name: 'Test User', email: 'test@example.com' }`,
+    categories: `{ name: 'Test Category' }`,
+    products: `{ name: 'Test Product', price: 10.99 }`,
+    orders: `{ total: 100.00 }`
+  };
+  return commonPatterns[tableName] || `{ name: 'Test ${pascal(tableName)}' }`;
+}
 function getTestCommand(framework, baseCommand) {
   switch (framework) {
     case "vitest":
-      return `${baseCommand} --reporter=default --reporter=json --outputFile="$TEST_RESULTS_DIR/results-\${TIMESTAMP}.json" "$@"`;
+      return `FORCE_COLOR=1 ${baseCommand} --reporter=default --reporter=json --outputFile="$TEST_RESULTS_DIR/results-\${TIMESTAMP}.json" "$@"`;
     case "jest":
-      return `${baseCommand} --json --outputFile="$TEST_RESULTS_DIR/results-\${TIMESTAMP}.json" "$@"`;
+      return `FORCE_COLOR=1 ${baseCommand} --colors --json --outputFile="$TEST_RESULTS_DIR/results-\${TIMESTAMP}.json" "$@"`;
     case "bun":
-      return `${baseCommand} "$@" 2>&1 | tee "$TEST_RESULTS_DIR/results-\${TIMESTAMP}.txt"`;
+      return `FORCE_COLOR=1 ${baseCommand} "$@" 2>&1 | tee "$TEST_RESULTS_DIR/results-\${TIMESTAMP}.txt"`;
     default:
-      return `${baseCommand} "$@"`;
+      return `FORCE_COLOR=1 ${baseCommand} "$@"`;
   }
 }
 function getFrameworkImports(framework) {
@@ -2324,8 +2419,16 @@ function getFrameworkImports(framework) {
       return "import { describe, it, expect, beforeAll, afterAll } from 'vitest';";
   }
 }
-function generateSampleData(table) {
+function generateSampleData(table, hasForeignKeys = false) {
   const fields = [];
+  const foreignKeyColumns = new Map;
+  if (hasForeignKeys) {
+    for (const fk of table.fks) {
+      if (fk.from.length === 1 && fk.from[0]) {
+        foreignKeyColumns.set(fk.from[0], fk.toTable);
+      }
+    }
+  }
   for (const col of table.columns) {
     if (col.name === "id" && col.hasDefault) {
       continue;
@@ -2336,10 +2439,17 @@ function generateSampleData(table) {
     if (col.name === "deleted_at") {
       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);
+    if (!col.nullable) {
+      const foreignTable = foreignKeyColumns.get(col.name);
+      const value = foreignTable ? `${foreignTable}Id` : getSampleValue(col.pgType, col.name);
       fields.push(`    ${col.name}: ${value}`);
+    } else {
+      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 (isImportant) {
+        const foreignTable = foreignKeyColumns.get(col.name);
+        const value = foreignTable ? `${foreignTable}Id` : getSampleValue(col.pgType, col.name);
+        fields.push(`    ${col.name}: ${value}`);
+      }
     }
   }
   return fields.length > 0 ? `{
@@ -2411,6 +2521,18 @@ function getSampleValue(type, name, isUpdate = false) {
   if (name.includes("tier")) {
     return `'Standard'`;
   }
+  if (name.includes("emergency")) {
+    return `'Emergency Contact ${isUpdate ? "Updated" : "Name"}'`;
+  }
+  if (name === "date_of_birth" || name.includes("birth")) {
+    return `new Date('1990-01-01')`;
+  }
+  if (name.includes("accommodations")) {
+    return `'No special accommodations'`;
+  }
+  if (name.includes("flight")) {
+    return `'Economy'`;
+  }
   switch (type) {
     case "text":
     case "varchar":
@@ -2434,7 +2556,7 @@ function getSampleValue(type, name, isUpdate = false) {
       return `'2024-01-01'`;
     case "timestamp":
     case "timestamptz":
-      return `new Date().toISOString()`;
+      return `new Date()`;
     case "json":
     case "jsonb":
       return `{ key: 'value' }`;
@@ -2447,7 +2569,7 @@ function getSampleValue(type, name, isUpdate = false) {
       return `'test'`;
   }
 }
-function generateTestCases(table, sampleData, updateData) {
+function generateTestCases(table, sampleData, updateData, hasForeignKeys = false) {
   const Type = pascal(table.name);
   const hasData = sampleData !== "{}";
   return `it('should create a ${table.name}', async () => {
@@ -2506,6 +2628,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 +3045,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresdk",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "Generate a typed server/client SDK from a Postgres schema (includes, Zod, Hono).",
   "type": "module",
   "bin": {
@@ -28,6 +28,7 @@
     "test:gen-with-tests": "bun src/cli.ts generate -c test/test-with-tests.config.ts",
     "test:pull": "bun test/test-pull.ts",
     "test:typecheck": "bun test/test-typecheck.ts",
+    "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build",
     "publish:patch": "./publish.sh",
     "publish:minor": "./publish.sh",