@ coloop-ai/ recall- sdk

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

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

安装

npm install @coloop-ai/recall-sdk

快开始

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,
    },
  })
}

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

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 字段(当存在时),原始响应/请求对象,以及解析后的有效载荷,这样您就可以在不添加自己的类型守护器的情况下对故障快速进行重试:

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所述,页眉和安全重试请求 一能指南。 。 。 .

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

请求超时

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

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) (中文(简体) ).

生成客户端访问

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

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 类型:

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 详细情况.