@yarch/contract 0.1.0

package/README.md

@@ -0,0 +1,14 @@
+# @yarch/contract
+
+yarch 前端契约 SDK——契约唯一权威为 [yarch 仓 contract/](https://github.com/yuandonghao/yarch/tree/main/contract)，本包是其 TypeScript 方言实现（React/Vue 通吃，零框架依赖）。
+
+- `rest-response`：`RestResponse<T>` 信封类型 + 解包（失败抛 `ApiError`）
+- `error-codes`：13 码常量表（0 成功 · 1xxx 通用 · 2xxx 认证 · 3xxx+ 业务注册段）
+- `api-error`：traceId 报障凭证 · `shouldRedirectToLogin`
+- `trace-id`：`X-Trace-Id` 生成/透传（W3C traceparent 对齐）
+- `http`：fetch 封装 + 401 映射
+- `navigator`：导航端口（依赖倒置——框架适配包 `@yarch/react` / `@yarch/vue` 注入实现）
+
+用法：`createClient({ baseUrl, getHeaders })` → `api.get<PageData<T>>("/items?page=1")`。
+
+配套：工程脚手架 `npm create @yarch/admin@latest <name>`（[@yarch/create-admin](https://www.npmjs.com/package/@yarch/create-admin)）。

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@yarch/contract",
+  "version": "0.1.0",
+  "description": "yarch 前端契约 SDK（跨框架，React/Vue 通吃）：RestResponse/PageData 类型与解包、错误码常量表、ApiError、traceId、fetch 封装",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": { "test": "vitest run" },
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "git+https://github.com/yuandonghao/yarch.git", "directory": "stacks/web/packages/contract" },
+  "license": "Apache-2.0",
+  "devDependencies": { "vitest": "^3.0.0", "typescript": "^5.6.0" }
+}

package/src/api-error.ts

@@ -0,0 +1,21 @@
+/** ApiError：业务错误的统一形态 —— code 对应错误码表，traceId 是报障凭证 */
+export class ApiError extends Error {
+  readonly code: number;
+  readonly traceId: string;
+
+  constructor(code: number, message: string, traceId = "") {
+    super(message);
+    this.name = "ApiError";
+    this.code = code;
+    this.traceId = traceId;
+  }
+
+  /** 契约：token 过期引导重登录，禁无脑重试（rest-conventions.md 认证段） */
+  get shouldRedirectToLogin(): boolean {
+    return this.code === 2001 || this.code === 2002;
+  }
+
+  get isForbidden(): boolean {
+    return this.code === 2003 || this.code === 2004;
+  }
+}

package/src/error-codes.ts

@@ -0,0 +1,20 @@
+/** 错误码常量表 —— 与 contract/api/error-codes.md v1.0 同源（0/1xxx/2xxx 归 yarch；3xxx+ 业务侧扩展） */
+export const CODE_SUCCESS = 0;
+
+export const errorCodes = {
+  INTERNAL_ERROR: 1000,
+  INVALID_ARGUMENT: 1001,
+  MALFORMED_BODY: 1002,
+  NOT_FOUND: 1004,
+  CONFLICT: 1005,
+  RATE_LIMITED: 1006,
+  IDEMPOTENCY_CONFLICT: 1007,
+  UPSTREAM_TIMEOUT: 1008,
+  UNAVAILABLE: 1009,
+  UNAUTHORIZED: 2001,
+  CREDENTIALS_EXPIRED: 2002,
+  FORBIDDEN: 2003,
+  ACCOUNT_DISABLED: 2004,
+} as const;
+
+export type YarchErrorCode = (typeof errorCodes)[keyof typeof errorCodes];

package/src/http.ts

