@tansr/api-client 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tansr (tansr.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# @tansr/api-client
+
+Tansr 网关薄客户端:用平台 key 直连 Tansr 数据面(OpenAI / Anthropic / OpenAI
+Responses 三协议形)与账面(模型目录 / 用量)。**零依赖**——只用运行时全局
+`fetch` 与 Web Streams,不引 openai/anthropic SDK。
+
+- 运行环境:Node ≥ 20.3(内建 fetch),或任何具备 `fetch`/`ReadableStream` 的
+  现代浏览器 / 边缘运行时;
+- 请求体 passthrough:网关不做协议转换,字段语义与各上游协议一致,本包类型
+  只钉常用字段、其余原样放行。
+
+## 获取 key
+
+登录 Tansr 门户,在 **`/console` → API Keys** 创建 PAT(`tansr_sk_` 前缀;scope
+可选 `data` 或 `data control`——`/v1/usage` 需要 `control`)。登录态 access JWT
+同样可用,两者均走 `Authorization: Bearer`。
+
+## 三行起步
+
+```ts
+import { Tansr } from '@tansr/api-client';
+
+const client = new Tansr({ apiKey: process.env.TANSR_API_KEY }); // 省略 apiKey 时自动读 env TANSR_API_KEY
+const r = await client.chat.completions.create({
+  model: 'kimi-k3',
+  messages: [{ role: 'user', content: '你好' }],
+});
+console.log(r.choices?.[0]?.message?.content);
+console.log(r.meta); // { requestId, cost, balance } —— 消费 x-tansr-* 响应头
+```
+
+自建/私有部署传 `baseUrl`(含 `/v1`):`new Tansr({ apiKey, baseUrl: 'http://127.0.0.1:8787/v1' })`。
+
+## 流式(SSE)
+
+```ts
+const stream = client.chat.completions.stream({ model: 'kimi-k3', messages });
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices?.[0]?.delta?.content ?? '');
+}
+console.log(stream.meta); // 迭代完成后可取;流式无 x-tansr-cost(成本流末才可知),cost 恒 null
+```
+
+- OpenAI 系(chat / responses):`data: [DONE]` 哨兵终止;
+- Anthropic(messages):`event:` 行语义已归一到帧对象的 `type` 字段,流体自然
+  结束即止;
+- 提前 `break` 会取消上游读,网关按断链结算,不留悬挂请求;
+- 流对象单次可迭代。
+
+## 三协议同型 API 面
+
+| 径 | 非流式 | 流式 |
+|----|--------|------|
+| OpenAI chat | `client.chat.completions.create(params)` | `client.chat.completions.stream(params)` |
+| Anthropic messages | `client.messages.create(params)` | `client.messages.stream(params)` |
+| OpenAI Responses | `client.responses.create(params)` | `client.responses.stream(params)` |
+
+目录与账面:
+
+```ts
+const models = await client.models.list();
+const usage = await client.usage.get({ window: '7d', groupBy: 'model' }); // 需 control scope
+```
+
+## 错误处理
+
+```ts
+import { TansrApiError, TansrConnectionError } from '@tansr/api-client';
+
+try {
+  await client.chat.completions.create({ model, messages });
+} catch (err) {
+  if (err instanceof TansrApiError) {
+    // 网关错误信封 { error: { code, message, requestId, detail? } } 的映射
+    console.error(err.status, err.code, err.requestId, err.detail);
+    if (err.status === 402) {/* 余额不足:detail 携 balance / estimatedCost */}
+    if (err.status === 429) {/* 限流:err.retryAfterMs 由 Retry-After 头换算(服务端原值,毫秒) */}
+  } else if (err instanceof TansrConnectionError) {
+    // 网络故障 / 超时(cause 保真底层错误)
+  }
+}
+```
+
+上游 4xx/5xx 由网关原样透传,本包尽力从透传体提取 `code`/`message`,兜底
+`http_<status>`。错误对象永不携带 api key。
+
+## 取消与超时
+
+```ts
+const ac = new AbortController();
+const p = client.messages.create(params, { signal: ac.signal, timeoutMs: 30_000 });
+ac.abort(); // 用户取消:原样抛调用方的 AbortError,不做包装
+```
+
+`timeoutMs`(构造器缺省 600_000)是**一次调用的总预算**:以调用起点计,覆盖整个
+请求生命周期(含流式全程),也含幂等 GET 的 429 重试等待与后续尝试——重试不会
+重新起算。预算耗尽抛 `TansrConnectionError`(`timed out after <timeoutMs>ms`)。
+
+## 重试纪律
+
+- 幂等 GET(`models.list` / `usage.get`)的 429 自动重试:尊重 `Retry-After`
+  (秒、小数秒或 HTTP-date;缺失 / 不可解析时回落 1 s、2 s 退避),上限 2 次;
+- 单次等待钳 **30 s** 上限(`Retry-After` 来自对端,不让远端决定客户端悬挂时长);
+- 等待与重试都在 `timeoutMs` 总预算之内:剩余预算盖不住(钳制后的)等待时**不再等待、
+  不再重试**,直接抛出该 429 的 `TansrApiError`——`status === 429`,`retryAfterMs`
+  携服务端原值(不受 30 s 钳制影响),调用方可据此自行排程:
+
+  ```ts
+  try {
+    await client.models.list({ timeoutMs: 5_000 });
+  } catch (err) {
+    if (err instanceof TansrApiError && err.status === 429 && err.retryAfterMs !== null) {
+      // 预算内放弃重试:按服务端建议自行排程,而不是让本次调用悬挂
+      scheduleRetry(err.retryAfterMs);
+    }
+  }
+  ```
+
+- **POST 数据面一律不自动重试**:网关按请求预扣与结算(计费面),盲重试会
+  重复计费——失败原样抛出,由调用方决策。
+
+## meta 挂载说明
+
+非流式返回值的 `meta` 是**不可枚举**属性:`JSON.stringify(响应)` 不含 meta,
+持久化原始响应体不被污染;注意 `{ ...res }` 展开会丢弃它,先取后展开。
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Tansr 网关薄客户端入口:三行起步——
+ *
+ *   const client = new Tansr({ apiKey: process.env.TANSR_API_KEY });
+ *   const r = await client.chat.completions.create({ model, messages });
+ *
+ * 设计:零依赖(仅全局 fetch / Web Streams,不引 openai/anthropic SDK,不依赖
+ * 仓内 kernel/providers/protocol);数据面请求体原样直达网关(passthrough,
+ * 不做协议转换),三协议(chat/messages/responses)各走各径。api key 只存
+ * 私有字段并落 authorization 头,客户端与错误对象的序列化面零泄漏。
+ */
+import { HttpCore } from './http.js';
+import { TansrStream } from './stream.js';
+import type { AnthropicMessage, ChatCompletion, ChatCompletionChunk, ChatCompletionsCreateParams, MessageStreamEvent, MessagesCreateParams, ModelsListResponse, RequestOptions, ResponseObject, ResponseStreamEvent, ResponsesCreateParams, UsageGetParams, UsageReport, WithMeta } from './types.js';
+export interface TansrOptions {
+    /** 平台 key:PAT(`tansr_sk_` 前缀)或登录 access JWT,均走 Bearer;缺省回落 env TANSR_API_KEY。 */
+    readonly apiKey?: string;
+    /** 网关基址(含 /v1;尾斜杠自动剥除),缺省 https://api.tansr.com/v1。 */
+    readonly baseUrl?: string;
+    /**
+     * 单次调用的总预算(毫秒,以调用起点计):覆盖流式全程,也含幂等 GET 的 429 重试等待与
+     * 后续尝试;剩余预算盖不住 Retry-After(钳 30 s)时不再等待,直接抛 429 TansrApiError
+     * (携 retryAfterMs)。缺省 600_000。
+     */
+    readonly timeoutMs?: number;
+    /** 自定义 fetch(测试注入缝;沿仓惯例命名 fetchImpl),缺省全局 fetch。 */
+    readonly fetchImpl?: typeof fetch;
+    /** 逐请求附加头(如 org 作用域 x-tansr-org);authorization/content-type/accept 不可覆盖。 */
+    readonly defaultHeaders?: Readonly<Record<string, string>>;
+}
+/** OpenAI chat completions 形数据面(POST /v1/chat/completions)。 */
+export declare class ChatCompletions {
+    #private;
+    constructor(core: HttpCore);
+    /** 非流式;返回值挂 meta { requestId, cost, balance }(消费响应头)。 */
+    create(params: ChatCompletionsCreateParams, options?: RequestOptions): Promise<WithMeta<ChatCompletion>>;
+    /** SSE 流式(AsyncIterable 逐帧;`data: [DONE]` 终止;stream.meta 迭代完成后可取)。 */
+    stream(params: ChatCompletionsCreateParams, options?: RequestOptions): TansrStream<ChatCompletionChunk>;
+}
+/** Anthropic messages 形数据面(POST /v1/messages)。 */
+export declare class Messages {
+    #private;
+    constructor(core: HttpCore);
+    create(params: MessagesCreateParams, options?: RequestOptions): Promise<WithMeta<AnthropicMessage>>;
+    /** SSE 流式(`event:` 行语义归一到 type;流体自然结束即止)。 */
+    stream(params: MessagesCreateParams, options?: RequestOptions): TansrStream<MessageStreamEvent>;
+}
+/** OpenAI Responses 形数据面(POST /v1/responses)。 */
+export declare class Responses {
+    #private;
+    constructor(core: HttpCore);
+    create(params: ResponsesCreateParams, options?: RequestOptions): Promise<WithMeta<ResponseObject>>;
+    stream(params: ResponsesCreateParams, options?: RequestOptions): TansrStream<ResponseStreamEvent>;
+}
+/** 模型目录(GET /v1/models;幂等 GET,429 自动重试至多 2 次)。 */
+export declare class Models {
+    #private;
+    constructor(core: HttpCore);
+    list(options?: RequestOptions): Promise<WithMeta<ModelsListResponse>>;
+}
+/** 用量账面(GET /v1/usage;需 key 具 control scope)。 */
+export declare class Usage {
+    #private;
+    constructor(core: HttpCore);
+    get(params?: UsageGetParams, options?: RequestOptions): Promise<WithMeta<UsageReport>>;
+}
+export declare class Tansr {
+    readonly chat: {
+        readonly completions: ChatCompletions;
+    };
+    readonly messages: Messages;
+    readonly responses: Responses;
+    readonly models: Models;
+    readonly usage: Usage;
+    /** 生效的网关基址(尾斜杠已剥除)。 */
+    readonly baseUrl: string;
+    constructor(options?: TansrOptions);
+}

package/dist/client.js

@@ -0,0 +1,150 @@
+/**
+ * Tansr 网关薄客户端入口:三行起步——
+ *
+ *   const client = new Tansr({ apiKey: process.env.TANSR_API_KEY });
+ *   const r = await client.chat.completions.create({ model, messages });
+ *
+ * 设计:零依赖(仅全局 fetch / Web Streams,不引 openai/anthropic SDK,不依赖
+ * 仓内 kernel/providers/protocol);数据面请求体原样直达网关(passthrough,
+ * 不做协议转换),三协议(chat/messages/responses)各走各径。api key 只存
+ * 私有字段并落 authorization 头,客户端与错误对象的序列化面零泄漏。
+ */
+import { HttpCore } from './http.js';
+import { TansrStream } from './stream.js';
+import { TansrConnectionError } from './errors.js';
+const DEFAULT_BASE_URL = 'https://api.tansr.com/v1';
+const DEFAULT_TIMEOUT_MS = 600_000;
+/** OpenAI chat completions 形数据面(POST /v1/chat/completions)。 */
+export class ChatCompletions {
+    #core;
+    constructor(core) {
+        this.#core = core;
+    }
+    /** 非流式;返回值挂 meta { requestId, cost, balance }(消费响应头)。 */
+    async create(params, options) {
+        assertNotStreamParams(params, 'chat.completions');
+        const { json, meta } = await this.#core.requestJson('POST', '/chat/completions', { body: params }, perRequest(options));
+        return withMeta(json, meta);
+    }
+    /** SSE 流式(AsyncIterable 逐帧;`data: [DONE]` 终止;stream.meta 迭代完成后可取)。 */
+    stream(params, options) {
+        return new TansrStream(() => this.#core.openStream('/chat/completions', { ...params, stream: true }, perRequest(options)));
+    }
+}
+/** Anthropic messages 形数据面(POST /v1/messages)。 */
+export class Messages {
+    #core;
+    constructor(core) {
+        this.#core = core;
+    }
+    async create(params, options) {
+        assertNotStreamParams(params, 'messages');
+        const { json, meta } = await this.#core.requestJson('POST', '/messages', { body: params }, perRequest(options));
+        return withMeta(json, meta);
+    }
+    /** SSE 流式(`event:` 行语义归一到 type;流体自然结束即止)。 */
+    stream(params, options) {
+        return new TansrStream(() => this.#core.openStream('/messages', { ...params, stream: true }, perRequest(options)));
+    }
+}
+/** OpenAI Responses 形数据面(POST /v1/responses)。 */
+export class Responses {
+    #core;
+    constructor(core) {
+        this.#core = core;
+    }
+    async create(params, options) {
+        assertNotStreamParams(params, 'responses');
+        const { json, meta } = await this.#core.requestJson('POST', '/responses', { body: params }, perRequest(options));
+        return withMeta(json, meta);
+    }
+    stream(params, options) {
+        return new TansrStream(() => this.#core.openStream('/responses', { ...params, stream: true }, perRequest(options)));
+    }
+}
+/** 模型目录(GET /v1/models;幂等 GET,429 自动重试至多 2 次)。 */
+export class Models {
+    #core;
+    constructor(core) {
+        this.#core = core;
+    }
+    async list(options) {
+        const { json, meta } = await this.#core.requestJson('GET', '/models', {}, perRequest(options));
+        return withMeta(json, meta);
+    }
+}
+/** 用量账面(GET /v1/usage;需 key 具 control scope)。 */
+export class Usage {
+    #core;
+    constructor(core) {
+        this.#core = core;
+    }
+    async get(params = {}, options) {
+        const groupBy = params.groupBy === undefined
+            ? undefined
+            : typeof params.groupBy === 'string'
+                ? params.groupBy
+                : params.groupBy.join(',');
+        const query = { window: params.window, groupBy };
+        const { json, meta } = await this.#core.requestJson('GET', '/usage', { query }, perRequest(options));
+        return withMeta(json, meta);
+    }
+}
+export class Tansr {
+    chat;
+    messages;
+    responses;
+    models;
+    usage;
+    /** 生效的网关基址(尾斜杠已剥除)。 */
+    baseUrl;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ?? envApiKey();
+        if (typeof apiKey !== 'string' || apiKey === '') {
+            // 消息只提示来源,永不回显任何 key 材料
+            throw new TypeError('tansr api key is required: pass { apiKey } or set the TANSR_API_KEY env var');
+        }
+        const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        if (typeof fetchImpl !== 'function') {
+            throw new TypeError('global fetch is unavailable: pass { fetchImpl } (Node >= 20.3 has fetch built in)');
+        }
+        const core = new HttpCore({
+            apiKey,
+            baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+            timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            fetchImpl,
+            defaultHeaders: options.defaultHeaders ?? {},
+        });
+        this.baseUrl = core.baseUrl;
+        this.chat = { completions: new ChatCompletions(core) };
+        this.messages = new Messages(core);
+        this.responses = new Responses(core);
+        this.models = new Models(core);
+        this.usage = new Usage(core);
+    }
+}
+/** 浏览器/边缘运行时无 process:安全探测,不硬依赖 node 类型面。 */
+function envApiKey() {
+    const proc = globalThis.process;
+    return proc?.env?.TANSR_API_KEY;
+}
+function perRequest(options) {
+    return { signal: options?.signal, timeoutMs: options?.timeoutMs };
+}
+/** create 径拒收 stream: true——流式必须走 .stream()(返回形态不同,静默降级会误导)。 */
+function assertNotStreamParams(params, label) {
+    if (params.stream === true) {
+        throw new TypeError(`${label}.create() does not stream; use ${label}.stream(...) instead`);
+    }
+}
+/**
+ * meta 以不可枚举属性挂载:JSON.stringify(响应) 不含 meta,原始响应体持久化
+ * 不被污染(注意 { ...res } 展开会丢弃 meta,先取后展开)。
+ */
+function withMeta(value, meta) {
+    if (typeof value !== 'object' || value === null) {
+        throw new TansrConnectionError('gateway returned a non-object JSON body');
+    }
+    Object.defineProperty(value, 'meta', { value: meta, enumerable: false, configurable: true });
+    return value;
+}

package/dist/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @tansr/api-client 错误面。
+ *
+ * 两类错误:
+ * - TansrApiError:网关给出了 HTTP 错误响应——tansr 错误信封
+ *   `{ error: { code, message, requestId, detail? } }`,或上游 4xx/5xx 透传体
+ *   (网关不造方言,原样转发,本客户端尽力提取 code/message)。
+ *   402 余额不足 / 429 限流(带 retryAfterMs)均为其实例。
+ * - TansrConnectionError:请求根本没到达或没读完(网络故障、超时、响应体
+ *   非法 JSON)。用户主动 AbortSignal 取消不属于两者——原样上抛调用方的
+ *   中止异常(AbortError),不做包装。
+ *
+ * 纪律:错误对象只携带服务端返回的信息与状态码,构造参数里没有、也永不
+ * 引用 api key / authorization 头(零泄漏;测试对序列化面有专项断言)。
+ */
+export interface TansrApiErrorArgs {
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    readonly requestId?: string | null;
+    readonly detail?: Record<string, unknown> | null;
+    readonly retryAfterMs?: number | null;
+}
+/** 网关 HTTP 错误(错误信封映射;402/429 等均为本类实例,按 status/code 分派)。 */
+export declare class TansrApiError extends Error {
+    /** HTTP 状态码(402 余额不足、429 限流、4xx/5xx 上游透传等)。 */
+    readonly status: number;
+    /** 稳定错误码(tansr 信封 code;上游透传时尽力取 code/type,兜底 `http_<status>`)。 */
+    readonly code: string;
+    /** 服务端请求标识(信封 requestId,缺省回落 x-tansr-request-id 头),用于回执排障。 */
+    readonly requestId: string | null;
+    /** 信封附加细节(如 402 的 { balance, estimatedCost });上游透传体无此位。 */
+    readonly detail: Record<string, unknown> | null;
+    /**
+     * 429 时由 Retry-After 头(秒 / HTTP-date)/ 信封 detail.retryAfterSec 换算成毫秒;其余情形为 null。
+     * 恒为服务端原值:客户端自动重试的等待另有 30 s 钳制与 timeoutMs 总预算,不改写此字段——
+     * 预算内放弃重试时调用方仍据此自行排程。
+     */
+    readonly retryAfterMs: number | null;
+    constructor(args: TansrApiErrorArgs);
+}
+/** 网络层故障:连不上网关 / 超时 / 响应体读取或解析失败(cause 保真底层错误)。 */
+export declare class TansrConnectionError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,48 @@
+/**
+ * @tansr/api-client 错误面。
+ *
+ * 两类错误:
+ * - TansrApiError:网关给出了 HTTP 错误响应——tansr 错误信封
+ *   `{ error: { code, message, requestId, detail? } }`,或上游 4xx/5xx 透传体
+ *   (网关不造方言,原样转发,本客户端尽力提取 code/message)。
+ *   402 余额不足 / 429 限流(带 retryAfterMs)均为其实例。
+ * - TansrConnectionError:请求根本没到达或没读完(网络故障、超时、响应体
+ *   非法 JSON)。用户主动 AbortSignal 取消不属于两者——原样上抛调用方的
+ *   中止异常(AbortError),不做包装。
+ *
+ * 纪律:错误对象只携带服务端返回的信息与状态码,构造参数里没有、也永不
+ * 引用 api key / authorization 头(零泄漏;测试对序列化面有专项断言)。
+ */
+/** 网关 HTTP 错误(错误信封映射;402/429 等均为本类实例,按 status/code 分派)。 */
+export class TansrApiError extends Error {
+    /** HTTP 状态码(402 余额不足、429 限流、4xx/5xx 上游透传等)。 */
+    status;
+    /** 稳定错误码(tansr 信封 code;上游透传时尽力取 code/type,兜底 `http_<status>`)。 */
+    code;
+    /** 服务端请求标识(信封 requestId,缺省回落 x-tansr-request-id 头),用于回执排障。 */
+    requestId;
+    /** 信封附加细节(如 402 的 { balance, estimatedCost });上游透传体无此位。 */
+    detail;
+    /**
+     * 429 时由 Retry-After 头(秒 / HTTP-date)/ 信封 detail.retryAfterSec 换算成毫秒;其余情形为 null。
+     * 恒为服务端原值:客户端自动重试的等待另有 30 s 钳制与 timeoutMs 总预算,不改写此字段——
+     * 预算内放弃重试时调用方仍据此自行排程。
+     */
+    retryAfterMs;
+    constructor(args) {
+        super(args.message);
+        this.name = 'TansrApiError';
+        this.status = args.status;
+        this.code = args.code;
+        this.requestId = args.requestId ?? null;
+        this.detail = args.detail ?? null;
+        this.retryAfterMs = args.retryAfterMs ?? null;
+    }
+}
+/** 网络层故障:连不上网关 / 超时 / 响应体读取或解析失败(cause 保真底层错误)。 */
+export class TansrConnectionError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'TansrConnectionError';
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,57 @@
+import type { ResponseMeta } from './types.js';
+export declare const HEADER_REQUEST_ID = "x-tansr-request-id";
+export declare const HEADER_COST = "x-tansr-cost";
+export declare const HEADER_BALANCE = "x-tansr-balance";
+/**
+ * 计时缝(包内私有,不经 index.ts 导出):产品缺省用运行时全局计时器;测试注入虚拟时钟,
+ * 以确定性推进验证总预算 / 钳制等时序语义,不靠真实等待。
+ */
+export interface HttpClock {
+    readonly now: () => number;
+    readonly setTimeout: (callback: () => void, delayMs: number) => unknown;
+    readonly clearTimeout: (handle: unknown) => void;
+}
+export interface HttpCoreOptions {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    readonly fetchImpl: typeof fetch;
+    readonly defaultHeaders: Readonly<Record<string, string>>;
+    /** 计时缝(测试注入;缺省全局计时器)。 */
+    readonly clock?: HttpClock | undefined;
+}
+export interface PerRequestOptions {
+    readonly signal?: AbortSignal | undefined;
+    readonly timeoutMs?: number | undefined;
+}
+/** openStream 返回的流句柄:响应 + meta + 停表/中断归因钩子(供 TansrStream 消费)。 */
+export interface StreamHandle {
+    readonly response: Response;
+    readonly meta: ResponseMeta;
+    /** 流读毕/中止后停表(超时计时器覆盖流全程,必须成对调用)。 */
+    readonly finish: () => void;
+    /** 流中断归因:超时 → TansrConnectionError;用户取消 → 原样返回;其余包装网络错误。 */
+    readonly mapStreamError: (err: unknown) => unknown;
+}
+export declare function metaFromHeaders(headers: Headers): ResponseMeta;
+export declare class HttpCore {
+    #private;
+    readonly baseUrl: string;
+    constructor(opts: HttpCoreOptions);
+    /**
+     * 非流式 JSON 请求(GET 走 429 重试纪律;2xx 断言对象体并回 meta)。
+     * 整个循环(每次 fetch + 体读取 + 重试等待)共用一个以调用起点计的总预算。
+     */
+    requestJson(method: 'GET' | 'POST', path: string, args: {
+        readonly query?: Record<string, string | undefined>;
+        readonly body?: unknown;
+    }, opts?: PerRequestOptions): Promise<{
+        json: Record<string, unknown>;
+        meta: ResponseMeta;
+    }>;
+    /**
+     * 流式请求(POST,accept: text/event-stream):零重试(计费面,见头注)。
+     * 非 2xx 在此按错误信封抛出;2xx 交还句柄由 TansrStream 逐帧消费。
+     */
+    openStream(path: string, body: unknown, opts?: PerRequestOptions): Promise<StreamHandle>;
+}