postgresdk 0.13.1 → 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

@@ -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}`);
     }
@@ -2811,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 = {
@@ -3864,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
@@ -3889,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;
 // -------------------------------------
 
@@ -3931,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" {
@@ -3975,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,
         });
 
@@ -3999,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);
@@ -4064,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();
@@ -4099,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) {
@@ -4123,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"
     });
@@ -5397,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" };
 }
@@ -5423,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) {
@@ -5495,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.`);
@@ -5593,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/index.js

@@ -2051,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 = {
@@ -3104,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
@@ -3129,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;
 // -------------------------------------
 
@@ -3171,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" {
@@ -3215,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,
         });
 
@@ -3239,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);
@@ -3304,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();
@@ -3339,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) {
@@ -3363,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"
     });
@@ -4637,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" };
 }
@@ -4663,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) {
@@ -4735,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.`);
@@ -4833,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.1",
+  "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",