@porulle/sdk 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# @porulle/sdk
+
+Typed TypeScript client for any Porulle server. Generated from the OpenAPI spec — every endpoint, request body, and response is type-checked at compile time.
+
+## Two surfaces
+
+```ts
+import { createClient } from "@porulle/sdk";
+import { createCommerceHooks } from "@porulle/sdk/react";
+```
+
+- **`createClient<paths>`** — a vanilla `openapi-fetch` client. Use anywhere (Node, Bun, browser, Cloudflare Workers).
+- **`createCommerceHooks(client)`** — TanStack Query (React Query) hooks bound to that client.
+
+## Usage
+
+```ts
+import { createClient } from "@porulle/sdk";
+import type { paths } from "./generated/api-types";  // generate via openapi-typescript against your /api/doc
+
+const client = createClient<paths>({
+  baseUrl: "https://your-store.com",
+  auth: { type: "api_key", key: process.env.PORULLE_API_KEY! },
+});
+
+const { data, error } = await client.GET("/api/catalog/entities", {
+  params: { query: { type: "product", limit: 10 } },
+});
+```
+
+React Query bindings:
+
+```tsx
+import { createCommerceHooks } from "@porulle/sdk/react";
+
+const commerce = createCommerceHooks(client);
+
+function ProductList() {
+  const { data } = commerce.useQuery("get", "/api/catalog/entities", {
+    params: { query: { type: "product" } },
+  });
+  return <ul>{data?.data.map(p => <li key={p.id}>{p.slug}</li>)}</ul>;
+}
+```
+
+## Auth credentials
+
+| Type | Header sent |
+|---|---|
+| `{ type: "api_key", key }` | `x-api-key: <key>` |
+| `{ type: "bearer", token }` | `Authorization: Bearer <token>` |
+| (omitted) | request goes anonymous; the server's auth middleware decides what's allowed |
+
+## Generating types
+
+The SDK is generic — bring your own `paths` type. Generate it from your server's OpenAPI doc:
+
+```bash
+bunx openapi-typescript http://localhost:4000/api/doc -o src/generated/api-types.ts
+```
+
+The shipped server exposes `/api/doc` (JSON) and `/api/reference` (Scalar UI in dev).
+
+## See also
+
+- [Root README](../../README.md)
+- `apps/store-example/` — full app using the SDK

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * SDK Codegen CLI — generates TypeScript types from your UC server's OpenAPI spec.
+ *
+ * Usage:
+ *   bunx @porulle/sdk generate                          # from running server on :3000
+ *   bunx @porulle/sdk generate --url http://localhost:4000/api/doc
+ *   bunx @porulle/sdk generate --output src/types/api.ts
+ *
+ * This fetches /api/doc from your running server and runs openapi-typescript
+ * to produce a paths type file. Commit the output alongside your code.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;GAUG"}

