@springbrand/http 0.1.0-alpha.2 → 0.1.0-alpha.3

package/.agents/skills/dune-react-http/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dune-react-http
-description: Use SpringBrand shared HTTP contracts, Axios request clients, Query error recovery, and server response helpers. Trigger when constructing requests, injecting tokens, handling HTTP failures, connecting TanStack Query, or creating standard server responses.
+description: Use SpringBrand shared HTTP contracts, Axios request clients, Query error recovery, project error catalogs, Hono responses, and server helpers. Trigger when constructing requests, injecting tokens, handling HTTP failures, connecting TanStack Query, defining error codes, returning Hono/OpenAPI responses, reading request bodies, or creating standard server responses.
 ---
 
 # Dune React HTTP
@@ -13,7 +13,9 @@ Read the installed declarations and README before configuring a client. Public e
 | @springbrand/http/errors | Error definitions, cancellation and transient failure classification |
 | @springbrand/http/client | Axios client and standard HTTP error parsing |
 | @springbrand/http/query | Optional TanStack React Query integration |
-| @springbrand/http/server | Standard Response helpers and service authentication |
+| @springbrand/http/catalog | Project error catalog: typed HttpError, Zod response schemas, client decoder (zod peer) |
+| @springbrand/http/hono | Hono responders with TypedResponse types for zod-openapi (hono peer) |
+| @springbrand/http/server | Standard Response helpers, bounded body reading, If-Match, Content-Disposition, log diagnostics and service authentication |
 
 ## Client setup
 
@@ -33,13 +35,29 @@ Use isTransientHttpError from the core or errors entry point for cached-view rec
 
 Runtime capability failures use RUNTIME_UNSUPPORTED (kind runtime), distinct from invalid input; neither runtime failures nor blocked redirects are transient or retryable. Raw runtime diagnostics are not exposed.
 
+Override SDK-generated copy with the client messages option when the product language is not Chinese; server errMsg is unaffected.
+
+Return a Promise from onUnauthorized when it rechecks the session, so later failures of the same token are handled again after the check settles.
+
+Session-expiry failures (isUnauthorized) never reach notify, with or without a token; control per-request presentation with feedback.
+
 Only confirmed current Bearer session failures trigger onUnauthorized. Never clear sessions on network failures, every 401, or 403. SDK callbacks guard stale Token responses and duplicate feedback. Cookie login/recovery belongs to consumer authentication.
 
+## Error catalog
+
+Business error codes belong to each project. Define them once with defineErrorCatalog and derive HttpError, OpenAPI schemas and the client decodeError from it; do not keep a second catalog, HttpError class or error schema in the project. The catalog must define the SDK's required codes (the type checker reports missing ones). Status 0 codes are client-only and cannot be thrown. Register a details schema per code; unregistered details are never exposed.
+
+Use parseInput only for request input. Normalize thrown errors through toHttpError in the app's error handler; unknown exceptions return undefined and must become a generic 500.
+
+## Hono
+
+Create responders once with createHonoHttp(catalog) and return them directly from handlers so zod-openapi checks declared statuses. Do not cast their results or rebuild envelopes with c.json. httpError records the error on c.get("apiError") for request logging.
+
 ## Server setup
 
 Return ok or fail through framework-compatible Response handling. Failures use real 4xx/5xx and public error messages. Keep domain errors separate until the HTTP handler translates them. Validate business details before returning them. toErrorResponse hides unknown exceptions.
 
-Use service request/verification helpers for service credentials, independently of user authentication. Service requests use manual redirects and no-store; Workers omit the unsupported credentials option. The caller must reject 3xx instead of following them with service credentials. Never forward user Cookie/Authorization or send service tokens to another origin.
+Read untrusted bodies with readJsonLimited/readBytesLimited/limitRequestBody instead of trusting Content-Length. Log errors through errorDiagnostics, never by serializing raw errors. Use service request/verification helpers for service credentials, independently of user authentication. Service requests use manual redirects and no-store; Workers omit the unsupported credentials option. The caller must reject 3xx instead of following them with service credentials. Never forward user Cookie or send service tokens to another origin. Forward the caller's Authorization only with an explicit `{ forwardAuthorization: true }` when the downstream service authorizes that same user.
 
 ## Verification
 

package/README.md

@@ -1,6 +1,6 @@
 # SpringBrand HTTP SDK
 
-一个包提供共享 HTTP 合同、Axios 客户端、Query 接入和框架无关的服务端辅助函数。错误规则由 SDK 维护，消费者提供 Token、通知和业务回调。
+一个包提供共享 HTTP 合同、Axios 客户端、Query 接入、错误码目录、Hono 接入和框架无关的服务端辅助函数。错误规则由 SDK 维护，消费者提供 Token、通知和业务回调。
 
 ## 安装
 
@@ -18,9 +18,11 @@ pnpm add @springbrand/http@alpha
 | `@springbrand/http/errors` | 基础错误码、取消识别和临时错误判断 |
 | `@springbrand/http/client` | createHttpClient、parseHttpError |
 | `@springbrand/http/query` | createHttpQueryClient、读取重试策略 |
-| `@springbrand/http/server` | ok、fail、toErrorResponse、服务鉴权与安全诊断 |
+| `@springbrand/http/catalog` | defineErrorCatalog：项目错误码目录、HttpError、Zod Schema、客户端解码 |
+| `@springbrand/http/hono` | createHonoHttp：ok、httpError 等带 TypedResponse 类型的 Hono 响应 |
+| `@springbrand/http/server` | ok、fail、toErrorResponse、请求体限长读取、If-Match、Content-Disposition、服务鉴权与日志诊断 |
 
-客户端依赖 Axios。Query 是独立入口，以 `@tanstack/react-query` 作为可选 peer；核心和服务端使用者无需安装 React 或 Query。服务端要求标准 Request、Response 和 Web Crypto，建议 Node.js 24 或兼容运行时。
+客户端依赖 Axios。Query、catalog、hono 是独立入口，分别以 `@tanstack/react-query`、`zod`、`hono` 作为可选 peer；只用到哪个入口才需要安装对应依赖，核心和 server 入口都不需要。服务端要求标准 Request、Response 和 Web Crypto，建议 Node.js 24 或兼容运行时。
 
 ## 请求实例
 
