@springbrand/http 0.1.0-alpha.1 → 0.1.0-alpha.10

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

@@ -1,10 +1,12 @@
 ---
 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
 
+Shared error codes, canonical statuses and their HTTP statuses are defined in `@springbrand/errors`; this package reads them and does not restate them. `@springbrand/errors` is a peer dependency accepting any version: the consumer installs it directly and its version is the one HTTP uses.
+
 Read the installed declarations and README before configuring a client. Public entry points own different runtime needs; import only the capability needed.
 
 | Entry point | Responsibility |
@@ -13,15 +15,18 @@ 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). Codes registered in `@springbrand/errors` must use the registered HTTP status |
+| @springbrand/http/hono | Hono responders with TypedResponse types for zod-openapi (hono peer) |
+| @springbrand/http/types | Type-only entry for every public type, so consumers emitting declarations stay portable |
+| @springbrand/http/server | Standard Response helpers, bounded body reading, If-Match, Content-Disposition, log diagnostics and service authentication |
 
 ## Client setup
 
-Create one client per trusted API origin. Inject getToken; do not copy Token storage or Bearer construction into requests. Relative paths include the configured base path. Foreign origins and URL credentials are rejected. Defaults are Cookie omit, 15-second deadline and 10-MiB response limit.
+Create one client per trusted API origin. Inject getToken; do not copy Token storage or Bearer construction into requests. Relative paths include the configured base path. Foreign origins and URL credentials are rejected. Defaults are Cookie omit, no-store cache, manual redirects, 15-second deadline and 10-MiB response limit. The Fetch adapter supports browsers, Node.js 24 and Cloudflare Workers. Redirects reject with REQUEST_REDIRECT_BLOCKED, including opaque browser redirects; never enable automatic redirects for credential-bearing API calls.
 
 Pass params for query serialization and signal/timeoutMs for cancellation/deadlines. Null/undefined query values are omitted; use a string for literal null. Do not duplicate query encoding or timeout controllers in domain clients.
 
-Use get/post/put/patch/delete for payloads, request for data plus status and headers. Explicitly choose json, text or blob for endpoints without the standard success envelope. FormData owns its boundary. Pass Query's signal through; do not wrap cancellation as network failure.
+Use get/post/put/patch/delete for payloads, request for data plus status and headers. Explicitly choose json, text or blob for endpoints without the standard success envelope. FormData owns its boundary. In a browser, a request with onUploadProgress goes through XMLHttpRequest, because fetch upload progress needs a streamed body that Chrome sends only over HTTP/2; a redirect it followed still rejects with REQUEST_REDIRECT_BLOCKED. The client sends no User-Agent of its own (Safari and Firefox would otherwise require every cross-origin API to allow it in CORS); set one explicitly only for a server-to-server call that needs it. Pass Query's signal through; do not wrap cancellation as network failure.
 
 ## Error handling
 
@@ -31,14 +36,32 @@ Choose one feedback owner: client for direct calls, query for Query/Mutation. In
 
 Use isTransientHttpError from the core or errors entry point for cached-view recovery, matching the Query retry classifier. Network, timeout and HTTP 429/502/503/504 are transient; cancellation, decoding, auth and permission errors are not. Classification never authorizes replaying writes.
 
+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. 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
 
-Exercise transient read recovery, write uncertainty, field errors, cancellation, Token changes and callback failures. Verify server imports without React Query and packaged public entry points. Use HTTP Storybook examples as behavior references, not copied implementations. Do not add app-local parallel clients or edit installed node_modules.
+Exercise transient read recovery, write uncertainty, field errors, cancellation, Token changes and callback failures. Run the Miniflare/workerd regression with mocked outbound services; Node-only Fetch tests do not prove Worker compatibility. Verify server imports without React Query and packaged public entry points. Use HTTP Storybook examples as behavior references, not copied implementations. Do not add app-local parallel clients or edit installed node_modules.

package/README.md

@@ -1,13 +1,15 @@
 # SpringBrand HTTP SDK
 
