@fudanda/client 0.0.0-stage → 1.20261015.1-beta.1

package/dist/event-stream.js

@@ -0,0 +1,102 @@
+import { fillPath } from '@fudanda/shared/core';
+import { ClientError } from './errors.js';
+/** An instance-local registered SSE operation. Reconnect begins with a server ready
+ * frame; the consumer must requery durable data instead of trusting token replay. */
+export function subscribeOperation(client, op, options) {
+    if (op.kind !== 'sse' || op.method !== 'get')
+        throw Error('Expected a GET SSE contract');
+    const path = client.resolveOperationPath(op);
+    if (!path)
+        throw Error('SSE operation is not registered on this Client');
+    const url = fillPath(path, options.params);
+    const abort = new AbortController();
+    let reader;
+    const close = () => { abort.abort(); void reader?.cancel().catch(() => { }); };
+    options.signal?.addEventListener('abort', close, { once: true });
+    if (options.signal?.aborted)
+        close();
+    const done = (async () => {
+        let failures = 0;
+        while (!abort.signal.aborted) {
+            options.onConnection?.(failures ? 'reconnecting' : 'connecting');
+            try {
+                const response = await client.fetchRaw(url, { signal: abort.signal, headers: { Accept: 'text/event-stream' } });
+                if (response.status === 401) {
+                    options.onUnauthorized?.();
+                    return;
+                }
+                if ([403, 404].includes(response.status))
+                    throw new ClientError(response.status, 'stream_denied', '无法订阅该运行');
+                if (!response.ok || !response.body || !response.headers.get('content-type')?.startsWith('text/event-stream'))
+                    throw Error('Invalid SSE response');
+                reader = response.body.getReader();
+                options.onConnection?.('connected');
+                const decoder = new TextDecoder();
+                let buffer = '';
+                while (!abort.signal.aborted) {
+                    const part = await reader.read();
+                    if (part.done)
+                        break;
+                    buffer += decoder.decode(part.value, { stream: true });
+                    // Normalize only complete frames: CRLF can be split across TCP chunks.
+                    let match;
+                    while ((match = /\r?\n\r?\n/.exec(buffer))) {
+                        const frame = buffer.slice(0, match.index).replaceAll('\r\n', '\n');
+                        buffer = buffer.slice(match.index + match[0].length);
+                        if (frame.length > 512 * 1024)
+                            throw Error('SSE frame exceeds limit');
+                        let event = 'message';
+                        const data = [];
+                        for (const line of frame.split('\n')) {
+                            if (line.startsWith('event:'))
+                                event = line.slice(6).trim();
+                            else if (line.startsWith('data:'))
+                                data.push(line.slice(5).replace(/^ /, ''));
+                        }
+                        if (event === 'session-expired') {
+                            options.onUnauthorized?.();
+                            return;
+                        }
+                        if (event === 'denied')
+                            throw new ClientError(403, 'stream_denied', '订阅权限已失效');
+                        if (event === 'unavailable')
+                            throw Error('Stream unavailable');
+                        if (!data.length)
+                            continue;
+                        const value = options.parse(event, JSON.parse(data.join('\n')));
+                        if (!abort.signal.aborted)
+                            options.onEvent(value);
+                        failures = 0;
+                        if (event === 'done')
+                            return;
+                    }
+                    if (buffer.length > 512 * 1024)
+                        throw Error('SSE frame exceeds limit');
+                }
+            }
+            catch (error) {
+                if (abort.signal.aborted)
+                    return;
+                options.onError?.(error);
+                if (error instanceof ClientError && [403, 404].includes(error.status))
+                    return;
+            }
+            finally {
+                await reader?.cancel().catch(() => { });
+                reader?.releaseLock();
+                reader = undefined;
+            }
+            if (abort.signal.aborted)
+                return;
+            failures++;
+            options.onConnection?.('reconnecting');
+            await new Promise(resolve => {
+                const finish = () => { clearTimeout(timer); abort.signal.removeEventListener('abort', finish); resolve(); };
+                const timer = setTimeout(finish, Math.min(15000, Math.max(250, options.reconnectDelay ?? 750) * 2 ** Math.min(failures - 1, 4)));
+                abort.signal.addEventListener('abort', finish, { once: true });
+            });
+        }
+    })().finally(() => { options.signal?.removeEventListener('abort', close); options.onConnection?.('closed'); });
+    return { close, done };
+}
+//# sourceMappingURL=event-stream.js.map

