@batype/chainspec 1.0.0 → 2.1.0

package/README.md

@@ -15,10 +15,34 @@ React + Vite本地生成器，普通Node/browser SDK与React/SWR入口分开。*
 
 ## 一次完整流程
 
-导入或粘贴JSON → 配置命名空间/分组/服务地址 → 生成 → 搜索接口并预览调用、类型与诊断 → 下载完整SDK ZIP。输入与配置改动后，旧结果暂停复制/下载。输入面板可以折叠。支持亮色、暗色、系统主题和手机布局。
+导入文件、粘贴JSON或从URL获取 → 编辑可复用的JSON配置 → 生成 → 搜索接口并预览调用、类型与诊断 → 下载完整SDK ZIP。输入与配置改动后，旧结果暂停复制/下载。输入面板可以折叠。支持亮色、暗色、系统主题和手机布局。
 
 支持Swagger2.0、OpenAPI3.0/3.1 JSON的常见子集，本地引用、递归模型、枚举、组合类型、参数与JSON/平面表单。没有模型的响应使用unknown并提示；不是完整的OpenAPI或JSON Schema实现。远程引用、YAML和Swagger UI HTML需先转换。
 
+## 2.0 调用约定
+
+| 文档声明 | request / useRequest 参数 |
+|---|---|
+| 无请求体 | `(params, options)` |
+| 有请求体 | `(params, body, options)` |
+
+params包含`path/query/cookies`；`headers`统一放在options（标准HeadersInit），与signal、拦截器同级。是否有body取决于OpenAPI声明，而不是只看HTTP方法。没有path/query时用`{}`占位；可选body暂不传时，用`undefined`保留第二个位置。
+
+```ts
+// GET：params + options
+API.main.users.getUser.request({path:{id:'42'}},{headers:{'X-Client':'web'}});
+// POST：params + body + options
+API.main.users.createUser.request({}, {name:'Ada',email:'ada@example.com'}, {headers:{'X-Client':'web'}});
+// React 写hook：绑定body后，在事件里trigger()；也可trigger(newBody)覆盖。
+const bound=API.main.users.createUser.useRequest({}, {name:'Ada',email:'ada@example.com'}, {headers:{'X-Client':'web'}});
+// 或者暂不绑定body，在事件里deferred.trigger(body)。
+const deferred=API.main.users.createUser.useRequest({}, undefined, {headers:{'X-Client':'web'}});
+```
+
+GET/HEAD hook options中的enabled、swr与headers同级；不再使用v1的`options.request.headers`。写hook不自动发送请求，必填body未绑定时，trigger也必须提供body。无body的写操作使用`useRequest(params, options)`及`trigger()`。
+
+这是对v1生成SDK的破坏性变更。迁移步骤见[docs/migration-v2.md](docs/migration-v2.md)。
+
 ## 使用下载的SDK
 
 将sdk文件夹放进TypeScript工程。普通入口不依赖React或SWR：
@@ -49,8 +73,8 @@ function UserView(){
   return <span>{data?.name}</span>;
 }
 function Invite(){
-  const {trigger,isMutating}=API.main.users.createUser.useRequest();
-  return <button disabled={isMutating} onClick={()=>trigger({body:{name:'Ada',email:'ada@example.com'}})}>邀请</button>;
+  const {trigger,isMutating}=API.main.users.createUser.useRequest({}, undefined, {headers:{'X-Client':'web'}});
+  return <button disabled={isMutating} onClick={()=>trigger({name:'Ada',email:'ada@example.com'})}>邀请</button>;
 }
 ```
 
@@ -87,7 +111,7 @@ npm run dev
 # http://127.0.0.1:4184/chainspec/
 ```
 
-CLI从本地JSON生成一个**新目录**，不会覆盖已有目录：
+CLI支持本地JSON、HTTP(S) JSON链接和配置文件。默认创建新目录；重复生成显式加`--update`，只替换未经修改、无额外文件的CLI生成目录：
 
 ```sh
 npm run build:core
@@ -95,19 +119,74 @@ node bin/chainspec.mjs --in openapi.json --out ./new-sdk --namespace main --stri
 # --group-by tag / --base-url URL / --no-hooks
 ```
 
+### 一份 JSON 配置，网页与代码库共用
+
+网页的配置区直接编辑JSON，支持导入/导出，完整SDK ZIP也包含`chainspec.config.json`。配置格式版本`version: 1`与生成器npm版本独立。
+
+```json
+{
+  "version": 1,
+  "input": "https://example.com/api-json",
+  "output": "./src/api",
+  "namespace": "main",
+  "groupBy": "tag",
+  "hooks": true,
+  "controllerNames": {
+    "短信管理": "sms"
+  }
+}
+```
+
+```sh
+npm install -D @batype/chainspec@^2.1.0
+npx chainspec --config chainspec.config.json
+# 接口更新后重新生成：
+npx chainspec --config chainspec.config.json --update
+# 也可直接从链接生成：
+npx chainspec --in https://example.com/api-json --out ./new-sdk
+```
+
+加入你项目的package.json：`"sdk:generate": "chainspec --config chainspec.config.json --update"`，以后执行`npm run sdk:generate`即可。
+
+`input`也可以是`./openapi.json`，在代码库保留对应文件即可。配置文件中的本地input/output路径相对于配置文件；显式CLI参数覆盖JSON，并相对于当前工作目录。还可配置`stripPrefix`、`baseUrl`。未知键及错误类型直接报错，配置文件不执行JavaScript。网页只读取当前导入的JSON，不根据本地路径自动读磁盘；配置中的URL需要点击“获取JSON”。输出目录只用于CLI。
+
+首个Tag保留为分组依据，中文标签仍保留在说明和搜索中。调用链只生成ASCII标识符：显式`controllerNames`优先，未映射的非ASCII分组从路径推导并提示；同一Tag保持同一分组，重名使用稳定后缀。建议为中文Tag显式映射并提交配置，让名字在路径变化后仍保持稳定。2.0已有中文调用名的SDK需重新生成并修改调用；原有英文别名与v2入参约定保持不变。
+
+`--update`通过CLI生成的文件清单和SHA256检查所有生成文件；手改文件、额外文件、符号链接、未由CLI管理的旧目录会拒绝更新。自定义请求与业务代码放在SDK目录外。没有`--update`仍不会覆盖已有目录。
+
+`path`与`query`可以同时存在。例如`/users/{id}/orders?page=1`：
+
+```ts
+API.main.users.listOrders.request({
+  path: { id: '42' },
+  query: { page: 1 }
+}, { headers: { 'X-Client': 'web' } });
+// 如果文档还声明body：request({path, query}, body, options)。
+// useRequest使用同样的位置；具体字段由文档推导。
+```
+
 Node生成器API：
 
 ```ts
-import {generateSDK} from '@batype/chainspec';
+import {generateSDK, parseConfig, fetchDocument} from '@batype/chainspec';
 const project=generateSDK(jsonText,{namespace:'main',groupBy:'path',hooks:true});
 // project.files: 文件名→内容；operations与diagnostics供自定义工具展示
+// const config = parseConfig(configJSON);
+// const remote = generateSDK(await fetchDocument(config.input), config);
+```
+
+已正式发布到[npm：@batype/chainspec](https://www.npmjs.com/package/@batype/chainspec)，也可下载[GitHub Release tarball](https://github.com/batype/chainspec/releases)。
+
+```sh
+npm install -D @batype/chainspec
+npx --yes --package=@batype/chainspec chainspec --in openapi.json --out ./new-sdk --namespace main
 ```
 
-npm正式可用状态以官方注册表为准；未发布时可使用源码或[GitHub Release tarball](https://github.com/batype/chainspec/releases)。生成器npm入口不需要React、SWR或ZIP依赖。生成SDK自身的React入口才需要SWR。
+生成器npm入口不需要React、SWR或ZIP依赖。生成SDK自身的React入口才需要SWR。
 
 ## 数据与安全边界
 
-生产CSP `connect-src 'none'`；Worker只解析本地文档。仅主题持久化，无云历史或遥测。输入最大8MiB、5000操作/模型。清空后移除当前输入和结果。不要未经检查就公开包含业务模型、地址和枚举的生成SDK。仓库、截图和测试使用合成API；用户提供的文档不进入公开源码。
+只有点击获取链接或执行CLI时才GET指定的JSON；浏览器不携带Cookie/认证、不经过代理，目标站需允许CORS，HTTPS页面不能获取HTTP资源。生产CSP仅为URL导入允许HTTP(S)连接；Worker仍只解析文档，不获取外部引用。URL导入有20秒超时及8MiB流式限制，可取消。仅主题持久化，无云历史或遥测。输入最大8MiB、5000操作/模型。清空后移除当前输入和结果。不要未经检查就公开包含业务模型、地址和枚举的生成SDK。仓库、截图和测试使用合成API；用户提供的文档不进入公开源码。
 
 类型不验证服务端数据；不猜鉴权凭据；不保证复杂序列化和所有Schema约束。int64依然是JS number，需要精度时由服务器返回string。参阅[限制](docs/limits.md)。
 

package/bin/chainspec.mjs

@@ -1,81 +1,95 @@
 #!/usr/bin/env node
-import { readFile, mkdir, writeFile, lstat, rm } from "node:fs/promises";
-import { resolve } from "node:path";
-import { generateSDK, MAX_BYTES, VERSION } from "../lib/core/index.js";
-const args = process.argv.slice(2),
-  opts = {};
-let inputPath, output;
+import { readFile, mkdir, writeFile, lstat, rm, readdir, rename } from "node:fs/promises";
+import { resolve, dirname, basename, join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { generateSDK, parseConfig, fetchDocument, MAX_BYTES, VERSION } from "../lib/core/index.js";
+const args = process.argv.slice(2), opts = {};
+const marker = ".chainspec-generated.json";
+const digest = text => createHash("sha256").update(text).digest("hex");
+let inputPath, output, configPath, update = false;
+async function localJSON(path) {
+  const stat = await lstat(path);
+  if (!stat.isFile() || stat.size > MAX_BYTES)
+    throw Error("Input must be a regular JSON file of at most 8 MiB");
+  return new TextDecoder("utf-8", { fatal: true }).decode(await readFile(path));
+}
+async function exists(path) {
+  try { return await lstat(path); }
+  catch (e) { if (e.code === "ENOENT") return null; throw e; }
+}
 try {
   if (args.includes("--help") || !args.length) {
-    console.log(
-      "chainspec --in openapi.json --out ./new-sdk [--namespace main] [--strip-prefix /v1/api] [--group-by path|tag] [--base-url URL] [--no-hooks]\nReads local JSON only; creates a new output directory, never overwrites it.",
-    );
-    process.exit(0);
-  }
-  if (args.includes("--version")) {
-    console.log(VERSION);
+    console.log("chainspec --config chainspec.config.json [--update]\nchainspec --in openapi.json|https://example.com/api-json --out ./new-sdk [--namespace main] [--strip-prefix /v1/api] [--group-by path|tag] [--base-url URL] [--no-hooks]\nPaths in JSON resolve relative to the config file; explicit CLI flags override JSON.\nCreates a new directory. --update replaces only an unchanged CLI-generated directory.");
     process.exit(0);
   }
+  if (args.includes("--version")) { console.log(VERSION); process.exit(0); }
   for (let i = 0; i < args.length; i++) {
     const flag = args[i];
-    if (flag === "--no-hooks") {
-      opts.hooks = false;
-      continue;
-    }
-    if (
-      ![
-        "--in",
-        "--out",
-        "--namespace",
-        "--strip-prefix",
-        "--group-by",
-        "--base-url",
-      ].includes(flag)
-    )
+    if (flag === "--no-hooks") { opts.hooks = false; continue; }
+    if (flag === "--update") { update = true; continue; }
+    if (!["--config", "--in", "--out", "--namespace", "--strip-prefix", "--group-by", "--base-url"].includes(flag))
       throw Error("Unknown option; use --help");
     const val = args[++i];
     if (!val || val.startsWith("--")) throw Error("Missing option value");
-    if (flag === "--in") inputPath = val;
+    if (flag === "--config") configPath = resolve(val);
+    else if (flag === "--in") inputPath = val;
     else if (flag === "--out") output = val;
-    else
-      opts[
-        {
-          "--namespace": "namespace",
-          "--strip-prefix": "stripPrefix",
-          "--group-by": "groupBy",
-          "--base-url": "baseUrl",
-        }[flag]
-      ] = val;
+    else opts[{"--namespace":"namespace", "--strip-prefix":"stripPrefix", "--group-by":"groupBy", "--base-url":"baseUrl"}[flag]] = val;
   }
-  if (!inputPath || !output) throw Error("--in and --out are required");
-  if (opts.groupBy && !["path", "tag"].includes(opts.groupBy))
-    throw Error("--group-by must be path or tag");
-  const stat = await lstat(inputPath);
-  if (!stat.isFile() || stat.size > MAX_BYTES)
-    throw Error("Input must be a regular JSON file of at most 8 MiB");
-  const result = generateSDK(
-    new TextDecoder("utf-8", { fatal: true }).decode(await readFile(inputPath)),
-    opts,
-  );
-  const dir = resolve(output);
-  await mkdir(dir, { mode: 0o700 });
+  const config = configPath ? parseConfig(await localJSON(configPath)) : undefined;
+  const base = configPath ? dirname(configPath) : process.cwd();
+  const source = inputPath ?? config?.input;
+  const destination = output ? resolve(output) : config ? resolve(base, config.output) : undefined;
+  if (!source || !destination) throw Error("--in and --out, or --config, are required");
+  const settings = { ...config, ...opts };
+  if (settings.groupBy && !["path", "tag"].includes(settings.groupBy)) throw Error("--group-by must be path or tag");
+  const text = /^[a-z][a-z\d+.-]*:/i.test(source)
+    ? await fetchDocument(source)
+    : await localJSON(resolve(inputPath ? process.cwd() : base, source));
+  const result = generateSDK(text, settings);
+  const dir = destination;
+  const old = await exists(dir);
+  if (old) {
+    if (!update) throw Object.assign(Error("Output already exists; choose a new directory or use --update."), { code: "EEXIST" });
+    if (!old.isDirectory() || old.isSymbolicLink()) throw Error("Refusing to update a symlink or non-directory");
+    const ownerStat = await exists(join(dir, marker));
+    if (!ownerStat?.isFile() || ownerStat.isSymbolicLink()) throw Error("Output is not managed by this CLI; choose a new directory");
+    const owner = JSON.parse(await localJSON(join(dir, marker)));
+    if (owner.generator !== "ChainSpec" || !owner.files || typeof owner.files !== "object" || Array.isArray(owner.files))
+      throw Error("Invalid generated-directory marker");
+    const names = await readdir(dir);
+    if (names.some(name => name !== marker && !Object.hasOwn(owner.files, name)))
+      throw Error("Output contains extra files; move custom code outside the generated directory");
+    for (const [name, hash] of Object.entries(owner.files)) {
+      if (name !== basename(name) || name === marker || !names.includes(name)) throw Error("Generated files changed; choose a new directory");
+      const stat = await lstat(join(dir, name));
+      if (!stat.isFile() || stat.isSymbolicLink() || digest(await readFile(join(dir, name))) !== hash)
+        throw Error("Generated files changed; choose a new directory to preserve edits");
+    }
+  }
+  await mkdir(dirname(dir), { recursive: true });
+  const stage = join(dirname(dir), `.${basename(dir)}.chainspec-${randomUUID()}`);
+  await mkdir(stage, { mode: 0o700 });
   try {
+    const files = Object.fromEntries(Object.entries(result.files).map(([name, text]) => [name, digest(text)]));
     for (const [file, text] of Object.entries(result.files))
-      await writeFile(resolve(dir, file), text, { flag: "wx", mode: 0o600 });
-  } catch (e) {
-    await rm(dir, { recursive: true, force: true });
-    throw e;
-  }
-  console.log(
-    `Generated ${result.operations.length} operations, ${result.schemaCount} schemas, ${result.diagnostics.length} diagnostics.\nOutput: ${dir}`,
-  );
+      await writeFile(join(stage, file), text, { flag: "wx", mode: 0o600 });
+    await writeFile(join(stage, marker), JSON.stringify({ generator: "ChainSpec", version: VERSION, files }, null, 2), { flag: "wx", mode: 0o600 });
+    if (old) {
+      const backup = `${stage}.previous`;
+      await rename(dir, backup);
+      try { await rename(stage, dir); }
+      catch (e) { await rename(backup, dir); throw e; }
+      await rm(backup, { recursive: true });
+    } else {
+      // Reserve destination first so a concurrently created directory is never replaced.
+      await mkdir(dir, { mode: 0o700 });
+      try { for (const name of await readdir(stage)) await rename(join(stage, name), join(dir, name)); }
+      catch (e) { await rm(dir, { recursive: true, force: true }); throw e; }
+    }
+  } finally { await rm(stage, { recursive: true, force: true }); }
+  console.log(`Generated ${result.operations.length} operations, ${result.schemaCount} schemas, ${result.diagnostics.length} diagnostics.\nOutput: ${dir}`);
 } catch (error) {
-  console.error(
-    error?.code === "EEXIST"
-      ? "Output already exists; choose a new directory."
-      : error instanceof Error
-        ? error.message
-        : "Generation failed",
-  );
+  console.error(error?.code === "EEXIST" ? "Output already exists; choose a new directory or use --update." : error instanceof Error ? error.message : "Generation failed");
   process.exitCode = 1;
 }

package/lib/core/config.d.ts

@@ -0,0 +1,10 @@
+import type { GeneratorOptions } from "./model.js";
+/** Shared by the web editor and CLI. Paths resolve relative to the config file. */
+export type ChainSpecConfig = GeneratorOptions & {
+    version: 1;
+    input: string;
+    output: string;
+};
+export declare const DEFAULT_CONFIG: ChainSpecConfig;
+export declare function parseConfig(input: string | unknown): ChainSpecConfig;
+export declare function documentURL(input: string): URL;

package/lib/core/config.js

@@ -0,0 +1,67 @@
+export const DEFAULT_CONFIG = {
+    version: 1,
+    input: "./openapi.json",
+    output: "./src/api",
+    namespace: "main",
+    groupBy: "path",
+    hooks: true,
+    controllerNames: {},
+};
+const keys = new Set([
+    "version", "input", "output", "namespace", "groupBy", "stripPrefix",
+    "controllerNames", "baseUrl", "hooks",
+]);
+export function parseConfig(input) {
+    let value = input;
+    if (typeof input === "string") {
+        try {
+            value = JSON.parse(input);
+        }
+        catch {
+            throw new Error("配置必须是有效 JSON");
+        }
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("配置必须是 JSON 对象");
+    for (const key of Object.keys(value))
+        if (!keys.has(key))
+            throw new Error(`未知配置项：${key}`);
+    if (value.version !== 1)
+        throw new Error("配置 version 必须为 1");
+    for (const key of ["input", "output"])
+        if (typeof value[key] !== "string" || !value[key].trim())
+            throw new Error(`配置 ${key} 必须为非空字符串`);
+    for (const key of ["namespace", "stripPrefix", "baseUrl"])
+        if (value[key] !== undefined && typeof value[key] !== "string")
+            throw new Error(`配置 ${key} 必须为字符串`);
+    if (value.namespace !== undefined && !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value.namespace))
+        throw new Error("命名空间需为英文标识符");
+    if (value.groupBy !== undefined && !["path", "tag"].includes(value.groupBy))
+        throw new Error("groupBy 必须为 path 或 tag");
+    if (value.hooks !== undefined && typeof value.hooks !== "boolean")
+        throw new Error("hooks 必须为布尔值");
+    if (value.stripPrefix && !value.stripPrefix.startsWith("/"))
+        throw new Error("stripPrefix 必须以 / 开头");
+    if (value.controllerNames !== undefined) {
+        if (!value.controllerNames || typeof value.controllerNames !== "object" || Array.isArray(value.controllerNames))
+            throw new Error("controllerNames 必须为原分组到英文名称的对象");
+        for (const alias of Object.values(value.controllerNames))
+            if (typeof alias !== "string" || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(alias))
+                throw new Error("controllerNames 的值必须为英文标识符，例如 sms");
+    }
+    if (/^[a-z][a-z\d+.-]*:/i.test(value.input))
+        documentURL(value.input);
+    return { ...value, controllerNames: { ...value.controllerNames } };
+}
+export function documentURL(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new Error("请输入完整的 HTTP(S) JSON 地址");
+    }
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.hash)
+        throw new Error("文档地址仅支持 HTTP(S)，不能包含用户名、密码或片段");
+    return url;
+}

