@tansr/api-client 0.2.0

package/dist/http.js

@@ -0,0 +1,308 @@
+/**
+ * HTTP 核:鉴权头落笔、超时/取消合流、错误信封映射、meta 头消费与重试纪律。
+ *
+ * - 重试纪律:仅幂等 GET 的 429 自动重试(尊重 Retry-After,上限 2 次)。
+ *   POST 数据面(chat/messages/responses)一律不自动重试——网关按请求预扣
+ *   与结算(计费面),盲重试会造成重复计费,失败语义原样交还调用方决策。
+ * - 超时语义:timeoutMs 是一次调用的**总预算(deadline)**,以调用起点计,覆盖整个
+ *   请求生命周期——非流式含体读取,流式含全程,GET 429 的每次重试等待与后续尝试
+ *   都以剩余预算为界。Retry-After 的等待钳 MAX_RETRY_AFTER_WAIT_MS 上限;剩余
+ *   预算盖不住等待时不再等待、不再重试,直接按 429 错误信封抛 TansrApiError
+ *   (retryAfterMs 携服务端原值,不钳制,供调用方自行排程)。超时归因
+ *   TansrConnectionError,用户 AbortSignal 取消则原样上抛不包装。
+ * - key 纪律:api key 仅存本核私有字段,只写进请求 authorization 头;
+ *   永不进错误对象/日志/序列化面(defaultHeaders 不可覆盖 authorization)。
+ */
+import { TansrApiError, TansrConnectionError } from './errors.js';
+export const HEADER_REQUEST_ID = 'x-tansr-request-id';
+export const HEADER_COST = 'x-tansr-cost';
+export const HEADER_BALANCE = 'x-tansr-balance';
+const HEADER_RETRY_AFTER = 'retry-after';
+/** GET 429 重试上限(不含首次请求)。 */
+const MAX_GET_RETRIES = 2;
+/** Retry-After 缺失/不可解析时的回落退避(毫秒,按第 n 次重试取位)。 */
+const FALLBACK_BACKOFF_MS = [1_000, 2_000];
+/**
+ * 单次重试等待的上限(毫秒):Retry-After 来自对端,不钳制等于让远端决定客户端悬挂时长。
+ * 只钳等待,不改错误对象里回报的 retryAfterMs(服务端原值)。
+ */
+const MAX_RETRY_AFTER_WAIT_MS = 30_000;
+const REAL_CLOCK = {
+    now: () => Date.now(),
+    setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+/** 一次调用的总预算:以调用起点计 deadline,重试等待与每次 fetch 都以剩余预算为界。 */
+class Deadline {
+    /** 调用方给的总预算(毫秒;超时文案回报此值)。 */
+    totalMs;
+    #endsAt;
+    #clock;
+    constructor(totalMs, clock) {
+        this.totalMs = totalMs;
+        this.#endsAt = clock.now() + totalMs;
+        this.#clock = clock;
+    }
+    /** 剩余预算(毫秒;耗尽后为 0)。 */
+    remainingMs() {
+        return Math.max(0, this.#endsAt - this.#clock.now());
+    }
+}
+export function metaFromHeaders(headers) {
+    return {
+        requestId: headers.get(HEADER_REQUEST_ID),
+        cost: headers.get(HEADER_COST),
+        balance: headers.get(HEADER_BALANCE),
+    };
+}
+export class HttpCore {
+    baseUrl;
+    #apiKey;
+    #timeoutMs;
+    #fetchImpl;
+    #defaultHeaders;
+    #clock;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.#apiKey = opts.apiKey;
+        this.#timeoutMs = opts.timeoutMs;
+        this.#fetchImpl = opts.fetchImpl;
+        this.#defaultHeaders = opts.defaultHeaders;
+        this.#clock = opts.clock ?? REAL_CLOCK;
+    }
+    /**
+     * 非流式 JSON 请求(GET 走 429 重试纪律;2xx 断言对象体并回 meta)。
+     * 整个循环(每次 fetch + 体读取 + 重试等待)共用一个以调用起点计的总预算。
+     */
+    async requestJson(method, path, args, opts = {}) {
+        const url = this.baseUrl + path + buildQuery(args.query);
+        const hasBody = args.body !== undefined;
+        const init = {
+            method,
+            headers: this.#headers('application/json', hasBody),
+            ...(hasBody ? { body: JSON.stringify(args.body) } : {}),
+        };
+        const maxRetries = method === 'GET' ? MAX_GET_RETRIES : 0;
+        const deadline = new Deadline(opts.timeoutMs ?? this.#timeoutMs, this.#clock);
+        for (let attempt = 0;; attempt++) {
+            const timed = await this.#fetchWithTimeout(url, init, opts, deadline);
+            const { response } = timed;
+            if (response.status === 429 && attempt < maxRetries) {
+                const advertisedMs = retryAfterMsFromHeader(response, this.#clock) ??
+                    FALLBACK_BACKOFF_MS[Math.min(attempt, FALLBACK_BACKOFF_MS.length - 1)] ??
+                    1_000;
+                const waitMs = Math.min(advertisedMs, MAX_RETRY_AFTER_WAIT_MS);
+                if (waitMs < deadline.remainingMs()) {
+                    await response.body?.cancel().catch(() => undefined);
+                    timed.finish();
+                    await sleep(waitMs, opts.signal, this.#clock);
+                    continue;
+                }
+                // 剩余预算盖不住(钳制后的)等待:不再等待、不再重试,落到下方按 429 错误信封抛出
+                // (TansrApiError.retryAfterMs 携服务端原值,调用方可自行排程)。
+            }
+            try {
+                if (!response.ok)
+                    throw await this.#toApiError(response);
+                let text;
+                try {
+                    text = await response.text();
+                }
+                catch (err) {
+                    throw this.#mapBodyReadError(err, timed, opts);
+                }
+                let json;
+                try {
+                    json = JSON.parse(text);
+                }
+                catch (err) {
+                    throw new TansrConnectionError('gateway returned invalid JSON', { cause: err });
+                }
+                if (typeof json !== 'object' || json === null || Array.isArray(json)) {
+                    throw new TansrConnectionError('gateway returned a non-object JSON body');
+                }
+                return { json: json, meta: metaFromHeaders(response.headers) };
+            }
+            finally {
+                timed.finish();
+            }
+        }
+    }
+    /**
+     * 流式请求(POST,accept: text/event-stream):零重试(计费面,见头注)。
+     * 非 2xx 在此按错误信封抛出;2xx 交还句柄由 TansrStream 逐帧消费。
+     */
+    async openStream(path, body, opts = {}) {
+        const url = this.baseUrl + path;
+        const init = {
+            method: 'POST',
+            headers: this.#headers('text/event-stream', true),
+            body: JSON.stringify(body),
+        };
+        const deadline = new Deadline(opts.timeoutMs ?? this.#timeoutMs, this.#clock);
+        const timed = await this.#fetchWithTimeout(url, init, opts, deadline);
+        if (!timed.response.ok) {
+            try {
+                throw await this.#toApiError(timed.response);
+            }
+            finally {
+                timed.finish();
+            }
+        }
+        return {
+            response: timed.response,
+            meta: metaFromHeaders(timed.response.headers),
+            finish: timed.finish,
+            mapStreamError: (err) => this.#mapBodyReadError(err, timed, opts),
+        };
+    }
+    #headers(accept, hasBody) {
+        const headers = { ...this.#defaultHeaders, accept };
+        if (hasBody)
+            headers['content-type'] = 'application/json';
+        // authorization 恒由本核最后落笔:defaultHeaders 不可覆盖(防误配旁路鉴权)
+        headers.authorization = `Bearer ${this.#apiKey}`;
+        return headers;
+    }
+    /**
+     * 单次 fetch:用户 signal 与超时合流;失败即时归因(超时/用户取消/网络)。
+     * 超时计时器取 deadline 的**剩余**预算(重试时不重新起算),覆盖本次 fetch 及其后的体读取。
+     */
+    async #fetchWithTimeout(url, init, opts, deadline) {
+        const ctl = new AbortController();
+        let timedOut = false;
+        const timer = this.#clock.setTimeout(() => {
+            timedOut = true;
+            ctl.abort();
+        }, deadline.remainingMs());
+        const signal = opts.signal !== undefined ? AbortSignal.any([opts.signal, ctl.signal]) : ctl.signal;
+        try {
+            const response = await this.#fetchImpl(url, { ...init, signal });
+            return { response, finish: () => this.#clock.clearTimeout(timer), timedOut: () => timedOut, deadline };
+        }
+        catch (err) {
+            this.#clock.clearTimeout(timer);
+            if (timedOut)
+                throw new TansrConnectionError(`request timed out after ${deadline.totalMs}ms`);
+            if (opts.signal?.aborted === true)
+                throw err; // 用户取消:原样上抛
+            throw new TansrConnectionError('failed to reach the tansr gateway', { cause: err });
+        }
+    }
+    /** 响应体读取中断归因(非流式 text() 与流式逐帧共用)。 */
+    #mapBodyReadError(err, timed, opts) {
+        if (timed.timedOut()) {
+            return new TansrConnectionError(`request timed out after ${timed.deadline.totalMs}ms`);
+        }
+        if (opts.signal?.aborted === true)
+            return err; // 用户取消:原样上抛
+        return new TansrConnectionError('failed to read the gateway response', { cause: err });
+    }
+    /** 非 2xx → TansrApiError:tansr 信封优先,上游透传体尽力提取,双兜底。 */
+    async #toApiError(response) {
+        let text = '';
+        try {
+            text = await response.text();
+        }
+        catch {
+            // 错误体不可读:保底以状态码成错
+        }
+        const parsed = parseErrorBody(text);
+        const headerRetryMs = retryAfterMsFromHeader(response, this.#clock);
+        const detailRetrySec = parsed.detail?.retryAfterSec;
+        const detailRetryMs = typeof detailRetrySec === 'number' && Number.isFinite(detailRetrySec)
+            ? Math.max(0, Math.round(detailRetrySec * 1_000))
+            : null;
+        return new TansrApiError({
+            status: response.status,
+            code: parsed.code ?? `http_${response.status}`,
+            message: parsed.message ?? (text !== '' ? snippet(text) : `gateway responded with HTTP ${response.status}`),
+            requestId: parsed.requestId ?? response.headers.get(HEADER_REQUEST_ID),
+            detail: parsed.detail,
+            retryAfterMs: headerRetryMs ?? detailRetryMs,
+        });
+    }
+}
+/**
+ * 错误体解析:tansr 信封 { error: { code, message, requestId, detail } };
+ * 上游透传(OpenAI 形 error.type / Anthropic 形 { type:'error', error:{…} })
+ * 同径尽力提取;非 JSON 返回全 null 由调用侧兜底。
+ */
+function parseErrorBody(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed === 'object' && parsed !== null) {
+            const errField = parsed.error;
+            if (typeof errField === 'object' && errField !== null) {
+                const e = errField;
+                return {
+                    code: typeof e.code === 'string' ? e.code : typeof e.type === 'string' ? e.type : null,
+                    message: typeof e.message === 'string' ? e.message : null,
+                    requestId: typeof e.requestId === 'string' ? e.requestId : null,
+                    detail: isPlainObject(e.detail) ? e.detail : null,
+                };
+            }
+        }
+    }
+    catch {
+        // 非 JSON 错误体(上游透传任意文本)
+    }
+    return { code: null, message: null, requestId: null, detail: null };
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Retry-After 头 → 毫秒:秒数(整数;小数秒同 detail.retryAfterSec 一并接受)或 HTTP-date;
+ * 不可解析回 null。HTTP-date 三种形态(IMF-fixdate / RFC 850 / asctime)必含月名字母,
+ * 无字母的串不交给 Date.parse——V8 会把 "0.05" 之类数字串宽松解析成过去日期,等价于
+ * 把不合规头当成 0 等待。
+ */
+function retryAfterMsFromHeader(response, clock) {
+    const raw = response.headers.get(HEADER_RETRY_AFTER);
+    if (raw === null)
+        return null;
+    const trimmed = raw.trim();
+    if (/^\d+(\.\d+)?$/.test(trimmed))
+        return Math.round(Number(trimmed) * 1_000);
+    if (!/[A-Za-z]/.test(trimmed))
+        return null;
+    const dateMs = Date.parse(trimmed);
+    if (!Number.isNaN(dateMs))
+        return Math.max(0, dateMs - clock.now());
+    return null;
+}
+function snippet(text) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    return collapsed.length > 240 ? `${collapsed.slice(0, 237)}...` : collapsed;
+}
+function buildQuery(query) {
+    if (query === undefined)
+        return '';
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined && value !== '')
+            params.set(key, value);
+    }
+    const s = params.toString();
+    return s === '' ? '' : `?${s}`;
+}
+/** 重试等待:用户取消立即以 signal.reason 拒绝(与 fetch 的取消语义一致)。 */
+function sleep(ms, signal, clock) {
+    return new Promise((resolve, reject) => {
+        const reasonOf = (s) => s.reason ?? new DOMException('This operation was aborted', 'AbortError');
+        if (signal?.aborted === true) {
+            reject(reasonOf(signal));
+            return;
+        }
+        const onAbort = () => {
+            clock.clearTimeout(timer);
+            reject(reasonOf(signal));
+        };
+        const timer = clock.setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @tansr/api-client 公共出口。
+ *
+ * 运行时导出:Tansr(默认导出同名)、TansrApiError / TansrConnectionError、
+ * TansrStream(流返回值类型,亦可 instanceof)。其余为纯类型导出。
+ */
+export { Tansr, ChatCompletions, Messages, Responses, Models, Usage } from './client.js';
+export type { TansrOptions } from './client.js';
+export { TansrApiError, TansrConnectionError } from './errors.js';
+export type { TansrApiErrorArgs } from './errors.js';
+export { TansrStream } from './stream.js';
+export type { AnthropicMessage, AnthropicMessageParam, AnthropicUsage, ChatCompletion, ChatCompletionChoice, ChatCompletionChunk, ChatCompletionChunkChoice, ChatCompletionUsage, ChatCompletionsCreateParams, ChatMessageParam, MessageStreamEvent, MessagesCreateParams, ModelInfo, ModelsListResponse, RequestOptions, ResponseMeta, ResponseObject, ResponseStreamEvent, ResponsesCreateParams, UsageGetParams, UsageReport, UsageRow, WithMeta, } from './types.js';
+import { Tansr } from './client.js';
+export default Tansr;

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @tansr/api-client 公共出口。
+ *
+ * 运行时导出:Tansr(默认导出同名)、TansrApiError / TansrConnectionError、
+ * TansrStream(流返回值类型,亦可 instanceof)。其余为纯类型导出。
+ */
+export { Tansr, ChatCompletions, Messages, Responses, Models, Usage } from './client.js';
+export { TansrApiError, TansrConnectionError } from './errors.js';
+export { TansrStream } from './stream.js';
+import { Tansr } from './client.js';
+export default Tansr;

package/dist/sse.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SSE 解析器:字节流 → 事件 { event, data }(WHATWG EventSource 语义的最小
+ * 零依赖实现,只取本客户端需要的子集)。
+ *
+ * - 行语义:`data:` 行(同事件多行按规范以 '\n' 连接)、`event:` 行、`:` 注释
+ *   行忽略、空行分发;`id:`/`retry:` 忽略(薄客户端无重连语义);
+ * - 行终符 CRLF / LF / CR 均支持;跨 chunk 断行(含被切开的 \r\n)与多字节
+ *   UTF-8 断字由行缓冲 + TextDecoder(stream: true) 正确重组;
+ * - 行扫描线性:每次 feed 只单遍扫本次新到的文本(每个字符恰看一次),未凑满的残行
+ *   不参与再扫描——不随缓冲增长而重扫,`\r` 稀疏的大块不再退化为二次(RV-4-07);
+ * - 与规范的刻意偏差:flush() 在 EOF 时把未以空行收尾的残余事件尽力分发一次
+ *   (规范是丢弃)——上游异常截断时不吞掉最后一帧;残帧若非法 JSON 由消费侧
+ *   自然丢弃。无 data 行的事件(如裸 event: 行)不分发。
+ */
+export interface SseEvent {
+    /** `event:` 行给出的事件名;OpenAI chat 流无事件名,为 null。 */
+    readonly event: string | null;
+    /** `data:` 行内容(多行以 '\n' 连接)。 */
+    readonly data: string;
+}
+export declare class SseParser {
+    #private;
+    /** 喂入一个网络分帧,返回其中凑齐的完整事件(可能为 0..n 个)。 */
+    feed(chunk: Uint8Array): SseEvent[];
+    /** EOF 收尾:冲刷解码器与残行,分发未收尾的残余事件(见头注偏差说明)。 */
+    flush(): SseEvent[];
+}

package/dist/sse.js

@@ -0,0 +1,119 @@
+/**
+ * SSE 解析器:字节流 → 事件 { event, data }(WHATWG EventSource 语义的最小
+ * 零依赖实现,只取本客户端需要的子集)。
+ *
+ * - 行语义:`data:` 行(同事件多行按规范以 '\n' 连接)、`event:` 行、`:` 注释
+ *   行忽略、空行分发;`id:`/`retry:` 忽略(薄客户端无重连语义);
+ * - 行终符 CRLF / LF / CR 均支持;跨 chunk 断行(含被切开的 \r\n)与多字节
+ *   UTF-8 断字由行缓冲 + TextDecoder(stream: true) 正确重组;
+ * - 行扫描线性:每次 feed 只单遍扫本次新到的文本(每个字符恰看一次),未凑满的残行
+ *   不参与再扫描——不随缓冲增长而重扫,`\r` 稀疏的大块不再退化为二次(RV-4-07);
+ * - 与规范的刻意偏差:flush() 在 EOF 时把未以空行收尾的残余事件尽力分发一次
+ *   (规范是丢弃)——上游异常截断时不吞掉最后一帧;残帧若非法 JSON 由消费侧
+ *   自然丢弃。无 data 行的事件(如裸 event: 行)不分发。
+ */
+const LF = 0x0a;
+const CR = 0x0d;
+export class SseParser {
+    #decoder = new TextDecoder('utf-8');
+    /** 未凑满一行的残余文本(不含任何行终符;跨 chunk 断行重组缓冲,只在该行凑齐时拼接一次)。 */
+    #tail = '';
+    /** 上一 chunk 以 \r 收尾:该行已按 CR 行终分发;下一 chunk 若以 \n 开头,它是被切开的 \r\n 后半,吞掉。 */
+    #skipLf = false;
+    #eventName = null;
+    #dataLines = [];
+    /** 喂入一个网络分帧,返回其中凑齐的完整事件(可能为 0..n 个)。 */
+    feed(chunk) {
+        const events = [];
+        this.#consume(this.#decoder.decode(chunk, { stream: true }), events);
+        return events;
+    }
+    /** EOF 收尾:冲刷解码器与残行,分发未收尾的残余事件(见头注偏差说明)。 */
+    flush() {
+        const events = [];
+        this.#consume(this.#decoder.decode(), events);
+        this.#skipLf = false;
+        if (this.#tail !== '') {
+            const line = this.#tail;
+            this.#tail = '';
+            this.#line(line, events);
+        }
+        const pending = this.#dispatch();
+        if (pending !== null)
+            events.push(pending);
+        return events;
+    }
+    /**
+     * 单遍线性扫描本次新到的文本:遇 \n 或 \r 即成行(\r 后紧跟的 \n 属同一 CRLF,跳过);
+     * \r 落在文本末字节时按 CR 行终立即成行,并记下"下一 chunk 首字节若为 \n 须吞掉"。
+     * 残余 #tail 已知不含行终符,只在首行凑齐时与之拼接一次,不随缓冲增长而重扫。
+     */
+    #consume(text, events) {
+        const len = text.length;
+        let pos = 0;
+        if (this.#skipLf && len > 0) {
+            this.#skipLf = false;
+            if (text.charCodeAt(0) === LF)
+                pos = 1;
+        }
+        let i = pos;
+        while (i < len) {
+            const code = text.charCodeAt(i);
+            if (code !== LF && code !== CR) {
+                i += 1;
+                continue;
+            }
+            this.#line(this.#takeLine(text, pos, i), events);
+            if (code === CR) {
+                if (i + 1 < len) {
+                    if (text.charCodeAt(i + 1) === LF)
+                        i += 1;
+                }
+                else {
+                    this.#skipLf = true;
+                }
+            }
+            i += 1;
+            pos = i;
+        }
+        if (pos < len)
+            this.#tail += pos === 0 ? text : text.slice(pos);
+    }
+    /** 取出 [pos, end) 作为一行;若有残余 #tail,拼在行首并清空(仅首行会命中)。 */
+    #takeLine(text, pos, end) {
+        const piece = text.slice(pos, end);
+        if (this.#tail === '')
+            return piece;
+        const line = this.#tail + piece;
+        this.#tail = '';
+        return line;
+    }
+    #line(line, events) {
+        if (line === '') {
+            const ev = this.#dispatch();
+            if (ev !== null)
+                events.push(ev);
+            return;
+        }
+        if (line.startsWith(':'))
+            return; // 注释行(保活 ping 等)
+        const colon = line.indexOf(':');
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' '))
+            value = value.slice(1); // 规范:仅剥一个前导空格
+        if (field === 'data')
+            this.#dataLines.push(value);
+        else if (field === 'event')
+            this.#eventName = value;
+        // id / retry / 未知字段:忽略
+    }
+    #dispatch() {
+        const ev = this.#dataLines.length > 0
+            ? { event: this.#eventName, data: this.#dataLines.join('\n') }
+            : null;
+        this.#eventName = null;
+        this.#dataLines = [];
+        return ev;
+    }
+}