package/dist/cli.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * SDK Codegen CLI — generates TypeScript types from your UC server's OpenAPI spec.
+ *
+ * Usage:
+ *   bunx @porulle/sdk generate                          # from running server on :3000
+ *   bunx @porulle/sdk generate --url http://localhost:4000/api/doc
+ *   bunx @porulle/sdk generate --output src/types/api.ts
+ *
+ * This fetches /api/doc from your running server and runs openapi-typescript
+ * to produce a paths type file. Commit the output alongside your code.
+ */
+import { writeFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { execSync } from "node:child_process";
+const args = process.argv.slice(2);
+const command = args[0];
+if (command !== "generate") {
+    console.log(`
+@porulle/sdk — Type Generation CLI
+
+Usage:
+  bunx @porulle/sdk generate [options]
+
+Options:
+  --url <url>       OpenAPI spec URL (default: http://localhost:3000/api/doc)
+  --output <path>   Output file path (default: src/generated/api-types.ts)
+
+Examples:
+  bunx @porulle/sdk generate
+  bunx @porulle/sdk generate --url http://localhost:4000/api/doc
+  bunx @porulle/sdk generate --output src/types/commerce.ts
+  `);
+    process.exit(command === undefined || command === "help" || command === "--help" ? 0 : 1);
+}
+const urlIdx = args.indexOf("--url");
+const outputIdx = args.indexOf("--output");
+const specUrl = urlIdx !== -1 && args[urlIdx + 1]
+    ? args[urlIdx + 1]
+    : process.env.API_URL ?? "http://localhost:3000/api/doc";
+const outputFile = outputIdx !== -1 && args[outputIdx + 1]
+    ? args[outputIdx + 1]
+    : "src/generated/api-types.ts";
+const outputDir = dirname(outputFile);
+const tempSpec = join(outputDir, "_spec.json");
+async function main() {
+    console.log(`Fetching OpenAPI spec from ${specUrl}...`);
+    let res;
+    try {
+        res = await fetch(specUrl);
+    }
+    catch (err) {
+        console.error(`\nCould not connect to ${specUrl}`);
+        console.error("");
+        console.error("Make sure your server is running:");
+        console.error("  bun run dev");
+        console.error("");
+        console.error("Or specify a custom URL:");
+        console.error("  bunx @porulle/sdk generate --url http://your-server/api/doc");
+        process.exit(1);
+        return; // unreachable, satisfies TS
+    }
+    if (!res.ok) {
+        console.error(`Server returned ${res.status} ${res.statusText}`);
+        console.error("Make sure the OpenAPI spec is enabled (GET /api/doc should return JSON).");
+        process.exit(1);
+    }
+    const spec = await res.json();
+    const pathCount = Object.keys(spec.paths ?? {}).length;
+    if (pathCount === 0) {
+        console.error("OpenAPI spec has 0 paths. Is the server configured correctly?");
+        process.exit(1);
+    }
+    mkdirSync(outputDir, { recursive: true });
+    writeFileSync(tempSpec, JSON.stringify(spec, null, 2));
+    console.log(`Spec extracted: ${pathCount} paths`);
+    console.log(`Generating types → ${outputFile}`);
+    try {
+        execSync(`npx openapi-typescript ${tempSpec} -o ${outputFile}`, {
+            stdio: "inherit",
+        });
+    }
+    catch {
+        console.error("openapi-typescript failed. Is it installed?");
+        console.error("  bun add -d openapi-typescript");
+        process.exit(1);
+    }
+    try {
+        unlinkSync(tempSpec);
+    }
+    catch { }
+    console.log(`\nDone — ${pathCount} paths typed in ${outputFile}`);
+    console.log("Commit this file alongside your route changes.");
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,89 @@
+import { type AuthCredential } from "./middleware.js";
+export interface SDKOptions {
+    /** Base URL of the UnifiedCommerce server (e.g., "http://localhost:4000"). */
+    baseUrl: string;
+    /** Authentication credential (API key or Bearer token). */
+    auth?: AuthCredential | undefined;
+    /** Additional headers sent with every request. */
+    headers?: Record<string, string> | undefined;
+    /** Custom fetch implementation (for testing or SSR). */
+    fetch?: typeof globalThis.fetch | undefined;
+}
+/**
+ * Creates a typed openapi-fetch client for your UnifiedCommerce API.
+ *
+ * Generic — you pass your own generated paths type:
+ *
+ * ```ts
+ * import { createClient } from "@porulle/sdk";
+ * import type { paths } from "./generated/api-types";
+ *
+ * const client = createClient<paths>({
+ *   baseUrl: "http://localhost:3000",
+ *   auth: { type: "api_key", key: "dev-key" },
+ * });
+ *
+ * const { data } = await client.GET("/api/catalog/entities");
+ * ```
+ */
+export declare function createClient<TPaths extends {}>(options: SDKOptions): import("openapi-fetch").Client<TPaths, `${string}/${string}`>;
+/**
+ * Creates a typed SDK with ergonomic domain namespaces.
+ *
+ * This is a convenience wrapper that creates an openapi-fetch client
+ * and adds sdk.catalog.list(), sdk.cart.addItem(), etc. on top.
+ *
+ * For full type coverage (including plugin routes), use createClient()
+ * with your own generated paths type instead.
+ *
+ * ```ts
+ * import { createSDK } from "@porulle/sdk";
+ * const sdk = createSDK({ baseUrl: "http://localhost:3000", auth: { ... } });
+ * const { data } = await sdk.catalog.list();
+ * ```
+ */
+export declare function createSDK(options: SDKOptions): {
+    raw: import("openapi-fetch").Client<Record<string, unknown>, `${string}/${string}`>;
+    catalog: {
+        list(query?: Record<string, string>): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+        get(idOrSlug: string): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+        create(body: Record<string, unknown>): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+    };
+    cart: {
+        create(body: Record<string, unknown>): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+        get(id: string): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+        addItem(id: string, body: Record<string, unknown>): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+    };
+    checkout: {
+        create(body: Record<string, unknown>): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+    };
+    orders: {
+        list(query?: Record<string, string>): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+        get(idOrNumber: string): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+    };
+    search: {
+        query(query: {
+            q: string;
+            [k: string]: string;
+        }): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+    };
+    me: {
+        profile: {
+            get(): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+            update(body: Record<string, unknown>): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+        };
+        orders: {
+            list(query?: Record<string, string>): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+            get(id: string): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+            tracking(id: string): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+            reorder(id: string): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+        };
+    };
+    webhooks: {
+        list(query?: Record<string, string>): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+        get(id: string): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+        create(body: Record<string, unknown>): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+        delete(id: string): Promise<import("openapi-fetch").FetchResponse<unknown, never, `${string}/${string}`>>;
+    };
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtE,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IAClC,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC7C,wDAAwD;IACxD,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,GAAG,SAAS,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,MAAM,SAAS,EAAE,EAAE,OAAO,EAAE,UAAU,iEAclE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,UAAU;;;qBAkB1B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;sBACrB,MAAM;qBACP,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;qBAIvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAC5B,MAAM;oBACF,MAAM,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;qBAIpC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;qBAIvB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;wBACnB,MAAM;;;qBAIT;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;SAAE;;;;;yBAMhC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;yBAGvB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;oBAC3B,MAAM;yBACD,MAAM;wBACP,MAAM;;;;qBAKP,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;gBAC3B,MAAM;qBACD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;mBACzB,MAAM;;EAGtB"}

package/dist/client.js

@@ -0,0 +1,100 @@
+import openapiCreateClient from "openapi-fetch";
+import { authMiddleware } from "./middleware.js";
+/**
+ * Creates a typed openapi-fetch client for your UnifiedCommerce API.
+ *
+ * Generic — you pass your own generated paths type:
+ *
+ * ```ts
+ * import { createClient } from "@porulle/sdk";
+ * import type { paths } from "./generated/api-types";
+ *
+ * const client = createClient<paths>({
+ *   baseUrl: "http://localhost:3000",
+ *   auth: { type: "api_key", key: "dev-key" },
+ * });
+ *
+ * const { data } = await client.GET("/api/catalog/entities");
+ * ```
+ */
+export function createClient(options) {
+    const clientOpts = {
+        baseUrl: options.baseUrl,
+    };
+    if (options.headers)
+        clientOpts.headers = options.headers;
+    if (options.fetch)
+        clientOpts.fetch = options.fetch;
+    const client = openapiCreateClient(clientOpts);
+    if (options.auth) {
+        client.use(authMiddleware(options.auth));
+    }
+    return client;
+}
+/**
+ * Creates a typed SDK with ergonomic domain namespaces.
+ *
+ * This is a convenience wrapper that creates an openapi-fetch client
+ * and adds sdk.catalog.list(), sdk.cart.addItem(), etc. on top.
+ *
+ * For full type coverage (including plugin routes), use createClient()
+ * with your own generated paths type instead.
+ *
+ * ```ts
+ * import { createSDK } from "@porulle/sdk";
+ * const sdk = createSDK({ baseUrl: "http://localhost:3000", auth: { ... } });
+ * const { data } = await sdk.catalog.list();
+ * ```
+ */
+export function createSDK(options) {
+    const client = openapiCreateClient({ baseUrl: options.baseUrl, ...(options.headers ? { headers: options.headers } : {}), ...(options.fetch ? { fetch: options.fetch } : {}) });
+    if (options.auth) {
+        client.use(authMiddleware(options.auth));
+    }
+    // Untyped convenience wrappers for core routes.
+    // These work without codegen but have no compile-time body/response validation.
+    // For full types, use createClient<paths>() with your generated types.
+    const raw = client;
+    return {
+        raw,
+        catalog: {
+            list(query) { return raw.GET("/api/catalog/entities", query ? { params: { query } } : undefined); },
+            get(idOrSlug) { return raw.GET("/api/catalog/entities/{idOrSlug}", { params: { path: { idOrSlug } } }); },
+            create(body) { return raw.POST("/api/catalog/entities", { body }); },
+        },
+        cart: {
+            create(body) { return raw.POST("/api/carts", { body }); },
+            get(id) { return raw.GET("/api/carts/{id}", { params: { path: { id } } }); },
+            addItem(id, body) { return raw.POST("/api/carts/{id}/items", { params: { path: { id } }, body }); },
+        },
+        checkout: {
+            create(body) { return raw.POST("/api/checkout", { body }); },
+        },
+        orders: {
+            list(query) { return raw.GET("/api/orders", query ? { params: { query } } : undefined); },
+            get(idOrNumber) { return raw.GET("/api/orders/{idOrNumber}", { params: { path: { idOrNumber } } }); },
+        },
+        search: {
+            query(query) { return raw.GET("/api/search", { params: { query } }); },
+        },
+        me: {
+            profile: {
+                get() { return raw.GET("/api/me/profile", undefined); },
+                update(body) { return raw.PATCH("/api/me/profile", { body }); },
+            },
+            orders: {
+                list(query) { return raw.GET("/api/me/orders", query ? { params: { query } } : undefined); },
+                get(id) { return raw.GET("/api/me/orders/{id}", { params: { path: { id } } }); },
+                tracking(id) { return raw.GET("/api/me/orders/{id}/tracking", { params: { path: { id } } }); },
+                reorder(id) { return raw.POST("/api/me/orders/{id}/reorder", { params: { path: { id } } }); },
+            },
+        },
+        webhooks: {
+            list(query) { return raw.GET("/api/webhooks", query ? { params: { query } } : undefined); },
+            get(id) { return raw.GET("/api/webhooks/{id}", { params: { path: { id } } }); },
+            create(body) { return raw.POST("/api/webhooks", { body }); },
+            delete(id) { return raw.DELETE("/api/webhooks/{id}", { params: { path: { id } } }); },
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createSDK, createClient, type SDKOptions } from "./client.js";
+export { authMiddleware, type AuthCredential, type ApiKeyAuth, type BearerAuth } from "./middleware.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createSDK, createClient } from "./client.js";
+export { authMiddleware } from "./middleware.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAmB,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,cAAc,EAAyD,MAAM,iBAAiB,CAAC"}

package/dist/middleware.d.ts

@@ -0,0 +1,17 @@
+import type { Middleware } from "openapi-fetch";
+export interface ApiKeyAuth {
+    type: "api_key";
+    key: string;
+}
+export interface BearerAuth {
+    type: "bearer";
+    token: string;
+}
+export type AuthCredential = ApiKeyAuth | BearerAuth;
+/**
+ * openapi-fetch middleware that injects authentication headers.
+ *
+ * Supports API key (x-api-key header) and Bearer token (Authorization header).
+ */
+export declare function authMiddleware(credential: AuthCredential): Middleware;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,UAAU,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,cAAc,GAAG,UAAU,CAWrE"}

package/dist/middleware.js

@@ -0,0 +1,19 @@
+/**
+ * openapi-fetch middleware that injects authentication headers.
+ *
+ * Supports API key (x-api-key header) and Bearer token (Authorization header).
+ */
+export function authMiddleware(credential) {
+    return {
+        onRequest({ request }) {
+            if (credential.type === "api_key") {
+                request.headers.set("x-api-key", credential.key);
+            }
+            else if (credential.type === "bearer") {
+                request.headers.set("Authorization", `Bearer ${credential.token}`);
+            }
+            return request;
+        },
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,UAA0B;IACvD,OAAO;QACL,SAAS,CAAC,EAAE,OAAO,EAAE;YACnB,IAAI,UAAU,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAClC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;YACnD,CAAC;iBAAM,IAAI,UAAU,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACxC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC;YACrE,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/react.d.ts

@@ -0,0 +1,33 @@
+/**
+ * React Query integration for the UnifiedCommerce SDK.
+ *
+ * Wraps any openapi-fetch client in TanStack Query hooks.
+ * Generic — works with any generated paths type.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from "@porulle/sdk";
+ * import { createCommerceHooks } from "@porulle/sdk/react";
+ * import type { paths } from "./generated/api-types";
+ *
+ * const client = createClient<paths>({ baseUrl: "http://localhost:3000" });
+ * const commerce = createCommerceHooks(client);
+ *
+ * function ProductList() {
+ *   const { data } = commerce.useQuery("get", "/api/catalog/entities", {
+ *     params: { query: { type: "product" } },
+ *   });
+ * }
+ * ```
+ */
+import type createOpenapiClient from "openapi-fetch";
+/**
+ * Creates TanStack Query hooks from any typed openapi-fetch client.
+ *
+ * @param client - A typed openapi-fetch client (from createClient<paths>())
+ * @returns useQuery, useMutation, useSuspenseQuery hooks typed against your paths
+ */
+export declare function createCommerceHooks<TPaths extends {}>(client: ReturnType<typeof createOpenapiClient<TPaths>>): import("openapi-react-query").OpenapiQueryClient<TPaths, `${string}/${string}`>;
+/** Type alias for the hooks object returned by createCommerceHooks. */
+export type CommerceHooks<TPaths extends {} = {}> = ReturnType<typeof createCommerceHooks<TPaths>>;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,mBAAmB,MAAM,eAAe,CAAC;AAErD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,SAAS,EAAE,EACnD,MAAM,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC,mFAGvD;AAED,uEAAuE;AACvE,MAAM,MAAM,aAAa,CAAC,MAAM,SAAS,EAAE,GAAG,EAAE,IAAI,UAAU,CAAC,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC"}

package/dist/react.js

@@ -0,0 +1,33 @@
+/**
+ * React Query integration for the UnifiedCommerce SDK.
+ *
+ * Wraps any openapi-fetch client in TanStack Query hooks.
+ * Generic — works with any generated paths type.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from "@porulle/sdk";
+ * import { createCommerceHooks } from "@porulle/sdk/react";
+ * import type { paths } from "./generated/api-types";
+ *
+ * const client = createClient<paths>({ baseUrl: "http://localhost:3000" });
+ * const commerce = createCommerceHooks(client);
+ *
+ * function ProductList() {
+ *   const { data } = commerce.useQuery("get", "/api/catalog/entities", {
+ *     params: { query: { type: "product" } },
+ *   });
+ * }
+ * ```
+ */
+import createQueryHooks from "openapi-react-query";
+/**
+ * Creates TanStack Query hooks from any typed openapi-fetch client.
+ *
+ * @param client - A typed openapi-fetch client (from createClient<paths>())
+ * @returns useQuery, useMutation, useSuspenseQuery hooks typed against your paths
+ */
+export function createCommerceHooks(client) {
+    return createQueryHooks(client);
+}
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,gBAAgB,MAAM,qBAAqB,CAAC;AAGnD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAsD;IAEtD,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAClC,CAAC"}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@porulle/sdk",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "bun": "./src/react.ts",
+      "import": "./dist/react.js",
+      "types": "./dist/react.d.ts"
+    }
+  },
+  "bin": {
+    "unifiedcommerce-sdk": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 1000",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.17.0",
+    "openapi-typescript-helpers": "^0.1.0"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/node": "^24.5.2",
+    "eslint": "^9.39.1",
+    "openapi-react-query": "^0.5.4",
+    "@tanstack/react-query": "^5.94.5",
+    "openapi-typescript": "^7.13.0",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": ">=5.0.0",
+    "openapi-react-query": ">=0.3.0",
+    "openapi-typescript": ">=7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "openapi-react-query": {
+      "optional": true
+    },
+    "openapi-typescript": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "description": "Typed TypeScript client for any Porulle server. Generated from the OpenAPI spec — every endpoint, request body, and response is type-checked at compile time.",
+  "homepage": "https://porulle-docs.vercel.app",
+  "bugs": {
+    "url": "https://github.com/asyncdotengineering/porulle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asyncdotengineering/porulle.git",
+    "directory": "packages/sdk"
+  },
+  "author": "Porulle contributors"
+}

package/src/cli.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+/**
+ * SDK Codegen CLI — generates TypeScript types from your UC server's OpenAPI spec.
+ *
+ * Usage:
+ *   bunx @porulle/sdk generate                          # from running server on :3000
+ *   bunx @porulle/sdk generate --url http://localhost:4000/api/doc
+ *   bunx @porulle/sdk generate --output src/types/api.ts
+ *
+ * This fetches /api/doc from your running server and runs openapi-typescript
+ * to produce a paths type file. Commit the output alongside your code.
+ */
+
+import { writeFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { execSync } from "node:child_process";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command !== "generate") {
+  console.log(`
+@porulle/sdk — Type Generation CLI
+
+Usage:
+  bunx @porulle/sdk generate [options]
+
+Options:
+  --url <url>       OpenAPI spec URL (default: http://localhost:3000/api/doc)
+  --output <path>   Output file path (default: src/generated/api-types.ts)
+
+Examples:
+  bunx @porulle/sdk generate
+  bunx @porulle/sdk generate --url http://localhost:4000/api/doc
+  bunx @porulle/sdk generate --output src/types/commerce.ts
+  `);
+  process.exit(command === undefined || command === "help" || command === "--help" ? 0 : 1);
+}
+
+const urlIdx = args.indexOf("--url");
+const outputIdx = args.indexOf("--output");
+
+const specUrl = urlIdx !== -1 && args[urlIdx + 1]
+  ? args[urlIdx + 1]!
+  : process.env.API_URL ?? "http://localhost:3000/api/doc";
+
+const outputFile = outputIdx !== -1 && args[outputIdx + 1]
+  ? args[outputIdx + 1]!
+  : "src/generated/api-types.ts";
+
+const outputDir = dirname(outputFile);
+const tempSpec = join(outputDir, "_spec.json");
+
+async function main() {
+  console.log(`Fetching OpenAPI spec from ${specUrl}...`);
+
+  let res: Response;
+  try {
+    res = await fetch(specUrl);
+  } catch (err) {
+    console.error(`\nCould not connect to ${specUrl}`);
+    console.error("");
+    console.error("Make sure your server is running:");
+    console.error("  bun run dev");
+    console.error("");
+    console.error("Or specify a custom URL:");
+    console.error("  bunx @porulle/sdk generate --url http://your-server/api/doc");
+    process.exit(1);
+    return; // unreachable, satisfies TS
+  }
+
+  if (!res.ok) {
+    console.error(`Server returned ${res.status} ${res.statusText}`);
+    console.error("Make sure the OpenAPI spec is enabled (GET /api/doc should return JSON).");
+    process.exit(1);
+  }
+
+  const spec = await res.json() as { paths?: Record<string, unknown> };
+  const pathCount = Object.keys(spec.paths ?? {}).length;
+
+  if (pathCount === 0) {
+    console.error("OpenAPI spec has 0 paths. Is the server configured correctly?");
+    process.exit(1);
+  }
+
+  mkdirSync(outputDir, { recursive: true });
+  writeFileSync(tempSpec, JSON.stringify(spec, null, 2));
+  console.log(`Spec extracted: ${pathCount} paths`);
+
+  console.log(`Generating types → ${outputFile}`);
+  try {
+    execSync(`npx openapi-typescript ${tempSpec} -o ${outputFile}`, {
+      stdio: "inherit",
+    });
+  } catch {
+    console.error("openapi-typescript failed. Is it installed?");
+    console.error("  bun add -d openapi-typescript");
+    process.exit(1);
+  }
+
+  try { unlinkSync(tempSpec); } catch {}
+
+  console.log(`\nDone — ${pathCount} paths typed in ${outputFile}`);
+  console.log("Commit this file alongside your route changes.");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/client.ts

@@ -0,0 +1,126 @@
+import openapiCreateClient from "openapi-fetch";
+import type { PathsWithMethod, MediaType } from "openapi-typescript-helpers";
+import { authMiddleware, type AuthCredential } from "./middleware.js";
+
+export interface SDKOptions {
+  /** Base URL of the UnifiedCommerce server (e.g., "http://localhost:4000"). */
+  baseUrl: string;
+  /** Authentication credential (API key or Bearer token). */
+  auth?: AuthCredential | undefined;
+  /** Additional headers sent with every request. */
+  headers?: Record<string, string> | undefined;
+  /** Custom fetch implementation (for testing or SSR). */
+  fetch?: typeof globalThis.fetch | undefined;
+}
+
+/**
+ * Creates a typed openapi-fetch client for your UnifiedCommerce API.
+ *
+ * Generic — you pass your own generated paths type:
+ *
+ * ```ts
+ * import { createClient } from "@porulle/sdk";
+ * import type { paths } from "./generated/api-types";
+ *
+ * const client = createClient<paths>({
+ *   baseUrl: "http://localhost:3000",
+ *   auth: { type: "api_key", key: "dev-key" },
+ * });
+ *
+ * const { data } = await client.GET("/api/catalog/entities");
+ * ```
+ */
+export function createClient<TPaths extends {}>(options: SDKOptions) {
+  const clientOpts: Parameters<typeof openapiCreateClient<TPaths>>[0] = {
+    baseUrl: options.baseUrl,
+  };
+  if (options.headers) clientOpts.headers = options.headers;
+  if (options.fetch) clientOpts.fetch = options.fetch;
+
+  const client = openapiCreateClient<TPaths>(clientOpts);
+
+  if (options.auth) {
+    client.use(authMiddleware(options.auth));
+  }
+
+  return client;
+}
+
+/**
+ * Creates a typed SDK with ergonomic domain namespaces.
+ *
+ * This is a convenience wrapper that creates an openapi-fetch client
+ * and adds sdk.catalog.list(), sdk.cart.addItem(), etc. on top.
+ *
+ * For full type coverage (including plugin routes), use createClient()
+ * with your own generated paths type instead.
+ *
+ * ```ts
+ * import { createSDK } from "@porulle/sdk";
+ * const sdk = createSDK({ baseUrl: "http://localhost:3000", auth: { ... } });
+ * const { data } = await sdk.catalog.list();
+ * ```
+ */
+export function createSDK(options: SDKOptions) {
+  const client = openapiCreateClient<Record<string, never>>(
+    { baseUrl: options.baseUrl, ...(options.headers ? { headers: options.headers } : {}), ...(options.fetch ? { fetch: options.fetch } : {}) },
+  );
+
+  if (options.auth) {
+    client.use(authMiddleware(options.auth));
+  }
+
+  // Untyped convenience wrappers for core routes.
+  // These work without codegen but have no compile-time body/response validation.
+  // For full types, use createClient<paths>() with your generated types.
+  const raw = client as ReturnType<typeof openapiCreateClient<Record<string, unknown>>>;
+
+  return {
+    raw,
+
+    catalog: {
+      list(query?: Record<string, string>) { return raw.GET("/api/catalog/entities" as never, query ? { params: { query } } as never : undefined as never); },
+      get(idOrSlug: string) { return raw.GET("/api/catalog/entities/{idOrSlug}" as never, { params: { path: { idOrSlug } } } as never); },
+      create(body: Record<string, unknown>) { return raw.POST("/api/catalog/entities" as never, { body } as never); },
+    },
+
+    cart: {
+      create(body: Record<string, unknown>) { return raw.POST("/api/carts" as never, { body } as never); },
+      get(id: string) { return raw.GET("/api/carts/{id}" as never, { params: { path: { id } } } as never); },
+      addItem(id: string, body: Record<string, unknown>) { return raw.POST("/api/carts/{id}/items" as never, { params: { path: { id } }, body } as never); },
+    },
+
+    checkout: {
+      create(body: Record<string, unknown>) { return raw.POST("/api/checkout" as never, { body } as never); },
+    },
+
+    orders: {
+      list(query?: Record<string, string>) { return raw.GET("/api/orders" as never, query ? { params: { query } } as never : undefined as never); },
+      get(idOrNumber: string) { return raw.GET("/api/orders/{idOrNumber}" as never, { params: { path: { idOrNumber } } } as never); },
+    },
+
+    search: {
+      query(query: { q: string; [k: string]: string }) { return raw.GET("/api/search" as never, { params: { query } } as never); },
+    },
+
+    me: {
+      profile: {
+        get() { return raw.GET("/api/me/profile" as never, undefined as never); },
+        update(body: Record<string, unknown>) { return raw.PATCH("/api/me/profile" as never, { body } as never); },
+      },
+      orders: {
+        list(query?: Record<string, string>) { return raw.GET("/api/me/orders" as never, query ? { params: { query } } as never : undefined as never); },
+        get(id: string) { return raw.GET("/api/me/orders/{id}" as never, { params: { path: { id } } } as never); },
+        tracking(id: string) { return raw.GET("/api/me/orders/{id}/tracking" as never, { params: { path: { id } } } as never); },
+        reorder(id: string) { return raw.POST("/api/me/orders/{id}/reorder" as never, { params: { path: { id } } } as never); },
+      },
+    },
+
+    webhooks: {
+      list(query?: Record<string, string>) { return raw.GET("/api/webhooks" as never, query ? { params: { query } } as never : undefined as never); },
+      get(id: string) { return raw.GET("/api/webhooks/{id}" as never, { params: { path: { id } } } as never); },
+      create(body: Record<string, unknown>) { return raw.POST("/api/webhooks" as never, { body } as never); },
+      delete(id: string) { return raw.DELETE("/api/webhooks/{id}" as never, { params: { path: { id } } } as never); },
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { createSDK, createClient, type SDKOptions } from "./client.js";
+export { authMiddleware, type AuthCredential, type ApiKeyAuth, type BearerAuth } from "./middleware.js";

package/src/middleware.ts

@@ -0,0 +1,31 @@
+import type { Middleware } from "openapi-fetch";
+
+export interface ApiKeyAuth {
+  type: "api_key";
+  key: string;
+}
+
+export interface BearerAuth {
+  type: "bearer";
+  token: string;
+}
+
+export type AuthCredential = ApiKeyAuth | BearerAuth;
+
+/**
+ * openapi-fetch middleware that injects authentication headers.
+ *
+ * Supports API key (x-api-key header) and Bearer token (Authorization header).
+ */
+export function authMiddleware(credential: AuthCredential): Middleware {
+  return {
+    onRequest({ request }) {
+      if (credential.type === "api_key") {
+        request.headers.set("x-api-key", credential.key);
+      } else if (credential.type === "bearer") {
+        request.headers.set("Authorization", `Bearer ${credential.token}`);
+      }
+      return request;
+    },
+  };
+}

package/src/react.ts

@@ -0,0 +1,40 @@
+/**
+ * React Query integration for the UnifiedCommerce SDK.
+ *
+ * Wraps any openapi-fetch client in TanStack Query hooks.
+ * Generic — works with any generated paths type.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from "@porulle/sdk";
+ * import { createCommerceHooks } from "@porulle/sdk/react";
+ * import type { paths } from "./generated/api-types";
+ *
+ * const client = createClient<paths>({ baseUrl: "http://localhost:3000" });
+ * const commerce = createCommerceHooks(client);
+ *
+ * function ProductList() {
+ *   const { data } = commerce.useQuery("get", "/api/catalog/entities", {
+ *     params: { query: { type: "product" } },
+ *   });
+ * }
+ * ```
+ */
+
+import createQueryHooks from "openapi-react-query";
+import type createOpenapiClient from "openapi-fetch";
+
+/**
+ * Creates TanStack Query hooks from any typed openapi-fetch client.
+ *
+ * @param client - A typed openapi-fetch client (from createClient<paths>())
+ * @returns useQuery, useMutation, useSuspenseQuery hooks typed against your paths
+ */
+export function createCommerceHooks<TPaths extends {}>(
+  client: ReturnType<typeof createOpenapiClient<TPaths>>,
+) {
+  return createQueryHooks(client);
+}
+
+/** Type alias for the hooks object returned by createCommerceHooks. */
+export type CommerceHooks<TPaths extends {} = {}> = ReturnType<typeof createCommerceHooks<TPaths>>;