uapp-communication-sdk 1.0.0-dev.64 → 1.0.0-dev.66

package/README.md

@@ -601,7 +601,74 @@ Before going live, verify:
 
 ---
 
-## 13. Package exports
+## 13. Without a widget: status and notifications
+
+A widget only exists on the page it is mounted on, and the person using your application is usually
+somewhere else in it. Two headless clients cover that. Both render nothing, hold no React, and take
+the same options as a widget — including `getAssertion`, which must mint a **fresh** assertion every
+time it is called.
+
+### Their own status
+
+The widgets show everyone **else's** status beside their name — Available, Busy, In a meeting, Focus,
+Away — but they have no chrome of their own to set one from. This is how your header gets a status
+control:
+
+```ts
+import { createPresenceClient } from 'uapp-communication-sdk';
+
+const presence = createPresenceClient({
+  apiBaseUrl: 'https://api.commhub.example',
+  clientKey: 'sk_live_…',
+  getAssertion: () => fetch('/api/commhub-assertion').then((r) => r.text()),
+});
+
+const current = await presence.getMine();      // { status: 'available', source: 'connection', … }
+await presence.setMine({ status: 'busy', minutes: 30, note: 'On a call' });
+await presence.clearMine();
+```
+
+Three things to build against:
+
+- **`minutes`, not an end time.** The server resolves the duration against its own clock and caps it
+  at 24 hours, so a device with a wrong clock cannot extend its own status. Every status ends: there
+  is no "until I turn it off", because a status nobody remembers to clear is still showing days later
+  and an indicator nobody believes is worse than none.
+- **Render the answer, not the request.** All three calls return the RESOLVED presence, which is not
+  always what you asked for — a calendar block can outrank a self-set status. `source` tells you which
+  input won (`override`, `activity`, `calendar`, `connection`), so your UI can say "from your calendar"
+  instead of leaving somebody to wonder why they look busy.
+- **Offer "clear" only when `hasOverride` is true.** A status that came from a calendar is not theirs
+  to clear, and a dead control is a promise the feature does not keep.
+
+Every call answers `null` rather than throwing — on a failed exchange, an unreachable API, or a
+response that does not match the contract. A half-parsed status in your header is worse than none.
+
+This client reads and writes; it opens no socket. It will not tell you when somebody **else's** status
+changes — mount a widget for that.
+
+### Notifications
+
+```ts
+import { createNotificationClient } from 'uapp-communication-sdk';
+
+const client = createNotificationClient({
+  apiBaseUrl: 'https://api.commhub.example',
+  clientKey: 'sk_live_…',
+  getAssertion: () => fetch('/api/commhub-assertion').then((r) => r.text()),
+  onNotification: (n) => bell.add(n),
+});
+await client.start();
+```
+
+`start()` loads what is already unread and then opens the live connection — without the first half a
+badge reads zero on every page load however long the person was away. `markAsRead(id)` keeps the count
+agreeing with the Hub. Requires the `commhub.feed` scope: that is what the notification hub is scoped
+to.
+
+---
+
+## 14. Package exports
 
 ```ts
 import {
@@ -613,6 +680,8 @@ import {
   CommsProvider,
   WidgetRoot,
   SDK_MODULE_SCOPES,
+  createPresenceClient,
+  createNotificationClient,
 } from 'uapp-communication-sdk';
 
 import type {
@@ -624,6 +693,15 @@ import type {
   ThemeDensity,
   ThemeMode,
   WidgetRootProps,
+  PresenceClient,
+  PresenceClientOptions,
+  SdkPresence,
+  SdkPresenceSource,
+  SdkPresenceStatus,
+  SetSdkPresenceInput,
+  NotificationClient,
+  NotificationClientOptions,
+  SdkNotification,
 } from 'uapp-communication-sdk';
 ```
 
@@ -631,7 +709,7 @@ Most integrations only need `defineCustomElements()`.
 
 ---
 
-## 14. Support information to collect
+## 15. Support information to collect
 
 If an integration fails, collect: