@sparqjs/api-client 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# @sparqjs/api-client
+
+`@sparqjs/api-client` 是 Sparq 前端共享的 HTTP 传输层。它封装 Axios、请求配置、响应 envelope 解包和统一错误，不承载 Admin、Schema、Storage、Settings 或插件业务协议。
+
+## 负责范围
+
+- 配置 `baseURL`、Cookie、Header、Token、CSRF、超时和参数序列化。
+- 解包后端 `code/data/message` 响应。
+- 将 HTTP、网络和业务 envelope 错误归一化为 `SparqApiError`。
+- 提供 response、error、unauthorized 和 forbidden hooks。
+- 透传 Axios 支持的 `AbortSignal`、上传进度等单次请求配置。
+
+## 不负责范围
+
+- 不增加 `schema`、`storage`、`settings`、`admin` 等领域 namespace。
+- 不依赖 Vue、Router、Pinia、schema core 或 schema protocol。
+- 不定义业务 DTO、页面反馈、登录状态或 `DataAdapter`。
+- 不向插件暴露宿主 Admin 已配置 Cookie 和 CSRF 的 transport 实例。
+
+领域 HTTP adapter 应放在真实消费者中。Admin 的正式实现位于 `apps/admin/src/client/api`，Stage 的验证实现位于 `apps/stage/src/api`；两者分别满足自身运行场景，不为表面复用提前拆成新包。
+
+## 使用方式
+
+```ts
+import { createSparqApiClient } from '@sparqjs/api-client'
+
+const transport = createSparqApiClient({
+    baseURL: '/api',
+    withCredentials: true,
+})
+
+const result = await transport.request<{ id: string }>({
+    method: 'GET',
+    url: '/records/1',
+})
+```
+
+宿主应用应按认证边界创建 transport。Admin 当前只创建一个 authority-scoped 实例，认证、管理和 schema 领域 adapter 共同复用该实例。

package/dist/client.d.ts

@@ -0,0 +1,6 @@
+import type { CreateSparqApiClientOptions, SparqApiClient } from './types';
+/**
+ * 创建 Sparq API client。
+ */
+export declare function createSparqApiClient(options?: CreateSparqApiClientOptions): SparqApiClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,2BAA2B,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE1E;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,2BAAgC,GAAG,cAAc,CAE9F"}

package/dist/client.js