-一个包提供共享 HTTP 合同、Axios 客户端、Query 接入和框架无关的服务端辅助函数。错误规则由 SDK 维护，消费者提供 Token、通知和业务回调。
+一个包提供共享 HTTP 合同、Axios 客户端、Query 接入、错误码目录、Hono 接入和框架无关的服务端辅助函数。错误规则由 SDK 维护，消费者提供 Token、通知和业务回调。
 
 ## 安装
 
 ```sh
-pnpm add @springbrand/http@alpha
+pnpm add @springbrand/http@alpha @springbrand/errors@alpha
 ```
 
+`@springbrand/errors` 是 peer 依赖，接受任意版本：由使用方安装并决定版本，HTTP 包直接使用它，不需要为 errors 更新而重新发布。
+
 使用 Query 入口时，另外安装兼容的 `@tanstack/react-query`。
 
 ## 入口
@@ -18,9 +20,12 @@ 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/types` | 只含类型的入口：公共 API 用到的全部类型，供开启 declaration 的使用方生成可移植的声明文件 |
+| `@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 或兼容运行时。
 
 ## 请求实例
 
@@ -39,7 +44,7 @@ const items = await api.get<Item[]>('/items');
 await api.post('/items', { name: 'Example' });
 ```
 
-Token 每次发送时读取。实例只向绑定来源发送请求；非法地址、带用户名密码的 URL 和其他来源的绝对 URL 会在发送前失败。`baseUrl` 的路径前缀会与相对接口路径拼接。
+Token 每次发送时读取。实例使用 `cache: no-store` 和 `redirect: manual`，兼容浏览器、Node.js 24 和 Cloudflare Workers。API 重定向（含浏览器 opaque redirect）以 REQUEST_REDIRECT_BLOCKED 拒绝，不跟随跳转；Query 缓存仍由 Query 管理。实例只向绑定来源发送请求；非法地址、带用户名密码的 URL 和其他来源的绝对 URL 会在发送前失败。`baseUrl` 的路径前缀会与相对接口路径拼接。
 
 客户端使用 Axios Fetch Adapter，默认 `credentials: 'omit'`。Cookie 登录使用显式 `credentials: 'include'` 的独立实例。`auth: false` 关闭 SDK 的 Bearer 注入，Cookie 策略不随之改变。有 getToken 时，SDK 管理 Authorization，额外请求头不能覆盖它。
 
@@ -54,7 +59,7 @@ const file = await api.request<Blob>('/download', { responseMode: 'blob' });
 const filenameHeader = file.headers['content-disposition'];
 ```
 
-普通 JSON、文本和 Blob 分别使用 json、text、blob 模式。GET 和 HEAD 不接受请求体。FormData 不手工设置 multipart boundary。
+普通 JSON、文本和 Blob 分别使用 json、text、blob 模式。GET 和 HEAD 不接受请求体。FormData 不手工设置 multipart boundary。浏览器里传了 onUploadProgress 的请求改用 XMLHttpRequest 发送：fetch 要报上传进度只能流式发送请求体，Chrome 只在 HTTP/2 上允许，HTTP/1.1 会报 ERR_ALPN_NEGOTIATION_FAILED。XMLHttpRequest 自动跟随的重定向同样以 REQUEST_REDIRECT_BLOCKED 拒绝。
 
 默认超时 15 秒，覆盖 timeoutMs，0 表示关闭超时。默认最大响应 10 MiB，覆盖 maxResponseBytes；0 仅允许空内容。客户端在读取数据流时检查实际字节数，超限取消读取。第一版不暴露无限流、SSE 或原生 Response 合同。
 
