使用 novu/api TypeScript SDK 示例从环境搭建到事件触发的完整实践【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu本指南以 libs/internal-sdk/examples/README.md 为核心讲解如何在 Novu 仓库中搭建novu/apiSDK 示例运行环境、配置凭据、执行事件触发示例并结合 trigger.example.ts 与 SDK 源码剖析其底层调用链。读完本文你将能独立跑通官方示例、读懂novu.trigger的每个参数并基于示例模板快速扩展自己的自动化脚本。一、示例目录是什么在 Novu 仓库的 libs/internal-sdk/examples 目录下存放着一组用于演示novu/apiSDK 用法的示例脚本。novu/api是 Novu 的 TypeScript SDK当前仓库内版本为 3.19.0见 libs/internal-sdk/package.json用于以编程方式与 Novu 平台交互触发工作流事件、管理订阅者、读取消息与通知、配置集成等。目录当前包含三个文件README.md使用说明本文主体package.json示例工程声明通过novu/api: file:..直接引用仓库内的 SDK 源码trigger.example.ts演示如何调用novu.trigger触发一次通知事件。需要注意这些示例文件由 Speakeasy 代码生成器产出文件头部标注Code generated by Speakeasy ... DO NOT EDIT因此它们是示例脚手架真正的业务逻辑需要开发者自行填充。二、环境准备Prerequisites根据 README 的要求运行示例需要满足两个前置条件Node.jsv18 或更高版本npm对应地examples/package.json 的devDependencies也印证了运行时依赖types/nodeNode 类型定义、dotenv读取.env环境变量、tsx直接运行 TypeScript 文件的执行器以及novu/api指向父目录libs/internal-sdk的本地依赖。在动手前建议先确认 Node 版本满足要求node -v npm -v三、构建让示例链接到真实 SDK示例通过novu/api: file:..引用 SDK 源码因此直接npm install是不够的必须先构建父级 SDK 包。examples/package.json中的三个脚本把这一过程封装好了{ scripts: { build:parent: cd .. npm i npm run build cd -, build:examples: npm i, build: npm run build:parent npm run build:examples } }其执行顺序是build:parent进入父目录libs/internal-sdk安装其依赖并执行npm run build。父包的构建脚本为tsc见 libs/internal-sdk/package.json即用 TypeScript 编译器把src/编译为index.js等产物build:examples回到示例目录执行npm i把本地构建好的novu/api链接进示例工程。所以在示例目录中运行npm run build即可一次性完成构建 SDK 安装示例依赖两步。首次运行耗时较长属于正常现象因为父包需要完整编译整个 SDK。四、配置环境变量复制 .env.templateSDK 调用需要真实的平台凭据。README 给出的配置步骤是将.env.template复制为.envcp .env.template .env编辑.env填入你的实际凭据。仓库中的 .env.template 是一个占位骨架其内容仅为注释说明它提示该文件用于存放novu/apiSDK 的环境变量复制后需填入真实值且切勿把.env提交到版本控制。trigger.example.ts第一行就调用了dotenv.config()见 trigger.example.ts这意味着示例启动时会自动把.env中的键值对加载进process.env供脚本读取。对于生产或多人协作场景把敏感的 API Token 放入.env而非硬编码进脚本是更安全的做法。说明当前仓库内的trigger.example.ts为生成器产出的占位版本认证值以YOUR_BEARER_TOKEN_HERE硬编码占位你可以根据.env中的变量自行改造示例将其替换为process.env读取。五、运行示例README 给出了标准的运行命令需在 examples 目录内执行npm run build npx tsx trigger.example.ts该命令分两段npm run build先完成第三节所述的 SDK 构建与依赖安装npx tsx trigger.example.ts用tsx直接执行 TypeScript 示例无需先编译示例文件本身。tsx之所以能直接运行.ts是因为它基于 esbuild 做即时转译这也是它被列为devDependencies版本^4.19.2的原因。运行后脚本会调用 Novu 的触发接口并console.log(result)打印响应结果。六、逐行解读 trigger.example.tstrigger.example.ts 是示例目录中唯一的示例脚本完整展示了 SDK 的最核心用法——触发事件。下面逐段拆解import dotenv from dotenv; dotenv.config();加载.env环境变量。import { Novu } from novu/api; const novu new Novu({ security: { bearerAuth: YOUR_BEARER_TOKEN_HERE, }, });从novu/api导入并实例化 SDK 入口类Novu。初始化时必须通过security提供认证信息。从 sdk.ts 与 trigger.ts 的源码注释可以确认触发操作要求bearerAuth或secretKey其中之一被设置——即 API KeyBearer Token或 Secret Key 均可用于认证。async function main() { const result await novu.trigger({ workflowId: workflow_identifier, payload: { comment_id: string, post: { text: string }, }, overrides: {}, to: SUBSCRIBER_ID, actor: value, context: { key: org-acme }, }); console.log(result); } main().catch(console.error);novu.trigger的参数对应TriggerEventRequestDto其字段定义见 triggereventrequestdto.ts各字段含义如下参数类型说明workflowIdstring工作流标识符SDK 用它匹配关联的工作流注意映射到的请求字段名为name见该文件底部的 zod schema 映射payload对象传给工作流的自定义数据供模板变量渲染使用to订阅者标识接收方可以是订阅者 ID 字符串或订阅者对象overridesOverrides通道级覆盖配置作用于特定通道类型的所有步骤步骤级覆盖优先级更高actorSubscriberPayloadDto \| string用于展示消息发起者头像的 actor 订阅者 ID 或对象若传入新对象系统会创建对应订阅者context租户上下文触发时指定的租户上下文含id与可选data用于多租户场景transactionIdstring可选去重标识见下文防重复触发七、源码级原理trigger 的调用链novu.trigger并不是一个孤立方法它的背后是一条完整的 SDK 调用链理解它有助于排查问题与扩展用法入口Novu类libs/internal-sdk/src/sdk/sdk.ts继承自ClientSDK对外暴露trigger、cancel、triggerBroadcast、triggerBulk等方法以及workflows、subscribers、messages、notifications、topics、layouts、integrations、agents、activity、environments等懒加载子模块实现trigger方法内部委托给funcs/trigger.ts导出的trigger函数libs/internal-sdk/src/funcs/trigger.ts该函数负责请求编码JSON/simple 参数编码、HTTP 调用、状态码匹配与错误归一化服务地址默认请求https://api.novu.co可通过SDKOptions.serverIdx切换为https://eu.api.novu.coEU 区域或用serverURL覆盖为自托管地址libs/internal-sdk/src/lib/config.ts结果处理返回APIPromiseResult...通过unwrapAsync解包为EventsControllerTriggerResponse。另外两个值得注意的行为源自 trigger.ts 的 SDK 文档注释单次接收方上限 100一次触发最多携带 100 个接收者防重复触发可选传transactionId若再次使用相同的transactionId本次触发将被忽略保留期取决于计费层级。八、触发方式家族不止 trigger 一种Novu类还提供了其他三种事件操作见 sdk.ts在编写示例时可按场景选用cancel(transactionId)用先前触发时生成的transactionId取消处于活动或挂起状态的工作流常用于撤销进行中的 digest聚合或 delay延迟步骤triggerBroadcast(dto)向全部既有订阅者广播事件适合发送公告类消息triggerBulk(dto)一次请求批量触发多个事件避免多次调用 API单次请求上限 100 个事件。这些方法同样接受可选的idempotencyKey参数幂等键用于保证重复请求不会产生重复副作用。九、创建你自己的示例README 对扩展示例给出的建议非常简洁复制一个现有示例文件。cp trigger.example.ts my-workflow.example.ts这样做有两个原因示例文件由代码生成器产出生成过程中不会覆盖新增的文件README 原文they wont be overwritten by the generation process因此复制出来的新文件可以安全地自由修改复制保留了既有的导入结构、dotenv加载与main().catch(console.error)的错误兜底骨架你只需替换业务逻辑。建议在新示例中把占位的bearerAuth改为从.env读取配合dotenv.config()将workflowId替换为你实际创建的工作流标识符依据第八节选用trigger/triggerBroadcast/triggerBulk/cancel等不同 API用npx tsx my-workflow.example.ts直接运行验证。十、常见问题与注意事项提示找不到novu/api模块通常是父包未构建先在 examples 目录执行npm run build内部会先构建libs/internal-sdk认证失败 / 401确认security.bearerAuth或secretKey已替换为真实凭据且凭据所属环境与serverURLapi.novu.co还是eu.api.novu.co一致自托管部署若你使用的是自托管 Novu务必通过serverURL覆盖默认的云服务地址而不是依赖默认值不要把.env提交进版本库这是 .env.template 中的明确提示凭据泄露可能导致严重安全风险Node 版本README 要求 v18 及以上低版本可能无法运行tsx或 SDK 产物。围绕以上步骤你可以从一条npm run build npx tsx trigger.example.ts命令出发快速完成从环境搭建、凭据配置到事件触发的完整链路验证并在此基础上扩展出属于自己的 Novu 自动化脚本。【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考