@tansr/api-client 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,196 @@
+/**
+ * @tansr/api-client 类型面。
+ *
+ * 薄客户端选型:三协议(OpenAI chat / Anthropic messages / OpenAI responses)
+ * 的请求与响应只钉常用字段,其余经索引签名放行——网关对数据面是 passthrough
+ * (不做协议转换),完整字段语义以上游协议文档为准;钉死全量类型会把上游
+ * 演进变成本包的破坏性变更,与零依赖薄客户端的定位相悖。
+ */
+/** 逐请求元信息:消费 x-tansr-request-id / x-tansr-cost / x-tansr-balance 响应头。 */
+export interface ResponseMeta {
+    /** 网关请求标识(恒有;回执排障用)。 */
+    readonly requestId: string | null;
+    /** 实结成本(仅非流式;流式成本流末才可知,网关不回传此头,恒 null)。 */
+    readonly cost: string | null;
+    /** 台账余额(非流式为终审值;流式为预扣后快照)。 */
+    readonly balance: string | null;
+}
+/**
+ * 非流式返回值挂载 meta(不可枚举属性:JSON.stringify(响应) 不含 meta,
+ * 持久化原始响应体不被污染;注意展开运算 { ...res } 会丢弃它,先取后展开)。
+ */
+export type WithMeta<T> = T & {
+    readonly meta: ResponseMeta;
+};
+/** 逐请求选项:create/stream 均收。 */
+export interface RequestOptions {
+    /** 取消信号:中止请求与流式读取(原样上抛调用方的中止异常)。 */
+    readonly signal?: AbortSignal;
+    /** 覆盖构造器 timeoutMs(毫秒;一次调用的总预算,覆盖整个请求生命周期——含流式全程与 GET 429 重试等待)。 */
+    readonly timeoutMs?: number;
+}
+export interface ChatMessageParam {
+    /** 'system' | 'user' | 'assistant' | 'tool' 等。 */
+    role: string;
+    content: string | ReadonlyArray<Record<string, unknown>> | null;
+    [key: string]: unknown;
+}
+export interface ChatCompletionsCreateParams {
+    model: string;
+    messages: readonly ChatMessageParam[];
+    max_tokens?: number;
+    max_completion_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+    stop?: string | readonly string[];
+    tools?: ReadonlyArray<Record<string, unknown>>;
+    response_format?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface ChatCompletionUsage {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+    [key: string]: unknown;
+}
+export interface ChatCompletionChoice {
+    index?: number;
+    message?: {
+        role?: string;
+        content?: string | null;
+        [key: string]: unknown;
+    };
+    finish_reason?: string | null;
+    [key: string]: unknown;
+}
+export interface ChatCompletion {
+    id?: string;
+    object?: string;
+    created?: number;
+    model?: string;
+    choices?: ChatCompletionChoice[];
+    usage?: ChatCompletionUsage;
+    [key: string]: unknown;
+}
+export interface ChatCompletionChunkChoice {
+    index?: number;
+    delta?: {
+        role?: string;
+        content?: string | null;
+        [key: string]: unknown;
+    };
+    finish_reason?: string | null;
+    [key: string]: unknown;
+}
+/** 流式逐帧(SSE data 解析产物;终帧可携 usage——网关已向上游要求 include_usage)。 */
+export interface ChatCompletionChunk {
+    id?: string;
+    object?: string;
+    choices?: ChatCompletionChunkChoice[];
+    usage?: ChatCompletionUsage | null;
+    [key: string]: unknown;
+}
+export interface AnthropicMessageParam {
+    /** 'user' | 'assistant'。 */
+    role: string;
+    content: string | ReadonlyArray<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+export interface MessagesCreateParams {
+    model: string;
+    messages: readonly AnthropicMessageParam[];
+    /** Anthropic 协议必填。 */
+    max_tokens: number;
+    system?: string | ReadonlyArray<Record<string, unknown>>;
+    temperature?: number;
+    tools?: ReadonlyArray<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+export interface AnthropicUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+    [key: string]: unknown;
+}
+export interface AnthropicMessage {
+    id?: string;
+    type?: string;
+    role?: string;
+    model?: string;
+    content?: Array<Record<string, unknown>>;
+    stop_reason?: string | null;
+    stop_sequence?: string | null;
+    usage?: AnthropicUsage;
+    [key: string]: unknown;
+}
+/**
+ * 流式逐帧:message_start / content_block_delta / message_stop 等。`event:` 行
+ * 语义已归一到 type 字段(data 缺 type 时以事件名补位),消费侧统一按 type 分派。
+ */
+export interface MessageStreamEvent {
+    type: string;
+    [key: string]: unknown;
+}
+export interface ResponsesCreateParams {
+    model: string;
+    input?: string | ReadonlyArray<unknown>;
+    instructions?: string;
+    max_output_tokens?: number;
+    temperature?: number;
+    tools?: ReadonlyArray<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+export interface ResponseObject {
+    id?: string;
+    object?: string;
+    status?: string;
+    model?: string;
+    output?: Array<Record<string, unknown>>;
+    output_text?: string;
+    usage?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** 流式逐帧:response.created / response.output_text.delta / response.completed 等(按 type 分派)。 */
+export interface ResponseStreamEvent {
+    type: string;
+    [key: string]: unknown;
+}
+export interface ModelInfo {
+    /** 模型句柄(数据面 model 字段直接用它)。 */
+    id: string;
+    object?: string;
+    created?: number;
+    /** 'tansr'(平台)| 'org' | 'user'。 */
+    owned_by?: string;
+    [key: string]: unknown;
+}
+export interface ModelsListResponse {
+    object?: string;
+    data: ModelInfo[];
+    [key: string]: unknown;
+}
+export interface UsageGetParams {
+    /** 统计窗口,形如 '7d'(1..90 天;缺省 7d)。 */
+    readonly window?: string;
+    /** 聚合维度:day/model/source/key/session,至多 3 维;数组会按逗号拼接。缺省 day,source。 */
+    readonly groupBy?: string | readonly string[];
+}
+export interface UsageRow {
+    requests?: number;
+    inTokens?: number;
+    outTokens?: number;
+    cost?: string;
+    day?: string;
+    modelId?: string | null;
+    source?: string;
+    keyId?: string;
+    sessionId?: string;
+    [key: string]: unknown;
+}
+export interface UsageReport {
+    window?: string;
+    groupBy?: string[];
+    data: UsageRow[];
+    [key: string]: unknown;
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * @tansr/api-client 类型面。
+ *
+ * 薄客户端选型:三协议(OpenAI chat / Anthropic messages / OpenAI responses)
+ * 的请求与响应只钉常用字段,其余经索引签名放行——网关对数据面是 passthrough
+ * (不做协议转换),完整字段语义以上游协议文档为准;钉死全量类型会把上游
+ * 演进变成本包的破坏性变更,与零依赖薄客户端的定位相悖。
+ */
+export {};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@tansr/api-client",
+  "version": "0.2.0",
+  "description": "Thin zero-dependency TypeScript client for the Tansr gateway: OpenAI/Anthropic/Responses-shaped data plane, models catalog & usage, SSE streaming (public, MIT).",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.3"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "tansr",
+    "openai",
+    "anthropic",
+    "chat-completions",
+    "sse",
+    "api-client"
+  ],
+  "homepage": "https://tansr.com",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}