用途:指导在 Node.js 项目中采用官方 beta 版 Instantly TypeScript SDK(@instantlyai/sdk),避免自行臆造资源方法或掩盖 HTTP 失败语义,并让操作可复现、可审查。
主要能力与契约:官方包为 @instantlyai/sdk,在稳定 1.0.0 之前仍为 beta;要求 Node.js 22 或更高版本;对非成功响应抛出 ResponseError;资源覆盖由 OpenAPI schema 生成,beta 期间可能变化。
认证:使用 API v2 密钥,以 Authorization: Bearer <key> 访问 https://api.instantly.ai/api/v2。仅授予端点所需的最小 scope,密钥从服务端密钥管理器注入,不得打印、持久化、提交或放入 URL。密钥创建、轮换、撤销、成员变更、跨工作区委派与生产访问均需负责人批准。
使用方式:安装前检查运行时与 lockfile 兼容性;确认当前 beta 版本并固定解析后的 lockfile;在服务端用 apiKey 创建 Instantly 实例,不暴露到浏览器;只使用已安装版本中存在的生成资源方法与请求类型;按状态处理 ResponseError,并对响应体与授权信息做脱敏;为每次 beta 变更添加契约测试与升级评审。
错误处理:401 停止并核实 bearer 密钥存在、有效且未被撤销;403 停止并对照该操作的确切必需 scope,不要默认放宽为 all:all;429 协调工作区整体预算、遵守端点覆盖并限制重试;schema 或租户不匹配时失败关闭,保留脱敏证据,不重试变更操作。
限制与审批边界:未经负责人明确批准,不得创建、轮换、泄露或撤销密钥,邀请或移除成员,跨工作区委派,连接发信账户,创建或激活活动,导入或删除线索,更改抑制或保留策略,注册、修补、恢复或删除 webhook,调整套餐或付费容量,传输诊断信息,或执行其他生产变更。除非被要求实现,诊断应保持只读。输出应包含工作区安全范围、检查的文件与契约、确切的 API v2 路由与所需 scope、收集的证据、验证结果、已脱敏字段、剩余风险、负责人、审批状态与回滚或下一步。资料未提供具体代码示例、价格与更多平台细节。