stable · overview · 0.1.0

Notifications

從業務意圖到傳送

Project Backend 建立 Notification Intent，說明要使用的 template、locale、Delivery Endpoint 與 variables。MiniCenter 驗證 client-scoped Sender Profile、template、endpoint 與 consent，再建立 Notification Delivery 交給 durable worker。

Notification Intent 是 Project Backend 已決定要通知的業務事實；MiniCenter 不替 Project Backend 決定何時通知、收件人的偏好或 marketing purpose。

Project Backend 應把 Notification Catalog 保存在自己的 repository，並在 CI 透過驗證 Notification Catalog確認 event key、purpose、locale、variables 與 MiniCenter 已核准的 Sender Profile 和 template 相容。

Channels 與可靠性

目前平台的 delivery channels 包含 email、FCM、APNs、LINE 與 Web Push。每個 Delivery Endpoint、Sender Profile、template 與 consent 都限制在同一 Project Client。

Delivery 以 PostgreSQL durable operation 保存，provider 的暫時失敗會 exponential backoff retry；超過嘗試上限後進入 dead-letter。建立 Intent 成功只代表請求已持久化，不代表 provider 已送達。

從送出 Notification Intent開始，再閱讀channels、delivery outcome 與 retry。

Guides

• Validate a Notification Catalog — 在 CI 對照 MiniCenter 已核准的 Sender Profile 與 template，阻止通知契約漂移。
• 送出 Notification Intent — 在 sandbox 以已核准的 Sender Profile、template 與 Delivery Endpoint 建立通知。
• Channels、delivery outcome 與 retry — 理解 email、FCM、APNs、LINE、Web Push 的 endpoint、outcome 與 durable retry。

API Reference

• Validate a repository-owned Notification Catalog — POST /api/v1/notification-catalog/validate
• Register an email Delivery Endpoint — POST /api/v1/email-delivery-endpoints
• Verify an email Delivery Endpoint — POST /api/v1/email-delivery-endpoints/{endpointId}/verify
• Create a Notification Intent — POST /api/v1/notification-intents
• Create an FCM, APNs, LINE, or Web Push Notification Intent — POST /api/v1/channel-notification-intents
• Register or reuse an FCM, APNs, or Web Push Delivery Endpoint — POST /api/v1/notification-endpoints
• Verify a channel Delivery Endpoint — POST /api/v1/notification-endpoints/{endpointId}/verify
• Inspect a channel Delivery Endpoint without exposing its identifier — GET /api/v1/notification-endpoints/{endpointId}
• Revoke a channel Delivery Endpoint — DELETE /api/v1/notification-endpoints/{endpointId}
• Grant or revoke channel Delivery Consent for a purpose — PUT /api/v1/notification-endpoints/{endpointId}/consents/{purpose}
• Get a Notification Delivery outcome — GET /api/v1/notification-deliveries/{deliveryId}

Event Reference

• In-app notification signal — An ephemeral in-app signal is available for a Project Client target.
• Notification Delivery outcome — The authoritative current state of an email, FCM, APNs, LINE, or Web Push Delivery.