postgresdk 0.13.0 → 0.14.1

package/README.md

@@ -4,6 +4,50 @@
 
 Generate a typed server/client SDK from your PostgreSQL database schema.
 
+## See It In Action
+
+**Your database:**
+```sql
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  name TEXT NOT NULL,
+  email TEXT UNIQUE NOT NULL
+);
+
+CREATE TABLE posts (
+  id SERIAL PRIMARY KEY,
+  user_id INTEGER REFERENCES users(id),
+  title TEXT NOT NULL,
+  published_at TIMESTAMPTZ
+);
+```
+
+**What you get:**
+```typescript
+// ✨ Fully typed client with autocomplete
+const user = await sdk.users.create({
+  name: "Alice",
+  email: "alice@example.com"
+});
+// ^ TypeScript knows: user.id is number, user.name is string
+
+// 🔗 Automatic relationship loading
+const users = await sdk.users.list({
+  include: { posts: true }
+});
+// ^ users[0].posts is fully typed Post[]
+
+// 🎯 Advanced filtering with type safety
+const filtered = await sdk.users.list({
+  where: {
+    email: { $ilike: '%@company.com' },
+    posts: { published_at: { $isNot: null } }
+  }
+});
+```
+
+**All generated automatically. Zero boilerplate.**
+
 ## Features
 
 - 🚀 **Instant SDK Generation** - Point at your PostgreSQL database and get a complete SDK
@@ -20,14 +64,23 @@ Generate a typed server/client SDK from your PostgreSQL database schema.
 npm install -g postgresdk
 # or
 npx postgresdk generate
+
+# With Bun
+bun install -g postgresdk
+# or
+bunx postgresdk generate
 ```
 
+> **Note:** Currently only generates **Hono** server code. See [Supported Frameworks](#supported-frameworks) for details.
+
 ## Quick Start
 
 1. Initialize your project:
 
 ```bash
 npx postgresdk init
+# or with Bun
+bunx postgresdk init
 ```
 
 This creates a `postgresdk.config.ts` file with all available options documented.
@@ -45,12 +98,13 @@ export default {
 
 ```bash
 postgresdk generate
+# or with Bun
+bunx postgresdk generate
 ```
 
-4. Use the generated SDK:
+4. Set up your server:
 
 ```typescript
-// Server (Hono)
 import { Hono } from "hono";
 import { Client } from "pg";
 import { createRouter } from "./api/server/router";
@@ -61,8 +115,11 @@ await pg.connect();
 
 const api = createRouter({ pg });
 app.route("/", api);
+```
+
+5. Use the client SDK:
 
-// Client
+```typescript
 import { SDK } from "./api/client";
 
 const sdk = new SDK({ baseUrl: "http://localhost:3000" });
