@suluk/sdk 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,182 @@
+# @suluk/sdk
+
+**Generate a complete, intuitive TypeScript SDK from one v4 "Suluk" contract — ofetch-based, entity-grouped, fully typed, auth wired, with the v4 superpowers (declared cost + access + input schema) surfaced as typed metadata on every method.**
+
+> **CANDIDATE tooling — not official OpenAPI.** Suluk is a single-contributor candidate for
+> OpenAPI Specification v4.0 ("Moonwalk"), unaffiliated with the OpenAPI Initiative and unable
+> to ratify anything on the SIG's behalf.
+
+## Install
+
+```sh
+bun add @suluk/sdk
+```
+
+`ofetch` and `@cfworker/json-schema` are peer dependencies — bring your own. The **generated** SDK
+imports both at runtime, so an app that ships the output needs `bun add ofetch @cfworker/json-schema`.
+
+## What it does
+
+`generateSdk(doc)` takes a v4 document and returns **one self-contained `.ts` file** (a string) — a
+client library a developer downloads and uses straight away, not a bag of functions:
+
+- **`ofetch`-based `createClient(config)` factory** — auth wired via an `onRequest` interceptor (bearer
+  token or session cookie), retries, configurable `baseURL`.
+- **Entity-grouped methods** — CRUD operations group by entity (`api.product.create(...)`), custom ops
+  by path (`api.checkout.order(...)`). Method-name collisions are resolved deterministically and surfaced.
+- **Fully typed from the schemas** — request bodies, query params, and response types are TS types
+  derived from the contract's JSON Schemas (the same `tsType` mapping is exported for reuse).
+- **Inputs shipped AS DATA + validated directly** — the contract's input JSON Schemas (2020-12) are
+  emitted as a literal `schemas` map and validated by a generic, eval-free engine (`@cfworker/json-schema`,
+  Workers-native) — never transpiled into one validator's source, so what runs is exactly what the
+  contract stores. Each input is exposed as a **Standard Schema** (`.input`), so it drops into
+  react-hook-form / TanStack Form / tRPC unchanged.
+- **v4 facets as typed metadata** — every method carries `.cost` (µ$), `.requires` (access), and `.input`
+  (the Standard Schema), plus a client-level `$manifest` / `$meta` for tooling. These are hints + a
+  client-side guard, **not** enforcement — the server stays the security boundary.
+
+## When to reach for it
+
+- You want to hand API **consumers** a typed client library generated from the contract — e.g. expose a
+  `GET /sdk.ts` route that streams the generated source as a download.
+- You want the client to validate inputs against the contract's real constraints before sending, and to
+  carry cost/access metadata for cost-aware or permission-aware UIs.
+
+**Not** for an admin UI (use `@suluk/panel` / `@suluk/admin`), rendered API reference docs
+(`@suluk/reference` / `@suluk/scalar`), or owned React form/table components (`@suluk/shadcn`). And it
+generates source the consumer **owns** — it does not host a client runtime they have to call home to.
+
+## Usage
+
+`generateSdk` is codegen: feed it a v4 document, get back TypeScript source as a string. Common case —
+serve it as a downloadable file from your API (this is exactly how `saasuluk` exposes its SDK):
+
+```ts
+import { generateSdk } from "@suluk/sdk";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+// `document` is your v4 contract (e.g. projected by @suluk/hono / @suluk/drizzle)
+app.get("/sdk.ts", (c) =>
+  new Response(generateSdk(document, { baseURL: new URL(c.req.url).origin }), {
+    headers: {
+      "content-type": "application/typescript; charset=utf-8",
+      "content-disposition": 'attachment; filename="my-sdk.ts"',
+    },
+  }),
+);
+```
+
+Or write it to disk in a build step:
+
+```ts
+import { generateSdk } from "@suluk/sdk";
+
+const source = generateSdk(v4Document, { baseURL: "https://api.example.com" });
+await Bun.write("./client/suluk-sdk.ts", source);
+```
+
+### Using the generated SDK
+
+The emitted file exports `createClient`. A consumer drops it in alongside `ofetch` +
+`@cfworker/json-schema`:
+
+```ts
+import { createClient } from "./suluk-sdk";
+
+const api = createClient({
+  baseURL: "https://api.example.com",
+  token: () => localStorage.getItem("token"), // string | sync/async getter → `Authorization: Bearer …`
+  // credentials: "include"  // session-cookie auth (default)
+  // validate: false         // skip client-side input validation (default: on)
+});
+
+// entity-grouped: CRUD by entity, custom ops by path
+const products = await api.product.list();
+const order = await api.checkout.order({ items: [{ productId: 1, qty: 2 }] }); // input validated before send
+
+// v4 facets ride along as typed metadata on each method
+api.product.create.cost;      // declared cost in µ$  (number | null)
+api.product.create.requires;  // who can call it      ("anyone" | "admin" | …)
+api.product.create.input;     // the Standard Schema   (plugs into react-hook-form / TanStack Form / tRPC)
+
+// client-level escape hatches + introspection
+api.$fetch;     // the raw ofetch instance
+api.$schemas;   // the contract's input JSON Schemas, as data
+api.$manifest;  // { "<entity.method>": { cost, requires, scope? } }
+api.$meta;      // { operations, totalDeclaredMicroUsd, version }
+```
+
+The generated SDK also exports the shared models from `components.schemas` (a TS `type` + a `…Schema`
+Standard Schema per model, both derived from the one JSON Schema), `SulukValidationError` (thrown when an
+input fails validation), and the `schemas` data map.
+
+### `tsType` — the schema → TS-type mapping
+
+The same JSON-Schema → TS-type-string function the generator uses internally is exported, in case you
+need it standalone (e.g. building adjacent codegen):
+
+```ts
+import { tsType } from "@suluk/sdk";
+
+tsType(doc, { type: "string" });                                  // "string"
+tsType(doc, { type: "array", items: { type: "integer" } });       // "number[]"
+tsType(doc, { type: "object", properties: { a: { type: "string" } }, required: ["a"] }); // "{ a: string }"
+```
+
+## Reactive stores (`generateStores`) — the C037 reactive layer
+
+`generateSdk` gives you the typed RPC calls. `generateStores(doc)` projects the **C037 reactive facet**
+(`x-suluk-store` + `x-suluk-notify`) into a typed **Nano Stores** layer *on top of* that client — also a
+self-contained `.ts` string. The contract declares the **policy**; the generator emits the **plumbing**; your
+app fills the **behavior** through an unjs [`hookable`](https://unjs.io/packages/hookable) hook-bus:
+
+- **STATES** — a query op (`x-suluk-store.key`) → a `$<key>` `@nanostores/query` fetcher store (cached by
+  `ttl`, optional `revalidateOnFocus`); a parameterized query → a `(…args) => store` factory.
+- **EVENTS** — a mutation op (`x-suluk-store.invalidates`) → an action that invalidates the named stores on a
+  2xx (→ refetch), re-throwing so callers still `catch` (the propagation contract).
+- **CALLBACKS** — the declared `x-suluk-notify` status→severity policy **classifies + emits**; you tap typed
+  hooks (`notify`, `request:error`, `mutation:success`, `mutation:settled`, `store:invalidate`) to render/act.
+
+```ts
+import { generateSdk, generateStores } from "@suluk/sdk";
+const sdkSrc    = generateSdk(doc, { baseURL });   // -> web/src/lib/sdk.ts
+const storesSrc = generateStores(doc);             // -> web/src/lib/stores.ts (imports SulukClient from ./sdk)
+```
+
+```ts
+// in the app: declare policy in the contract, inject rendering once
+const stores = createStores(api);
+stores.hooks.hook("notify", ({ severity, problem }) => toast[severity](problem.detail ?? problem.title ?? "Error"));
+const { data } = useStore(stores.$paymentMethods);          // STATE
+await stores.actions.setDefaultPaymentMethod({ id });        // EVENT -> auto-invalidates $paymentMethods
+```
+
+It deliberately does **not** declare multi-call / zero-call actions, optimistic/rollback, retry, or
+derived/normalized state — those are composition, app-config, or a typed seam, never the contract (ADR C037
+§"Parity boundary"). The generated peer deps are `@nanostores/query`, `nanostores`, `hookable`.
+
+> Overlap: `@suluk/nano-stores` is a *runtime* `createApiStores(RouteContract[])` that does not read the
+> facet; `generateStores` is the **owned-source**, v4-doc + facet-driven projection (the `generateSdk` posture).
+
+## API
+
+| Export | What it does |
+| --- | --- |
+| `generateSdk(doc, opts?)` | Takes an `OpenAPIv4Document`, returns a complete self-contained SDK as a TypeScript source string. |
+| `generateStores(doc, opts?)` | Projects the C037 reactive facet into a self-contained Nano Stores layer (states + invalidation + hookable callbacks) over the generated client. |
+| `tsType(doc, schema, depth?)` | Maps a JSON Schema to a TypeScript type string (used for typed inputs/responses). |
+| `resolveOps(doc)` | walkOps + deterministic collision resolution — the shared op list (so SDK + stores accessor names never drift). |
+| `SdkOptions` / `StoresOptions` | Options — `{ baseURL? }` / `{ clientModule? }`. |
+
+## Boundary
+
+This is **codegen** (L3: render/generate, never host) — `generateSdk` returns a string of source the
+consumer owns and can edit; nothing here becomes a runtime they must call home to. The package does **not**
+fetch your contract, host a client, or enforce the facets: `.cost` / `.requires` are inert metadata + a
+client-side guard, and the **server is the security boundary** (per ADR C022). You inject the v4 document
+(projected by `@suluk/hono` / `@suluk/drizzle` / your own source) and the `baseURL`; serving the generated
+file and authenticating real requests stay app-side.
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Generate a COMPLETE, intuitive TypeScript SDK from a v4 'Suluk' contract — built on ofetch, entity-grouped, fully typed from the schemas, auth wired (bearer/session) via interceptors, and the v4 superpowers (declared cost + access) surfaced as typed metadata. Not a bag of functions: a library a developer downloads and uses straight away. CANDIDATE tooling.",
   "publishConfig": {
     "access": "public"
@@ -19,7 +19,7 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@suluk/core": "^0.1.7"
+    "@suluk/core": "^0.1.11"
   },
   "peerDependencies": {
     "ofetch": "^1.5.1",

package/src/generate-stores.ts

@@ -0,0 +1,239 @@
+/**
+ * generateStores — project the C037 reactive facet (`x-suluk-store` + `x-suluk-notify`) into a typed Nano Stores
+ * reactive layer ON TOP of the generated SDK client. One self-contained .ts file (the L3 codegen posture of
+ * generateSdk — owned source, no @suluk/* runtime dep), implementing the council-verified parity standard (ADR C037):
+ *
+ *   • POLICY is declared, PLUMBING is emitted, BEHAVIOR is a typed seam.
+ *   • STATES  — a query op (`x-suluk-store.key`) becomes a `$<key>` @nanostores/query fetcher store (lazy, cached by
+ *     `ttl`, optionally `revalidateOnFocus`); a parameterized query becomes a `(…args) => store` factory.
+ *   • EVENTS  — a mutation op (`x-suluk-store.invalidates`) invalidates the named query stores on a 2xx → refetch.
+ *   • CALLBACKS — surfaced through an unjs `hookable` hook-bus (ecosystem-parity with ofetch): the DECLARED
+ *     `x-suluk-notify` status→severity policy CLASSIFIES + EMITS; the app TAPS `hooks.hook(name, fn)` to render/act.
+ *     `onSuccess` text rides the same `notify` hook. The renderer is injected; the policy is declared.
+ *
+ * What it deliberately does NOT do (parity boundary, ADR §"Parity boundary"): multi-call / zero-call ACTIONS (compose
+ * over the generated primitives, or a server aggregate endpoint), optimistic/rollback, retry/cache tuning, derived /
+ * normalized state — all BEHAVIOR (a hook/seam) or target-specific adapter config, never the contract.
+ *
+ * The client accessor names come from the SAME `resolveOps` generateSdk uses, so a store calls EXACTLY the method the
+ * SDK emitted (no drift). Generated peer deps: `@nanostores/query`, `nanostores`, `hookable`.
+ */
+import type { OpenAPIv4Document, SulukNotifyPolicy } from "@suluk/core";
+import { resolveOps, clientAccessor, ident, camel, type OpInfo } from "./generate";
+
+export interface StoresOptions {
+  /** Import specifier for the generated SDK module (where `SulukClient` lives). Default `"./sdk"`. */
+  clientModule?: string;
+}
+
+/** The client TYPE index for an op (`["paymentMethods"]["list"]`), matching `clientAccessor`'s runtime path. */
+const typeIndex = (op: OpInfo): string =>
+  (op.ns.length ? [op.ns[op.ns.length - 1]!, op.member] : [op.member]).map((p) => `["${ident(p!)}"]`).join("");
+
+/** A store/action whose SDK method takes arguments (path params / query / body) → a parameterized factory. */
+const argful = (op: OpInfo): boolean => op.pathParams.length > 0 || op.queryRaw != null || op.bodyRaw != null;
+
+export function generateStores(doc: OpenAPIv4Document, opts: StoresOptions = {}): string {
+  const { ops } = resolveOps(doc);
+  const clientModule = opts.clientModule ?? "./sdk";
+  const title = doc.info?.title ?? "API";
+  const notify = (doc as { ["x-suluk-notify"]?: SulukNotifyPolicy })["x-suluk-notify"] ?? {};
+
+  const queries = ops.filter((o) => o.store?.key);
+  // a mutation = a store facet that is NOT a query (no `key`) and does something on write: invalidate stores OR toast onSuccess.
+  const mutations = ops.filter((o) => o.store && !o.store.key && ((o.store.invalidates && o.store.invalidates.length > 0) || !!o.store.onSuccess));
+
+  // ── STATES: a $<key> fetcher store (or a (…args)=>store factory) per query op ──
+  const queryDecls = queries
+    .map((op) => {
+      const key = op.store!.key!;
+      const v = "$" + ident(key);
+      const acc = clientAccessor(op);
+      const T = `Awaited<ReturnType<SulukClient${typeIndex(op)}>>`;
+      const settings: string[] = [];
+      if (op.store!.ttl != null) settings.push(`cacheLifetime: ${Math.round(op.store!.ttl * 1000)}`);
+      if (op.store!.revalidateOnFocus) settings.push(`revalidateOnFocus: true`);
+      const setStr = settings.length ? `, ${settings.join(", ")}` : "";
+      // on success clear the per-op dedupe marker so a recovered query re-arms notifications; on error report+dedupe (true)
+      // so nanoquery's retry-backoff + revalidate-on-focus re-runs don't re-toast the SAME failure. Always re-throw.
+      if (argful(op)) {
+        return (
+          `  const ${v} = (...args: Parameters<SulukClient${typeIndex(op)}>) =>\n` +
+          `    createFetcherStore<${T}>([${JSON.stringify("@" + key + "\u0000")}, JSON.stringify(args)], {\n` +
+          `      fetcher: async () => { try { const v = await client.${acc}(...args); _seen.delete(${JSON.stringify(key)}); return v; } catch (e) { await report(${JSON.stringify(key)}, e, true); throw e; } }${setStr},\n` +
+          `    });`
+        );
+      }
+      return (
+        `  const ${v} = createFetcherStore<${T}>([${JSON.stringify("@" + key)}], {\n` +
+        `    fetcher: async () => { try { const v = await client.${acc}(); _seen.delete(${JSON.stringify(key)}); return v; } catch (e) { await report(${JSON.stringify(key)}, e, true); throw e; } }${setStr},\n` +
+        `  });`
+      );
+    })
+    .join("\n");
+
+  // ── invalidators: store key → a function that refreshes it. Use REVALIDATE (not invalidate): revalidateKeys keeps the
+  //    cached data and refetches in the background, so a list stays on screen during a mutation refresh instead of
+  //    blinking to a spinner. Exact `.revalidate()` for plain stores; a delimited-prefix match for parameterized
+  //    families (@nanostores/query joins key parts with "", so the "@<key>\u0000" prefix — NUL-delimited — is unambiguous
+  //    and can't collide a key that is another key's string-prefix, e.g. "credit" vs "credits"). ──
+  const invalDecls = queries
+    .map((op) => {
+      const key = op.store!.key!;
+      const v = "$" + ident(key);
+      const body = argful(op)
+        ? `ctx.revalidateKeys((k) => typeof k === "string" && k.startsWith(${JSON.stringify("@" + key + "\u0000")}))`
+        : `${v}.revalidate()`;
+      return `    ${JSON.stringify(key)}: () => { void hooks.callHook("store:invalidate", { store: ${JSON.stringify(key)} }); ${body}; },`;
+    })
+    .join("\n");
+
+  // ── EVENTS + CALLBACKS: a wrapped action per mutation op (invalidate named stores on 2xx; surface onSuccess; route
+  //    errors through the notify policy; ALWAYS re-throw so callers still catch — the propagation contract). ──
+  const actionDecls = mutations
+    .map((op) => {
+      const name = ident(camel(op.name));
+      const acc = clientAccessor(op);
+      const inv = op.store!.invalidates ?? [];
+      const invCalls = inv.length ? inv.map((k) => `_invalidate[${JSON.stringify(k)}]?.();`).join(" ") : "/* no stores to invalidate */";
+      const successHook = op.store!.onSuccess
+        ? `\n      await hooks.callHook("notify", { severity: "success", problem: { status: 200, detail: ${JSON.stringify(op.store!.onSuccess)} } });`
+        : "";
+      return (
+        `  async function ${name}(...args: Parameters<SulukClient${typeIndex(op)}>) {\n` +
+        `    try {\n` +
+        `      const r = await client.${acc}(...args);\n` +
+        `      ${invCalls}\n` +
+        `      await hooks.callHook("mutation:success", { op: ${JSON.stringify(name)}, invalidated: ${JSON.stringify(inv)} });${successHook}\n` +
+        `      return r;\n` +
+        `    } catch (e) {\n` +
+        `      await report(${JSON.stringify(name)}, e);\n` +
+        `      throw e;\n` +
+        `    } finally {\n` +
+        `      await hooks.callHook("mutation:settled", { op: ${JSON.stringify(name)} });\n` +
+        `    }\n` +
+        `  }`
+      );
+    })
+    .join("\n");
+
+  const queryNames = queries.map((op) => "$" + ident(op.store!.key!));
+  const actionNames = mutations.map((op) => ident(camel(op.name)));
+  const ret =
+    `  return { ` +
+    (queryNames.length ? queryNames.join(", ") + ", " : "") +
+    `actions: { ${actionNames.join(", ")} }, report, hooks, ctx };`;
+
+  return `/**
+ * ${title} — reactive Nano Stores layer. AUTO-GENERATED by @suluk/sdk (generateStores) from the v4 contract. Do not edit.
+ *
+ * Built from the C037 reactive facet: ${queries.length} query store(s), ${mutations.length} mutation action(s). STATES are
+ * @nanostores/query fetcher stores; EVENTS are mutation→store invalidations; CALLBACKS surface through an unjs hookable
+ * hook-bus (the declared x-suluk-notify policy classifies + emits; YOU tap hooks.hook(name, fn) to render/act). The
+ * client accessors match the generated SDK exactly (one resolveOps source). Self-contained: no @suluk/* runtime dep.
+ *
+ *   import { createClient } from "${clientModule}";
+ *   import { createStores } from "./stores";
+ *   import { toast } from "sonner";
+ *   const api = createClient({ baseURL: "…" });
+ *   const stores = createStores(api);
+ *   stores.hooks.hook("notify", ({ severity, problem }) => {
+ *     if (severity === "silent") return;                         // sonner exposes toast.warning (not toast.warn) — map it:
+ *     (severity === "warn" ? toast.warning : toast[severity])(problem.detail ?? problem.title ?? "Error");
+ *   });
+ *   // component:  const { data } = useStore(stores.$paymentMethods);   action:  await stores.actions.setDefaultPaymentMethod({ id });
+ *
+ * Requires: \`npm i @nanostores/query nanostores hookable\`.
+ */
+import { nanoquery } from "@nanostores/query";
+import { createHooks, type Hookable } from "hookable";
+import type { SulukClient } from "${clientModule}";
+
+/** How loudly a response surfaces (the x-suluk-notify severities). */
+export type NotifySeverity = "silent" | "info" | "success" | "warn" | "error";
+/** An RFC-9457-ish problem surfaced to hooks (the parsed error body + its status). */
+export interface StoreProblem {
+  status: number | "network";
+  title?: string;
+  detail?: string;
+  raw?: unknown;
+}
+
+/** The typed hook bus (unjs hookable). Tap these to render/act — the BEHAVIOR seam (the contract declares POLICY only). */
+export interface StoreHooks {
+  /** the policy decided this response should surface — render it (e.g. a toast). */
+  notify: (e: { severity: NotifySeverity; problem: StoreProblem }) => void | Promise<void>;
+  /** a query/action errored (fires for EVERY error, even silent ones — for logging). */
+  "request:error": (e: { op: string; severity: NotifySeverity; problem: StoreProblem }) => void | Promise<void>;
+  /** a mutation action succeeded (2xx) and invalidated its stores. */
+  "mutation:success": (e: { op: string; invalidated: string[] }) => void | Promise<void>;
+  /** a mutation action settled (success or error). */
+  "mutation:settled": (e: { op: string }) => void | Promise<void>;
+  /** a query store was invalidated (about to refetch). */
+  "store:invalidate": (e: { store: string }) => void | Promise<void>;
+}
+
+/** The DECLARED status→severity policy (x-suluk-notify). Keys: a status ("402"), a class ("2xx"/"4xx"/"5xx"), or "network". */
+const NOTIFY: Record<string, NotifySeverity> = ${JSON.stringify(notify)};
+
+/** Classify a status to a severity: exact status ("402" / "network") > class (Nxx) > "silent". */
+function classify(status: number | "network"): NotifySeverity {
+  const k = String(status); // exact key — covers a numeric status AND "network"
+  if (NOTIFY[k]) return NOTIFY[k]!;
+  if (typeof status === "number") {
+    const cls = Math.floor(status / 100) + "xx";
+    if (NOTIFY[cls]) return NOTIFY[cls]!;
+  }
+  return "silent";
+}
+
+/** Extract an RFC-9457 problem from an ofetch error (status + parsed body). */
+function problemOf(e: unknown): StoreProblem {
+  const err = (e ?? {}) as { status?: number; statusCode?: number; response?: { status?: number; _data?: unknown }; data?: { title?: string; detail?: string } };
+  const raw = (err.response?.status ?? err.status ?? err.statusCode);
+  const status: number | "network" = typeof raw === "number" ? raw : "network";
+  const data = (err.data ?? (err.response?._data as { title?: string; detail?: string } | undefined)) ?? undefined;
+  return { status, title: data?.title, detail: data?.detail ?? (e instanceof Error ? e.message : undefined), raw: data };
+}
+
+export interface CreateStoresOptions {
+  /** Bring your own hook bus (e.g. to share one across modules). Defaults to a fresh \`createHooks<StoreHooks>()\`. */
+  hooks?: Hookable<StoreHooks>;
+}
+
+/** Create the reactive store layer for ${title}, bound to an SDK client. The contract declares the policy; you inject the rendering via \`hooks\`. */
+export function createStores(client: SulukClient, options: CreateStoresOptions = {}) {
+  const hooks = options.hooks ?? createHooks<StoreHooks>();
+  const [createFetcherStore, , ctx] = nanoquery();
+  /** last surfaced status per op — so an AUTO re-run of a failing query (retry-backoff / revalidate-on-focus) doesn't
+   *  re-toast the SAME failure. A query clears its entry on success; user-triggered actions/one-offs pass dedupe=false. */
+  const _seen = new Map<string, number | "network">();
+
+  /** classify → fire request:error (always) → fire notify (unless silent, or — when \`dedupe\` — unchanged since last).
+   *  The error seam — exposed as \`report\` so one-off / multi-call actions you compose in app code route errors through
+   *  the SAME declared notify policy. Pass \`dedupe=true\` for auto-refetching queries; omit it for user-driven calls. */
+  async function report(op: string, e: unknown, dedupe = false): Promise<void> {
+    const problem = problemOf(e);
+    const severity = classify(problem.status);
+    await hooks.callHook("request:error", { op, severity, problem });
+    if (severity === "silent") return;
+    if (dedupe && _seen.get(op) === problem.status) return;
+    _seen.set(op, problem.status);
+    await hooks.callHook("notify", { severity, problem });
+  }
+
+${queryDecls || "  // (no query stores declared)"}
+
+  const _invalidate: Record<string, () => void> = {
+${invalDecls}
+  };
+
+${actionDecls || "  // (no mutation actions declared)"}
+
+${ret}
+}
+
+/** The reactive store layer's shape (stores + actions + hooks + the @nanostores/query ctx). */
+export type SulukStores = ReturnType<typeof createStores>;
+`;
+}

package/src/generate.ts

@@ -11,12 +11,12 @@
  *     (the Standard Schema). Metadata + a client-side guard, not enforcement — the server is the boundary (C022).
  * Static TS types come from the SAME JSON Schema (tsType), so the body is typed AND validated from one source.
  */
-import type { OpenAPIv4Document } from "@suluk/core";
+import type { OpenAPIv4Document, SulukStore } from "@suluk/core";
 import { isReference } from "@suluk/core";
 
 const reserved = new Set(["delete", "new", "function", "default", "return", "class", "in", "for"]);
-const ident = (s: string) => { const c = s.replace(/[^a-zA-Z0-9_$]/g, "_").replace(/^[0-9]/, "_$&"); return reserved.has(c) ? `${c}_` : c; };
-const camel = (s: string) => s.replace(/[-_/]+(.)/g, (_, c) => c.toUpperCase()).replace(/[^a-zA-Z0-9_$]/g, "");
+export const ident = (s: string) => { const c = s.replace(/[^a-zA-Z0-9_$]/g, "_").replace(/^[0-9]/, "_$&"); return reserved.has(c) ? `${c}_` : c; };
+export const camel = (s: string) => s.replace(/[-_/]+(.)/g, (_, c) => c.toUpperCase()).replace(/[^a-zA-Z0-9_$]/g, "");
 const jsKey = (k: string) => (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(k) ? k : JSON.stringify(k));
 const refName = (r: unknown) => (isReference(r) ? String((r as { $ref: string }).$ref).split("/").pop()! : null);
 
@@ -49,11 +49,13 @@ interface RawReq {
   responses?: Record<string, { status: string | number; contentSchema?: unknown }>;
   ["x-suluk-cost"]?: { estimateMicroUsd?: number; components?: { microUsd?: number }[] };
   ["x-suluk-access"]?: { requires?: string; scope?: string };
+  ["x-suluk-store"]?: SulukStore;
 }
-interface OpInfo {
+export interface OpInfo {
   name: string; ns: string[]; member: string; method: string; uri: string;
   pathParams: string[]; queryRaw?: unknown; bodyRaw?: unknown; respType: string;
   cost: number | null; requires: string; scope?: string; summary?: string;
+  store?: SulukStore; // the C037 reactive facet (read by generateStores, not generateSdk)
   bid?: string; qid?: string; bodyTs?: string; queryTs?: string; // assigned after collision resolution
 }
 
@@ -82,12 +84,42 @@ function walkOps(doc: OpenAPIv4Document): OpInfo[] {
         name, ns, member, method: req.method.toLowerCase(), uri, pathParams: pathVars(uri),
         queryRaw: ps.query, bodyRaw: req.contentSchema ?? ps.body, respType: respType(doc, req),
         cost: costOf(req), requires: acc?.requires ?? "anyone", scope: acc?.scope, summary: req.summary,
+        store: req["x-suluk-store"],
       });
     }
   }
   return ops;
 }
 
