@h-ai/api-client 0.1.0-alpha5

package/dist/index.d.ts

@@ -0,0 +1,348 @@
+import * as _h_ai_core from '@h-ai/core';
+import { HaiResult } from '@h-ai/core';
+import { z } from 'zod';
+
+declare const HaiApiClientError: {
+    readonly NETWORK_ERROR: _h_ai_core.HaiErrorDef;
+    readonly TIMEOUT: _h_ai_core.HaiErrorDef;
+    readonly SERVER_ERROR: _h_ai_core.HaiErrorDef;
+    readonly UNAUTHORIZED: _h_ai_core.HaiErrorDef;
+    readonly FORBIDDEN: _h_ai_core.HaiErrorDef;
+    readonly NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly VALIDATION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly TOKEN_REFRESH_FAILED: _h_ai_core.HaiErrorDef;
+    readonly NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
+    readonly CONFIG_ERROR: _h_ai_core.HaiErrorDef;
+    readonly UNKNOWN: _h_ai_core.HaiErrorDef;
+};
+/**
+ * API 端点契约定义
+ *
+ * 描述单个 API 端点的 HTTP 方法、路径、入参/出参 Schema 与元数据。
+ * 客户端通过 `api.call(endpoint, input)` 调用，服务端通过
+ * `kit.fromContract(endpoint, handler)` 响应，两端共享同一份契约。
+ *
+ * @typeParam TInput - 入参类型（由 Zod Schema 推导）
+ * @typeParam TOutput - 出参类型（由 Zod Schema 推导）
+ *
+ * @example
+ * ```ts
+ * const loginEndpoint: EndpointDef<LoginInput, LoginOutput> = {
+ *   method: 'POST',
+ *   path: '/auth/login',
+ *   input: LoginInputSchema,
+ *   output: LoginOutputSchema,
+ *   requireAuth: false,
+ * }
+ * ```
+ */
+interface EndpointDef<TInput = unknown, TOutput = unknown> {
+    /** HTTP 方法 */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** 相对路径（相对于 API 前缀，如 '/auth/login'） */
+    path: string;
+    /** 入参 Zod Schema（GET 请求为 query params，其他为 body） */
+    input: z.ZodType<TInput>;
+    /** 出参 Zod Schema */
+    output: z.ZodType<TOutput>;
+    /** 是否需要认证（默认 true） */
+    requireAuth?: boolean;
+    /** OpenAPI 描述元数据 */
+    meta?: {
+        summary?: string;
+        tags?: string[];
+    };
+}
+/**
+ * Token 对（与 @h-ai/iam 的 TokenPair 对齐）
+ */
+interface TokenPair {
+    /** Access Token */
+    accessToken: string;
+    /** Refresh Token */
+    refreshToken: string;
+    /** 过期时间（秒） */
+    expiresIn: number;
+    /** Token 类型 */
+    tokenType: 'Bearer';
+}
+/**
+ * Token 存储适配器
+ *
+ * 可插拔存储后端（localStorage / memory / Capacitor Preferences / 自定义）。
+ */
+interface TokenStorage {
+    /** 获取 Access Token */
+    getAccessToken: () => Promise<string | null>;
+    /** 设置 Access Token */
+    setAccessToken: (token: string) => Promise<void>;
+    /** 获取 Refresh Token */
+    getRefreshToken: () => Promise<string | null>;
+    /** 设置 Refresh Token */
+    setRefreshToken: (token: string) => Promise<void>;
+    /** 清空所有 Token */
+    clear: () => Promise<void>;
+}
+/**
+ * 请求配置（传递给拦截器）
+ */
+interface RequestConfig {
+    /** 完整 URL */
+    url: string;
+    /** HTTP 方法 */
+    method: string;
+    /** 请求头 */
+    headers: Record<string, string>;
+    /** 请求体（已序列化） */
+    body?: string | FormData;
+    /** 信号（abort） */
+    signal?: AbortSignal;
+}
+/** 请求拦截器 */
+type RequestInterceptor = (config: RequestConfig) => RequestConfig | Promise<RequestConfig>;
+/** 响应拦截器 */
+type ResponseInterceptor = (response: Response) => Response | Promise<Response>;
+/**
+ * Token 刷新配置
+ */
+interface AuthConfig {
+    /** Token 存储适配器（默认 createLocalStorageTokenStorage） */
+    storage?: TokenStorage;
+    /** Refresh Token 接口路径（相对于 baseUrl） */
+    refreshUrl: string;
+    /** Token 刷新回调 */
+    onTokenRefreshed?: (tokens: TokenPair) => void;
+    /** Token 刷新失败回调（通常用于跳转登录页） */
+    onRefreshFailed?: () => void;
+}
+/**
+ * ApiClient 配置
+ */
+interface ApiClientConfig {
+    /** API 基础 URL（如 https://api.example.com/api/v1） */
+    baseUrl: string;
+    /** Token 认证配置（省略则不启用自动 Token 管理） */
+    auth?: AuthConfig;
+    /** 请求超时（毫秒，默认 30000） */
+    timeout?: number;
+    /** 拦截器 */
+    interceptors?: {
+        request?: RequestInterceptor[];
+        response?: ResponseInterceptor[];
+    };
+    /** 自定义 fetch 实现（用于测试或特殊环境） */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * 文件上传选项
+ */
+interface UploadOptions {
+    /** 文件字段名（默认 'file'） */
+    fieldName?: string;
+    /** 附加表单字段 */
+    extraFields?: Record<string, string>;
+}
+/**
+ * 流式请求选项
+ */
+interface StreamOptions {
+    /** 外部取消信号（例如 AbortController.signal） */
+    signal?: AbortSignal;
+}
+/**
+ * Api Client 实例接口
+ *
+ * 提供通用 HTTP 方法和契约调用能力。
+ */
+interface ApiClient {
+    /** GET 请求 */
+    get: <T>(path: string, params?: Record<string, unknown>) => Promise<HaiResult<T>>;
+    /** POST 请求 */
+    post: <T>(path: string, body?: unknown) => Promise<HaiResult<T>>;
+    /** PUT 请求 */
+    put: <T>(path: string, body?: unknown) => Promise<HaiResult<T>>;
+    /** PATCH 请求 */
+    patch: <T>(path: string, body?: unknown) => Promise<HaiResult<T>>;
+    /** DELETE 请求 */
+    delete: <T>(path: string, params?: Record<string, unknown>) => Promise<HaiResult<T>>;
+    /** 文件上传 */
+    upload: (path: string, file: File | Blob, options?: UploadOptions) => Promise<HaiResult<unknown>>;
+    /** 流式请求（返回 AsyncIterable） */
+    stream: (path: string, body?: unknown, options?: StreamOptions) => AsyncIterable<string>;
+    /**
+     * 契约调用（推荐）
+     *
+     * 基于 EndpointDef 发起请求，路径、方法、入参、出参类型全由契约保证。
+     */
+    call: <TInput, TOutput>(endpoint: EndpointDef<TInput, TOutput>, input: TInput) => Promise<HaiResult<TOutput>>;
+    /** Token 管理 */
+    auth: {
+        /** 设置 Token */
+        setTokens: (tokens: TokenPair) => Promise<void>;
+        /** 清空 Token */
+        clear: () => Promise<void>;
+        /** Token 刷新回调，返回取消订阅函数 */
+        onTokenRefreshed: (callback: (tokens: TokenPair) => void) => () => void;
+    };
+}
+/**
+ * 辅助函数：创建端点定义（获得类型推导）
+ *
+ * @example
+ * ```ts
+ * const login = defineEndpoint({
+ *   method: 'POST',
+ *   path: '/auth/login',
+ *   input: LoginInputSchema,
+ *   output: LoginOutputSchema,
+ *   requireAuth: false,
+ * })
+ * ```
+ */
+declare function defineEndpoint<TInput, TOutput>(def: EndpointDef<TInput, TOutput>): EndpointDef<TInput, TOutput>;
+/**
+ * API 客户端函数接口（单例模式）
+ *
+ * 统一的 API 客户端访问入口：
+ * - `api.init(config)` — 初始化客户端
+ * - `api.close()` — 关闭客户端并释放资源
+ * - `api.get / post / put / patch / delete` — 通用 HTTP 方法
+ * - `api.call(endpoint, input)` — 契约调用
+ * - `api.upload(path, file)` — 文件上传
+ * - `api.stream(path, body)` — 流式请求
+ * - `api.auth` — Token 管理
+ * - `api.config` — 当前配置（未初始化时为 null）
+ * - `api.isInitialized` — 初始化状态
+ */
+interface ApiClientFunctions {
+    /**
+     * 初始化 API 客户端
+     *
+     * 已有实例时会先 close 再重新初始化。
+     *
+     * @param config - 客户端配置
+     * @returns 成功 ok(undefined)；失败返回 err（含 ApiClientError）
+     */
+    init: (config: ApiClientConfig) => Promise<HaiResult<void>>;
+    /**
+     * 关闭 API 客户端并释放资源
+     *
+     * 重复调用不会报错。
+     */
+    close: () => Promise<void>;
+    /** 当前客户端配置；未初始化或已关闭时为 null */
+    readonly config: ApiClientConfig | null;
+    /** 是否已完成初始化 */
+    readonly isInitialized: boolean;
+    /** GET 请求 */
+    readonly get: ApiClient['get'];
+    /** POST 请求 */
+    readonly post: ApiClient['post'];
+    /** PUT 请求 */
+    readonly put: ApiClient['put'];
+    /** PATCH 请求 */
+    readonly patch: ApiClient['patch'];
+    /** DELETE 请求 */
+    readonly delete: ApiClient['delete'];
+    /** 文件上传 */
+    readonly upload: ApiClient['upload'];
+    /**
+     * 流式请求（返回 AsyncIterable）
+     *
+     * @throws 未初始化时抛出异常（async generator 无法返回 HaiResult）
+     */
+    readonly stream: ApiClient['stream'];
+    /** 契约调用（推荐） */
+    readonly call: ApiClient['call'];
+    /** Token 管理 */
+    readonly auth: ApiClient['auth'];
+}
+
+/**
+ * @h-ai/api-client — Token 存储适配器
+ *
+ * 提供 localStorage 和内存两种内置 Token 存储实现。
+ * @module api-client-auth
+ */
+
+/**
+ * 创建基于 localStorage 的 Token 存储
+ *
+ * 适用于浏览器端 SPA / PWA。Capacitor 环境建议使用
+ * `@h-ai/capacitor` 提供的 `CapacitorTokenStorage`。
+ *
+ * @returns TokenStorage 实例
+ *
+ * @example
+ * ```ts
+ * import { api, createLocalStorageTokenStorage } from '@h-ai/api-client'
+ *
+ * await api.init({
+ *   baseUrl: 'https://api.example.com',
+ *   auth: {
+ *     storage: createLocalStorageTokenStorage(),
+ *     refreshUrl: '/auth/refresh',
+ *   },
+ * })
+ * ```
+ */
+declare function createLocalStorageTokenStorage(): TokenStorage;
+/**
+ * 创建内存 Token 存储
+ *
+ * 适用于 Node.js 测试、SSR 或短生命周期场景。
+ * 页面刷新后 Token 丢失。
+ *
+ * @returns TokenStorage 实例
+ *
+ * @example
+ * ```ts
+ * import { api, createMemoryTokenStorage } from '@h-ai/api-client'
+ *
+ * await api.init({
+ *   baseUrl: 'https://api.example.com',
+ *   auth: {
+ *     storage: createMemoryTokenStorage(),
+ *     refreshUrl: '/auth/refresh',
+ *   },
+ * })
+ * ```
+ */
+declare function createMemoryTokenStorage(): TokenStorage;
+
+/**
+ * @h-ai/api-client — 模块入口
+ *
+ * 提供统一的 `api` 对象，管理 HTTP 客户端运行时状态与生命周期。
+ * @module api-client-main
+ */
+
+/**
+ * API 客户端单例
+ *
+ * 使用前必须先调用 `api.init()` 初始化，传入 baseUrl 等配置信息。
+ * 初始化后通过 `api.get`、`api.post`、`api.call` 等方法发起请求。
+ *
+ * @example
+ * ```ts
+ * import { api } from '@h-ai/api-client'
+ *
+ * // 初始化
+ * await api.init({
+ *   baseUrl: 'https://api.example.com/api/v1',
+ *   auth: { refreshUrl: '/auth/refresh' },
+ * })
+ *
+ * // 契约调用
+ * const result = await api.call(loginEndpoint, { identifier: 'alice', password: 'xxx' })
+ *
+ * // 通用 HTTP
+ * const users = await api.get<User[]>('/users', { page: 1 })
+ *
+ * // 关闭
+ * await api.close()
+ * ```
+ */
+declare const api: ApiClientFunctions;
+
+export { type ApiClient, type ApiClientConfig, type ApiClientFunctions, type AuthConfig, type EndpointDef, HaiApiClientError, type RequestConfig, type RequestInterceptor, type ResponseInterceptor, type StreamOptions, type TokenPair, type TokenStorage, type UploadOptions, api, createLocalStorageTokenStorage, createMemoryTokenStorage, defineEndpoint };