SDK 概览
官方 TypeScript 和 Python SDK——它们在纯 HTTPS 之上增加了什么、二者如何比较,以及在发布到 npm 和 PyPI 之前如何从源码构建它们。
两个官方 SDK 封装了公共 API:面向 TypeScript 和 JavaScript 的 @dcision/sdk,以及面向 Python 的 dcision。它们以安全重试运行决策、分派函数目的地、验证 webhook 签名,并读取你的账户和执行记录——两种语言的行为完全相同。
尚未发布——请从源码构建
@dcision/sdk 还没有发布到 npm,dcision 也还没有发布到 PyPI。请按下面的方式从 Dcision 仓库的检出副本构建它们。在本页说明它们已发布之前,npm 或 PyPI 上任何使用这些名称的包都不是来自 Dcision:请不要安装。
# In a checkout of the Dcision repository — Node.js 22 and pnpm 10 for the workspace
pnpm install
pnpm --filter @dcision/sdk build # TypeScript: builds packages/sdk/dist
pip install ./packages/sdk-python # Python: installs into the active environment然后用 npm install /path/to/dcision/packages/sdk 把 TypeScript 构建添加到你的项目——参见 TypeScript SDK 和 Python SDK。
它们增加了什么
- 绝不会让决策运行两次的重试。每次
decide调用都会发送一个Idempotency-Key——你提供的,或者一个由其所有重试共用的新 UUID——并在网络错误、超时、429、502、503和504时重试,遵循Retry-After。如果第二个请求发现第一个仍在运行,它会等待第一个完成,而不是失败。 - 函数目的地。按名称注册处理函数;SDK 会在决策之后按顺序调用它们。
- Webhook 验证。一次调用即可以恒定时间检查
Dcision-Signature、时间戳和事件。 - 类型化的响应和统一的错误类型。每个 API 字段都有类型,而每种失败——API 错误、网络错误、抛出异常的处理函数、无效签名——都是带有稳定
code的DcisionError。 - 安全的默认设置。API 密钥在本地校验且从不打印;请求使用
https且从不跟随重定向,因此密钥不会到达其他主机。
对比
| TypeScript | Python | |
|---|---|---|
| 包 | @dcision/sdk(packages/sdk) | dcision(packages/sdk-python) |
| 运行时 | Node.js 20+、Bun、Deno、Cloudflare Workers、Vercel Edge | Python 3.9+ |
| 依赖 | 无——使用 fetch 和 Web Crypto | 无——仅标准库 |
| 客户端 | 异步(promise) | 同步;在异步代码中使用 asyncio.to_thread |
| 运行决策 | dcision.decide(slug, state, options) | client.decide(slug, state, ...) |
| 函数目的地 | functions、decision.dispatch() | functions=、decision.dispatch() |
| Webhook | verifyWebhook()、verifySignature() | verify_webhook()、verify_signature() |
| 账户和执行记录 | me()、executions.list()、executions.iterate() | me()、executions.list()、executions.iterate() |
| 每次尝试的超时 | 30 秒 | 30 秒 |
| 重试 | 2 次(共 3 次尝试) | 2 次(共 3 次尝试) |
不使用 SDK
API 只是一个携带 JSON 的 HTTPS POST,因此任何语言都可以使用:参见运行决策中的 cURL、JavaScript 和 Python 示例,以及幂等重试中带重试的完整客户端。CLI 覆盖终端和 CI——它同样需要从源码构建。