@xtremax/pigeon 0.3.0 → 0.4.0

package/skills/add-pigeon-notifications/references/inbox-contract.instructions.md

@@ -0,0 +1,210 @@
+# Pigeon inbox: the full contract
+
+Read this when the steps in `SKILL.md` are not enough: translating the bell, placing the full list on a page of its own, reading the inbox from server code, or building a bell without React and Mantine.
+
+## Contents
+
+- [The package's entries](#the-packages-entries)
+- [`InboxProvider`, `NotificationBell`, `InboxFullList`](#inboxprovider-notificationbell-inboxfulllist)
+- [Labels](#labels)
+- [`createInboxHandler`](#createinboxhandler)
+- [The six operations of the route](#the-six-operations-of-the-route)
+- [Error codes](#error-codes)
+- [How the bell behaves](#how-the-bell-behaves)
+- [Reading the inbox from server code](#reading-the-inbox-from-server-code)
+- [An app without React or Mantine](#an-app-without-react-or-mantine)
+
+## The package's entries
+
+| Import | Runs | Holds |
+|---|---|---|
+| `@xtremax/pigeon/client` | server | `createCommunicationClient`, `CommunicationError` |
+| `@xtremax/pigeon/inbox` | server | `createInboxHandler`, `createInboxClient` |
+| `@xtremax/pigeon/inbox-react` | browser | `InboxProvider`, `NotificationBell`, `InboxFullList`, `DEFAULT_INBOX_LABELS` |
+| `@xtremax/pigeon/inbox-react/styles.css` | browser | the bell's stylesheet |
+| `@xtremax/pigeon/preferences` | server | `createPreferencesHandler`, `createPreferencesClient` (see `consent.instructions.md`) |
+| `@xtremax/pigeon/preferences-react` | browser | `NotificationPreferences`, `DEFAULT_PREFERENCE_LABELS` |
+| `@xtremax/pigeon/events` | server | `createEventHandler`, `verifyEventSignature` (delivery events; not needed for the bell) |
+| `@xtremax/pigeon` | server | all server entries, plus `deriveIdempotencyKey`, `newIdempotencyKey` |
+
+The server entries hold the key. Imported into a browser bundle they resolve to a stub that throws `server_only`. `inbox-react` and `preferences-react` hold no key and call only the app's own routes.
+
+The names in the code say `Communication` (`createCommunicationClient`, `COMMUNICATION_API_KEY`). That is Pigeon's name on the Buildpad platform, where it is the Communication connector. It is the same service.
+
+## `InboxProvider`, `NotificationBell`, `InboxFullList`
+
+`InboxProvider` props, all optional:
+
+| Prop | Default | Use |
+|---|---|---|
+| `apiBase` | `/api/communication/inbox` | Where the app mounted the route. A path on the app's own origin only: an absolute URL is refused. |
+| `labels` | English | Replaces any visible or spoken text. See [Labels](#labels). |
+| `locale` | the browser's | Formats times, for example `'id'` or `'en-GB'`. |
+| `onViewAll` | opens the full list in a dialog | Call your router to open a page of your own instead. |
+| `onOpenPreferences` | opens the preference dialog | Open a settings page of your own instead. |
+| `openLink` | a new tab, `noopener,noreferrer` | Open a notification's link your own way, for example in the same tab. |
+
+`labels` is a plain object, so it can be passed from a server component. The three callbacks are functions: to use one, render `InboxProvider` from a client component (`'use client'`).
+
+`NotificationBell` takes `size` (pixels, never under 44). It must be inside `InboxProvider`.
+
+`InboxFullList` is the full, paged list. Use it with `onViewAll` to give notifications a page of their own. It needs an `InboxProvider` above it, so put the provider around the whole signed-in layout: the header's bell and the page's list then share one, and the count is asked for once.
+
+```tsx
+'use client';
+import { InboxFullList, InboxProvider, NotificationBell } from '@xtremax/pigeon/inbox-react';
+import { useRouter } from 'next/navigation';
+
+// around the signed-in layout: the header with the bell, and the pages
+const router = useRouter();
+<InboxProvider onViewAll={() => router.push('/notifications')}>
+  <header><NotificationBell /></header>
+  {children}
+</InboxProvider>
+
+// on app/(authenticated)/notifications/page.tsx
+<InboxFullList maxHeight="70vh" />
+```
+
+## Labels
+
+Pass any of these in `labels`. `{n}` and `{label}` are filled in.
+
+| Key | English default |
+|---|---|
+| `bell` | Notifications |
+| `bellWithCount` | {label}, {n} unread |
+| `heading` | Notifications |
+| `tabAll` | All |
+| `tabUnread` | Unread |
+| `tabUnreadWithCount` | Unread ({n}) |
+| `markAllRead` | Mark all as read |
+| `viewAll` | View all |
+| `preferences` | Notification preferences |
+| `emptyAll` | You have no notifications. |
+| `emptyUnread` | You have no unread notifications. |
+| `loading` | Loading notifications |
+| `loadError` | Notifications could not be loaded. |
+| `retry` | Try again |
+| `actionError` | That did not work. Try again. |
+| `dismiss` | Dismiss |
+| `close` | Close |
+| `unread` | Unread |
+| `announcement` | Announcement |
+| `loadMore` | Show older notifications |
+| `newOne` | 1 new notification |
+| `newMany` | {n} new notifications |
+| `fullListTitle` | All notifications |
+| `preferencesTitle` | Notification preferences |
+| `preferenceToggle` | Receive in-app notifications |
+| `preferenceOn` | New notifications from this app appear here. |
+| `preferenceOff` | New notifications from this app do not appear here. The ones you already have stay. Other apps are not affected. |
+| `preferenceLoadError` | Your preference could not be loaded. |
+| `preferenceSaveError` | Your choice was not saved. Try again. |
+
+The titles and bodies of notifications are not labels: they are written by whoever sent them, in the language they chose.
+
+## `createInboxHandler`
+
+```ts
+createInboxHandler(options): (request: Request) => Promise<Response>
+```
+
+| Option | Default | Use |
+|---|---|---|
+| `resolvePerson` (required) | | `(request) => string \| null`, sync or async. The signed-in person's id from the app's own session. `null` or an empty string means nobody. At most 128 characters. |
+| `client` | made on the first request from `COMMUNICATION_API_KEY` and `COMMUNICATION_URL` | Pass `createInboxClient({ apiKey, baseUrl })` to use other settings. |
+| `basePath` | `/api/communication/inbox` | Set it when the route file is somewhere else. It must match `apiBase` on `InboxProvider`. |
+| `allowedOrigins` | the request's own origin | Origins that may send `POST` and `PUT`. Needed only when pages are served from another origin than the route. |
+| `timeoutMs` | 8000 | Bounds each call to Pigeon. |
+| `onError` | | Told about every failure answered as `unavailable`. Log it: the browser is never told the cause. |
+
+The handler takes a standard `Request` and answers a standard `Response`, so it works in any server that speaks the Fetch API, not only Next.js. Export it for `GET`, `POST` and `PUT`.
+
+## The six operations of the route
+
+All paths are under the base path. Every answer is JSON with `Cache-Control: no-store`. A success is `{ "data": ... }`; a failure is `{ "error": { "code", "message", "field"? } }`.
+
+| Method and path | Request | `data` in the answer |
+|---|---|---|
+| `GET /summary` | | `{ unreadCount, newestUnreadAt, pollSeconds }` |
+| `GET /notifications` | query `limit` (1 to 100, default 20), `cursor`, `unread=true` | `{ notifications: [...], nextCursor, unreadCount }` |
+| `POST /notifications/{id}/read` | empty JSON body | `{ notification, unreadCount }` |
+| `POST /read-all` | `{ "upTo"?: ISO time }` | `{ marked, remaining, unreadCount }`; call again while `remaining > 0` |
+| `GET /preference` | | `{ state, changedAt, delivers }` |
+| `PUT /preference` | `{ "state": "opted_in" \| "opted_out" }` | `{ state, changedAt, delivers }` |
+
+A notification:
+
+```ts
+interface InboxNotification {
+  id: string;
+  kind: 'notification' | 'announcement';
+  title: string;            // plain text; never render it as markup
+  body: string;             // plain text
+  link: string | null;      // absolute https, or null
+  source: { type: 'xapp' | 'tenant'; name: string };
+  createdAt: string;        // ISO time
+  read: boolean;
+  readAt: string | null;
+}
+```
+
+- `nextCursor` is `null` on the last page. Pass it back as `cursor` unchanged.
+- `state` is `opted_in`, `opted_out` or `not_set`; `delivers` says whether new notifications reach the person now.
+- `POST` and `PUT` must come from the app's own pages: the handler checks `Sec-Fetch-Site: same-origin` or the `Origin` header.
+
+## Error codes
+
+| Code | Status | Meaning |
+|---|---|---|
+| `not_signed_in` | 401 | `resolvePerson` returned nobody. The bell stops asking, silently. |
+| `not_permitted` | 403 | A `POST` or `PUT` from another origin, or Pigeon refused the key for this call. |
+| `not_found` | 404 | No such operation, or a notification that is not this person's or not this app's. |
+| `invalid_input` | 422 | A value from the browser was refused; `field` names it. |
+| `rate_limited` | 429 | Too many calls. |
+| `unavailable` | 503 | Everything else: a wrong or revoked key, a timeout, Pigeon not reachable. The cause goes to `onError` only. |
+
+Errors thrown by `createCommunicationClient` and `createInboxClient` are `CommunicationError` with `code`, `status`, `requestId` and `retryable`. Codes you may meet when sending: `channel_unavailable`, `validation_failed` (a missing or too long variable, an unknown template), `forbidden`, `invalid_credentials`, `rate_limited`, `idempotency_conflict`, `not_configured`, `timeout`, `network_error`.
+
+## How the bell behaves
+
+- **Updates.** It asks for the count every 60 seconds (Pigeon's setting, never under 15). It pauses while the page is hidden and asks at once when it is visible again. After failures it waits longer, up to 5 minutes. There is no realtime push.
+- **Outage.** It keeps the last count and the page keeps working. A list that cannot load shows "Try again".
+- **Selecting a notification** marks it read, and opens its link when it has an `https` one.
+- **"Mark all as read"** covers what this bell shows, never another app's notifications.
+- **Announcements** are one copy per person: read in one app's bell, they are read in every bell.
+- **The preference** is this app's own. Switching it off stops this app's notifications for the person; other apps and announcements go on.
+- **Nothing is kept in the browser's storage.**
+
+## Reading the inbox from server code
+
+For a count in a server-rendered page, a digest email or a test. Each call takes the person id first.
+
+```ts
+import { createInboxClient } from '@xtremax/pigeon/inbox';
+import { communication } from '@/lib/communication/client';
+
+const inbox = createInboxClient(communication()); // shares the key and settings
+
+const { unreadCount } = await inbox.summary(personId);
+const page = await inbox.list(personId, { limit: 20, unreadOnly: true });
+await inbox.markRead(personId, page.notifications[0].id);
+await inbox.markAllRead(personId);
+const preference = await inbox.getPreference(personId);
+await inbox.setPreference(personId, 'opted_out');
+```
+
+These throw `CommunicationError` on failure. The person id here is trusted, so it must come from your own session or data, never from a request.
+
+## An app without React or Mantine
+
+The route is the same: mount `createInboxHandler` on a catch-all route of the app's server. Then build the bell with the app's own components against the six operations above:
+
+1. Ask `GET /summary` when the page loads, then every `pollSeconds`. Stop on `401`. Wait longer after a failure.
+2. Show `unreadCount` on the bell (`99+` above 99).
+3. On open, `GET /notifications`. Show `title` and `body` as text. Offer `nextCursor` as "show older".
+4. On select, `POST /notifications/{id}/read`, and open `link` in a new tab with `noopener,noreferrer` only when it starts with `https://`.
+5. Offer "mark all as read" (`POST /read-all`, repeated while `remaining > 0`) and the on/off choice (`GET` and `PUT /preference`).
+
+Send requests with `credentials: 'same-origin'`. Never call Pigeon from the browser and never put the key in the page.