tempest-react-sdk 0.8.0 → 0.9.0

package/README.md

@@ -96,11 +96,11 @@ cd my-app
 npm install
 npm run dev
 
-# want it installable + web-push ready? add --pwa
+# want it installable + web-push + offline ready? add --pwa
 npx -p tempest-react-sdk create-tempest-app my-app --pwa
 ```
 
-The `--pwa` flag overlays a manifest, a service worker built from `tempest-react-sdk/sw`, and push wiring (`usePushSubscription` + `useBeforeInstallPrompt`) on top of the base app — no `vite-plugin-pwa`. See [Scaffold › PWA mode](https://mauriciobenjamin700.github.io/tempest-react-sdk/scaffold/#modo-pwa-pwa).
+The `--pwa` flag overlays a manifest, install prompt (`useBeforeInstallPrompt`), push wiring (`usePushSubscription`), **offline caching** (app-shell precache + runtime caching), **generated icons** (`tempestPwaIcons`, via `sharp`) and a **dev-mode service worker** (`tempestPwaDevSw`) on top of the base app — full `vite-plugin-pwa` parity for the common case, built from `tempest-react-sdk/sw` + `tempest-react-sdk/vite`, with no `vite-plugin-pwa`. See [Scaffold › PWA mode](https://mauriciobenjamin700.github.io/tempest-react-sdk/scaffold/#modo-pwa-pwa).
 
 Already have a project? Install the SDK, then scaffold `src/` + configs into it:
 
@@ -203,12 +203,12 @@ Every module is re-exported from the package root — `import { Button, useDebou
 | `router` _(dep: `react-router-dom`)_         | `defineRoutes`, `AppRouter`, `RouteGuard`, + re-exports (`Link`, `NavLink`, `Outlet`, `Navigate`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`, `useMatch`, `useRouteError`, `redirect`, `BrowserRouter`/`HashRouter`/`MemoryRouter`/`Routes`/`Route`), types: `TempestRouteObject`, `RouterKind`, `AppRouterProps`, `RouteGuardProps`                                                                                                                                                                                                                               |
 | `store` _(dep: `zustand`)_                   | `createStore`, `createSelectors`, types: `CreateStoreOptions`, `CreateStorePersistOptions`, `WithSelectors`                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `app`                                        | `AppProviders` (composes `ErrorBoundary` → `QueryProvider` → `ThemeProvider` → `I18nProvider`), type: `AppProvidersProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `vite` _(subpath `tempest-react-sdk/vite`)_  | `createViteConfig`, types: `CreateViteConfigOptions`, `ProxyEntry`, `TempestViteConfig`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `vite` _(subpath `tempest-react-sdk/vite`)_  | `createViteConfig`, `tempestPwaManifest` (emits `precache-manifest.json` for offline precache), `tempestPwaIcons` (generates the PNG icon set from one SVG via `sharp`), `tempestPwaDevSw` (serves the SW under `npm run dev`), `tempestPwaIcons({ appleSplash })` (Apple splash screens), types: `CreateViteConfigOptions`, `ProxyEntry`, `TempestViteConfig`, `TempestPwaManifestOptions`, `TempestPwaIconsOptions`, `TempestPwaDevSwOptions`, `AppleSplashSpec`, `TempestVitePlugin`                                                                                              |
 | `forms` _(peer: `zod`, `react-hook-form`)_   | `validateForm`, `zodResolver`, `useZodForm`, `validateCPF`, `validateCNPJ`, `formatCEP`, `formatCNPJ`, `unmask`, `CPFInput`, `CNPJInput`, `PhoneInput`, `CEPInput`, `MoneyInput`, `useViaCEP`                                                                                                                                                                                                                                                                                                                                                                                        |
 | `sse`                                        | `createEventStream`, `useEventStream`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `ws`                                         | `createWebSocket`, `useWebSocket`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `push`                                       | `WebPushClient`, `WebPushUnsupportedError`, `WebPushPermissionDeniedError`, `usePushSubscription`, `urlBase64ToUint8Array`, `isPushSupported`                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `sw` _(also subpath `tempest-react-sdk/sw`)_ | `registerServiceWorker`, `skipWaiting`, `unregisterAllServiceWorkers`, `installPushHandler`, `installNotificationClickHandler`, `installSkipWaitingListener` — the React-free `tempest-react-sdk/sw` subpath is ideal for bundling into your own `sw.ts`                                                                                                                                                                                                                                                                                                                             |
+| `sw` _(also subpath `tempest-react-sdk/sw`)_ | `registerServiceWorker`, `skipWaiting`, `unregisterAllServiceWorkers`, `installPushHandler`, `installNotificationClickHandler`, `installSkipWaitingListener`, `installPrecache` (app-shell offline), `installRuntimeCache` (per-route caching, incl. `rangeRequests`), `createPartialResponse` (206 range slicing), `installBackgroundSync` (offline mutation queue) — the React-free `tempest-react-sdk/sw` subpath is ideal for bundling into your own `sw.ts`                                                                                                                     |
 | `audio`                                      | `createAudioPlayer`, `playAudio`, `stopAudio`, `useAudio`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `offline` _(peer: `dexie`)_                  | `createOfflineStore`, types: `OfflineStore`, `OfflineStoreConfig`, `ListOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `error-boundary`                             | `ErrorBoundary`, `useErrorHandler`, types: `ErrorBoundaryProps`, `ErrorBoundaryRenderProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

package/bin/lib/openapi/generate.mjs

@@ -0,0 +1,259 @@
+// OpenAPI 3.x → per-tag { schemas.ts (Zod), types.ts, service.ts (class) }.
+// Pure: takes the parsed spec object, returns a { path: contents } map. No I/O.
+import { refName, zodName, schemaToZod } from "./schema-to-zod.mjs";
+
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete"];
+
+/** Slug a tag into a folder/identifier-safe base ("User Profiles" → "user-profiles"). */
+function tagSlug(tag) {
+    return (
+        tag
+            .trim()
+            .replace(/[^a-zA-Z0-9]+/g, "-")
+            .replace(/^-+|-+$/g, "")
+            .toLowerCase() || "default"
+    );
+}
+
+/** PascalCase for class names ("user-profiles" → "UserProfiles"). */
+function pascal(s) {
+    return s.replace(/(^|[^a-zA-Z0-9])([a-zA-Z0-9])/g, (_, _b, ch) => ch.toUpperCase());
+}
+
+/** camelCase method name from operationId or method+path. */
+function methodName(op, method, path) {
+    if (op.operationId) {
+        const id = op.operationId.replace(/[^a-zA-Z0-9]+(.)?/g, (_, ch) =>
+            ch ? ch.toUpperCase() : "",
+        );
+        return id.charAt(0).toLowerCase() + id.slice(1);
+    }
+    const parts = path
+        .split("/")
+        .filter(Boolean)
+        .map((p) => p.replace(/[{}]/g, ""));
+    return method + parts.map((p) => pascal(p)).join("");
+}
+
+/** Collect component-schema names referenced (transitively) by a schema node. */
+function collectRefs(node, schemas, acc = new Set(), seen = new Set()) {
+    if (!node || typeof node !== "object") return acc;
+    if (node.$ref) {
+        const name = refName(node.$ref);
+        if (!acc.has(name)) {
+            acc.add(name);
+            if (!seen.has(name)) {
+                seen.add(name);
+                collectRefs(schemas[name], schemas, acc, seen);
+            }
+        }
+        return acc;
+    }
+    for (const v of Object.values(node)) {
+        if (v && typeof v === "object") collectRefs(v, schemas, acc, seen);
+    }
+    return acc;
+}
+
+/** TS type expression for a schema node (uses generated type names for $refs). */
+function tsType(schema) {
+    if (!schema || typeof schema !== "object") return "unknown";
+    if (schema.$ref) return refName(schema.$ref);
+    if (schema.allOf) return schema.allOf.map(tsType).join(" & ");
+    if (schema.anyOf || schema.oneOf) return (schema.anyOf ?? schema.oneOf).map(tsType).join(" | ");
+    const t = Array.isArray(schema.type) ? schema.type.find((x) => x !== "null") : schema.type;
+    const nul = (Array.isArray(schema.type) && schema.type.includes("null")) || schema.nullable;
+    let base;
+    switch (t) {
+        case "string":
+            base = Array.isArray(schema.enum)
+                ? schema.enum.map((v) => JSON.stringify(v)).join(" | ")
+                : "string";
+            break;
+        case "integer":
+        case "number":
+            base = "number";
+            break;
+        case "boolean":
+            base = "boolean";
+            break;
+        case "array":
+            base = `${tsType(schema.items)}[]`;
+            break;
+        case "object":
+        default:
+            base = "Record<string, unknown>";
+    }
+    return nul ? `${base} | null` : base;
+}
+
+/** Topologically sort schema names so dependencies are declared first. */
+function topoSort(names, schemas) {
+    const sorted = [];
+    const visited = new Set();
+    const onStack = new Set();
+    const cyclic = new Set();
+    function visit(name) {
+        if (visited.has(name)) return;
+        if (onStack.has(name)) {
+            cyclic.add(name);
+            return;
+        }
+        onStack.add(name);
+        const deps = collectRefs(schemas[name], schemas, new Set(), new Set([name]));
+        for (const d of deps) if (names.has(d) && d !== name) visit(d);
+        onStack.delete(name);
+        visited.add(name);
+        sorted.push(name);
+    }
+    for (const n of [...names].sort()) visit(n);
+    return { sorted, cyclic };
+}
+
+/** Extract the success ($2xx) JSON response schema of an operation. */
+function successSchema(op) {
+    const responses = op.responses ?? {};
+    const code =
+        ["200", "201", "202", "2XX"].find((c) => responses[c]) ??
+        Object.keys(responses).find((c) => c.startsWith("2"));
+    const content = code && responses[code]?.content?.["application/json"];
+    return content?.schema ?? null;
+}
+
+/** Extract the JSON request body schema of an operation. */
+function bodySchema(op) {
+    return op.requestBody?.content?.["application/json"]?.schema ?? null;
+}
+
+/**
+ * Generate the per-tag files from a parsed OpenAPI document.
+ *
+ * @param {object} doc - The parsed OpenAPI 3.x spec.
+ * @returns {{ files: Record<string, string>, tags: string[] }}
+ */
+export function generate(doc) {
+    const schemas = doc.components?.schemas ?? {};
+    const groups = new Map(); // slug → { tag, ops: [...] }
+
+    for (const [path, item] of Object.entries(doc.paths ?? {})) {
+        for (const method of HTTP_METHODS) {
+            const op = item[method];
+            if (!op) continue;
+            const tag = op.tags?.[0] ?? "default";
+            const slug = tagSlug(tag);
+            if (!groups.has(slug)) groups.set(slug, { tag, slug, ops: [] });
+            groups.get(slug).ops.push({ method, path, op });
+        }
+    }
+
+    const files = {};
+    const tags = [];
+
+    for (const { tag, slug, ops } of groups.values()) {
+        tags.push(tag);
+        const Class = `${pascal(slug)}Service`;
+
+        // 1. Which component schemas does this group touch (transitively)?
+        const used = new Set();
+        for (const { op } of ops) {
+            const b = bodySchema(op);
+            const r = successSchema(op);
+            if (b) collectRefs(b, schemas, used);
+            if (r) collectRefs(r, schemas, used);
+        }
+        const { sorted, cyclic } = topoSort(used, schemas);
+
+        // 2. schemas.ts
+        const schemaLines = sorted.map((name) => {
+            const expr = schemaToZod(schemas[name], (ref) => {
+                const n = refName(ref);
+                return cyclic.has(n) ? `z.lazy(() => ${zodName(n)})` : zodName(n);
+            });
+            return `export const ${zodName(name)} = ${expr};`;
+        });
+        files[`${slug}/schemas.ts`] = `import { z } from "zod";\n\n${schemaLines.join("\n\n")}\n`;
+
+        // 3. types.ts
+        const typeLines = sorted.map(
+            (name) => `export type ${name} = z.infer<typeof S.${zodName(name)}>;`,
+        );
+        files[`${slug}/types.ts`] =
+            `import type { z } from "zod";\n\nimport * as S from "./schemas";\n\n${typeLines.join("\n")}\n`;
+
+        // 4. service.ts
+        const methods = ops.map(({ method, path, op }) => emitMethod(method, path, op, used));
+        const usedTypeNames = [...used].sort();
+        const typeImport = usedTypeNames.length
+            ? `import type { ${usedTypeNames.join(", ")} } from "./types";\n`
+            : "";
+        const schemaImport = usedTypeNames.length ? `import * as S from "./schemas";\n` : "";
+        files[`${slug}/service.ts`] =
+            `import type { ApiClient } from "tempest-react-sdk";\n\n` +
+            schemaImport +
+            typeImport +
+            `\n/** Generated service for the "${tag}" routes. Inject an ApiClient (createApiClient). */\n` +
+            `export class ${Class} {\n` +
+            `    constructor(private readonly api: ApiClient) {}\n\n` +
+            methods.join("\n\n") +
+            `\n}\n`;
+
+        // 5. index.ts (re-export)
+        files[`${slug}/index.ts`] =
+            `export * from "./schemas";\nexport * from "./types";\nexport { ${Class} } from "./service";\n`;
+    }
+
+    // Root barrel.
+    files["index.ts"] =
+        [...groups.values()].map(({ slug }) => `export * from "./${slug}";`).join("\n") + "\n";
+
+    return { files, tags };
+}
+
+/** Emit a single class method for one operation. */
+function emitMethod(method, path, op, used) {
+    const name = methodName(op, method, path);
+    const pathParams = (op.parameters ?? []).filter((p) => p.in === "path");
+    const queryParams = (op.parameters ?? []).filter((p) => p.in === "query");
+    const body = bodySchema(op);
+    const resp = successSchema(op);
+    const retType = resp ? tsType(resp) : "void";
+
+    const args = [];
+    for (const p of pathParams) args.push(`${p.name}: ${tsType(p.schema ?? { type: "string" })}`);
+    if (body) args.push(`body: ${tsType(body)}`);
+    if (queryParams.length) {
+        const q = queryParams
+            .map(
+                (p) =>
+                    `${JSON.stringify(p.name)}${p.required ? "" : "?"}: ${tsType(p.schema ?? { type: "string" })}`,
+            )
+            .join("; ");
+        args.push(`params: { ${q} }`);
+    }
+
+    // Interpolate path params into a template literal.
+    const tpl = path.replace(/{([^}]+)}/g, (_, n) => "${" + n + "}");
+    const url = pathParams.length ? `\`${tpl}\`` : JSON.stringify(path);
+
+    const callOpts = [];
+    if (body) callOpts.push("body");
+    if (queryParams.length) callOpts.push("params");
+    const optsArg = callOpts.length ? `, { ${callOpts.join(", ")} }` : "";
+
+    // Zod input validation: validate the body when it references a known schema.
+    let validation = "";
+    if (body && body.$ref) {
+        const schemaConst = `S.${zodName(refName(body.$ref))}`;
+        validation = `        ${schemaConst}.parse(body);\n`;
+    }
+
+    const ret = retType === "void" ? "Promise<void>" : `Promise<${retType}>`;
+    const generic = retType === "void" ? "" : `<${retType}>`;
+    return (
+        `    /** \`${method.toUpperCase()} ${path}\`${op.summary ? ` — ${op.summary}` : ""} */\n` +
+        `    async ${name}(${args.join(", ")}): ${ret} {\n` +
+        validation +
+        `        return this.api.${method}${generic}(${url}${optsArg});\n` +
+        `    }`
+    );
+}

package/bin/lib/openapi/generate.test.mjs

@@ -0,0 +1,129 @@
+import { describe, it, expect } from "vitest";
+import { generate } from "./generate.mjs";
+
+const SPEC = {
+    openapi: "3.1.0",
+    components: {
+        schemas: {
+            User: {
+                type: "object",
+                required: ["id", "email"],
+                properties: {
+                    id: { type: "integer" },
+                    email: { type: "string", format: "email" },
+                    name: { type: "string" },
+                },
+            },
+            UserCreate: {
+                type: "object",
+                required: ["email"],
+                properties: {
+                    email: { type: "string", format: "email" },
+                    name: { type: "string" },
+                },
+            },
+        },
+    },
+    paths: {
+        "/users": {
+            get: {
+                tags: ["users"],
+                operationId: "list_users",
+                parameters: [
+                    { name: "limit", in: "query", required: false, schema: { type: "integer" } },
+                ],
+                responses: {
+                    200: {
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "array",
+                                    items: { $ref: "#/components/schemas/User" },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            post: {
+                tags: ["users"],
+                operationId: "create_user",
+                requestBody: {
+                    content: {
+                        "application/json": { schema: { $ref: "#/components/schemas/UserCreate" } },
+                    },
+                },
+                responses: {
+                    201: {
+                        content: {
+                            "application/json": { schema: { $ref: "#/components/schemas/User" } },
+                        },
+                    },
+                },
+            },
+        },
+        "/users/{id}": {
+            get: {
+                tags: ["users"],
+                operationId: "get_user",
+                parameters: [
+                    { name: "id", in: "path", required: true, schema: { type: "integer" } },
+                ],
+                responses: {
+                    200: {
+                        content: {
+                            "application/json": { schema: { $ref: "#/components/schemas/User" } },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};
+
+describe("generate — FastAPI-style spec", () => {
+    const { files, tags } = generate(SPEC);
+
+    it("groups by tag", () => {
+        expect(tags).toContain("users");
+        expect(Object.keys(files)).toEqual(
+            expect.arrayContaining([
+                "users/schemas.ts",
+                "users/types.ts",
+                "users/service.ts",
+                "users/index.ts",
+                "index.ts",
+            ]),
+        );
+    });
+
+    it("emits Zod schemas for referenced models", () => {
+        const s = files["users/schemas.ts"];
+        expect(s).toContain('import { z } from "zod";');
+        expect(s).toContain("export const UserSchema = z.object({");
+        expect(s).toContain("export const UserCreateSchema = z.object({");
+        expect(s).toContain('"email": z.string().email()');
+    });
+
+    it("emits inferred types", () => {
+        const t = files["users/types.ts"];
+        expect(t).toContain("export type User = z.infer<typeof S.UserSchema>;");
+        expect(t).toContain("export type UserCreate = z.infer<typeof S.UserCreateSchema>;");
+    });
+
+    it("emits a service class with one method per route", () => {
+        const svc = files["users/service.ts"];
+        expect(svc).toContain("export class UsersService {");
+        expect(svc).toContain("constructor(private readonly api: ApiClient) {}");
+        // list with query params
+        expect(svc).toMatch(
+            /async listUsers\(params: \{ "limit"\?: number \}\): Promise<User\[\]>/,
+        );
+        // create with Zod input validation
+        expect(svc).toContain("S.UserCreateSchema.parse(body);");
+        expect(svc).toMatch(/async createUser\(body: UserCreate\): Promise<User>/);
+        // path param interpolation
+        expect(svc).toMatch(/async getUser\(id: number\): Promise<User>/);
+        expect(svc).toContain("return this.api.get<User>(`/users/${id}`);");
+    });
+});

package/bin/lib/openapi/load.mjs

@@ -0,0 +1,24 @@
+// Load an OpenAPI spec from a local file path or an http(s) URL → parsed object.
+import { readFile } from "node:fs/promises";
+
+/**
+ * @param {string} source - File path or http(s) URL to an openapi.json.
+ * @returns {Promise<object>} The parsed OpenAPI document.
+ */
+export async function loadSpec(source) {
+    let raw;
+    if (/^https?:\/\//.test(source)) {
+        const res = await fetch(source);
+        if (!res.ok) throw new Error(`Failed to fetch ${source} — HTTP ${res.status}`);
+        raw = await res.text();
+    } else {
+        raw = await readFile(source, "utf8");
+    }
+    try {
+        return JSON.parse(raw);
+    } catch {
+        throw new Error(
+            `Could not parse ${source} as JSON. Only openapi.json (JSON) is supported for now — point at the FastAPI /openapi.json endpoint.`,
+        );
+    }
+}

package/bin/lib/openapi/schema-to-zod.mjs

@@ -0,0 +1,123 @@
+// JSON Schema (OpenAPI 3.0/3.1 subset) → Zod expression source string.
+// Pure + deterministic so the generated output is stable and testable.
+
+/** Convert a $ref like "#/components/schemas/User" to its schema name ("User"). */
+export function refName(ref) {
+    return ref.slice(ref.lastIndexOf("/") + 1);
+}
+
+/** The generated Zod const name for a schema name (e.g. "User" → "UserSchema"). */
+export function zodName(name) {
+    return `${name}Schema`;
+}
+
+function isNullable(schema) {
+    if (schema.nullable === true) return true; // OpenAPI 3.0
+    if (Array.isArray(schema.type)) return schema.type.includes("null"); // 3.1
+    return false;
+}
+
+function withModifiers(expr, schema) {
+    let out = expr;
+    if (isNullable(schema)) out += ".nullable()";
+    if (schema.default !== undefined) out += `.default(${JSON.stringify(schema.default)})`;
+    return out;
+}
+
+/** Pick the primary (non-null) type when 3.1 uses an array of types. */
+function primaryType(schema) {
+    if (Array.isArray(schema.type)) return schema.type.find((t) => t !== "null");
+    return schema.type;
+}
+
+/**
+ * Convert one schema node to a Zod expression string.
+ *
+ * @param {object} schema - The (sub)schema.
+ * @param {(ref: string) => string} [resolveRef] - Maps a $ref to its Zod expr
+ *   (defaults to the bare `${Name}Schema` const, used lazily).
+ * @returns {string} A Zod expression, e.g. `z.string().email()`.
+ */
+export function schemaToZod(schema, resolveRef = (ref) => zodName(refName(ref))) {
+    if (!schema || typeof schema !== "object") return "z.unknown()";
+
+    if (schema.$ref) return resolveRef(schema.$ref);
+
+    // Composition.
+    if (Array.isArray(schema.allOf)) {
+        const parts = schema.allOf.map((s) => schemaToZod(s, resolveRef));
+        if (parts.length === 1) return withModifiers(parts[0], schema);
+        return withModifiers(
+            parts.reduce((a, b) => `z.intersection(${a}, ${b})`),
+            schema,
+        );
+    }
+    if (Array.isArray(schema.anyOf) || Array.isArray(schema.oneOf)) {
+        const variants = (schema.anyOf ?? schema.oneOf).map((s) => schemaToZod(s, resolveRef));
+        const union = variants.length === 1 ? variants[0] : `z.union([${variants.join(", ")}])`;
+        return withModifiers(union, schema);
+    }
+
+    // Standalone enum (no explicit object/array type).
+    if (Array.isArray(schema.enum)) {
+        const allStrings = schema.enum.every((v) => typeof v === "string");
+        const expr = allStrings
+            ? `z.enum([${schema.enum.map((v) => JSON.stringify(v)).join(", ")}])`
+            : `z.union([${schema.enum.map((v) => `z.literal(${JSON.stringify(v)})`).join(", ")}])`;
+        return withModifiers(expr, schema);
+    }
+
+    switch (primaryType(schema)) {
+        case "string": {
+            let e = "z.string()";
+            if (schema.format === "email") e += ".email()";
+            else if (schema.format === "uuid") e += ".uuid()";
+            else if (schema.format === "uri" || schema.format === "url") e += ".url()";
+            else if (schema.format === "date-time") e = "z.string().datetime({ offset: true })";
+            if (typeof schema.minLength === "number") e += `.min(${schema.minLength})`;
+            if (typeof schema.maxLength === "number") e += `.max(${schema.maxLength})`;
+            if (typeof schema.pattern === "string")
+                e += `.regex(/${schema.pattern.replace(/\//g, "\\/")}/)`;
+            return withModifiers(e, schema);
+        }
+        case "integer":
+        case "number": {
+            let e = "z.number()";
+            if (primaryType(schema) === "integer") e += ".int()";
+            if (typeof schema.minimum === "number") e += `.min(${schema.minimum})`;
+            if (typeof schema.maximum === "number") e += `.max(${schema.maximum})`;
+            return withModifiers(e, schema);
+        }
+        case "boolean":
+            return withModifiers("z.boolean()", schema);
+        case "null":
+            return "z.null()";
+        case "array": {
+            const items = schema.items ? schemaToZod(schema.items, resolveRef) : "z.unknown()";
+            return withModifiers(`z.array(${items})`, schema);
+        }
+        case "object":
+        default: {
+            if (schema.properties && typeof schema.properties === "object") {
+                const required = new Set(schema.required ?? []);
+                const entries = Object.entries(schema.properties).map(([key, prop]) => {
+                    let expr = schemaToZod(prop, resolveRef);
+                    if (!required.has(key)) expr += ".optional()";
+                    return `    ${JSON.stringify(key)}: ${expr},`;
+                });
+                let e = entries.length ? `z.object({\n${entries.join("\n")}\n})` : "z.object({})";
+                // additionalProperties → passthrough / record.
+                if (schema.additionalProperties === true) e += ".passthrough()";
+                return withModifiers(e, schema);
+            }
+            if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+                return withModifiers(
+                    `z.record(${schemaToZod(schema.additionalProperties, resolveRef)})`,
+                    schema,
+                );
+            }
+            // No type info → unknown record / passthrough object.
+            return withModifiers("z.record(z.unknown())", schema);
+        }
+    }
+}

package/bin/lib/openapi/schema-to-zod.test.mjs

@@ -0,0 +1,81 @@
+import { describe, it, expect } from "vitest";
+import { refName, zodName, schemaToZod } from "./schema-to-zod.mjs";
+
+describe("refName / zodName", () => {
+    it("extracts the schema name from a $ref", () => {
+        expect(refName("#/components/schemas/User")).toBe("User");
+    });
+    it("builds the zod const name", () => {
+        expect(zodName("User")).toBe("UserSchema");
+    });
+});
+
+describe("schemaToZod — primitives", () => {
+    it("string with format", () => {
+        expect(schemaToZod({ type: "string" })).toBe("z.string()");
+        expect(schemaToZod({ type: "string", format: "email" })).toBe("z.string().email()");
+        expect(schemaToZod({ type: "string", format: "uuid" })).toBe("z.string().uuid()");
+        expect(schemaToZod({ type: "string", format: "date-time" })).toBe(
+            "z.string().datetime({ offset: true })",
+        );
+    });
+    it("integer vs number", () => {
+        expect(schemaToZod({ type: "integer" })).toBe("z.number().int()");
+        expect(schemaToZod({ type: "number", minimum: 0 })).toBe("z.number().min(0)");
+    });
+    it("boolean", () => {
+        expect(schemaToZod({ type: "boolean" })).toBe("z.boolean()");
+    });
+});
+
+describe("schemaToZod — $ref / nullable / enum", () => {
+    it("$ref → ZodName", () => {
+        expect(schemaToZod({ $ref: "#/components/schemas/User" })).toBe("UserSchema");
+    });
+    it("nullable (3.0)", () => {
+        expect(schemaToZod({ type: "string", nullable: true })).toBe("z.string().nullable()");
+    });
+    it("nullable (3.1 type array)", () => {
+        expect(schemaToZod({ type: ["string", "null"] })).toBe("z.string().nullable()");
+    });
+    it("string enum", () => {
+        expect(schemaToZod({ type: "string", enum: ["a", "b"] })).toBe('z.enum(["a", "b"])');
+    });
+});
+
+describe("schemaToZod — array / object", () => {
+    it("array of refs", () => {
+        expect(schemaToZod({ type: "array", items: { $ref: "#/components/schemas/User" } })).toBe(
+            "z.array(UserSchema)",
+        );
+    });
+    it("object with required + optional", () => {
+        const out = schemaToZod({
+            type: "object",
+            required: ["id"],
+            properties: { id: { type: "integer" }, name: { type: "string" } },
+        });
+        expect(out).toContain('"id": z.number().int(),');
+        expect(out).toContain('"name": z.string().optional(),');
+        expect(out.startsWith("z.object({")).toBe(true);
+    });
+    it("record for additionalProperties schema", () => {
+        expect(schemaToZod({ type: "object", additionalProperties: { type: "number" } })).toBe(
+            "z.record(z.number())",
+        );
+    });
+});
+
+describe("schemaToZod — composition", () => {
+    it("anyOf → union", () => {
+        expect(schemaToZod({ anyOf: [{ type: "string" }, { type: "number" }] })).toBe(
+            "z.union([z.string(), z.number()])",
+        );
+    });
+    it("allOf → intersection", () => {
+        const out = schemaToZod({
+            allOf: [{ $ref: "#/components/schemas/A" }, { $ref: "#/components/schemas/B" }],
+        });
+        expect(out).toBe("z.intersection(ASchema, BSchema)");
+    });
+});