tempest-react-sdk 0.8.0 → 0.10.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,339 @@
+// 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) {
+        const parts = (schema.anyOf ?? schema.oneOf).map(tsType);
+        return [...new Set(parts)].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 "null":
+            return "null";
+        case "array":
+            base = `${tsType(schema.items)}[]`;
+            break;
+        case "object":
+        default:
+            base = "Record<string, unknown>";
+    }
+    return nul ? `${base} | null` : base;
+}
+
+/**
+ * TS type for a query-param value. Query params serialize to strings, so the
+ * client only accepts `string | number | boolean | null`. Anything richer
+ * (objects, arrays of objects) is narrowed to `string` to stay assignable.
+ */
+function queryParamType(schema) {
+    const t = tsType(schema ?? { type: "string" });
+    const allowed = new Set(["string", "number", "boolean", "null"]);
+    const ok = t.split("|").every((part) => allowed.has(part.trim()));
+    return ok ? t : "string";
+}
+
+/** Turn a tag slug into a JS-safe identifier ("chat-messages" → "chatMessages"). */
+function slugIdent(slug) {
+    const id = slug.replace(/[^a-zA-Z0-9]+(.)?/g, (_, ch) => (ch ? ch.toUpperCase() : ""));
+    return /^[a-zA-Z_]/.test(id) ? id : `_${id}`;
+}
+
+/** 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 };
+}
+
+/** Follow a chain of $refs to the concrete schema node. */
+function resolveSchema(schema, schemas) {
+    let node = schema;
+    let guard = 0;
+    while (node && node.$ref && guard++ < 16) node = schemas[refName(node.$ref)];
+    return node;
+}
+
+/**
+ * Detect a Tempest pagination envelope and return its kind + item type.
+ *
+ * Offset (fastapi-pagination `Page` / `BasePaginationSchema`):
+ *   items + total + pages + (size | page_size).
+ * Cursor (`CursorPaginationSchema`): items + next_cursor + has_more.
+ *
+ * @returns {{ kind: "offset"|"cursor", itemType: string }|null}
+ */
+function detectPage(schema, schemas) {
+    const node = resolveSchema(schema, schemas);
+    const props = node?.properties;
+    if (!props || !props.items || resolveSchema(props.items, schemas)?.type !== "array") {
+        return null;
+    }
+    const itemType = tsType(resolveSchema(props.items, schemas).items);
+    if ("total" in props && "pages" in props && ("size" in props || "page_size" in props)) {
+        return { kind: "offset", itemType };
+    }
+    if ("next_cursor" in props && "has_more" in props) {
+        return { kind: "cursor", itemType };
+    }
+    return null;
+}
+
+/** 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 usedNames = new Set();
+        const methods = ops.map(({ method, path, op }) =>
+            emitMethod(method, path, op, schemas, usedNames),
+        );
+        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` : "";
+        const body = methods.join("\n\n");
+        // Pagination envelopes are re-exported from the SDK; import what we used.
+        const sdkTypes = ["ApiClient"];
+        if (body.includes("OffsetPage<")) sdkTypes.push("OffsetPage");
+        if (body.includes("CursorPage<")) sdkTypes.push("CursorPage");
+        files[`${slug}/service.ts`] =
+            `import type { ${sdkTypes.join(", ")} } 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` +
+            body +
+            `\n}\n`;
+
+        // 5. index.ts (re-export)
+        files[`${slug}/index.ts`] =
+            `export * from "./schemas";\nexport * from "./types";\nexport { ${Class} } from "./service";\n`;
+    }
+
+    // Root barrel — namespaced per group so schema/type names shared across
+    // groups (e.g. UserResponseSchema in both `admin` and `auth`) don't collide.
+    files["index.ts"] =
+        [...groups.values()]
+            .map(({ slug }) => `export * as ${slugIdent(slug)} from "./${slug}";`)
+            .join("\n") + "\n";
+
+    return { files, tags };
+}
+
+/** Emit a single class method for one operation. */
+function emitMethod(method, path, op, schemas, usedNames = new Set()) {
+    let name = methodName(op, method, path);
+    // Dedupe collisions within a group (e.g. operationIds "home__get" / "home_get").
+    if (usedNames.has(name)) {
+        let n = 2;
+        while (usedNames.has(`${name}${n}`)) n += 1;
+        name = `${name}${n}`;
+    }
+    usedNames.add(name);
+    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);
+    // Map a Tempest pagination envelope to OffsetPage<T>/CursorPage<T>.
+    const page = resp ? detectPage(resp, schemas) : null;
+    const retType = page
+        ? `${page.kind === "offset" ? "OffsetPage" : "CursorPage"}<${page.itemType}>`
+        : 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 ? "" : "?"}: ${queryParamType(p.schema)}`,
+            )
+            .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.pagination.test.mjs

@@ -0,0 +1,86 @@
+import { describe, it, expect } from "vitest";
+
+import { generate } from "./generate.mjs";
+
+const SPEC = {
+    openapi: "3.1.0",
+    components: {
+        schemas: {
+            Post: {
+                type: "object",
+                required: ["id"],
+                properties: { id: { type: "integer" }, title: { type: "string" } },
+            },
+            PostPage: {
+                type: "object",
+                properties: {
+                    items: { type: "array", items: { $ref: "#/components/schemas/Post" } },
+                    total: { type: "integer" },
+                    page: { type: "integer" },
+                    page_size: { type: "integer" },
+                    pages: { type: "integer" },
+                },
+            },
+            PostFeed: {
+                type: "object",
+                properties: {
+                    items: { type: "array", items: { $ref: "#/components/schemas/Post" } },
+                    next_cursor: { type: "string", nullable: true },
+                    has_more: { type: "boolean" },
+                    limit: { type: "integer" },
+                },
+            },
+        },
+    },
+    paths: {
+        "/posts": {
+            get: {
+                tags: ["posts"],
+                operationId: "list_posts",
+                responses: {
+                    200: {
+                        content: {
+                            "application/json": {
+                                schema: { $ref: "#/components/schemas/PostPage" },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+        "/posts/feed": {
+            get: {
+                tags: ["posts"],
+                operationId: "feed_posts",
+                responses: {
+                    200: {
+                        content: {
+                            "application/json": {
+                                schema: { $ref: "#/components/schemas/PostFeed" },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};
+
+describe("generate — pagination envelopes", () => {
+    const { files } = generate(SPEC);
+    const svc = files["posts/service.ts"];
+
+    it("maps the offset envelope to OffsetPage<Post>", () => {
+        expect(svc).toMatch(/async listPosts\(\): Promise<OffsetPage<Post>>/);
+    });
+
+    it("maps the cursor envelope to CursorPage<Post>", () => {
+        expect(svc).toMatch(/async feedPosts\(\): Promise<CursorPage<Post>>/);
+    });
+
+    it("imports the page types from the SDK", () => {
+        expect(svc).toContain(
+            'import type { ApiClient, OffsetPage, CursorPage } from "tempest-react-sdk";',
+        );
+    });
+});

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.`,
+        );
+    }
+}