# @eka-care/ekascribe-ts-sdk 中文文档

规范地址：https://npmcn.com/package/%40eka-care/ekascribe-ts-sdk/

版本：3\.0\.58
npm 元数据更新时间：2026-10-22T10:45:46.723Z
中文译文更新时间：2026-11-16T05:43:38.628Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40eka-care/ekascribe-ts-sdk
原文对照：https://npmcn.com/package/%40eka-care/ekascribe-ts-sdk/?lang=original
项目主页：https://github.com/eka-care/eka-js-sdk#readme
源码仓库：https://github.com/eka-care/eka-js-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：341 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2025-08-14T09:41:23.984Z
- 最新版本发布：2026-10-22T10:45:46.311Z
- 近 30 天下载量：1956（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：326（近 12 个月 204 个）

## 中文简介

EkaScribe TypeSDK - 现代ES2020建设

## 安装

```sh
npm install @eka-care/ekascribe-ts-sdk
```

也可以使用：`pnpm add @eka-care/ekascribe-ts-sdk`、`yarn add @eka-care/ekascribe-ts-sdk`、`bun add @eka-care/ekascribe-ts-sdk`

## README

# EkaScribe 类型脚本 SDK

浏览器SDK用于使用Eka Care的语音转录API来捕捉音频并生成结构化的医疗文件.

## 先决条件

-   节点14+
-   `npm` 或者说 `yarn`
-   通过浏览器权限访问麦克风
-   稳定的网络连接
-   从Eka Care处获得信使

## 安装

```bash
npm install @eka-care/ekascribe-ts-sdk
# or
yarn add @eka-care/ekascribe-ts-sdk
```

## Bundler 设置

SDK使用共享工作器进行背景音频上传. 现代捆绑者自动处理这个.

### 维特

工作在盒子内.

```ts
import { getEkaScribeInstance } from '@eka-care/ekascribe-ts-sdk';
```

### 网页包 5

工作在盒子内。 这个 `new URL(..., import.meta.url)` 模式为本地支持.

```ts
import { getEkaScribeInstance } from '@eka-care/ekascribe-ts-sdk';
```

### 下一个.js

确保 SDK 只用于客户端 :

```tsx
'use client';

import { getEkaScribeInstance } from '@eka-care/ekascribe-ts-sdk';
```

### 浏览器( 脚本标签)

```html
<script type="module">
  import { getEkaScribeInstance } from 'https://cdn.jsdelivr.net/npm/@eka-care/ekascribe-ts-sdk/dist/index.mjs';
</script>
```

* * *

## 实例管理

SDK使用一个 **单子图案**。 。 。 . `getEkaScribeInstance()` 总是返回给定的同一实例 `env` + 键 `clientId` 组合.

```ts
const ekascribe = getEkaScribeInstance(config);
```

-   通话 `getEkaScribeInstance()` 多次使用相同的配置返回同一实例.
-   若为 `env` 或者说 `clientId` 更改,将自动重置旧实例.
-   如果只是这样的话 `access_token` 更改,在不重置的情况下将符号更新到已有实例上.
-   SDK 支持 **一次进行中的记录**。总是打电话 `endRecording()` 或者说 `cancelSession()` 在开始新的录音之前。 如果你打电话 `startRecordingV2()` 当录制活动时, SDK 在本地清理旧录制, 但确实 **没有** 结束服务器上的会话 —— 旧会话将被丢弃直到到期 .

* * *

## 融合指南

### 步骤1:初始化 SDK

```ts
import { getEkaScribeInstance } from '@eka-care/ekascribe-ts-sdk';
import type { EkaScribeConfig } from '@eka-care/ekascribe-ts-sdk';

const config: EkaScribeConfig = {
  access_token: '<your_access_token>',
  env: 'PROD',                             // 'PROD' | 'DEV'
  clientId: '<your_client_id>',            // optional
  allianceConfig: {
    baseUrl: 'https://api.eka.care/voice/v1',  // required
    useWorker: 'auto',                              // optional: true | false | 'auto'
    debug: false,                                   // optional
  },
  sharedWorkerUrl: workerUrl,              // optional — see SharedWorker section
};

const ekascribe = getEkaScribeInstance(config);
```

#### `EkaScribeConfig`