package/dist/event-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-stream.js","sourceRoot":"","sources":["../src/event-stream.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { Client, validateGoPath } from './client.js';
+export type { ClientOptions, RequestOptions, ApiEnvelope, Method } from './client.js';
+export { ClientError, ApiError } from './errors.js';
+export { subscribe } from './subscriptions.js';
+export { subscribeOperation } from './event-stream.js';
+export type { EventStreamOptions } from './event-stream.js';
+export type { ChangeEvent, SubscriptionOptions, Subscription } from './subscriptions.js';
+export { call, callRaw, operationURL, foundationPath, foundationRequestBody, isFoundationOperation, toQueryString, unwrap } from './contracts.js';
+export type { JsonClient, UrlInputOf } from './contracts.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAClD,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAC,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAC,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACtF,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC/I,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { Client, validateGoPath } from './client.js';
+export { ClientError, ApiError } from './errors.js';
+export { subscribe } from './subscriptions.js';
+export { subscribeOperation } from './event-stream.js';
+export { call, callRaw, operationURL, foundationPath, foundationRequestBody, isFoundationOperation, toQueryString, unwrap } from './contracts.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAElD,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAC,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAGlD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/subscriptions.d.ts

@@ -0,0 +1,22 @@
+import type { Client } from './client.js';
+export interface ChangeEvent {
+    resources: string[];
+    cursor: string;
+    requery: boolean;
+}
+export interface SubscriptionOptions {
+    signal?: AbortSignal;
+    onChange: (event: ChangeEvent) => void;
+    onError?: (error: unknown) => void;
+    onUnauthorized?: () => void;
+    /** Bounded reconnect delay, in milliseconds. */
+    reconnectDelay?: number;
+}
+export interface Subscription {
+    close(): void;
+    done: Promise<void>;
+}
+/** Fetch-based SSE works with both Cookie and restricted API Key clients.
+ * Cursor stays in memory; ready/reconnect always requests an authorized requery. */
+export declare function subscribe(client: Client, options: SubscriptionOptions): Subscription;
+//# sourceMappingURL=subscriptions.d.ts.map

package/dist/subscriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../src/subscriptions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,WAAW,WAAW;IAAG,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE;AACtF,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACvC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AACD,MAAM,WAAW,YAAY;IAAG,KAAK,IAAI,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE;AAEpE;oFACoF;AACpF,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAuDpF"}

package/dist/subscriptions.js