+/**
+ * walkOps + DETERMINISTIC method-name collision resolution — SHARED by generateSdk AND generateStores so the client
+ * accessor names (`client.<ns>.<member>`) can NEVER drift between the two projections. Mutates `op.member` in place;
+ * returns the resolved ops + the human-readable collision list (for the SDK header). One source of accessor identity.
+ */
+export function resolveOps(doc: OpenAPIv4Document): { ops: OpInfo[]; collisions: string[] } {
+  const ops = walkOps(doc);
+  const collisions: string[] = [];
+  const byKey = new Map<string, OpInfo[]>();
+  for (const op of ops) { const k = [...op.ns, op.member].join("."); (byKey.get(k) ?? byKey.set(k, []).get(k)!).push(op); }
+  for (const [key, list] of byKey) {
+    if (list.length < 2) continue;
+    collisions.push(`client.${key} ← ${list.map((o) => o.name).join(", ")}`);
+    const used = new Map<string, number>();
+    for (const op of [...list].sort((a, b) => a.name.localeCompare(b.name) || a.method.localeCompare(b.method))) {
+      const cand = op.member + op.method.charAt(0).toUpperCase() + op.method.slice(1);
+      const n = used.get(cand) ?? 0; used.set(cand, n + 1);
+      op.member = n === 0 ? cand : `${cand}${n + 1}`;
+    }
+  }
+  return { ops, collisions };
+}
+
+/** The client accessor for an op — the dotted path AFTER `client.` (e.g. `paymentMethods.list`). Matches emitTree's
+ *  by-last-namespace-segment grouping, so `createStores` calls EXACTLY the method `generateSdk` emitted. */
+export function clientAccessor(op: OpInfo): string {
+  return op.ns.length ? `${ident(op.ns[op.ns.length - 1]!)}.${ident(op.member)}` : ident(op.member);
+}
+
 function emitMethod(op: OpInfo): string {
   const args: string[] = op.pathParams.map((p) => `${ident(p)}: string | number`);
   if (op.qid) args.push(`query?: ${op.queryTs}`);
@@ -113,22 +145,9 @@ function emitTree(ops: OpInfo[]): string {
 export interface SdkOptions { baseURL?: string }
 
 export function generateSdk(doc: OpenAPIv4Document, opts: SdkOptions = {}): string {
-  const ops = walkOps(doc);
-  // resolve method-name collisions DETERMINISTICALLY (council wf4pmh1ie: never a runtime guess) — append the HTTP
-  // method, then a stable index; surface them in the header.
-  const collisions: string[] = [];
-  const byKey = new Map<string, OpInfo[]>();
-  for (const op of ops) { const k = [...op.ns, op.member].join("."); (byKey.get(k) ?? byKey.set(k, []).get(k)!).push(op); }
-  for (const [key, list] of byKey) {
-    if (list.length < 2) continue;
-    collisions.push(`client.${key} ← ${list.map((o) => o.name).join(", ")}`);
-    const used = new Map<string, number>();
-    for (const op of [...list].sort((a, b) => a.name.localeCompare(b.name) || a.method.localeCompare(b.method))) {
-      const cand = op.member + op.method.charAt(0).toUpperCase() + op.method.slice(1);
-      const n = used.get(cand) ?? 0; used.set(cand, n + 1);
-      op.member = n === 0 ? cand : `${cand}${n + 1}`;
-    }
-  }
+  // resolveOps does walkOps + DETERMINISTIC collision resolution (council wf4pmh1ie: never a runtime guess), shared
+  // with generateStores so accessor names can't drift.
+  const { ops, collisions } = resolveOps(doc);
 
   // Emit a JSON Schema AS A LITERAL. When it $refs components, splice them in as $defs and rewrite the pointers,
   // so each validator is self-contained (the generic engine resolves refs without the whole document).

package/src/index.ts

@@ -6,4 +6,13 @@
  *   import { generateSdk } from "@suluk/sdk";
  *   const tsSource = generateSdk(v4Document, { baseURL: "https://api.example.com" }); // a self-contained .ts file
  */
-export { generateSdk, tsType, type SdkOptions } from "./generate";
+export { generateSdk, tsType, resolveOps, clientAccessor, type SdkOptions, type OpInfo } from "./generate";
+/**
+ * generateStores(doc) — project the C037 reactive facet (`x-suluk-store` + `x-suluk-notify`) into a typed Nano Stores
+ * reactive layer (states + mutation→store invalidation + a hookable callback seam) on top of the generated client.
+ *
+ *   import { generateSdk, generateStores } from "@suluk/sdk";
+ *   const sdk = generateSdk(doc, { baseURL });   // the typed RPC client
+ *   const stores = generateStores(doc);          // the reactive layer over it (a self-contained .ts file)
+ */
+export { generateStores, type StoresOptions } from "./generate-stores";

package/test/stores.test.ts

@@ -0,0 +1,99 @@
+import { test, expect, describe } from "bun:test";
+import { generateStores } from "../src/index";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+// A contract carrying the C037 reactive facet: a plain query store (session), a cached query store (paymentMethods),
+// a parameterized query store (pet/{id} → a factory), a mutation that invalidates + onSuccess, and a doc notify policy.
+const doc = {
+  openapi: "4.0.0-candidate",
+  info: { title: "Store API" },
+  "x-suluk-notify": { "2xx": "silent", "401": "silent", "402": "error", "4xx": "warn", "5xx": "error", network: "error" },
+  paths: {
+    session: { requests: { getSession: { method: "get", responses: { ok: { status: 200 } }, "x-suluk-store": { key: "session", ttl: 300, revalidateOnFocus: true } } } },
+    paymentMethods: { requests: { listPaymentMethods: { method: "get", responses: { ok: { status: 200, contentSchema: { type: "object", properties: { methods: { type: "array", items: { type: "object", properties: { id: { type: "string" } } } } } } } }, "x-suluk-store": { key: "paymentMethods", ttl: 60 } } } },
+    "billing/methods/default": { requests: { setDefaultPaymentMethod: { method: "post", contentSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] }, responses: { ok: { status: 200 } }, "x-suluk-store": { invalidates: ["paymentMethods"], onSuccess: "Default card updated." } } } },
+    "pet/{id}": { requests: { getPet: { method: "get", responses: { ok: { status: 200 } }, "x-suluk-store": { key: "pet", params: ["id"] } } } },
+  },
+} as unknown as OpenAPIv4Document;
+
+describe("@suluk/sdk generateStores — a typed Nano Stores reactive layer from the C037 facet", () => {
+  const stores = generateStores(doc);
+
+  test("emits a self-contained @nanostores/query + hookable layer over the SDK client", () => {
+    expect(stores).toContain('import { nanoquery } from "@nanostores/query"');
+    expect(stores).toContain('import { createHooks, type Hookable } from "hookable"');
+    expect(stores).toContain('import type { SulukClient } from "./sdk"'); // client TYPE only — self-contained
+    expect(stores).toContain("export function createStores(client: SulukClient");
+    expect(stores).toContain("const [createFetcherStore, , ctx] = nanoquery()");
+    expect(stores).toContain("Requires: `npm i @nanostores/query nanostores hookable`");
+  });
+
+  test("STATES — a $<key> fetcher store per query op, typed off the client, with ttl/focus settings", () => {
+    expect(stores).toContain('const $session = createFetcherStore<Awaited<ReturnType<SulukClient["session"]["get"]>>>(["@session"]');
+    expect(stores).toContain("cacheLifetime: 300000"); // ttl seconds → ms
+    expect(stores).toContain("revalidateOnFocus: true");
+    expect(stores).toContain("client.session.get()"); // calls the EXACT SDK accessor (shared resolveOps)
+    expect(stores).toContain('const $paymentMethods = createFetcherStore<Awaited<ReturnType<SulukClient["paymentMethods"]["list"]>>>(["@paymentMethods"]');
+    expect(stores).toContain("cacheLifetime: 60000");
+  });
+
+  test("a parameterized query (path param) becomes a (…args)=>store factory keyed by the args (delimited prefix)", () => {
+    expect(stores).toContain('const $pet = (...args: Parameters<SulukClient["pet"]["get"]>) =>');
+    expect(stores).toContain("JSON.stringify(args)], {"); // parameterized query store keyed by its args
+    expect(stores).toContain("client.pet.get(...args)");
+  });
+
+  test("EVENTS — a mutation action invalidates the named stores on 2xx + fires mutation:success", () => {
+    expect(stores).toContain('async function setDefaultPaymentMethod(...args: Parameters<SulukClient["methods"]["default_"]>)');
+    expect(stores).toContain("const r = await client.methods.default_(...args);"); // matches the real SDK accessor
+    expect(stores).toContain('_invalidate["paymentMethods"]?.();');
+    expect(stores).toContain('await hooks.callHook("mutation:success", { op: "setDefaultPaymentMethod", invalidated: ["paymentMethods"] });');
+    expect(stores).toContain("throw e;"); // propagation contract — re-throw after the error seam
+    expect(stores).toContain('await hooks.callHook("mutation:settled"');
+  });
+
+  test("CALLBACKS — onSuccess rides the notify hook; the x-suluk-notify policy is compiled + classified", () => {
+    expect(stores).toContain('detail: "Default card updated."');
+    expect(stores).toContain("const NOTIFY: Record<string, NotifySeverity> = {"); // the policy compiled to a data map
+    expect(stores).toContain('"402":"error"');
+    expect(stores).toContain('"network":"error"');
+    expect(stores).toContain('"2xx":"silent"');
+    expect(stores).toContain("function classify(status: number | \"network\"): NotifySeverity");
+    expect(stores).toContain('if (severity === "silent") return;'); // policy decides; renderer injected
+    expect(stores).toContain("export interface StoreHooks");
+  });
+
+  test("invalidators — REVALIDATE (keep cache visible): exact .revalidate() for plain stores; delimited-prefix for families", () => {
+    expect(stores).toContain('"session": () => {');
+    expect(stores).toContain("$session.revalidate()");
+    expect(stores).toContain('ctx.revalidateKeys((k) => typeof k === "string" && k.startsWith('); // parameterized family // pet is parameterized
+  });
+
+  test("query errors dedupe so an auto re-run (retry/refocus) of the SAME failure doesn't re-toast", () => {
+    expect(stores).toContain("const _seen = new Map<string, number | \"network\">()");
+    expect(stores).toContain("if (dedupe && _seen.get(op) === problem.status) return;");
+    expect(stores).toContain('catch (e) { await report("session", e, true); throw e; }'); // queries dedupe
+    expect(stores).toContain('_seen.delete("session")'); // cleared on success → re-arms
+  });
+
+  test("returns the stores + actions + hooks + ctx", () => {
+    expect(stores).toContain("return { $session, $paymentMethods, $pet, actions: { setDefaultPaymentMethod }, report, hooks, ctx };");
+    expect(stores).toContain("export type SulukStores = ReturnType<typeof createStores>");
+  });
+
+  test("clientModule option redirects the type import", () => {
+    expect(generateStores(doc, { clientModule: "../lib/sdk" })).toContain('import type { SulukClient } from "../lib/sdk"');
+  });
+
+  test("the emitted source is syntactically valid TypeScript (transpiles clean)", () => {
+    expect(() => new Bun.Transpiler({ loader: "tsx" }).transformSync(stores)).not.toThrow();
+  });
+
+  test("declares nothing for a contract with no reactive facet (no stores/actions)", () => {
+    const bare = generateStores({ openapi: "4.0.0-candidate", info: { title: "Bare" }, paths: { ping: { requests: { getPing: { method: "get", responses: { ok: { status: 200 } } } } } } } as unknown as OpenAPIv4Document);
+    expect(bare).toContain("// (no query stores declared)");
+    expect(bare).toContain("// (no mutation actions declared)");
+    expect(bare).toContain("return { actions: {  }, report, hooks, ctx };");
+    expect(() => new Bun.Transpiler({ loader: "tsx" }).transformSync(bare)).not.toThrow();
+  });
+});