```ts
interface EkaScribeConfig {
  access_token?: string;          // Bearer token for authentication
  env: 'PROD' | 'DEV';           // Environment
  clientId?: string;              // Your client identifier
  mode?: 'http' | 'ipc';         // Transport mode (default: 'http')
  ipcBridge?: IpcBridge;          // Required when mode is 'ipc' (Electron apps)
  enableTracking?: boolean;       // Enable internal analytics tracking
  flavour?: string;               // Client flavour identifier
  sharedWorkerUrl?: string;       // URL to worker.bundle.js for background uploads
  allianceConfig?: {
    baseUrl?: string;             // Scribe service URL (required)
    useWorker?: boolean | 'auto'; // SharedWorker: true | false | 'auto' (default: 'auto')
    debug?: boolean;              // Enable debug logging (default: false)
  };
  widget?: WidgetConfig;          // Widget configuration — see Widget section
}
```

### 第2步:登记召回

注册回调 **在此之前** 开始录制。 事件一开始就起火.

```ts
import type { EkaCallbackMap } from '@eka-care/ekascribe-ts-sdk';

// Token refresh — SDK calls this automatically on 401
ekascribe.registerCallback('onTokenRequired', async () => {
  const newToken = await fetchFreshToken(); // your token refresh logic
  return newToken; // must return the new token string
});

// Recording state changes
ekascribe.registerCallback('onRecordingStateChange', (event) => {
  console.log('State:', event.type); // 'started' | 'paused' | 'resumed' | 'ended'
});

// Upload progress
ekascribe.registerCallback('onUploadEvent', (event) => {
  if (event.type === 'progress') {
    console.log(`Uploaded ${event.data.successCount}/${event.data.totalCount}`);
  }
});

// Errors
ekascribe.registerCallback('onError', (event) => {
  console.error(`[${event.error.code}] ${event.error.message}`);
});
```