package/dist/stream.d.ts

@@ -0,0 +1,9 @@
+import type { StreamHandle } from './http.js';
+import type { ResponseMeta } from './types.js';
+export declare class TansrStream<T> implements AsyncIterable<T> {
+    #private;
+    constructor(open: () => Promise<StreamHandle>);
+    /** 逐请求元信息(消费响应头)。迭代开始前为 null;响应头到达后可读,迭代完成后必有。 */
+    get meta(): ResponseMeta | null;
+    [Symbol.asyncIterator](): AsyncGenerator<T, void, undefined>;
+}

package/dist/stream.js

@@ -0,0 +1,87 @@
+/**
+ * TansrStream:SSE 响应 → AsyncIterable<逐帧对象>。
+ *
+ * - 惰性起流:首次迭代才发请求(单次可迭代;HTTP 错误在首个 next() 以
+ *   TansrApiError 拒绝——402/429 等与非流式同径);
+ * - 终止语义:OpenAI 系 `data: [DONE]` 哨兵即止;Anthropic 无哨兵,流体自然
+ *   结束即止(message_stop 帧原样产出);
+ * - `event:` 行语义:data 缺 type 字段时以事件名补位(Anthropic/Responses
+ *   消费侧统一按 type 分派);非 JSON 的 data 帧静默跳过;
+ * - meta:响应头到达(首帧前)即可读,迭代完成后必有;流式无 x-tansr-cost
+ *   (成本流末才可知,实结见网关台账),cost 恒 null;
+ * - 取消:提前 break/throw 会取消上游读(网关按断链结算),用户 AbortSignal
+ *   的中止异常原样上抛。
+ */
+import { SseParser } from './sse.js';
+const DONE_SENTINEL = '[DONE]';
+/** 内部分派哨兵:终止 / 跳过本帧(与合法 JSON 值域零冲突)。 */
+const DONE = Symbol('tansr.sse.done');
+const SKIP = Symbol('tansr.sse.skip');
+export class TansrStream {
+    #meta = null;
+    #consumed = false;
+    #open;
+    constructor(open) {
+        this.#open = open;
+    }
+    /** 逐请求元信息(消费响应头)。迭代开始前为 null;响应头到达后可读,迭代完成后必有。 */
+    get meta() {
+        return this.#meta;
+    }
+    async *[Symbol.asyncIterator]() {
+        if (this.#consumed) {
+            throw new TypeError('TansrStream is single-use: it has already been iterated');
+        }
+        this.#consumed = true;
+        const handle = await this.#open();
+        this.#meta = handle.meta;
+        const body = handle.response.body;
+        if (body === null) {
+            handle.finish();
+            return;
+        }
+        const reader = body.getReader();
+        const parser = new SseParser();
+        try {
+            for (;;) {
+                let step;
+                try {
+                    step = await reader.read();
+                }
+                catch (err) {
+                    throw handle.mapStreamError(err);
+                }
+                const events = step.done ? parser.flush() : parser.feed(step.value);
+                for (const ev of events) {
+                    const chunk = toChunk(ev);
+                    if (chunk === DONE)
+                        return;
+                    if (chunk !== SKIP)
+                        yield chunk;
+                }
+                if (step.done)
+                    return;
+            }
+        }
+        finally {
+            handle.finish();
+            // 提前 break/throw:取消上游读(读毕时为幂等空操作,失败静默——连接已亡)
+            await reader.cancel().catch(() => undefined);
+        }
+    }
+}
+function toChunk(ev) {
+    if (ev.data.trim() === DONE_SENTINEL)
+        return DONE;
+    let parsed;
+    try {
+        parsed = JSON.parse(ev.data);
+    }
+    catch {
+        return SKIP; // 非 JSON data(保活/未知帧):静默跳过
+    }
+    if (typeof parsed === 'object' && parsed !== null && ev.event !== null && !('type' in parsed)) {
+        parsed.type = ev.event;
+    }
+    return parsed;
+}