变更日志

NU Signal Partners API 的重要变更。版本固定在路径中（/v1）；条目追踪 openapi/partner-api.yaml 的修订。

0.6.0

• 安全申请领取——新申请返回引用和一次性状态令牌。获批后，合作伙伴以原子方式领取一个有效 72 小时的 bootstrap 令牌。公开申请需要明确的隐私同意。
• 商业条款协议轴——使用类型、MG/RS、固定费用、API 与数据授权费、范围及合同快照固定在每个 deal 上，结算直接使用这些条款。
• 只读 Partner Portal——通过绝不存储原始 API 密钥的签名会话查看目录、deal 和 Production 结算。
• 加强环境隔离——金融结算 API 需要 Production 密钥；Sandbox 调用返回 production_key_required。

0.5.0

• 类型安全的 JS/TS SDK——packages/sdk-js 为所有 Partner API 路由提供具体请求与响应类型，包括公开申请和首个密钥 bootstrap。一致性测试会阻止缺失或过时的方法。
• 精确的 OpenAPI 响应约定——成功/错误封装及 required/nullable 定义与实际响应一致；协议与结算详情始终提供 updated_at 水位标记。
• 会话吊销一致性——活动会话返回 revoked；已结束会话保留真实最终状态。allowed_ips 仅适用于令牌签发，不绑定观众媒体 IP。
• 退款符号标准化——REFUND.revenue_amount 在账本中始终标准化为负数，并一致地从结算净收入中扣减。

0.4.0

• 托管 WebView 播放——POST /playback/tokens 现在除 manifest 外还返回托管 webview_url。无需播放器集成即可在 WebView 或 iframe 中打开；二者绑定同一会话（播放 API）。
• 观众偏好——可选非 PII 的 preferences 用于个性化 WebView 并存入会话（由 GET /playback/sessions/{id} 返回）。Schema 严格；含 @ 或空格的值会以 validation_failed（422）拒绝。
• 公开申请去重——24 小时内用相同联系邮箱重新提交 POST /partner-applications，不会创建新行，而是以 200 和 deduped: true 返回现有申请。

0.3.0

• 加强完整性保护——已知 Prisma 错误映射为清晰的 4xx 响应：P2002 → conflict（409）、P2003 → validation_failed、P2025 → resource_not_found（错误代码）。
• 请求大小上限——事件 payload 限制为 4 KB，请求字符串字段具有明确长度限制。
• 公开路由速率限制——未身份验证的 POST /partner-applications 和 POST /v1/api-keys/bootstrap 按客户端 IP 限制为 20/min。
• 幂等冲突——使用处理中 X-NU-Request-Id 重试创建播放令牌或授权请求时，返回 conflict（409），不会重复写入。已完成请求重放原始响应。

0.2.0

• 标准错误封装——所有错误均使用固定代码集返回 { "error": { code, message, request_id, details? } }（错误代码）。
• 请求头——正式规定 Authorization、X-NU-Partner-Id 和可选 X-NU-Request-Id（身份验证）。
• 事件分类——用于推导结算资格的规范 EventType 值（事件 API）。
• 结算异议与调整——POST /settlements/{id}/dispute 及扩展的结算费用和分成字段（结算 API）。
• 游标分页——列表端点接受 cursor，并与 page/limit 一同返回 next_cursor（目录 API）。

0.1.0 — 初始 Sandbox API

初始 MVP 框架：面向隔离 Sandbox 环境的目录、授权、播放和事件 API。