stable · guide · 0.1.0

送出 Notification Intent

準備通知資源

請 Platform Operator 在 sandbox 建立並核准 Sender Profile 與 template。Project Backend 可用具 notifications:write scope 的 Project Credential 註冊 FCM、APNs 或 Web Push Delivery Endpoint；MiniCenter 儲存 provider identifier，後續 inspect response 不會再揭露它。

Register a channel Delivery Endpoint

使用 SDK 的通用 request 方法或相同 HTTP contract 註冊 token：

Ts example

const endpoint = await client.request("POST", "/notification-endpoints", {
  body: { channel: "fcm", identifier: deviceToken },
});

Shell example

: "${MINICENTER_PROJECT_CREDENTIAL:?set the sandbox Project Credential}"
: "${MINICENTER_URL:=https://sandbox.minicenter.otus.tw}"
curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer ${MINICENTER_PROJECT_CREDENTIAL}" \
  --header "Content-Type: application/json" \
  --data '{"channel":"fcm","identifier":"sandbox-fcm-device-token-0001"}' \
  "${MINICENTER_URL}/api/v1/notification-endpoints"

註冊回應為 pending 時，從驗證通知取得一次性 token，再呼叫 POST /notification-endpoints/{endpointId}/verify。完成驗證後，以 PUT /notification-endpoints/{endpointId}/consents/{purpose} 授予明確 purpose。可用 safe inspect API 讀取狀態與 consent，但無法取回 provider token；不再使用的 endpoint 應呼叫 revoke API。

Email template 的 {{variable}} 一律做 HTML escaping。只有 template owner 明確寫成 {{{variable}}} 時，該 body variable 才會當成 project-owned HTML；subject 不允許 raw variable。若 Project Backend 傳入完整 HTML email，template 應以 {{{body}}} 明確宣告這個信任邊界。

Register an email Delivery Endpoint

Project Backend 以 POST /email-delivery-endpoints 註冊正規化後的 email address。新 endpoint 回傳一次性 verification_token；驗證持有者後，將該 token 傳給 POST /email-delivery-endpoints/{endpointId}/verify。重複註冊只回傳穩定 ID 與狀態，不會再次揭露 token。

建立 email Intent

同一業務通知在結果不明時必須沿用原本的 Idempotency-Key 與完全相同的 body。

Shell example

: "${MINICENTER_PROJECT_CREDENTIAL:?set the sandbox Project Credential}"
: "${MINICENTER_URL:=https://sandbox.minicenter.otus.tw}"
curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer ${MINICENTER_PROJECT_CREDENTIAL}" \
  --header "Idempotency-Key: docs-notification-1" \
  --header "Content-Type: application/json" \
  --data '{"sender_profile_id":"81000000-0000-4000-8000-000000000001","template_key":"sandbox-welcome","locale":"zh-TW","endpoint_id":"82000000-0000-4000-8000-000000000001","variables":{"display_name":"Sandbox user"}}' \
  "${MINICENTER_URL}/api/v1/notification-intents"

回應的 intent_id 與 delivery_id 是穩定識別碼。status 是建立當下的 delivery 狀態，不應被解讀為已送達證明。

建立 FCM、APNs、LINE 或 Web Push Intent

非 email channel 使用相同的 credential 與 idempotency 規則，但呼叫 POST /channel-notification-intents，並提供已驗證 endpoint 的 purpose。建立後可用回應中的 delivery_id 查詢 outcome。