@@ -0,0 +1,8 @@
+import { createRequestExecutor } from './request';
+/**
+ * 创建 Sparq API client。
+ */
+export function createSparqApiClient(options = {}) {
+    return createRequestExecutor(options);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AAGjD;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAAuC,EAAE;IAC1E,OAAO,qBAAqB,CAAC,OAAO,CAAC,CAAA;AACzC,CAAC"}

package/dist/error.d.ts

@@ -0,0 +1,21 @@
+import type { SparqApiError } from './types';
+/**
+ * 创建标准 API 错误。
+ */
+export declare function createSparqApiError(input: {
+    status?: number;
+    code?: string;
+    message?: string;
+    details?: unknown;
+    requestId?: string;
+    raw?: unknown;
+}): SparqApiError;
+/**
+ * 把 axios 或未知错误归一化为 SparqApiError。
+ */
+export declare function normalizeApiError(error: unknown): SparqApiError;
+/**
+ * 判断是否已经是标准 API 错误。
+ */
+export declare function isSparqApiError(error: unknown): error is SparqApiError;
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACvC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,GAAG,CAAC,EAAE,OAAO,CAAA;CAChB,GAAG,aAAa,CA+BhB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAiC/D;AAcD;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE"}

package/dist/error.js

@@ -0,0 +1,119 @@
+import axios from 'axios';
+/**
+ * 创建标准 API 错误。
+ */
+export function createSparqApiError(input) {
+    const error = new Error(input.message || '请求失败');
+    Object.defineProperties(error, {
+        name: {
+            value: 'SparqApiError',
+            enumerable: true,
+        },
+        status: {
+            value: input.status ?? 0,
+            enumerable: true,
+        },
+        code: {
+            value: input.code || 'API_ERROR',
+            enumerable: true,
+        },
+        details: {
+            value: input.details,
+            enumerable: true,
+        },
+        requestId: {
+            value: input.requestId,
+            enumerable: true,
+        },
+        raw: {
+            value: input.raw,
+            enumerable: false,
+        },
+    });
+    return error;
+}
+/**
+ * 把 axios 或未知错误归一化为 SparqApiError。
+ */
+export function normalizeApiError(error) {
+    if (isSparqApiError(error)) {
+        return error;
+    }
+    if (axios.isAxiosError(error)) {
+        const response = error.response;
+        const data = response?.data;
+        const body = isRecord(data) ? data : undefined;
+        const status = response?.status ?? 0;
+        const requestId = readRequestId(response?.headers);
+        return createSparqApiError({
+            status,
+            code: readCode(body) || readString(body, 'error') || readAxiosErrorCode(error) || fallbackCode(status),
+            message: readString(body, 'message') || error.message || fallbackMessage(status),
+            details: body?.details ?? body?.errors ?? body?.data,
+            requestId,
+            raw: error,
+        });
+    }
+    if (error instanceof Error) {
+        return createSparqApiError({
+            message: error.message,
+            raw: error,
+        });
+    }
+    return createSparqApiError({
+        message: String(error || '请求失败'),
+        raw: error,
+    });
+}
+function readAxiosErrorCode(error) {
+    return typeof error.code === 'string' && error.code.trim() !== '' ? error.code : undefined;
+}
+function readCode(record) {
+    const value = record?.code;
+    if (typeof value === 'number') {
+        return String(value);
+    }
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+/**
+ * 判断是否已经是标准 API 错误。
+ */
+export function isSparqApiError(error) {
+    return isRecord(error) && error.name === 'SparqApiError';
+}
+function fallbackCode(status) {
+    if (status === 401) {
+        return 'UNAUTHORIZED';
+    }
+    if (status === 403) {
+        return 'FORBIDDEN';
+    }
+    if (status >= 500) {
+        return 'SERVER_ERROR';
+    }
+    return 'API_ERROR';
+}
+function fallbackMessage(status) {
+    if (status === 401) {
+        return '登录状态已失效';
+    }
+    if (status === 403) {
+        return '没有权限执行该操作';
+    }
+    return '请求失败';
+}
+function readString(record, key) {
+    const value = record?.[key];
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+function readRequestId(headers) {
+    if (!isRecord(headers)) {
+        return undefined;
+    }
+    const value = headers['x-request-id'] ?? headers['X-Request-Id'];
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+//# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAOnC;IACG,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,IAAI,MAAM,CAAkB,CAAA;IAEjE,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE;QAC3B,IAAI,EAAE;YACF,KAAK,EAAE,eAAe;YACtB,UAAU,EAAE,IAAI;SACnB;QACD,MAAM,EAAE;YACJ,KAAK,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC;YACxB,UAAU,EAAE,IAAI;SACnB;QACD,IAAI,EAAE;YACF,KAAK,EAAE,KAAK,CAAC,IAAI,IAAI,WAAW;YAChC,UAAU,EAAE,IAAI;SACnB;QACD,OAAO,EAAE;YACL,KAAK,EAAE,KAAK,CAAC,OAAO;YACpB,UAAU,EAAE,IAAI;SACnB;QACD,SAAS,EAAE;YACP,KAAK,EAAE,KAAK,CAAC,SAAS;YACtB,UAAU,EAAE,IAAI;SACnB;QACD,GAAG,EAAE;YACD,KAAK,EAAE,KAAK,CAAC,GAAG;YAChB,UAAU,EAAE,KAAK;SACpB;KACJ,CAAC,CAAA;IAEF,OAAO,KAAK,CAAA;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC5C,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAA;IAChB,CAAC;IAED,IAAI,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;QAC/B,MAAM,IAAI,GAAG,QAAQ,EAAE,IAAI,CAAA;QAC3B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;QAC9C,MAAM,MAAM,GAAG,QAAQ,EAAE,MAAM,IAAI,CAAC,CAAA;QACpC,MAAM,SAAS,GAAG,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;QAElD,OAAO,mBAAmB,CAAC;YACvB,MAAM;YACN,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,kBAAkB,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,MAAM,CAAC;YACtG,OAAO,EAAE,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,KAAK,CAAC,OAAO,IAAI,eAAe,CAAC,MAAM,CAAC;YAChF,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,IAAI,IAAI,EAAE,IAAI;YACpD,SAAS;YACT,GAAG,EAAE,KAAK;SACb,CAAC,CAAA;IACN,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QACzB,OAAO,mBAAmB,CAAC;YACvB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,GAAG,EAAE,KAAK;SACb,CAAC,CAAA;IACN,CAAC;IAED,OAAO,mBAAmB,CAAC;QACvB,OAAO,EAAE,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC;QAChC,GAAG,EAAE,KAAK;KACb,CAAC,CAAA;AACN,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAwB;IAChD,OAAO,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AAC9F,CAAC;AAED,SAAS,QAAQ,CAAC,MAA2C;IACzD,MAAM,KAAK,GAAG,MAAM,EAAE,IAAI,CAAA;IAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;IACxB,CAAC;IACD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AAC/E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC1C,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,CAAA;AAC5D,CAAC;AAED,SAAS,YAAY,CAAC,MAAc;IAChC,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACjB,OAAO,cAAc,CAAA;IACzB,CAAC;IACD,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACjB,OAAO,WAAW,CAAA;IACtB,CAAC;IACD,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;QAChB,OAAO,cAAc,CAAA;IACzB,CAAC;IACD,OAAO,WAAW,CAAA;AACtB,CAAC;AAED,SAAS,eAAe,CAAC,MAAc;IACnC,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACjB,OAAO,SAAS,CAAA;IACpB,CAAC;IACD,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACjB,OAAO,WAAW,CAAA;IACtB,CAAC;IACD,OAAO,MAAM,CAAA;AACjB,CAAC;AAED,SAAS,UAAU,CAAC,MAA2C,EAAE,GAAW;IACxE,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,CAAA;IAC3B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AAC/E,CAAC;AAED,SAAS,aAAa,CAAC,OAAgB;IACnC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACrB,OAAO,SAAS,CAAA;IACpB,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,cAAc,CAAC,IAAI,OAAO,CAAC,cAAc,CAAC,CAAA;IAChE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AAC/E,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAA;AACtD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createSparqApiClient } from './client';
+export { createSparqApiError, isSparqApiError, normalizeApiError } from './error';
+export type { CreateSparqApiClientOptions, SparqApiClient, SparqApiClientHooks, SparqApiError, SparqRequestConfig, } from './types';
+//# 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,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAC/C,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AACjF,YAAY,EACR,2BAA2B,EAC3B,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,kBAAkB,GACrB,MAAM,SAAS,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createSparqApiClient } from './client';
+export { createSparqApiError, isSparqApiError, normalizeApiError } from './error';
+//# 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,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAC/C,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA"}

package/dist/request.d.ts

@@ -0,0 +1,6 @@
+import type { CreateSparqApiClientOptions, SparqApiClient } from './types';
+/**
+ * 创建底层请求执行器。
+ */
+export declare function createRequestExecutor(options: CreateSparqApiClientOptions): Pick<SparqApiClient, 'http' | 'request'>;
+//# sourceMappingURL=request.d.ts.map

package/dist/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,2BAA2B,EAAE,cAAc,EAAsB,MAAM,SAAS,CAAA;AAE9F;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,2BAA2B,GAAG,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC,CAuEpH"}

package/dist/request.js

@@ -0,0 +1,106 @@
+import axios from 'axios';
+import { createSparqApiError, normalizeApiError } from './error';
+/**
+ * 创建底层请求执行器。
+ */
+export function createRequestExecutor(options) {
+    const http = options.axios ??
+        axios.create({
+            baseURL: options.baseURL,
+            timeout: options.timeout,
+            withCredentials: options.withCredentials,
+            paramsSerializer: {
+                serialize: serializeParams,
+            },
+        });
+    http.interceptors.request.use((config) => {
+        const token = options.getToken?.();
+        const dynamicHeaders = options.getHeaders?.();
+        if (token) {
+            config.headers = config.headers ?? {};
+            config.headers.Authorization = `Bearer ${token}`;
+        }
+        if (dynamicHeaders) {
+            for (const [key, value] of Object.entries(dynamicHeaders)) {
+                if (value !== undefined && value !== null) {
+                    config.headers = config.headers ?? {};
+                    config.headers[key] = value;
+                }
+            }
+        }
+        return config;
+    });
+    http.interceptors.response.use((response) => {
+        options.onResponse?.(response);
+        return response;
+    }, (error) => {
+        if (axios.isAxiosError(error) && error.response) {
+            options.onResponse?.(error.response);
+        }
+        return Promise.reject(error);
+    });
+    async function request(config) {
+        const silent = config.silent ?? options.silent ?? false;
+        try {
+            const response = await http.request(config);
+            return unwrapResponseData(response.data);
+        }
+        catch (caught) {
+            const error = normalizeApiError(caught);
+            if (!silent) {
+                if (error.status === 401) {
+                    options.onUnauthorized?.(error);
+                }
+                else if (error.status === 403) {
+                    options.onForbidden?.(error);
+                }
+                options.onError?.(error);
+            }
+            throw error;
+        }
+    }
+    return {
+        http,
+        request,
+    };
+}
+function serializeParams(params) {
+    if (!isRecord(params)) {
+        return '';
+    }
+    const values = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === '') {
+            continue;
+        }
+        if (typeof value === 'object') {
+            values.set(key, JSON.stringify(value));
+            continue;
+        }
+        values.set(key, String(value));
+    }
+    return values.toString();
+}
+function unwrapResponseData(data) {
+    if (!isRecord(data)) {
+        return data;
+    }
+    if (typeof data.code === 'number' && 'data' in data) {
+        if (data.code === 0) {
+            return data.data;
+        }
+        const details = data.data;
+        throw createSparqApiError({
+            status: 200,
+            code: isRecord(details) && typeof details.code === 'string' ? details.code : String(data.code),
+            message: typeof data.message === 'string' ? data.message : '请求失败',
+            details,
+            raw: data,
+        });
+    }
+    return data;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+//# sourceMappingURL=request.js.map

package/dist/request.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,63 @@
+import type { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';
+/**
+ * 请求生命周期钩子。
+ *
+ * api-client 只负责触发钩子，不直接绑定任何 UI 提示组件。
+ */
+export interface SparqApiClientHooks {
+    /** 收到 HTTP 响应时触发，包括非 2xx 响应。 */
+    onResponse?: (response: AxiosResponse) => void;
+    /** 请求失败时触发。silent 请求不会触发该钩子。 */
+    onError?: (error: SparqApiError) => void;
+    /** HTTP 401 时触发。 */
+    onUnauthorized?: (error: SparqApiError) => void;
+    /** HTTP 403 时触发。 */
+    onForbidden?: (error: SparqApiError) => void;
+}
+/**
+ * 创建 Sparq API client 的配置。
+ */
+export interface CreateSparqApiClientOptions extends SparqApiClientHooks {
+    /** API 根地址，例如 /api。 */
+    baseURL?: string;
+    /** 请求超时时间。 */
+    timeout?: number;
+    /** 是否携带 cookie。 */
+    withCredentials?: boolean;
+    /** 动态读取认证 token。 */
+    getToken?: () => string | undefined | null;
+    /** 动态读取附加请求头，例如租户、应用或插件上下文。 */
+    getHeaders?: () => Record<string, string | undefined | null>;
+    /** 自定义 axios 实例，测试或高级接入时使用。 */
+    axios?: AxiosInstance;
+    /** 默认是否静默错误。 */
+    silent?: boolean;
+}
+/**
+ * 单次请求配置。
+ */
+export interface SparqRequestConfig<TData = unknown> extends AxiosRequestConfig<TData> {
+    /** 静默请求不会触发 onError/onUnauthorized/onForbidden。 */
+    silent?: boolean;
+}
+/**
+ * Sparq API client 实例。
+ */
+export interface SparqApiClient {
+    /** 底层 axios 实例。 */
+    readonly http: AxiosInstance;
+    /** 执行请求并返回响应业务数据。 */
+    request<T = unknown, TData = unknown>(config: SparqRequestConfig<TData>): Promise<T>;
+}
+/**
+ * 归一化后的 API 错误。
+ */
+export interface SparqApiError extends Error {
+    readonly name: 'SparqApiError';
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    readonly requestId?: string;
+    readonly raw?: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAE7E;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAChC,gCAAgC;IAChC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAA;IAC9C,gCAAgC;IAChC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;IACxC,oBAAoB;IACpB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;IAC/C,oBAAoB;IACpB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,2BAA4B,SAAQ,mBAAmB;IACpE,uBAAuB;IACvB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,cAAc;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mBAAmB;IACnB,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,GAAG,IAAI,CAAA;IAC1C,+BAA+B;IAC/B,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,CAAA;IAC5D,+BAA+B;IAC/B,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,gBAAgB;IAChB,MAAM,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,KAAK,GAAG,OAAO,CAAE,SAAQ,kBAAkB,CAAC,KAAK,CAAC;IAClF,mDAAmD;IACnD,MAAM,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,mBAAmB;IACnB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,qBAAqB;IACrB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO,EAAE,MAAM,EAAE,kBAAkB,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;CACvF;AAED;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CACzB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@sparqjs/api-client",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "axios": "^1.7.0"
+  }
+}