dengzhaofun
diff --git a/‎apps/admin/src/lib/api-client.ts‎
Lines changed: 126 additions & 11 deletions b/‎apps/admin/src/lib/api-client.ts‎
Lines changed: 126 additions & 11 deletions
diff --git a/‎apps/server/CLAUDE.md‎
Lines changed: 113 additions & 16 deletions b/‎apps/server/CLAUDE.md‎
Lines changed: 113 additions & 16 deletions
diff --git a/‎apps/server/src/db.ts‎
Lines changed: 2 additions & 1 deletion b/‎apps/server/src/db.ts‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎apps/server/src/index.ts‎
Lines changed: 18 additions & 6 deletions b/‎apps/server/src/index.ts‎
Lines changed: 18 additions & 6 deletions
@@ -1,14 +1,114 @@
+/**
+ * Thin HTTP client for the server's `/api/*` business routes.
+ *
+ * Every business endpoint returns the standard envelope:
+ *   { code: string, data: T | null, message: string, requestId: string }
+ *
+ * This wrapper unwraps `.data` on success, so hooks and routes can
+ * stay on their original typings — e.g. `useQuery` still receives the
+ * resource object / `{ items }` list, not the envelope.
+ *
+ * Errors are normalized into `ApiError` whose `body.error` mirrors the
+ * envelope's `message` for backward compatibility (dozens of existing
+ * toast call sites read `err.body.error`). New code can prefer
+ * `err.message`, `err.code`, or `err.requestId` directly.
+ *
+ * NOTE: Better Auth (`/api/auth/*`) uses its own client in
+ * `lib/auth-client.ts` and does NOT go through this wrapper — so the
+ * envelope assumption is safe here.
+ */
+
 const BASE_URL =
   import.meta.env.VITE_AUTH_SERVER_URL ?? "http://localhost:8787"
 
+type ApiErrorBody = {
+  /** Backward-compat alias for `message`. */
+  error: string
+  code: string
+  message: string
+  requestId: string
+}
+
 export class ApiError extends Error {
   constructor(
     public status: number,
-    public body: { error: string; code?: string },
+    public body: ApiErrorBody,
   ) {
-    super(body.error)
+    super(body.message || body.error)
     this.name = "ApiError"
   }
+
+  get code(): string {
+    return this.body.code
+  }
+
+  get requestId(): string {
+    return this.body.requestId
+  }
+}
+
+type SuccessEnvelope<T> = {
+  code: "ok"
+  data: T | null
+  message: string
+  requestId: string
+}
+
+type ErrorEnvelope = {
+  code: string
+  data: null
+  message: string
+  requestId: string
+}
+
+type AnyEnvelope<T> = SuccessEnvelope<T> | ErrorEnvelope
+
+function isEnvelope(value: unknown): value is AnyEnvelope<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "code" in value &&
+    typeof (value as { code: unknown }).code === "string" &&
+    "requestId" in value
+  )
+}
+
+function toErrorBody(status: number, parsed: unknown): ApiErrorBody {
+  if (isEnvelope(parsed)) {
+    return {
+      error: parsed.message,
+      code: parsed.code,
+      message: parsed.message,
+      requestId: parsed.requestId,
+    }
+  }
+  // Fallback for non-envelope error bodies (e.g. unexpected 5xx from a
+  // proxy, or legacy endpoint that slipped through). Preserve whatever
+  // text/JSON we got so the toast still shows something useful.
+  const fallbackMessage =
+    typeof parsed === "string"
+      ? parsed
+      : parsed && typeof parsed === "object" && "error" in parsed &&
+        typeof (parsed as { error: unknown }).error === "string"
+        ? (parsed as { error: string }).error
+        : `Request failed with status ${status}`
+  return {
+    error: fallbackMessage,
+    code: "http_error",
+    message: fallbackMessage,
+    requestId: "",
+  }
+}
+
+async function parseBody(res: Response): Promise<unknown> {
+  if (res.status === 204) return undefined
+  const text = await res.text()
+  if (!text) return undefined
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
 }
 
 async function request<T>(
@@ -24,15 +124,22 @@ async function request<T>(
     },
   })
 
-  if (res.status === 204) return undefined as T
-
-  const body = await res.json()
+  const parsed = await parseBody(res)
 
   if (!res.ok) {
-    throw new ApiError(res.status, body)
+    throw new ApiError(res.status, toErrorBody(res.status, parsed))
   }
 