见 [回调引用](https://npmcn.com/package/%40eka-care/ekascribe-ts-sdk/#readme-callbacks-reference) 所有召回类型和有效载荷.

### 第3步:开始录音

创建会话并在一个电话中启动麦克风 .

```ts
import type { RecordingOptions } from '@eka-care/ekascribe-ts-sdk';

const options: RecordingOptions = {
  templates: ['template-id'],             // required: template IDs for output
  sessionMode: 'consultation',            // optional: 'consultation' | 'dictation'
  languageHint: ['en', 'hi'],            // optional: input audio language hints
  transcriptLanguage: 'en',              // optional: output transcript language
  model: 'pro',                          // optional: 'pro' | 'lite'
  uploadType: 'chunked',                 // optional: 'chunked' (default) | 'single'
  deviceId: microphoneId,                // optional: specific microphone device ID
  patientDetails: {                      // optional
    name: 'John Doe',
    age: '45',
    gender: 'male',
  },
  additionalData: {},                    // optional: any extra data for the session
};

const result = await ekascribe.startRecordingV2(options);

if (result.error_code) {
  console.error(result.error_code, result.message);
  return;
}

const sessionId = result.txn_id;
console.log('Recording started:', sessionId);
```

#### `RecordingOptions`

```ts
interface RecordingOptions {
  templates: string[];                   // Template IDs for extraction (required)
  model?: string;                        // Model ID ('pro' | 'lite')
  languageHint?: string[];               // Language codes for audio input
  transcriptLanguage?: string;           // Language code for transcript output
  uploadType?: string;                   // 'chunked' | 'single' (default: 'chunked')
  communicationProtocol?: string;        // 'http' (default)
  additionalData?: Record<string, any>;  // Extra data for the session
  deviceId?: string;                     // Specific microphone device ID
  sessionMode?: string;                  // 'consultation' | 'dictation'
  patientDetails?: PatientDetails;       // Patient info
  sessionId?: string;                    // External session/transaction ID
}

interface PatientDetails {
  oid?: string;
  name?: string;
  age?: string;
  gender?: string;
  mobile?: number;
}
```

#### 回应: `TStartRecordingResponse`

```ts
type TStartRecordingResponse = {
  error_code?: ERROR_CODE;  // present only on error
  status_code: number;
  message: string;
  txn_id?: string;          // session ID — present on success
  business_id?: string;
  oid?: string;
  uuid?: string;
};
```

### 第4步:暂停/恢复

```ts
const pauseResult = ekascribe.pauseRecording();
// later...
const resumeResult = ekascribe.resumeRecording();
```

#### 回应: `TPauseRecordingResponse`

```ts
type TPauseRecordingResponse = {
  status_code: number;
  message: string;
  error_code?: ERROR_CODE;
  is_paused?: boolean;
};
```

### 第5步:结束记录

停止麦克风,冲出待发音频,等待所有上传,并在服务器上结束会话(触发处理).

```ts
const endResult = await ekascribe.endRecording();

if (endResult.error_code) {
  switch (endResult.error_code) {
    case 'audio_upload_failed':
      // Some audio files failed to upload — retry
      await ekascribe.retryUploadRecording();
      break;
    case 'end_recording_failed':
    case 'internal_server_error':
      console.error(endResult.error_code, endResult.message);
      break;
  }
}
```

#### 回应: `TEndRecordingResponse`

```ts
type TEndRecordingResponse = {
  error_code?: ERROR_CODE;
  status_code: number;
  message: string;
  failed_files?: string[];       // files that failed to upload
  total_audio_files?: string[];  // all audio files generated
};
```

### 步骤6:获取输出

使用 `getSessionStatus()` 在结束录制后进行结果调查.

```ts
const status = await ekascribe.getSessionStatus(sessionId, {
  poll: {
    maxAttempts: 60,
    intervalMs: 2000,
    signal: abortController.signal,   // optional: cancel polling early
    onProgress: (sessionData) => {
      console.log('Status:', sessionData.status);
      // Display partial results as they come in
      if (sessionData.templates) {
        console.log('Templates:', sessionData.templates);
      }
    },
  },
});

if (status.success) {
  console.log('Final status:', status.data.status);
  console.log('Templates:', status.data.templates);
  console.log('Transcript:', status.data.transcript);
}
```

#### 回应: `SDKResult<GetSessionStatusResponse>`

```ts
// All async Alliance methods return SDKResult — check result.success
type SDKResult<T> =
  | { success: true; data: T; httpStatus?: number }
  | { success: false; error: ScribeError };

type GetSessionStatusResponse = {
  session_id: string;
  status: SessionStatus;
  created_at: string;
  expires_at?: string | null;
  completed_at?: string | null;
  model_used?: string | null;
  language_detected?: string | null;
  audio_files_received: number;
  audio_files: string[];
  audio_files_processed?: number;
  additional_data: Record<string, any>;
  templates?: TemplateEntry[];
  transcript?: string;
  processing_errors?: ProcessingError[];
  error?: { code: string; message: string };
};
```

### 步骤7:清理

```ts
// Reset the singleton — clears all state, destroys widget, removes callbacks
await ekascribe.resetInstance();
```

打电话后 `resetInstance()`你必须打电话 `getEkaScribeInstance()` 再次获得一个新的实例.

### 流程图

```
  getEkaScribeInstance(config)
         |
         v
  registerCallback()  ──  Set up event handlers before recording
         |
         v
  startRecordingV2()  ──  Creates session + starts mic + begins upload
         |
    pause / resume    ──  Optional during recording
         |
         v
  endRecording()      ──  Stops mic + flushes audio + ends session
         |
         v
  getSessionStatus()  ──  Poll until completed/failed
         |
         v
  Read results        ──  templates, transcript, errors
```

* * *

## 回调引用

注册 `registerCallback(name, handler)`。删除方式 `removeCallback(name, handler)`。 。 。 .

### `onTokenRequired`

当SDK收到来自任何API呼叫的401时自动调用. 您的操作员必须返回一个新的访问标志。 SDK会更新其内部的代号并重试失败的请求.

```ts
ekascribe.registerCallback('onTokenRequired', async () => {
  // Call your auth service to get a fresh token
  const newToken = await myAuthService.refreshToken();
  return newToken; // return the token string
});
```

**重要内容:**

-   处理者必须返回 `Promise<string>` 或者说 `string`
-   10秒后SDK出局——如果你的刷新需要更长的时间,请求失败
-   信使一回,SDK就会打电话 `updateAuthTokens()` 内部,你不需要自己称呼它
-   这将取代手动检查的旧模式 `status_code: 401` 在每次答复中

#### 类型

```ts
// Consumer-facing type (EkaScribe SDK)
onTokenRequired: () => Promise<string> | string;
```

### `onRecordingStateChange`

记录状态过渡时被放出.

```ts
ekascribe.registerCallback('onRecordingStateChange', (event) => {
  console.log(event.type); // 'started' | 'paused' | 'resumed' | 'ended'
});
```

#### 类型

```ts
interface RecordingStateChangeEvent {
  type: 'started' | 'paused' | 'resumed' | 'ended';
  timestamp: string;
  data?: any;
}
```

### `onAudioEvent`

用于语音检测、沉默警告、块创建和帧处理.

```ts
ekascribe.registerCallback('onAudioEvent', (event) => {
  switch (event.type) {
    case 'user_speech':
      console.log('Speaking:', event.data.isSpeaking);
      break;
    case 'silence_warning':
      console.log('Silence duration:', event.data.durationMs, 'ms');
      break;
    case 'chunk_ready':
      console.log('Chunk:', event.data.fileName);
      break;
    case 'frame_processed':
      // Raw audio frame data
      break;
  }
});
```

#### 类型

```ts
type AudioEvent =
  | { type: 'user_speech'; timestamp: string; data: { isSpeaking: boolean } }
  | { type: 'silence_warning'; timestamp: string; data: { durationMs: number } }
  | { type: 'chunk_ready'; timestamp: string; data: { chunkIndex: number; fileName: string; chunkData: Uint8Array[] } }
  | { type: 'frame_processed'; timestamp: string; data: { isSpeech: number; notSpeech: number; frame: Float32Array; duration: number } };
```

### `onUploadEvent`

为上传进度、失败和重试而解雇.

```ts
ekascribe.registerCallback('onUploadEvent', (event) => {
  switch (event.type) {
    case 'progress':
      console.log(`${event.data.successCount}/${event.data.totalCount} uploaded`);
      break;
    case 'failed':
      console.error(`Upload failed: ${event.data.fileName}`, event.data.error);
      break;
    case 'retry':
      console.log(`Retrying ${event.data.fileName}, attempt ${event.data.attempt}`);
      break;
  }
});
```

#### 类型

```ts
type UploadEvent =
  | { type: 'progress'; timestamp: string; data: { successCount: number; totalCount: number } }
  | { type: 'failed'; timestamp: string; data: { fileName: string; error: string } }
  | { type: 'retry'; timestamp: string; data: { fileName: string; attempt: number } };
```

### `onSessionEvent`

在会话生命周期活动时被发射.

```ts
ekascribe.registerCallback('onSessionEvent', (event) => {
  switch (event.type) {
    case 'created':
      console.log('Session created:', event.data.session_id);
      break;
    case 'ended':
      console.log('Session ended:', event.data.session_id);
      break;
    case 'status_update':
      console.log('Status update:', event.data.status);
      break;
    case 'partial_result':
      console.log('Partial result:', event.data);
      break;
  }
});
```

#### 类型

```ts
type SessionEvent =
  | { type: 'created'; timestamp: string; data: CreateSessionResponse }
  | { type: 'ended'; timestamp: string; data: EndSessionResponse }
  | { type: 'status_update'; timestamp: string; data: GetSessionStatusResponse }
  | { type: 'partial_result'; timestamp: string; data: any };
```

### `onError`

SDK出错——VAD故障,工人出错,网络问题,验证出错.

```ts
ekascribe.registerCallback('onError', (event) => {
  console.error(`[${event.type}] ${event.error.code}: ${event.error.message}`);
});
```

#### 类型

```ts
interface ErrorEvent {
  type: 'vad_error' | 'worker_error' | 'transport_error' | 'validation_error';
  timestamp: string;
  error: {
    code: string;
    message: string;
    details?: any;
  };
}
```

### 删除回调

```ts
const handler = (event) => { /* ... */ };

ekascribe.registerCallback('onUploadEvent', handler);
// later...
ekascribe.removeCallback('onUploadEvent', handler);
```

### 重试上传失败

若为 `endRecording()` 返回时 `audio_upload_failed`,重试失败的上传:

```ts
const result = await ekascribe.retryUploadRecording();
```

#### 回应: `TEndRecordingResponse`

```ts
{
  status_code: number;
  message: string;
  error_code?: ERROR_CODE;
  failed_files?: string[];       // files still failing after retry
  total_audio_files?: string[];
}
```

### 取消会话

取消会话 **无** 启动服务器侧处理.

```ts
// Cancel current active session
await ekascribe.cancelSession();

// Or cancel a specific session by ID
await ekascribe.cancelSession('session-id');
```

#### 回应: `SDKResult<PatchSessionResponse>`

```ts
const result = await ekascribe.cancelSession();
if (result.success) {
  console.log('Session cancelled');
}
```

### 预录音频上传

上传一个预先录制的音频文件,而不是现场录制. 用于非实时流量 .

**流量 :**

1.  通过 `ekascribe.sessions.createSession()`
2.  通过上传音频 `processPreRecordedAudio()`
3.  结束会话通过 `ekascribe.sessions.endSession()`

```ts
const result = await ekascribe.processPreRecordedAudio({
  uploadUrl: session.upload_url,       // from createSession response
  audioFile: audioBlob,                // File or Blob
});
```

#### 请求

```ts
{
  uploadUrl: string;        // S3 upload URL from session
  audioFile: File | Blob;   // the audio file
}
```

#### 回应: `TStartRecordingResponse`

```ts
{
  status_code: number;
  message: string;
  error_code?: ERROR_CODE;
}
```

* * *

## 会话 Utils

### `getSessionHistory(request)`

获取以前的会话 .

```ts
const sessions = await ekascribe.sessions.getSessionHistory({
  txn_count: 10,        // number of sessions to fetch
  oid: 'patient-oid',        // optional: filter by patient oid
});
```

#### 回应: `TGetTransactionHistoryResponse`

```ts
{
  data: Array<{
    txn_id: string;
    b_id: string;
    created_at: string;
    mode: string;
    oid: string;
    patient_details?: TPatientDetails;
    processing_status: 'success' | 'system_failure' | 'request_failure' | 'cancelled' | 'in-progress';
    user_status: 'init' | 'commit';
    uuid: string;
  }>;
  status: string;
  code: number;
  message: string;
  retrieved_count: number;
}
```

### `getSessionDetails(request)`

获取特定会话的详细信息,包括文件、上下文和预先签名的URL.

```ts
const details = await ekascribe.sessions.getSessionDetails({
  session_id: 'session-id',
  presigned: true,         // include presigned URLs for documents
});
```

答复中的每一文件都载有: `presigned_url`。要获取实际文件内容(注释、记录等),请从此 URL 中获取:

```ts
const doc = details.data?.documents[0];
if (doc?.presigned_url) {
  const response = await fetch(doc.presigned_url);
  const content = await response.json();
}
```

> 指定 URL 是临时的 —— 检查 `presigned_url_expires_at` (时间戳)使用前。 打电话 `getDocument(documentId)` 以获取新预签名的 URL,如果过期.

#### 请求

```ts
type TGetV1SessionDetailsRequest = {
  session_id: string;
  presigned?: boolean;   // default: false
};
```

#### 回应: `TGetV1SessionDetailsResponse`

```ts
type TGetV1SessionDetailsResponse = {
  data?: {
    schema_version: string;
    session_id: string;
    uuid: string;
    wid: string;
    created_at: number;
    expires_at: number;
    upload_url: string;
    status: string;
    user_status: 'init' | 'recording_started' | 'commit' | string;
    transfer: string;
    flavour: string;
    patient_details: TPatientDetails | Record<string, unknown>;
    audio_matrix: Record<string, unknown>;
    additional_data: {
      input_languages?: { id: string; name: string }[];
      output_format_template?: {
        template_id: string;
        template_name?: string;
        template_type?: string;
      }[];
      [key: string]: unknown;
    };
    documents: Array<{
      document_id: string;
      session_id: string;
      template_id: string;
      document_name: string;
      document_type: 'notes' | 'context' | 'transcript' | 'integration';
      type: string;
      status: string;
      errors: Array<{ type: string | null; code: string; msg: string }>;
      warnings: Array<{ type: string | null; code: string; msg: string }>;
      publish: Record<string, unknown>;
      created_at: number;
      presigned_url: string | null;
      presigned_url_expires_at: number | null;
      vault_doc_id: string | null;
      lang?: string;
    }>;
    context: {
      past_sessions?: Array<{ date_epoch: number; session_id: string }>;
      documents?: string[];
      attachments?: Array<{ id: string; patient_oid?: string }>;
    };
  };
  status_code: number;
  message?: string;
};
```

### `getDocument(documentId)`

通过ID获取单一文档 。 如果前一个 URL 已过期, 请使用此选项获取新预签名的 URL .

```ts
const doc = await ekascribe.documents.getDocument('document-id');
if (doc.data?.presigned_url) {
  const response = await fetch(doc.data.presigned_url);
  const content = await response.json();
}
```

#### 回应: `TPostV1DocumentResponse`

```ts
type TPostV1DocumentResponse = {
  status_code: number;
  status?: string;
  message?: string;
  data?: {
    document_id: string;
    session_id: string;
    template_id: string;
    document_name: string;
    type: string;
    status: string;
    errors: unknown[];
    warnings: unknown[];
    usage_information: Record<string, unknown>;
    document_path: {
      bucket: string;
      folder: string;
      filename: string;
    };
    presigned_url: string;
    created_at: string;
    updated_at: number;
    publish: Record<string, unknown>;
  };
};
```

### `patchSessionStatus(request, sessionId?)`

更新会话属性(病人细节,状态,模板).

```ts
await ekascribe.sessions.patchSessionStatus({
  patient_details: { name: 'Jane Doe', age: '30', gender: 'female' },
  additional_data: { notes: 'Follow-up visit' },
  templates: ['soap', 'prescription'],
}, sessionId);
```

* * *

## 发现

### `getDiscoveryDocument()`

初始化时获取原始发现文件 。 包含服务器能力(所支持的模型,语言,上传方法,音频格式).

```ts
const discovery = ekascribe.sessions.getDiscoveryDocument();
```

回返 `DiscoveryDocument | null`。 。 。 .

### `getDiscoveryConfig()`

从发现文档中获取解析的配置 .

```ts
const config = ekascribe.sessions.getDiscoveryConfig();

if (config.success) {
  console.log('Resolved config:', config.data);
}
```

回返 `SDKResult<ResolvedConfig>`。 。 。 .

* * *

## 部件

SDK提供了可选的预建录音UI. 当启用时, SDK 通过 Shadow DOM 向您的页面注入了浮动部件—— 您写入零 UI 代码 .

### 一体化

**步骤1:** 启用 SDK 配置中带有会话默认和回调的部件 :

```ts
const ekascribe = getEkaScribeInstance({
  access_token: token,
  env: 'PROD',
  allianceConfig: { baseUrl: '...' },
  widget: {
    enabled: true,
    orientation: 'horizontal',          // 'horizontal' | 'vertical'
    zIndex: 9999,                       // optional
    position: { bottom: 20, right: 20 }, // optional
    sessionDefaults: {
      input_language: ['en'],
      output_format_template: [{ template_id: 'soap' }],
      model_type: 'pro',
      mode: 'consultation',
    },
    callbacks: {
      onRecordingStart: ({ txn_id }) => {},
      onRecordingStop: ({ txn_id, duration }) => {},
      onProcessingComplete: ({ txn_id, sessionData }) => {
        // sessionData contains templates, transcript, etc.
      },
      onError: ({ error_code, message }) => {},
    },
  },
});
```

**步骤2:** 打电话 `startForPatient()` 对于每个病人——部件出现,用户直接与之互动(暂停、恢复、停止)。 你通过回调得到结果.

```ts
await ekascribe.startForPatient({
  txn_id: 'unique-session-id',
  patient_details: {                  // optional
    username: 'John Doe',
    age: 45,
    biologicalSex: 'M',
  },
  additional_data: {},                // optional
});
```

就是这样。 部件处理 `startRecordingV2()`, (中文(简体) ), `pauseRecording()`, (中文(简体) ), `resumeRecording()`, (中文(简体) ), `endRecording()`,以及 `getSessionStatus()` 内部.

### 行为

-   **可拖动** ——部件可以在屏幕上的任何位置重新定位.
-   **一次录一回** 电话 `startForPatient()` 当录制活动返回错误时。 如果部件处于DODE或错误状态,则自动重置并启动新会话.
-   **状态** ——处理后,部件会扩展以显示笔录并制作出平分笔记. 如果两者都可用,则以单独的分页显示.

### 部件状态流程

```
COLLAPSED ──> RECORDING ──> PAUSED ──> RECORDING ──> PROCESSING ──> DONE
     ^             │                                       │           │
     │             └──── (user clicks stop) ───────────────┘           │
     │                                                                 │
     └──────────── (user clicks close) ────────────────────────────────┘
                                                   │
                                               ERROR
```

### 类型

```ts
interface WidgetConfig {
  enabled: boolean;
  theme?: 'light' | 'dark';
  zIndex?: number;
  primaryColor?: string;
  position?: { bottom?: number; right?: number; top?: number; left?: number };
  orientation?: 'horizontal' | 'vertical';
  callbacks?: WidgetCallbacks;
  sessionDefaults: {
    input_language: string[];
    output_format_template: { template_id: string; template_name?: string; template_type?: string }[];
    model_type: string;
    mode: string;
  };
}

interface StartForPatientConfig {
  txn_id: string;
  patient_details?: {
    username?: string;
    age?: number;
    biologicalSex?: string;
    mobile?: string;
  };
  additional_data?: Record<string, unknown>;
}

interface WidgetCallbacks {
  onRecordingStart?: (data: { txn_id: string }) => void;
  onRecordingPause?: (data: { txn_id: string; duration: number }) => void;
  onRecordingResume?: (data: { txn_id: string }) => void;
  onRecordingStop?: (data: { txn_id: string; duration: number }) => void;
  onProcessingStart?: (data: { txn_id: string }) => void;
  onProcessingComplete?: (data: { txn_id: string; sessionData: unknown }) => void;
  onError?: (data: { error_code: string; message: string }) => void;
  onWidgetClose?: (data: { txn_id: string }) => void;
}
```

* * *

## 认证

### `updateAuthTokens(token)`

手动更新访问符 。 这向所有内部运输者和工人宣传该标志.

```ts
ekascribe.updateAuthTokens({ access_token: 'new-token' });
```

> 如果你有的话 `onTokenRequired` sDK自动处理401s。 你们只需要 `updateAuthTokens()` 用于主动代号旋转(如到期前).

* * *

## 共享工人配置

SDK会卸载音频压缩并上传到一个共享工作人,以便更好的主线程性能. 如果共享工人不可用或失败,SDK静默地回落到主线程处理.

### 设置

```ts
import { createWorkerBlobUrl } from '@eka-care/ekascribe-ts-sdk';

// Option 1: Use the built-in helper (recommended)
const workerUrl = await createWorkerBlobUrl();

// Option 2: Fetch from CDN
async function getWorkerUrl() {
  const res = await fetch(
    'https://cdn.jsdelivr.net/npm/@eka-care/ekascribe-ts-sdk@latest/dist/worker.bundle.js'
  );
  const script = await res.text();
  const blob = new Blob([script], { type: 'application/javascript' });
  return URL.createObjectURL(blob);
}
const workerUrl = await getWorkerUrl();

// Option 3: Copy to public directory
// cp node_modules/@eka-care/ekascribe-ts-sdk/dist/worker.bundle.js public/
const workerUrl = '/worker.bundle.js';
```

通过配置的 URL :

```ts
const ekascribe = getEkaScribeInstance({
  // ...
  sharedWorkerUrl: workerUrl,
});
```

**注释:**

-   工人的URL必须来自同一来源,或有适当的CORS头
-   完成时记得取消 blob URL : `URL.revokeObjectURL(workerUrl)`
-   若为 `sharedWorkerUrl` 未提供, SDK 使用主线程( 没有共享工人)

* * *

## 错误代码

| 错误代码 | 说明 |
| --- | --- |
| `microphone` | 麦克风访问出错(拒绝或无法访问) |
| `txn_init_failed` | 初始化会话失败 |
| `txn_limit_exceeded` | 最多同时举行的会议超过 |
| `internal_server_error` | 服务器侧出错 |
| `end_recording_failed` | 结束记录失败 |
| `audio_upload_failed` | 音频文件上传到服务器失败 |
| `txn_commit_failed` | 提交调用失败 |
| `txn_status_mismatch` | 当前会话状态的操作无效 |
| `network_error` | 网络连接问题 |
| `unknown_error` | 未分类错误 |
| `unauthorized` | 认证失败( 无效或过期的令牌) |
| `forbidden` | 权限不足 |

* * *

## 折旧方法

这些方法取自更古老的SDK版本. 他们仍然在工作,但没有被推荐进行新的融合.

| 折旧方法 | 替换使用 |
| --- | --- |
| `initTransaction()` + 键 `startRecording()` | `startRecordingV2()` |
| `getTemplateOutput()` | `getSessionStatus()` 有民调 |
| `getOutputTranscription()` | `getSessionStatus()` 有民调 |
| `commitTransactionCall()` | 自动处理 `endRecording()` |
| `stopTransactionCall()` | 自动处理 `endRecording()` |

### `initTransaction(request)`

在服务器上创建会话 。 之后必须 `startRecording()`。 。 。 .

```ts
const result = await ekascribe.initTransaction({
  mode: 'consultation',
  input_language: ['en-IN'],
  output_format_template: [{ template_id: 'template-id' }],
  txn_id: 'unique-id',
  transfer: 'chunked',
  model_type: 'pro',
  patient_details: {                // optional
    username: 'John Doe',
    age: 45,
    biologicalSex: 'M',
  },
});
// result: { status_code, message, txn_id?, error_code? }
```

### `startRecording(microphoneID?)`

开始录制已初始化的会话 .

```ts
const result = await ekascribe.startRecording();
// result: { status_code, message, txn_id?, error_code? }
```

### `getTemplateOutput(request)`

为会话获取已处理的模板输出 .

```ts
const result = await ekascribe.getTemplateOutput({ txn_id: 'session-id' });
// result: { status_code, message?, response? }
```

### `getOutputTranscription(request)`

获取会话的复制输出 .

```ts
const result = await ekascribe.getOutputTranscription({ txn_id: 'session-id' });
// result: { status_code, message?, response? }
```

### `commitTransactionCall()`

在服务器上提交当前交易 .

```ts
const result = await ekascribe.commitTransactionCall();
// result: { status_code, message, error_code?, failed_files? }
```

### `stopTransactionCall()`

停止服务器上的当前交易.

```ts
const result = await ekascribe.stopTransactionCall();
// result: { status_code, message, error_code? }
```

* * *

## 完整示例

```ts
import {
  getEkaScribeInstance,
  type EkaScribeConfig,
  type RecordingOptions,
} from '@eka-care/ekascribe-ts-sdk';

// 1. Initialize
const config: EkaScribeConfig = {
  access_token: token,
  env: 'PROD',
  allianceConfig: {
    baseUrl: 'https://api.eka.care/voice/v1',
  },
};

const ekascribe = getEkaScribeInstance(config);

// 2. Register callbacks
ekascribe.registerCallback('onTokenRequired', async () => {
  return await refreshToken();
});

ekascribe.registerCallback('onUploadEvent', (event) => {
  if (event.type === 'progress') {
    updateProgressUI(event.data.successCount, event.data.totalCount);
  }
});

ekascribe.registerCallback('onError', (event) => {
  showErrorToast(event.error.message);
});

// 3. Start recording
const startResult = await ekascribe.startRecordingV2({
  templates: ['soap'],
  sessionMode: 'consultation',
  languageHint: ['en'],
  patientDetails: { name: 'John Doe', age: '45', gender: 'male' },
});

if (startResult.error_code) {
  showError(startResult.message);
  return;
}

const sessionId = startResult.txn_id!;

// 4. User interacts...
// pauseBtn.onclick = () => ekascribe.pauseRecording();
// resumeBtn.onclick = () => ekascribe.resumeRecording();

// 5. End recording
const endResult = await ekascribe.endRecording();

if (endResult.error_code === 'audio_upload_failed') {
  await ekascribe.retryUploadRecording();
}

// 6. Get results
const status = await ekascribe.getSessionStatus(sessionId, {
  poll: {
    maxAttempts: 60,
    intervalMs: 2000,
    onProgress: (s) => updateStatusUI(s.status),
  },
});

if (status.success) {
  displayResults(status.data.templates, status.data.transcript);
}

// 7. Cleanup on unmount
await ekascribe.resetInstance();
```

* * *

## 贡献准则

这是一个不断更新的开源项目. 欢迎捐款!

参考 [EkaScribe TS SDK 软件](https://github.com/eka-care/eka-js-sdk) 用于SDK执行.

## 常见问题

### @eka-care/ekascribe-ts-sdk 是什么？

EkaScribe TypeSDK - 现代ES2020建设

### 如何安装 @eka-care/ekascribe-ts-sdk？

在项目目录运行 npm install @eka-care/ekascribe-ts-sdk，或使用 pnpm add / yarn add / bun add。

### @eka-care/ekascribe-ts-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @eka-care/ekascribe-ts-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @eka-care/ekascribe-ts-sdk 可以商用吗？

@eka-care/ekascribe-ts-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @eka-care/ekascribe-ts-sdk 的下载量有多少？

根据 npm 官方下载统计，@eka-care/ekascribe-ts-sdk 在 2026/10/13 – 2026/11/11 这 30 天内被下载 1,956 次，日均约 65 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @eka-care/ekascribe-ts-sdk 还在维护吗？

最新版本 3\.0\.58 发布于 2026/10/22（24 天前）；至今共发布 326 个版本，其中过去 12 个月发布了 204 个；首次发布于 2025/08/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