@@ -0,0 +1,54 @@
+/** 框架无关 fetch 封装：traceId 透传 + 信封解包 + 错误映射（401/402→重登录端口） */
+import { ApiError } from "./api-error";
+import { RestResponse } from "./rest-response";
+import { newTraceId, TRACE_ID_HEADER } from "./trace-id";
+import { navigateToLogin } from "./navigator";
+
+export interface HttpOptions {
+  baseUrl?: string;
+  getHeaders?: () => Record<string, string>;
+}
+
+export function createClient(options: HttpOptions = {}) {
+  const baseUrl = options.baseUrl ?? "";
+
+  async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      [TRACE_ID_HEADER]: newTraceId(),
+      ...(options.getHeaders?.() ?? {}),
+    };
+    let response: Response;
+    try {
+      response = await fetch(baseUrl + path, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+      });
+    } catch (cause) {
+      throw new ApiError(-1, `网络错误：${String(cause)}`);
+    }
+
+    if (response.status === 401) {
+      navigateToLogin("unauthorized");
+      throw new ApiError(2001, "未认证", response.headers.get(TRACE_ID_HEADER) ?? "");
+    }
+
+    const envelope = (await response.json()) as RestResponse<T>;
+    if (envelope.code !== 0) {
+      const apiError = new ApiError(envelope.code, envelope.message, envelope.traceId);
+      if (apiError.shouldRedirectToLogin) {
+        navigateToLogin(`code ${envelope.code}`);
+      }
+      throw apiError;
+    }
+    return envelope.data as T;
+  }
+
+  return {
+    get: <T>(path: string) => request<T>("GET", path),
+    post: <T>(path: string, body: unknown) => request<T>("POST", path, body),
+    put: <T>(path: string, body: unknown) => request<T>("PUT", path, body),
+    delete: <T>(path: string) => request<T>("DELETE", path),
+  };
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./error-codes";
+export * from "./rest-response";
+export * from "./api-error";
+export * from "./trace-id";
+export * from "./navigator";
+export * from "./http";

package/src/navigator.ts

@@ -0,0 +1,18 @@
+/**
+ * 导航端口（依赖倒置）：共享包零框架依赖，401→重登录 的路由跳转由各框架适配层注入实现
+ * （对应 java 侧 ProductCache 端口的同一手法）。
+ */
+export interface YarchNavigator {
+  /** 401/2002 时引导到登录页（记录回跳地址） */
+  redirectToLogin(reason: string): void;
+}
+
+let navigator: YarchNavigator | null = null;
+
+export function setNavigator(impl: YarchNavigator): void {
+  navigator = impl;
+}
+
+export function navigateToLogin(reason: string): void {
+  navigator?.redirectToLogin(reason);
+}

package/src/rest-response.ts

@@ -0,0 +1,35 @@
+/** 信封与分页负载（rest-response.md v1.0）：code/message/data/traceId 四字段，前端只认这个形状 */
+import { ApiError } from "./api-error";
+
+export interface RestResponse<T> {
+  code: number;
+  message: string;
+  data: T | null;
+  traceId: string;
+}
+
+export interface PageData<T> {
+  list: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+  nextCursor?: string;
+}
+
+/** 解包：code != 0 抛 ApiError（含 traceId 报障凭证）；data 为 null 抛 ApiError */
+export function unwrap<T>(envelope: RestResponse<T>): T {
+  if (envelope.code !== 0) {
+    throw new ApiError(envelope.code, envelope.message, envelope.traceId);
+  }
+  if (envelope.data === null) {
+    throw new ApiError(-1, "信封 data 为 null（成功无负载场景请用 unwrapAllowNull）", envelope.traceId);
+  }
+  return envelope.data as T;
+}
+
+export function unwrapAllowNull<T>(envelope: RestResponse<T>): T | null {
+  if (envelope.code !== 0) {
+    throw new ApiError(envelope.code, envelope.message, envelope.traceId);
+  }
+  return envelope.data;
+}

package/src/trace-id.ts

@@ -0,0 +1,14 @@
+/** traceId（logging-trace.md 前端行）：生成/透传 X-Trace-Id，错误对象暴露 traceId 供报障 */
+const TRACE_HEADER = "X-Trace-Id";
+
+export function newTraceId(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+export function traceHeader(): Record<string, string> {
+  return { [TRACE_HEADER]: newTraceId() };
+}
+
+export const TRACE_ID_HEADER = TRACE_HEADER;