package/lib/core/index.d.ts

@@ -1,5 +1,8 @@
 import type { GeneratorOptions, GeneratedProject } from "./model.js";
 export type { GeneratorOptions, GeneratedProject, Diagnostic, Operation, } from "./model.js";
 export { MAX_BYTES, MAX_OPERATIONS } from "./model.js";
-export declare const VERSION = "1.0.0";
+export { parseConfig, DEFAULT_CONFIG } from "./config.js";
+export type { ChainSpecConfig } from "./config.js";
+export { fetchDocument } from "./source.js";
+export declare const VERSION = "2.1.0";
 export declare function generateSDK(input: string | Record<string, any>, options?: GeneratorOptions): GeneratedProject;

package/lib/core/index.js

@@ -2,7 +2,9 @@ import { parseDocument, normalize } from "./parse.js";
 import { createSchemaWriter } from "./schema.js";
 import { RUNTIME_SOURCE, HOOKS_SOURCE, RUNTIME_LICENSE } from "./templates.js";
 export { MAX_BYTES, MAX_OPERATIONS } from "./model.js";
-export const VERSION = "1.0.0";
+export { parseConfig, DEFAULT_CONFIG } from "./config.js";
+export { fetchDocument } from "./source.js";
+export const VERSION = "2.1.0";
 const q = JSON.stringify;
 const banner = "// Generated by ChainSpec. Do not edit; regenerate from your OpenAPI document.\n";
 export function generateSDK(input, options = {}) {
@@ -27,16 +29,19 @@ export function generateSDK(input, options = {}) {
     types += "export interface Operations {\n";
     for (const op of operations) {
         const fields = [];
-        for (const loc of ["path", "query", "header", "cookie"]) {
+        for (const loc of ["path", "query", "cookie"]) {
             const ps = op.parameters.filter((p) => p.in === loc);
             if (!ps.length)
                 continue;
-            const field = loc === "header" ? "headers" : loc === "cookie" ? "cookies" : loc;
+            const field = loc === "cookie" ? "cookies" : loc;
             fields.push(`${field}${ps.some((p) => p.required) ? "" : "?"}: { ${ps.map((p) => `${q(p.name)}${p.required ? "" : "?"}: ${writer.type(p.schema, "input", op.id + "." + loc + "." + p.name)};`).join(" ")} };`);
         }
-        if (op.body)
-            fields.push(`body${op.body.required ? "" : "?"}: ${writer.type(op.body.schema, "input", op.id + ".body")};`);
-        types += `  ${q(op.id)}: { input: { ${fields.join(" ")} }; output: ${writer.type(op.response, "output", op.id + ".response")}; };\n`;
+        const body = op.body
+            ? writer.type(op.body.schema, "input", op.id + ".body")
+            : "never";
+        const headerParams = op.parameters.filter((p) => p.in === "header");
+        const headers = `{ ${headerParams.map((p) => `${q(p.name)}${p.required ? "" : "?"}: ${writer.type(p.schema, "input", op.id + ".header." + p.name)};`).join(" ")} }`;
+        types += `  ${q(op.id)}: { params: ${fields.length ? `{ ${fields.join(" ")} }` : "Record<string, never>"}; body: ${body}; headers: ${headers}; output: ${writer.type(op.response, "output", op.id + ".response")}; };\n`;
     }
     types += "}\n";
     const groups = new Map();
@@ -61,7 +66,7 @@ export function generateSDK(input, options = {}) {
                         ? "QueryEndpoint"
                         : "MutationEndpoint"
                     : "Endpoint";
-                text += `${op.deprecated ? "/** @deprecated */\n" : ""}    ${q(op.name)}: ${ep}<${index(op.id, "input")},${index(op.id, "output")}>;\n`;
+                text += `${op.deprecated ? "/** @deprecated */\n" : ""}    ${q(op.name)}: ${ep}<${index(op.id, "params")},${index(op.id, "body")},${index(op.id, "output")},${Boolean(op.body)},${op.body?.required ?? false}>;\n`;
             }
             text += "  };\n";
         }
@@ -77,11 +82,12 @@ export function generateSDK(input, options = {}) {
                     controller: op.controller,
                     name: op.name,
                     parameters: op.parameters.map(({ schema, ...p }) => p),
+                    hasBody: Boolean(op.body),
                     bodyRequired: op.body?.required,
                     mediaType: op.body?.mediaType,
                     responseType: op.responseType,
                 };
-                let endpoint = `client.endpoint<${index(op.id, "input")},${index(op.id, "output")}>(${q(definition)})`;
+                let endpoint = `client.endpoint<${index(op.id, "params")},${index(op.id, "body")},${index(op.id, "output")},${Boolean(op.body)},${op.body?.required ?? false}>(${q(definition)})`;
                 if (react)
                     endpoint = `${op.method === "GET" || op.method === "HEAD" ? "withQuery" : "withMutation"}(${endpoint})`;
                 text += `${q(op.name)}: ${endpoint},\n`;
@@ -120,7 +126,7 @@ export function generateSDK(input, options = {}) {
     const first = operations.find((o) => o.method === "GET") ?? operations[0];
     const access = `API.${namespace}[${q(first.controller)}][${q(first.name)}]`;
     files["README.md"] =
-        `# Generated SDK\n\nGenerated locally with ChainSpec ${VERSION}. Copy these files into your TypeScript project. No runtime code evaluation or request is performed by the generator.\n\n## Setup\n\nNode22+ or a browser with Fetch, Headers, FormData, Blob. TypeScript moduleResolution Bundler or NodeNext; .js imports resolve to the corresponding .ts sources.\n\nPlain SDK: import {createAPI} from './index.js'. No React/SWR dependency.\n\n${options.hooks === false ? "" : "React SDK: npm install swr@^2.5.1 react@^19.3.1, then import {createReactAPI} from './react.js'. Use the returned API as a module-level singleton (or memoize it per Provider/SSR request). Do not create clients on every render.\n\n"}## Calls\n\n\`\`\`ts\nimport {createAPI} from './index.js';\nconst API=createAPI({baseUrl:${q(baseUrl)},cacheScope:()=> 'tenant:user:auth-revision'});\n// Inspect generated Operations input before calling:\n// ${access}.request({query:{...},path:{...},body:{...}});\n\`\`\`\n\n.request() returns the documented response body. Input sections are path/query/headers/cookies/body. Required arguments are required in TypeScript and checked for presence by the default runtime. Schema validation is NOT performed. Missing response schemas are unknown. JS numbers can lose int64 precision: ask your server for strings if required.\n\nGET/HEAD .useRequest(input, {enabled,request,swr}) reads with SWR; null input or enabled:false pauses it. Other methods .useRequest({request,swr}) (also .useMutation) return trigger(input), never send automatically. Hooks must be called unconditionally at React component/custom-hook top level. HEAD returns no body in Fetch.\n\nCache keys isolate client instances, base URL, operation, inputs, request headers and cacheScope. Change cacheScope after switching users/tenants or changing authorization within one client. Do not put tokens in cacheScope. Logout should also clear your SWR Provider cache. Request interceptors do not automatically change cache keys.\n\n## Extension points\n\n- request: async context => ({data,status,headers:new Headers()}) replaces the entire Fetch transport. context includes URL, method, headers, structured body, mediaType, operation and AbortSignal. Custom adapters must preserve the declared response shape; returning an Axios response unchanged is NOT compatible (normalize response.headers).\n- beforeRequest: async context => context (or void); global handlers run before per-call handlers. Add auth headers, tracing, or cancellation here.\n- afterResponse: async (response,context) => response (or void), for successful responses only. Unwrapping changes the schema contract; do not unwrap unless the server schema already describes the unwrapped body.\n- onError: async (error,context) => void; errors are rethrown. Non-2xx status becomes ApiError with status/data/headers. Network and AbortError are preserved. No automatic retry in .request(). SWR has its own configurable retries.\n\nSupported query serialization: form (arrays and flat objects), spaceDelimited, pipeDelimited, flat deepObject. Path/header simple serialization; header objects and nested query objects need a custom serializer. Cookie parameters require a custom Node request adapter (Fetch in browsers cannot set Cookie headers). JSON, flat multipart and URL-encoded bodies supported; nested forms need a custom adapter. JSON-schema constraints, auth schemes, oneOf exclusivity, server variables, parameter serialization and streaming may need application validation.\n\nThe generator supports local refs, not remote refs. Review manifest.json diagnostics, media choices and operation names. Do not add this SDK or its spec to a public repository without checking that disclosure is intended.\n`;
+        `# Generated SDK\n\nGenerated locally with ChainSpec ${VERSION}. Copy these files into your TypeScript project. No runtime code evaluation or request is performed by the generator.\n\n## Setup\n\nNode22+ or a browser with Fetch, Headers, FormData, Blob. TypeScript moduleResolution Bundler or NodeNext; .js imports resolve to the corresponding .ts sources.\n\nPlain SDK: import {createAPI} from './index.js'. No React/SWR dependency.\n\n${options.hooks === false ? "" : "React SDK: npm install swr@^2.5.1 react@^19.3.1, then import {createReactAPI} from './react.js'. Use the returned API as a module-level singleton (or memoize it per Provider/SSR request). Do not create clients on every render.\n\n"}## Calls\n\n\`\`\`ts\nimport {createAPI} from './index.js';\nconst API=createAPI({baseUrl:${q(baseUrl)},cacheScope:()=> 'tenant:user:auth-revision'});\n// Inspect generated Operations params/body before calling:\n// ${access}.request(params${first.body ? ", body" : ""}, options);\n\`\`\`\n\n.request() returns the documented response body. The first params object contains path/query/cookies. With a documented request body: request(params, body, options). Without one: request(params?, options). Headers are options.headers (standard HeadersInit) and may also be set globally or by beforeRequest. Empty params are {} when a body is present. Operations exposes params/body/headers/output types. Required arguments are required in TypeScript and checked for presence by the default runtime. Schema validation is NOT performed. Missing response schemas are unknown. JS numbers can lose int64 precision: ask your server for strings if required.\n\nGET/HEAD .useRequest(params, {enabled,headers,signal,swr}) reads with SWR; null params or enabled:false pauses it. If a query operation documents a body, use the same three positions as request. Other methods .useRequest(params, body, {headers,signal,swr}) (also .useMutation) bind params and an optional body, never send automatically. trigger() uses the bound body; trigger(body) supplies or overrides it. If a required body was not bound, TypeScript requires trigger(body). For operations without a body use .useRequest(params, options) then trigger(). Trigger options, such as throwOnError, are its second argument. Hook options are flat: headers/signal/interceptors are alongside swr, not under request. Hooks must be called unconditionally at React component/custom-hook top level. HEAD returns no body in Fetch.\n\nCache keys isolate client instances, base URL, operation, inputs, request headers and cacheScope. Change cacheScope after switching users/tenants or changing authorization within one client. Do not put tokens in cacheScope. Logout should also clear your SWR Provider cache. Request interceptors do not automatically change cache keys.\n\n## Extension points\n\n- request: async context => ({data,status,headers:new Headers()}) replaces the entire Fetch transport. context includes URL, method, headers, structured body, mediaType, operation and AbortSignal. Custom adapters must preserve the declared response shape; returning an Axios response unchanged is NOT compatible (normalize response.headers).\n- beforeRequest: async context => context (or void); global handlers run before per-call handlers. Add auth headers, tracing, or cancellation here.\n- afterResponse: async (response,context) => response (or void), for successful responses only. Unwrapping changes the schema contract; do not unwrap unless the server schema already describes the unwrapped body.\n- onError: async (error,context) => void; errors are rethrown. Non-2xx status becomes ApiError with status/data/headers. Network and AbortError are preserved. No automatic retry in .request(). SWR has its own configurable retries.\n\nSupported query serialization: form (arrays and flat objects), spaceDelimited, pipeDelimited, flat deepObject. Path/header simple serialization; header objects and nested query objects need a custom serializer. Cookie parameters require a custom Node request adapter (Fetch in browsers cannot set Cookie headers). JSON, flat multipart and URL-encoded bodies supported; nested forms need a custom adapter. JSON-schema constraints, auth schemes, oneOf exclusivity, server variables, parameter serialization and streaming may need application validation.\n\nThe generator supports local refs, not remote refs. Review manifest.json diagnostics, media choices and operation names. Do not add this SDK or its spec to a public repository without checking that disclosure is intended.\n`;
     diagnostics.push({
         level: "info",
         code: "static-types",

package/lib/core/parse.js

@@ -14,12 +14,12 @@ const reserved = new Set(["__proto__", "prototype", "constructor", "then"]);
 export function nameOf(value, fallback = "endpoint") {
     const words = value
         .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
-        .split(/[^\p{ID_Continue}$]+/u)
+        .split(/[^A-Za-z0-9_$]+/)
         .filter(Boolean);
     let result = words
         .map((w, i) => i ? w[0].toUpperCase() + w.slice(1) : w[0].toLowerCase() + w.slice(1))
         .join("") || fallback;
-    if (!/^[\p{ID_Start}_$]/u.test(result))
+    if (!/^[A-Za-z_$]/.test(result))
         result = "_" + result;
     return reserved.has(result) ? result + "Api" : result;
 }
@@ -52,7 +52,7 @@ export function parseDocument(input) {
 }
 export function normalize(doc, options, diagnostics) {
     const namespace = options.namespace ?? "main";
-    if (!/^[\p{ID_Start}_$][\p{ID_Continue}$]*$/u.test(namespace) ||
+    if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(namespace) ||
         reserved.has(namespace))
         throw new Error("命名空间需是有效标识符，不能使用保留的对象属性");
     const candidates = [
@@ -71,6 +71,7 @@ export function normalize(doc, options, diagnostics) {
     const operations = [];
     const used = new Set();
     const groupSources = new Map();
+    const assignedGroups = new Map();
     for (const path of Object.keys(doc.paths).sort()) {
         if (!path.startsWith("/") || path.includes("?") || path.includes("#"))
             throw new Error("paths中的路径需以/开头且不能包含query/hash");
@@ -92,7 +93,16 @@ export function normalize(doc, options, diagnostics) {
                 "default";
             const originalGroup = op["x-sdk-controller"] ??
                 (options.groupBy === "tag" ? (tags[0] ?? pathGroup) : pathGroup);
-            let controller = nameOf(options.controllerNames?.[originalGroup] ?? originalGroup, "default");
+            const alias = options.controllerNames?.[originalGroup];
+            if (alias !== undefined && !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(alias))
+                throw new Error(`分组「${originalGroup}」的别名需为英文标识符`);
+            let controller = assignedGroups.get(originalGroup) ?? nameOf(alias ?? (/^[\x00-\x7F]+$/.test(originalGroup) ? originalGroup : pathGroup), "group_" + hash(originalGroup));
+            if (!assignedGroups.has(originalGroup) && alias === undefined && /[^\x00-\x7F]/.test(originalGroup))
+                diagnostics.push({
+                    level: "warning", code: "group-name-fallback",
+                    message: `分组「${originalGroup}」使用路径推导名称 ${controller}；可在 controllerNames 中显式映射`,
+                    location: path,
+                });
             if (groupSources.has(controller) &&
                 groupSources.get(controller) !== originalGroup) {
                 controller += "_" + hash(originalGroup);
@@ -104,8 +114,10 @@ export function normalize(doc, options, diagnostics) {
                 });
             }
             groupSources.set(controller, originalGroup);
+            assignedGroups.set(originalGroup, controller);
             const originalId = typeof op.operationId === "string" ? op.operationId : undefined;
-            let name = nameOf(originalId ?? method + " " + stripped.replace(/\{([^}]+)\}/g, "by $1"));
+            const methodSource = method + " " + stripped.replace(/\{([^}]+)\}/g, "by $1");
+            let name = nameOf(originalId && /^[\x00-\x7F]+$/.test(originalId) ? originalId : methodSource);
             if (used.has(`${controller}.${name}`)) {
                 name += "_" + method + "_" + hash(path);
                 diagnostics.push({

package/lib/core/source.d.ts

@@ -0,0 +1,2 @@
+/** Only called after an explicit URL import / CLI invocation. Never fetches refs. */
+export declare function fetchDocument(input: string, signal?: AbortSignal): Promise<string>;

package/lib/core/source.js

@@ -0,0 +1,43 @@
+import { MAX_BYTES } from "./model.js";
+import { parseDocument } from "./parse.js";
+import { documentURL } from "./config.js";
+/** Only called after an explicit URL import / CLI invocation. Never fetches refs. */
+export async function fetchDocument(input, signal) {
+    const url = documentURL(input);
+    const abort = AbortSignal.any([AbortSignal.timeout(20_000), ...(signal ? [signal] : [])]);
+    const response = await fetch(url, {
+        method: "GET", credentials: "omit", referrerPolicy: "no-referrer",
+        headers: { Accept: "application/json" }, signal: abort,
+    });
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new Error(`获取文档失败：HTTP ${response.status}`);
+    }
+    if (Number(response.headers.get("content-length")) > MAX_BYTES) {
+        await response.body?.cancel();
+        throw new Error("远程文档最大 8 MiB");
+    }
+    if (!response.body)
+        throw new Error("远程文档为空");
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    let bytes = 0, text = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytes += value.byteLength;
+            if (bytes > MAX_BYTES)
+                throw new Error("远程文档最大 8 MiB");
+            text += decoder.decode(value, { stream: true });
+        }
+        text += decoder.decode();
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+    parseDocument(text);
+    return text;
+}

package/lib/core/templates.d.ts

@@ -1,3 +1,3 @@
-export declare const RUNTIME_SOURCE = "/** ChainSpec runtime. Generated SDK types describe the spec, not runtime validation. */\nexport type Parameter = {\n  name: string;\n  in: \"path\" | \"query\" | \"header\" | \"cookie\";\n  required?: boolean;\n  style?: string;\n  explode?: boolean;\n};\nexport type Definition = {\n  id: string;\n  method: string;\n  path: string;\n  controller: string;\n  name: string;\n  parameters: Parameter[];\n  bodyRequired?: boolean;\n  mediaType?: string;\n  responseType: \"json\" | \"text\" | \"blob\" | \"void\" | \"auto\";\n};\nexport type Input = {\n  path?: Record<string, unknown>;\n  query?: Record<string, unknown>;\n  headers?: Record<string, unknown>;\n  cookies?: Record<string, unknown>;\n  body?: unknown;\n};\nexport interface RequestContext {\n  url: string;\n  method: string;\n  headers: Headers;\n  body: unknown;\n  mediaType?: string;\n  signal?: AbortSignal;\n  readonly operation: Definition;\n}\nexport interface TransportResponse {\n  data: unknown;\n  status: number;\n  headers: Headers;\n}\nexport type RequestAdapter = (\n  context: RequestContext,\n) => Promise<TransportResponse>;\nexport type BeforeRequest = (\n  context: RequestContext,\n) => void | RequestContext | Promise<void | RequestContext>;\nexport type AfterResponse = (\n  response: TransportResponse,\n  context: RequestContext,\n) => void | TransportResponse | Promise<void | TransportResponse>;\nexport type OnError = (\n  error: unknown,\n  context: RequestContext | undefined,\n) => void | Promise<void>;\nexport interface RequestOptions {\n  signal?: AbortSignal;\n  headers?: HeadersInit;\n  beforeRequest?: BeforeRequest[];\n  afterResponse?: AfterResponse[];\n  onError?: OnError[];\n}\nexport interface ClientConfig {\n  baseUrl?: string;\n  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);\n  request?: RequestAdapter;\n  beforeRequest?: BeforeRequest[];\n  afterResponse?: AfterResponse[];\n  onError?: OnError[];\n  /** Change on tenant/user/auth changes. Never put bearer tokens here. */ cacheScope?:\n    | string\n    | (() => string);\n}\nexport type RequestArgs<I> = {} extends I\n  ? [input?: I, options?: RequestOptions]\n  : [input: I, options?: RequestOptions];\nexport interface Endpoint<I, R> {\n  readonly definition: Definition;\n  request(...args: RequestArgs<I>): Promise<R>;\n  getKey(input?: I, options?: RequestOptions): readonly unknown[];\n}\nexport class ApiError extends Error {\n  constructor(\n    public status: number,\n    public data: unknown,\n    public headers: Headers,\n  ) {\n    super(`HTTP ${status}`);\n    this.name = \"ApiError\";\n  }\n}\nconst scalar = (value: unknown): string => {\n  if (value === null) return \"\";\n  if ([\"string\", \"number\", \"boolean\"].includes(typeof value))\n    return String(value);\n  throw new Error(\"Parameter must be a scalar or a declared array/object\");\n};\nconst isRecord = (v: unknown): v is Record<string, unknown> =>\n  typeof v === \"object\" && v !== null && !Array.isArray(v);\nfunction queryEntries(\n  name: string,\n  value: unknown,\n  style = \"form\",\n  explode = true,\n): [string, string][] {\n  if (value === undefined) return [];\n  if (style === \"deepObject\") {\n    if (!isRecord(value)) throw new Error(\"deepObject needs an object\");\n    return Object.entries(value)\n      .filter(([, v]) => v !== undefined)\n      .map(([k, v]) => [`${name}[${k}]`, scalar(v)]);\n  }\n  if (Array.isArray(value)) {\n    if (style === \"form\" && explode) return value.map((v) => [name, scalar(v)]);\n    const delimiter =\n      style === \"spaceDelimited\" ? \" \" : style === \"pipeDelimited\" ? \"|\" : \",\";\n    return [[name, value.map(scalar).join(delimiter)]];\n  }\n  if (isRecord(value)) {\n    const values = Object.entries(value).filter(([, v]) => v !== undefined);\n    return explode\n      ? values.map(([k, v]) => [k, scalar(v)])\n      : [[name, values.flatMap(([k, v]) => [k, scalar(v)]).join(\",\")]];\n  }\n  return [[name, scalar(value)]];\n}\nfunction pathValue(value: unknown, explode = false): string {\n  const enc = (v: unknown) => encodeURIComponent(scalar(v));\n  if (Array.isArray(value)) return value.map(enc).join(\",\");\n  if (isRecord(value))\n    return Object.entries(value)\n      .map(([k, v]) =>\n        explode ? `${enc(k)}=${enc(v)}` : `${enc(k)},${enc(v)}`,\n      )\n      .join(\",\");\n  return enc(value);\n}\nexport async function defaultRequest(\n  ctx: RequestContext,\n): Promise<TransportResponse> {\n  const headers = new Headers(ctx.headers);\n  let body: BodyInit | undefined;\n  if (ctx.body !== undefined) {\n    if (ctx.method === \"GET\" || ctx.method === \"HEAD\")\n      throw new Error(\n        \"Fetch cannot send GET/HEAD bodies; configure a request adapter\",\n      );\n    if (ctx.mediaType?.includes(\"json\")) {\n      body = JSON.stringify(ctx.body);\n      if (!headers.has(\"Content-Type\"))\n        headers.set(\"Content-Type\", ctx.mediaType);\n    } else if (ctx.mediaType?.startsWith(\"multipart/form-data\")) {\n      if (!isRecord(ctx.body))\n        throw new Error(\"Multipart body must be an object\");\n      const form = new FormData();\n      for (const [name, value] of Object.entries(ctx.body)) {\n        if (value === undefined) continue;\n        for (const v of Array.isArray(value) ? value : [value])\n          form.append(name, v instanceof Blob ? v : scalar(v));\n      }\n      body = form;\n      headers.delete(\"Content-Type\");\n    } else if (ctx.mediaType?.startsWith(\"application/x-www-form-urlencoded\")) {\n      if (!isRecord(ctx.body)) throw new Error(\"Form body must be an object\");\n      const form = new URLSearchParams();\n      for (const [name, value] of Object.entries(ctx.body))\n        for (const [k, v] of queryEntries(name, value)) form.append(k, v);\n      body = form.toString();\n      if (!headers.has(\"Content-Type\"))\n        headers.set(\"Content-Type\", ctx.mediaType);\n    } else if (\n      typeof ctx.body === \"string\" ||\n      ctx.body instanceof Blob ||\n      ctx.body instanceof ArrayBuffer ||\n      ArrayBuffer.isView(ctx.body)\n    ) {\n      body = ctx.body as BodyInit;\n      if (ctx.mediaType && !headers.has(\"Content-Type\"))\n        headers.set(\"Content-Type\", ctx.mediaType);\n    } else\n      throw new Error(\"Unsupported body format; configure a request adapter\");\n  }\n  const response = await fetch(ctx.url, {\n    method: ctx.method,\n    headers,\n    body,\n    signal: ctx.signal,\n  });\n  let data: unknown;\n  const mode = ctx.operation.responseType;\n  if (\n    response.status === 204 ||\n    response.status === 205 ||\n    ctx.method === \"HEAD\"\n  )\n    data = undefined;\n  else if (!response.ok) {\n    const text = await response.text();\n    try {\n      data = JSON.parse(text);\n    } catch {\n      data = text;\n    }\n  } else if (mode === \"void\") data = undefined;\n  else if (\n    mode === \"blob\" ||\n    (mode === \"auto\" &&\n      !response.headers.get(\"Content-Type\")?.includes(\"json\") &&\n      !response.headers.get(\"Content-Type\")?.startsWith(\"text/\"))\n  )\n    data = await response.blob();\n  else {\n    const text = await response.text();\n    data =\n      mode === \"json\" ||\n      (mode === \"auto\" &&\n        response.headers.get(\"Content-Type\")?.includes(\"json\"))\n        ? text\n          ? JSON.parse(text)\n          : undefined\n        : text;\n  }\n  return { data, status: response.status, headers: response.headers };\n}\nconst runtimeId = Math.random().toString(36).slice(2);\nlet nextClient = 0;\nexport function createClient(config: ClientConfig = {}) {\n  const clientId = `chainspec-${runtimeId}-${++nextClient}`;\n  const base = config.baseUrl ?? \"\";\n  const before = [...(config.beforeRequest ?? [])],\n    after = [...(config.afterResponse ?? [])],\n    errors = [...(config.onError ?? [])];\n  return {\n    endpoint<I, R>(definition: Definition): Endpoint<I, R> {\n      const def = Object.freeze({\n        ...definition,\n        parameters: definition.parameters.map((p) => Object.freeze({ ...p })),\n      });\n      async function execute(\n        input: Input = {},\n        options: RequestOptions = {},\n      ): Promise<R> {\n        let context: RequestContext | undefined;\n        try {\n          let path = def.path;\n          for (const p of def.parameters.filter((p) => p.in === \"path\")) {\n            const value = input.path?.[p.name];\n            if (value === undefined || value === null)\n              throw new Error(`Missing path parameter: ${p.name}`);\n            path = path.split(`{${p.name}}`).join(pathValue(value, p.explode));\n          }\n          if (/\\{[^}]+\\}/.test(path))\n            throw new Error(\"Unresolved path parameter\");\n          const query = new URLSearchParams();\n          const headers = new Headers(\n            typeof config.headers === \"function\"\n              ? await config.headers()\n              : config.headers,\n          );\n          new Headers(options.headers).forEach((v, k) => headers.set(k, v));\n          for (const p of def.parameters.filter((p) => p.in !== \"path\")) {\n            const bag =\n              p.in === \"query\"\n                ? input.query\n                : p.in === \"header\"\n                  ? input.headers\n                  : input.cookies;\n            const value = bag?.[p.name];\n            if (p.required && (value === undefined || value === null))\n              throw new Error(`Missing ${p.in} parameter: ${p.name}`);\n            if (value === undefined) continue;\n            if (p.in === \"query\")\n              for (const [k, v] of queryEntries(\n                p.name,\n                value,\n                p.style,\n                p.explode ?? true,\n              ))\n                query.append(k, v);\n            else if (p.in === \"header\")\n              headers.set(\n                p.name,\n                Array.isArray(value)\n                  ? value.map(scalar).join(\",\")\n                  : scalar(value),\n              );\n            else if (config.request)\n              headers.append(\n                \"Cookie\",\n                `${p.name}=${encodeURIComponent(scalar(value))}`,\n              );\n            else\n              throw new Error(\n                \"Cookie parameters require a custom Node request adapter; browser Fetch cannot set Cookie headers\",\n              );\n          }\n          if (def.bodyRequired && input.body === undefined)\n            throw new Error(\"Request body is required\");\n          const url = `${base.replace(/\\/$/, \"\")}/${path.replace(/^\\//, \"\")}${query.size ? `?${query}` : \"\"}`;\n          context = {\n            url,\n            method: def.method,\n            headers,\n            body: input.body,\n            mediaType: def.mediaType,\n            signal: options.signal,\n            operation: def,\n          };\n          for (const fn of [...before, ...(options.beforeRequest ?? [])])\n            context = (await fn(context)) ?? context;\n          let response = await (config.request ?? defaultRequest)(context);\n          if (\n            !Number.isInteger(response.status) ||\n            response.status < 100 ||\n            response.status > 599\n          )\n            throw new Error(\"Adapter must return {data,status,headers}\");\n          if (response.status < 200 || response.status >= 300)\n            throw new ApiError(\n              response.status,\n              response.data,\n              response.headers,\n            );\n          for (const fn of [...after, ...(options.afterResponse ?? [])])\n            response = (await fn(response, context)) ?? response;\n          return response.data as R;\n        } catch (error) {\n          for (const fn of [...errors, ...(options.onError ?? [])])\n            await fn(error, context);\n          throw error;\n        }\n      }\n      return {\n        definition: def,\n        request: execute as Endpoint<I, R>[\"request\"],\n        getKey(input?: I, options?: RequestOptions) {\n          const scope =\n            typeof config.cacheScope === \"function\"\n              ? config.cacheScope()\n              : (config.cacheScope ?? \"\");\n          return [\n            clientId,\n            base,\n            scope,\n            def.id,\n            input ?? {},\n            Array.from(new Headers(options?.headers).entries()),\n          ];\n        },\n      };\n    },\n  };\n}\n";
-export declare const HOOKS_SOURCE = "import useSWR, { type SWRConfiguration, type SWRResponse } from \"swr\";\nimport useSWRMutation, {\n  type SWRMutationConfiguration,\n  type SWRMutationResponse,\n} from \"swr/mutation\";\nimport type { Endpoint, RequestArgs, RequestOptions } from \"./runtime.js\";\nexport type QueryOptions<R> = {\n  enabled?: boolean;\n  request?: RequestOptions;\n  swr?: SWRConfiguration<R, Error>;\n};\nexport type QueryArgs<I, R> = {} extends I\n  ? [input?: I | null, options?: QueryOptions<R>]\n  : [input: I | null, options?: QueryOptions<R>];\nexport type MutationOptions<I, R> = {\n  request?: RequestOptions;\n  swr?: SWRMutationConfiguration<R, Error, readonly unknown[], I>;\n};\nexport type QueryEndpoint<I, R> = Endpoint<I, R> & {\n  useRequest(...args: QueryArgs<I, R>): SWRResponse<R, Error>;\n};\nexport type MutationEndpoint<I, R> = Endpoint<I, R> & {\n  useRequest(\n    options?: MutationOptions<I, R>,\n  ): SWRMutationResponse<R, Error, readonly unknown[], I>;\n  useMutation(\n    options?: MutationOptions<I, R>,\n  ): SWRMutationResponse<R, Error, readonly unknown[], I>;\n};\nexport function withQuery<I, R>(endpoint: Endpoint<I, R>): QueryEndpoint<I, R> {\n  return Object.assign(endpoint, {\n    useRequest(...[input, options]: QueryArgs<I, R>) {\n      const enabled = input !== null && options?.enabled !== false;\n      return useSWR<R, Error>(\n        enabled ? endpoint.getKey(input ?? undefined, options?.request) : null,\n        () =>\n          endpoint.request(\n            ...([input ?? undefined, options?.request] as RequestArgs<I>),\n          ),\n        options?.swr,\n      );\n    },\n  });\n}\nexport function withMutation<I, R>(\n  endpoint: Endpoint<I, R>,\n): MutationEndpoint<I, R> {\n  function useMutation(options?: MutationOptions<I, R>) {\n    return useSWRMutation<R, Error, readonly unknown[], I>(\n      endpoint.getKey(undefined, options?.request),\n      (_key, { arg }) =>\n        endpoint.request(...([arg, options?.request] as RequestArgs<I>)),\n      options?.swr,\n    );\n  }\n  return Object.assign(endpoint, { useRequest: useMutation, useMutation });\n}\n";
+export declare const RUNTIME_SOURCE = "/** ChainSpec runtime. Generated SDK types describe the spec, not runtime validation. */\nexport type Parameter = {\n  name: string;\n  in: \"path\" | \"query\" | \"header\" | \"cookie\";\n  required?: boolean;\n  style?: string;\n  explode?: boolean;\n};\nexport type Definition = {\n  id: string;\n  method: string;\n  path: string;\n  controller: string;\n  name: string;\n  parameters: Parameter[];\n  hasBody: boolean;\n  bodyRequired?: boolean;\n  mediaType?: string;\n  responseType: \"json\" | \"text\" | \"blob\" | \"void\" | \"auto\";\n};\nexport type Input = {\n  path?: Record<string, unknown>;\n  query?: Record<string, unknown>;\n  cookies?: Record<string, unknown>;\n};\nexport interface RequestContext {\n  url: string;\n  method: string;\n  headers: Headers;\n  body: unknown;\n  mediaType?: string;\n  signal?: AbortSignal;\n  readonly operation: Definition;\n}\nexport interface TransportResponse {\n  data: unknown;\n  status: number;\n  headers: Headers;\n}\nexport type RequestAdapter = (\n  context: RequestContext,\n) => Promise<TransportResponse>;\nexport type BeforeRequest = (\n  context: RequestContext,\n) => void | RequestContext | Promise<void | RequestContext>;\nexport type AfterResponse = (\n  response: TransportResponse,\n  context: RequestContext,\n) => void | TransportResponse | Promise<void | TransportResponse>;\nexport type OnError = (\n  error: unknown,\n  context: RequestContext | undefined,\n) => void | Promise<void>;\nexport interface RequestOptions {\n  signal?: AbortSignal;\n  headers?: HeadersInit;\n  beforeRequest?: BeforeRequest[];\n  afterResponse?: AfterResponse[];\n  onError?: OnError[];\n}\nexport interface ClientConfig {\n  baseUrl?: string;\n  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);\n  request?: RequestAdapter;\n  beforeRequest?: BeforeRequest[];\n  afterResponse?: AfterResponse[];\n  onError?: OnError[];\n  /** Change on tenant/user/auth changes. Never put bearer tokens here. */ cacheScope?:\n    | string\n    | (() => string);\n}\nexport type RequestArgs<\n  P,\n  B,\n  H extends boolean,\n  Required extends boolean,\n> = H extends true\n  ? Required extends true\n    ? [params: P, body: B, options?: RequestOptions]\n    : [params: P, body?: B, options?: RequestOptions]\n  : {} extends P\n    ? [params?: P, options?: RequestOptions]\n    : [params: P, options?: RequestOptions];\nexport interface Endpoint<\n  P,\n  B,\n  R,\n  H extends boolean = false,\n  Required extends boolean = false,\n> {\n  readonly definition: Definition;\n  request(...args: RequestArgs<P, B, H, Required>): Promise<R>;\n  getKey(...args: RequestArgs<P, B, H, Required>): readonly unknown[];\n}\n/** Body position is fixed by the generated operation contract, never inferred from object keys. */\nexport function splitArgs(\n  definition: Definition,\n  args: readonly unknown[],\n): { params: Input; body: unknown; options: RequestOptions } {\n  return {\n    params: (args[0] ?? {}) as Input,\n    body: definition.hasBody ? args[1] : undefined,\n    options: (args[definition.hasBody ? 2 : 1] ?? {}) as RequestOptions,\n  };\n}\nexport class ApiError extends Error {\n  constructor(\n    public status: number,\n    public data: unknown,\n    public headers: Headers,\n  ) {\n    super(`HTTP ${status}`);\n    this.name = \"ApiError\";\n  }\n}\nconst scalar = (value: unknown): string => {\n  if (value === null) return \"\";\n  if ([\"string\", \"number\", \"boolean\"].includes(typeof value))\n    return String(value);\n  throw new Error(\"Parameter must be a scalar or a declared array/object\");\n};\nconst isRecord = (v: unknown): v is Record<string, unknown> =>\n  typeof v === \"object\" && v !== null && !Array.isArray(v);\nfunction queryEntries(\n  name: string,\n  value: unknown,\n  style = \"form\",\n  explode = true,\n): [string, string][] {\n  if (value === undefined) return [];\n  if (style === \"deepObject\") {\n    if (!isRecord(value)) throw new Error(\"deepObject needs an object\");\n    return Object.entries(value)\n      .filter(([, v]) => v !== undefined)\n      .map(([k, v]) => [`${name}[${k}]`, scalar(v)]);\n  }\n  if (Array.isArray(value)) {\n    if (style === \"form\" && explode) return value.map((v) => [name, scalar(v)]);\n    const delimiter =\n      style === \"spaceDelimited\" ? \" \" : style === \"pipeDelimited\" ? \"|\" : \",\";\n    return [[name, value.map(scalar).join(delimiter)]];\n  }\n  if (isRecord(value)) {\n    const values = Object.entries(value).filter(([, v]) => v !== undefined);\n    return explode\n      ? values.map(([k, v]) => [k, scalar(v)])\n      : [[name, values.flatMap(([k, v]) => [k, scalar(v)]).join(\",\")]];\n  }\n  return [[name, scalar(value)]];\n}\nfunction pathValue(value: unknown, explode = false): string {\n  const enc = (v: unknown) => encodeURIComponent(scalar(v));\n  if (Array.isArray(value)) return value.map(enc).join(\",\");\n  if (isRecord(value))\n    return Object.entries(value)\n      .map(([k, v]) =>\n        explode ? `${enc(k)}=${enc(v)}` : `${enc(k)},${enc(v)}`,\n      )\n      .join(\",\");\n  return enc(value);\n}\nexport async function defaultRequest(\n  ctx: RequestContext,\n): Promise<TransportResponse> {\n  const headers = new Headers(ctx.headers);\n  let body: BodyInit | undefined;\n  if (ctx.body !== undefined) {\n    if (ctx.method === \"GET\" || ctx.method === \"HEAD\")\n      throw new Error(\n        \"Fetch cannot send GET/HEAD bodies; configure a request adapter\",\n      );\n    if (ctx.mediaType?.includes(\"json\")) {\n      body = JSON.stringify(ctx.body);\n      if (!headers.has(\"Content-Type\"))\n        headers.set(\"Content-Type\", ctx.mediaType);\n    } else if (ctx.mediaType?.startsWith(\"multipart/form-data\")) {\n      if (!isRecord(ctx.body))\n        throw new Error(\"Multipart body must be an object\");\n      const form = new FormData();\n      for (const [name, value] of Object.entries(ctx.body)) {\n        if (value === undefined) continue;\n        for (const v of Array.isArray(value) ? value : [value])\n          form.append(name, v instanceof Blob ? v : scalar(v));\n      }\n      body = form;\n      headers.delete(\"Content-Type\");\n    } else if (ctx.mediaType?.startsWith(\"application/x-www-form-urlencoded\")) {\n      if (!isRecord(ctx.body)) throw new Error(\"Form body must be an object\");\n      const form = new URLSearchParams();\n      for (const [name, value] of Object.entries(ctx.body))\n        for (const [k, v] of queryEntries(name, value)) form.append(k, v);\n      body = form.toString();\n      if (!headers.has(\"Content-Type\"))\n        headers.set(\"Content-Type\", ctx.mediaType);\n    } else if (\n      typeof ctx.body === \"string\" ||\n      ctx.body instanceof Blob ||\n      ctx.body instanceof ArrayBuffer ||\n      ArrayBuffer.isView(ctx.body)\n    ) {\n      body = ctx.body as BodyInit;\n      if (ctx.mediaType && !headers.has(\"Content-Type\"))\n        headers.set(\"Content-Type\", ctx.mediaType);\n    } else\n      throw new Error(\"Unsupported body format; configure a request adapter\");\n  }\n  const response = await fetch(ctx.url, {\n    method: ctx.method,\n    headers,\n    body,\n    signal: ctx.signal,\n  });\n  let data: unknown;\n  const mode = ctx.operation.responseType;\n  if (\n    response.status === 204 ||\n    response.status === 205 ||\n    ctx.method === \"HEAD\"\n  )\n    data = undefined;\n  else if (!response.ok) {\n    const text = await response.text();\n    try {\n      data = JSON.parse(text);\n    } catch {\n      data = text;\n    }\n  } else if (mode === \"void\") data = undefined;\n  else if (\n    mode === \"blob\" ||\n    (mode === \"auto\" &&\n      !response.headers.get(\"Content-Type\")?.includes(\"json\") &&\n      !response.headers.get(\"Content-Type\")?.startsWith(\"text/\"))\n  )\n    data = await response.blob();\n  else {\n    const text = await response.text();\n    data =\n      mode === \"json\" ||\n      (mode === \"auto\" &&\n        response.headers.get(\"Content-Type\")?.includes(\"json\"))\n        ? text\n          ? JSON.parse(text)\n          : undefined\n        : text;\n  }\n  return { data, status: response.status, headers: response.headers };\n}\nconst runtimeId = Math.random().toString(36).slice(2);\nlet nextClient = 0;\nexport function createClient(config: ClientConfig = {}) {\n  const clientId = `chainspec-${runtimeId}-${++nextClient}`;\n  const base = config.baseUrl ?? \"\";\n  const before = [...(config.beforeRequest ?? [])],\n    after = [...(config.afterResponse ?? [])],\n    errors = [...(config.onError ?? [])];\n  return {\n    endpoint<P, B, R, H extends boolean, Required extends boolean>(\n      definition: Definition,\n    ): Endpoint<P, B, R, H, Required> {\n      const def = Object.freeze({\n        ...definition,\n        parameters: definition.parameters.map((p) => Object.freeze({ ...p })),\n      });\n      async function execute(...args: unknown[]): Promise<R> {\n        const { params: input, body, options } = splitArgs(def, args);\n        let context: RequestContext | undefined;\n        try {\n          let path = def.path;\n          for (const p of def.parameters.filter((p) => p.in === \"path\")) {\n            const value = input.path?.[p.name];\n            if (value === undefined || value === null)\n              throw new Error(`Missing path parameter: ${p.name}`);\n            path = path.split(`{${p.name}}`).join(pathValue(value, p.explode));\n          }\n          if (/\\{[^}]+\\}/.test(path))\n            throw new Error(\"Unresolved path parameter\");\n          const query = new URLSearchParams();\n          const headers = new Headers(\n            typeof config.headers === \"function\"\n              ? await config.headers()\n              : config.headers,\n          );\n          new Headers(options.headers).forEach((v, k) => headers.set(k, v));\n          for (const p of def.parameters.filter(\n            (p) => p.in === \"query\" || p.in === \"cookie\",\n          )) {\n            const bag = p.in === \"query\" ? input.query : input.cookies;\n            const value = bag?.[p.name];\n            if (p.required && (value === undefined || value === null))\n              throw new Error(`Missing ${p.in} parameter: ${p.name}`);\n            if (value === undefined) continue;\n            if (p.in === \"query\")\n              for (const [k, v] of queryEntries(\n                p.name,\n                value,\n                p.style,\n                p.explode ?? true,\n              ))\n                query.append(k, v);\n            else if (config.request)\n              headers.append(\n                \"Cookie\",\n                `${p.name}=${encodeURIComponent(scalar(value))}`,\n              );\n            else\n              throw new Error(\n                \"Cookie parameters require a custom Node request adapter; browser Fetch cannot set Cookie headers\",\n              );\n          }\n          if (def.bodyRequired && body === undefined)\n            throw new Error(\"Request body is required\");\n          const url = `${base.replace(/\\/$/, \"\")}/${path.replace(/^\\//, \"\")}${query.size ? `?${query}` : \"\"}`;\n          context = {\n            url,\n            method: def.method,\n            headers,\n            body,\n            mediaType: def.mediaType,\n            signal: options.signal,\n            operation: def,\n          };\n          for (const fn of [...before, ...(options.beforeRequest ?? [])])\n            context = (await fn(context)) ?? context;\n          for (const p of def.parameters.filter(\n            (p) => p.in === \"header\" && p.required,\n          )) {\n            if (!context.headers.has(p.name))\n              throw new Error(`Missing header parameter: ${p.name}`);\n          }\n          let response = await (config.request ?? defaultRequest)(context);\n          if (\n            !Number.isInteger(response.status) ||\n            response.status < 100 ||\n            response.status > 599\n          )\n            throw new Error(\"Adapter must return {data,status,headers}\");\n          if (response.status < 200 || response.status >= 300)\n            throw new ApiError(\n              response.status,\n              response.data,\n              response.headers,\n            );\n          for (const fn of [...after, ...(options.afterResponse ?? [])])\n            response = (await fn(response, context)) ?? response;\n          return response.data as R;\n        } catch (error) {\n          for (const fn of [...errors, ...(options.onError ?? [])])\n            await fn(error, context);\n          throw error;\n        }\n      }\n      return {\n        definition: def,\n        request: execute as Endpoint<P, B, R, H, Required>[\"request\"],\n        getKey(...args: RequestArgs<P, B, H, Required>) {\n          const { params, body, options } = splitArgs(def, args);\n          const scope =\n            typeof config.cacheScope === \"function\"\n              ? config.cacheScope()\n              : (config.cacheScope ?? \"\");\n          return [\n            clientId,\n            base,\n            scope,\n            def.id,\n            params,\n            body,\n            Array.from(new Headers(options?.headers).entries()),\n          ];\n        },\n      };\n    },\n  };\n}\n";
+export declare const HOOKS_SOURCE = "import useSWR, { type SWRConfiguration, type SWRResponse } from \"swr\";\nimport useSWRMutation, {\n  type SWRMutationConfiguration,\n  type SWRMutationResponse,\n} from \"swr/mutation\";\nimport {\n  splitArgs,\n  type Endpoint,\n  type RequestArgs,\n  type RequestOptions,\n} from \"./runtime.js\";\nexport type QueryOptions<R> = RequestOptions & {\n  enabled?: boolean;\n  swr?: SWRConfiguration<R, Error>;\n};\nexport type QueryArgs<\n  P,\n  B,\n  R,\n  H extends boolean,\n  Required extends boolean,\n> = H extends true\n  ? Required extends true\n    ? [params: P | null, body: B, options?: QueryOptions<R>]\n    : [params: P | null, body?: B, options?: QueryOptions<R>]\n  : {} extends P\n    ? [params?: P | null, options?: QueryOptions<R>]\n    : [params: P | null, options?: QueryOptions<R>];\nexport type MutationOptions<B, R> = RequestOptions & {\n  swr?: SWRMutationConfiguration<R, Error, readonly unknown[], B> & {\n    throwOnError?: boolean;\n  };\n};\nexport type TriggerOptions<B, R> = SWRMutationConfiguration<\n  R,\n  Error,\n  readonly unknown[],\n  B\n> & { throwOnError?: boolean };\nexport type MutationResult<B, R, Bound extends boolean> = Omit<\n  SWRMutationResponse<R, Error, readonly unknown[], B>,\n  \"trigger\"\n> & {\n  trigger(\n    ...args: Bound extends true\n      ? [body?: B, options?: TriggerOptions<B, R>]\n      : [body: B, options?: TriggerOptions<B, R>]\n  ): Promise<R | undefined>;\n};\nexport type MutationHook<\n  P,\n  B,\n  R,\n  H extends boolean,\n  Required extends boolean,\n> = H extends true\n  ? {\n      (\n        params: P,\n        body: B,\n        options?: MutationOptions<B, R>,\n      ): MutationResult<B, R, true>;\n      (\n        params: P,\n        body?: undefined,\n        options?: MutationOptions<B, R>,\n      ): MutationResult<B, R, Required extends true ? false : true>;\n    }\n  : (\n      ...args: {} extends P\n        ? [params?: P, options?: MutationOptions<never, R>]\n        : [params: P, options?: MutationOptions<never, R>]\n    ) => MutationResult<never, R, true>;\nexport type QueryEndpoint<\n  P,\n  B,\n  R,\n  H extends boolean,\n  Required extends boolean,\n> = Endpoint<P, B, R, H, Required> & {\n  useRequest(...args: QueryArgs<P, B, R, H, Required>): SWRResponse<R, Error>;\n};\nexport type MutationEndpoint<\n  P,\n  B,\n  R,\n  H extends boolean,\n  Required extends boolean,\n> = Endpoint<P, B, R, H, Required> & {\n  useRequest: MutationHook<P, B, R, H, Required>;\n  useMutation: MutationHook<P, B, R, H, Required>;\n};\nexport function withQuery<P, B, R, H extends boolean, Required extends boolean>(\n  endpoint: Endpoint<P, B, R, H, Required>,\n): QueryEndpoint<P, B, R, H, Required> {\n  function useRequest(...args: QueryArgs<P, B, R, H, Required>) {\n    const { options } = splitArgs(endpoint.definition, args);\n    const config = options as QueryOptions<R>;\n    const requestArgs = args as unknown as RequestArgs<P, B, H, Required>;\n    return useSWR<R, Error>(\n      args[0] !== null && config.enabled !== false\n        ? endpoint.getKey(...requestArgs)\n        : null,\n      () => endpoint.request(...requestArgs),\n      config.swr,\n    );\n  }\n  return Object.assign(endpoint, { useRequest });\n}\nexport function withMutation<\n  P,\n  B,\n  R,\n  H extends boolean,\n  Required extends boolean,\n>(\n  endpoint: Endpoint<P, B, R, H, Required>,\n): MutationEndpoint<P, B, R, H, Required> {\n  function useMutation(...args: unknown[]) {\n    const {\n      params,\n      body: preset,\n      options,\n    } = splitArgs(endpoint.definition, args);\n    const config = options as MutationOptions<B, R>;\n    const boundArgs = (endpoint.definition.hasBody\n      ? [params, preset, options]\n      : [params, options]) as unknown as RequestArgs<P, B, H, Required>;\n    const state = useSWRMutation<R, Error, readonly unknown[], B>(\n      endpoint.getKey(...boundArgs),\n      (_key, { arg }) => {\n        const requestArgs = (endpoint.definition.hasBody\n          ? [params, arg, options]\n          : [params, options]) as unknown as RequestArgs<P, B, H, Required>;\n        return endpoint.request(...requestArgs);\n      },\n      config.swr,\n    );\n    return {\n      ...state,\n      trigger: (...triggerArgs: unknown[]) => {\n        const body = triggerArgs.length ? triggerArgs[0] : preset;\n        const trigger = state.trigger as (\n          body: B,\n          options?: TriggerOptions<B, R>,\n        ) => Promise<R | undefined>;\n        return trigger(\n          body as B,\n          triggerArgs[1] as TriggerOptions<B, R> | undefined,\n        );\n      },\n    };\n  }\n  return Object.assign(endpoint, {\n    useRequest: useMutation,\n    useMutation,\n  }) as MutationEndpoint<P, B, R, H, Required>;\n}\n";
 export declare const RUNTIME_LICENSE = "MIT License\n\nCopyright (c) 2026 batype and SnapNest contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n";

package/lib/core/templates.js

@@ -1,4 +1,4 @@
 // Generated by scripts/embed-templates.mjs. Edit templates/ instead.
-export const RUNTIME_SOURCE = "/** ChainSpec runtime. Generated SDK types describe the spec, not runtime validation. */\nexport type Parameter = {\n  name: string;\n  in: \"path\" | \"query\" | \"header\" | \"cookie\";\n  required?: boolean;\n  style?: string;\n  explode?: boolean;\n};\nexport type Definition = {\n  id: string;\n  method: string;\n  path: string;\n  controller: string;\n  name: string;\n  parameters: Parameter[];\n  bodyRequired?: boolean;\n  mediaType?: string;\n  responseType: \"json\" | \"text\" | \"blob\" | \"void\" | \"auto\";\n};\nexport type Input = {\n  path?: Record<string, unknown>;\n  query?: Record<string, unknown>;\n  headers?: Record<string, unknown>;\n  cookies?: Record<string, unknown>;\n  body?: unknown;\n};\nexport interface RequestContext {\n  url: string;\n  method: string;\n  headers: Headers;\n  body: unknown;\n  mediaType?: string;\n  signal?: AbortSignal;\n  readonly operation: Definition;\n}\nexport interface TransportResponse {\n  data: unknown;\n  status: number;\n  headers: Headers;\n}\nexport type RequestAdapter = (\n  context: RequestContext,\n) => Promise<TransportResponse>;\nexport type BeforeRequest = (\n  context: RequestContext,\n) => void | RequestContext | Promise<void | RequestContext>;\nexport type AfterResponse = (\n  response: TransportResponse,\n  context: RequestContext,\n) => void | TransportResponse | Promise<void | TransportResponse>;\nexport type OnError = (\n  error: unknown,\n  context: RequestContext | undefined,\n) => void | Promise<void>;\nexport interface RequestOptions {\n  signal?: AbortSignal;\n  headers?: HeadersInit;\n  beforeRequest?: BeforeRequest[];\n  afterResponse?: AfterResponse[];\n  onError?: OnError[];\n}\nexport interface ClientConfig {\n  baseUrl?: string;\n  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);\n  request?: RequestAdapter;\n  beforeRequest?: BeforeRequest[];\n  afterResponse?: AfterResponse[];\n  onError?: OnError[];\n  /** Change on tenant/user/auth changes. Never put bearer tokens here. */ cacheScope?:\n    | string\n    | (() => string);\n}\nexport type RequestArgs<I> = {} extends I\n  ? [input?: I, options?: RequestOptions]\n  : [input: I, options?: RequestOptions];\nexport interface Endpoint<I, R> {\n  readonly definition: Definition;\n  request(...args: RequestArgs<I>): Promise<R>;\n  getKey(input?: I, options?: RequestOptions): readonly unknown[];\n}\nexport class ApiError extends Error {\n  constructor(\n    public status: number,\n    public data: unknown,\n    public headers: Headers,\n  ) {\n    super(`HTTP ${status}`);\n    this.name = \"ApiError\";\n  }\n}\nconst scalar = (value: unknown): string => {\n  if (value === null) return \"\";\n  if ([\"string\", \"number\", \"boolean\"].includes(typeof value))\n    return String(value);\n  throw new Error(\"Parameter must be a scalar or a declared array/object\");\n};\nconst isRecord = (v: unknown): v is Record<string, unknown> =>\n  typeof v === \"object\" && v !== null && !Array.isArray(v);\nfunction queryEntries(\n  name: string,\n  value: unknown,\n  style = \"form\",\n  explode = true,\n): [string, string][] {\n  if (value === undefined) return [];\n  if (style === \"deepObject\") {\n    if (!isRecord(value)) throw new Error(\"deepObject needs an object\");\n    return Object.entries(value)\n      .filter(([, v]) => v !== undefined)\n      .map(([k, v]) => [`${name}[${k}]`, scalar(v)]);\n  }\n  if (Array.isArray(value)) {\n    if (style === \"form\" && explode) return value.map((v) => [name, scalar(v)]);\n    const delimiter =\n      style === \"spaceDelimited\" ? \" \" : style === \"pipeDelimited\" ? \"|\" : \",\";\n    return [[name, value.map(scalar).join(delimiter)]];\n  }\n  if (isRecord(value)) {\n    const values = Object.entries(value).filter(([, v]) => v !== undefined);\n    return explode\n      ? values.map(([k, v]) => [k, scalar(v)])\n      : [[name, values.flatMap(([k, v]) => [k, scalar(v)]).join(\",\")]];\n  }\n  return [[name, scalar(value)]];\n}\nfunction pathValue(value: unknown, explode = false): string {\n  const enc = (v: unknown) => encodeURIComponent(scalar(v));\n  if (Array.isArray(value)) return value.map(enc).join(\",\");\n  if (isRecord(value))\n    return Object.entries(value)\n      .map(([k, v]) =>\n        explode ? `${enc(k)}=${enc(v)}` : `${enc(k)},${enc(v)}`,\n      )\n      .join(\",\");\n  return enc(value);\n}\nexport async function defaultRequest(\n  ctx: RequestContext,\n): Promise<TransportResponse> {\n  const headers = new Headers(ctx.headers);\n  let body: BodyInit | undefined;\n  if (ctx.body !== undefined) {\n    if (ctx.method === \"GET\" || ctx.method === \"HEAD\")\n      throw new Error(\n        \"Fetch cannot send GET/HEAD bodies; configure a request adapter\",\n      );\n    if (ctx.mediaType?.includes(\"json\")) {\n      body = JSON.stringify(ctx.body);\n      if (!headers.has(\"Content-Type\"))\n        headers.set(\"Content-Type\", ctx.mediaType);\n    } else if (ctx.mediaType?.startsWith(\"multipart/form-data\")) {\n      if (!isRecord(ctx.body))\n        throw new Error(\"Multipart body must be an object\");\n      const form = new FormData();\n      for (const [name, value] of Object.entries(ctx.body)) {\n        if (value === undefined) continue;\n        for (const v of Array.isArray(value) ? value : [value])\n          form.append(name, v instanceof Blob ? v : scalar(v));\n      }\n      body = form;\n      headers.delete(\"Content-Type\");\n    } else if (ctx.mediaType?.startsWith(\"application/x-www-form-urlencoded\")) {\n      if (!isRecord(ctx.body)) throw new Error(\"Form body must be an object\");\n      const form = new URLSearchParams();\n      for (const [name, value] of Object.entries(ctx.body))\n        for (const [k, v] of queryEntries(name, value)) form.append(k, v);\n      body = form.toString();\n      if (!headers.has(\"Content-Type\"))\n        headers.set(\"Content-Type\", ctx.mediaType);\n    } else if (\n      typeof ctx.body === \"string\" ||\n      ctx.body instanceof Blob ||\n      ctx.body instanceof ArrayBuffer ||\n      ArrayBuffer.isView(ctx.body)\n    ) {\n      body = ctx.body as BodyInit;\n      if (ctx.mediaType && !headers.has(\"Content-Type\"))\n        headers.set(\"Content-Type\", ctx.mediaType);\n    } else\n      throw new Error(\"Unsupported body format; configure a request adapter\");\n  }\n  const response = await fetch(ctx.url, {\n    method: ctx.method,\n    headers,\n    body,\n    signal: ctx.signal,\n  });\n  let data: unknown;\n  const mode = ctx.operation.responseType;\n  if (\n    response.status === 204 ||\n    response.status === 205 ||\n    ctx.method === \"HEAD\"\n  )\n    data = undefined;\n  else if (!response.ok) {\n    const text = await response.text();\n    try {\n      data = JSON.parse(text);\n    } catch {\n      data = text;\n    }\n  } else if (mode === \"void\") data = undefined;\n  else if (\n    mode === \"blob\" ||\n    (mode === \"auto\" &&\n      !response.headers.get(\"Content-Type\")?.includes(\"json\") &&\n      !response.headers.get(\"Content-Type\")?.startsWith(\"text/\"))\n  )\n    data = await response.blob();\n  else {\n    const text = await response.text();\n    data =\n      mode === \"json\" ||\n      (mode === \"auto\" &&\n        response.headers.get(\"Content-Type\")?.includes(\"json\"))\n        ? text\n          ? JSON.parse(text)\n          : undefined\n        : text;\n  }\n  return { data, status: response.status, headers: response.headers };\n}\nconst runtimeId = Math.random().toString(36).slice(2);\nlet nextClient = 0;\nexport function createClient(config: ClientConfig = {}) {\n  const clientId = `chainspec-${runtimeId}-${++nextClient}`;\n  const base = config.baseUrl ?? \"\";\n  const before = [...(config.beforeRequest ?? [])],\n    after = [...(config.afterResponse ?? [])],\n    errors = [...(config.onError ?? [])];\n  return {\n    endpoint<I, R>(definition: Definition): Endpoint<I, R> {\n      const def = Object.freeze({\n        ...definition,\n        parameters: definition.parameters.map((p) => Object.freeze({ ...p })),\n      });\n      async function execute(\n        input: Input = {},\n        options: RequestOptions = {},\n      ): Promise<R> {\n        let context: RequestContext | undefined;\n        try {\n          let path = def.path;\n          for (const p of def.parameters.filter((p) => p.in === \"path\")) {\n            const value = input.path?.[p.name];\n            if (value === undefined || value === null)\n              throw new Error(`Missing path parameter: ${p.name}`);\n            path = path.split(`{${p.name}}`).join(pathValue(value, p.explode));\n          }\n          if (/\\{[^}]+\\}/.test(path))\n            throw new Error(\"Unresolved path parameter\");\n          const query = new URLSearchParams();\n          const headers = new Headers(\n            typeof config.headers === \"function\"\n              ? await config.headers()\n              : config.headers,\n          );\n          new Headers(options.headers).forEach((v, k) => headers.set(k, v));\n          for (const p of def.parameters.filter((p) => p.in !== \"path\")) {\n            const bag =\n              p.in === \"query\"\n                ? input.query\n                : p.in === \"header\"\n                  ? input.headers\n                  : input.cookies;\n            const value = bag?.[p.name];\n            if (p.required && (value === undefined || value === null))\n              throw new Error(`Missing ${p.in} parameter: ${p.name}`);\n            if (value === undefined) continue;\n            if (p.in === \"query\")\n              for (const [k, v] of queryEntries(\n                p.name,\n                value,\n                p.style,\n                p.explode ?? true,\n              ))\n                query.append(k, v);\n            else if (p.in === \"header\")\n              headers.set(\n                p.name,\n                Array.isArray(value)\n                  ? value.map(scalar).join(\",\")\n                  : scalar(value),\n              );\n            else if (config.request)\n              headers.append(\n                \"Cookie\",\n                `${p.name}=${encodeURIComponent(scalar(value))}`,\n              );\n            else\n              throw new Error(\n                \"Cookie parameters require a custom Node request adapter; browser Fetch cannot set Cookie headers\",\n              );\n          }\n          if (def.bodyRequired && input.body === undefined)\n            throw new Error(\"Request body is required\");\n          const url = `${base.replace(/\\/$/, \"\")}/${path.replace(/^\\//, \"\")}${query.size ? `?${query}` : \"\"}`;\n          context = {\n            url,\n            method: def.method,\n            headers,\n            body: input.body,\n            mediaType: def.mediaType,\n            signal: options.signal,\n            operation: def,\n          };\n          for (const fn of [...before, ...(options.beforeRequest ?? [])])\n            context = (await fn(context)) ?? context;\n          let response = await (config.request ?? defaultRequest)(context);\n          if (\n            !Number.isInteger(response.status) ||\n            response.status < 100 ||\n            response.status > 599\n          )\n            throw new Error(\"Adapter must return {data,status,headers}\");\n          if (response.status < 200 || response.status >= 300)\n            throw new ApiError(\n              response.status,\n              response.data,\n              response.headers,\n            );\n          for (const fn of [...after, ...(options.afterResponse ?? [])])\n            response = (await fn(response, context)) ?? response;\n          return response.data as R;\n        } catch (error) {\n          for (const fn of [...errors, ...(options.onError ?? [])])\n            await fn(error, context);\n          throw error;\n        }\n      }\n      return {\n        definition: def,\n        request: execute as Endpoint<I, R>[\"request\"],\n        getKey(input?: I, options?: RequestOptions) {\n          const scope =\n            typeof config.cacheScope === \"function\"\n              ? config.cacheScope()\n              : (config.cacheScope ?? \"\");\n          return [\n            clientId,\n            base,\n            scope,\n            def.id,\n            input ?? {},\n            Array.from(new Headers(options?.headers).entries()),\n          ];\n        },\n      };\n    },\n  };\n}\n";
-export const HOOKS_SOURCE = "import useSWR, { type SWRConfiguration, type SWRResponse } from \"swr\";\nimport useSWRMutation, {\n  type SWRMutationConfiguration,\n  type SWRMutationResponse,\n} from \"swr/mutation\";\nimport type { Endpoint, RequestArgs, RequestOptions } from \"./runtime.js\";\nexport type QueryOptions<R> = {\n  enabled?: boolean;\n  request?: RequestOptions;\n  swr?: SWRConfiguration<R, Error>;\n};\nexport type QueryArgs<I, R> = {} extends I\n  ? [input?: I | null, options?: QueryOptions<R>]\n  : [input: I | null, options?: QueryOptions<R>];\nexport type MutationOptions<I, R> = {\n  request?: RequestOptions;\n  swr?: SWRMutationConfiguration<R, Error, readonly unknown[], I>;\n};\nexport type QueryEndpoint<I, R> = Endpoint<I, R> & {\n  useRequest(...args: QueryArgs<I, R>): SWRResponse<R, Error>;\n};\nexport type MutationEndpoint<I, R> = Endpoint<I, R> & {\n  useRequest(\n    options?: MutationOptions<I, R>,\n  ): SWRMutationResponse<R, Error, readonly unknown[], I>;\n  useMutation(\n    options?: MutationOptions<I, R>,\n  ): SWRMutationResponse<R, Error, readonly unknown[], I>;\n};\nexport function withQuery<I, R>(endpoint: Endpoint<I, R>): QueryEndpoint<I, R> {\n  return Object.assign(endpoint, {\n    useRequest(...[input, options]: QueryArgs<I, R>) {\n      const enabled = input !== null && options?.enabled !== false;\n      return useSWR<R, Error>(\n        enabled ? endpoint.getKey(input ?? undefined, options?.request) : null,\n        () =>\n          endpoint.request(\n            ...([input ?? undefined, options?.request] as RequestArgs<I>),\n          ),\n        options?.swr,\n      );\n    },\n  });\n}\nexport function withMutation<I, R>(\n  endpoint: Endpoint<I, R>,\n): MutationEndpoint<I, R> {\n  function useMutation(options?: MutationOptions<I, R>) {\n    return useSWRMutation<R, Error, readonly unknown[], I>(\n      endpoint.getKey(undefined, options?.request),\n      (_key, { arg }) =>\n        endpoint.request(...([arg, options?.request] as RequestArgs<I>)),\n      options?.swr,\n    );\n  }\n  return Object.assign(endpoint, { useRequest: useMutation, useMutation });\n}\n";
+export const RUNTIME_SOURCE = "/** ChainSpec runtime. Generated SDK types describe the spec, not runtime validation. */\nexport type Parameter = {\n  name: string;\n  in: \"path\" | \"query\" | \"header\" | \"cookie\";\n  required?: boolean;\n  style?: string;\n  explode?: boolean;\n};\nexport type Definition = {\n  id: string;\n  method: string;\n  path: string;\n  controller: string;\n  name: string;\n  parameters: Parameter[];\n  hasBody: boolean;\n  bodyRequired?: boolean;\n  mediaType?: string;\n  responseType: \"json\" | \"text\" | \"blob\" | \"void\" | \"auto\";\n};\nexport type Input = {\n  path?: Record<string, unknown>;\n  query?: Record<string, unknown>;\n  cookies?: Record<string, unknown>;\n};\nexport interface RequestContext {\n  url: string;\n  method: string;\n  headers: Headers;\n  body: unknown;\n  mediaType?: string;\n  signal?: AbortSignal;\n  readonly operation: Definition;\n}\nexport interface TransportResponse {\n  data: unknown;\n  status: number;\n  headers: Headers;\n}\nexport type RequestAdapter = (\n  context: RequestContext,\n) => Promise<TransportResponse>;\nexport type BeforeRequest = (\n  context: RequestContext,\n) => void | RequestContext | Promise<void | RequestContext>;\nexport type AfterResponse = (\n  response: TransportResponse,\n  context: RequestContext,\n) => void | TransportResponse | Promise<void | TransportResponse>;\nexport type OnError = (\n  error: unknown,\n  context: RequestContext | undefined,\n) => void | Promise<void>;\nexport interface RequestOptions {\n  signal?: AbortSignal;\n  headers?: HeadersInit;\n  beforeRequest?: BeforeRequest[];\n  afterResponse?: AfterResponse[];\n  onError?: OnError[];\n}\nexport interface ClientConfig {\n  baseUrl?: string;\n  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);\n  request?: RequestAdapter;\n  beforeRequest?: BeforeRequest[];\n  afterResponse?: AfterResponse[];\n  onError?: OnError[];\n  /** Change on tenant/user/auth changes. Never put bearer tokens here. */ cacheScope?:\n    | string\n    | (() => string);\n}\nexport type RequestArgs<\n  P,\n  B,\n  H extends boolean,\n  Required extends boolean,\n> = H extends true\n  ? Required extends true\n    ? [params: P, body: B, options?: RequestOptions]\n    : [params: P, body?: B, options?: RequestOptions]\n  : {} extends P\n    ? [params?: P, options?: RequestOptions]\n    : [params: P, options?: RequestOptions];\nexport interface Endpoint<\n  P,\n  B,\n  R,\n  H extends boolean = false,\n  Required extends boolean = false,\n> {\n  readonly definition: Definition;\n  request(...args: RequestArgs<P, B, H, Required>): Promise<R>;\n  getKey(...args: RequestArgs<P, B, H, Required>): readonly unknown[];\n}\n/** Body position is fixed by the generated operation contract, never inferred from object keys. */\nexport function splitArgs(\n  definition: Definition,\n  args: readonly unknown[],\n): { params: Input; body: unknown; options: RequestOptions } {\n  return {\n    params: (args[0] ?? {}) as Input,\n    body: definition.hasBody ? args[1] : undefined,\n    options: (args[definition.hasBody ? 2 : 1] ?? {}) as RequestOptions,\n  };\n}\nexport class ApiError extends Error {\n  constructor(\n    public status: number,\n    public data: unknown,\n    public headers: Headers,\n  ) {\n    super(`HTTP ${status}`);\n    this.name = \"ApiError\";\n  }\n}\nconst scalar = (value: unknown): string => {\n  if (value === null) return \"\";\n  if ([\"string\", \"number\", \"boolean\"].includes(typeof value))\n    return String(value);\n  throw new Error(\"Parameter must be a scalar or a declared array/object\");\n};\nconst isRecord = (v: unknown): v is Record<string, unknown> =>\n  typeof v === \"object\" && v !== null && !Array.isArray(v);\nfunction queryEntries(\n  name: string,\n  value: unknown,\n  style = \"form\",\n  explode = true,\n): [string, string][] {\n  if (value === undefined) return [];\n  if (style === \"deepObject\") {\n    if (!isRecord(value)) throw new Error(\"deepObject needs an object\");\n    return Object.entries(value)\n      .filter(([, v]) => v !== undefined)\n      .map(([k, v]) => [`${name}[${k}]`, scalar(v)]);\n  }\n  if (Array.isArray(value)) {\n    if (style === \"form\" && explode) return value.map((v) => [name, scalar(v)]);\n    const delimiter =\n      style === \"spaceDelimited\" ? \" \" : style === \"pipeDelimited\" ? \"|\" : \",\";\n    return [[name, value.map(scalar).join(delimiter)]];\n  }\n  if (isRecord(value)) {\n    const values = Object.entries(value).filter(([, v]) => v !== undefined);\n    return explode\n      ? values.map(([k, v]) => [k, scalar(v)])\n      : [[name, values.flatMap(([k, v]) => [k, scalar(v)]).join(\",\")]];\n  }\n  return [[name, scalar(value)]];\n}\nfunction pathValue(value: unknown, explode = false): string {\n  const enc = (v: unknown) => encodeURIComponent(scalar(v));\n  if (Array.isArray(value)) return value.map(enc).join(\",\");\n  if (isRecord(value))\n    return Object.entries(value)\n      .map(([k, v]) =>\n        explode ? `${enc(k)}=${enc(v)}` : `${enc(k)},${enc(v)}`,\n      )\n      .join(\",\");\n  return enc(value);\n}\nexport async function defaultRequest(\n  ctx: RequestContext,\n): Promise<TransportResponse> {\n  const headers = new Headers(ctx.headers);\n  let body: BodyInit | undefined;\n  if (ctx.body !== undefined) {\n    if (ctx.method === \"GET\" || ctx.method === \"HEAD\")\n      throw new Error(\n        \"Fetch cannot send GET/HEAD bodies; configure a request adapter\",\n      );\n    if (ctx.mediaType?.includes(\"json\")) {\n      body = JSON.stringify(ctx.body);\n      if (!headers.has(\"Content-Type\"))\n        headers.set(\"Content-Type\", ctx.mediaType);\n    } else if (ctx.mediaType?.startsWith(\"multipart/form-data\")) {\n      if (!isRecord(ctx.body))\n        throw new Error(\"Multipart body must be an object\");\n      const form = new FormData();\n      for (const [name, value] of Object.entries(ctx.body)) {\n        if (value === undefined) continue;\n        for (const v of Array.isArray(value) ? value : [value])\n          form.append(name, v instanceof Blob ? v : scalar(v));\n      }\n      body = form;\n      headers.delete(\"Content-Type\");\n    } else if (ctx.mediaType?.startsWith(\"application/x-www-form-urlencoded\")) {\n      if (!isRecord(ctx.body)) throw new Error(\"Form body must be an object\");\n      const form = new URLSearchParams();\n      for (const [name, value] of Object.entries(ctx.body))\n        for (const [k, v] of queryEntries(name, value)) form.append(k, v);\n      body = form.toString();\n      if (!headers.has(\"Content-Type\"))\n        headers.set(\"Content-Type\", ctx.mediaType);\n    } else if (\n      typeof ctx.body === \"string\" ||\n      ctx.body instanceof Blob ||\n      ctx.body instanceof ArrayBuffer ||\n      ArrayBuffer.isView(ctx.body)\n    ) {\n      body = ctx.body as BodyInit;\n      if (ctx.mediaType && !headers.has(\"Content-Type\"))\n        headers.set(\"Content-Type\", ctx.mediaType);\n    } else\n      throw new Error(\"Unsupported body format; configure a request adapter\");\n  }\n  const response = await fetch(ctx.url, {\n    method: ctx.method,\n    headers,\n    body,\n    signal: ctx.signal,\n  });\n  let data: unknown;\n  const mode = ctx.operation.responseType;\n  if (\n    response.status === 204 ||\n    response.status === 205 ||\n    ctx.method === \"HEAD\"\n  )\n    data = undefined;\n  else if (!response.ok) {\n    const text = await response.text();\n    try {\n      data = JSON.parse(text);\n    } catch {\n      data = text;\n    }\n  } else if (mode === \"void\") data = undefined;\n  else if (\n    mode === \"blob\" ||\n    (mode === \"auto\" &&\n      !response.headers.get(\"Content-Type\")?.includes(\"json\") &&\n      !response.headers.get(\"Content-Type\")?.startsWith(\"text/\"))\n  )\n    data = await response.blob();\n  else {\n    const text = await response.text();\n    data =\n      mode === \"json\" ||\n      (mode === \"auto\" &&\n        response.headers.get(\"Content-Type\")?.includes(\"json\"))\n        ? text\n          ? JSON.parse(text)\n          : undefined\n        : text;\n  }\n  return { data, status: response.status, headers: response.headers };\n}\nconst runtimeId = Math.random().toString(36).slice(2);\nlet nextClient = 0;\nexport function createClient(config: ClientConfig = {}) {\n  const clientId = `chainspec-${runtimeId}-${++nextClient}`;\n  const base = config.baseUrl ?? \"\";\n  const before = [...(config.beforeRequest ?? [])],\n    after = [...(config.afterResponse ?? [])],\n    errors = [...(config.onError ?? [])];\n  return {\n    endpoint<P, B, R, H extends boolean, Required extends boolean>(\n      definition: Definition,\n    ): Endpoint<P, B, R, H, Required> {\n      const def = Object.freeze({\n        ...definition,\n        parameters: definition.parameters.map((p) => Object.freeze({ ...p })),\n      });\n      async function execute(...args: unknown[]): Promise<R> {\n        const { params: input, body, options } = splitArgs(def, args);\n        let context: RequestContext | undefined;\n        try {\n          let path = def.path;\n          for (const p of def.parameters.filter((p) => p.in === \"path\")) {\n            const value = input.path?.[p.name];\n            if (value === undefined || value === null)\n              throw new Error(`Missing path parameter: ${p.name}`);\n            path = path.split(`{${p.name}}`).join(pathValue(value, p.explode));\n          }\n          if (/\\{[^}]+\\}/.test(path))\n            throw new Error(\"Unresolved path parameter\");\n          const query = new URLSearchParams();\n          const headers = new Headers(\n            typeof config.headers === \"function\"\n              ? await config.headers()\n              : config.headers,\n          );\n          new Headers(options.headers).forEach((v, k) => headers.set(k, v));\n          for (const p of def.parameters.filter(\n            (p) => p.in === \"query\" || p.in === \"cookie\",\n          )) {\n            const bag = p.in === \"query\" ? input.query : input.cookies;\n            const value = bag?.[p.name];\n            if (p.required && (value === undefined || value === null))\n              throw new Error(`Missing ${p.in} parameter: ${p.name}`);\n            if (value === undefined) continue;\n            if (p.in === \"query\")\n              for (const [k, v] of queryEntries(\n                p.name,\n                value,\n                p.style,\n                p.explode ?? true,\n              ))\n                query.append(k, v);\n            else if (config.request)\n              headers.append(\n                \"Cookie\",\n                `${p.name}=${encodeURIComponent(scalar(value))}`,\n              );\n            else\n              throw new Error(\n                \"Cookie parameters require a custom Node request adapter; browser Fetch cannot set Cookie headers\",\n              );\n          }\n          if (def.bodyRequired && body === undefined)\n            throw new Error(\"Request body is required\");\n          const url = `${base.replace(/\\/$/, \"\")}/${path.replace(/^\\//, \"\")}${query.size ? `?${query}` : \"\"}`;\n          context = {\n            url,\n            method: def.method,\n            headers,\n            body,\n            mediaType: def.mediaType,\n            signal: options.signal,\n            operation: def,\n          };\n          for (const fn of [...before, ...(options.beforeRequest ?? [])])\n            context = (await fn(context)) ?? context;\n          for (const p of def.parameters.filter(\n            (p) => p.in === \"header\" && p.required,\n          )) {\n            if (!context.headers.has(p.name))\n              throw new Error(`Missing header parameter: ${p.name}`);\n          }\n          let response = await (config.request ?? defaultRequest)(context);\n          if (\n            !Number.isInteger(response.status) ||\n            response.status < 100 ||\n            response.status > 599\n          )\n            throw new Error(\"Adapter must return {data,status,headers}\");\n          if (response.status < 200 || response.status >= 300)\n            throw new ApiError(\n              response.status,\n              response.data,\n              response.headers,\n            );\n          for (const fn of [...after, ...(options.afterResponse ?? [])])\n            response = (await fn(response, context)) ?? response;\n          return response.data as R;\n        } catch (error) {\n          for (const fn of [...errors, ...(options.onError ?? [])])\n            await fn(error, context);\n          throw error;\n        }\n      }\n      return {\n        definition: def,\n        request: execute as Endpoint<P, B, R, H, Required>[\"request\"],\n        getKey(...args: RequestArgs<P, B, H, Required>) {\n          const { params, body, options } = splitArgs(def, args);\n          const scope =\n            typeof config.cacheScope === \"function\"\n              ? config.cacheScope()\n              : (config.cacheScope ?? \"\");\n          return [\n            clientId,\n            base,\n            scope,\n            def.id,\n            params,\n            body,\n            Array.from(new Headers(options?.headers).entries()),\n          ];\n        },\n      };\n    },\n  };\n}\n";
+export const HOOKS_SOURCE = "import useSWR, { type SWRConfiguration, type SWRResponse } from \"swr\";\nimport useSWRMutation, {\n  type SWRMutationConfiguration,\n  type SWRMutationResponse,\n} from \"swr/mutation\";\nimport {\n  splitArgs,\n  type Endpoint,\n  type RequestArgs,\n  type RequestOptions,\n} from \"./runtime.js\";\nexport type QueryOptions<R> = RequestOptions & {\n  enabled?: boolean;\n  swr?: SWRConfiguration<R, Error>;\n};\nexport type QueryArgs<\n  P,\n  B,\n  R,\n  H extends boolean,\n  Required extends boolean,\n> = H extends true\n  ? Required extends true\n    ? [params: P | null, body: B, options?: QueryOptions<R>]\n    : [params: P | null, body?: B, options?: QueryOptions<R>]\n  : {} extends P\n    ? [params?: P | null, options?: QueryOptions<R>]\n    : [params: P | null, options?: QueryOptions<R>];\nexport type MutationOptions<B, R> = RequestOptions & {\n  swr?: SWRMutationConfiguration<R, Error, readonly unknown[], B> & {\n    throwOnError?: boolean;\n  };\n};\nexport type TriggerOptions<B, R> = SWRMutationConfiguration<\n  R,\n  Error,\n  readonly unknown[],\n  B\n> & { throwOnError?: boolean };\nexport type MutationResult<B, R, Bound extends boolean> = Omit<\n  SWRMutationResponse<R, Error, readonly unknown[], B>,\n  \"trigger\"\n> & {\n  trigger(\n    ...args: Bound extends true\n      ? [body?: B, options?: TriggerOptions<B, R>]\n      : [body: B, options?: TriggerOptions<B, R>]\n  ): Promise<R | undefined>;\n};\nexport type MutationHook<\n  P,\n  B,\n  R,\n  H extends boolean,\n  Required extends boolean,\n> = H extends true\n  ? {\n      (\n        params: P,\n        body: B,\n        options?: MutationOptions<B, R>,\n      ): MutationResult<B, R, true>;\n      (\n        params: P,\n        body?: undefined,\n        options?: MutationOptions<B, R>,\n      ): MutationResult<B, R, Required extends true ? false : true>;\n    }\n  : (\n      ...args: {} extends P\n        ? [params?: P, options?: MutationOptions<never, R>]\n        : [params: P, options?: MutationOptions<never, R>]\n    ) => MutationResult<never, R, true>;\nexport type QueryEndpoint<\n  P,\n  B,\n  R,\n  H extends boolean,\n  Required extends boolean,\n> = Endpoint<P, B, R, H, Required> & {\n  useRequest(...args: QueryArgs<P, B, R, H, Required>): SWRResponse<R, Error>;\n};\nexport type MutationEndpoint<\n  P,\n  B,\n  R,\n  H extends boolean,\n  Required extends boolean,\n> = Endpoint<P, B, R, H, Required> & {\n  useRequest: MutationHook<P, B, R, H, Required>;\n  useMutation: MutationHook<P, B, R, H, Required>;\n};\nexport function withQuery<P, B, R, H extends boolean, Required extends boolean>(\n  endpoint: Endpoint<P, B, R, H, Required>,\n): QueryEndpoint<P, B, R, H, Required> {\n  function useRequest(...args: QueryArgs<P, B, R, H, Required>) {\n    const { options } = splitArgs(endpoint.definition, args);\n    const config = options as QueryOptions<R>;\n    const requestArgs = args as unknown as RequestArgs<P, B, H, Required>;\n    return useSWR<R, Error>(\n      args[0] !== null && config.enabled !== false\n        ? endpoint.getKey(...requestArgs)\n        : null,\n      () => endpoint.request(...requestArgs),\n      config.swr,\n    );\n  }\n  return Object.assign(endpoint, { useRequest });\n}\nexport function withMutation<\n  P,\n  B,\n  R,\n  H extends boolean,\n  Required extends boolean,\n>(\n  endpoint: Endpoint<P, B, R, H, Required>,\n): MutationEndpoint<P, B, R, H, Required> {\n  function useMutation(...args: unknown[]) {\n    const {\n      params,\n      body: preset,\n      options,\n    } = splitArgs(endpoint.definition, args);\n    const config = options as MutationOptions<B, R>;\n    const boundArgs = (endpoint.definition.hasBody\n      ? [params, preset, options]\n      : [params, options]) as unknown as RequestArgs<P, B, H, Required>;\n    const state = useSWRMutation<R, Error, readonly unknown[], B>(\n      endpoint.getKey(...boundArgs),\n      (_key, { arg }) => {\n        const requestArgs = (endpoint.definition.hasBody\n          ? [params, arg, options]\n          : [params, options]) as unknown as RequestArgs<P, B, H, Required>;\n        return endpoint.request(...requestArgs);\n      },\n      config.swr,\n    );\n    return {\n      ...state,\n      trigger: (...triggerArgs: unknown[]) => {\n        const body = triggerArgs.length ? triggerArgs[0] : preset;\n        const trigger = state.trigger as (\n          body: B,\n          options?: TriggerOptions<B, R>,\n        ) => Promise<R | undefined>;\n        return trigger(\n          body as B,\n          triggerArgs[1] as TriggerOptions<B, R> | undefined,\n        );\n      },\n    };\n  }\n  return Object.assign(endpoint, {\n    useRequest: useMutation,\n    useMutation,\n  }) as MutationEndpoint<P, B, R, H, Required>;\n}\n";
 export const RUNTIME_LICENSE = "MIT License\n\nCopyright (c) 2026 batype and SnapNest contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@batype/chainspec",
-  "version": "1.0.0",
+  "version": "2.1.0",
   "description": "Generate typed chainable TypeScript SDKs and SWR hooks from OpenAPI JSON, locally.",
   "type": "module",
   "license": "MIT",