@@ -82,13 +139,12 @@ Create a `postgresdk.config.ts` file in your project root:
 export default {
   // Required
   connectionString: process.env.DATABASE_URL || "postgres://user:pass@localhost:5432/dbname",
-  
+
   // Optional (with defaults)
   schema: "public",                    // Database schema to introspect
-  outServer: "./api/server",           // Server code output directory  
-  outClient: "./api/client",           // Client SDK output directory
+  outDir: "./api",                     // Output directory (or { client: "./sdk", server: "./api" })
   softDeleteColumn: null,              // Column name for soft deletes (e.g., "deleted_at")
-  includeMethodsDepth: 2,               // Max depth for nested includes
+  includeMethodsDepth: 2,              // Max depth for nested includes
   dateType: "date",                    // "date" | "string" - How to handle timestamps
   serverFramework: "hono",             // Currently only hono is supported
   useJsExtensions: false,              // Add .js to imports (for Vercel Edge, Deno)
@@ -97,7 +153,11 @@ export default {
   auth: {
     apiKey: process.env.API_KEY,        // Simple API key auth
     // OR
-    jwt: process.env.JWT_SECRET,        // Simple JWT auth
+    jwt: {                              // JWT with multi-service support
+      services: [
+        { issuer: "my-app", secret: process.env.JWT_SECRET }
+      ]
+    }
   },
   
   // Test generation (optional)
@@ -282,14 +342,35 @@ const sdk = new SDK({
 export default {
   connectionString: "...",
   auth: {
-    jwt: process.env.JWT_SECRET
+    strategy: "jwt-hs256",
+    jwt: {
+      services: [
+        { issuer: "my-app", secret: process.env.JWT_SECRET }
+      ],
+      audience: "my-api"  // Optional
+    }
+  }
+};
+
+// Multi-service example (each service has its own secret)
+export default {
+  connectionString: "...",
+  auth: {
+    strategy: "jwt-hs256",
+    jwt: {
+      services: [
+        { issuer: "web-app", secret: process.env.WEB_APP_SECRET },
+        { issuer: "mobile-app", secret: process.env.MOBILE_SECRET },
+      ],
+      audience: "my-api"
+    }
   }
 };
 
 // Client SDK usage
 const sdk = new SDK({
   baseUrl: "http://localhost:3000",
-  auth: { jwt: "eyJhbGciOiJIUzI1NiIs..." }
+  auth: { jwt: "eyJhbGciOiJIUzI1NiIs..." }  // JWT must include 'iss' claim
 });
 ```
 
@@ -378,6 +459,42 @@ app.route("/", apiRouter);
 serve({ fetch: app.fetch, port: 3000 });
 ```
 
+## Deployment
+
+### Serverless (Vercel, Netlify, Cloudflare Workers)
+
+Use `max: 1` - each serverless instance should hold one connection:
+
+```typescript
+import { Pool } from "@neondatabase/serverless";
+
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 1  // One connection per serverless instance
+});
+
+const apiRouter = createRouter({ pg: pool });
+```
+
+**Why `max: 1`?** Serverless functions are ephemeral and isolated. Each instance handles one request at a time, so connection pooling provides no benefit and wastes database connections.
+
+### Traditional Servers (Railway, Render, VPS)
+
+Use connection pooling to reuse connections across requests:
+
+```typescript
+import { Pool } from "@neondatabase/serverless";
+
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 10  // Reuse connections across requests
+});
+
+const apiRouter = createRouter({ pg: pool });
+```
+
+**Why `max: 10`?** Long-running servers handle many concurrent requests. Pooling prevents opening/closing connections for every request, significantly improving performance.
+
 ## SDK Distribution
 
 Your generated SDK can be pulled by client applications:
@@ -420,6 +537,9 @@ Run tests with the included Docker setup:
 ```bash
 chmod +x api/tests/run-tests.sh
 ./api/tests/run-tests.sh
+
+# Or with Bun's built-in test runner (if framework: "bun")
+bun test
 ```
 
 ## CLI Commands
@@ -437,8 +557,14 @@ Commands:
 Options:
   -c, --config <path>  Path to config file (default: postgresdk.config.ts)
 
+Init flags:
+  --api                Generate API-side config (for database introspection)
+  --sdk                Generate SDK-side config (for consuming remote SDK)
+
 Examples:
-  postgresdk init
+  postgresdk init                              # Interactive prompt
+  postgresdk init --api                        # API-side config
+  postgresdk init --sdk                        # SDK-side config
   postgresdk generate
   postgresdk generate -c custom.config.ts
   postgresdk pull --from=https://api.com --output=./src/sdk
@@ -446,10 +572,32 @@ Examples:
 
 ## Requirements
 
-- Node.js 18+ 
+- Node.js 18+
 - PostgreSQL 12+
 - TypeScript project (for using generated code)
 
+## Supported Frameworks
+
+**Currently, postgresdk only generates server code for Hono.**
+
+While the configuration accepts `serverFramework: "hono" | "express" | "fastify"`, only Hono is implemented at this time. Attempting to generate code with `express` or `fastify` will result in an error.
+
+### Why Hono?
+
+Hono was chosen as the initial framework because:
+- **Edge-first design** - Works seamlessly in serverless and edge environments (Cloudflare Workers, Vercel Edge, Deno Deploy)
+- **Minimal dependencies** - Lightweight with excellent performance
+- **Modern patterns** - Web Standard APIs (Request/Response), TypeScript-first
+- **Framework compatibility** - Works across Node.js, Bun, Deno, and edge runtimes
+
+### Future Framework Support
+
+The codebase architecture is designed to support multiple frameworks. Adding Express or Fastify support would require:
+- Implementing framework-specific route emitters (`emit-routes-express.ts`, etc.)
+- Implementing framework-specific router creators (`emit-router-express.ts`, etc.)
+
+Contributions to add additional framework support are welcome.
+
 ## License
 
 MIT

package/dist/cli.js

@@ -578,7 +578,7 @@ function generateIncludeMethods(table, graph, opts, allTables) {
         path: newPath,
         isMany: newIsMany,
         targets: newTargets,
-        returnType: `{ data: (${buildReturnType(baseTableName, newPath, newIsMany, newTargets, graph)})[]; total: number; limit: number; offset: number; hasMore: boolean; }`,
+        returnType: `PaginatedResponse<${buildReturnType(baseTableName, newPath, newIsMany, newTargets, graph)}>`,
         includeSpec: buildIncludeSpec(newPath)
       });
       methods.push({
@@ -618,7 +618,7 @@ function generateIncludeMethods(table, graph, opts, allTables) {
               path: combinedPath,
               isMany: [edge1.kind === "many", edge2.kind === "many"],
               targets: [edge1.target, edge2.target],
-              returnType: `{ data: (Select${pascal(baseTableName)} & { ${type1}; ${type2} })[]; total: number; limit: number; offset: number; hasMore: boolean; }`,
+              returnType: `PaginatedResponse<Select${pascal(baseTableName)} & { ${type1}; ${type2} }>`,
               includeSpec: { [key1]: true, [key2]: true }
             });
             methods.push({
@@ -785,7 +785,7 @@ function generateResourceWithSDK(table, model, graph, config) {
   const endpoints = [];
   sdkMethods.push({
     name: "list",
-    signature: `list(params?: ListParams): Promise<{ data: ${Type}[]; total: number; limit: number; offset: number; hasMore: boolean; }>`,
+    signature: `list(params?: ListParams): Promise<PaginatedResponse<${Type}>>`,
     description: `List ${tableName} with filtering, sorting, and pagination. Returns paginated results with metadata.`,
     example: `// Get all ${tableName}
 const result = await sdk.${tableName}.list();
@@ -812,7 +812,7 @@ const currentPage = Math.floor(filtered.offset / filtered.limit) + 1;`,
     path: basePath,
     description: `List all ${tableName} records with pagination metadata`,
     queryParameters: generateQueryParams(table, enums),
-    responseBody: `{ data: ${Type}[]; total: number; limit: number; offset: number; hasMore: boolean; }`
+    responseBody: `PaginatedResponse<${Type}>`
   });
   if (hasSinglePK) {
     sdkMethods.push({
@@ -1951,12 +1951,14 @@ function getDefaultComplexBlock(key) {
   //     process.env.API_KEY_1,
   //     process.env.API_KEY_2,
   //   ],
-  //   
+  //
   //   // For JWT (HS256) authentication
   //   jwt: {
-  //     sharedSecret: process.env.JWT_SECRET,  // Secret for signing/verifying
-  //     issuer: "my-app",                      // Optional: validate 'iss' claim
-  //     audience: "my-users",                  // Optional: validate 'aud' claim
+  //     services: [                            // Array of services that can authenticate
+  //       { issuer: "web-app", secret: process.env.WEB_APP_SECRET },
+  //       { issuer: "mobile-app", secret: process.env.MOBILE_SECRET },
+  //     ],
+  //     audience: "my-api",                    // Optional: validate 'aud' claim
   //   }
   // },`;
     case "pull":
@@ -1983,6 +1985,8 @@ async function initCommand(args) {
   console.log(`\uD83D\uDE80 Initializing postgresdk configuration...
 `);
   const forceError = args.includes("--force-error");
+  const isApiSide = args.includes("--api");
+  const isSdkSide = args.includes("--sdk");
   const configPath = resolve(process.cwd(), "postgresdk.config.ts");
   if (existsSync(configPath)) {
     if (forceError) {
@@ -2102,21 +2106,65 @@ async function initCommand(args) {
     }
     return;
   }
+  let projectType;
+  if (isApiSide && isSdkSide) {
+    console.error("❌ Error: Cannot use both --api and --sdk flags");
+    process.exit(1);
+  } else if (isApiSide) {
+    projectType = "api";
+  } else if (isSdkSide) {
+    projectType = "sdk";
+  } else {
+    const response = await prompts({
+      type: "select",
+      name: "projectType",
+      message: "What type of project is this?",
+      choices: [
+        {
+          title: "API-side (generating SDK from database)",
+          value: "api",
+          description: "You have a PostgreSQL database and want to generate an SDK"
+        },
+        {
+          title: "SDK-side (consuming a remote SDK)",
+          value: "sdk",
+          description: "You want to pull and use an SDK from a remote API"
+        }
+      ],
+      initial: 0
+    });
+    projectType = response.projectType;
+    if (!projectType) {
+      console.log(`
+✅ Cancelled. No changes made.`);
+      process.exit(0);
+    }
+  }
+  const template = projectType === "api" ? CONFIG_TEMPLATE_API : CONFIG_TEMPLATE_SDK;
   const envPath = resolve(process.cwd(), ".env");
   const hasEnv = existsSync(envPath);
   try {
-    writeFileSync(configPath, CONFIG_TEMPLATE, "utf-8");
+    writeFileSync(configPath, template, "utf-8");
     console.log("✅ Created postgresdk.config.ts");
     console.log(`
 \uD83D\uDCDD Next steps:`);
-    console.log("   1. Edit postgresdk.config.ts with your database connection");
-    if (!hasEnv) {
-      console.log("   2. Consider creating a .env file for sensitive values:");
-      console.log("      DATABASE_URL=postgres://user:pass@localhost:5432/mydb");
-      console.log("      API_KEY=your-secret-key");
-      console.log("      JWT_SECRET=your-jwt-secret");
-    }
-    console.log("   3. Run 'postgresdk generate' to create your SDK");
+    if (projectType === "api") {
+      console.log("   1. Edit postgresdk.config.ts with your database connection");
+      if (!hasEnv) {
+        console.log("   2. Consider creating a .env file for sensitive values:");
+        console.log("      DATABASE_URL=postgres://user:pass@localhost:5432/mydb");
+        console.log("      API_KEY=your-secret-key");
+        console.log("      JWT_SECRET=your-jwt-secret");
+      }
+      console.log("   3. Run 'postgresdk generate' to create your SDK");
+    } else {
+      console.log("   1. Edit postgresdk.config.ts with your API URL in pull.from");
+      if (!hasEnv) {
+        console.log("   2. Consider creating a .env file if you need authentication:");
+        console.log("      API_TOKEN=your-api-token");
+      }
+      console.log("   3. Run 'postgresdk pull' to fetch your SDK");
+    }
     console.log(`
 \uD83D\uDCA1 Tip: The config file has detailed comments for all options.`);
     console.log("   Uncomment the options you want to customize.");
@@ -2125,8 +2173,8 @@ async function initCommand(args) {
     process.exit(1);
   }
 }
-var CONFIG_TEMPLATE = `/**
- * PostgreSDK Configuration
+var CONFIG_TEMPLATE_API = `/**
+ * PostgreSDK Configuration (API-Side)
  *
  * This file configures how postgresdk generates your type-safe API and SDK
  * from your PostgreSQL database schema.
@@ -2137,9 +2185,7 @@ var CONFIG_TEMPLATE = `/**
  *   3. Start using your generated SDK!
  *
  * CLI COMMANDS:
- *   postgresdk init              Initialize this config file
  *   postgresdk generate          Generate API and SDK from your database
- *   postgresdk pull              Pull SDK from a remote API
  *   postgresdk help              Show help and examples
  *
  * Environment variables are automatically loaded from .env files.
@@ -2165,16 +2211,17 @@ export default {
   // schema: "public",
 
   /**
-   * Output directory for server-side code (routes, validators, etc.)
-   * Default: "./api/server"
-   */
-  // outServer: "./api/server",
-
-  /**
-   * Output directory for client SDK
-   * Default: "./api/client"
+   * Output directory for generated code
+   *
+   * Simple usage (same directory for both):
+   *   outDir: "./api"
+   *
+   * Separate directories for client and server:
+   *   outDir: { client: "./sdk", server: "./api" }
+   *
+   * Default: { client: "./api/client", server: "./api/server" }
    */
-  // outClient: "./api/client",
+  // outDir: "./api",
 
   // ========== ADVANCED OPTIONS ==========
 
@@ -2254,23 +2301,42 @@ export default {
   //
   //   // For JWT (HS256) authentication
   //   jwt: {
-  //     sharedSecret: process.env.JWT_SECRET,  // Secret for signing/verifying
-  //     issuer: "my-app",                      // Optional: validate 'iss' claim
-  //     audience: "my-users",                  // Optional: validate 'aud' claim
+  //     services: [                            // Array of services that can authenticate
+  //       { issuer: "web-app", secret: process.env.WEB_APP_SECRET },
+  //       { issuer: "mobile-app", secret: process.env.MOBILE_SECRET },
+  //     ],
+  //     audience: "my-api",                    // Optional: validate 'aud' claim
   //   }
   // },
+};
+`, CONFIG_TEMPLATE_SDK = `/**
+ * PostgreSDK Configuration (SDK-Side)
+ *
+ * This file configures how postgresdk pulls a generated SDK from a remote API.
+ *
+ * QUICK START:
+ *   1. Update the 'pull.from' URL below
+ *   2. Run: postgresdk pull
+ *   3. Import and use the SDK!
+ *
+ * CLI COMMANDS:
+ *   postgresdk pull              Pull SDK from a remote API
+ *   postgresdk help              Show help and examples
+ *
+ * Environment variables are automatically loaded from .env files.
+ */
 
-  // ========== SDK DISTRIBUTION (Pull Configuration) ==========
+export default {
+  // ========== SDK PULL CONFIGURATION ==========
 
   /**
    * Configuration for pulling SDK from a remote API
-   * Used when running: postgresdk pull
    */
-  // pull: {
-  //   from: "https://api.myapp.com",     // API URL to pull SDK from
-  //   output: "./src/sdk",                // Local directory for pulled SDK
-  //   token: process.env.API_TOKEN,       // Optional authentication token
-  // },
+  pull: {
+    from: "https://api.myapp.com",     // API URL to pull SDK from
+    output: "./src/sdk",                // Local directory for pulled SDK
+    // token: process.env.API_TOKEN,    // Optional authentication token
+  },
 };
 `;
 var init_cli_init = __esm(() => {
@@ -2333,7 +2399,7 @@ Example config file:`);
   console.log(`\uD83D\uDCC1 Output directory: ${config.output}`);
   try {
     const headers = config.token ? { Authorization: `Bearer ${config.token}` } : {};
-    const manifestRes = await fetch(`${config.from}/sdk/manifest`, { headers });
+    const manifestRes = await fetch(`${config.from}/_psdk/sdk/manifest`, { headers });
     if (!manifestRes.ok) {
       throw new Error(`Failed to fetch SDK manifest: ${manifestRes.status} ${manifestRes.statusText}`);
     }
@@ -2341,7 +2407,7 @@ Example config file:`);
     console.log(`\uD83D\uDCE6 SDK version: ${manifest.version}`);
     console.log(`\uD83D\uDCC5 Generated: ${manifest.generated}`);
     console.log(`\uD83D\uDCC4 Files: ${manifest.files.length}`);
-    const sdkRes = await fetch(`${config.from}/sdk/download`, { headers });
+    const sdkRes = await fetch(`${config.from}/_psdk/sdk/download`, { headers });
     if (!sdkRes.ok) {
       throw new Error(`Failed to download SDK: ${sdkRes.status} ${sdkRes.statusText}`);
     }
@@ -2735,6 +2801,31 @@ export type PaginationParams = z.infer<typeof PaginationParamsSchema>;
 `;
 }
 
+// src/emit-shared-types.ts
+function emitSharedTypes() {
+  return `/**
+ * Shared types used across all SDK operations
+ */
+
+/**
+ * Paginated response structure returned by list operations
+ * @template T - The type of records in the data array
+ */
+export interface PaginatedResponse<T> {
+  /** Array of records for the current page */
+  data: T[];
+  /** Total number of records matching the query (across all pages) */
+  total: number;
+  /** Maximum number of records per page */
+  limit: number;
+  /** Number of records skipped (for pagination) */
+  offset: number;
+  /** Whether there are more records available after this page */
+  hasMore: boolean;
+}
+`;
+}
+
 // src/emit-routes-hono.ts
 init_utils();
 function emitHonoRoutes(table, _graph, opts) {
@@ -2786,7 +2877,7 @@ const listSchema = z.object({
  * @param deps.onRequest - Optional hook that runs before each request (for audit logging, RLS, etc.)
  */
 export function register${Type}Routes(app: Hono, deps: { pg: { query: (text: string, params?: any[]) => Promise<{ rows: any[] }> }, onRequest?: (c: Context, pg: { query: (text: string, params?: any[]) => Promise<{ rows: any[] }> }) => Promise<void> }) {
-  const base = "/v1/${fileTableName}";
+  const base = "${opts.apiPathPrefix}/${fileTableName}";
   
   // Create operation context
   const ctx: coreOps.OperationContext = {
@@ -3003,7 +3094,7 @@ function emitClient(table, graph, opts, model) {
    * @returns The record with nested ${method.path.join(" and ")} if found, null otherwise
    */
   async ${method.name}(pk: ${pkType}): Promise<${method.returnType}> {
-    const results = await this.post<{ data: ${baseReturnType}[]; total: number; limit: number; offset: number; hasMore: boolean; }>(\`\${this.resource}/list\`, {
+    const results = await this.post<PaginatedResponse<${baseReturnType}>>(\`\${this.resource}/list\`, {
       where: ${pkWhere},
       include: ${JSON.stringify(method.includeSpec)},
       limit: 1
@@ -3034,6 +3125,7 @@ function emitClient(table, graph, opts, model) {
  */
 import { BaseClient } from "./base-client${ext}";
 import type { Where } from "./where-types${ext}";
+import type { PaginatedResponse } from "./types/shared${ext}";
 ${typeImports}
 ${otherTableImports.join(`
 `)}
@@ -3081,20 +3173,8 @@ export class ${Type}Client extends BaseClient {
     where?: Where<Select${Type}>;
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
-  }): Promise<{
-    data: Select${Type}[];
-    total: number;
-    limit: number;
-    offset: number;
-    hasMore: boolean;
-  }> {
-    return this.post<{
-      data: Select${Type}[];
-      total: number;
-      limit: number;
-      offset: number;
-      hasMore: boolean;
-    }>(\`\${this.resource}/list\`, params ?? {});
+  }): Promise<PaginatedResponse<Select${Type}>> {
+    return this.post<PaginatedResponse<Select${Type}>>(\`\${this.resource}/list\`, params ?? {});
   }
 
   /**
@@ -3205,6 +3285,11 @@ export type { AuthConfig, HeaderMap, AuthHeadersProvider } from "./base-client${
     out += `export type { Insert${Type}, Update${Type}, Select${Type} } from "./types/${t.name}${ext}";
 `;
   }
+  out += `
+// Shared types
+`;
+  out += `export type { PaginatedResponse } from "./types/shared${ext}";
+`;
   return out;
 }
 
@@ -3845,14 +3930,12 @@ function emitAuth(cfgAuth) {
   const strategy = cfgAuth?.strategy ?? "none";
   const apiKeyHeader = cfgAuth?.apiKeyHeader ?? "x-api-key";
   const apiKeys = cfgAuth?.apiKeys ?? [];
-  const jwtShared = cfgAuth?.jwt?.sharedSecret ?? "";
-  const jwtIssuer = cfgAuth?.jwt?.issuer ?? undefined;
+  const jwtServices = cfgAuth?.jwt?.services ?? [];
   const jwtAudience = cfgAuth?.jwt?.audience ?? undefined;
   const STRATEGY = JSON.stringify(strategy);
   const API_KEY_HEADER = JSON.stringify(apiKeyHeader);
   const RAW_API_KEYS = JSON.stringify(apiKeys);
-  const JWT_SHARED_SECRET = JSON.stringify(jwtShared);
-  const JWT_ISSUER = jwtIssuer === undefined ? "undefined" : JSON.stringify(jwtIssuer);
+  const JWT_SERVICES = JSON.stringify(jwtServices);
   const JWT_AUDIENCE = jwtAudience === undefined ? "undefined" : JSON.stringify(jwtAudience);
   return `/**
  * AUTO-GENERATED FILE - DO NOT EDIT
@@ -3870,8 +3953,7 @@ const STRATEGY = ${STRATEGY} as "none" | "api-key" | "jwt-hs256";
 const API_KEY_HEADER = ${API_KEY_HEADER} as string;
 const RAW_API_KEYS = ${RAW_API_KEYS} as readonly string[];
 
-const JWT_SHARED_SECRET = ${JWT_SHARED_SECRET} as string;
-const JWT_ISSUER = ${JWT_ISSUER} as string | undefined;
+const JWT_SERVICES = ${JWT_SERVICES} as ReadonlyArray<{ issuer: string; secret: string }>;
 const JWT_AUDIENCE = ${JWT_AUDIENCE} as string | undefined;
 // -------------------------------------
 
@@ -3912,7 +3994,12 @@ function resolveKeys(keys: readonly string[]): string[] {
 }
 
 const API_KEYS = resolveKeys(RAW_API_KEYS);
-const HS256_SECRET = resolveValue(JWT_SHARED_SECRET);
+
+// Resolve JWT service secrets from env vars if needed
+const RESOLVED_JWT_SERVICES = JWT_SERVICES.map(svc => ({
+  issuer: svc.issuer,
+  secret: resolveValue(svc.secret)
+}));
 
 // Augment Hono context for DX
 declare module "hono" {
@@ -3956,21 +4043,43 @@ export async function authMiddleware(c: Context, next: Next) {
       }
       const token = m[1];
 
-      if (!HS256_SECRET) {
-        log.error("JWT strategy configured but JWT_SHARED_SECRET is empty");
+      if (!RESOLVED_JWT_SERVICES.length) {
+        log.error("JWT strategy configured but no services defined");
         return c.json({ error: "Unauthorized" }, 401);
       }
 
       // Lazy import 'jose' so projects not using JWT don't need it at runtime.
       try {
-        const { jwtVerify } = await import("jose");
-        const key = new TextEncoder().encode(HS256_SECRET);
-        log.debug("Verifying JWT with secret:", HS256_SECRET ? "present" : "missing");
-        log.debug("Expected issuer:", JWT_ISSUER);
+        const { decodeJwt, jwtVerify } = await import("jose");
+
+        // Decode without verification to extract issuer claim
+        const unverifiedPayload = decodeJwt(token);
+        const issuer = unverifiedPayload.iss;
+
+        if (!issuer) {
+          log.error("JWT missing required 'iss' (issuer) claim");
+          return c.json({ error: "Unauthorized" }, 401);
+        }
+
+        // Find matching service by issuer
+        const service = RESOLVED_JWT_SERVICES.find(s => s.issuer === issuer);
+        if (!service) {
+          log.error("Unknown JWT issuer:", issuer);
+          return c.json({ error: "Unauthorized" }, 401);
+        }
+
+        if (!service.secret) {
+          log.error("JWT service configured but secret is empty for issuer:", issuer);
+          return c.json({ error: "Unauthorized" }, 401);
+        }
+
+        // Verify JWT using the service's secret
+        const key = new TextEncoder().encode(service.secret);
+        log.debug("Verifying JWT from issuer:", issuer);
         log.debug("Expected audience:", JWT_AUDIENCE);
-        
+
         const { payload } = await jwtVerify(token, key, {
-          issuer: JWT_ISSUER || undefined,
+          issuer: issuer,
           audience: JWT_AUDIENCE || undefined,
         });
 
@@ -3980,7 +4089,7 @@ export async function authMiddleware(c: Context, next: Next) {
           sub: typeof payload.sub === "string" ? payload.sub : undefined,
           claims: payload as any,
         });
-        log.debug("JWT verified successfully");
+        log.debug("JWT verified successfully for issuer:", issuer);
         return next();
       } catch (verifyError: any) {
         log.error("JWT verification failed:", verifyError?.message || verifyError);
@@ -4045,10 +4154,22 @@ ${hasAuth ? `export { authMiddleware } from "./auth${ext}";` : ""}
  * const pg = new Client({ connectionString: process.env.DATABASE_URL });
  * await pg.connect();
  *
- * // OR using Neon driver (Edge-compatible)
+ * // OR using Neon driver
  * import { Pool } from "@neondatabase/serverless";
- * const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
- * const pg = pool; // Pool already has the compatible query method
+ *
+ * // For serverless (Vercel/Netlify) - one connection per instance
+ * const pool = new Pool({
+ *   connectionString: process.env.DATABASE_URL!,
+ *   max: 1
+ * });
+ *
+ * // For traditional servers - connection pooling
+ * const pool = new Pool({
+ *   connectionString: process.env.DATABASE_URL!,
+ *   max: 10
+ * });
+ *
+ * const pg = pool;
  *
  * // Mount all generated routes
  * const app = new Hono();
@@ -4080,21 +4201,21 @@ export function createRouter(
   
   // Register table routes
 ${registrations}
-  
+
   // SDK distribution endpoints
-  router.get("/sdk/manifest", (c) => {
+  router.get("/_psdk/sdk/manifest", (c) => {
     return c.json({
       version: SDK_MANIFEST.version,
       generated: SDK_MANIFEST.generated,
       files: Object.keys(SDK_MANIFEST.files)
     });
   });
-  
-  router.get("/sdk/download", (c) => {
+
+  router.get("/_psdk/sdk/download", (c) => {
     return c.json(SDK_MANIFEST);
   });
-  
-  router.get("/sdk/files/:path{.*}", (c) => {
+
+  router.get("/_psdk/sdk/files/:path{.*}", (c) => {
     const path = c.req.param("path");
     const content = SDK_MANIFEST.files[path as keyof typeof SDK_MANIFEST.files];
     if (!content) {
@@ -4104,25 +4225,25 @@ ${registrations}
       "Content-Type": "text/plain; charset=utf-8"
     });
   });
-  
+
   // API Contract endpoints - describes the entire API
-  router.get("/api/contract", (c) => {
+  router.get("/_psdk/contract", (c) => {
     const format = c.req.query("format") || "json";
-    
+
     if (format === "markdown") {
       return c.text(getContract("markdown") as string, 200, {
         "Content-Type": "text/markdown; charset=utf-8"
       });
     }
-    
+
     return c.json(getContract("json"));
   });
-  
-  router.get("/api/contract.json", (c) => {
+
+  router.get("/_psdk/contract.json", (c) => {
     return c.json(getContract("json"));
   });
-  
-  router.get("/api/contract.md", (c) => {
+
+  router.get("/_psdk/contract.md", (c) => {
     return c.text(getContract("markdown") as string, 200, {
       "Content-Type": "text/markdown; charset=utf-8"
     });
@@ -5378,17 +5499,10 @@ function normalizeAuthConfig(input) {
     };
   }
   if ("jwt" in input && input.jwt) {
-    if (typeof input.jwt === "string") {
-      return {
-        strategy: "jwt-hs256",
-        jwt: { sharedSecret: input.jwt }
-      };
-    } else {
-      return {
-        strategy: "jwt-hs256",
-        jwt: input.jwt
-      };
-    }
+    return {
+      strategy: "jwt-hs256",
+      jwt: input.jwt
+    };
   }
   return { strategy: "none" };
 }
@@ -5404,8 +5518,18 @@ async function generate(configPath) {
   const model = await introspect(cfg.connectionString, cfg.schema || "public");
   console.log("\uD83D\uDD17 Building relationship graph...");
   const graph = buildGraph(model);
-  const serverDir = cfg.outServer || "./api/server";
-  const originalClientDir = cfg.outClient || "./api/client";
+  let serverDir;
+  let originalClientDir;
+  if (typeof cfg.outDir === "string") {
+    serverDir = cfg.outDir;
+    originalClientDir = cfg.outDir;
+  } else if (cfg.outDir && typeof cfg.outDir === "object") {
+    serverDir = cfg.outDir.server;
+    originalClientDir = cfg.outDir.client;
+  } else {
+    serverDir = "./api/server";
+    originalClientDir = "./api/client";
+  }
   const sameDirectory = serverDir === originalClientDir;
   let clientDir = originalClientDir;
   if (sameDirectory) {
@@ -5439,6 +5563,7 @@ async function generate(configPath) {
   files.push({ path: join(serverDir, "include-spec.ts"), content: includeSpec });
   files.push({ path: join(clientDir, "include-spec.ts"), content: includeSpec });
   files.push({ path: join(clientDir, "params", "shared.ts"), content: emitSharedParamsZod() });
+  files.push({ path: join(clientDir, "types", "shared.ts"), content: emitSharedTypes() });
   files.push({ path: join(clientDir, "base-client.ts"), content: emitBaseClient() });
   files.push({ path: join(clientDir, "where-types.ts"), content: emitWhereTypes() });
   files.push({
@@ -5475,7 +5600,8 @@ async function generate(configPath) {
         softDeleteColumn: cfg.softDeleteColumn || null,
         includeMethodsDepth: cfg.includeMethodsDepth || 2,
         authStrategy: normalizedAuth?.strategy,
-        useJsExtensions: cfg.useJsExtensions
+        useJsExtensions: cfg.useJsExtensions,
+        apiPathPrefix: cfg.apiPathPrefix || "/v1"
       });
     } else {
       throw new Error(`Framework "${serverFramework}" is not yet supported. Currently only "hono" is available.`);
@@ -5573,6 +5699,17 @@ async function generate(configPath) {
     console.log(`     2. Edit the script to configure your API server startup`);
     console.log(`     3. Run tests: ${testDir}/run-tests.sh`);
   }
+  console.log(`
+\uD83D\uDCDA Usage:`);
+  console.log(`  Server (${serverFramework}):`);
+  console.log(`    import { createRouter } from "./${relative(process.cwd(), serverDir)}/router";`);
+  console.log(`    const api = createRouter({ pg });`);
+  console.log(`    app.route("/", api);`);
+  console.log(`
+  Client:`);
+  console.log(`    import { SDK } from "./${relative(process.cwd(), clientDir)}";`);
+  console.log(`    const sdk = new SDK({ baseUrl: "http://localhost:3000" });`);
+  console.log(`    const users = await sdk.users.list();`);
 }
 
 // src/cli.ts

package/dist/emit-routes-hono.d.ts

@@ -8,4 +8,5 @@ export declare function emitHonoRoutes(table: Table, _graph: Graph, opts: {
     includeMethodsDepth: number;
     authStrategy?: string;
     useJsExtensions?: boolean;
+    apiPathPrefix: string;
 }): string;

package/dist/emit-shared-types.d.ts

@@ -0,0 +1 @@
+export declare function emitSharedTypes(): string;

package/dist/index.js

@@ -577,7 +577,7 @@ function generateIncludeMethods(table, graph, opts, allTables) {
         path: newPath,
         isMany: newIsMany,
         targets: newTargets,
-        returnType: `{ data: (${buildReturnType(baseTableName, newPath, newIsMany, newTargets, graph)})[]; total: number; limit: number; offset: number; hasMore: boolean; }`,
+        returnType: `PaginatedResponse<${buildReturnType(baseTableName, newPath, newIsMany, newTargets, graph)}>`,
         includeSpec: buildIncludeSpec(newPath)
       });
       methods.push({
@@ -617,7 +617,7 @@ function generateIncludeMethods(table, graph, opts, allTables) {
               path: combinedPath,
               isMany: [edge1.kind === "many", edge2.kind === "many"],
               targets: [edge1.target, edge2.target],
-              returnType: `{ data: (Select${pascal(baseTableName)} & { ${type1}; ${type2} })[]; total: number; limit: number; offset: number; hasMore: boolean; }`,
+              returnType: `PaginatedResponse<Select${pascal(baseTableName)} & { ${type1}; ${type2} }>`,
               includeSpec: { [key1]: true, [key2]: true }
             });
             methods.push({
@@ -784,7 +784,7 @@ function generateResourceWithSDK(table, model, graph, config) {
   const endpoints = [];
   sdkMethods.push({
     name: "list",
-    signature: `list(params?: ListParams): Promise<{ data: ${Type}[]; total: number; limit: number; offset: number; hasMore: boolean; }>`,
+    signature: `list(params?: ListParams): Promise<PaginatedResponse<${Type}>>`,
     description: `List ${tableName} with filtering, sorting, and pagination. Returns paginated results with metadata.`,
     example: `// Get all ${tableName}
 const result = await sdk.${tableName}.list();
@@ -811,7 +811,7 @@ const currentPage = Math.floor(filtered.offset / filtered.limit) + 1;`,
     path: basePath,
     description: `List all ${tableName} records with pagination metadata`,
     queryParameters: generateQueryParams(table, enums),
-    responseBody: `{ data: ${Type}[]; total: number; limit: number; offset: number; hasMore: boolean; }`
+    responseBody: `PaginatedResponse<${Type}>`
   });
   if (hasSinglePK) {
     sdkMethods.push({
@@ -1975,6 +1975,31 @@ export type PaginationParams = z.infer<typeof PaginationParamsSchema>;
 `;
 }
 
+// src/emit-shared-types.ts
+function emitSharedTypes() {
+  return `/**
+ * Shared types used across all SDK operations
+ */
+
+/**
+ * Paginated response structure returned by list operations
+ * @template T - The type of records in the data array
+ */
+export interface PaginatedResponse<T> {
+  /** Array of records for the current page */
+  data: T[];
+  /** Total number of records matching the query (across all pages) */
+  total: number;
+  /** Maximum number of records per page */
+  limit: number;
+  /** Number of records skipped (for pagination) */
+  offset: number;
+  /** Whether there are more records available after this page */
+  hasMore: boolean;
+}
+`;
+}
+
 // src/emit-routes-hono.ts
 init_utils();
 function emitHonoRoutes(table, _graph, opts) {
@@ -2026,7 +2051,7 @@ const listSchema = z.object({
  * @param deps.onRequest - Optional hook that runs before each request (for audit logging, RLS, etc.)
  */
 export function register${Type}Routes(app: Hono, deps: { pg: { query: (text: string, params?: any[]) => Promise<{ rows: any[] }> }, onRequest?: (c: Context, pg: { query: (text: string, params?: any[]) => Promise<{ rows: any[] }> }) => Promise<void> }) {
-  const base = "/v1/${fileTableName}";
+  const base = "${opts.apiPathPrefix}/${fileTableName}";
   
   // Create operation context
   const ctx: coreOps.OperationContext = {
@@ -2243,7 +2268,7 @@ function emitClient(table, graph, opts, model) {
    * @returns The record with nested ${method.path.join(" and ")} if found, null otherwise
    */
   async ${method.name}(pk: ${pkType}): Promise<${method.returnType}> {
-    const results = await this.post<{ data: ${baseReturnType}[]; total: number; limit: number; offset: number; hasMore: boolean; }>(\`\${this.resource}/list\`, {
+    const results = await this.post<PaginatedResponse<${baseReturnType}>>(\`\${this.resource}/list\`, {
       where: ${pkWhere},
       include: ${JSON.stringify(method.includeSpec)},
       limit: 1
@@ -2274,6 +2299,7 @@ function emitClient(table, graph, opts, model) {
  */
 import { BaseClient } from "./base-client${ext}";
 import type { Where } from "./where-types${ext}";
+import type { PaginatedResponse } from "./types/shared${ext}";
 ${typeImports}
 ${otherTableImports.join(`
 `)}
@@ -2321,20 +2347,8 @@ export class ${Type}Client extends BaseClient {
     where?: Where<Select${Type}>;
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
-  }): Promise<{
-    data: Select${Type}[];
-    total: number;
-    limit: number;
-    offset: number;
-    hasMore: boolean;
-  }> {
-    return this.post<{
-      data: Select${Type}[];
-      total: number;
-      limit: number;
-      offset: number;
-      hasMore: boolean;
-    }>(\`\${this.resource}/list\`, params ?? {});
+  }): Promise<PaginatedResponse<Select${Type}>> {
+    return this.post<PaginatedResponse<Select${Type}>>(\`\${this.resource}/list\`, params ?? {});
   }
 
   /**
@@ -2445,6 +2459,11 @@ export type { AuthConfig, HeaderMap, AuthHeadersProvider } from "./base-client${
     out += `export type { Insert${Type}, Update${Type}, Select${Type} } from "./types/${t.name}${ext}";
 `;
   }
+  out += `
+// Shared types
+`;
+  out += `export type { PaginatedResponse } from "./types/shared${ext}";
+`;
   return out;
 }
 
@@ -3085,14 +3104,12 @@ function emitAuth(cfgAuth) {
   const strategy = cfgAuth?.strategy ?? "none";
   const apiKeyHeader = cfgAuth?.apiKeyHeader ?? "x-api-key";
   const apiKeys = cfgAuth?.apiKeys ?? [];
-  const jwtShared = cfgAuth?.jwt?.sharedSecret ?? "";
-  const jwtIssuer = cfgAuth?.jwt?.issuer ?? undefined;
+  const jwtServices = cfgAuth?.jwt?.services ?? [];
   const jwtAudience = cfgAuth?.jwt?.audience ?? undefined;
   const STRATEGY = JSON.stringify(strategy);
   const API_KEY_HEADER = JSON.stringify(apiKeyHeader);
   const RAW_API_KEYS = JSON.stringify(apiKeys);
-  const JWT_SHARED_SECRET = JSON.stringify(jwtShared);
-  const JWT_ISSUER = jwtIssuer === undefined ? "undefined" : JSON.stringify(jwtIssuer);
+  const JWT_SERVICES = JSON.stringify(jwtServices);
   const JWT_AUDIENCE = jwtAudience === undefined ? "undefined" : JSON.stringify(jwtAudience);
   return `/**
  * AUTO-GENERATED FILE - DO NOT EDIT
@@ -3110,8 +3127,7 @@ const STRATEGY = ${STRATEGY} as "none" | "api-key" | "jwt-hs256";
 const API_KEY_HEADER = ${API_KEY_HEADER} as string;
 const RAW_API_KEYS = ${RAW_API_KEYS} as readonly string[];
 
-const JWT_SHARED_SECRET = ${JWT_SHARED_SECRET} as string;
-const JWT_ISSUER = ${JWT_ISSUER} as string | undefined;
+const JWT_SERVICES = ${JWT_SERVICES} as ReadonlyArray<{ issuer: string; secret: string }>;
 const JWT_AUDIENCE = ${JWT_AUDIENCE} as string | undefined;
 // -------------------------------------
 
@@ -3152,7 +3168,12 @@ function resolveKeys(keys: readonly string[]): string[] {
 }
 
 const API_KEYS = resolveKeys(RAW_API_KEYS);
-const HS256_SECRET = resolveValue(JWT_SHARED_SECRET);
+
+// Resolve JWT service secrets from env vars if needed
+const RESOLVED_JWT_SERVICES = JWT_SERVICES.map(svc => ({
+  issuer: svc.issuer,
+  secret: resolveValue(svc.secret)
+}));
 
 // Augment Hono context for DX
 declare module "hono" {
@@ -3196,21 +3217,43 @@ export async function authMiddleware(c: Context, next: Next) {
       }
       const token = m[1];
 
-      if (!HS256_SECRET) {
-        log.error("JWT strategy configured but JWT_SHARED_SECRET is empty");
+      if (!RESOLVED_JWT_SERVICES.length) {
+        log.error("JWT strategy configured but no services defined");
         return c.json({ error: "Unauthorized" }, 401);
       }
 
       // Lazy import 'jose' so projects not using JWT don't need it at runtime.
       try {
-        const { jwtVerify } = await import("jose");
-        const key = new TextEncoder().encode(HS256_SECRET);
-        log.debug("Verifying JWT with secret:", HS256_SECRET ? "present" : "missing");
-        log.debug("Expected issuer:", JWT_ISSUER);
+        const { decodeJwt, jwtVerify } = await import("jose");
+
+        // Decode without verification to extract issuer claim
+        const unverifiedPayload = decodeJwt(token);
+        const issuer = unverifiedPayload.iss;
+
+        if (!issuer) {
+          log.error("JWT missing required 'iss' (issuer) claim");
+          return c.json({ error: "Unauthorized" }, 401);
+        }
+
+        // Find matching service by issuer
+        const service = RESOLVED_JWT_SERVICES.find(s => s.issuer === issuer);
+        if (!service) {
+          log.error("Unknown JWT issuer:", issuer);
+          return c.json({ error: "Unauthorized" }, 401);
+        }
+
+        if (!service.secret) {
+          log.error("JWT service configured but secret is empty for issuer:", issuer);
+          return c.json({ error: "Unauthorized" }, 401);
+        }
+
+        // Verify JWT using the service's secret
+        const key = new TextEncoder().encode(service.secret);
+        log.debug("Verifying JWT from issuer:", issuer);
         log.debug("Expected audience:", JWT_AUDIENCE);
-        
+
         const { payload } = await jwtVerify(token, key, {
-          issuer: JWT_ISSUER || undefined,
+          issuer: issuer,
           audience: JWT_AUDIENCE || undefined,
         });
 
@@ -3220,7 +3263,7 @@ export async function authMiddleware(c: Context, next: Next) {
           sub: typeof payload.sub === "string" ? payload.sub : undefined,
           claims: payload as any,
         });
-        log.debug("JWT verified successfully");
+        log.debug("JWT verified successfully for issuer:", issuer);
         return next();
       } catch (verifyError: any) {
         log.error("JWT verification failed:", verifyError?.message || verifyError);
@@ -3285,10 +3328,22 @@ ${hasAuth ? `export { authMiddleware } from "./auth${ext}";` : ""}
  * const pg = new Client({ connectionString: process.env.DATABASE_URL });
  * await pg.connect();
  *
- * // OR using Neon driver (Edge-compatible)
+ * // OR using Neon driver
  * import { Pool } from "@neondatabase/serverless";
- * const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
- * const pg = pool; // Pool already has the compatible query method
+ *
+ * // For serverless (Vercel/Netlify) - one connection per instance
+ * const pool = new Pool({
+ *   connectionString: process.env.DATABASE_URL!,
+ *   max: 1
+ * });
+ *
+ * // For traditional servers - connection pooling
+ * const pool = new Pool({
+ *   connectionString: process.env.DATABASE_URL!,
+ *   max: 10
+ * });
+ *
+ * const pg = pool;
  *
  * // Mount all generated routes
  * const app = new Hono();
@@ -3320,21 +3375,21 @@ export function createRouter(
   
   // Register table routes
 ${registrations}
-  
+
   // SDK distribution endpoints
-  router.get("/sdk/manifest", (c) => {
+  router.get("/_psdk/sdk/manifest", (c) => {
     return c.json({
       version: SDK_MANIFEST.version,
       generated: SDK_MANIFEST.generated,
       files: Object.keys(SDK_MANIFEST.files)
     });
   });
-  
-  router.get("/sdk/download", (c) => {
+
+  router.get("/_psdk/sdk/download", (c) => {
     return c.json(SDK_MANIFEST);
   });
-  
-  router.get("/sdk/files/:path{.*}", (c) => {
+
+  router.get("/_psdk/sdk/files/:path{.*}", (c) => {
     const path = c.req.param("path");
     const content = SDK_MANIFEST.files[path as keyof typeof SDK_MANIFEST.files];
     if (!content) {
@@ -3344,25 +3399,25 @@ ${registrations}
       "Content-Type": "text/plain; charset=utf-8"
     });
   });
-  
+
   // API Contract endpoints - describes the entire API
-  router.get("/api/contract", (c) => {
+  router.get("/_psdk/contract", (c) => {
     const format = c.req.query("format") || "json";
-    
+
     if (format === "markdown") {
       return c.text(getContract("markdown") as string, 200, {
         "Content-Type": "text/markdown; charset=utf-8"
       });
     }
-    
+
     return c.json(getContract("json"));
   });
-  
-  router.get("/api/contract.json", (c) => {
+
+  router.get("/_psdk/contract.json", (c) => {
     return c.json(getContract("json"));
   });
-  
-  router.get("/api/contract.md", (c) => {
+
+  router.get("/_psdk/contract.md", (c) => {
     return c.text(getContract("markdown") as string, 200, {
       "Content-Type": "text/markdown; charset=utf-8"
     });
@@ -4618,17 +4673,10 @@ function normalizeAuthConfig(input) {
     };
   }
   if ("jwt" in input && input.jwt) {
-    if (typeof input.jwt === "string") {
-      return {
-        strategy: "jwt-hs256",
-        jwt: { sharedSecret: input.jwt }
-      };
-    } else {
-      return {
-        strategy: "jwt-hs256",
-        jwt: input.jwt
-      };
-    }
+    return {
+      strategy: "jwt-hs256",
+      jwt: input.jwt
+    };
   }
   return { strategy: "none" };
 }
@@ -4644,8 +4692,18 @@ async function generate(configPath) {
   const model = await introspect(cfg.connectionString, cfg.schema || "public");
   console.log("\uD83D\uDD17 Building relationship graph...");
   const graph = buildGraph(model);
-  const serverDir = cfg.outServer || "./api/server";
-  const originalClientDir = cfg.outClient || "./api/client";
+  let serverDir;
+  let originalClientDir;
+  if (typeof cfg.outDir === "string") {
+    serverDir = cfg.outDir;
+    originalClientDir = cfg.outDir;
+  } else if (cfg.outDir && typeof cfg.outDir === "object") {
+    serverDir = cfg.outDir.server;
+    originalClientDir = cfg.outDir.client;
+  } else {
+    serverDir = "./api/server";
+    originalClientDir = "./api/client";
+  }
   const sameDirectory = serverDir === originalClientDir;
   let clientDir = originalClientDir;
   if (sameDirectory) {
@@ -4679,6 +4737,7 @@ async function generate(configPath) {
   files.push({ path: join(serverDir, "include-spec.ts"), content: includeSpec });
   files.push({ path: join(clientDir, "include-spec.ts"), content: includeSpec });
   files.push({ path: join(clientDir, "params", "shared.ts"), content: emitSharedParamsZod() });
+  files.push({ path: join(clientDir, "types", "shared.ts"), content: emitSharedTypes() });
   files.push({ path: join(clientDir, "base-client.ts"), content: emitBaseClient() });
   files.push({ path: join(clientDir, "where-types.ts"), content: emitWhereTypes() });
   files.push({
@@ -4715,7 +4774,8 @@ async function generate(configPath) {
         softDeleteColumn: cfg.softDeleteColumn || null,
         includeMethodsDepth: cfg.includeMethodsDepth || 2,
         authStrategy: normalizedAuth?.strategy,
-        useJsExtensions: cfg.useJsExtensions
+        useJsExtensions: cfg.useJsExtensions,
+        apiPathPrefix: cfg.apiPathPrefix || "/v1"
       });
     } else {
       throw new Error(`Framework "${serverFramework}" is not yet supported. Currently only "hono" is available.`);
@@ -4813,6 +4873,17 @@ async function generate(configPath) {
     console.log(`     2. Edit the script to configure your API server startup`);
     console.log(`     3. Run tests: ${testDir}/run-tests.sh`);
   }
+  console.log(`
+\uD83D\uDCDA Usage:`);
+  console.log(`  Server (${serverFramework}):`);
+  console.log(`    import { createRouter } from "./${relative(process.cwd(), serverDir)}/router";`);
+  console.log(`    const api = createRouter({ pg });`);
+  console.log(`    app.route("/", api);`);
+  console.log(`
+  Client:`);
+  console.log(`    import { SDK } from "./${relative(process.cwd(), clientDir)}";`);
+  console.log(`    const sdk = new SDK({ baseUrl: "http://localhost:3000" });`);
+  console.log(`    const users = await sdk.users.list();`);
 }
 export {
   generate

package/dist/types.d.ts

@@ -3,8 +3,10 @@ export interface AuthConfig {
     apiKeyHeader?: string;
     apiKeys?: string[];
     jwt?: {
-        sharedSecret?: string;
-        issuer?: string;
+        services: Array<{
+            issuer: string;
+            secret: string;
+        }>;
         audience?: string;
     };
 }
@@ -12,22 +14,20 @@ export type AuthConfigInput = AuthConfig | {
     apiKey?: string;
     apiKeys?: string[];
     apiKeyHeader?: string;
-    jwt?: string | {
-        sharedSecret?: string;
-        issuer?: string;
-        audience?: string;
-    };
 };
 export interface Config {
     connectionString: string;
     schema?: string;
-    outServer?: string;
-    outClient?: string;
+    outDir?: string | {
+        client: string;
+        server: string;
+    };
     softDeleteColumn?: string | null;
     dateType?: "date" | "string";
     includeMethodsDepth?: number;
     skipJunctionTables?: boolean;
     serverFramework?: "hono" | "express" | "fastify";
+    apiPathPrefix?: string;
     auth?: AuthConfigInput;
     pull?: PullConfig;
     useJsExtensions?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresdk",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Generate a typed server/client SDK from a Postgres schema (includes, Zod, Hono).",
   "type": "module",
   "bin": {
@@ -45,14 +45,14 @@
     "zod": "^4.0.15"
   },
   "devDependencies": {
+    "@hono/node-server": "^1.19.7",
     "@types/bun": "^1.2.20",
     "@types/node": "^20.0.0",
     "@types/pg": "^8.15.5",
     "drizzle-kit": "^0.31.4",
     "drizzle-orm": "^0.44.4",
     "jose": "^6.0.12",
-    "typescript": "^5.5.0",
-    "vitest": "^3.2.4"
+    "typescript": "^5.5.0"
   },
   "author": "Ben Honda <ben@theadpharm.com>",
   "license": "MIT",