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

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;

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

@@ -5,12 +5,14 @@ export declare const errorDefinitions: {
     readonly RESPONSE_INVALID: "服务返回的数据格式异常。";
     readonly RESPONSE_TOO_LARGE: "返回内容超过读取限制。";
     readonly REQUEST_INVALID_INPUT: "请求配置无效。";
+    readonly RUNTIME_UNSUPPORTED: "当前运行环境不支持 HTTP 请求所需能力，请升级 SDK 或检查运行时配置。";
+    readonly REQUEST_REDIRECT_BLOCKED: "接口返回了重定向，已阻止跳转，请检查 API 地址。";
     readonly AUTH_UNAUTHENTICATED: "登录状态已失效，请重新登录。";
     readonly REQUEST_FORBIDDEN: "没有执行此操作的权限。";
     readonly INTERNAL_ERROR: "服务暂时无法完成请求，请稍后重试。";
     readonly HTTP_ERROR: "请求未能完成，请检查后重试。";
 };
-export type ApiErrorKind = "network" | "timeout" | "http" | "response" | "input";
+export type ApiErrorKind = "network" | "timeout" | "http" | "response" | "input" | "runtime";
 export type ApiErrorOptions<T = unknown> = {
     status: number;
     code: string;
@@ -21,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;
@@ -35,3 +40,5 @@ export declare class ApiError<T = unknown> extends Error {
 }
 export declare function isRequestCancelled(error: unknown): boolean;
 export declare const isApiError: (error: unknown) => error is ApiError;
+/** Temporary transport or service failures; this does not authorize replaying a write. */
+export declare function isTransientHttpError(error: unknown): error is ApiError;

package/dist/errors.js

@@ -4,12 +4,20 @@ const errorDefinitions = {
   RESPONSE_INVALID: "服务返回的数据格式异常。",
   RESPONSE_TOO_LARGE: "返回内容超过读取限制。",
   REQUEST_INVALID_INPUT: "请求配置无效。",
+  RUNTIME_UNSUPPORTED: "当前运行环境不支持 HTTP 请求所需能力，请升级 SDK 或检查运行时配置。",
+  REQUEST_REDIRECT_BLOCKED: "接口返回了重定向，已阻止跳转，请检查 API 地址。",
   AUTH_UNAUTHENTICATED: "登录状态已失效，请重新登录。",
   REQUEST_FORBIDDEN: "没有执行此操作的权限。",
   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;
@@ -19,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;
@@ -29,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) {
@@ -37,9 +46,13 @@ function isRequestCancelled(error) {
   return "name" in error && error.name === "AbortError" || "code" in error && error.code === "ERR_CANCELED";
 }
 const isApiError = (error) => error instanceof ApiError;
+function isTransientHttpError(error) {
+  return error instanceof ApiError && (error.kind === "network" || error.kind === "timeout" || error.kind === "http" && [429, 502, 503, 504].includes(error.status));
+}
 export {
   ApiError,
   errorDefinitions,
   isApiError,
-  isRequestCancelled
+  isRequestCancelled,
+  isTransientHttpError
 };

package/dist/hono.d.ts

@@ -0,0 +1,49 @@
+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";
+export type CatalogError<D extends ErrorDefinitions, C extends keyof D & string> = ApiError & {
+    readonly code: C;
+    readonly status: D[C]["status"];
+};
+export type SuccessResponse<T, S extends 200 | 201 | 202> = Response & TypedResponse<JSONParsed<{
+    success: true;
+    msg: T;
+    errMsg: "";
+    code: "";
+}>, S, "json">;
+export type ErrorStatus<D extends ErrorDefinitions, C extends keyof D> = D[C]["status"] & ContentfulStatusCode;
+/** 显式写出响应类型：让 Hono 在泛型 C 未确定时推导 JSONParsed，会在声明文件里丢掉 code 字段。 */
+export 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">;
+};

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 } from "./errors.js";
+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, RequestContext, RequestNotice, RequestFailure, ResponseInfo, HttpClientConfig, HttpMessages, HttpRequestOptions, HttpMethod, ResponseMode, Feedback, FeedbackOwner, QueryScalar, UploadProgress, } from "./types.js";

package/dist/index.js

@@ -1,7 +1,8 @@
-import { ApiError, errorDefinitions, isApiError, isRequestCancelled } from "./errors.js";
+import { ApiError, errorDefinitions, isApiError, isRequestCancelled, isTransientHttpError } from "./errors.js";
 export {
   ApiError,
   errorDefinitions,
   isApiError,
-  isRequestCancelled
+  isRequestCancelled,
+  isTransientHttpError
 };

package/dist/query.js

@@ -1,10 +1,10 @@
 import { QueryClient, MutationCache, QueryCache, isCancelledError } from "@tanstack/react-query";
-import { isRequestCancelled, ApiError } from "./errors.js";
+import { isRequestCancelled, ApiError, isTransientHttpError } from "./errors.js";
 import { toSafeDiagnostics } from "./diagnostics.js";
 function shouldRetryRequest(failureCount, error, maxRetries = 2) {
   if (failureCount >= maxRetries || !(error instanceof ApiError)) return false;
   if (error.context?.method !== "GET" && error.context?.method !== "HEAD") return false;
-  return error.kind === "network" || error.kind === "timeout" || error.kind === "http" && [429, 502, 503, 504].includes(error.status);
+  return isTransientHttpError(error);
 }
 function requestRetryDelay(attempt, error) {
   const requested = error instanceof ApiError ? error.retryAfterMs : void 0;

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,67 @@
+import { httpStatusOf } from "@springbrand/errors";
+import { ApiError } from "../errors.js";
+const invalidJson = (cause) => new ApiError({ status: httpStatusOf("REQUEST_INVALID_JSON"), code: "REQUEST_INVALID_JSON", message: "Expected a JSON object", kind: "http", cause });
+const tooLarge = () => new ApiError({ status: httpStatusOf("REQUEST_PAYLOAD_TOO_LARGE"), 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: httpStatusOf("REQUEST_INVALID_INPUT"), 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";