SDK 总览 - Pushnow Docs

选择一个 SDK

所有 SDK 都有两条路径。Scoped API token client 使用 Dashboard 里创建的一个 Authorization key（PushNow_...），按它的 scopes 读取账号、来源、历史、日志，也可以直接调用 /v2/messages 发送通知。后端会使用已登录 Web 或 App 保存的同账号 sender key 加密。E2EE sender 路径仍然支持本地 sender 授权、本地内容加密和加密附件上传。当前说明基于仓库里的本地源码包；不要假设这些包已经发布到公开包管理平台。

语言	仓库目录	运行环境	文档
TypeScript / JavaScript	`sdk/typescript`	支持 WebCrypto 的现代浏览器，或 Node.js 22+	TypeScript 和 npm
Python	`sdk/python`	Python 3.10+ 以及 Node.js 22+	Python
Go	`sdk/go`	Go 1.22+ 以及 Node.js 22+	Go
Java	`sdk/java`	Java 11+ 以及 Node.js 22+	Java

Python、Go 和 Java 是对内置、锁定版本 JavaScript HPKE runtime 的子进程绑定。它们不是各语言原生的密码学实现，编译产物也不会把 Node 打包进去。部署时需要把对应 SDK 的 runtime/ 目录和安装好的依赖一起带上。

一个 key，对应多个权限

在 Dashboard 创建 API token 并选择 scopes。account:read 用于 getAccount / account，sources:read 用于来源列表，send:write 用于 sendMessage，history:read 用于历史读取，history:write 用于状态更新和删除，logs:read 用于投递日志，all 开启所有 scoped token 能力。同一个 key 通过 Authorization: Bearer <PushNow_...> 传入。

这条 token 路径适合服务端集成、Webhook 和简单自动化。sendMessage 会把标题和正文提交到 /v2/messages；PushNow 使用同账号保存的 sender key 在服务端完成加密。

授权和 E2EE 登录是两件事

先在 iOS App 里登录并初始化加密账号。SDK 授权流程不会注册用户，也不会用邮箱密码登录。它会创建一个 sender 密钥对，并请求你的可信设备批准这个 sender。

推荐流程使用已登录 App 或可信 Dashboard 会话里的账号 access token 发起账号绑定授权，再在可信手机上完成批准。token 只用于授权设置请求，不能单独加密消息。

SDK 授权现在只支持账号 Access Token 流程。token 用来创建账号绑定授权，仍然需要已登录的可信 App 批准 sender，SDK 才会拿到可复用的加密 config。

授权完成后的配置包含 api_url、user_id、source_id、source_key、identity_public_key、sender_private_key 和经过认证的 archive public record。它是私密凭证，必须安全保存。单个 scoped API token 可以按权限调用 HTTP API 并在拥有 send:write 时发送通知；只有需要客户端本地生成 envelope 或加密附件时，才需要这份 sender 配置。

不同语言的选项差异

行为	TypeScript	Python / Java	Go
发送到所有设备	省略 `deviceIds`	省略 `deviceIds`	`DeviceIDs: nil`
发送到指定设备	`deviceIds: [id]`	`deviceIds` 列表 / JSON array	指向设备 ID 切片的指针
只保存到收件箱	`inboxOnly: true` 或 `deviceIds: []`	`pushEnabled: false` 或空 `deviceIds`	`PushEnabled` 指向 false，或指向空设备 ID 列表
定时发送	`scheduledAt` 选项	`scheduledAt` 输入	`ScheduledAt`
图片	`image` 文件输入	`images` 文件列表	`Images`
声音	`MessageOptions.sound`	`sound` 输入	`Sound` 指针

设备定向只影响本次 APNs 推送目标，不限制账号历史记录。账号下其他设备仍可在收件箱里看到同一条消息。定时发送最长 30 天，不会把已保存消息隐藏到触发时间才出现。更多内容字段见消息内容和定时发送。

声音参数统一为 default | silent | chime。省略时保持默认行为。silent 仍会请求可见通知，只是不带 aps.sound；chime 使用 App 内置的 pushnow-chime.wav，不接受任意上传的音频文件名。声音是公开路由元数据，消息正文和文件仍然加密。最终是否响铃受 iOS 通知设置、声音权限和专注模式影响。

重试和日志

需要可靠投递时，先 prepare 一次并保存原始 outbox，然后重试同一个 envelope。TypeScript SDK 当前在内存里绑定账号和 source，序列化 outbox 后再导入不被支持；需要重启后重试时，优先使用 CLI 或 Python/Go/Java 绑定的 durable outbox 流程。

SDK 的请求事件和日志只暴露 method、endpoint template、HTTP status、耗时和结果类型，不包含 token、明文、密文 payload 或原始响应体。这些本地诊断日志和账号里的投递日志是两套东西。