@@ -121,7 +123,15 @@ if (query.data !== undefined && isTransientHttpError(query.error)) {
 
 主动写入的网络失败会提示结果暂时无法确认，不自动重发。取消保持取消语义，不包装成 NETWORK_ERROR。超时为 REQUEST_TIMEOUT，格式错误为 RESPONSE_INVALID，内容超限为 RESPONSE_TOO_LARGE。请求运行时不支持所需能力时为 RUNTIME_UNSUPPORTED（kind: runtime），与非法调用参数 REQUEST_INVALID_INPUT 分开；运行时和重定向错误不重试、不清理登录。
 
-默认仅 401 且 AUTH_UNAUTHENTICATED 触发失效回调。旧身份的响应不清理新身份，同一 Token 并发失效仅处理一次；网络错误、其他 401 和 403 不退出登录。默认自动处理针对实例携带的 Bearer 身份，Cookie 会话的恢复流程由消费者掌握。
+默认仅 401 且 AUTH_UNAUTHENTICATED 触发失效回调；这类登录失效交给认证流程，不论请求是否携带 Token 都不弹通用提示。单个请求的提示方式用 `feedback`（auto、inline、silent）控制。onUnauthorized 返回 Promise 时（例如复检会话），复检期间同一 Token 的重复失效只处理一次，Promise 完成后恢复处理；返回 void 时直到 Token 变化。旧身份的响应不清理新身份，同一 Token 并发失效仅处理一次；网络错误、其他 401 和 403 不退出登录。默认自动处理针对实例携带的 Bearer 身份，Cookie 会话的恢复流程由消费者掌握。
+
+`messages` 用来替换 SDK 自身产生的提示文案（例如 NETWORK_ERROR、REQUEST_TIMEOUT，以及写操作结果无法确认时的 MUTATION_RESULT_UNCERTAIN），默认是中文。服务端返回的 errMsg 不受影响。
+
+```ts
+createHttpClient({ baseUrl, messages: { NETWORK_ERROR: 'Unable to reach the server', MUTATION_RESULT_UNCERTAIN: 'Check the result before retrying' } });
+```
+
+pnpm 可能按消费者的可选 peer 解析出多份 SDK 实例；`instanceof ApiError` 通过全局 Symbol 跨实例识别，目录的 HttpError 等子类仍按原型链判断。
 
 ApiError 使用对象参数，泛型 details 可用于业务详情：
 
@@ -136,6 +146,65 @@ throw new ApiError<{ revision: number }>({
 
 decodeResponse 处理特殊成功协议；decodeError 可调用公开 parseHttpError 后验证并附加业务 details。SDK 保留请求上下文、错误类和原始状态，不在公共错误中保存原始 Axios config 或凭据。
 
+## 错误码目录
+
+业务错误码属于项目，不属于 SDK。每个项目用 `defineErrorCatalog` 定义一次目录，服务端抛错、OpenAPI Schema 和浏览器解析都从这里派生：
+
+```ts
+import { z } from 'zod';
+import { defineErrorCatalog } from '@springbrand/http/catalog';
+
+export const errorDefinitions = {
+  // SDK 服务端辅助函数会产生这些码，目录必须定义（类型检查会提示缺失）。
+  REQUEST_INVALID_INPUT: { status: 400, message: 'Request input is invalid' },
+  REQUEST_INVALID_JSON: { status: 400, message: 'Expected a JSON object' },
+  REQUEST_VALIDATION_FAILED: { status: 422, message: 'Validation failed' },
+  REQUEST_PAYLOAD_TOO_LARGE: { status: 413, message: 'Request body is too large' },
+  REQUEST_NOT_FOUND: { status: 404, message: 'Resource not found' },
+  REQUEST_RATE_LIMITED: { status: 429, message: 'Too many requests' },
+  AUTH_UNAUTHENTICATED: { status: 401, message: 'Authentication required' },
+  INTERNAL_ERROR: { status: 500, message: 'Internal server error' },
+  // 业务码
+  CAMPAIGN_NOT_STARTED: { status: 409, message: 'Campaign has not started yet' },
+  // status 0 只属于客户端，不能在服务端抛出，也不会进入响应 Schema。
+  NETWORK_ERROR: { status: 0, message: 'Unable to reach the server' },
+} as const;
+
+export const errors = defineErrorCatalog(errorDefinitions, {
+  details: { CAMPAIGN_NOT_STARTED: z.object({ startsAt: z.iso.datetime() }) },
+});
+
+throw new errors.HttpError('CAMPAIGN_NOT_STARTED', undefined, { details: { startsAt } });
+```
+
+目录返回：
+
+| 成员 | 用途 |
+| --- | --- |
+| `HttpError` | 继承 ApiError。状态码和默认文案由错误码决定，错误码、状态码和 details 都有类型 |
+| `parseInput(schema, input)` | 只用于请求输入：失败抛 422 REQUEST_VALIDATION_FAILED 并带字段错误。存储数据和输出的校验失败不要用它 |
+| `toHttpError(error)` | 把本目录的 HttpError 和 SDK server 函数抛出的 HTTP ApiError 统一成 HttpError；其他异常返回 undefined，由应用按 500 处理 |
+| `httpErrorSchema`、`validationErrorSchema` | OpenAPI 用的失败响应 Schema；`responseSchema(msg)` 是成功响应 Schema |
+| `decodeError` | 传给 createHttpClient 的 decodeError：只接受本目录的码，并校验登记过的 details；其他响应体是 RESPONSE_INVALID（目录定义了该码时使用目录文案） |
+| `errorFromResponse(response)` | 服务间调用时，从非 2xx 的 Response 读出 ApiError |
+| `isErrorCode`、`isHttpErrorResponse`、`codes` | 判断和列举服务端错误码 |
+
+details 只对登记了 Schema 的错误码公开：抛出时校验失败会直接报错，解码时校验失败会丢弃。
+
+## Hono 接入
+
+```ts
+import { createHonoHttp } from '@springbrand/http/hono';
+
+export const { ok, httpError, httpNotFound, httpUnauthorized, httpValidationError, httpRateLimited, httpInternalError, httpErrorResponse } =
+  createHonoHttp(errors);
+
+app.onError((error, c) => httpError(c, errors.toHttpError(error) ?? new errors.HttpError('INTERNAL_ERROR', undefined, { cause: error })));
+app.openapi(route, c => found ? ok(c, item) : httpNotFound(c));
+```
+
+返回值保留 Hono 的 TypedResponse 类型，`@hono/zod-openapi` 会检查处理器返回的状态码和响应体是否在路由里声明过。`ok(c, msg, status?)` 支持 200、201、202。`httpError` 会执行 `c.set("apiError", error)` 供请求日志读取，请求编号读自 `c.get("requestId")`。拿不到 Context 的地方用 `httpErrorResponse(error, { requestId })`，它不会生成新的请求编号。
+
 ## 服务端
 
 ```ts
@@ -149,7 +218,11 @@ ok 支持 200、201、202；无内容成功直接用标准 Response。fail 只
 
 toErrorResponse 公开标准 ApiError 的安全信息，未知异常返回固定 500 INTERNAL_ERROR。业务错误和 details 在 HTTP 处理器中翻译和验证。
 
-createServiceRequest 为绑定来源构造服务请求，清理用户 Authorization 和 Cookie，注入 X-SpringBrand-Service-Token。verifyServiceToken 比较等长摘要。服务请求使用 no-store / manual，Worker 中不设置浏览器专有的 credentials。调用方需拒绝非成功响应，尤其不得自行跟随 3xx 并转发服务凭据；不使用用户 Bearer 的登录失效流程。
+请求体工具按实际读取的字节数限制大小，不信任 Content-Length：`readBytesLimited`、`readJsonLimited`、`limitRequestBody`（中间件中计数后重建 Request）、`readJson`。超限抛 413 REQUEST_PAYLOAD_TOO_LARGE，JSON 语法错误抛 400 REQUEST_INVALID_JSON，都是 `kind: "http"` 的 ApiError，用目录的 `toHttpError` 转成项目 HttpError。`requireIfMatchRevision(request, subject)` 读取 `If-Match: "3"` 形式的版本号。`contentDispositionHeader(filename, type?)` 生成兼容非 ASCII 文件名的下载响应头。
+
+`errorDiagnostics(error)` 是请求日志用的异常投影：保留 cause 链、调用栈和上游状态，遮蔽凭据；带 query 或 params 的数据库异常只记录固定文案。`redactSensitiveText` 单独提供遮蔽能力。
+
+createServiceRequest 为绑定来源构造服务请求，清理用户 Authorization 和 Cookie，注入 X-SpringBrand-Service-Token。第三个参数可以是路径，也可以是一个 Request：传 Request 时转发它的方法、请求头、请求体（流式请求体自动声明半双工）和 signal；同源 URL 原样使用，其他来源只保留路径和查询参数并绑定到 baseUrl。下游需要按调用者身份鉴权时（例如 API 代理用户请求到 Agent），显式传第五个参数 `{ forwardAuthorization: true }` 保留 Authorization；Cookie 始终删除。verifyServiceToken 比较等长摘要。服务请求使用 no-store / manual，Worker 中不设置浏览器专有的 credentials。调用方需拒绝非成功响应，尤其不得自行跟随 3xx 并转发服务凭据；不使用用户 Bearer 的登录失效流程。
 
 ## 验证与示例
 

package/dist/catalog.d.ts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+import { ApiError } from "./errors.js";
+import type { FieldError, ResponseInfo } from "./types.js";
+export type ErrorDefinition = {
+    readonly status: number;
+    readonly message: string;
+};
+export type ErrorDefinitions = Readonly<Record<string, ErrorDefinition>>;
+/** SDK 的服务端辅助函数会产生这些错误码，每个错误目录都必须定义它们。 */
+export declare const requiredErrorCodes: readonly ["REQUEST_INVALID_INPUT", "REQUEST_INVALID_JSON", "REQUEST_VALIDATION_FAILED", "REQUEST_PAYLOAD_TOO_LARGE", "REQUEST_NOT_FOUND", "REQUEST_RATE_LIMITED", "AUTH_UNAUTHENTICATED", "INTERNAL_ERROR"];
+export type RequiredErrorCode = (typeof requiredErrorCodes)[number];
+/** 能出现在 HTTP 响应里的错误码；status 为 0 的码（如 NETWORK_ERROR）只属于客户端。 */
+export type ServerErrorCode<D extends ErrorDefinitions> = {
+    [K in keyof D & string]: D[K]["status"] extends 0 ? never : K;
+}[keyof D & string];
+export type DetailSchemas<D extends ErrorDefinitions> = {
+    readonly [K in ServerErrorCode<D>]?: z.ZodType;
+};
+type DetailsOf<S, C> = C extends keyof S ? S[C] extends z.ZodType ? z.output<S[C]> : undefined : undefined;
+export type HttpErrorOptions<T> = ErrorOptions & {
+    errors?: FieldError[];
+    details?: T;
+    upstreamStatus?: number;
+    upstreamRequestId?: string;
+};
+export type CatalogErrorResponse<C extends string> = {
+    code: C;
+    errMsg: string;
+    requestId?: string;
+    errors?: FieldError[];
+    details?: unknown;
+};
+/** 标准成功响应 `{ success: true, msg, errMsg: "", code: "" }` 的 Schema。 */
+export declare function responseSchema<T extends z.ZodType>(msgSchema: T): z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    msg: T;
+    errMsg: z.ZodLiteral<"">;
+    code: z.ZodLiteral<"">;
+}, z.core.$strip>;
+/**
+ * 用项目自己的错误码目录生成带类型的 HttpError、OpenAPI Schema 和客户端解码器。
+ * 目录只定义一次：服务端抛错、响应 Schema 和浏览器解析都从这里派生。
+ */
+export declare function defineErrorCatalog<const D extends ErrorDefinitions & Record<RequiredErrorCode, ErrorDefinition>, const S extends DetailSchemas<D> = Record<never, never>>(definitions: D, options?: {
+    details?: S;
+}): {
+    definitions: D;
+    codes: readonly ServerErrorCode<D>[];
+    HttpError: {
+        new <C extends ServerErrorCode<D> = ServerErrorCode<D>>(code: C, message?: string, options?: HttpErrorOptions<DetailsOf<S, C>>): {
+            readonly code: C;
+            readonly status: D[C]["status"];
+            readonly upstreamStatus: number | undefined;
+            readonly upstreamRequestId: string | undefined;
+            readonly requestId?: string;
+            readonly errors?: FieldError[];
+            readonly details?: DetailsOf<S, C> | undefined;
+            readonly kind: import("./errors.js").ApiErrorKind;
+            readonly retryAfterMs?: number;
+            readonly context?: import("./types.js").RequestContext;
+            name: string;
+            message: string;
+            stack?: string;
+            cause?: unknown;
+        };
+        [Symbol.hasInstance](value: unknown): boolean;
+        captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+        prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+        stackTraceLimit: number;
+    };
+    isErrorCode: (value: unknown) => value is ServerErrorCode<D>;
+    isHttpErrorResponse: (data: unknown) => data is CatalogErrorResponse<ServerErrorCode<D>>;
+    parseInput: <T extends z.ZodType>(schema: T, input: unknown) => z.output<T>;
+    toHttpError: (error: unknown) => {
+        readonly code: ServerErrorCode<D>;
+        readonly status: D[ServerErrorCode<D>]["status"];
+        readonly upstreamStatus: number | undefined;
+        readonly upstreamRequestId: string | undefined;
+        readonly requestId?: string;
+        readonly errors?: FieldError[];
+        readonly details?: DetailsOf<S, ServerErrorCode<D>> | undefined;
+        readonly kind: import("./errors.js").ApiErrorKind;
+        readonly retryAfterMs?: number;
+        readonly context?: import("./types.js").RequestContext;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    } | undefined;
+    decodeError: (data: unknown, info: ResponseInfo) => ApiError;
+    errorFromResponse: (response: Response) => Promise<ApiError>;
+    httpErrorSchema: z.ZodObject<{
+        details?: z.ZodOptional<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>> | undefined;
+        code: z.ZodEnum<{ [k_1 in ServerErrorCode<D>]: k_1; } extends infer T ? { [k in keyof T]: T[k]; } : never>;
+        errMsg: z.ZodString;
+        requestId: z.ZodOptional<z.ZodString>;
+        errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            errMsg: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+    validationErrorSchema: z.ZodObject<{
+        details?: z.ZodOptional<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>> | undefined;
+        code: z.ZodEnum<{ [k_1 in ServerErrorCode<D>]: k_1; } extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>;
+        errMsg: z.ZodString;
+        requestId: z.ZodOptional<z.ZodString>;
+        errors: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            errMsg: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+};
+export type ErrorCatalogOf<D extends ErrorDefinitions & Record<RequiredErrorCode, ErrorDefinition>, S extends DetailSchemas<D> = Record<never, never>> = ReturnType<typeof defineErrorCatalog<D, S>>;
+export {};

package/dist/catalog.js

@@ -0,0 +1,131 @@
+import { z } from "zod";
+import { ApiError } from "./errors.js";
+import { parseHttpError } from "./response.js";
+import { sdkError } from "./sdk-error.js";
+const requiredErrorCodes = [
+  "REQUEST_INVALID_INPUT",
+  "REQUEST_INVALID_JSON",
+  "REQUEST_VALIDATION_FAILED",
+  "REQUEST_PAYLOAD_TOO_LARGE",
+  "REQUEST_NOT_FOUND",
+  "REQUEST_RATE_LIMITED",
+  "AUTH_UNAUTHENTICATED",
+  "INTERNAL_ERROR"
+];
+const fieldErrorsSchema = z.array(z.object({ path: z.string(), errMsg: z.string() }));
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+function responseSchema(msgSchema) {
+  return z.object({ success: z.literal(true), msg: msgSchema, errMsg: z.literal(""), code: z.literal("") });
+}
+function defineErrorCatalog(definitions, options = {}) {
+  const detailSchemas = options.details ?? {};
+  for (const [code, definition] of Object.entries(definitions)) {
+    if (!/^[A-Z][A-Z0-9_]{0,127}$/.test(code)) throw new RangeError(`Invalid error code ${code}`);
+    if (definition.status !== 0 && !(Number.isInteger(definition.status) && definition.status >= 400 && definition.status <= 599)) {
+      throw new RangeError(`Error ${code} must use status 0 or a 4xx/5xx status`);
+    }
+  }
+  const codes = Object.keys(definitions).filter((code) => definitions[code].status !== 0);
+  for (const code of Object.keys(detailSchemas)) {
+    if (!codes.includes(code)) throw new RangeError(`Details schema ${code} is not a server error code`);
+  }
+  function isErrorCode(value) {
+    return typeof value === "string" && Object.hasOwn(definitions, value) && definitions[value].status !== 0;
+  }
+  function parseDetails(code, details, strict) {
+    const schema = detailSchemas[code];
+    if (!schema || details === void 0) return void 0;
+    if (strict) return schema.parse(details);
+    const result = schema.safeParse(details);
+    return result.success ? result.data : void 0;
+  }
+  class HttpError extends ApiError {
+    upstreamStatus;
+    upstreamRequestId;
+    constructor(code, message, options2) {
+      if (!isErrorCode(code)) throw new RangeError(`Unknown server error code ${String(code)}`);
+      super({
+        status: definitions[code].status,
+        code,
+        message: message ?? definitions[code].message,
+        errors: options2?.errors,
+        // 只有登记了 Schema 的错误码才公开 details，且必须先通过校验。
+        details: parseDetails(code, options2?.details, true),
+        kind: "http",
+        cause: options2?.cause
+      });
+      this.name = "HttpError";
+      this.upstreamStatus = options2?.upstreamStatus;
+      this.upstreamRequestId = options2?.upstreamRequestId;
+    }
+  }
+  function parseInput(schema, input) {
+    const result = schema.safeParse(input);
+    if (!result.success) {
+      throw new HttpError("REQUEST_VALIDATION_FAILED", void 0, {
+        cause: result.error,
+        errors: result.error.issues.map((issue) => ({ path: issue.path.join("."), errMsg: issue.message }))
+      });
+    }
+    return result.data;
+  }
+  function toHttpError(error) {
+    if (error instanceof HttpError) return error;
+    if (!(error instanceof ApiError) || error.kind !== "http" || !isErrorCode(error.code)) return void 0;
+    return new HttpError(error.code, error.message, {
+      cause: error.cause ?? error,
+      errors: error.errors,
+      details: parseDetails(error.code, error.details, false)
+    });
+  }
+  function isHttpErrorResponse(data) {
+    return isRecord(data) && isErrorCode(data.code) && typeof data.errMsg === "string";
+  }
+  function decodeError(data, info) {
+    if (!isHttpErrorResponse(data)) {
+      const fallback = parseHttpError(void 0, info);
+      const message = definitions.RESPONSE_INVALID?.message;
+      const options2 = { status: info.status, kind: info.status >= 500 ? "http" : "response", requestId: fallback.requestId, retryAfterMs: fallback.retryAfterMs };
+      return message === void 0 ? sdkError("RESPONSE_INVALID", options2) : new ApiError({ ...options2, code: "RESPONSE_INVALID", message });
+    }
+    const parsed = parseHttpError(data, info);
+    const details = parseDetails(data.code, data.details, false);
+    return details === void 0 ? parsed : new ApiError({ ...parsed, message: parsed.message, details });
+  }
+  async function errorFromResponse(response) {
+    const data = await response.json().catch(() => void 0);
+    const headers = {};
+    response.headers.forEach((value, key) => {
+      headers[key.toLowerCase()] = value;
+    });
+    return decodeError(data, { status: response.status, headers });
+  }
+  const schemas = Object.values(detailSchemas).filter((schema) => schema !== void 0);
+  const detailsSchema = schemas.length === 0 ? void 0 : schemas.length === 1 ? schemas[0] : z.union(schemas);
+  const httpErrorSchema = z.object({
+    code: z.enum(codes),
+    errMsg: z.string(),
+    requestId: z.string().optional(),
+    errors: fieldErrorsSchema.optional(),
+    ...detailsSchema ? { details: detailsSchema.optional() } : {}
+  });
+  const validationErrorSchema = httpErrorSchema.extend({ errors: fieldErrorsSchema });
+  return {
+    definitions,
+    codes,
+    HttpError,
+    isErrorCode,
+    isHttpErrorResponse,
+    parseInput,
+    toHttpError,
+    decodeError,
+    errorFromResponse,
+    httpErrorSchema,
+    validationErrorSchema
+  };
+}
+export {
+  defineErrorCatalog,
+  requiredErrorCodes,
+  responseSchema
+};

package/dist/client.js

@@ -1,5 +1,6 @@
 import axios from "axios";
-import { ApiError, errorDefinitions, isRequestCancelled } from "./errors.js";
+import { ApiError, isRequestCancelled } from "./errors.js";
+import { sdkError, keepSdkDefault, sdkMessage } from "./sdk-error.js";
 import { createErrorHandler } from "./error-handler.js";
 import { toSafeDiagnostics } from "./diagnostics.js";
 import { serviceUrl, boundUrl } from "./url.js";
@@ -35,14 +36,14 @@ function createHttpClient(config) {
     let sentToken;
     let received = false;
     try {
-      if (!["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"].includes(method) || (method === "GET" || method === "HEAD") && options.body !== void 0) throw new ApiError({ status: 0, code: "REQUEST_INVALID_INPUT", message: errorDefinitions.REQUEST_INVALID_INPUT, kind: "input" });
+      if (!["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"].includes(method) || (method === "GET" || method === "HEAD") && options.body !== void 0) throw sdkError("REQUEST_INVALID_INPUT", { status: 0, kind: "input" });
       const url = boundUrl(base, path);
       for (const [key, value] of Object.entries(options.params ?? {})) {
         for (const item of Array.isArray(value) ? value : [value]) if (item !== void 0 && item !== null) url.searchParams.append(key, String(item));
       }
       const timeout = options.timeoutMs ?? config.timeoutMs ?? 15e3;
       const limit = options.maxResponseBytes ?? config.maxResponseBytes ?? 10 * 1024 * 1024;
-      if (!Number.isFinite(timeout) || timeout < 0 || !Number.isSafeInteger(limit) || limit < 0) throw new ApiError({ status: 0, code: "REQUEST_INVALID_INPUT", message: errorDefinitions.REQUEST_INVALID_INPUT, kind: "input" });
+      if (!Number.isFinite(timeout) || timeout < 0 || !Number.isSafeInteger(limit) || limit < 0) throw sdkError("REQUEST_INVALID_INPUT", { status: 0, kind: "input" });
       if (signal.aborted) throw signal.reason;
       const headers = new Headers(config.getHeaders?.());
       new Headers(options.headers).forEach((value, key) => headers.set(key, value));
@@ -54,7 +55,7 @@ function createHttpClient(config) {
       }
       if (options.idempotencyKey) headers.set("Idempotency-Key", options.idempotencyKey);
       if (options.body instanceof FormData) headers.delete("Content-Type");
-      if (timeout > 0) timer = setTimeout(() => controller.abort(new ApiError({ status: 0, code: "REQUEST_TIMEOUT", message: errorDefinitions.REQUEST_TIMEOUT, kind: "timeout" })), timeout);
+      if (timeout > 0) timer = setTimeout(() => controller.abort(sdkError("REQUEST_TIMEOUT", { status: 0, kind: "timeout" })), timeout);
       const requestHeaders = new axios.AxiosHeaders(Object.fromEntries(headers));
       if (options.body instanceof FormData) requestHeaders.setContentType("multipart/form-data");
       const response = await transport.request({
@@ -81,7 +82,7 @@ function createHttpClient(config) {
           await response.data?.cancel();
         } catch {
         }
-        throw new ApiError({ status: response.status, code: "REQUEST_REDIRECT_BLOCKED", message: errorDefinitions.REQUEST_REDIRECT_BLOCKED, kind: "response", requestId: responseHeaders["x-request-id"] });
+        throw sdkError("REQUEST_REDIRECT_BLOCKED", { status: response.status, kind: "response", requestId: responseHeaders["x-request-id"] });
       }
       const chunks = await readBody(response.data, info, limit);
       if (signal.aborted) throw signal.reason;
@@ -93,8 +94,8 @@ function createHttpClient(config) {
             if (!(decoded instanceof ApiError)) throw new Error("invalid decoder");
             throw decoded;
           } catch (error) {
-            if (error instanceof ApiError) throw new ApiError({ ...error, status: response.status, message: error.message, requestId: error.requestId ?? responseHeaders["x-request-id"], retryAfterMs: error.retryAfterMs ?? parseRetryAfter(responseHeaders["retry-after"]) });
-            throw new ApiError({ status: response.status, code: "RESPONSE_INVALID", message: errorDefinitions.RESPONSE_INVALID, kind: "response", requestId: responseHeaders["x-request-id"] });
+            if (error instanceof ApiError) throw keepSdkDefault(error, new ApiError({ ...error, status: response.status, message: error.message, requestId: error.requestId ?? responseHeaders["x-request-id"], retryAfterMs: error.retryAfterMs ?? parseRetryAfter(responseHeaders["retry-after"]) }));
+            throw sdkError("RESPONSE_INVALID", { status: response.status, kind: "response", requestId: responseHeaders["x-request-id"] });
           }
         }
         throw parseHttpError(data2, info);
@@ -109,21 +110,22 @@ function createHttpClient(config) {
       const timedOut = reason instanceof Error && reason.name === "TimeoutError";
       const networkFailure = received || axios.isAxiosError(reason) && reason.request instanceof Request;
       const code = timedOut ? "REQUEST_TIMEOUT" : runtimeUnsupported ? "RUNTIME_UNSUPPORTED" : networkFailure ? "NETWORK_ERROR" : "REQUEST_INVALID_INPUT";
-      const normalized = reason instanceof ApiError ? reason : new ApiError({
+      const normalized = reason instanceof ApiError ? reason : sdkError(code, {
         status: 0,
-        code,
-        message: errorDefinitions[code],
         kind: timedOut ? "timeout" : runtimeUnsupported ? "runtime" : networkFailure ? "network" : "input"
       });
-      const failure = new ApiError({ ...normalized, message: normalized.message, context });
+      const failure = new ApiError({ ...normalized, message: sdkMessage(normalized, config.messages), context });
       const unauthorized = config.isUnauthorized ?? ((value) => value.status === 401 && value.code === "AUTH_UNAUTHENTICATED");
       try {
-        if (options.handleUnauthorized !== false && sentToken && config.onUnauthorized && failure.kind === "http" && failure.status >= 400 && unauthorized(failure)) {
-          if (config.getToken?.() !== sentToken || rejectedToken === sentToken) context.authHandled = true;
-          else {
-            rejectedToken = sentToken;
-            context.authHandled = true;
-            config.onUnauthorized(failure);
+        if (failure.kind === "http" && failure.status >= 400 && unauthorized(failure)) context.authHandled = true;
+        if (context.authHandled && options.handleUnauthorized !== false && sentToken && config.onUnauthorized && config.getToken?.() === sentToken && rejectedToken !== sentToken) {
+          rejectedToken = sentToken;
+          const handling = config.onUnauthorized(failure);
+          if (handling && typeof handling.then === "function") {
+            const handledToken = sentToken;
+            void Promise.resolve(handling).catch(() => void 0).finally(() => {
+              if (rejectedToken === handledToken) rejectedToken = void 0;
+            });
           }
         }
       } catch (callbackError) {

package/dist/error-handler.d.ts

@@ -1,2 +1,2 @@
 import type { ErrorContext, HttpClientConfig } from "./types.js";
-export declare function createErrorHandler(config: Pick<HttpClientConfig, "notify" | "onBusinessError" | "onFailure">): (error: unknown, input?: Partial<ErrorContext>) => void;
+export declare function createErrorHandler(config: Pick<HttpClientConfig, "notify" | "onBusinessError" | "onFailure" | "messages">): (error: unknown, input?: Partial<ErrorContext>) => void;

package/dist/error-handler.js

@@ -1,6 +1,8 @@
-import { isRequestCancelled, ApiError, errorDefinitions } from "./errors.js";
+import { isRequestCancelled, ApiError } from "./errors.js";
+import { sdkError, sdkMessage } from "./sdk-error.js";
 import { toSafeDiagnostics } from "./diagnostics.js";
 const handled = /* @__PURE__ */ new WeakSet();
+const mutationResultUncertain = "暂时无法确认操作结果，请保留输入并检查结果后再重试。";
 function createErrorHandler(config) {
   function callback(run) {
     try {
@@ -14,7 +16,8 @@ function createErrorHandler(config) {
   }
   return function handleError(error, input = {}) {
     if (isRequestCancelled(error) || error && typeof error === "object" && handled.has(error)) return;
-    const apiError = error instanceof ApiError ? error : new ApiError({ status: 0, code: "INTERNAL_ERROR", message: errorDefinitions.INTERNAL_ERROR, kind: "response" });
+    const apiError = error instanceof ApiError ? error : sdkError("INTERNAL_ERROR", { status: 0, kind: "response" });
+    const message = sdkMessage(apiError, config.messages);
     const method = apiError.context?.method;
     const context = {
       intent: input.intent ?? (method === "GET" || method === "HEAD" ? "read" : "mutation"),
@@ -34,7 +37,7 @@ function createErrorHandler(config) {
     if (error && typeof error === "object") handled.add(error);
     const uncertain = context.intent === "mutation" && (apiError.kind === "network" || apiError.kind === "timeout");
     callback(() => config.notify?.({
-      message: uncertain ? "暂时无法确认操作结果，请保留输入并检查结果后再重试。" : apiError.message,
+      message: uncertain ? config.messages?.MUTATION_RESULT_UNCERTAIN ?? mutationResultUncertain : message,
       requestId: apiError.requestId,
       id: apiError.kind === "network" || apiError.kind === "timeout" ? "http-network" : void 0
     }));

package/dist/errors.d.ts

@@ -23,8 +23,11 @@ export type ApiErrorOptions<T = unknown> = {
     kind?: ApiErrorKind;
     retryAfterMs?: number;
     context?: RequestContext;
+    cause?: unknown;
 };
 export declare class ApiError<T = unknown> extends Error {
+    /** 跨 SDK 实例识别 ApiError；子类（如目录的 HttpError）仍按原型链判断。 */
+    static [Symbol.hasInstance](value: unknown): boolean;
     readonly status: number;
     readonly code: string;
     readonly requestId?: string;

package/dist/errors.js

@@ -11,7 +11,13 @@ const errorDefinitions = {
   INTERNAL_ERROR: "服务暂时无法完成请求，请稍后重试。",
   HTTP_ERROR: "请求未能完成，请检查后重试。"
 };
+const apiErrorBrand = Symbol.for("@springbrand/http.ApiError");
 class ApiError extends Error {
+  /** 跨 SDK 实例识别 ApiError；子类（如目录的 HttpError）仍按原型链判断。 */
+  static [Symbol.hasInstance](value) {
+    if (this !== ApiError) return Function.prototype[Symbol.hasInstance].call(this, value);
+    return Boolean(value && typeof value === "object" && value[apiErrorBrand] === true);
+  }
   status;
   code;
   requestId;
@@ -21,7 +27,7 @@ class ApiError extends Error {
   retryAfterMs;
   context;
   constructor(options) {
-    super(options.message);
+    super(options.message, options.cause === void 0 ? void 0 : { cause: options.cause });
     this.name = "ApiError";
     this.status = options.status;
     this.code = options.code;
@@ -31,6 +37,7 @@ class ApiError extends Error {
     this.kind = options.kind ?? "http";
     this.retryAfterMs = options.retryAfterMs;
     this.context = options.context;
+    Object.defineProperty(this, apiErrorBrand, { value: true });
   }
 }
 function isRequestCancelled(error) {

package/dist/hono.d.ts

@@ -0,0 +1,50 @@
+import type { Context, TypedResponse } from "hono";
+import type { JSONParsed, JSONValue } from "hono/utils/types";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import type { ErrorDefinition, ErrorDefinitions, RequiredErrorCode } from "./catalog.js";
+import type { ApiError } from "./errors.js";
+import type { FieldError } from "./types.js";
+type CatalogError<D extends ErrorDefinitions, C extends keyof D & string> = ApiError & {
+    readonly code: C;
+    readonly status: D[C]["status"];
+};
+type SuccessResponse<T, S extends 200 | 201 | 202> = Response & TypedResponse<JSONParsed<{
+    success: true;
+    msg: T;
+    errMsg: "";
+    code: "";
+}>, S, "json">;
+type ErrorStatus<D extends ErrorDefinitions, C extends keyof D> = D[C]["status"] & ContentfulStatusCode;
+/** 显式写出响应类型：让 Hono 在泛型 C 未确定时推导 JSONParsed，会在声明文件里丢掉 code 字段。 */
+type ErrorResponse<D extends ErrorDefinitions, C extends keyof D & string> = Response & TypedResponse<{
+    errMsg: string;
+    code: C;
+    requestId?: string;
+    errors?: FieldError[];
+    details?: JSONValue;
+}, ErrorStatus<D, C>, "json">;
+/**
+ * 把 defineErrorCatalog 的结果接到 Hono。返回值保留 Hono 的 TypedResponse 类型，
+ * zod-openapi 可以检查每个路由声明的状态码和响应体。
+ * httpError 只接受本目录 HttpError 构造的错误；只属于客户端的码（status 0）无法构造。
+ * 失败响应会执行 `c.set("apiError", error)` 供请求日志读取；请求编号读自 `c.get("requestId")`。
+ */
+export declare function createHonoHttp<const D extends ErrorDefinitions & Record<RequiredErrorCode, ErrorDefinition>>(catalog: {
+    readonly definitions: D;
+    readonly HttpError: abstract new (...args: never[]) => ApiError;
+}): {
+    ok: {
+        <T>(c: Context, msg: T): SuccessResponse<T, 200>;
+        <T, S extends 200 | 201 | 202>(c: Context, msg: T, status: S): SuccessResponse<T, S>;
+    };
+    httpError: <C extends keyof D & string>(c: Context, error: CatalogError<D, C>) => ErrorResponse<D, C>;
+    httpErrorResponse: <C extends keyof D & string>(error: CatalogError<D, C>, options?: {
+        requestId?: string;
+    }) => Response;
+    httpUnauthorized: (c: Context, message?: string) => ErrorResponse<D, "AUTH_UNAUTHENTICATED">;
+    httpNotFound: (c: Context, message?: string) => ErrorResponse<D, "REQUEST_NOT_FOUND">;
+    httpRateLimited: (c: Context, message?: string) => ErrorResponse<D, "REQUEST_RATE_LIMITED">;
+    httpInternalError: (c: Context, message?: string) => ErrorResponse<D, "INTERNAL_ERROR">;
+    httpValidationError(c: Context, errors: FieldError[]): ErrorResponse<D, "REQUEST_VALIDATION_FAILED">;
+};
+export {};

package/dist/hono.js

@@ -0,0 +1,44 @@
+function createHonoHttp(catalog) {
+  const HttpError = catalog.HttpError;
+  function requestId(c) {
+    const value = c.get("requestId");
+    return typeof value === "string" ? value : void 0;
+  }
+  function errorBody(error, id) {
+    return {
+      errMsg: error.message,
+      code: error.code,
+      ...id ? { requestId: id } : {},
+      ...error.errors ? { errors: error.errors } : {},
+      ...error.details !== void 0 ? { details: error.details } : {}
+    };
+  }
+  function ok(c, msg, status = 200) {
+    return c.json({ success: true, msg, errMsg: "", code: "" }, status);
+  }
+  function httpError(c, error) {
+    c.set("apiError", error);
+    return c.json(errorBody(error, requestId(c)), error.status);
+  }
+  function httpErrorResponse(error, options = {}) {
+    return Response.json(errorBody(error, options.requestId), { status: error.status });
+  }
+  function shortcut(code) {
+    return (c, message) => httpError(c, new HttpError(code, message));
+  }
+  return {
+    ok,
+    httpError,
+    httpErrorResponse,
+    httpUnauthorized: shortcut("AUTH_UNAUTHENTICATED"),
+    httpNotFound: shortcut("REQUEST_NOT_FOUND"),
+    httpRateLimited: shortcut("REQUEST_RATE_LIMITED"),
+    httpInternalError: shortcut("INTERNAL_ERROR"),
+    httpValidationError(c, errors) {
+      return httpError(c, new HttpError("REQUEST_VALIDATION_FAILED", void 0, { errors }));
+    }
+  };
+}
+export {
+  createHonoHttp
+};

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { ApiError, errorDefinitions, isApiError, isRequestCancelled, isTransientHttpError } from "./errors.js";
 export type { ApiErrorOptions, ApiErrorKind } from "./errors.js";
-export type { ApiSuccessResponse, HttpErrorResponse, FieldError, HttpResult, ErrorContext, RequestNotice, RequestFailure, HttpClientConfig, HttpRequestOptions, HttpMethod, ResponseMode } from "./types.js";
+export type { ApiSuccessResponse, HttpErrorResponse, FieldError, HttpResult, ErrorContext, RequestNotice, RequestFailure, HttpClientConfig, HttpMessages, HttpRequestOptions, HttpMethod, ResponseMode } from "./types.js";

package/dist/response.js

@@ -1,4 +1,5 @@
-import { ApiError, errorDefinitions } from "./errors.js";
+import { ApiError } from "./errors.js";
+import { sdkError } from "./sdk-error.js";
 const record = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
 function parseRetryAfter(value) {
   if (!value) return void 0;
@@ -10,14 +11,10 @@ function parseHttpError(data, info) {
   const body = record(data) ? data : {};
   const valid = typeof body.code === "string" && /^[A-Z][A-Z0-9_]{0,127}$/.test(body.code) && typeof body.errMsg === "string";
   const errors = Array.isArray(body.errors) ? body.errors.filter((item) => record(item) && typeof item.path === "string" && typeof item.errMsg === "string").slice(0, 100).map((item) => ({ path: item.path.slice(0, 256), errMsg: item.errMsg.slice(0, 2048) })) : void 0;
-  return new ApiError({
-    status: info.status,
-    code: valid ? body.code : info.status >= 500 ? "INTERNAL_ERROR" : "HTTP_ERROR",
-    message: valid ? body.errMsg.slice(0, 4096) : info.status >= 500 ? errorDefinitions.INTERNAL_ERROR : errorDefinitions.HTTP_ERROR,
-    requestId: typeof body.requestId === "string" ? body.requestId.slice(0, 256) : info.headers["x-request-id"],
-    errors: valid ? errors : void 0,
-    retryAfterMs: parseRetryAfter(info.headers["retry-after"])
-  });
+  const requestId = typeof body.requestId === "string" ? body.requestId.slice(0, 256) : info.headers["x-request-id"];
+  const retryAfterMs = parseRetryAfter(info.headers["retry-after"]);
+  if (!valid) return sdkError(info.status >= 500 ? "INTERNAL_ERROR" : "HTTP_ERROR", { status: info.status, requestId, retryAfterMs });
+  return new ApiError({ status: info.status, code: body.code, message: body.errMsg.slice(0, 4096), requestId, errors, retryAfterMs });
 }
 async function readBody(body, info, limit) {
   if (!body) return [];
@@ -25,12 +22,12 @@ async function readBody(body, info, limit) {
   const chunks = [];
   let bytes = 0;
   try {
-    if (Number(info.headers["content-length"]) > limit) throw new ApiError({ status: info.status, code: "RESPONSE_TOO_LARGE", message: errorDefinitions.RESPONSE_TOO_LARGE, kind: "response", requestId: info.headers["x-request-id"] });
+    if (Number(info.headers["content-length"]) > limit) throw sdkError("RESPONSE_TOO_LARGE", { status: info.status, kind: "response", requestId: info.headers["x-request-id"] });
     let chunk = await reader.read();
     while (!chunk.done) {
       const value = chunk.value;
       bytes += value.byteLength;
-      if (bytes > limit) throw new ApiError({ status: info.status, code: "RESPONSE_TOO_LARGE", message: errorDefinitions.RESPONSE_TOO_LARGE, kind: "response", requestId: info.headers["x-request-id"] });
+      if (bytes > limit) throw sdkError("RESPONSE_TOO_LARGE", { status: info.status, kind: "response", requestId: info.headers["x-request-id"] });
       chunks.push(value);
       chunk = await reader.read();
     }
@@ -56,7 +53,7 @@ function decodeBody(chunks, mode, info, config) {
       try {
         value = text ? JSON.parse(text) : void 0;
       } catch {
-        throw new ApiError({ status: info.status, code: "RESPONSE_INVALID", message: errorDefinitions.RESPONSE_INVALID, kind: "response", requestId: info.headers["x-request-id"] });
+        throw sdkError("RESPONSE_INVALID", { status: info.status, kind: "response", requestId: info.headers["x-request-id"] });
       }
     }
   }
@@ -65,12 +62,12 @@ function decodeBody(chunks, mode, info, config) {
       return config.decodeResponse(value, info);
     } catch (error) {
       if (error instanceof ApiError) throw error;
-      throw new ApiError({ status: info.status, code: "RESPONSE_INVALID", message: errorDefinitions.RESPONSE_INVALID, kind: "response", requestId: info.headers["x-request-id"] });
+      throw sdkError("RESPONSE_INVALID", { status: info.status, kind: "response", requestId: info.headers["x-request-id"] });
     }
   }
   if (mode !== "envelope") return value;
   if (record(value) && value.success === true && Object.hasOwn(value, "msg")) return value.msg;
-  throw new ApiError({ status: info.status, code: "RESPONSE_INVALID", message: errorDefinitions.RESPONSE_INVALID, kind: "response", requestId: info.headers["x-request-id"] });
+  throw sdkError("RESPONSE_INVALID", { status: info.status, kind: "response", requestId: info.headers["x-request-id"] });
 }
 function errorBody(chunks) {
   try {

package/dist/sdk-error.d.ts

@@ -0,0 +1,10 @@
+import { ApiError, errorDefinitions, type ApiErrorOptions } from "./errors.js";
+import type { HttpMessages } from "./types.js";
+type SdkErrorCode = keyof typeof errorDefinitions;
+/** SDK 生成的错误使用默认文案，并登记为可被消费者文案替换。 */
+export declare function sdkError(code: SdkErrorCode, options: Omit<ApiErrorOptions, "code" | "message">): ApiError;
+/** 服务端返回的 errMsg 保持原样，只替换 SDK 自身产生的默认文案。 */
+export declare function sdkMessage(error: ApiError, messages: HttpMessages | undefined): string;
+/** 重新包装 SDK 错误时保留“默认文案”标记。 */
+export declare function keepSdkDefault(from: ApiError, to: ApiError): ApiError;
+export {};

package/dist/sdk-error.js

@@ -0,0 +1,20 @@
+import { ApiError, errorDefinitions } from "./errors.js";
+const defaultMessage = /* @__PURE__ */ new WeakSet();
+function sdkError(code, options) {
+  const error = new ApiError({ ...options, code, message: errorDefinitions[code] });
+  defaultMessage.add(error);
+  return error;
+}
+function sdkMessage(error, messages) {
+  if (!defaultMessage.has(error)) return error.message;
+  return messages?.[error.code] ?? error.message;
+}
+function keepSdkDefault(from, to) {
+  if (defaultMessage.has(from)) defaultMessage.add(to);
+  return to;
+}
+export {
+  keepSdkDefault,
+  sdkError,
+  sdkMessage
+};

package/dist/server/body.d.ts

@@ -0,0 +1,10 @@
+/** 解析未校验的请求 JSON；语法错误是 400，不能变成 500。 */
+export declare function readJson(request: Request): Promise<unknown>;
+/** 按实际读取的字节数限制请求或响应体，不信任 Content-Length。 */
+export declare function readBytesLimited(input: Request | Response, maxBytes: number): Promise<Uint8Array>;
+/** 计数后重建请求，供中间件在交给后续处理器前限制请求体。 */
+export declare function limitRequestBody(request: Request, maxBytes: number): Promise<Request>;
+/** 限长读取请求 JSON。 */
+export declare function readJsonLimited(request: Request, maxBytes: number): Promise<unknown>;
+/** 从 If-Match 读取一个带引号的正整数版本，例如 "3"。 */
+export declare function requireIfMatchRevision(request: Request, subject: string): number;

package/dist/server/body.js

@@ -0,0 +1,66 @@
+import { ApiError } from "../errors.js";
+const invalidJson = (cause) => new ApiError({ status: 400, code: "REQUEST_INVALID_JSON", message: "Expected a JSON object", kind: "http", cause });
+const tooLarge = () => new ApiError({ status: 413, code: "REQUEST_PAYLOAD_TOO_LARGE", message: "Request body is too large", kind: "http" });
+async function readJson(request) {
+  try {
+    return await request.json();
+  } catch (cause) {
+    if (!(cause instanceof SyntaxError)) throw cause;
+    throw invalidJson(cause);
+  }
+}
+async function readBytesLimited(input, maxBytes) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) throw new RangeError("maxBytes must be a non-negative safe integer");
+  if (!input.body) return new Uint8Array();
+  const reader = input.body.getReader();
+  const chunks = [];
+  let bytes = 0;
+  try {
+    for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) {
+      bytes += chunk.value.byteLength;
+      if (bytes > maxBytes) {
+        await reader.cancel();
+        throw tooLarge();
+      }
+      chunks.push(chunk.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const body = new Uint8Array(bytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return body;
+}
+async function limitRequestBody(request, maxBytes) {
+  if (!request.body) return request;
+  const body = await readBytesLimited(request, maxBytes);
+  return new Request(request, { body, duplex: "half" });
+}
+async function readJsonLimited(request, maxBytes) {
+  const body = await readBytesLimited(request, maxBytes);
+  try {
+    return JSON.parse(new TextDecoder().decode(body));
+  } catch (cause) {
+    if (!(cause instanceof SyntaxError)) throw cause;
+    throw invalidJson(cause);
+  }
+}
+function requireIfMatchRevision(request, subject) {
+  const match = /^"([1-9]\d*)"$/.exec(request.headers.get("if-match") ?? "");
+  const revision = match ? Number(match[1]) : Number.NaN;
+  if (!Number.isSafeInteger(revision)) {
+    throw new ApiError({ status: 400, code: "REQUEST_INVALID_INPUT", message: `If-Match must contain the current ${subject}, for example "3"`, kind: "http" });
+  }
+  return revision;
+}
+export {
+  limitRequestBody,
+  readBytesLimited,
+  readJson,
+  readJsonLimited,
+  requireIfMatchRevision
+};

package/dist/server/content-disposition.d.ts

@@ -0,0 +1,2 @@
+/** 生成兼容非 ASCII 文件名的 Content-Disposition 响应头。 */
+export declare function contentDispositionHeader(filename: string, type?: "attachment" | "inline"): string;

package/dist/server/content-disposition.js

@@ -0,0 +1,7 @@
+import { create } from "content-disposition";
+function contentDispositionHeader(filename, type = "attachment") {
+  return create(filename, { type });
+}
+export {
+  contentDispositionHeader
+};

package/dist/server/error-diagnostics.d.ts

@@ -0,0 +1,7 @@
+/** 遮蔽凭据，但不截断调用方提供的诊断文本。 */
+export declare function redactSensitiveText(text: string): string;
+/**
+ * 服务端日志用的异常投影：保留 cause 链和调用栈，不序列化 SQL、参数或请求体。
+ * 带 query/params 的数据库异常只记录固定文案。
+ */
+export declare function errorDiagnostics(error: unknown, depth?: number): Record<string, unknown> | undefined;

package/dist/server/error-diagnostics.js

@@ -0,0 +1,25 @@
+function redactSensitiveText(text) {
+  return text.replace(/Bearer\s+[^\s"']+/gi, "Bearer [Redacted]").replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+:[^\s/@]+@/gi, "$1[Redacted]@").replace(/(["']?(?:password|secret|token|api[_-]?key|authorization)["']?\s*[=:]\s*)(?:"[^"\n]*"|'[^'\n]*'|[^\s&,;]+)/gi, "$1[Redacted]").replace(/\beyJ[\w-]+\.[\w-]+\.[\w-]+\b/g, "[Redacted JWT]");
+}
+const redact = (text) => redactSensitiveText(text).slice(0, 1e3);
+function errorDiagnostics(error, depth = 0) {
+  if (!(error instanceof Error) || depth >= 5) return void 0;
+  const fields = error;
+  const databaseQuery = "query" in error || "params" in error;
+  const code = typeof fields.code === "string" && /^[A-Za-z0-9_]{1,80}$/.test(fields.code) ? fields.code : void 0;
+  return {
+    name: error.name,
+    message: databaseQuery ? "Database query failed" : error instanceof SyntaxError ? "Invalid syntax" : redact(error.message),
+    ...code ? { code } : {},
+    ...typeof fields.requestId === "string" ? { providerRequestId: redact(fields.requestId) } : {},
+    ...typeof fields.statusCode === "number" ? { providerStatus: fields.statusCode } : {},
+    stack: error.stack?.split("\n").filter((line) => /^\s+at /.test(line)).slice(0, 12).map(redact).join("\n"),
+    ...typeof fields.upstreamStatus === "number" ? { upstreamStatus: fields.upstreamStatus } : {},
+    ...typeof fields.upstreamRequestId === "string" ? { upstreamRequestId: redact(fields.upstreamRequestId) } : {},
+    cause: errorDiagnostics(error.cause, depth + 1)
+  };
+}
+export {
+  errorDiagnostics,
+  redactSensitiveText
+};

package/dist/server/index.d.ts

@@ -1,4 +1,7 @@
 export { ok, fail, toErrorResponse } from "./response.js";
 export type { ServerResponseOptions, HttpFailureInput } from "./response.js";
 export { createServiceRequest, verifyServiceToken, SERVICE_TOKEN_HEADER } from "./service-auth.js";
+export { readJson, readJsonLimited, readBytesLimited, limitRequestBody, requireIfMatchRevision } from "./body.js";
+export { contentDispositionHeader } from "./content-disposition.js";
+export { errorDiagnostics, redactSensitiveText } from "./error-diagnostics.js";
 export { toSafeDiagnostics } from "../diagnostics.js";

package/dist/server/index.js

@@ -1,11 +1,22 @@
 import { fail, ok, toErrorResponse } from "./response.js";
 import { SERVICE_TOKEN_HEADER, createServiceRequest, verifyServiceToken } from "./service-auth.js";
+import { limitRequestBody, readBytesLimited, readJson, readJsonLimited, requireIfMatchRevision } from "./body.js";
+import { contentDispositionHeader } from "./content-disposition.js";
+import { errorDiagnostics, redactSensitiveText } from "./error-diagnostics.js";
 import { toSafeDiagnostics } from "../diagnostics.js";
 export {
   SERVICE_TOKEN_HEADER,
+  contentDispositionHeader,
   createServiceRequest,
+  errorDiagnostics,
   fail,
+  limitRequestBody,
   ok,
+  readBytesLimited,
+  readJson,
+  readJsonLimited,
+  redactSensitiveText,
+  requireIfMatchRevision,
   toErrorResponse,
   toSafeDiagnostics,
   verifyServiceToken

package/dist/server/service-auth.d.ts

@@ -1,3 +1,10 @@
 export declare const SERVICE_TOKEN_HEADER = "X-SpringBrand-Service-Token";
-export declare function createServiceRequest(baseUrl: string, token: string, path: string | URL, init?: RequestInit): Request;
+/**
+ * 构造绑定来源的服务请求。传入 Request 时会转发它的方法、请求头、请求体和 signal；
+ * 同源 URL 原样使用，其他来源只保留路径和查询参数并绑定到 baseUrl。
+ * 默认删除用户的 Authorization 和 Cookie；只有下游需要按调用者身份鉴权时，才显式传 forwardAuthorization。
+ */
+export declare function createServiceRequest(baseUrl: string | URL, token: string, input: string | URL | Request, init?: RequestInit, behavior?: {
+    forwardAuthorization?: boolean;
+}): Request;
 export declare function verifyServiceToken(provided: string | null | undefined, expected: string): Promise<boolean>;

package/dist/server/service-auth.js

@@ -1,13 +1,28 @@
-import { boundUrl, serviceUrl } from "../url.js";
+import { serviceUrl, boundUrl } from "../url.js";
 const SERVICE_TOKEN_HEADER = "X-SpringBrand-Service-Token";
-function createServiceRequest(baseUrl, token, path, init = {}) {
+function createServiceRequest(baseUrl, token, input, init = {}, behavior = {}) {
   if (!token.trim()) throw new TypeError("Service token is required");
-  const url = boundUrl(serviceUrl(baseUrl), path);
-  const headers = new Headers(init.headers);
-  headers.delete("Authorization");
+  const base = serviceUrl(String(baseUrl));
+  const source = input instanceof Request ? input : void 0;
+  let path = source ? new URL(source.url) : input;
+  if (path instanceof URL && source && path.origin !== base.origin) path = `${path.pathname}${path.search}`;
+  const url = boundUrl(base, path);
+  const headers = new Headers(source?.headers);
+  new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+  if (!behavior.forwardAuthorization) headers.delete("Authorization");
   headers.delete("Cookie");
   headers.set(SERVICE_TOKEN_HEADER, token);
-  const options = { ...init, headers, cache: "no-store", redirect: "manual" };
+  const body = init.body !== void 0 ? init.body : source?.body ?? null;
+  const options = {
+    ...init,
+    method: init.method ?? source?.method ?? "GET",
+    headers,
+    body,
+    signal: init.signal ?? source?.signal ?? null,
+    cache: "no-store",
+    redirect: "manual"
+  };
+  if (body instanceof ReadableStream) options.duplex = "half";
   if ("credentials" in Request.prototype) options.credentials = "omit";
   else delete options.credentials;
   return new Request(url, options);

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { ApiError } from "./errors.js";
+import type { ApiError, errorDefinitions } from "./errors.js";
 export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
 export type ResponseMode = "envelope" | "json" | "text" | "blob";
 export type Feedback = "auto" | "inline" | "silent";
@@ -77,6 +77,8 @@ export type HttpRequestOptions = {
     idempotencyKey?: string;
     onUploadProgress?: (progress: UploadProgress) => void;
 };
+/** 替换 SDK 自身产生的提示文案；服务端返回的 errMsg 不受影响。 */
+export type HttpMessages = Partial<Record<keyof typeof errorDefinitions | "MUTATION_RESULT_UNCERTAIN", string>>;
 export type HttpClientConfig = {
     baseUrl: string;
     timeoutMs?: number;
@@ -88,11 +90,16 @@ export type HttpClientConfig = {
     decodeResponse?: (data: unknown, info: ResponseInfo) => unknown;
     decodeError?: (data: unknown, info: ResponseInfo) => ApiError;
     isUnauthorized?: (error: ApiError) => boolean;
-    onUnauthorized?: (error: ApiError) => void;
+    /**
+     * 当前 Bearer 被确认失效时调用。同一 token 的重复失效只处理一次：
+     * 返回 Promise 时，Promise 完成后恢复处理（例如复检会话后 token 仍有效）；返回 void 时直到 token 变化。
+     */
+    onUnauthorized?: (error: ApiError) => void | Promise<unknown>;
     notify?: (notice: RequestNotice) => void;
     onBusinessError?: (error: ApiError, context: ErrorContext) => boolean;
     feedbackOwner?: FeedbackOwner;
     onFailure?: (failure: RequestFailure) => void;
+    messages?: HttpMessages;
     /** 注入标准 Fetch，便于测试或适配宿主；请求仍由 Axios 执行。 */
     fetch?: typeof globalThis.fetch;
 };

package/dist/url.js

@@ -1,6 +1,6 @@
-import { ApiError, errorDefinitions } from "./errors.js";
+import { sdkError } from "./sdk-error.js";
 function invalidUrl() {
-  throw new ApiError({ status: 0, code: "REQUEST_INVALID_INPUT", message: errorDefinitions.REQUEST_INVALID_INPUT, kind: "input" });
+  throw sdkError("REQUEST_INVALID_INPUT", { status: 0, kind: "input" });
 }
 function serviceUrl(baseUrl) {
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/http",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "license": "MIT",
   "type": "module",
   "publishConfig": {
@@ -38,6 +38,16 @@
       "import": "./dist/query.js",
       "default": "./dist/query.js"
     },
+    "./catalog": {
+      "types": "./dist/catalog.d.ts",
+      "import": "./dist/catalog.js",
+      "default": "./dist/catalog.js"
+    },
+    "./hono": {
+      "types": "./dist/hono.d.ts",
+      "import": "./dist/hono.js",
+      "default": "./dist/hono.js"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "import": "./dist/server/index.js",
@@ -45,31 +55,42 @@
     },
     "./package.json": "./package.json"
   },
-  "scripts": {
-    "build": "vite build && tsc -p tsconfig.build.json",
-    "watch": "vite build --watch",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src tests --ext ts --max-warnings 0",
-    "test": "vitest run"
-  },
   "dependencies": {
-    "axios": "1.20.0"
+    "axios": "1.20.0",
+    "content-disposition": "2.0.1"
   },
   "peerDependencies": {
-    "@tanstack/react-query": "^5.104.1"
+    "@tanstack/react-query": "^5.104.1",
+    "hono": "^4.12.0",
+    "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-query": {
       "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@tanstack/react-query": "5.104.1",
     "@types/node": "^20.8.3",
     "esbuild": "0.27.7",
+    "hono": "4.12.33",
     "miniflare": "5.20260910.0-alpha",
     "typescript": "^5.0.2",
     "vite": "^5.4.19",
-    "vitest": "3.2.6"
+    "vitest": "3.2.6",
+    "zod": "4.6.5"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "watch": "vite build --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests --ext ts --max-warnings 0",
+    "test": "vitest run"
   }
-}
+}