-  return body as T
+  if (parsed === undefined) {
+    return undefined as T
+  }
+
+  // Unwrap envelope; non-envelope responses (shouldn't happen after
+  // the server-side migration, but just in case) fall through as-is.
+  if (isEnvelope(parsed)) {
+    return parsed.data as T
+  }
+  return parsed as T
 }
 
 /**
@@ -55,12 +162,20 @@ async function uploadFormData<T>(
     credentials: "include",
     body: form,
   })
-  if (res.status === 204) return undefined as T
-  const body = await res.json()
+
+  const parsed = await parseBody(res)
+
   if (!res.ok) {
-    throw new ApiError(res.status, body)
+    throw new ApiError(res.status, toErrorBody(res.status, parsed))
+  }
+
+  if (parsed === undefined) {
+    return undefined as T
+  }
+  if (isEnvelope(parsed)) {
+    return parsed.data as T
   }
-  return body as T
+  return parsed as T
 }
 
 export const api = {
 
@@ -168,26 +168,123 @@ Do **not** mount it globally on `app` in `src/index.ts`. Future public
 routes (API-key / JWT auth for tenant frontends) must be free of
 `requireAuth`, and a global mount would quietly break them.
 
-## Error handling — throw, map in router `onError`
+## Response envelope — every business endpoint returns `{code, data, message, requestId}`
+
+All business routes (everything under `/api/*` EXCEPT the Better Auth
+mounts `/api/auth/*` and `/api/client/auth/*`, which are third-party
+owned) return the standard envelope from
+`src/lib/response.ts`:
+
+```jsonc
+// success
+{ "code": "ok", "data": <payload>, "message": "", "requestId": "..." }
+// business error (HTTP 4xx)
+{ "code": "check_in.config_not_found", "data": null, "message": "...", "requestId": "..." }
+// validation error (HTTP 400)
+{ "code": "validation_error", "data": null, "message": "...", "requestId": "..." }
+// unhandled (HTTP 500)
+{ "code": "internal_error", "data": null, "message": "...", "requestId": "..." }
+```
 
-Routes throw `ModuleError` subclasses from handlers. Each router
-declares an `onError` that maps them:
+HTTP status codes follow REST: success 2xx, business/validation 4xx,
+unhandled 5xx. Deletes and other "no payload" endpoints return HTTP
+200 with `data: null` — NEVER 204, so the SDK/frontend unwrap logic
+doesn't have to branch on status.
 
-```ts
-checkInRouter.onError((err, c) => {
-  if (err instanceof ModuleError) {
-    return c.json(
-      { error: err.message, code: err.code, requestId: c.get("requestId") },
-      err.httpStatus as ContentfulStatusCode,
-    );
-  }
-  throw err; // global app.onError → 500
-});
-```
+### How to write a route
+
+1. Build the router with a factory from `lib/openapi.ts`, NOT
+   `new OpenAPIHono<HonoEnv>()`:
+
+   ```ts
+   import { createAdminRouter } from "../../lib/openapi";
+   export const checkInRouter = createAdminRouter();
+   ```
+
+   Three factories exist — pick the one that matches the route's auth:
+   - `createAdminRouter()` — admin dashboard (session or `ak_`).
+   - `createClientRouter()` — end-user `cpk_` + HMAC.
+   - `createPublicRouter()` — unauthenticated (health, etc).
+
+   Each factory wires:
+   - `defaultHook` — Zod validation failures become the envelope with
+     `code: "validation_error"`, HTTP 400.
+   - `onError` — `ModuleError` instances become the envelope with the
+     subclass's `code` and `httpStatus`. Unknown errors rethrow to the
+     global `app.onError` which returns a 500 envelope.
+
+   **Do not** write a `router.onError(...)` block in a module — the
+   factory owns that. If you need module-specific error handling,
+   extend `ModuleError` with a new subclass.
+
+2. Declare each route with the matching `createXxxRoute` wrapper
+   (adds `security` + `operationId`) and wrap every success response
+   schema in `envelopeOf(...)`:
+
+   ```ts
+   import { createAdminRoute } from "../../lib/openapi";
+   import { envelopeOf, commonErrorResponses, NullDataEnvelopeSchema } from "../../lib/response";
+
+   createAdminRoute({
+     method: "get",
+     path: "/configs/{id}",
+     responses: {
+       200: {
+         description: "OK",
+         content: { "application/json": { schema: envelopeOf(CheckInConfigResponseSchema) } },
+       },
+       ...commonErrorResponses,  // 400 / 401 / 403 / 404 / 409 / 500
+     },
+   });
+
+   // For delete / ack — 200 + null data (do NOT use 204)
+   createAdminRoute({
+     method: "delete",
+     path: "/configs/{id}",
+     responses: {
+       200: {
+         description: "Deleted",
+         content: { "application/json": { schema: NullDataEnvelopeSchema } },
+       },
+       ...commonErrorResponses,
+     },
+   });
+   ```
+
+   This keeps the emitted OpenAPI spec honest about the wire format,
+   so the generated SDK types in `packages/sdk-*-ts` are accurate.
+
+3. Wrap every handler return in `ok(...)`:
+
+   ```ts
+   import { ok } from "../../lib/response";
+
+   return c.json(ok(serializeConfig(row)), 201);
+   return c.json(ok({ items: rows.map(serializeConfig) }), 200);
+   return c.json(ok(null), 200);  // delete / ack
+   ```
+
+   `ok()` reads `requestId` from the `requestContext` AsyncLocalStorage —
+   the handler doesn't need to pass anything.
+
+4. **Do not** define a per-module `ErrorResponseSchema` in
+   `validators.ts`. The shared `ErrorEnvelopeSchema` in
+   `lib/response.ts` is what every 4xx/5xx response points at.
+
+### Why not wrap via middleware?
+
+A response-rewriting middleware would be smaller code, but the emitted
+OpenAPI spec would still declare the unwrapped payload as the response
+body — which would make every generated SDK type wrong. The explicit
+`envelopeOf(schema)` at the declaration site is the price we pay for
+accurate SDK contracts.
+
+### Don't try to return `c.json(..., err.httpStatus)` inline per handler
 
-Don't try to return `c.json(..., err.httpStatus)` inline per handler:
 `@hono/zod-openapi` requires every status literal to match a specific
-declared response, and a runtime-typed status won't narrow.
+declared response, and a runtime-typed status won't narrow. Throw
+`ModuleError` subclasses and let the router factory's `onError`
+translate them.
 
 ## Event history belongs to the unified behavior log (not here)
 
 
@@ -2,6 +2,7 @@ import { env } from "cloudflare:workers";
 import { neon } from "@neondatabase/serverless";
 import { upstashCache } from "drizzle-orm/cache/upstash";
 import { drizzle as drizzleNeon, type NeonHttpDatabase } from "drizzle-orm/neon-http";
+import type { Pool as PgPool } from "pg";
 
 import * as schema from "./schema";
 
@@ -87,7 +88,7 @@ export const db: NeonHttpDatabase<typeof schema> = isNeon
         async end() {},
       };
       const drz = drizzle({
-        client: poolShim as unknown as pg.Pool,
+        client: poolShim as unknown as PgPool,
         schema,
         cache,
       });
 
@@ -11,6 +11,7 @@ import { endUserAuth, EU_ORG_ID_HEADER } from "./end-user-auth";
 import type { HonoEnv } from "./env";
 import { registerSecuritySchemes, validationDefaultHook } from "./lib/openapi";
 import { requestContext } from "./lib/request-context";
+import { INTERNAL_ERROR_CODE, NOT_FOUND_CODE, fail } from "./lib/response";
 import { requireClientCredential } from "./middleware/require-client-credential";
 import { requestLog } from "./middleware/request-log";
 import { session } from "./middleware/session";
@@ -127,15 +128,26 @@ app.use(
   }),
 );
 
-// Global error handler
+// Global error handler — returns the standard envelope. Module-level
+// routers handle `ModuleError` in their own `onError` (installed by
+// `createAdminRouter` / `createClientRouter` in `lib/openapi.ts`);
+// anything that reaches here is unexpected.
 app.onError((err, c) => {
   console.error(err);
-  return c.json(
-    { error: err.message, requestId: c.get("requestId") },
-    500,
-  );
+  return c.json(fail(INTERNAL_ERROR_CODE, err.message), 500);
 });
 
+// Global 404 — fires when no route matched at all (Hono's default is
+// `404 Not Found` plain text). Business module routers already cover
+// their own sub-paths; Better Auth's `/api/auth/*` and
+// `/api/client/auth/*` wildcards claim those prefixes. Anything that
+// still lands here is an unknown URL, so we return the standard
+// envelope so SDKs / frontend wrappers don't have to branch on
+// content-type.
+app.notFound((c) =>
+  c.json(fail(NOT_FOUND_CODE, `Not found: ${c.req.method} ${c.req.path}`), 404),
+);
+
 // Better Auth — handle all /api/auth/* routes (uses module-level auth instance)
 app.on(["POST", "GET"], "/api/auth/*", (c) => auth.handler(c.req.raw));
 
@@ -265,7 +277,7 @@ app.doc31("/openapi.json", {
       "apollokit is a multi-tenant game-SaaS backend. Routes are split into\n\n" +
       "- **Admin** (`/api/<module>/...`): used by SaaS operators from the admin dashboard. Authenticate with a Better Auth session cookie or an admin API key (`Authorization: Bearer ak_…`).\n" +
       "- **Client** (`/api/client/<module>/...`): consumed by tenant frontends on behalf of end users. Authenticate with a client public key (`X-Client-Public-Key: cpk_…`) plus HMAC headers (`X-Client-Signature`, `X-Client-Timestamp`, `X-Client-Nonce`).\n\n" +
-      "Validation errors return HTTP 400 with `{ error, code: \"VALIDATION_ERROR\", issues, requestId }`. Domain errors return their declared status with `{ error, code, requestId }`.",
+      "Every business endpoint returns the standard envelope `{ code, data, message, requestId }`. Success uses `code: \"ok\"` and the payload in `data`. Validation errors use HTTP 400 and `code: \"validation_error\"`. Domain errors use the module-specific `code` (e.g. `check_in.config_not_found`) at their declared HTTP status. Better Auth routes (`/api/auth/*`, `/api/client/auth/*`) keep the third-party library's native format.",
   },
   servers: [{ url: "http://localhost:8787", description: "Dev" }],
 });