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

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;

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) {

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, 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/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";

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/response.js

@@ -1,3 +1,4 @@
+import { httpStatusOf } from "@springbrand/errors";
 import { ApiError, errorDefinitions } from "../errors.js";
 function responseHeaders(options) {
   const requestId = options.requestId ?? crypto.randomUUID();
@@ -22,7 +23,7 @@ function toErrorResponse(error, options = {}) {
   if (error instanceof ApiError && error.kind === "http" && Number.isInteger(error.status) && error.status >= 400 && error.status <= 599 && /^[A-Z][A-Z0-9_]{0,127}$/.test(error.code) && !["NETWORK_ERROR", "REQUEST_TIMEOUT", "RESPONSE_TOO_LARGE"].includes(error.code)) {
     return fail({ status: error.status, code: error.code, message: error.message, errors: error.errors, details: error.details, requestId: options.requestId ?? error.requestId, headers: options.headers });
   }
-  return fail({ status: 500, code: "INTERNAL_ERROR", message: errorDefinitions.INTERNAL_ERROR, ...options });
+  return fail({ status: httpStatusOf("INTERNAL_ERROR"), code: "INTERNAL_ERROR", message: errorDefinitions.INTERNAL_ERROR, ...options });
 }
 export {
   fail,

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,31 @@
-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);
-  return new Request(url, { ...init, headers, credentials: "omit", redirect: "error" });
+  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);
 }
 async function verifyServiceToken(provided, expected) {
   if (!provided || !expected) return false;

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 {