# @coloop-ai/recall-sdk 中文文档

规范地址：https://npmcn.com/package/%40coloop-ai/recall-sdk/

版本：0\.9\.1
npm 元数据更新时间：2026-09-07T09:25:25.835Z
中文译文更新时间：2026-11-10T11:15:29.100Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40coloop-ai/recall-sdk
原文对照：https://npmcn.com/package/%40coloop-ai/recall-sdk/?lang=original
项目主页：https://github.com/Genei-Ltd/recall-sdk#readme
源码仓库：https://github.com/Genei-Ltd/recall-sdk

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

- 包体积（解压后）：1.8 MB，18 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2025-10-16T18:19:38.671Z
- 最新版本发布：2026-09-07T09:25:25.659Z
- 近 30 天下载量：23284（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 2 个）

## 中文简介

用于Recall.ai会合bot API的Type-safe SDK,由提供商的端点引用生成.

## 安装

```sh
npm install @coloop-ai/recall-sdk
```

也可以使用：`pnpm add @coloop-ai/recall-sdk`、`yarn add @coloop-ai/recall-sdk`、`bun add @coloop-ai/recall-sdk`

## README

# @ coloop-ai/ recall- sdk

[![npm version](https://img.shields.io/npm/v/@coloop-ai/recall-sdk.svg)](https://www.npmjs.com/package/@coloop-ai/recall-sdk) [![npm downloads](https://img.shields.io/npm/dm/@coloop-ai/recall-sdk.svg)](https://www.npmjs.com/package/@coloop-ai/recall-sdk) [![npm bundle size](https://img.shields.io/bundlephobia/min/@coloop-ai/recall-sdk)](https://bundlephobia.com/package/@coloop-ai/recall-sdk) [![License: MIT](https://img.shields.io/npm/l/@coloop-ai/recall-sdk.svg)](https://github.com/Genei-Ltd/recall-sdk/blob/main/LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue?logo=typescript)](https://www.typescriptlang.org/) [![GitHub stars](https://img.shields.io/github/stars/Genei-Ltd/recall-sdk?style=social)](https://github.com/Genei-Ltd/recall-sdk)

安全型客户端装订 Recall.ai meeting bot API. 操作由提供商的OpenAPI碎片所产生并被包在一个ergoomic SDK上.

> ⚠️ 这个项目由Coloop维护,不附属于Recall.ai或得到其认可——在使用前审查其API条款.

## 安装

```bash
npm install @coloop-ai/recall-sdk
```

## 快开始

```ts
import { RecallSdk } from '@coloop-ai/recall-sdk'

const recall = new RecallSdk({
  apiKey: process.env.RECALL_API_KEY!,
  timeoutMs: 10_000, // abort requests that hang for 10s
  // baseUrl: 'https://eu-central-1.recall.ai', // optionally target a different region
})

const bot = await recall.bot.create({
  meeting_url: 'https://zoom.us/j/123456789',
  bot_name: 'Demo bot',
})

const bots = await recall.bot.list({
  status: ['ready', 'joining_call'],
})
console.log(bots.results?.map((entry) => entry.id))

await recall.bot.update(bot.id, {
  metadata: { source: 'docs-example' },
})

const now = new Date().toISOString()

const events = await recall.calendar.listEvents({
  start_time__gte: now,
})

if (events.next) {
  const moreEvents = await recall.calendar.listEvents({
    start_time__gte: now,
    cursor: events.next,
  })
}

const nextEvent = events.results?.[0]
if (nextEvent) {
  await recall.calendar.scheduleBot(nextEvent.id, {
    deduplication_key: nextEvent.id,
    bot_config: {
      join_offset: 60,
    },
  })
}
```

一旦一个录音完成处理,你就可以镜像仪表盘中重现的表面:

```ts
const recording = await recall.recording.retrieve(bot.recording_id!)

if (recording.shortcuts?.video_mixed?.id) {
  const video = await recall.video.mixed.retrieve(
    recording.shortcuts.video_mixed.id,
  )
  console.log('Download mixed video from', video.data.download_url)
}

const audioSeparate = await recall.audio.separate.list({
  recording_id: recording.id,
})
const firstParticipantTrack = audioSeparate.results?.[0]
if (firstParticipantTrack) {
  await recall.audio.separate.update(firstParticipantTrack.id, {
    metadata: { exported_by: 'sample-app' },
  })
}
```

这个 `RecallSdk` 自动添加 `Token` aPI 密钥的前缀 `RecallSdkError` 对于未成功的答复,并返回每次呼叫的已打出的反应有效载荷,可选择中止挂载请求(并提出 `RecallSdkTimeoutError`当 `timeoutMs` 已配置.

## 处理错误

每个帮手都升起 `RecallSdkError` 当提醒 API 以非-2xx 状态响应时。 错误暴露出 HTTP 状态代码, recall- special `code` 编号 : `detail` 字段(当存在时),原始响应/请求对象,以及解析后的有效载荷,这样您就可以在不添加自己的类型守护器的情况下对故障快速进行重试:

```ts
import { RecallSdk, isRecallSdkError } from '@coloop-ai/recall-sdk'

try {
  await recall.bot.create({
    meeting_url: 'https://zoom.us/j/123456789',
    bot_name: 'Demo bot',
  })
} catch (error) {
  if (!isRecallSdkError(error)) throw error

  if (error.status === 429) {
    // Surface rate limit metadata to tracing/logging before retrying.
    console.warn('Recall throttled request', error.payload)
    return
  }

  if (error.status === 400) {
    // Permanent failure — inspect error.detail/code for specifics.
    throw new Error(
      `Failed to create bot (${error.code ?? 'unknown'}): ${
        error.detail ?? error.message
      }`,
    )
  }
}
```

## 同上有权力的请求

问题的方法 `POST`, (中文(简体) ), `PUT`,或 `PATCH` 呼叫接受可选 `IdempotentRequestOptions` 参数。 提供 `idempotencyKey` 发送 `Idempotency-Key` 如Recall's所述,页眉和安全重试请求 [一能指南](https://docs.recall.ai/reference/idempotency)。 。 。 .

```ts
await recall.bot.create(
  {
    meeting_url: 'https://zoom.us/j/123456789',
    bot_name: 'Demo bot',
  },
  { idempotencyKey: 'my-idempotency-key' },
)
```

## 请求超时

设定 `timeoutMs` 当 SDK 自动中止超过所配置的持续时间的请求时。 SDK拒绝 `RecallSdkTimeoutError`,可以将其作为可重试失败处理:

```ts
import { RecallSdk, RecallSdkTimeoutError } from '@coloop-ai/recall-sdk'

const recall = new RecallSdk({
  apiKey: process.env.RECALL_API_KEY!,
  timeoutMs: 5_000,
})

try {
  await recall.bot.list()
} catch (error) {
  if (error instanceof RecallSdkTimeoutError) {
    console.warn('Recall request timed out, retrying shortly')
    // retry or surface to your queue
  }
}
```

## 高级别方法

`RecallSdk` 将最常见的Recall.ai工作流程和分组操作映射为模块:

-   `recall.bot` - 管理会议项目(`list`, (中文(简体) ), `create`, (中文(简体) ), `retrieve`, (中文(简体) ), `update`, (中文(简体) ), `delete`, (中文(简体) ), `deleteMedia`, (中文(简体) ), `leaveCall`) (中文(简体) ).
-   `recall.calendar` - 有方法的便利入口:
    -   日历事件 : `listEvents`, (中文(简体) ), `retrieveEvent`, (中文(简体) ), `scheduleBot`, (中文(简体) ), `unscheduleBot`。 。 。 .
    -   日历账户 : `listCalendars`, (中文(简体) ), `createCalendar`, (中文(简体) ), `retrieveCalendar`, (中文(简体) ), `updateCalendar`, (中文(简体) ), `deleteCalendar`, (中文(简体) ), `createCalendarAccessToken`。 。 。 .
    -   嵌入式模块`recall.calendar.events` 财务报告和审定财务报表 `recall.calendar.accounts`)如果更喜欢一个明确的命名空间,则会暴露同样的方法.
-   `recall.recording` - 制作会议记录`list`, (中文(简体) ), `retrieve`, (中文(简体) ), `delete`, (中文(简体) ), `createTranscript`) (中文(简体) ).
-   `recall.transcript` - 检查文物记录(`list`, (中文(简体) ), `retrieve`, (中文(简体) ), `delete`, (中文(简体) ), `update`) (中文(简体) ).
-   `recall.audio` - 管理音频文物。 方便帮助者(`listMixed`, (中文(简体) ), `retrieveMixed`, (中文(简体) ), `updateMixed`, (中文(简体) ), `deleteMixed`, (中文(简体) ), `listSeparate`, (中文(简体) ), `retrieveSeparate`, (中文(简体) ), `updateSeparate`, (中文(简体) ), `deleteSeparate`授权使用嵌入式模块(`recall.audio.mixed`, (中文(简体) ), `recall.audio.separate`) (中文(简体) ).
-   `recall.video` –通过用于音频的同一种帮助模式管理视频文物.

每种方法都采用轻量级识别器(`botId`, (中文(简体) ), `eventId`, (中文(简体) ), `calendarId`等),带有可选请求机构或查询对象,与生成的类型类型相匹配.

插图帮助器(机器人、日历、日历事件、录音、录音、录音、录音/录像制品)用原始光标符号自动替换复召提供的页标 URL,以便您通过 `response.next` 或者说 `response.previous` 直接通过 `cursor` 查询参数而无需手动解析 . `bot.list` 取而代之的是页码 `next`编号 :`previous` 为该 `page` 查询段落(参见 `BotListPage`) (中文(简体) ).

## 生成客户端访问

如果您需要完全控制请求选项(海关头、替代响应样式、重试),您可以直接与生成的客户端合作:

```ts
import { GeneratedRecallSdk, sdk } from '@coloop-ai/recall-sdk'

const client = sdk.createClient({
  baseUrl: 'https://us-east-1.recall.ai',
  auth: () => `Token ${process.env.RECALL_API_KEY}`,
  responseStyle: 'body',
})

const raw = new GeneratedRecallSdk({ client })
const response = await raw.botList({ query: { status: ['ready'] } })
```

所有请求/答复类型均导出自 `@coloop-ai/recall-sdk`,而webhook 计划生活在 `@coloop-ai/recall-sdk/webhooks`,因此即使在使用低等平面时也可以静态地输入集成.

## 网络呼号

Recall's webhook的有效载荷(机器人生命周期,Calendar v2通知,桌面上传生命周期等)不包含在公开的OpenAPI定义中,因此他们的计划是手工制作的在这个SDK中. 这个 `@coloop-ai/recall-sdk/webhooks` 由 Zod 供电的入口输出运行时间验证器和类型Script 类型:

```ts
import {
  WebhookEvent,
  BotStatusCode,
  CallEndedSubCode,
} from '@coloop-ai/recall-sdk/webhooks'

export function handleWebhook(payload: unknown) {
  const parsed = WebhookEvent.safeParse(payload)
  if (!parsed.success) {
    console.warn('Unhandled webhook payload', parsed.error)
    return
  }

  const event = parsed.data
  switch (event.event) {
    case 'bot.status_change': {
      const { code, sub_code } = event.data.status
      if (code === BotStatusCode.enum.call_ended && sub_code) {
        const reason = CallEndedSubCode.safeParse(sub_code)
        if (reason.success) {
          console.log('Call ended with reason', reason.data)
        }
      }
      break
    }
    case 'calendar.sync_events': {
      const { calendar_id, last_updated_ts } = event.data
      console.log('Sync calendar', calendar_id, 'since', last_updated_ts)
      break
    }
  }
}
```

`WebhookEvent` 双倍的受歧视工会类型(`import type { WebhookEvent }`工会验证人(`WebhookEvent.safeParse`) (中文(简体) ). 支持诸如 `BotStatusCode`, (中文(简体) ), `CallEndedSubCode`, (中文(简体) ), `FatalSubCode`, (中文(简体) ), `ZoomRecordingPermissionDeniedSubCode`,而其他人则保持您的匹配逻辑与Recall的表面一致,而基础的有效载荷域仍然接受未来的字符串值,因此整合在Recall ships 时会不断编译出新的代码.

## 脚本

-   `npm run generate` - 获取合并的规格并重生 `src/generated/**`。 。 。 .
-   `npm run tc` - 在不排放文件的情况下检查项目类型.
-   `npm run lint` – ESLint横跨仓库.
-   `npm run test` – Vitest套房(如果有意义的行为改变,增加覆盖).
-   `npm run build` - 编译为两套无害环境管理/CJS捆绑 `dist/` 使用 tsdown (运行) `npm run generate` (第一编).

## 许可证

根据麻省理工学院的许可获释. 见 `LICENSE` 详细情况.

## 常见问题

### @coloop-ai/recall-sdk 是什么？

用于Recall\.ai会合bot API的Type-safe SDK,由提供商的端点引用生成\.

### 如何安装 @coloop-ai/recall-sdk？

在项目目录运行 npm install @coloop-ai/recall-sdk，或使用 pnpm add / yarn add / bun add。

### @coloop-ai/recall-sdk 支持 TypeScript 吗？

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

### @coloop-ai/recall-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @coloop-ai/recall-sdk 可以商用吗？

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

### @coloop-ai/recall-sdk 的下载量有多少？

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

### @coloop-ai/recall-sdk 还在维护吗？

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