flare-api-client-ts

Status: Deprecated / compatibility only.
This package is kept for existing frontend integrations, but new business API capabilities should not be added here. Future shared instance facade work is reserved for packages/flare-instance-api-py.

前端 API SDK。

架构边界文档

1. docs/SSOT-API-CLIENT-BOUNDARY.md（SSOT）
2. docs/CAPABILITY-INVENTORY.md
3. docs/GOV-12-FREEZE-CHECKLIST.md

职责只做两件事：

1. 封装 POST /auth/exchange
2. 封装 POST /chat/run 和 POST /chat/stream

不包含业务逻辑，不包含 UI，不包含领域判断。

Deprecated policy

1. 保留现有导出与兼容测试。
2. 不再新增 instance 业务能力、私有网关能力或 app 级资源治理能力。
3. 仅允许安全修复、兼容修复和现有 contract 的必要维护。
4. 新的 instance API 基座方向预留给 packages/flare-instance-api-py，但当前延迟实施。

chatRun / chatStreamSSE 支持 stream_protocol，取值为 v1、v2、v2_compat。

导出

1. authExchange
2. chatRun
3. chatStreamSSE
4. createApiClient
5. joinUrl
6. parseSseEvent
7. 共享类型：SessionRecordDTO、MessageRecordDTO、SourceRecordDTO、StreamEventDTO（见 src/common-types.d.ts）

最小用法

import { authExchange, chatRun, chatStreamSSE } from '@dva89/flare-api-client-ts';

const profile = await authExchange(
  {
    credential: 'demo-credential',
    external_user_id: 'user-001',
  },
  {
    baseUrl: 'http://127.0.0.1:18001',
  }
);

const runResult = await chatRun(
  {
    session_id: 'session-001',
    message: 'hello',
    intent: 'requirement_refinement',
  },
  {
    baseUrl: 'http://127.0.0.1:18001',
    token: profile.access_token,
  }
);

const stream = chatStreamSSE(
  {
    session_id: 'session-001',
    message: 'hello',
    intent: 'requirement_refinement',
    stream_protocol: 'v2_compat', // 可选：v2 / v2_compat / v1
  },
  {
    baseUrl: 'http://127.0.0.1:18001',
    token: profile.access_token,
    onEvent(event) {
      console.log(event.type, event.data);
    },
  }
);

await stream.done;

说明

1. chatStreamSSE 使用 fetch + ReadableStream，不依赖 EventSource。
2. 如果宿主需要中断流，调用返回值的 abort()。