@contractkit/plugin-typescript 0.33.3 → 0.34.1

package/dist/index.js

@@ -6,10 +6,11 @@ import { resolve as resolve2, join as join2, relative as relative7, dirname as d
 import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, readdirSync, rmdirSync } from "fs";
 
 // src/codegen-contract.ts
-import { relative, dirname } from "path";
+import { relative as relative2, dirname as dirname2 } from "path";
 import { collectTypeRefs, computeModelsWithOutput as ckComputeModelsWithOutput, collectExternalOutputRefs as ckCollectExternalOutputRefs } from "@contractkit/core";
 
 // src/ts-render.ts
+import { dirname, relative } from "path";
 var JSON_VALUE_TYPE_DECL = "export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };";
 function quoteKey(name) {
   return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `'${name}'`;
@@ -23,6 +24,12 @@ function escapeSingleQuoted(s) {
   return s.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r");
 }
 __name(escapeSingleQuoted, "escapeSingleQuoted");
+function sourceLink(label, outPath, sourceFile, line) {
+  const rel = outPath ? relative(dirname(outPath), sourceFile) : sourceFile;
+  const href = rel.startsWith(".") ? rel : `./${rel}`;
+  return `[${label}](${href}${line === void 0 ? "" : `#L${line}`})`;
+}
+__name(sourceLink, "sourceLink");
 function headerNameToProperty(name) {
   const parts = name.split(/[-_]/).filter(Boolean);
   return parts.map((p, i) => {
@@ -84,7 +91,9 @@ function renderTsScalar(name, target) {
     case "date":
     case "time":
     case "datetime":
+      return "DateTime";
     case "duration":
+      return "Duration";
     case "interval":
       return "string";
     case "null":
@@ -173,18 +182,66 @@ var DECIMAL_PRELUDE_LINES = [
 ];
 
 // src/codegen-revive.ts
-var DECIMAL_COERCE_DECL = [
-  `const __dec = (v: unknown, path: string): Decimal => {`,
-  `    if (typeof v !== 'string') {`,
-  `        throw new TypeError(\`ContractKit: expected a decimal string at '\${path}', received \${typeof v} \u2014 decimals must be sent as quoted JSON strings.\`);`,
-  `    }`,
-  `    try {`,
-  `        return new Decimal(v);`,
-  `    } catch {`,
-  `        throw new TypeError(\`ContractKit: '\${v}' at '\${path}' is not a valid decimal.\`);`,
-  `    }`,
-  `};`
-];
+var COERCE_DECLS = {
+  "__dec(": [
+    `const __dec = (v: unknown, path: string): Decimal => {`,
+    `    if (typeof v !== 'string') {`,
+    `        throw new TypeError(\`ContractKit: expected a decimal string at '\${path}', received \${typeof v} \u2014 decimals must be sent as quoted JSON strings.\`);`,
+    `    }`,
+    `    try {`,
+    `        return new Decimal(v);`,
+    `    } catch {`,
+    `        throw new TypeError(\`ContractKit: '\${v}' at '\${path}' is not a valid decimal.\`);`,
+    `    }`,
+    `};`
+  ],
+  "__dt(": [
+    `const __dt = (v: unknown, path: string): DateTime => {`,
+    `    if (typeof v !== 'string') {`,
+    `        throw new TypeError(\`ContractKit: expected an ISO 8601 string at '\${path}', received \${typeof v}.\`);`,
+    `    }`,
+    `    const d = DateTime.fromISO(v);`,
+    `    if (!d.isValid) throw new TypeError(\`ContractKit: '\${v}' at '\${path}' is not a valid ISO 8601 datetime.\`);`,
+    `    return d;`,
+    `};`
+  ],
+  "__dtf(": [
+    `const __dtf = (v: unknown, path: string, fmt: string): DateTime => {`,
+    `    if (typeof v !== 'string') {`,
+    `        throw new TypeError(\`ContractKit: expected a string at '\${path}' in format \${fmt}, received \${typeof v}.\`);`,
+    `    }`,
+    `    const d = DateTime.fromFormat(v, fmt);`,
+    `    if (!d.isValid) throw new TypeError(\`ContractKit: '\${v}' at '\${path}' does not match format \${fmt}.\`);`,
+    `    return d;`,
+    `};`
+  ],
+  "__dur(": [
+    `const __dur = (v: unknown, path: string): Duration => {`,
+    `    if (typeof v !== 'string') {`,
+    `        throw new TypeError(\`ContractKit: expected an ISO 8601 duration string at '\${path}', received \${typeof v}.\`);`,
+    `    }`,
+    `    const d = Duration.fromISO(v);`,
+    `    if (!d.isValid) throw new TypeError(\`ContractKit: '\${v}' at '\${path}' is not a valid ISO 8601 duration.\`);`,
+    `    return d;`,
+    `};`
+  ]
+};
+var DECIMAL_COERCE_DECL = COERCE_DECLS["__dec("];
+function coerceDeclsFor(lines) {
+  const haystack = lines.join("\n");
+  return Object.entries(COERCE_DECLS).filter(([prefix]) => haystack.includes(prefix)).flatMap(([, decl]) => decl);
+}
+__name(coerceDeclsFor, "coerceDeclsFor");
+function coerceLuxonImports(lines) {
+  const haystack = lines.join("\n");
+  const needed = /* @__PURE__ */ new Set();
+  if (haystack.includes("__dt(") || haystack.includes("__dtf(")) needed.add("DateTime");
+  if (haystack.includes("__dur(")) needed.add("Duration");
+  return [
+    ...needed
+  ].sort();
+}
+__name(coerceLuxonImports, "coerceLuxonImports");
 function reviveFnName(model, variant = "base") {
   return `revive${model}${variant === "output" ? "Output" : ""}`;
 }
@@ -195,10 +252,17 @@ function applyCase(name, caseTransform) {
   return name.charAt(0).toUpperCase() + name.slice(1);
 }
 __name(applyCase, "applyCase");
+var DEFAULT_REVIVABLE_SCALARS = /* @__PURE__ */ new Set([
+  "decimal",
+  "date",
+  "time",
+  "datetime",
+  "duration"
+]);
 function typeReachesDecimal(type, opts) {
   switch (type.kind) {
     case "scalar":
-      return type.name === "decimal";
+      return (opts.revivableScalars ?? DEFAULT_REVIVABLE_SCALARS).has(type.name);
     case "ref":
       return opts.modelsWithDecimal.has(type.name);
     case "array":
@@ -220,6 +284,34 @@ function typeReachesDecimal(type, opts) {
   }
 }
 __name(typeReachesDecimal, "typeReachesDecimal");
+function scalarCoercion(type, slot, path, opts) {
+  if (!(opts.revivableScalars ?? DEFAULT_REVIVABLE_SCALARS).has(type.name)) return [];
+  switch (type.name) {
+    case "decimal":
+      return [
+        `${slot} = __dec(${slot}, '${path}');`
+      ];
+    case "datetime":
+      return [
+        `${slot} = __dt(${slot}, '${path}');`
+      ];
+    case "duration":
+      return [
+        `${slot} = __dur(${slot}, '${path}');`
+      ];
+    case "date":
+      return [
+        `${slot} = __dtf(${slot}, '${path}', '${type.format ?? "yyyy-MM-dd"}');`
+      ];
+    case "time":
+      return [
+        `${slot} = __dtf(${slot}, '${path}', '${type.format ?? "HH:mm:ss"}');`
+      ];
+    default:
+      return [];
+  }
+}
+__name(scalarCoercion, "scalarCoercion");
 var Scope = class Scope2 {
   static {
     __name(this, "Scope");
@@ -232,9 +324,7 @@ var Scope = class Scope2 {
 function emit(slot, type, path, opts, scope, variant) {
   switch (type.kind) {
     case "scalar":
-      return type.name === "decimal" ? [
-        `${slot} = __dec(${slot}, '${path}');`
-      ] : [];
+      return scalarCoercion(type, slot, path, opts);
     case "ref":
       return opts.modelsWithDecimal.has(type.name) ? [
         `${reviveRefName(type.name, opts, variant)}(${slot} as never);`
@@ -386,7 +476,7 @@ function renderOne(model, opts, variant) {
     const body2 = emit("__v[0]", model.type, model.name, opts, scope, variant);
     if (body2.length === 0) return [];
     return [
-      `/** Rehydrates every \`decimal\` in a ${typeName} from its wire string. Mutates and returns \`raw\`. */`,
+      `/** Rehydrates every wire-encoded scalar in a ${typeName} into its runtime type. Mutates and returns \`raw\`. */`,
       `export function ${fnName}(raw: ${typeName}): ${typeName} {`,
       `    const __v = [raw] as unknown[];`,
       ...body2.map((l) => `    ${l}`),
@@ -398,7 +488,7 @@ function renderOne(model, opts, variant) {
   const body = model.fields.flatMap((f) => typeReachesDecimal(f.type, opts) ? fieldStatements(obj, f, model.name, opts, scope, variant, model.outputCase) : []);
   if (body.length === 0) return [];
   return [
-    `/** Rehydrates every \`decimal\` in a ${typeName} from its wire string. Mutates and returns \`raw\`. */`,
+    `/** Rehydrates every wire-encoded scalar in a ${typeName} into its runtime type. Mutates and returns \`raw\`. */`,
     `export function ${fnName}(raw: ${typeName}): ${typeName} {`,
     `    const ${obj} = raw as unknown as Record<string, unknown>;`,
     ...body.map((l) => `    ${l}`),
@@ -459,8 +549,7 @@ function generateComments(model, outPath) {
   if (model.description) {
     for (const l of escapeJsDocLines(model.description)) lines.push(` * ${l}`);
   }
-  const relPath = outPath ? relative(dirname(outPath), model.loc.file) : model.loc.file;
-  lines.push(` * generated from [${model.name}](file://./${relPath}#L${model.loc.line})`);
+  lines.push(` * generated from ${sourceLink(model.name, outPath, model.loc.file, model.loc.line)}`);
   lines.push("*/");
   return lines;
 }
@@ -510,7 +599,7 @@ function generateContract(root, context) {
   }
   lines.push("");
   if (needsBinary) {
-    lines.push(`const _ZodBinary = z.custom<Buffer>((val) => Buffer.isBuffer(val), { error: 'Must be binary data' });`);
+    lines.push(context?.target === "server" ? `const _ZodBinary = z.custom<Buffer>((val) => Buffer.isBuffer(val), { error: 'Must be binary data' });` : `const _ZodBinary = z.custom<Blob>((val) => val instanceof Blob, { error: 'Must be binary data' });`);
   }
   if (needsDatetime) {
     lines.push(`const _ZodDatetime = z.preprocess((val) => typeof val === 'string' ? DateTime.fromISO(val) : val, z.custom<DateTime>((val) => val instanceof DateTime && val.isValid, { message: 'Must be in ISO 8601 format' }));`);
@@ -526,7 +615,6 @@ function generateContract(root, context) {
     lines.push(`const _ZodJson: z.ZodType<_JsonValue> = z.lazy(() => z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(_ZodJson), z.record(z.string(), _ZodJson)]));`);
   }
   if (needsBinary || needsDatetime || needsInterval || needsDecimal || needsJson) lines.push("");
-  const modelsWithWriteonly = new Set(root.models.filter((m) => m.fields.some((f) => f.visibility === "writeonly")).map((m) => m.name));
   const modelMap = new Map(root.models.map((m) => [
     m.name,
     m
@@ -538,7 +626,7 @@ function generateContract(root, context) {
   } : void 0;
   const bodyLines = [];
   for (const model of topoSortModels(root.models)) {
-    bodyLines.push(...generateModel(model, context?.currentOutPath, allModelsWithInput, modelsWithWriteonly, modelMap, allModelsWithOutput));
+    bodyLines.push(...generateModel(model, context?.currentOutPath, allModelsWithInput, modelMap, allModelsWithOutput));
     if (reviveOpts) {
       const revivers = renderReviveFunctions(model, reviveOpts);
       if (revivers.length > 0) {
@@ -548,8 +636,9 @@ function generateContract(root, context) {
     }
     bodyLines.push("");
   }
-  if (bodyLines.some((l) => l.includes("__dec("))) {
-    lines.push(...DECIMAL_COERCE_DECL);
+  const coerceDecls = coerceDeclsFor(bodyLines);
+  if (coerceDecls.length > 0) {
+    lines.push(...coerceDecls);
     lines.push("");
   }
   lines.push(...bodyLines);
@@ -579,13 +668,13 @@ function flattenFormatChain(model, modelMap) {
   };
 }
 __name(flattenFormatChain, "flattenFormatChain");
-function generateModel(model, outPath, modelsWithInput, modelsWithWriteonly, modelMap, modelsWithOutput) {
+function generateModel(model, outPath, modelsWithInput, modelMap, modelsWithOutput) {
   if (model.type) {
     return generateTypeAlias(model, outPath, modelsWithInput, modelsWithOutput);
   }
   const effective = modelMap ? flattenFormatChain(model, modelMap) : model;
   const needsInputSplit = effective.fields.some((f) => f.visibility !== "normal") || (modelsWithInput?.has(effective.name) ?? false);
-  const lines = needsInputSplit ? generateThreeSchemaModel(effective, outPath, modelsWithInput, modelsWithWriteonly, modelMap) : generateSimpleModel(effective, outPath);
+  const lines = needsInputSplit ? generateThreeSchemaModel(effective, outPath, modelsWithInput, modelMap) : generateSimpleModel(effective, outPath);
   if (modelsWithOutput?.has(effective.name)) {
     lines.push(`export type ${effective.name}Output = z.output<typeof ${effective.name}>;`);
   }
@@ -674,26 +763,13 @@ function collectEffectiveWritableFieldNames(modelName, modelMap) {
   return result;
 }
 __name(collectEffectiveWritableFieldNames, "collectEffectiveWritableFieldNames");
-function generateThreeSchemaModel(model, outPath, modelsWithInput, modelsWithWriteonly, modelMap) {
+function generateThreeSchemaModel(model, outPath, modelsWithInput, modelMap) {
   const lines = [];
   const name = model.name;
   lines.push(...generateComments(model, outPath));
   const wrapper = modeToWrapper(model.mode ?? "strict");
   const allFields = model.fields;
-  const hasWriteonly = allFields.some((f) => f.visibility === "writeonly");
   const bases = model.bases ?? [];
-  if (hasWriteonly) {
-    const baseBody = renderFields(allFields, model.mode);
-    if (bases.length > 0) {
-      const { head, tail } = buildExtendChain(bases, (b) => modelsWithWriteonly?.has(b) ? `${b}Base` : b);
-      lines.push(`const ${name}Base = ${head}${tail}.extend({`);
-    } else {
-      lines.push(`const ${name}Base = ${wrapper}({`);
-    }
-    lines.push(...baseBody.map((l) => `    ${l}`));
-    lines.push(`});`);
-    lines.push("");
-  }
   const readFields = allFields.filter((f) => f.visibility !== "writeonly");
   const readBody = renderFields(readFields, model.mode);
   if (bases.length > 0) {
@@ -790,10 +866,7 @@ function renderFieldsAsSnakeCase(fields, defaultMode) {
   });
 }
 __name(renderFieldsAsSnakeCase, "renderFieldsAsSnakeCase");
-function renderField(field, defaultMode) {
-  const lines = [];
-  if (field.deprecated) lines.push("/** @deprecated */");
-  let expr = renderType(field.type, void 0, defaultMode);
+function applyFieldModifiers(expr, field) {
   if (field.nullable) expr += ".nullable()";
   if (field.default !== void 0) {
     const dv = typeof field.default === "string" ? `"${escapeString(field.default)}"` : String(field.default);
@@ -802,6 +875,14 @@ function renderField(field, defaultMode) {
     expr += ".optional()";
   }
   if (field.description) expr += `.describe("${escapeString(field.description)}")`;
+  return expr;
+}
+__name(applyFieldModifiers, "applyFieldModifiers");
+function renderField(field, defaultMode) {
+  const lines = [];
+  if (field.deprecated) lines.push("/** @deprecated */");
+  let expr = renderType(field.type, void 0, defaultMode);
+  expr = applyFieldModifiers(expr, field);
   lines.push(`${quoteKey2(field.name)}: ${expr},`);
   return lines;
 }
@@ -855,6 +936,7 @@ function regexHasAnchor(source) {
   return backslashes % 2 === 0;
 }
 __name(regexHasAnchor, "regexHasAnchor");
+var NUMERIC_PREPROCESS = `(v) => (typeof v === 'string' && v.trim() !== '' ? Number(v) : v)`;
 function renderScalar(s) {
   switch (s.name) {
     case "string": {
@@ -866,17 +948,12 @@ function renderScalar(s) {
       if (s.regex) e += `.regex(${renderRegexLiteral(s.regex)})`;
       return e;
     }
-    case "number": {
-      let e = "z.coerce.number()";
-      if (s.min !== void 0) e += `.min(${s.min})`;
-      if (s.max !== void 0) e += `.max(${s.max})`;
-      return e;
-    }
+    case "number":
     case "int": {
-      let e = "z.coerce.number().int()";
-      if (s.min !== void 0) e += `.min(${s.min})`;
-      if (s.max !== void 0) e += `.max(${s.max})`;
-      return e;
+      let inner = s.name === "int" ? "z.number().int()" : "z.number()";
+      if (s.min !== void 0) inner += `.min(${s.min})`;
+      if (s.max !== void 0) inner += `.max(${s.max})`;
+      return `z.preprocess(${NUMERIC_PREPROCESS}, ${inner})`;
     }
     case "bigint": {
       let inner = "z.bigint()";
@@ -1107,14 +1184,7 @@ function renderInputField(field, modelsWithInput, defaultMode) {
   const lines = [];
   if (field.deprecated) lines.push("/** @deprecated */");
   let expr = renderInputType(field.type, modelsWithInput, defaultMode);
-  if (field.nullable) expr += ".nullable()";
-  if (field.default !== void 0) {
-    const dv = typeof field.default === "string" ? `"${escapeString(field.default)}"` : String(field.default);
-    expr += `.default(${dv})`;
-  } else if (field.optional) {
-    expr += ".optional()";
-  }
-  if (field.description) expr += `.describe("${escapeString(field.description)}")`;
+  expr = applyFieldModifiers(expr, field);
   lines.push(`${quoteKey2(field.name)}: ${expr},`);
   return lines;
 }
@@ -1167,14 +1237,7 @@ ${fieldLines}
 __name(renderQueryType, "renderQueryType");
 function renderQueryField(field, modelsWithInput, defaultMode) {
   let expr = field.type.kind === "array" ? renderQueryType(field.type, modelsWithInput, defaultMode) : modelsWithInput ? renderInputType(field.type, modelsWithInput, defaultMode) : renderType(field.type, void 0, defaultMode);
-  if (field.nullable) expr += ".nullable()";
-  if (field.default !== void 0) {
-    const dv = typeof field.default === "string" ? `"${escapeString(field.default)}"` : String(field.default);
-    expr += `.default(${dv})`;
-  } else if (field.optional) {
-    expr += ".optional()";
-  }
-  if (field.description) expr += `.describe("${escapeString(field.description)}")`;
+  expr = applyFieldModifiers(expr, field);
   return `${quoteKey2(field.name)}: ${expr},`;
 }
 __name(renderQueryField, "renderQueryField");
@@ -1371,8 +1434,8 @@ function resolveImportPath(refName, context) {
   if (context) {
     const refOutPath = context.modelOutPaths.get(refName);
     if (refOutPath) {
-      const fromDir = dirname(context.currentOutPath);
-      let rel = relative(fromDir, refOutPath);
+      const fromDir = dirname2(context.currentOutPath);
+      let rel = relative2(fromDir, refOutPath);
       rel = rel.replace(/\.ts$/, ".js");
       if (!rel.startsWith(".")) rel = "./" + rel;
       return rel;
@@ -1388,8 +1451,8 @@ function pascalToDotCase(name) {
 __name(pascalToDotCase, "pascalToDotCase");
 
 // src/codegen-operation.ts
-import { resolveModifiers, resolveSecurity, SECURITY_NONE, classifyContentType, emittedResponses } from "@contractkit/core";
-import { basename, dirname as dirname2, relative as relative2 } from "path";
+import { resolveModifiers, resolveSecurity, SECURITY_NONE, classifyContentType, emittedResponses, PATH_PARAM_RE_G, toIdentifier } from "@contractkit/core";
+import { basename, dirname as dirname3, relative as relative3 } from "path";
 function bodyParserToken(contentType) {
   switch (classifyContentType(contentType)) {
     case "urlencoded":
@@ -1468,8 +1531,7 @@ function generateOp(root, options = {}) {
   const lines = [];
   lines.push("");
   lines.push("/**");
-  const relFile = options.outPath ? relative2(dirname2(options.outPath), root.file) : root.file;
-  lines.push(` * generated from [${basename(root.file)}](file://./${relFile})`);
+  lines.push(` * generated from ${sourceLink(basename(root.file), options.outPath, root.file)}`);
   lines.push("*/");
   lines.push(`export const ${routerName} = ServerKitRouter();`);
   lines.push("");
@@ -1569,8 +1631,7 @@ function generateHandler(route, op, root, options) {
   if (desc) {
     for (const l of escapeJsDocLines(desc)) lines.push(` * ${l}`);
   }
-  const relFile = outPath ? relative2(dirname2(outPath), file) : file;
-  lines.push(` * from [${basename(file)}](file://./${relFile}#L${op.loc.line})`);
+  lines.push(` * from ${sourceLink(basename(file), outPath, file, op.loc.line)}`);
   const effectiveSecurity = resolveSecurity(route, op, root);
   if (effectiveSecurity === SECURITY_NONE) {
     lines.push(` * anonymous access, no security required`);
@@ -1580,7 +1641,7 @@ function generateHandler(route, op, root, options) {
   if (mods.includes("deprecated")) lines.push(` * @deprecated`);
   lines.push("*/");
   const method = op.method;
-  const path = route.path.replace(/\{(\w+)\}/g, ":$1");
+  const path = route.path.replace(PATH_PARAM_RE_G, (_m, name) => `:${toIdentifier(name)}`);
   const bodies = op.request?.bodies ?? [];
   const hasBody = bodies.length > 0;
   const isSingleMultipart = bodies.length === 1 && bodies[0].contentType === "multipart/form-data";
@@ -1679,7 +1740,7 @@ function generateSingleStatusResult(resp, op, className, call, options) {
     }
   }
   lines.push("");
-  lines.push(`    ctx.status = ${resp?.statusCode ?? op.responses[0]?.statusCode ?? 200};`);
+  lines.push(`    ctx.status = ${resp?.statusCode ?? 204};`);
   lines.push(...headerSetLines(respHeaders, "    "));
   if (bodies.length === 1) {
     lines.push(`    ctx.type = '${bodies[0].contentType}';`);
@@ -1833,7 +1894,7 @@ function buildArgs(route, op) {
   const args = [];
   if (route.params) {
     if (route.params.kind === "params") {
-      args.push(...route.params.nodes.map((p) => p.name));
+      args.push(...route.params.nodes.map((p) => toIdentifier(p.name)));
     } else {
       args.push("params");
     }
@@ -1963,18 +2024,17 @@ function generateParamValidation(source, ctxExpr, varName, mode, suffix = "", mo
     lines.push("");
   } else if (source.kind === "params") {
     if (source.nodes.length > 0) {
-      const lhs = varName === "params" ? `{ ${source.nodes.map((p) => p.name).join(", ")} }` : varName;
+      const isPathParams = ctxExpr === "ctx.params";
+      const bind = /* @__PURE__ */ __name((name) => isPathParams ? toIdentifier(name) : name, "bind");
+      const lhs = varName === "params" ? `{ ${source.nodes.map((p) => bind(p.name)).join(", ")} }` : varName;
       lines.push(`    const ${lhs} = await parseAndValidate(`);
       lines.push(`        ${ctxExpr},`);
       lines.push(`        ${modeToWrapper(mode)}({`);
       for (const param of source.nodes) {
-        const key = isValidIdentifier2(param.name) ? param.name : `'${param.name}'`;
-        if (isQuery && param.type.kind === "array") {
-          const inner = renderType(param.type);
-          lines.push(`            ${key}: z.preprocess((v) => typeof v === 'string' ? v.split(',') : v, ${inner}),`);
-        } else {
-          lines.push(`            ${key}: ${renderType(param.type)},`);
-        }
+        const bound = bind(param.name);
+        const key = isValidIdentifier2(bound) ? bound : `'${bound}'`;
+        const base = isQuery ? renderQueryType(param.type, modelsWithInput) : renderInputType(param.type, modelsWithInput);
+        lines.push(`            ${key}: ${applyFieldModifiers(base, param)},`);
       }
       lines.push(`        })${suffix},`);
       lines.push(`    );`);
@@ -2004,9 +2064,9 @@ function generateTypeImports(types, opFile, options) {
         unresolved.push(type);
       }
     }
-    const fromDir = dirname2(outPath);
+    const fromDir = dirname3(outPath);
     for (const [typeOutPath, names] of byFile) {
-      let rel = relative2(fromDir, typeOutPath);
+      let rel = relative3(fromDir, typeOutPath);
       rel = rel.replace(/\.ts$/, ".js");
       if (!rel.startsWith(".")) rel = "./" + rel;
       lines.push(`import { ${names.sort().join(", ")} } from '${rel}';`);
@@ -2230,11 +2290,11 @@ function deriveTypeImportPath(file, template) {
 __name(deriveTypeImportPath, "deriveTypeImportPath");
 
 // src/index.ts
-import { runIncrementalCodegen, parseIncrementalManifest, emptyIncrementalManifest, serializeIncrementalManifest, hashFingerprint, collectTransitiveModelRefs, computeModelsWithCaseTransform, computeModelsWithDecimal } from "@contractkit/core";
+import { runIncrementalCodegen, parseIncrementalManifest, emptyIncrementalManifest, serializeIncrementalManifest, hashFingerprint, collectTransitiveModelRefs, computeModelsWithCaseTransform, computeModelsWithScalar } from "@contractkit/core";
 
 // src/codegen-sdk.ts
-import { resolveModifiers as resolveModifiers2, isJsonMime, classifyContentType as classifyContentType2, observableResponses, thrownResponses } from "@contractkit/core";
-import { basename as basename2, dirname as dirname3, relative as relative3 } from "path";
+import { resolveModifiers as resolveModifiers2, isJsonMime, classifyContentType as classifyContentType2, observableResponses, thrownResponses, PATH_PARAM_RE_G as PATH_PARAM_RE_G2, toIdentifier as toIdentifier2 } from "@contractkit/core";
+import { basename as basename2, dirname as dirname4, relative as relative4 } from "path";
 function jsonOrFormSerialize(varName, contentType) {
   if (contentType === "application/x-www-form-urlencoded") {
     return `new URLSearchParams(${varName} as unknown as Record<string, string>).toString()`;
@@ -2304,7 +2364,6 @@ function generateSdk(root, options = {}) {
       const mods = resolveModifiers2(route, op);
       if (!includeInternal && mods.includes("internal")) continue;
       classBody.push("");
-      if (mods.includes("deprecated")) classBody.push("    /** @deprecated */");
       classBody.push(...generateMethod(route, op, root.file, options, inlineRevivers));
     }
   }
@@ -2312,19 +2371,29 @@ function generateSdk(root, options = {}) {
     ...inlineRevivers.values()
   ].flat();
   const decimalPrelude = decimalPreludeFor(inlineReviverDecls);
-  if (types.length > 0) {
-    lines.push(...generateTypeImports2(types, root.file, options, usedRevivers(classBody)));
+  const errorAliases = generateErrorBodyAliases(root, options);
+  const referenced = referencedTypes(types, [
+    ...classBody,
+    ...errorAliases,
+    ...inlineReviverDecls
+  ]);
+  if (referenced.length > 0) {
+    lines.push(...generateTypeImports2(referenced, root.file, options, usedRevivers(classBody)));
   }
   lines.push(...decimalPrelude.imports);
+  const headerLuxon = headerLuxonImport(classBody, decimalPrelude.imports);
+  if (headerLuxon) lines.push(headerLuxon);
   if (options.sdkOptionsPath && options.outPath) {
-    let rel = relative3(dirname3(options.outPath), options.sdkOptionsPath);
+    let rel = relative4(dirname4(options.outPath), options.sdkOptionsPath);
     rel = rel.replace(/\.ts$/, ".js");
     if (!rel.startsWith(".")) rel = "./" + rel;
     const jsonImport = sdkNeedsJson(root, includeInternal) ? ", JsonValue" : "";
     lines.push(`import type { SdkFetch${jsonImport} } from '${rel}';`);
     const valueImports = [];
     if (sdkNeedsBigIntReplacer(root, includeInternal)) valueImports.push("bigIntReplacer");
-    if (sdkNeedsBigIntReviver(root, includeInternal)) valueImports.push("parseJson");
+    if (sdkParsesJsonResponse(root, includeInternal)) {
+      valueImports.push(sdkResponsesUseBigInt(root, options, includeInternal) ? "parseJsonWithBigInt as parseJson" : "parseJson");
+    }
     if (sdkNeedsQueryString(root, includeInternal)) valueImports.push("buildQueryString");
     if (sdkNeedsReadContentType(root, includeInternal)) valueImports.push("readContentType");
     if (valueImports.length > 0) {
@@ -2401,14 +2470,13 @@ function generateSdk(root, options = {}) {
     lines.push("}");
     lines.push("");
     lines.push("export async function parseJson<T>(res: Response): Promise<T> {");
-    lines.push("    return JSON.parse(await res.text(), bigIntReviver) as T;");
+    lines.push(sdkResponsesUseBigInt(root, options, includeInternal) ? "    return JSON.parse(await res.text(), bigIntReviver) as T;" : "    return JSON.parse(await res.text()) as T;");
     lines.push("}");
   }
   if (sdkNeedsJson(root, includeInternal) && !(options.sdkOptionsPath && options.outPath)) {
     lines.push(JSON_VALUE_TYPE_DECL);
   }
   lines.push("");
-  const errorAliases = generateErrorBodyAliases(root, options);
   if (errorAliases.length > 0) {
     lines.push(...errorAliases);
     lines.push("");
@@ -2422,8 +2490,7 @@ function generateSdk(root, options = {}) {
     lines.push(...decl);
   }
   lines.push("/**");
-  const relFile = options.outPath ? relative3(dirname3(options.outPath), root.file) : root.file;
-  lines.push(` * generated from [${basename2(root.file)}](file://./${relFile})`);
+  lines.push(` * generated from ${sourceLink(basename2(root.file), options.outPath, root.file)}`);
   lines.push(" */");
   lines.push(`export class ${clientClassName} {`);
   lines.push("    constructor(private fetch: SdkFetch) {}");
@@ -2443,7 +2510,6 @@ function generateClientMethods(root, options) {
       const mods = resolveModifiers2(route, op);
       if (!includeInternal && mods.includes("internal")) continue;
       lines.push("");
-      if (mods.includes("deprecated")) lines.push("    /** @deprecated */");
       lines.push(...generateMethod(route, op, root.file, options, inlineRevivers));
       methodNames.push(deriveMethodName(op, route));
     }
@@ -2473,22 +2539,45 @@ function generateClientMethods(root, options) {
 }
 __name(generateClientMethods, "generateClientMethods");
 function decimalPreludeFor(declLines) {
-  if (!declLines.some((l) => l.includes("__dec("))) return {
+  const decls = coerceDeclsFor(declLines);
+  if (decls.length === 0) return {
     imports: [],
     decls: []
   };
+  const imports = [];
+  const preamble = [];
+  if (declLines.some((l) => l.includes("__dec("))) {
+    imports.push(DECIMAL_IMPORT);
+    preamble.push(DECIMAL_CONFIG_LINE, "");
+  }
+  const luxon = coerceLuxonImports(declLines);
+  if (luxon.length > 0) imports.push(`import { ${luxon.join(", ")} } from 'luxon';`);
   return {
-    imports: [
-      DECIMAL_IMPORT
-    ],
+    imports,
     decls: [
-      DECIMAL_CONFIG_LINE,
-      "",
-      ...DECIMAL_COERCE_DECL
+      ...preamble,
+      ...decls
     ]
   };
 }
 __name(decimalPreludeFor, "decimalPreludeFor");
+function headerLuxonImport(methodLines, existingImports) {
+  if (existingImports.some((l) => l.includes("from 'luxon'"))) return void 0;
+  const needed = [
+    "DateTime",
+    "Duration"
+  ].filter((c) => methodLines.some((l) => l.includes(`${c}.from`)));
+  return needed.length > 0 ? `import { ${needed.join(", ")} } from 'luxon';` : void 0;
+}
+__name(headerLuxonImport, "headerLuxonImport");
+function referencedTypes(types, emitted) {
+  const haystack = emitted.join("\n");
+  return types.filter((t) => {
+    const escaped = t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?<![A-Za-z0-9_$])${escaped}(?![A-Za-z0-9_$])`).test(haystack);
+  });
+}
+__name(referencedTypes, "referencedTypes");
 function usedRevivers(lines) {
   const found = /* @__PURE__ */ new Set();
   for (const m of lines.join("\n").matchAll(/\brevive[A-Z]\w*/g)) found.add(m[0]);
@@ -2507,6 +2596,7 @@ function generateMethod(route, op, file, options, inlineRevivers) {
   } : void 0;
   const lines = [];
   const methodName = deriveMethodName(op, route);
+  const where = `${op.method.toUpperCase()} ${route.path}`;
   const mRevive = hint(revive, `${methodName.charAt(0).toUpperCase()}${methodName.slice(1)}`);
   const httpMethod = op.method.toUpperCase();
   const { modelsWithInput, modelsWithOutput } = options;
@@ -2538,11 +2628,13 @@ function generateMethod(route, op, file, options, inlineRevivers) {
   const expectStatuses = observable.filter((r) => r.statusCode < 200 || r.statusCode >= 300).map((r) => r.statusCode);
   const desc = op.description ?? route.description;
   const errorBodyName = thrown.some((r) => r.bodies.length > 0) ? errorBodyTypeName(route, op) : void 0;
-  if (op.name || desc || errorBodyName) {
+  const deprecated = resolveModifiers2(route, op).includes("deprecated");
+  if (op.name || desc || errorBodyName || deprecated) {
     const tags = [];
     if (op.name) tags.push(`@name ${op.name}`);
     if (desc) tags.push(`@description ${desc}`);
     if (errorBodyName) tags.push(`@throws {SdkError<${errorBodyName}>} on ${thrown.map((r) => r.statusCode).join(", ")}`);
+    if (deprecated) tags.push("@deprecated");
     const contentLines = tags.flatMap((t) => escapeJsDocLines(t));
     if (contentLines.length === 1) {
       lines.push(`    /** ${contentLines[0]} */`);
@@ -2635,15 +2727,15 @@ function generateMethod(route, op, file, options, inlineRevivers) {
     lines.push(`        switch (result.status) {`);
     for (const resp of rest) {
       lines.push(`            case ${resp.statusCode}:`);
-      lines.push(...sdkReturnLines(resp, modelsWithOutput, "                ", true, mRevive));
+      lines.push(...sdkReturnLines(resp, modelsWithOutput, "                ", true, mRevive, where));
     }
     lines.push(`            default:`);
-    lines.push(...sdkReturnLines(fallback, modelsWithOutput, "                ", true, mRevive));
+    lines.push(...sdkReturnLines(fallback, modelsWithOutput, "                ", true, mRevive, where));
     lines.push(`        }`);
   } else if (primaryBodies.length > 1) {
-    lines.push(...sdkReturnLines(primaryResponse, modelsWithOutput, "        ", false, mRevive));
+    lines.push(...sdkReturnLines(primaryResponse, modelsWithOutput, "        ", false, mRevive, where));
   } else if (hasRespHeaders) {
-    const headerEntries = sdkHeaderEntries(respHeaders);
+    const headerEntries = sdkHeaderEntries(respHeaders, where);
     if (isVoid) {
       lines.push(`        return { headers: { ${headerEntries} } };`);
     } else {
@@ -2687,6 +2779,7 @@ function reviveExprFor(bodyType, ctx) {
   if (!ctx || ctx.modelsWithDecimal.size === 0) return null;
   const opts = {
     modelsWithDecimal: ctx.modelsWithDecimal,
+    revivableScalars: ctx.revivableScalars,
     modelsWithOutput: ctx.modelsWithOutput,
     modelMap: ctx.modelMap
   };
@@ -2722,8 +2815,48 @@ function renderSdkHeadersShape(headers, modelsWithOutput) {
   return `{ ${fields.join("; ")} }`;
 }
 __name(renderSdkHeadersShape, "renderSdkHeadersShape");
-function sdkHeaderEntries(headers) {
-  return headers.map((h) => `${quoteKey(headerNameToProperty(h.name))}: result.headers.get('${h.name}') ?? undefined`).join(", ");
+function sdkHeaderEntry(h, where) {
+  const raw = `result.headers.get('${h.name}')`;
+  const key = quoteKey(headerNameToProperty(h.name));
+  const scalar = h.type.kind === "scalar" ? h.type.name : void 0;
+  const convert = /* @__PURE__ */ __name((expr) => `${key}: ${h.optional ? `${raw} === null ? undefined : ${expr(`${raw}!`)}` : expr(`${raw}!`)}`, "convert");
+  switch (scalar) {
+    case "string":
+    case "email":
+    case "url":
+    case "uuid":
+    case "interval":
+    case "unknown":
+      return `${key}: ${raw}${h.optional ? " ?? undefined" : "!"}`;
+    // Temporals are Luxon objects since the SDK started reviving them, so the shape
+    // `renderOutputTsType` produces says `DateTime` and the raw string no longer satisfies it.
+    // The format for date and time comes from the contract, as it does in the reviver.
+    case "datetime":
+      return convert((v) => `DateTime.fromISO(${v})`);
+    case "duration":
+      return convert((v) => `Duration.fromISO(${v})`);
+    case "date":
+      return convert((v) => `DateTime.fromFormat(${v}, '${h.type.kind === "scalar" && h.type.format || "yyyy-MM-dd"}')`);
+    case "time":
+      return convert((v) => `DateTime.fromFormat(${v}, '${h.type.kind === "scalar" && h.type.format || "HH:mm:ss"}')`);
+    case "number":
+    case "int":
+      return `${key}: ${h.optional ? `${raw} === null ? undefined : Number(${raw})` : `Number(${raw})`}`;
+    case "boolean":
+      return `${key}: ${h.optional ? `${raw} === null ? undefined : ${raw} === 'true'` : `${raw} === 'true'`}`;
+    case "bigint":
+      return convert((v) => `BigInt(${v})`);
+    default:
+      throw new Error(`Response header '${h.name}' on ${where} is declared as ${describeHeaderType(h.type)}, which cannot be read from an HTTP header. Header values arrive as strings \u2014 declare it as string, email, url, uuid, a date/time type, int, number, boolean or bigint.`);
+  }
+}
+__name(sdkHeaderEntry, "sdkHeaderEntry");
+function describeHeaderType(type) {
+  return type.kind === "scalar" ? `the '${type.name}' scalar` : type.kind === "ref" ? `the model '${type.name}'` : `${type.kind === "array" ? "an" : "a"} ${type.kind}`;
+}
+__name(describeHeaderType, "describeHeaderType");
+function sdkHeaderEntries(headers, where) {
+  return headers.map((h) => sdkHeaderEntry(h, where)).join(", ");
 }
 __name(sdkHeaderEntries, "sdkHeaderEntries");
 function sdkResponseMembers(resp, modelsWithOutput, includeStatus) {
@@ -2763,14 +2896,14 @@ function sdkResponseMembers(resp, modelsWithOutput, includeStatus) {
   ].join("; ")} }`);
 }
 __name(sdkResponseMembers, "sdkResponseMembers");
-function sdkReturnLines(resp, modelsWithOutput, indent, includeStatus, revive) {
+function sdkReturnLines(resp, modelsWithOutput, indent, includeStatus, revive, where) {
   const bodies = resp.bodies;
   const headers = resp.headers ?? [];
   const leading = includeStatus ? [
     `status: ${resp.statusCode}`
   ] : [];
   const trailing = headers.length > 0 ? [
-    `headers: { ${sdkHeaderEntries(headers)} }`
+    `headers: { ${sdkHeaderEntries(headers, where)} }`
   ] : [];
   if (bodies.length === 0) {
     return [
@@ -2855,9 +2988,11 @@ function generateErrorBodyAliases(root, options) {
   return lines;
 }
 __name(generateErrorBodyAliases, "generateErrorBodyAliases");
-function buildUrlExpression(path, _) {
-  return path.replace(/\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g, (_match, name) => {
-    return `\${encodeURIComponent(${name})}`;
+function buildUrlExpression(path, params) {
+  return path.replace(PATH_PARAM_RE_G2, (_m, name) => {
+    if (!params || params.kind === "params") return `\${encodeURIComponent(${toIdentifier2(name)})}`;
+    const access = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? `params.${name}` : `params[${JSON.stringify(name)}]`;
+    return `\${encodeURIComponent(String(${access}))}`;
   });
 }
 __name(buildUrlExpression, "buildUrlExpression");
@@ -2867,7 +3002,7 @@ function buildMethodParams(route, op, modelsWithInput) {
     if (route.params.kind === "params") {
       for (const p of route.params.nodes) {
         params.push({
-          name: p.name,
+          name: toIdentifier2(p.name),
           type: renderInputTsType(p.type, modelsWithInput),
           optional: false
         });
@@ -2951,55 +3086,44 @@ function buildMethodParams(route, op, modelsWithInput) {
       optional: false
     });
   }
-  if (op.query) {
-    if (op.query.kind === "params") {
-      const fields = op.query.nodes.map((p) => `${quoteKey(p.name)}?: ${renderInputTsType(p.type, modelsWithInput)}`).join("; ");
-      params.push({
-        name: "query",
-        type: `{ ${fields} }`,
-        optional: true
-      });
-    } else if (op.query.kind === "ref") {
-      const typeName = modelsWithInput?.has(op.query.name) ? `${op.query.name}Input` : op.query.name;
-      params.push({
-        name: "query",
-        type: typeName,
-        optional: true
-      });
-    } else {
-      params.push({
-        name: "query",
-        type: renderInputTsType(op.query.node, modelsWithInput),
-        optional: true
-      });
-    }
+  if (op.query) params.push(inlineArgParam("query", op.query, modelsWithInput));
+  if (op.headers) params.push(inlineArgParam("customHeaders", op.headers, modelsWithInput));
+  return normaliseOptionalOrder(params);
+}
+__name(buildMethodParams, "buildMethodParams");
+function inlineArgParam(name, source, modelsWithInput) {
+  if (source.kind === "params") {
+    const isOptional = /* @__PURE__ */ __name((p) => Boolean(p.optional) || p.default !== void 0, "isOptional");
+    const fields = source.nodes.map((p) => `${quoteKey(p.name)}${isOptional(p) ? "?" : ""}: ${renderInputTsType(p.type, modelsWithInput)}`).join("; ");
+    return {
+      name,
+      type: `{ ${fields} }`,
+      optional: source.nodes.every(isOptional)
+    };
   }
-  if (op.headers) {
-    if (op.headers.kind === "params") {
-      const fields = op.headers.nodes.map((p) => `${quoteKey(p.name)}?: ${renderInputTsType(p.type, modelsWithInput)}`).join("; ");
-      params.push({
-        name: "customHeaders",
-        type: `{ ${fields} }`,
-        optional: true
-      });
-    } else if (op.headers.kind === "ref") {
-      const typeName = modelsWithInput?.has(op.headers.name) ? `${op.headers.name}Input` : op.headers.name;
-      params.push({
-        name: "customHeaders",
-        type: typeName,
-        optional: true
-      });
-    } else {
-      params.push({
-        name: "customHeaders",
-        type: renderInputTsType(op.headers.node, modelsWithInput),
-        optional: true
-      });
-    }
+  if (source.kind === "ref") {
+    const typeName = modelsWithInput?.has(source.name) ? `${source.name}Input` : source.name;
+    return {
+      name,
+      type: typeName,
+      optional: true
+    };
   }
-  return params;
+  return {
+    name,
+    type: renderInputTsType(source.node, modelsWithInput),
+    optional: true
+  };
 }
-__name(buildMethodParams, "buildMethodParams");
+__name(inlineArgParam, "inlineArgParam");
+function normaliseOptionalOrder(params) {
+  const lastRequired = params.reduce((last, p, i) => p.optional ? last : i, -1);
+  return params.map((p, i) => i < lastRequired ? {
+    ...p,
+    optional: false
+  } : p);
+}
+__name(normaliseOptionalOrder, "normaliseOptionalOrder");
 function deriveMethodName(op, route) {
   if (op.sdk) return op.sdk;
   if (op.name) return nameToMethodName(op.name);
@@ -3215,7 +3339,7 @@ function sdkNeedsBigIntReplacer(root, includeInternal = false) {
   return false;
 }
 __name(sdkNeedsBigIntReplacer, "sdkNeedsBigIntReplacer");
-function sdkNeedsBigIntReviver(root, includeInternal = false) {
+function sdkParsesJsonResponse(root, includeInternal = false) {
   for (const route of root.routes) {
     for (const op of route.operations) {
       if (!includeInternal && resolveModifiers2(route, op).includes("internal")) continue;
@@ -3226,7 +3350,44 @@ function sdkNeedsBigIntReviver(root, includeInternal = false) {
   }
   return false;
 }
-__name(sdkNeedsBigIntReviver, "sdkNeedsBigIntReviver");
+__name(sdkParsesJsonResponse, "sdkParsesJsonResponse");
+function sdkResponsesUseBigInt(root, options, includeInternal = false) {
+  const tainted = options.modelsWithBigInt;
+  const reachesBigInt = /* @__PURE__ */ __name((type) => {
+    switch (type.kind) {
+      case "ref":
+        return tainted?.has(type.name) ?? false;
+      case "array":
+        return reachesBigInt(type.item);
+      case "lazy":
+        return reachesBigInt(type.inner);
+      case "tuple":
+        return type.items.some(reachesBigInt);
+      case "record":
+        return reachesBigInt(type.value);
+      case "union":
+      case "discriminatedUnion":
+      case "intersection":
+        return type.members.some(reachesBigInt);
+      case "inlineObject":
+        return type.fields.some((f) => reachesBigInt(f.type));
+      default:
+        return typeNeedsScalar(type, "bigint");
+    }
+  }, "reachesBigInt");
+  for (const route of root.routes) {
+    for (const op of route.operations) {
+      if (!includeInternal && resolveModifiers2(route, op).includes("internal")) continue;
+      for (const resp of op.responses) {
+        for (const body of resp.bodies) {
+          if (classifyContentType2(body.contentType) === "json" && reachesBigInt(body.bodyType)) return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+__name(sdkResponsesUseBigInt, "sdkResponsesUseBigInt");
 function sdkNeedsJson(root, includeInternal = false) {
   for (const route of root.routes) {
     for (const op of route.operations) {
@@ -3291,9 +3452,9 @@ function generateTypeImports2(types, opFile, options, revivers = []) {
         unresolved.push(type);
       }
     }
-    const fromDir = dirname3(outPath);
+    const fromDir = dirname4(outPath);
     for (const [typeOutPath, names] of byFile) {
-      let rel = relative3(fromDir, typeOutPath);
+      let rel = relative4(fromDir, typeOutPath);
       rel = rel.replace(/\.ts$/, ".js");
       if (!rel.startsWith(".")) rel = "./" + rel;
       lines.push(`import type { ${names.sort().join(", ")} } from '${rel}';`);
@@ -3413,7 +3574,20 @@ function generateSdkOptions() {
     "    return qs ? `?${qs}` : '';",
     "}",
     "",
+    "/**",
+    " * Read a JSON response body.",
+    " *",
+    " * No reviver: `bigIntReviver` matches any string of the form `123n` anywhere in the",
+    " * document, so a contract with no bigint field would still have a legitimate string like",
+    ' * "123n" silently turned into a BigInt. Clients whose contracts do use bigint import',
+    " * `parseJsonWithBigInt` under this name instead.",
+    " */",
     "export async function parseJson<T>(res: Response): Promise<T> {",
+    "    return JSON.parse(await res.text()) as T;",
+    "}",
+    "",
+    "/** `parseJson` for contracts that declare a bigint, applying the `123n` reviver. */",
+    "export async function parseJsonWithBigInt<T>(res: Response): Promise<T> {",
     "    return JSON.parse(await res.text(), bigIntReviver) as T;",
     "}",
     ""
@@ -3500,6 +3674,7 @@ function generateAreaClient(input) {
   const unresolvedTypes = /* @__PURE__ */ new Set();
   let needsJson = false;
   let needsBigIntReplacer = false;
+  let needsParseJson = false;
   let needsBigIntReviver = false;
   let needsQueryString = false;
   let needsReadContentType = false;
@@ -3518,27 +3693,32 @@ function generateAreaClient(input) {
     for (const alias of generateErrorBodyAliases(inline.root, inline.codegenOptions)) collectedErrorAliases.add(alias);
     if (sdkNeedsJson(inline.root, includeInternal)) needsJson = true;
     if (sdkNeedsBigIntReplacer(inline.root, includeInternal)) needsBigIntReplacer = true;
-    if (sdkNeedsBigIntReviver(inline.root, includeInternal)) needsBigIntReviver = true;
+    if (sdkParsesJsonResponse(inline.root, includeInternal)) needsParseJson = true;
+    if (sdkResponsesUseBigInt(inline.root, inline.codegenOptions, includeInternal)) needsBigIntReviver = true;
     if (sdkNeedsQueryString(inline.root, includeInternal)) needsQueryString = true;
     if (sdkNeedsReadContentType(inline.root, includeInternal)) needsReadContentType = true;
     for (const reviver of usedRevivers(methodLines)) {
       const stem = reviver.replace(/^revive/, "");
       const modelOut = inline.codegenOptions.modelOutPaths?.get(stem) ?? inline.codegenOptions.modelOutPaths?.get(stem.replace(/Output$/, ""));
       if (!modelOut) continue;
-      let rel = relative3(dirname3(outPath), modelOut).replace(/\.ts$/, ".js");
+      let rel = relative4(dirname4(outPath), modelOut).replace(/\.ts$/, ".js");
       if (!rel.startsWith(".")) rel = "./" + rel;
       const set = reviversByImportPath.get(rel) ?? /* @__PURE__ */ new Set();
       set.add(reviver);
       reviversByImportPath.set(rel, set);
     }
-    const typesForFile = collectTypes2(inline.root, inline.codegenOptions.modelsWithInput, inline.codegenOptions.modelsWithOutput, includeInternal);
+    const typesForFile = referencedTypes(collectTypes2(inline.root, inline.codegenOptions.modelsWithInput, inline.codegenOptions.modelsWithOutput, includeInternal), [
+      ...methodLines,
+      ...generateErrorBodyAliases(inline.root, inline.codegenOptions),
+      ...preludeLines
+    ]);
     const { modelOutPaths } = inline.codegenOptions;
     if (modelOutPaths) {
-      const fromDir = dirname3(outPath);
+      const fromDir = dirname4(outPath);
       for (const t of typesForFile) {
         const typeOutPath = modelOutPaths.get(t);
         if (typeOutPath) {
-          let rel = relative3(fromDir, typeOutPath).replace(/\.ts$/, ".js");
+          let rel = relative4(fromDir, typeOutPath).replace(/\.ts$/, ".js");
           if (!rel.startsWith(".")) rel = "./" + rel;
           const set = typesByImportPath.get(rel) ?? /* @__PURE__ */ new Set();
           set.add(t);
@@ -3549,14 +3729,14 @@ function generateAreaClient(input) {
       }
     }
   }
-  let sdkOptionsRel = relative3(dirname3(outPath), sdkOptionsPath).replace(/\.ts$/, ".js");
+  let sdkOptionsRel = relative4(dirname4(outPath), sdkOptionsPath).replace(/\.ts$/, ".js");
   if (!sdkOptionsRel.startsWith(".")) sdkOptionsRel = "./" + sdkOptionsRel;
   const lines = [];
   const jsonImport = needsJson ? ", JsonValue" : "";
   lines.push(`import type { SdkFetch${jsonImport} } from '${sdkOptionsRel}';`);
   const valueImports = [];
   if (needsBigIntReplacer) valueImports.push("bigIntReplacer");
-  if (needsBigIntReviver) valueImports.push("parseJson");
+  if (needsParseJson) valueImports.push(needsBigIntReviver ? "parseJsonWithBigInt as parseJson" : "parseJson");
   if (needsQueryString) valueImports.push("buildQueryString");
   if (needsReadContentType) valueImports.push("readContentType");
   if (valueImports.length > 0) {
@@ -3580,6 +3760,8 @@ function generateAreaClient(input) {
     lines.push(`import type { ${t} } from './${pascalToDotCase(t)}.js';`);
   }
   if (areaNeedsDecimalImport) lines.push(DECIMAL_IMPORT);
+  const areaHeaderLuxon = headerLuxonImport(collectedMethodLines, collectedRevivePrelude);
+  if (areaHeaderLuxon) lines.push(areaHeaderLuxon);
   const importedClients = /* @__PURE__ */ new Set();
   for (const sc of subareaClients) {
     const key = `${sc.client.className}|${sc.client.importPath}`;
@@ -3655,7 +3837,6 @@ function generateSdkAggregator(input) {
 __name(generateSdkAggregator, "generateSdkAggregator");
 
 // src/codegen-plain-types.ts
-import { relative as relative4, dirname as dirname4 } from "path";
 import { computeModelsWithOutput, collectExternalOutputRefs } from "@contractkit/core";
 function generatePlainTypes(root, context) {
   const target = context?.target ?? "client";
@@ -3684,6 +3865,10 @@ function generatePlainTypes(root, context) {
   ].sort();
   const needsDecimal = rootNeedsScalar(root, "decimal") || (context?.emitRevivers && context.modelsWithDecimal ? root.models.some((m) => context.modelsWithDecimal.has(m.name)) : false);
   if (needsDecimal) lines.push(DECIMAL_IMPORT);
+  const luxonImports = [];
+  if (rootNeedsScalar(root, "date") || rootNeedsScalar(root, "time") || rootNeedsScalar(root, "datetime")) luxonImports.push("DateTime");
+  if (rootNeedsScalar(root, "duration")) luxonImports.push("Duration");
+  if (luxonImports.length > 0) lines.push(`import { ${luxonImports.join(", ")} } from 'luxon';`);
   for (const ref of allExternalRefs) {
     const importPath = resolveImportPath(ref, context);
     lines.push(`import type { ${ref} } from '${importPath}';`);
@@ -3725,8 +3910,9 @@ function generatePlainTypes(root, context) {
     lines.push("");
     lines.push(DECIMAL_CONFIG_LINE);
   }
-  if (bodyLines.some((l) => l.includes("__dec("))) {
-    lines.push(...DECIMAL_COERCE_DECL);
+  const coerceDecls = coerceDeclsFor(bodyLines);
+  if (coerceDecls.length > 0) {
+    lines.push(...coerceDecls);
     lines.push("");
   }
   lines.push(...bodyLines);
@@ -3772,8 +3958,7 @@ function generateComments2(model, outPath) {
   if (model.description) {
     for (const l of escapeJsDocLines(model.description)) lines.push(` * ${l}`);
   }
-  const relPath = outPath ? relative4(dirname4(outPath), model.loc.file) : model.loc.file;
-  lines.push(` * generated from [${model.name}](file://./${relPath}#L${model.loc.line})`);
+  lines.push(` * generated from ${sourceLink(model.name, outPath, model.loc.file, model.loc.line)}`);
   lines.push(" */");
   return lines;
 }
@@ -3919,7 +4104,7 @@ function renderOutputField(field, outputCase, modelsWithOutput, target) {
 __name(renderOutputField, "renderOutputField");
 
 // src/codegen-mcp.ts
-import { resolveModifiers as resolveModifiers3, emittedResponses as emittedResponses2 } from "@contractkit/core";
+import { resolveModifiers as resolveModifiers3, emittedResponses as emittedResponses2, toIdentifier as toIdentifier3 } from "@contractkit/core";
 import { basename as basename3, dirname as dirname5, relative as relative5 } from "path";
 function mcpConfig(op) {
   return op.mcp && typeof op.mcp === "object" ? op.mcp : void 0;
@@ -3976,7 +4161,7 @@ function buildArgsProps(route, op, modelsWithInput) {
     if (route.params.kind === "params") {
       for (const node of route.params.nodes) {
         props.push({
-          key: node.name,
+          key: toIdentifier3(node.name),
           expr: renderInputType(node.type, modelsWithInput),
           optional: false
         });
@@ -4205,9 +4390,8 @@ function renderToolClass(plan, file, options) {
   const { route, op, toolName, className, argsConstName } = plan;
   const cfg = mcpConfig(op);
   const lines = [];
-  const relFile = options.outPath ? relative5(dirname5(options.outPath), file) : file;
   lines.push("/**");
-  lines.push(` * from [${basename3(file)}](file://./${relFile}#L${op.loc.line})`);
+  lines.push(` * from ${sourceLink(basename3(file), options.outPath, file, op.loc.line)}`);
   lines.push(" */");
   lines.push("@Injectable()");
   lines.push(`export class ${className} implements McpToolHandler {`);
@@ -4231,7 +4415,8 @@ function renderToolClass(plan, file, options) {
   const callArgs = buildArgs(route, op);
   const isVoid = !primaryResponseBody(op);
   const structured = !!outExpr;
-  lines.push("    async handle(args: Record<string, unknown>, _context: McpToolContext): Promise<CallToolResult> {");
+  const argsParam = destructure.length > 0 ? "args" : "_args";
+  lines.push(`    async handle(${argsParam}: Record<string, unknown>, _context: McpToolContext): Promise<CallToolResult> {`);
   if (destructure.length > 0) {
     lines.push(`        const { ${destructure.join(", ")} } = await parseAndValidate(args, ${argsConstName});`);
   }
@@ -4301,9 +4486,8 @@ function generateMcpFile(root, options = {}) {
     imports.push(`import { ${svc} } from '${mod}';`);
   }
   imports.push(...schemaImportLines(collectSchemaIds(plans, options.modelsWithInput), options));
-  const relFile = options.outPath ? relative5(dirname5(options.outPath), root.file) : root.file;
   const header = `// Auto-generated MCP tools
-// generated from [${basename3(root.file)}](file://./${relFile})`;
+// generated from ${sourceLink(basename3(root.file), options.outPath, root.file)}`;
   return `${header}
 ${imports.join("\n")}
 
@@ -4320,11 +4504,19 @@ function generateMcpAggregator(entries) {
   lines.push(`import { McpToolHandlerMap } from '@maroonedsoftware/mcp';`);
   for (const e of sorted) lines.push(`import { ${e.registerFn} } from '${e.importPath}';`);
   lines.push("");
-  lines.push("/** Build + register the MCP tool catalog. Call once at startup. */");
+  lines.push("/**");
+  lines.push(" * Build the MCP tool catalog.");
+  lines.push(" *");
+  lines.push(" * Bind it to the `McpToolHandlerMap` token from a factory, which is what supplies the");
+  lines.push(" * `Container` needed to resolve each handler:");
+  lines.push(" *");
+  lines.push(" * ```ts");
+  lines.push(" * registry.register(McpToolHandlerMap).useFactory(registerMcpTools).asSingleton();");
+  lines.push(" * ```");
+  lines.push(" */");
   lines.push("export function registerMcpTools(container: Container): McpToolHandlerMap {");
   lines.push("    const map = new McpToolHandlerMap();");
   for (const e of sorted) lines.push(`    ${e.registerFn}(map, container);`);
-  lines.push("    container.register(McpToolHandlerMap, { useValue: map });");
   lines.push("    return map;");
   lines.push("}");
   return lines.join("\n") + "\n";
@@ -4335,7 +4527,7 @@ function generateMcpRouter(options = {}) {
   return `import { ServerKitRouter, bodyParserMiddleware, requireSignature } from '@maroonedsoftware/koa';
 import { McpDispatcher, createMcpRequestContext, MCP_AUTH_POLICY } from '@maroonedsoftware/mcp';
 
-/** Mount the MCP endpoint onto a ServerKit router. Call \`registerMcpTools(container)\` at startup. */
+/** Mount the MCP endpoint onto a ServerKit router. Bind \`registerMcpTools\` to the \`McpToolHandlerMap\` token. */
 export function mountMcp(router: ReturnType<typeof ServerKitRouter>): void {
     router.post('${path}', bodyParserMiddleware(['json']), requireSignature('mcp', { policy: MCP_AUTH_POLICY }), async (ctx) => {
         const dispatcher = ctx.container.get(McpDispatcher);
@@ -4369,6 +4561,7 @@ function assertWithinBase(baseOutDir, outPath) {
   return outPath;
 }
 __name(assertWithinBase, "assertWithinBase");
+var TEMPLATE_VAR_RE_G = /\{(\w+)\}/g;
 function resolveTemplate(template, vars) {
   return template.replace(/\{(\w+)\}/g, (_, key) => vars[key] ?? `{${key}}`);
 }
@@ -4563,7 +4756,10 @@ function computePubliclyReachableTypes(opAsts, contractAsts, modelsWithInput, mo
 __name(computePubliclyReachableTypes, "computePubliclyReachableTypes");
 
 // src/index.ts
-var TYPESCRIPT_CODEGEN_VERSION = "1";
+var BIGINT_SCALARS = /* @__PURE__ */ new Set([
+  "bigint"
+]);
+var TYPESCRIPT_CODEGEN_VERSION = "2";
 var CACHE_MANIFEST_FILENAME = "typescript-manifest.json";
 var plugin = {
   name: "typescript",
@@ -4608,11 +4804,19 @@ async function runTypescriptCodegen(inputs, ctx, config, rootDir) {
     fileExists: existsSync
   });
   deleteStalePaths(result.deletedPaths);
+  const unresolved = /* @__PURE__ */ new Set();
   for (const { relativePath, content, ifAbsent } of result.filesToWrite) {
+    for (const [, key] of relativePath.matchAll(TEMPLATE_VAR_RE_G)) unresolved.add(`${key}::${relativePath}`);
     ctx.emitFile(relativePath, content, ifAbsent ? {
       ifAbsent: true
     } : void 0);
   }
+  for (const entry of [
+    ...unresolved
+  ].sort()) {
+    const [key, outPath] = entry.split("::");
+    ctx.warn?.(`Output path template variable {${key}} has no value, so '${outPath}' contains it literally. Declare it in the source file's 'options { keys { ${key}: ... } }' block, or remove it from the path template.`);
+  }
   writeManifest(manifestPath, result.manifest);
 }
 __name(runTypescriptCodegen, "runTypescriptCodegen");
@@ -4818,7 +5022,8 @@ function collectSdkOutput(config, rootDir, inputs, units, globalFiles) {
   const subConfigKey = stableSubConfig(config);
   const modelsWithInput = inputs.modelsWithInput;
   const modelsWithOutput = inputs.modelsWithOutput;
-  const modelsWithDecimal = computeModelsWithDecimal(inputs.contractRoots.flatMap((r) => r.models));
+  const modelsWithDecimal = computeModelsWithScalar(inputs.contractRoots.flatMap((r) => r.models), DEFAULT_REVIVABLE_SCALARS);
+  const modelsWithBigInt = computeModelsWithScalar(inputs.contractRoots.flatMap((r) => r.models), BIGINT_SCALARS);
   const modelMap = buildModelMap(inputs.contractRoots);
   const allFiles = [
     ...inputs.contractRoots.map((r) => r.file),
@@ -4861,6 +5066,7 @@ function collectSdkOutput(config, rootDir, inputs, units, globalFiles) {
       // Not covered by `root`: adding a decimal to a model in a *different* .ck file changes
       // this file's revivers with no change to `root` or the config.
       modelsWithDecimal: sliceModelSet(refs, ownNames, modelsWithDecimal),
+      modelsWithBigInt: sliceModelSet(refs, ownNames, modelsWithBigInt),
       sdkOptionsPath,
       sub: subConfigKey
     });
@@ -4876,7 +5082,10 @@ function collectSdkOutput(config, rootDir, inputs, units, globalFiles) {
             modelsWithInput,
             modelsWithOutput,
             modelsWithDecimal,
-            emitRevivers: true
+            emitRevivers: true,
+            // An SDK client runs in a browser as readily as in Node, and its scaffold
+            // declares no `@types/node`.
+            target: "client"
           });
         } else {
           let rel = relative7(dirname7(typeOutPath), sdkOptionsPath).replace(/\.ts$/, ".js");
@@ -4950,6 +5159,7 @@ function collectSdkOutput(config, rootDir, inputs, units, globalFiles) {
           modelsWithInput: sliceModelSet(refs, /* @__PURE__ */ new Set(), modelsWithInput),
           modelsWithOutput: sliceModelSet(refs, /* @__PURE__ */ new Set(), modelsWithOutput),
           modelsWithDecimal: sliceModelSet(refs, /* @__PURE__ */ new Set(), modelsWithDecimal),
+          modelsWithBigInt: sliceModelSet(refs, /* @__PURE__ */ new Set(), modelsWithBigInt),
           sdkOptionsPath,
           className,
           includeInternal: config.includeInternal ?? false,
@@ -4969,6 +5179,7 @@ function collectSdkOutput(config, rootDir, inputs, units, globalFiles) {
                 modelsWithInput,
                 modelsWithOutput,
                 modelsWithDecimal,
+                modelsWithBigInt,
                 modelMap,
                 includeInternal: config.includeInternal,
                 clientClassName: className
@@ -4995,6 +5206,7 @@ function collectSdkOutput(config, rootDir, inputs, units, globalFiles) {
         modelsWithInput: sliceModelSet(refs, /* @__PURE__ */ new Set(), modelsWithInput),
         modelsWithOutput: sliceModelSet(refs, /* @__PURE__ */ new Set(), modelsWithOutput),
         modelsWithDecimal: sliceModelSet(refs, /* @__PURE__ */ new Set(), modelsWithDecimal),
+        modelsWithBigInt: sliceModelSet(refs, /* @__PURE__ */ new Set(), modelsWithBigInt),
         sdkOptionsPath,
         includeInternal: config.includeInternal ?? false,
         sub: subConfigKey
@@ -5013,6 +5225,7 @@ function collectSdkOutput(config, rootDir, inputs, units, globalFiles) {
               modelsWithInput,
               modelsWithOutput,
               modelsWithDecimal,
+              modelsWithBigInt,
               modelMap,
               includeInternal: config.includeInternal
             })
@@ -5083,6 +5296,7 @@ function collectSdkOutput(config, rootDir, inputs, units, globalFiles) {
         modelsWithInput: sliceModelSet(allInlineRefs, /* @__PURE__ */ new Set(), modelsWithInput),
         modelsWithOutput: sliceModelSet(allInlineRefs, /* @__PURE__ */ new Set(), modelsWithOutput),
         modelsWithDecimal: sliceModelSet(allInlineRefs, /* @__PURE__ */ new Set(), modelsWithDecimal),
+        modelsWithBigInt: sliceModelSet(allInlineRefs, /* @__PURE__ */ new Set(), modelsWithBigInt),
         sdkOptionsPath,
         includeInternal: config.includeInternal ?? false,
         sub: subConfigKey
@@ -5097,6 +5311,7 @@ function collectSdkOutput(config, rootDir, inputs, units, globalFiles) {
           modelsWithInput,
           modelsWithOutput,
           modelsWithDecimal,
+          modelsWithBigInt,
           modelMap,
           includeInternal: config.includeInternal
         }
@@ -5238,11 +5453,15 @@ function collectZodOutput(config, rootDir, inputs, units) {
       render: /* @__PURE__ */ __name(() => [
         {
           relativePath: outPath,
+          // Server-shaped, which is what this sub-generator has always emitted. The
+          // standalone `zod:` output has no target option of its own; only the SDK's
+          // schemas are client-shaped, and they pass their own target.
           content: generateContract(ast, {
             modelOutPaths,
             currentOutPath: outPath,
             modelsWithInput,
-            modelsWithOutput
+            modelsWithOutput,
+            target: "server"
           })
         }
       ], "render")