@@ -119,9 +124,17 @@ if (query.data !== undefined && isTransientHttpError(query.error)) {
 
 查询参数直接传 `params`，由 SDK 编码：数组发送重复参数，null 和 undefined 省略。需要字面值 null 的业务字段应传字符串 `'null'`。传入 `signal` 和 `timeoutMs` 即可取消或设置超时，无需在业务包再创建超时控制器。
 
-主动写入的网络失败会提示结果暂时无法确认，不自动重发。取消保持取消语义，不包装成 NETWORK_ERROR。超时为 REQUEST_TIMEOUT，格式错误为 RESPONSE_INVALID，内容超限为 RESPONSE_TOO_LARGE。
+主动写入的网络失败会提示结果暂时无法确认，不自动重发。取消保持取消语义，不包装成 NETWORK_ERROR。超时为 REQUEST_TIMEOUT，格式错误为 RESPONSE_INVALID，内容超限为 RESPONSE_TOO_LARGE。请求运行时不支持所需能力时为 RUNTIME_UNSUPPORTED（kind: runtime），与非法调用参数 REQUEST_INVALID_INPUT 分开；运行时和重定向错误不重试、不清理登录。
+
+默认仅 401 且 AUTH_UNAUTHENTICATED 触发失效回调；这类登录失效交给认证流程，不论请求是否携带 Token 都不弹通用提示。单个请求的提示方式用 `feedback`（auto、inline、silent）控制。onUnauthorized 返回 Promise 时（例如复检会话），复检期间同一 Token 的重复失效只处理一次，Promise 完成后恢复处理；返回 void 时直到 Token 变化。旧身份的响应不清理新身份，同一 Token 并发失效仅处理一次；网络错误、其他 401 和 403 不退出登录。默认自动处理针对实例携带的 Bearer 身份，Cookie 会话的恢复流程由消费者掌握。
 
-默认仅 401 且 AUTH_UNAUTHENTICATED 触发失效回调。旧身份的响应不清理新身份，同一 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 +149,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 +221,11 @@ ok 支持 200、201、202；无内容成功直接用标准 Response。fail 只
 
 toErrorResponse 公开标准 ApiError 的安全信息，未知异常返回固定 500 INTERNAL_ERROR。业务错误和 details 在 HTTP 处理器中翻译和验证。
 
-createServiceRequest 为绑定来源构造服务请求，清理用户 Authorization 和 Cookie，注入 X-SpringBrand-Service-Token。verifyServiceToken 比较等长摘要。服务请求不跟随重定向，不使用用户 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 的登录失效流程。
 
 ## 验证与示例
 
@@ -161,6 +237,6 @@ pnpm --filter @springbrand/http build
 pnpm build-storybook
 ```
 
-Storybook 的 HTTP 分类包含成功、后台恢复、首次失败、字段错误、业务扩展、认证、取消、动态 Token 和上传下载。模拟服务仍通过真实 Axios 请求实现。
+Storybook 的 HTTP 分类包含成功、后台恢复、首次失败、字段错误、业务扩展、认证、取消、动态 Token 和上传下载。模拟服务仍通过真实 Axios 请求实现。tests/worker.test.ts 使用 Miniflare/workerd 执行真正的 Worker，验证 JSON、Token、服务凭据及重定向保护；测试不会访问真实供应商。
 
 完整设计位于 dune-react 的 trevordocs/axios-request-sdk-architecture.md。预发布版本使用 npm 的 alpha 标签，业务项目的迁移由各项目独立安排。

package/dist/catalog.d.ts

@@ -0,0 +1,113 @@
+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;
+};
+export 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>>;

package/dist/catalog.js

@@ -0,0 +1,135 @@
+import { isRegisteredErrorCode, httpStatusOf } from "@springbrand/errors";
+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`);
+    }
+    if (isRegisteredErrorCode(code) && definition.status !== (httpStatusOf(code) ?? 0)) {
+      throw new RangeError(`Error ${code} must use status ${httpStatusOf(code) ?? 0} registered in @springbrand/errors`);
+    }
+  }
+  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";
@@ -13,7 +14,8 @@ function createHttpClient(config) {
     responseType: "stream",
     timeout: 0,
     withCredentials: config.credentials === "same-origin" ? void 0 : config.credentials === "include",
-    fetchOptions: { redirect: "error" }
+    // Workers rejects explicit cache: default and redirect: error. Never follow API redirects.
+    fetchOptions: { cache: "no-store", redirect: "manual" }
   });
   const handleError = createErrorHandler(config);
   let rejectedToken;
@@ -29,19 +31,23 @@ function createHttpClient(config) {
     const method = options.method ?? "GET";
     const context = { method, feedback: options.feedback ?? "auto", feedbackOwner: options.feedbackOwner ?? config.feedbackOwner ?? "client" };
     const controller = new AbortController();
-    const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+    const signal = controller.signal;
+    const caller = options.signal;
+    const forward = () => controller.abort(caller?.reason);
+    if (caller?.aborted) forward();
+    else caller?.addEventListener("abort", forward, { once: true });
     let timer;
     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));
