@suluk/sdk 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/sdk",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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,8 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@suluk/core": "^0.1.11"
+    "@suluk/core": "^0.1.13",
+    "@suluk/examples": "^0.1.0"
   },
   "peerDependencies": {
     "ofetch": "^1.5.1",

package/src/generate-stores.ts

@@ -204,7 +204,19 @@ export interface CreateStoresOptions {
 /** 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();
+  // A bounded cache: @nanostores/query's default cache (a plain Map) is never evicted (cacheLifetime only gates a HIT),
+  // so a parameterized store driven by free text (a search box) would grow it for the page's lifetime. Cap it — evict
+  // the oldest entry past the limit (LRU-ish). The entry shape matches @nanostores/query's so the type stays exact.
+  const cache = new Map<string, { data?: unknown; error?: unknown; retryCount?: number; created?: number; expires?: number }>();
+  const _set = cache.set.bind(cache);
+  cache.set = (k, v) => {
+    if (!cache.has(k) && cache.size >= 500) {
+      const oldest = cache.keys().next().value;
+      if (oldest !== undefined) cache.delete(oldest);
+    }
+    return _set(k, v);
+  };
+  const [createFetcherStore, , ctx] = nanoquery({ cache });
   /** 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">();

package/src/generate.ts

@@ -8,11 +8,14 @@
  *   • an ofetch-based createClient(config) factory — auth wired via an onRequest interceptor (bearer / cookie)
  *   • methods grouped intuitively: CRUD by entity (client.product.create), custom ops by path (client.checkout.order)
  *   • the v4 SUPERPOWERS surfaced as TYPED METADATA on each method: `.cost` (µ$), `.requires` (access), `.input`
- *     (the Standard Schema). Metadata + a client-side guard, not enforcement — the server is the boundary (C022).
+ *     (the Standard Schema), `.fields` (C041 per-input origin: input/sourced/computed + a wireable source edge — so a
+ *     caller knows which inputs to faker, which to chain from a prior call, and which are server-set). 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, SulukStore } from "@suluk/core";
 import { isReference } from "@suluk/core";
+import { describeInputs, type FieldDescriptor } from "@suluk/examples";
 
 const reserved = new Set(["delete", "new", "function", "default", "return", "class", "in", "for"]);
 export const ident = (s: string) => { const c = s.replace(/[^a-zA-Z0-9_$]/g, "_").replace(/^[0-9]/, "_$&"); return reserved.has(c) ? `${c}_` : c; };
@@ -56,6 +59,7 @@ export interface OpInfo {
   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)
+  fields?: FieldDescriptor[]; // C041 per-input field origin (input/sourced/computed + wireable source edge)
   bid?: string; qid?: string; bodyTs?: string; queryTs?: string; // assigned after collision resolution
 }
 
@@ -80,11 +84,14 @@ function walkOps(doc: OpenAPIv4Document): OpInfo[] {
       else { const segs = uri.split("/").filter((x) => x && !x.startsWith("{")); ns = segs.slice(0, -1).map(camel); member = camel(segs[segs.length - 1] ?? name); }
       const ps = req.parameterSchema ?? {};
       const acc = req["x-suluk-access"];
+      const bodyRaw = req.contentSchema ?? ps.body;
+      const fields = describeInputs(bodyRaw as Record<string, unknown> | undefined);
       ops.push({
         name, ns, member, method: req.method.toLowerCase(), uri, pathParams: pathVars(uri),
-        queryRaw: ps.query, bodyRaw: req.contentSchema ?? ps.body, respType: respType(doc, req),
+        queryRaw: ps.query, bodyRaw, respType: respType(doc, req),
         cost: costOf(req), requires: acc?.requires ?? "anyone", scope: acc?.scope, summary: req.summary,
         store: req["x-suluk-store"],
+        fields: fields.length ? fields : undefined,
       });
     }
   }
@@ -128,7 +135,8 @@ function emitMethod(op: OpInfo): string {
   const opts = [`method: "${op.method.toUpperCase()}"`];
   if (op.bid) opts.push(`body: _v ? parse(${op.bid}, body) : body`);
   if (op.qid) opts.push(`query: _v && query ? parse(${op.qid}, query) : query`);
-  const meta = `{ cost: ${op.cost ?? "null"}, requires: ${JSON.stringify(op.requires)}${op.scope ? `, scope: ${JSON.stringify(op.scope)}` : ""}${op.bid ? `, input: ${op.bid}` : ""} }`;
+  const fieldsMeta = op.fields?.length ? `, fields: ${JSON.stringify(op.fields)}` : "";
+  const meta = `{ cost: ${op.cost ?? "null"}, requires: ${JSON.stringify(op.requires)}${op.scope ? `, scope: ${JSON.stringify(op.scope)}` : ""}${op.bid ? `, input: ${op.bid}` : ""}${fieldsMeta} }`;
   const doc = op.summary ? `      /** ${op.summary.replace(/\*\//g, "*\\/")} — ${op.requires}${op.cost != null ? ` · ⛁ ${op.cost}µ$` : ""} */\n` : "";
   return `${doc}      ${ident(op.member)}: Object.assign(\n        (${args.join(", ")}) => api<${op.respType}>(${url}, { ${opts.join(", ")} }),\n        ${meta},\n      )`;
 }
@@ -177,6 +185,7 @@ export function generateSdk(doc: OpenAPIv4Document, opts: SdkOptions = {}): stri
       inputDecls.push(`const ${op.qid} = std<${op.queryTs}>(schemas.${ident(base + "_q")});`);
     }
   }
+  // $manifest stays the LEAN facet index (cost/requires/scope); the full per-input origin lives on each method's `.fields`.
   const manifest = Object.fromEntries(ops.map((o) => [[...o.ns, o.member].join("."), { cost: o.cost, requires: o.requires, ...(o.scope ? { scope: o.scope } : {}) }]));
   const title = doc.info?.title ?? "API";
   const version = doc.openapi ?? "4.0.0-candidate";
@@ -192,7 +201,8 @@ export function generateSdk(doc: OpenAPIv4Document, opts: SdkOptions = {}): stri
  * single validator's source — so what runs is exactly what the contract stores (lossless). Each input is a STANDARD
  * SCHEMA (\`.input\`), so it drops into react-hook-form / TanStack Form / tRPC unchanged. Auth is wired via an
  * interceptor; every method carries the v4 facets as typed metadata — \`.cost\` (µ$), \`.requires\` (who can call it),
- * \`.input\` (the Standard Schema). Those are HINTS + a client-side guard, not enforcement — the server is the
+ * \`.input\` (the Standard Schema), and \`.fields\` (per-input origin: input/sourced/computed + wireable source edges).
+ * Those are HINTS + a client-side guard, not enforcement — the server is the
  * security boundary.${collisions.length ? `\n * Namespaced ${collisions.length} method collision(s) (a v4 multi-request-per-method capability): ${collisions.join("; ")}.` : ""}
  *
  *   import { createClient } from "./suluk-sdk";

package/test/origin-metadata.test.ts

@@ -0,0 +1,71 @@
+import { test, expect, describe } from "bun:test";
+import { generateSdk, resolveOps } from "../src/index";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+/**
+ * C041 — the SDK generator surfaces field-origin as typed metadata (`.fields`) so a caller knows which inputs to faker
+ * (`input`), which to CHAIN from a prior call (`sourced`, with a wireable `{op, select}` edge), and which are server-set
+ * (`computed`). Read from `@suluk/examples` (the shared leaf), not re-derived. The marker rides the request body schema.
+ */
+const doc = {
+  openapi: "4.0.0-candidate",
+  info: { title: "Billing API" },
+  paths: {
+    "billing/charge": {
+      requests: {
+        charge: {
+          method: "post",
+          contentSchema: {
+            type: "object",
+            required: ["amountCents", "subscriptionId"],
+            properties: {
+              amountCents: { type: "integer", minimum: 100, "x-suluk-origin": "input" },
+              subscriptionId: { type: "string", "x-suluk-origin": "sourced", "x-suluk-from": { op: "createSubscription", select: "id" } },
+              total: { type: "number", "x-suluk-origin": "computed", "x-suluk-from": "amountCents + fees" },
+            },
+          },
+          responses: { ok: { status: 200 } },
+          "x-suluk-access": { requires: "authenticated" },
+        },
+      },
+    },
+  },
+} as unknown as OpenAPIv4Document;
+
+describe("@suluk/sdk surfaces C041 field origin as method metadata", () => {
+  const src = generateSdk(doc, { baseURL: "https://api.example.com" });
+
+  test("the op carries a `fields:` metadata block", () => {
+    expect(src).toContain("fields:");
+  });
+
+  test("the sourced field is surfaced as a wireable edge (op + select), not a free input", () => {
+    expect(src).toContain('"origin":"sourced"');
+    expect(src).toContain('"op":"createSubscription"');
+    expect(src).toContain('"select":"id"');
+  });
+
+  test("the input field is marked fakerable; the computed field is marked not-fakerable", () => {
+    expect(src).toMatch(/"name":"amountCents"[^}]*"origin":"input"[^}]*"fakerable":true/);
+    expect(src).toMatch(/"name":"total"[^}]*"origin":"computed"[^}]*"fakerable":false/);
+  });
+
+  test("resolveOps populates op.fields from the request body (the SDK reads, never re-derives)", () => {
+    const { ops } = resolveOps(doc);
+    const charge = ops.find((o) => o.name === "charge")!;
+    expect(charge.fields?.map((f) => [f.name, f.origin])).toEqual([
+      ["amountCents", "input"],
+      ["subscriptionId", "sourced"],
+      ["total", "computed"],
+    ]);
+    expect(charge.fields?.find((f) => f.name === "subscriptionId")?.source).toEqual({ op: "createSubscription", select: "id" });
+  });
+
+  test("an op with no body emits no fields block (no bloat)", () => {
+    const noBody = {
+      openapi: "4.0.0-candidate", info: { title: "T" },
+      paths: { health: { requests: { health: { method: "get", responses: { ok: { status: 200 } } } } } },
+    } as unknown as OpenAPIv4Document;
+    expect(generateSdk(noBody)).not.toContain("fields:");
+  });
+});

package/test/stores.test.ts

@@ -24,7 +24,8 @@ describe("@suluk/sdk generateStores — a typed Nano Stores reactive layer from
     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("const [createFetcherStore, , ctx] = nanoquery({ cache })"); // bounded cache (no unbounded growth)
+    expect(stores).toContain("if (!cache.has(k) && cache.size >= 500)");
     expect(stores).toContain("Requires: `npm i @nanostores/query nanostores hookable`");
   });