@@ -0,0 +1,93 @@
+import { integrationContract } from '@fudanda/shared/integrations';
+import { operationURL } from './contracts.js';
+import { ClientError } from './errors.js';
+/** Fetch-based SSE works with both Cookie and restricted API Key clients.
+ * Cursor stays in memory; ready/reconnect always requests an authorized requery. */
+export function subscribe(client, options) {
+    const controller = new AbortController();
+    let activeReader;
+    const close = () => { controller.abort(); void activeReader?.cancel().catch(() => { }); };
+    options.signal?.addEventListener('abort', close, { once: true });
+    if (options.signal?.aborted)
+        close();
+    let cursor = '';
+    const done = (async () => {
+        while (!controller.signal.aborted) {
+            let reader;
+            try {
+                const response = await client.fetchRaw(operationURL(integrationContract.events), { signal: controller.signal, headers: { Accept: 'text/event-stream', ...(cursor ? { 'Last-Event-ID': cursor } : {}) } });
+                if (response.status === 401) {
+                    options.onUnauthorized?.();
+                    return;
+                }
+                if (response.status === 403)
+                    throw new ClientError(403, 'subscription_denied', '没有订阅权限');
+                if (!response.ok || !response.body || !response.headers.get('content-type')?.startsWith('text/event-stream'))
+                    throw new ClientError(response.status, 'subscription_unavailable', '订阅暂不可用');
+                reader = response.body.getReader();
+                activeReader = reader;
+                const decoder = new TextDecoder();
+                let buffer = '';
+                while (!controller.signal.aborted) {
+                    const part = await reader.read();
+                    if (part.done)
+                        break;
+                    buffer = (buffer + decoder.decode(part.value, { stream: true })).replace(/\r\n/g, '\n');
+                    if (buffer.length > 65536)
+                        throw new Error('SSE frame exceeds size limit');
+                    let boundary;
+                    while ((boundary = buffer.indexOf('\n\n')) >= 0) {
+                        const frame = buffer.slice(0, boundary);
+                        buffer = buffer.slice(boundary + 2);
+                        let event = '';
+                        let id = '';
+                        const data = [];
+                        for (const line of frame.split('\n')) {
+                            if (line.startsWith('event:'))
+                                event = line.slice(6).trim();
+                            else if (line.startsWith('id:'))
+                                id = line.slice(3).trim();
+                            else if (line.startsWith('data:'))
+                                data.push(line.slice(5).trimStart());
+                        }
+                        if (/^\d+$/.test(id))
+                            cursor = id;
+                        if (event === 'session-expired') {
+                            options.onUnauthorized?.();
+                            return;
+                        }
+                        if (event === 'unavailable')
+                            throw new Error('Subscription unavailable');
+                        if (event === 'change' || event === 'ready') {
+                            const parsed = JSON.parse(data.join('\n') || '{}');
+                            const resources = parsed && typeof parsed === 'object' && 'resources' in parsed && Array.isArray(parsed.resources) && parsed.resources.every(value => typeof value === 'string') ? parsed.resources : [];
+                            if (!controller.signal.aborted)
+                                options.onChange({ resources, cursor, requery: true });
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                if (controller.signal.aborted)
+                    return;
+                options.onError?.(error);
+                if (error instanceof ClientError && error.status === 403)
+                    return;
+            }
+            finally {
+                await reader?.cancel().catch(() => { });
+                reader?.releaseLock();
+                activeReader = undefined;
+            }
+            if (controller.signal.aborted)
+                return;
+            await new Promise(resolve => {
+                const finished = () => { clearTimeout(timer); controller.signal.removeEventListener('abort', finished); resolve(); };
+                const timer = setTimeout(finished, Math.min(30000, Math.max(250, options.reconnectDelay ?? 1500)));
+                controller.signal.addEventListener('abort', finished, { once: true });
+            });
+        }
+    })().finally(() => { options.signal?.removeEventListener('abort', close); });
+    return { close, done };
+}
+//# sourceMappingURL=subscriptions.js.map

package/dist/subscriptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.js","sourceRoot":"","sources":["../src/subscriptions.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@fudanda/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.20261015.1-beta.1",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "arcbase-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "node ../../scripts/clean-package.mjs && tsc -p tsconfig.json && tsc-alias --resolve-full-paths",
+    "check:types": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src --max-warnings 0"
+  },
+  "dependencies": {
+    "@fudanda/shared": "1.20261015.1-beta.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.12.0",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "typescript-eslint": "^8.71.1",
+    "vitest": "^5.0.3",
+    "tsc-alias": "^1.9.7"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!dist/.tsbuildinfo",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fudanda/arcbase.git",
+    "directory": "packages/client"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/src/client.ts

@@ -0,0 +1,203 @@
+import type { ApiResponse } from '@fudanda/shared/core';
+import { ClientError } from './errors';
+import type { AnyOperation } from '@fudanda/shared/core';
+
+export type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type ApiEnvelope<T> = ApiResponse<T> & { error?: string; requestId?: string; retryAfterSeconds?: number };
+export interface RequestOptions {
+  signal?: AbortSignal | null;
+  headers?: HeadersInit;
+  anonymousWrite?: boolean;
+}
+export interface ClientOptions {
+  baseURL?: string;
+  credentials?: RequestCredentials;
+  transport?: typeof fetch;
+  xhrFactory?: () => XMLHttpRequest;
+  onUnauthorized?: () => void;
+  /** For scripts/server integrations. Never persist or expose keys in browser storage. */
+  apiKey?: string;
+  /** Explicit host contracts; built-in operations remain restricted to the release catalog. */
+  operations?: readonly AnyOperation[];
+}
+
+const loginPaths = ['/api/v1/auth/login', '/api/v1/auth/session-conflict/resolve', '/api/v1/auth/external/start', '/api/v1/auth/external/complete'];
+
+export function validateGoPath(path: string): void {
+  if (!/^\/api\/v1\/[a-zA-Z0-9][a-zA-Z0-9_%./-]*(?:\?[a-zA-Z0-9%=&_.+-]*)?$/.test(path)
+    || path.includes('//')
+    || decodeURIComponent(path.split('?')[0]).includes('//')
+    || /(?:^|\/)\.{1,2}(?:\/|$)/.test(decodeURIComponent(path.split('?')[0]))
+    || !new URL(path, 'http://localhost').pathname.startsWith('/api/v1/')) {
+    throw new Error('Invalid Go API path');
+  }
+}
+
+/** Cookie/CSRF transport. UI, user state and query caches belong to the host. */
+export class Client {
+  private csrfToken: string | null = null;
+  private readonly unauthorizedListeners = new Set<() => void>();
+  private readonly baseURL: string;
+  private readonly send: typeof fetch;
+  private readonly credentials: RequestCredentials;
+  private readonly operations = new Map<AnyOperation, string>();
+
+  constructor(private readonly options: ClientOptions = {}) {
+    this.baseURL = (options.baseURL ?? '').replace(/\/$/, '');
+    if (this.baseURL && (!/^https?:\/\//.test(this.baseURL) || new URL(this.baseURL).origin !== this.baseURL)) throw new Error('baseURL must be an HTTP origin');
+    this.send = options.transport ?? ((...args) => globalThis.fetch(...args));
+    if (options.apiKey && !/^arc_[a-f0-9]{64}$/.test(options.apiKey)) throw new Error('Invalid ArcBase API Key');
+    this.credentials = options.credentials ?? (options.apiKey ? 'omit' : 'same-origin');
+    const routes = new Set<string>();
+    for (const op of options.operations ?? []) {
+      validateGoPath(op.fullPath.replaceAll(/\{[a-zA-Z][a-zA-Z0-9_]*\}/g, '1'));
+      if (!op.fullPath.startsWith('/api/v1/extensions/')) throw new Error('Host operations must use /api/v1/extensions/');
+      const key = `${op.method} ${op.fullPath}`;
+      if (routes.has(key)) throw new Error('Duplicate host operation');
+      routes.add(key); this.operations.set(op, op.fullPath);
+    }
+  }
+
+  /** Registration is instance-local and requires the exact declared operation. */
+  resolveOperationPath(op: AnyOperation): string | undefined { return this.operations.get(op); }
+
+  setCsrfToken(value: string | null): void { this.csrfToken = value; }
+  clearSession(): void { this.csrfToken = null; }
+  /** Long-lived authenticated transports use the same expiry notifications as HTTP 401. */
+  expireSession(): void { this.received(401); }
+  sessionHeaders(): Record<string, string> { return this.csrfToken ? { 'X-CSRF-Token': this.csrfToken } : {}; }
+
+  /** Hosts can observe expiry without replacing the caller's callback. */
+  subscribeUnauthorized(listener: () => void): () => void {
+    this.unauthorizedListeners.add(listener);
+    return () => { this.unauthorizedListeners.delete(listener); };
+  }
+
+  private headers(method: string, path: string, body: BodyInit | null | undefined, options: RequestOptions): Headers {
+    validateGoPath(path);
+    if (options.anonymousWrite && (method !== 'POST' || !loginPaths.includes(path))) throw new Error('Only origin-checked login actions may write without CSRF');
+    const write = !['GET', 'HEAD', 'OPTIONS'].includes(method);
+    if (write && !options.anonymousWrite && !this.csrfToken && !this.options.apiKey) throw new ClientError(401, 'session_missing', '登录状态尚未恢复');
+    const headers = new Headers(options.headers);
+    // Caller headers cannot supply a different identity or stale CSRF secret.
+    headers.delete('authorization');
+    headers.delete('cookie');
+    headers.delete('x-csrf-token');
+    if (this.options.apiKey) headers.set('Authorization', `Bearer ${this.options.apiKey}`);
+    if (body instanceof FormData) headers.delete('content-type');
+    else if (body !== undefined && body !== null && !headers.has('content-type')) headers.set('Content-Type', 'application/json');
+    if (write && !options.anonymousWrite && !this.options.apiKey) headers.set('X-CSRF-Token', this.csrfToken!);
+    return headers;
+  }
+
+  private received(status: number, anonymousWrite = false): void {
+    if (status === 401) {
+      this.clearSession();
+      if (!anonymousWrite) {
+        for (const listener of this.unauthorizedListeners) listener();
+        this.options.onUnauthorized?.();
+      }
+    }
+  }
+
+  async fetchRaw(path: string, options: RequestInit & RequestOptions = {}): Promise<Response> {
+    const { anonymousWrite, ...init } = options;
+    const method = (init.method ?? 'GET').toUpperCase();
+    const headers = this.headers(method, path, init.body, { ...options, anonymousWrite });
+    let response: Response;
+    try { response = await this.send(this.baseURL + path, { ...init, method, headers, credentials: this.credentials, cache: 'no-store' }); }
+    catch (error) {
+      if (error && typeof error === 'object' && 'name' in error && error.name === 'AbortError') throw error;
+      throw new ClientError(0, 'network_error', '网络请求失败，请检查网络连接');
+    }
+    // A host transport may resolve after cancellation; ignore that stale result.
+    if (init.signal?.aborted) throw new DOMException('已取消', 'AbortError');
+    this.received(response.status, anonymousWrite);
+    return response;
+  }
+
+  private async envelope<T>(response: Response): Promise<ApiEnvelope<T>> {
+    const requestId = response.headers.get('X-Request-Id') ?? undefined;
+    let payload: unknown;
+    try { payload = await response.json(); }
+    catch { throw new ClientError(response.status, 'invalid_response', '服务端响应格式错误', requestId); }
+    if (!payload || typeof payload !== 'object' || !('code' in payload) || typeof payload.code !== 'number'
+      || !('message' in payload) || typeof payload.message !== 'string' || !('data' in payload)) throw new ClientError(response.status, 'invalid_response', '服务端响应格式错误', requestId);
+    const result = payload as ApiEnvelope<T>;
+    if (!response.ok && result.code === 0) throw new ClientError(response.status, 'invalid_response', 'HTTP 状态与响应结果不一致', requestId);
+    const retryAfterSeconds = Number(response.headers.get('Retry-After'));
+    return { ...result, ...(requestId ? { requestId } : {}), ...(retryAfterSeconds > 0 ? { retryAfterSeconds } : {}) };
+  }
+
+  async request<T>(method: Method, path: string, options: RequestOptions & { body?: unknown } = {}): Promise<ApiEnvelope<T>> {
+    const { body, ...rest } = options;
+    const raw = body === undefined ? undefined : body instanceof FormData ? body : JSON.stringify(body);
+    return this.requestRaw<T>(path, { ...rest, method, body: raw });
+  }
+
+  async requestRaw<T>(path: string, options: RequestInit & RequestOptions = {}): Promise<ApiEnvelope<T>> {
+    return this.envelope<T>(await this.fetchRaw(path, options));
+  }
+
+  get<T>(path: string, options?: RequestOptions) { return this.request<T>('GET', path, options); }
+  post<T>(path: string, body?: unknown, options?: RequestOptions) { return this.request<T>('POST', path, { ...options, body, anonymousWrite: loginPaths.includes(path) }); }
+  put<T>(path: string, body?: unknown, options?: RequestOptions) { return this.request<T>('PUT', path, { ...options, body }); }
+  patch<T>(path: string, body?: unknown, options?: RequestOptions) { return this.request<T>('PATCH', path, { ...options, body }); }
+  delete<T>(path: string, body?: unknown, options?: RequestOptions) { return this.request<T>('DELETE', path, { ...options, body }); }
+
+  async readBlob(path: string, options: RequestInit & RequestOptions = {}): Promise<Blob> {
+    const response = await this.fetchRaw(path, options);
+    if (!response.ok) {
+      const result = await this.envelope<unknown>(response);
+      throw new ClientError(response.status, result.error ?? 'download_failed', result.message || '下载失败', result.requestId);
+    }
+    if (response.headers.get('Content-Type')?.includes('application/json') && !response.headers.has('Content-Disposition')) throw new ClientError(response.status, 'invalid_response', '文件响应格式错误');
+    return response.blob();
+  }
+
+  async postForm<T>(path: string, body: FormData, options: RequestOptions & { onProgress?: (percent: number) => void } = {}): Promise<ApiEnvelope<T>> {
+    if (!options.onProgress) return this.request<T>('POST', path, { ...options, body });
+    const headers = this.headers('POST', path, body, options);
+    if (options.signal?.aborted) throw new DOMException('已取消', 'AbortError');
+    const xhr = this.options.xhrFactory?.() ?? new XMLHttpRequest();
+    return new Promise((resolve, reject) => {
+      xhr.open('POST', this.baseURL + path);
+      xhr.withCredentials = this.credentials === 'include';
+      headers.forEach((value, name) => xhr.setRequestHeader(name, value));
+      const onProgress = (event: ProgressEvent) => {
+        if (event.lengthComputable) options.onProgress?.(Math.round(event.loaded / event.total * 100));
+      };
+      const onAbort = () => { xhr.abort(); reject(new DOMException('已取消', 'AbortError')); };
+      options.signal?.addEventListener('abort', onAbort, { once: true });
+      const cleanup = () => {
+        options.signal?.removeEventListener('abort', onAbort);
+        xhr.upload.removeEventListener('progress', onProgress);
+        xhr.removeEventListener('load', onLoad);
+        xhr.removeEventListener('error', onError);
+        xhr.removeEventListener('abort', onAborted);
+        xhr.removeEventListener('timeout', onTimeout);
+      };
+      const onLoad = () => {
+        cleanup();
+        this.received(xhr.status);
+        const responseHeaders = new Headers();
+        for (const name of ['Content-Type', 'X-Request-Id', 'Retry-After']) {
+          const value = xhr.getResponseHeader(name);
+          if (value) responseHeaders.set(name, value);
+        }
+        try { void this.envelope<T>(new Response(xhr.responseText, { status: xhr.status, headers: responseHeaders })).then(resolve, reject); }
+        catch (error) { reject(error); }
+      };
+      const onError = () => { cleanup(); reject(new ClientError(0, 'network_error', '网络请求失败，请检查网络连接')); };
+      const onAborted = () => { cleanup(); reject(new DOMException('已取消', 'AbortError')); };
+      const onTimeout = () => { cleanup(); reject(new ClientError(0, 'timeout', '上传超时')); };
+      xhr.upload.addEventListener('progress', onProgress);
+      xhr.addEventListener('load', onLoad);
+      xhr.addEventListener('error', onError);
+      xhr.addEventListener('abort', onAborted);
+      xhr.addEventListener('timeout', onTimeout);
+      try { xhr.send(body); }
+      catch { cleanup(); reject(new ClientError(0, 'network_error', '网络请求失败，请检查网络连接')); }
+    });
+  }
+}

package/src/contracts.ts

@@ -0,0 +1,90 @@
+import { fillPath, type AnyOperation, type ApiResponse, type EmptyInput, type InputOf, type OutputOf, type ParamsSchema, type ShapeInput } from '@fudanda/shared/core';
+import { foundationOperations } from '@fudanda/shared/foundation-operations';
+import { foundationSettingsBody, foundationSettingsOperation } from '@fudanda/shared/settings/foundation';
+import type { RequestOptions } from './client';
+import { ApiError } from './errors';
+
+export interface JsonClient {
+  resolveOperationPath?(op: AnyOperation): string | undefined;
+  get<T>(url: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+  post<T>(url: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+  put<T>(url: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+  patch<T>(url: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+  delete<T>(url: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+}
+
+const paths = new Map(foundationOperations.map(([, op]) => [op.fullPath, op.fullPath.replace(/^\/api\/(?!v1\/)/, '/api/v1/')]));
+export function isFoundationOperation(op: AnyOperation): boolean { return paths.has(op.fullPath); }
+export function foundationPath(op: AnyOperation): string {
+  const path = paths.get(op.fullPath);
+  if (!path) throw new Error(`操作 ${op.basePath}:${op.name} 尚未接入 Go`);
+  return path;
+}
+
+export function foundationRequestBody(op: AnyOperation, body: unknown): unknown {
+  if (!op.body || body === undefined || body instanceof FormData) return body;
+  const parsed: unknown = op.body.parse(body);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return parsed;
+  const partial = op.method === 'put' || op.method === 'patch';
+  const supplied = body && typeof body === 'object' ? body : {};
+  const removed = new Set(['tenantId', 'tenantCode', 'tenantViewId', 'viewingTenantId']);
+  return Object.fromEntries(Object.entries(parsed).filter(([key]) => !removed.has(key) && (!partial || Object.hasOwn(supplied, key))));
+}
+
+export function toQueryString(params: object): string {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && value !== '') search.set(key, String(value));
+  }
+  const query = search.toString();
+  return query ? `?${query}` : '';
+}
+
+type LooseInput = { params?: Record<string, unknown>; query?: object; headers?: Record<string, unknown>; body?: unknown };
+type InputArgs<Op extends AnyOperation> = Record<never, never> extends InputOf<Op> ? [input?: InputOf<Op>] : [input: InputOf<Op>];
+export type UrlInputOf<Op extends AnyOperation> =
+  (Op['params'] extends ParamsSchema ? { params: ShapeInput<Op['params']> } : EmptyInput) &
+  (Op['query'] extends ParamsSchema ? { query: ShapeInput<Op['query']> } : EmptyInput);
+type UrlArgs<Op extends AnyOperation> = Record<never, never> extends UrlInputOf<Op> ? [input?: UrlInputOf<Op>] : [input: UrlInputOf<Op>];
+
+export function operationURL<Op extends AnyOperation>(op: Op, ...args: UrlArgs<Op>): string {
+  const values = args[0] as LooseInput | undefined;
+  return fillPath(foundationPath(op), values?.params) + (values?.query ? toQueryString(values.query) : '');
+}
+
+/** Typed calls reuse shared schemas, including single-organization projections. */
+export async function callRaw<Op extends AnyOperation>(client: JsonClient, op: Op, ...args: [...InputArgs<Op>, options?: RequestOptions]): Promise<ApiResponse<OutputOf<Op>>> {
+  if (op.kind !== 'json') throw new Error(`契约操作「${op.name}」为 ${op.kind} 响应，请使用文件通道`);
+  const input = args[0] as LooseInput | undefined;
+  const options = args[1] as RequestOptions | undefined;
+  const headers = new Headers(options?.headers);
+  for (const [key, value] of Object.entries(input?.headers ?? {})) {
+    if (value !== undefined && value !== null) headers.set(key, String(value));
+  }
+  const requestOptions = { ...options, headers };
+  const hostPath = client.resolveOperationPath?.(op);
+  const url = hostPath ? fillPath(hostPath, input?.params) + (input?.query ? toQueryString(input.query) : '') : operationURL(op, ...([input] as unknown as UrlArgs<Op>));
+  const projected = hostPath ? op : foundationSettingsOperation(op);
+  const body = hostPath ? hostRequestBody(op, input?.body) : foundationRequestBody(projected, foundationSettingsBody(op, input?.body));
+  const response = op.method === 'get'
+    ? await client.get<OutputOf<Op>>(url, requestOptions)
+    : await client[op.method]<OutputOf<Op>>(url, body, requestOptions);
+  return response.code === 0 ? { ...response, data: projected.response.parse(response.data) as OutputOf<Op> } : response;
+}
+
+function hostRequestBody(op: AnyOperation, body: unknown): unknown {
+  if (!op.body || body === undefined || body instanceof FormData) return body;
+  const parsed: unknown = op.body.parse(body);
+  if ((op.method === 'put' || op.method === 'patch') && parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    return Object.fromEntries(Object.entries(parsed).filter(([key]) => body && typeof body === 'object' && Object.hasOwn(body, key)));
+  }
+  return parsed;
+}
+
+export async function call<Op extends AnyOperation>(client: JsonClient, op: Op, ...args: [...InputArgs<Op>, options?: RequestOptions]): Promise<OutputOf<Op>> {
+  return unwrap(await callRaw(client, op, ...args));
+}
+export function unwrap<T>(response: ApiResponse<T>): T {
+  if (response.code !== 0) throw new ApiError(response.code, response.message);
+  return response.data;
+}

package/src/errors.ts

@@ -0,0 +1,18 @@
+export class ClientError extends Error {
+  constructor(
+    readonly status: number,
+    readonly reason: string,
+    message: string,
+    readonly requestId?: string,
+  ) {
+    super(message);
+    this.name = 'ClientError';
+  }
+}
+
+export class ApiError extends Error {
+  constructor(readonly code: number, message: string) {
+    super(message || `请求失败（code=${code}）`);
+    this.name = 'ApiError';
+  }
+}