freezonex/tier0-sdk/tier0-sdk-notifications

Tier0 SDK — Notifications

Before starting, read the root SDK Skill at [`../SKILL.md`](../SKILL.md).

⚠️ Response format differs from every other endpoint

The two notifications endpoints do not use the {code, msg, data} envelope:

• Success: HTTP 200 with a bare JSON body (e.g. { messageId, status, createdAt }). Read fields directly — result.data does not exist.
• Failure: a real HTTP status code (400/401/403/404/409/422/429) with body { errorCode, message }. The SDK client throws ApiError; the raw error JSON lands in error.msg. Parsing pattern is in `references/send.md`.

Recipient UX invariant

recipientUserId is an internal transport field, not a user-facing concept.

• In an app, present a searchable member picker using names, nickname, email, and relevant roles. Store the selected member's userId internally and pass it to the send API; never render a free-text “User ID” field.
• In an agent conversation, ask for a recognizable person such as a name or email, query the member list, and show human-readable candidates when ambiguous. Never ask the user to find, paste, or choose a numeric ID.
• For a project-scoped audience, query that project's members. For a Workspace-wide audience, query platform members with statuses: ['active']. Read `tier0-sdk-members` before implementing either picker.
• A trusted business record may already contain a previously resolved userId; use it internally without exposing it. Do not accept an arbitrary ID supplied through ordinary end-user input.
• If the API key cannot query members, treat that as an app configuration or permission error. Do not fall back to raw-ID input. Cloud member queries currently require uns:read in addition to the notification permissions.

Notification decisions

Resolve the recipient and message from the user intent. Apply the SDK channel contract below:

Channel examples

For a resolved notification body, choose one request shape:

notificationsApi.openapiv1notificationssend(body); // default: Web & Desktop + Mobile
notificationsApi.openapiv1notificationssend({ ...body, channels: ['web', 'mobile'] }); // all
notificationsApi.openapiv1notificationssend({ ...body, channels: ['web'] }); // Web & Desktop
notificationsApi.openapiv1notificationssend({ ...body, channels: ['mobile'] }); // Mobile
notificationsApi.openapiv1notificationssend({ ...body, channels: [] }); // inbox only

These are alternatives, not five sends for the same event. See send.md for the full request and upgrade notes.

Scope Routing

Final Checklist

1. The user selected a recognizable member; no UI or prompt asked for a raw user ID.
2. recipientUserId was resolved internally from member data or a trusted business relation.
3. Recipient came from user intent; channels follow the SDK default or the user's explicit scope. Inbox-only requests use [].
4. The recipient is an active member of the API key's workspace.
5. idempotencyKey is a business-event key, reused verbatim on retries.
6. Responses were parsed as bare JSON (no envelope) and errors via ApiError.status + JSON in ApiError.msg.
7. Status reported to the user says "sent", never "seen/read" — there is no read receipt.
8. If a link was sent, it passes every rule in send.md — https:// or / prefix, protocol-relative //host and backslashes rejected, ≤500 characters, no Unicode whitespace / control / invisible format characters — and points at something the recipient has permission to open.