@@ -53,15 +59,18 @@ 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");
+      if (!requestHeaders.has("User-Agent")) requestHeaders.set("User-Agent", false);
+      const viaXhr = options.onUploadProgress !== void 0 && typeof XMLHttpRequest !== "undefined";
+      if (options.body instanceof FormData) requestHeaders.set("Content-Type", viaXhr ? false : "multipart/form-data");
       const response = await transport.request({
         url: url.href,
         method,
         headers: requestHeaders,
         data: options.body,
         signal,
+        ...viaXhr ? { adapter: "xhr", responseType: "arraybuffer" } : {},
         onUploadProgress: options.onUploadProgress ? (progress) => {
           try {
             options.onUploadProgress?.({ loaded: progress.loaded, total: progress.total, progress: progress.progress });
@@ -71,11 +80,20 @@ function createHttpClient(config) {
         } : void 0
       });
       received = true;
+      const redirected = viaXhr && response.request?.responseURL !== url.href;
+      const body = response.data instanceof ArrayBuffer ? new Response(response.data).body : response.data;
       const responseHeaders = {};
       const rawHeaders = response.headers instanceof axios.AxiosHeaders ? response.headers.toJSON() : response.headers;
       for (const [key, value] of Object.entries(rawHeaders)) if (typeof value === "string" || typeof value === "number" || Array.isArray(value)) responseHeaders[key.toLowerCase()] = String(value);
       const info = { status: response.status, headers: responseHeaders };
-      const chunks = await readBody(response.data, info, limit);
+      if (redirected || response.status === 0 || response.status >= 300 && response.status < 400) {
+        try {
+          await body?.cancel();
+        } catch {
+        }
+        throw sdkError("REQUEST_REDIRECT_BLOCKED", { status: response.status, kind: "response", requestId: responseHeaders["x-request-id"] });
+      }
+      const chunks = await readBody(body, info, limit);
       if (signal.aborted) throw signal.reason;
       if (response.status < 200 || response.status >= 300) {
         const data2 = errorBody(chunks);
@@ -85,8 +103,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);
@@ -97,21 +115,26 @@ function createHttpClient(config) {
       const reason = signal.aborted ? signal.reason : error;
       if (signal.aborted && !(reason instanceof ApiError) && !(reason instanceof Error && reason.name === "TimeoutError")) throw reason;
       if (isRequestCancelled(reason)) throw reason;
-      const normalized = reason instanceof ApiError ? reason : new ApiError({
+      const runtimeUnsupported = axios.isAxiosError(reason) && (reason.code === axios.AxiosError.ERR_NOT_SUPPORT || !reason.request && reason.cause instanceof TypeError);
+      const timedOut = reason instanceof Error && reason.name === "TimeoutError";
+      const networkFailure = received || axios.isAxiosError(reason) && (reason.request instanceof Request || typeof XMLHttpRequest !== "undefined" && reason.request instanceof XMLHttpRequest);
+      const code = timedOut ? "REQUEST_TIMEOUT" : runtimeUnsupported ? "RUNTIME_UNSUPPORTED" : networkFailure ? "NETWORK_ERROR" : "REQUEST_INVALID_INPUT";
+      const normalized = reason instanceof ApiError ? reason : sdkError(code, {
         status: 0,
-        code: reason instanceof Error && reason.name === "TimeoutError" ? "REQUEST_TIMEOUT" : received || axios.isAxiosError(reason) && reason.request instanceof Request ? "NETWORK_ERROR" : "REQUEST_INVALID_INPUT",
-        message: reason instanceof Error && reason.name === "TimeoutError" ? errorDefinitions.REQUEST_TIMEOUT : received || axios.isAxiosError(reason) && reason.request instanceof Request ? errorDefinitions.NETWORK_ERROR : errorDefinitions.REQUEST_INVALID_INPUT,
-        kind: reason instanceof Error && reason.name === "TimeoutError" ? "timeout" : received || axios.isAxiosError(reason) && reason.request instanceof Request ? "network" : "input"
+        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) {
@@ -122,6 +145,7 @@ function createHttpClient(config) {
       throw failure;
     } finally {
       if (timer !== void 0) clearTimeout(timer);
+      caller?.removeEventListener("abort", forward);
     }
   }
   const get = (path, options) => request(path, { ...options, method: "GET" }).then((value) => value.data);

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;