@droponair/sdk-js 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.26.0
+
+### Added
+
+- **Push payloads on outgoing messages.** `sendMessage` and `sendGroupMessage` accept
+  `options.push`, and `defaultPushPayload` on the client config attaches one to every
+  message that does not carry its own. Setting the default once is the recommended
+  route: passing a payload per send means forgetting it once stops push with no error
+  to notice.
+- **`PushDelivery` chooses how a push behaves** on the recipient's device, and the
+  platform translates it per transport rather than deciding for you:
+  - `alert` shows title and body as supplied. Suits apps sending cleartext.
+  - `mutable` shows them as a placeholder and lets your app replace the text before it
+    appears, which is how an end-to-end encrypted app puts real content on a lock
+    screen without the relay seeing it. On iOS this is also the reliable way to be
+    woken, because the system throttles silent pushes.
+  - `silent` wakes the app and shows nothing.
+  - `voip` is the call invite path, superseding the `voip` boolean, which is still honoured.
+
+### Notes
+
+- Push previously could not be triggered at all: no SDK exposed a way to attach a
+  payload, and the server only pushes when the sender supplies one.
+- Never put message content in `title` or `body`. Every field is readable by the relay,
+  which is why it can act on them, and putting plaintext there leaks it through the one
+  path the platform promises never sees it.
+- Additive and backward compatible. Messages sent without a payload behave exactly as
+  before, and an absent or unrecognised delivery mode is treated as `alert`.
+
+## 0.25.1
+
+### Changed
+
+- Documentation only, no behaviour or API change. Comments and notes that shipped in the
+  package described the platform's own internals rather than the integration surface: some
+  named components a consumer never talks to, and some carried planning tags that mean nothing
+  outside our own backlog. They are rewritten in terms of what the code does and what the
+  platform offers.
+- Where availability used to be described as a specific plan flag, it now points at the pricing
+  page and the app's subscription, which are the two places that stay correct as plans change.
+- `PROTOCOL_VERSION` references are untouched. That is the contract a consumer integrates
+  against and it remains the way to tell what a relay supports.
+- Em dashes are gone from the shipped text, per the house style. Each was judged in place
+  rather than swapped mechanically, so clauses read as sentences rather than comma splices.
+
 ## 0.25.0
 
 ### Added
@@ -43,7 +88,7 @@
 
 ## 0.24.2
 
-- Fix: E2EE group message decryption failed because the decrypt AAD bound `recipientId` to the group id instead of the receiving user's own id (which is what the sender encrypts against). Now matches the sender and the other SDKs. Requires sdk-be that preserves the sender timestamp on group notifications.
+- Fix: E2EE group message decryption failed because the decrypt AAD bound `recipientId` to the group id instead of the receiving user's own id (which is what the sender encrypts against). Now matches the sender and the other SDKs. Requires a relay that preserves the sender timestamp on group notifications.
 
 ## 0.24.1
 
@@ -221,7 +266,7 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ### Changed
 
-- **`revokeAttachment` accepts an `AttachmentRef`.** Calling `revokeAttachment(ref)` now also revokes the linked preview thumbnail (`ref.thumbnailAttachmentId`) in the same call. `revokeAttachment(attachmentId)` with a plain id string is unchanged and revokes only that one attachment. Additive — no breaking change.
+- **`revokeAttachment` accepts an `AttachmentRef`.** Calling `revokeAttachment(ref)` now also revokes the linked preview thumbnail (`ref.thumbnailAttachmentId`) in the same call. `revokeAttachment(attachmentId)` with a plain id string is unchanged and revokes only that one attachment. Additive, so no breaking change.
 
 ---
 
@@ -230,13 +275,13 @@ This project follows [Semantic Versioning](https://semver.org/).
 ### Added
 
 - **Group read receipts.** When a group has `readReceiptsVisibleToGroup` enabled, a member's `markRead(messageId, groupId)` is fanned to every other member, not just the reader's own devices. The inbound `ReadReceiptEvent` now carries `fromUserId` so you know which member read the message. New `client.updateGroup(groupId, { name?, readReceiptsVisibleToGroup? })` controls the per-group flag (it is a group-level choice; off by default). Broadcasts stay own-device only by design.
-- **Attachment revoke.** New `client.revokeAttachment(attachmentId)` — the platform stops issuing download URLs for it and recipients with a live connection get an `ATTACHMENT_REVOKED` event via `onEvent` (metadata = attachmentId). Bytes already downloaded cannot be recalled.
-- **Attachment preview thumbnails.** `prepareAttachmentAndUpload` accepts an optional `thumbnail` (and `thumbnailMimeType`). Entirely optional — if provided, the SDK uploads it as a separate attachment encrypted the same way and links it via `AttachmentRef.thumbnailAttachmentId`; download it like any attachment. If omitted, there is simply no thumbnail.
+- **Attachment revoke.** New `client.revokeAttachment(attachmentId)`. The platform stops issuing download URLs for it and recipients with a live connection get an `ATTACHMENT_REVOKED` event via `onEvent` (metadata = attachmentId). Bytes already downloaded cannot be recalled.
+- **Attachment preview thumbnails.** `prepareAttachmentAndUpload` accepts an optional `thumbnail` (and `thumbnailMimeType`). Entirely optional: if provided, the SDK uploads it as a separate attachment encrypted the same way and links it via `AttachmentRef.thumbnailAttachmentId`; download it like any attachment. If omitted, there is simply no thumbnail.
 
 ### Notes
 
 - Download authorization for GROUP attachments is now checked against *current* group membership: a user removed from a group can no longer download its attachments even if they were a recipient at upload time.
-- No PROTOCOL_VERSION change — additive proto fields (`SyncFrame.fromUserId`, `AttachmentRef.thumbnailAttachmentId`) and an additive event type.
+- No PROTOCOL_VERSION change: additive proto fields (`SyncFrame.fromUserId`, `AttachmentRef.thumbnailAttachmentId`) and an additive event type.
 
 ---
 
@@ -244,14 +289,14 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ### Added
 
-- **Notification clear sync.** `client.clearNotification(conversationId)` tells the user's other devices a conversation's notifications were dismissed; `client.onNotificationCleared(cb)` listens for it. Always available (no opt-out) — it is plain own-device hygiene.
+- **Notification clear sync.** `client.clearNotification(conversationId)` tells the user's other devices a conversation's notifications were dismissed; `client.onNotificationCleared(cb)` listens for it. Always available (no opt-out), since it is plain own-device hygiene.
 - **Draft sync.** `client.syncDraft(conversationId, draftText)` pushes a conversation draft to the user's other devices; `client.onDraftSync(cb)` listens for it. **Opt-in:** the app owner enables it in the dashboard, and the draft text crosses the relay in cleartext (fanned out, never stored). When disabled the server drops the frame.
 - New exported types: `NotificationClearEvent` / `NotificationClearCallback`, `DraftSyncEvent` / `DraftSyncCallback`.
 
 ### Notes
 
 - Both ride the existing `SyncFrame` wire type (own-device fan-out only, never delivered to a different user). No PROTOCOL_VERSION change.
-- Your app decides when to call `clearNotification()` / `syncDraft()` — the platform never infers dismissal or tracks drafts.
+- Your app decides when to call `clearNotification()` / `syncDraft()`. The platform never infers dismissal or tracks drafts.
 
 ---
 
@@ -259,13 +304,13 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ### Added
 
-- **Cross-device read receipts.** New `client.markRead(messageId, conversationId?)` reports a message as read; the receipt is relayed to the user's *other* devices (never to the message's sender). New `client.onReadReceipt(callback)` listens for receipts reported by the user's other devices — use it to clear unread state your app maintains.
+- **Cross-device read receipts.** New `client.markRead(messageId, conversationId?)` reports a message as read; the receipt is relayed to the user's *other* devices (never to the message's sender). New `client.onReadReceipt(callback)` listens for receipts reported by the user's other devices. Use it to clear unread state your app maintains.
 - New exported `ReadReceiptEvent` type and `ReadReceiptCallback`.
 - **PROTOCOL_VERSION bumped to 6.** Additive only: new `SyncFrame` wire type. Existing 0.10.x clients keep working against the new server.
 
 ### Notes
 
-- The platform is deliberately unopinionated: **your app decides when `markRead()` is called** — the server never infers read state, and unread counts stay client-side. The app owner can disable read receipts entirely from the dashboard, in which case the server silently drops the frame.
+- The platform is deliberately unopinionated: **your app decides when `markRead()` is called**. The server never infers read state, and unread counts stay client-side. The app owner can disable read receipts entirely from the dashboard, in which case the server silently drops the frame.
 - This release is own-device sync only: the *sender* of a message is not told when a recipient read it. Sender-side read notifications are a separate future capability.
 
 ---
@@ -274,7 +319,7 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ### Added
 
-- **Device trust.** New `client.listMyDevices()` returns the current user's registered devices; `client.revokeMyDevice(deviceId)` revokes one of them. A revoked device's live session is closed immediately and all future connections from it are denied (revoke is permanent — re-registering yields a fresh deviceId).
+- **Device trust.** New `client.listMyDevices()` returns the current user's registered devices; `client.revokeMyDevice(deviceId)` revokes one of them. A revoked device's live session is closed immediately and all future connections from it are denied (revoke is permanent, and re-registering yields a fresh deviceId).
 - **`DEVICE_REVOKED` event.** When this device is revoked (from another of the user's devices, or by the app owner), the SDK stops its reconnect loop, closes the socket, and surfaces a `DEVICE_REVOKED` event through `onEvent` so the app can clear local key storage and show a re-register prompt.
 - New exported `DeviceInfo` type.
 
@@ -326,7 +371,7 @@ This project follows [Semantic Versioning](https://semver.org/).
 ### Notes
 
 - Wire protocol unchanged (PROTOCOL_VERSION stays 4). The proto schema was already correct; only the JS hand-rolled codec was out of sync.
-- `protoFieldNumbers` for the group types are now documented in `droponair-sdk-shared/test-vectors/protobuf-vectors.json` for cross-platform reference.
+- `protoFieldNumbers` for the group types are now documented alongside the shared protocol test vectors, for cross-platform reference.
 
 ---
 
@@ -395,9 +440,8 @@ This project follows [Semantic Versioning](https://semver.org/).
   `getDisplayMedia()` (web) / `MediaProjection` (Android) / `ReplayKit` (iOS)
   in the app, add the track to the existing peer connection, then call
   `startScreenShare(...)` to notify the peer.
-- Plan gate: `screen_sharing` is enabled on PRO/GROWTH/PAYG/ENTERPRISE and
-  disabled on FREE. Check `subscription.featuresEnabled.screen_sharing` (server
-  side, on the customer's backend).
+- Availability depends on the app's plan; see the pricing page or the app's
+  subscription in the dashboard.
 
 ---
 
@@ -468,7 +512,7 @@ This project follows [Semantic Versioning](https://semver.org/).
 ### Added
 - **SDK versioning infrastructure:** `SDK_VERSION`, `PROTOCOL_VERSION`, and `PAYLOAD_FORMAT_VERSION` exported from `src/version.ts`
 - **Version telemetry:** `X-SDK-Version` header sent on token exchange; `sdkVersion` and `protocolVersion` query params on WebSocket handshake
-- **Server info endpoint:** SDK-BE now exposes `GET /api/info` (no auth) returning `protocolVersion`, `minSdkVersion`, and supported `features`
+- **Server info endpoint:** the platform now exposes `GET /api/info` (no auth) returning `protocolVersion`, `minSdkVersion`, and supported `features`
 - **Multi-device E2EE:** Per-device encrypted payloads (`devicePayloads[]` in Envelope proto), sender encrypts once per recipient device + self-sync to own other devices
 - **Self-sync:** Sent messages are encrypted for the sender's other devices so all devices see the conversation in real time
 - **Legacy fallback:** When recipient has no device keys, SDK falls back to single `encryptedPayload` path for backward compat with older clients

package/README.md

@@ -154,7 +154,7 @@ unchanged, so peers still address the same identity and existing conversations k
 
 ### Cross-device read receipts
 
-Available since SDK `0.11.0`. **Your app decides when a message is read** — the platform never infers it. Call `markRead()` at that moment; the receipt syncs to the user's *other* devices so they can clear their unread UI. It is not sent to the message's sender. The app owner can switch read receipts off entirely from the dashboard.
+Available since SDK `0.11.0`. **Your app decides when a message is read**, and the platform never infers it. Call `markRead()` at that moment; the receipt syncs to the user's *other* devices so they can clear their unread UI. It is not sent to the message's sender. The app owner can switch read receipts off entirely from the dashboard.
 
 ```typescript
 // When your UI decides the message has been read
@@ -162,11 +162,11 @@ client.markRead(messageId, peerUserId);
 
 // On the user's other devices
 client.onReadReceipt(e => {
-  // e.messageId was read elsewhere — clear your unread state for it
+  // e.messageId was read elsewhere, so clear your unread state for it
 });
 ```
 
-**Group read receipts.** Since SDK `0.13.0`, a group can opt into sharing read receipts with every member. Call `updateGroup(groupId, { readReceiptsVisibleToGroup: true })` (owner/admin); after that, a member's `markRead()` on a group message is broadcast to every other member, and `onReadReceipt` fires with `e.fromUserId` set to the member who read it. It is **opt-in per group** — the platform never enables it for you, and it has no effect unless read receipts are also enabled for your app.
+**Group read receipts.** Since SDK `0.13.0`, a group can opt into sharing read receipts with every member. Call `updateGroup(groupId, { readReceiptsVisibleToGroup: true })` (owner/admin); after that, a member's `markRead()` on a group message is broadcast to every other member, and `onReadReceipt` fires with `e.fromUserId` set to the member who read it. It is **opt-in per group**. The platform never enables it for you, and it has no effect unless read receipts are also enabled for your app.
 
 ```typescript
 await client.updateGroup(groupId, { readReceiptsVisibleToGroup: true });
@@ -178,7 +178,7 @@ client.onReadReceipt(e => {
 
 ### Notification clear & draft sync
 
-Available since SDK `0.12.0`, both own-device only. `clearNotification()` tells your user's other devices a conversation's notifications were dismissed — always available. `syncDraft()` pushes a draft so the user can keep typing on another device — **opt-in** (the app owner enables it in the dashboard) and the draft text crosses the relay in cleartext.
+Available since SDK `0.12.0`, both own-device only. `clearNotification()` tells your user's other devices a conversation's notifications were dismissed, and is always available. `syncDraft()` pushes a draft so the user can keep typing on another device, and is **opt-in** (the app owner enables it in the dashboard) and the draft text crosses the relay in cleartext.
 
 ```typescript
 client.clearNotification(conversationId);
@@ -190,7 +190,7 @@ client.onDraftSync(e => { /* pre-fill composer with e.draftText */ });
 
 ### Device trust
 
-Available since SDK `0.10.0`. Any device that completes a connection is implicitly trusted. `listMyDevices()` powers a "Your devices" screen; `revokeMyDevice()` cuts a device off immediately. When the *current* device is revoked, the SDK stops reconnecting and emits a `DEVICE_REVOKED` event via `onEvent` — listen for it to clear local key storage and prompt re-registration.
+Available since SDK `0.10.0`. Any device that completes a connection is implicitly trusted. `listMyDevices()` powers a "Your devices" screen; `revokeMyDevice()` cuts a device off immediately. When the *current* device is revoked, the SDK stops reconnecting and emits a `DEVICE_REVOKED` event via `onEvent`. Listen for it to clear local key storage and prompt re-registration.
 
 ```typescript
 const devices = await client.listMyDevices();
@@ -224,6 +224,45 @@ await client.registerPushToken({ platform: 'WEB_PUSH', token: JSON.stringify(sub
 await client.unregisterPushToken({ platform: 'APNS' });
 ```
 
+#### Attaching a payload
+
+A push is only sent when the sender attaches a payload, so set a default once and
+every message carries it. Passing one on each send also works, but forgetting once
+stops push with no error to notice.
+
+```typescript
+const client = await initialize({
+  appId, publicApiKey, getUserJwt,
+  defaultPushPayload: { title: 'New message', delivery: 'mutable' },
+});
+
+// Override for a single message
+await client.sendMessage(userId, text, {
+  push: { title: 'New photo', delivery: 'mutable', threadId: conversationId },
+});
+```
+
+#### Choosing how the push behaves
+
+`delivery` says what the recipient's device should do. The platform translates it
+per transport, so you pick what suits your app rather than adopting somebody else's
+model.
+
+| `delivery` | What happens |
+| --- | --- |
+| `'alert'` | Title and body are shown exactly as supplied. Suits apps sending cleartext. |
+| `'mutable'` | Shown as a placeholder, then your app replaces the text before it appears. This is how an end-to-end encrypted app shows real content without the relay seeing it. On iOS it needs a notification service extension; on Android it arrives as a data message. |
+| `'silent'` | The app is woken and nothing is shown. **iOS throttles these and does not guarantee delivery**, so use `'mutable'` when being woken matters. |
+| `'voip'` | Call invite: PushKit on iOS, high priority data on Android. Requires a registered VoIP token. |
+
+Omit `delivery` and it defaults to `'alert'`.
+
+**Never put message content in `title` or `body`.** Every field in the payload is
+readable by the relay, which is exactly why it can act on them, so putting plaintext
+there leaks it through the one path that otherwise never sees it. Send a placeholder
+and use `'mutable'` to replace it on the device.
+
+
 E2EE invariant: the push body is sender-supplied cleartext metadata only (e.g. "1 new message from Alice"), never the encrypted message contents. The recipient SDK decrypts the real message after the push wakes the device and the WebSocket reconnects.
 
 ### Message Edit & Delete
@@ -479,7 +518,7 @@ await wt.connect();
 await wt.sendEnvelope(envelopeBytes);
 ```
 
-Uses the browser-native `WebTransport` API; opens a single bidirectional stream and rides raw bytes both ways. Browser support: Chromium 97+ (stable), Firefox 125+ (stable), Safari Technology Preview only, Node 22+ behind experimental flags. The `droponair.com` endpoint advertises `transports: ["webtransport"]` only when the `droponair-webtransport` sidecar is live; check `GET /api/info.transports` and `features.transport_webtransport` to detect availability. Bring your own protobuf decoder. WebSocket remains the default; this primitive is purely opt-in.
+Uses the browser-native `WebTransport` API; opens a single bidirectional stream and rides raw bytes both ways. Browser support: Chromium 97+ (stable), Firefox 125+ (stable), Safari Technology Preview only, Node 22+ behind experimental flags. The endpoint advertises `transports: ["webtransport"]` only where the lane is available; check `GET /api/info.transports` and `features.transport_webtransport` to detect it. Bring your own protobuf decoder. WebSocket remains the default; this primitive is purely opt-in.
 
 ### Transport auto-select
 
@@ -500,7 +539,7 @@ Foundation for an `init({ transport: 'auto' })` shortcut once full `MessagingCli
 
 ### Call Recording
 
-Available since SDK `0.16.0`. The SDK **signals** recording state on a group or room call; your app does the actual media capture (`MediaRecorder`) and uploads the file to your own storage — the platform never holds the media. The recording signal is broadcast to every participant (including anyone who joins later); that transparency is enforced server-side.
+Available since SDK `0.16.0`. The SDK **signals** recording state on a group or room call; your app does the actual media capture (`MediaRecorder`) and uploads the file to your own storage. The platform never holds the media. The recording signal is broadcast to every participant (including anyone who joins later); that transparency is enforced server-side.
 
 | Method | Description |
 |--------|-------------|

package/dist/attachment/attachment-client.d.ts

@@ -44,7 +44,7 @@ export declare class AttachmentClient {
      */
     prepareAttachmentAndUpload(input: Uint8Array, opts: PrepareAttachmentOptions): Promise<AttachmentRef>;
     /**
-     * Revoke an attachment you sent (Phase 2f). After revoke the platform
+     * Revoke an attachment you sent. After revoke the platform
      * refuses to issue further download URLs and recipients with a live
      * connection get an ATTACHMENT_REVOKED event. Bytes a recipient already
      * downloaded cannot be recalled.

package/dist/attachment/attachment-client.js

@@ -147,7 +147,7 @@ class AttachmentClient {
         };
     }
     /**
-     * Revoke an attachment you sent (Phase 2f). After revoke the platform
+     * Revoke an attachment you sent. After revoke the platform
      * refuses to issue further download URLs and recipients with a live
      * connection get an ATTACHMENT_REVOKED event. Bytes a recipient already
      * downloaded cannot be recalled.

package/dist/core/messaging-client.d.ts

@@ -1,6 +1,6 @@
 import { CryptoService } from '../crypto/crypto-service';
 import { SessionManager } from './session-manager';
-import { BroadcastCallback, CallEventCallback, DropOnAirClient, EventCallback, CreateRoomOptions, GroupCallEventCallback, GroupInfo, GroupMessageCallback, Room, UpdateRoomOptions, SfuToken, SfuRecording, InitializeOptions, MessageCallback, MessageDeleteCallback, MessageEditCallback, TurnCredentials, DeviceInfo, ReadReceiptCallback, NotificationClearCallback, DraftSyncCallback, KeyCustody } from './types';
+import { BroadcastCallback, CallEventCallback, DropOnAirClient, EventCallback, CreateRoomOptions, GroupCallEventCallback, GroupInfo, GroupMessageCallback, Room, UpdateRoomOptions, SfuToken, SfuRecording, InitializeOptions, MessageCallback, MessageDeleteCallback, MessageEditCallback, TurnCredentials, DeviceInfo, ReadReceiptCallback, NotificationClearCallback, DraftSyncCallback, KeyCustody, PushPayload } from './types';
 import { AttachmentRef, CreateUploadSessionOptions, DownloadedAttachment, PrepareAttachmentOptions, UploadSession } from '../attachment/attachment-types';
 export declare class MessagingClient implements DropOnAirClient {
     private readonly options;
@@ -11,6 +11,7 @@ export declare class MessagingClient implements DropOnAirClient {
     private readonly httpUrl;
     private readonly tokenExchangeEndpoint;
     private readonly keyDirectoryEndpoint;
+    private readonly defaultPushPayload?;
     private readonly fetchFn;
     private readonly codec;
     private attachmentClient;
@@ -29,6 +30,12 @@ export declare class MessagingClient implements DropOnAirClient {
     private visibilityChangeHandler;
     private readonly autoAckIncomingMessages;
     private static readonly DEVICE_KEYS_CACHE_TTL_MS;
+    /**
+     * Resolves the payload for a send: what the caller passed, otherwise the
+     * client default, otherwise none at all. Returns undefined when there is
+     * nothing to send, so no push is requested rather than an empty one.
+     */
+    private resolvePushPayload;
     private readonly deviceKeysCache;
     private readonly callListeners;
     /** Pending startCall resolver, only one outgoing call can be in-flight at a time. */
@@ -39,7 +46,7 @@ export declare class MessagingClient implements DropOnAirClient {
     /** Pending startGroupCall resolver. */
     private pendingGroupInviteResolve;
     private pendingGroupInviteReject;
-    /** Pending joinRoom resolver (Feature 3.1), keyed by roomId. */
+    /** Pending joinRoom resolver, keyed by roomId. */
     private readonly pendingRoomJoins;
     private reconnectDelayMs;
     /** Schedule a single reconnect, replacing any pending one (never stack timers). */
@@ -112,6 +119,7 @@ export declare class MessagingClient implements DropOnAirClient {
     sendMessage(toUserId: string, plaintextMessage: string, options?: {
         attachments?: AttachmentRef[];
         clientMessageId?: string;
+        push?: PushPayload;
     }): Promise<{
         messageId: string;
     }>;
@@ -238,7 +246,7 @@ export declare class MessagingClient implements DropOnAirClient {
     getGroup(groupId: string): Promise<GroupInfo>;
     /**
      * Update a group. Any omitted field is left unchanged. `readReceiptsVisibleToGroup`
-     * (Phase 2e) controls whether members' group read receipts are visible to
+     * controls whether members' group read receipts are visible to
      * the whole group or stay own-device only.
      */
     updateGroup(groupId: string, update: {
@@ -282,6 +290,7 @@ export declare class MessagingClient implements DropOnAirClient {
      */
     sendGroupMessage(groupId: string, plaintext: string, memberUserIds: string[], options?: {
         attachments?: AttachmentRef[];
+        push?: PushPayload;
     }): Promise<{
         messageId: string;
     }>;

package/dist/core/messaging-client.js

@@ -11,6 +11,30 @@ const version_1 = require("../version");
 const attachment_client_1 = require("../attachment/attachment-client");
 const STORAGE_DEVICE_ID = 'droponair.device.id.v1';
 class MessagingClient {
+    /**
+     * Resolves the payload for a send: what the caller passed, otherwise the
+     * client default, otherwise none at all. Returns undefined when there is
+     * nothing to send, so no push is requested rather than an empty one.
+     */
+    resolvePushPayload(override) {
+        const payload = override ?? this.defaultPushPayload;
+        if (!payload)
+            return undefined;
+        const deliveryCodes = { alert: 0, mutable: 1, silent: 2, voip: 3 };
+        const delivery = deliveryCodes[payload.delivery ?? 'alert'] ?? 0;
+        return {
+            title: payload.title ?? '',
+            body: payload.body ?? '',
+            badge: payload.badge,
+            sound: payload.sound,
+            category: payload.category,
+            threadId: payload.threadId,
+            customJson: payload.customJson,
+            delivery,
+            // The server still reads the older boolean, so keep it consistent.
+            voip: delivery === 3 ? true : undefined,
+        };
+    }
     reconnectDelayMs() {
         // Exponential backoff with jitter: ~2s, 4s, 8s, 16s, 32s, 60s (capped), +/-20%.
         // Jitter avoids many clients reconnecting in lockstep after a server blip.
@@ -246,7 +270,7 @@ class MessagingClient {
         /** Pending startGroupCall resolver. */
         this.pendingGroupInviteResolve = null;
         this.pendingGroupInviteReject = null;
-        /** Pending joinRoom resolver (Feature 3.1), keyed by roomId. */
+        /** Pending joinRoom resolver, keyed by roomId. */
         this.pendingRoomJoins = new Map();
         this.messageListeners = new Set();
         this.eventListeners = new Set();
@@ -260,6 +284,7 @@ class MessagingClient {
         this.httpUrl = options.messagingHttpUrl ?? 'https://sdk.droponair.com';
         this.tokenExchangeEndpoint = options.tokenExchangeEndpoint ?? '/api/messaging/token-exchange';
         this.keyDirectoryEndpoint = options.keyDirectoryEndpoint ?? '/api/messaging/keys';
+        this.defaultPushPayload = options.defaultPushPayload;
         const providedFetch = options.fetchFn;
         const globalFetch = typeof globalThis !== 'undefined' ? globalThis.fetch : undefined;
         const resolvedFetch = providedFetch ?? globalFetch;
@@ -419,6 +444,7 @@ class MessagingClient {
             if (options?.attachments && options.attachments.length > 0) {
                 envelope.attachments = options.attachments.map(a => this.attachmentClient.toWire(a));
             }
+            envelope.pushPayload = this.resolvePushPayload(options?.push);
             this.sendFrame(this.codec.encodeEnvelope(envelope));
         }
         else {
@@ -442,6 +468,7 @@ class MessagingClient {
             if (options?.attachments && options.attachments.length > 0) {
                 envelope.attachments = options.attachments.map(a => this.attachmentClient.toWire(a));
             }
+            envelope.pushPayload = this.resolvePushPayload(options?.push);
             this.sendFrame(this.codec.encodeEnvelope(envelope));
         }
         return { messageId };
@@ -658,7 +685,7 @@ class MessagingClient {
         this.transport.send(this.codec.encodePushRegistrationFrame(frame));
     }
     // ---------------------------------------------------------------------------
-    // Device trust (PROTOCOL_VERSION 5+ / Phase 2b)
+    // Device trust (PROTOCOL_VERSION 5+)
     // ---------------------------------------------------------------------------
     /**
      * List the current user's registered devices. Each device is implicitly
@@ -711,7 +738,7 @@ class MessagingClient {
         }
     }
     // ---------------------------------------------------------------------------
-    // Cross-device read receipts (PROTOCOL_VERSION 6+ / Phase 2c)
+    // Cross-device read receipts (PROTOCOL_VERSION 6+)
     // ---------------------------------------------------------------------------
     /**
      * Mark a message as read. Call this when YOUR app decides a message has
@@ -950,7 +977,7 @@ class MessagingClient {
     }
     /**
      * Update a group. Any omitted field is left unchanged. `readReceiptsVisibleToGroup`
-     * (Phase 2e) controls whether members' group read receipts are visible to
+     * controls whether members' group read receipts are visible to
      * the whole group or stay own-device only.
      */
     async updateGroup(groupId, update) {
@@ -995,7 +1022,7 @@ class MessagingClient {
             throw new Error(`deleteGroup failed (HTTP ${res.status})`);
     }
     // ---------------------------------------------------------------------------
-    // Rooms (Feature 3.1 - scheduled & persistent meeting rooms)
+    // Rooms (scheduled & persistent meeting rooms)
     // ---------------------------------------------------------------------------
     async createRoom(options) {
         const jwt = await this.getValidDropOnAirJwt(false);
@@ -1223,6 +1250,7 @@ class MessagingClient {
             encryptionType: 0, // E2EE
             memberPayloads,
         };
+        frame.pushPayload = this.resolvePushPayload(options?.push);
         if (options?.attachments && options.attachments.length > 0) {
             frame.attachments = options.attachments.map(a => this.attachmentClient.toWire(a));
         }
@@ -1325,7 +1353,7 @@ class MessagingClient {
         return () => this.groupCallListeners.delete(callback);
     }
     // Group call moderation + waiting room. The server validates host/co-host
-    // authority and the `featuresEnabled.moderation` plan flag; on denial it
+    // authority and whether moderation is available on the app's plan; on denial it
     // emits a LIMIT_REACHED event with reason="MODERATION_NOT_ENABLED".
     transferHost(callId, groupId, newHostUserId) {
         this.sendGroupCallFrame({
@@ -1399,7 +1427,7 @@ class MessagingClient {
             payload: JSON.stringify({ userId }),
         });
     }
-    // Live stage controls (Feature 3.2). These act on a room call running in
+    // Live stage controls. These act on a room call running in
     // stage mode; pass the callId from joinRoom(). raiseHand / lowerHand and
     // submitStageQuestion are open to any participant; promote / demote are
     // host / co-host authority. Roles surface via GROUP_CALL_ROLE_CHANGED.
@@ -1428,7 +1456,7 @@ class MessagingClient {
     submitStageQuestion(callId, text) {
         this.sendGroupCallFrame({ type: 'GROUP_CALL_STAGE_QUESTION', callId, groupId: '', payload: text });
     }
-    // Call recording (Feature 3.5a). These SIGNAL recording state; the actual
+    // Call recording. These SIGNAL recording state; the actual
     // media capture + upload to your storage is your app's job (same split as
     // screen sharing). The platform broadcasts the signal to every participant.
     startRecording(callId) {
@@ -1589,7 +1617,7 @@ class MessagingClient {
                 plaintext = await this.cryptoService.decrypt(myPayload.encryptedPayload, sharedKey, {
                     messageId: notif.messageId,
                     senderId: notif.fromUserId,
-                    // AAD recipientId is the receiving user's own id — this MUST match the
+                    // AAD recipientId is the receiving user's own id, and this MUST match the
                     // sender's encrypt AAD, which binds recipientId to the target member's
                     // userId (memberId). Using notif.groupId here (the previous value) never
                     // matched, so E2EE group messages failed GCM auth on decrypt. android /
@@ -1634,7 +1662,7 @@ class MessagingClient {
             this.pendingGroupInviteReject = null;
             reject(new Error(`GROUP_CALL_ALREADY_ACTIVE:${wire.payload ?? ''}`));
         }
-        // Resolve / reject a pending joinRoom() (Feature 3.1). Room-call frames
+        // Resolve / reject a pending joinRoom(). Room-call frames
         // carry roomId; the join outcome is one of these four types.
         if (wire.roomId) {
             const pending = this.pendingRoomJoins.get(wire.roomId);

package/dist/core/types.d.ts

@@ -1,3 +1,46 @@
+/**
+ * How a push should behave on the recipient's device.
+ *
+ * The platform translates this per transport; it does not decide for you. Pick
+ * the one that matches your app, not the one that matches ours.
+ */
+export type PushDelivery = 
+/** Show title and body exactly as supplied. Suits apps sending cleartext. */
+'alert'
+/**
+ * Show them as a placeholder, then replace the text on the device before it
+ * appears. This is how an end-to-end encrypted app shows real content on a
+ * lock screen without the relay ever seeing it. On iOS it is also the reliable
+ * way to be woken, because silent pushes are throttled by the system.
+ */
+ | 'mutable'
+/** Wake the app, show nothing. Delivery is not guaranteed on iOS. */
+ | 'silent'
+/** Call invite. PushKit on iOS, high priority data on Android. */
+ | 'voip';
+/**
+ * Cleartext metadata that wakes a recipient's device when they have no live
+ * connection.
+ *
+ * Every field here is readable by the relay, which is precisely why it can act on
+ * them. Never put message content in `title` or `body`: it would leak through the
+ * one path the platform promises never sees it. A placeholder such as
+ * "New message" is the point, and `mutable` lets the device replace it.
+ */
+export interface PushPayload {
+    title?: string;
+    body?: string;
+    badge?: number;
+    sound?: string;
+    /** iOS UNNotificationCategory, Android channel id. */
+    category?: string;
+    /** Groups related notifications together. */
+    threadId?: string;
+    /** App-defined JSON passed through to the provider payload untouched. */
+    customJson?: string;
+    /** Defaults to 'alert'. */
+    delivery?: PushDelivery;
+}
 export type DropOnAirEventType = 'SERVER_RECEIVED' | 'DELIVERED' | 'PROCESSED' | 'LIMIT_REACHED' | 'IMPERSONATION_DETECTED' | 'ERROR' | 'CONNECTED' | 'DISCONNECTED' | 'RECONNECTING';
 export interface DropOnAirEvent {
     type: DropOnAirEventType | string;
@@ -117,7 +160,7 @@ export interface GroupInfo {
     members: GroupMemberInfo[];
     createdAt: number;
     /**
-     * Phase 2e. When true, a member's group read receipt is fanned to all other
+     * When true, a member's group read receipt is fanned to all other
      * members; when false it stays own-device only. Controlled via updateGroup().
      */
     readReceiptsVisibleToGroup?: boolean;
@@ -140,7 +183,7 @@ export interface GroupCallEvent {
     type: GroupCallEventType | string;
     callId: string;
     groupId: string;
-    /** Set instead of groupId when the event belongs to a room call (Feature 3.1). */
+    /** Set instead of groupId when the event belongs to a room call. */
     roomId?: string;
     targetUserId?: string;
     payload?: string;
@@ -160,7 +203,7 @@ export interface RoomPolicy {
     /** When true, the room flips to CLOSED once the last participant leaves the call. */
     autoCloseWhenEmpty?: boolean;
     /**
-     * When true, the room's live call runs in stage mode (Feature 3.2): hosts
+     * When true, the room's live call runs in stage mode: hosts
      * join as speakers, everyone else as receive-only audience who can raise a
      * hand to be promoted. Mesh-scale - suited to panels and small stages.
      */
@@ -191,7 +234,7 @@ export interface SfuToken {
     expiresAt: number;
 }
 /**
- * A server-side recording of an SFU-mode room (Phase 3.7.5). The platform
+ * A server-side recording of an SFU-mode room. The platform
  * never holds the recorded bytes - LiveKit Egress uploads the finalized file
  * directly to the destination configured in the panel under `destinationId`.
  */
@@ -311,6 +354,14 @@ export interface InitializeOptions {
     messagingHttpUrl?: string;
     tokenExchangeEndpoint?: string;
     keyDirectoryEndpoint?: string;
+    /**
+     * Attached to every message that does not carry its own.
+     *
+     * Set this once and push works; the alternative is remembering to pass a
+     * payload on every send, where forgetting once means push silently stops with
+     * no error to notice. Omit it entirely and no push is ever requested.
+     */
+    defaultPushPayload?: PushPayload;
     fetchFn?: typeof fetch;
     storage?: KeyStorageAdapter;
     /**
@@ -395,6 +446,8 @@ export interface DropOnAirClient {
     sendMessage(toUserId: string, plaintextMessage: string, options?: {
         attachments?: import('../attachment/attachment-types').AttachmentRef[];
         clientMessageId?: string;
+        /** Overrides `defaultPushPayload` for this message. */
+        push?: PushPayload;
     }): Promise<{
         messageId: string;
     }>;
@@ -565,6 +618,8 @@ export interface DropOnAirClient {
      */
     sendGroupMessage(groupId: string, plaintext: string, memberUserIds: string[], options?: {
         attachments?: import('../attachment/attachment-types').AttachmentRef[];
+        /** Overrides `defaultPushPayload` for this message. */
+        push?: PushPayload;
     }): Promise<{
         messageId: string;
     }>;

package/dist/index.js

@@ -59,13 +59,13 @@ async function initialize(options) {
     }
     return client;
 }
-// Phase 4.2.1: HTTP fallback lane primitive for restrictive networks.
+// HTTP fallback lane primitive for restrictive networks.
 var sse_transport_1 = require("./transport/sse-transport");
 Object.defineProperty(exports, "SseTransport", { enumerable: true, get: function () { return sse_transport_1.SseTransport; } });
-// Phase 4.3: WebTransport (HTTP/3) lane primitive.
+// WebTransport (HTTP/3) lane primitive.
 var webtransport_transport_1 = require("./transport/webtransport-transport");
 Object.defineProperty(exports, "WebTransportTransport", { enumerable: true, get: function () { return webtransport_transport_1.WebTransportTransport; } });
-// Phase 4.6: transport auto-select - intersects runtime + platform support.
+// transport auto-select - intersects runtime + platform support.
 var auto_select_1 = require("./transport/auto-select");
 Object.defineProperty(exports, "selectTransport", { enumerable: true, get: function () { return auto_select_1.selectTransport; } });
 /**

package/dist/transport/auto-select.d.ts

@@ -1,5 +1,5 @@
 /**
- * Transport auto-select (Phase 4.6).
+ * Transport auto-select.
  *
  * Tiny helper that probes which transport lanes the runtime AND the platform
  * BOTH support, and returns the best one for this client/host pair.

package/dist/transport/auto-select.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * Transport auto-select (Phase 4.6).
+ * Transport auto-select.
  *
  * Tiny helper that probes which transport lanes the runtime AND the platform
  * BOTH support, and returns the best one for this client/host pair.

package/dist/transport/protobuf-codec.d.ts

@@ -22,6 +22,26 @@ export interface WireAttachmentRef {
     wrappedKeys?: WireDeviceWrappedKey[];
     thumbnailAttachmentId?: string;
 }
+/**
+ * Cleartext metadata that wakes a recipient's device. Never message content: the
+ * relay can read every field here, which is the whole reason it can act on them.
+ *
+ * `delivery` says how the device should treat the push. The platform translates
+ * it per transport rather than deciding for the app.
+ */
+export interface WirePushPayload {
+    title?: string;
+    body?: string;
+    badge?: number;
+    sound?: string;
+    category?: string;
+    threadId?: string;
+    customJson?: string;
+    /** Superseded by `delivery: 3`; still honoured by the server. */
+    voip?: boolean;
+    /** 0 ALERT, 1 MUTABLE, 2 SILENT, 3 VOIP. */
+    delivery?: number;
+}
 export interface WireEnvelope {
     messageId: string;
     appId: string;
@@ -40,6 +60,8 @@ export interface WireEnvelope {
     plaintextPayload?: string;
     /** Zero or more attachment pointers (PROTOCOL_VERSION 4+). */
     attachments?: WireAttachmentRef[];
+    /** Wakes the recipient when they have no live session (PROTOCOL_VERSION 5+). */
+    pushPayload?: WirePushPayload;
 }
 export interface WireAck {
     messageId: string;
@@ -93,6 +115,8 @@ export interface WireGroupEnvelope {
     plaintextPayload?: string;
     memberPayloads: WireGroupMemberPayload[];
     attachments?: WireAttachmentRef[];
+    /** Wakes offline members (PROTOCOL_VERSION 5+). */
+    pushPayload?: WirePushPayload;
 }
 export interface WireGroupMessageNotification {
     messageId: string;
@@ -116,7 +140,7 @@ export interface WireGroupCallFrame {
     groupId: string;
     targetUserId?: string;
     payload?: string;
-    /** Set instead of groupId when the multi-party call belongs to a Room (Feature 3.1). */
+    /** Set instead of groupId when the multi-party call belongs to a Room. */
     roomId?: string;
 }
 /**

package/dist/transport/protobuf-codec.js

@@ -70,10 +70,29 @@ function buildAttachmentRefType() {
         .add(new protobuf.Field('wrappedKeys', 7, 'DeviceWrappedKey', 'repeated'))
         .add(new protobuf.Field('thumbnailAttachmentId', 8, 'string'));
 }
+// Same rule as AttachmentRef above: Envelope and GroupEnvelope each nest
+// PushPayload, so each needs its own instance. Sharing one would re-parent it
+// onto whichever added it last and orphan it from the other, which is how the
+// AttachmentRef outage happened. The Delivery enum nests inside it and is
+// rebuilt per call for the same reason.
+function buildPushPayloadType() {
+    return new protobuf.Type('PushPayload')
+        .add(new protobuf.Enum('Delivery', { ALERT: 0, MUTABLE: 1, SILENT: 2, VOIP: 3 }))
+        .add(new protobuf.Field('title', 1, 'string'))
+        .add(new protobuf.Field('body', 2, 'string'))
+        .add(new protobuf.Field('badge', 3, 'int32'))
+        .add(new protobuf.Field('sound', 4, 'string'))
+        .add(new protobuf.Field('category', 5, 'string'))
+        .add(new protobuf.Field('threadId', 6, 'string'))
+        .add(new protobuf.Field('customJson', 7, 'string'))
+        .add(new protobuf.Field('voip', 8, 'bool'))
+        .add(new protobuf.Field('delivery', 9, 'Delivery'));
+}
 const EnvelopeType = new protobuf.Type('Envelope')
     .add(EncryptionTypeEnum)
     .add(DeviceEncryptedPayloadType) // nested type must be added first
     .add(buildAttachmentRefType())
+    .add(buildPushPayloadType())
     .add(new protobuf.Field('messageId', 1, 'string'))
     .add(new protobuf.Field('appId', 2, 'string'))
     .add(new protobuf.Field('fromUserId', 3, 'string'))
@@ -85,7 +104,8 @@ const EnvelopeType = new protobuf.Type('Envelope')
     .add(new protobuf.Field('senderDeviceId', 9, 'string'))
     .add(new protobuf.Field('encryptionType', 10, 'EncryptionType'))
     .add(new protobuf.Field('plaintextPayload', 11, 'string'))
-    .add(new protobuf.Field('attachments', 12, 'AttachmentRef', 'repeated'));
+    .add(new protobuf.Field('attachments', 12, 'AttachmentRef', 'repeated'))
+    .add(new protobuf.Field('pushPayload', 13, 'PushPayload'));
 const AckType = new protobuf.Type('Ack')
     .add(new protobuf.Field('messageId', 1, 'string'))
     .add(new protobuf.Field('type', 2, 'string'));
@@ -138,6 +158,7 @@ const GroupEnvelopeType = new protobuf.Type('GroupEnvelope')
     .add(GroupEnvelopeEncryptionTypeEnum)
     .add(GroupMemberPayloadType)
     .add(buildAttachmentRefType())
+    .add(buildPushPayloadType())
     .add(new protobuf.Field('messageId', 1, 'string'))
     .add(new protobuf.Field('appId', 2, 'string'))
     .add(new protobuf.Field('groupId', 3, 'string'))
@@ -149,7 +170,8 @@ const GroupEnvelopeType = new protobuf.Type('GroupEnvelope')
     .add(new protobuf.Field('plaintextPayload', 9, 'string'))
     .add(new protobuf.Field('memberPayloads', 10, 'GroupMemberPayload', 'repeated'))
     // field 11 reserved upstream
-    .add(new protobuf.Field('attachments', 12, 'AttachmentRef', 'repeated'));
+    .add(new protobuf.Field('attachments', 12, 'AttachmentRef', 'repeated'))
+    .add(new protobuf.Field('pushPayload', 13, 'PushPayload'));
 const GroupNotifEncryptionTypeEnum = new protobuf.Enum('EncryptionType', { E2EE: 0, CLEARTEXT: 1 });
 const GroupNotifDeviceType = new protobuf.Type('DeviceEncryptedPayload')
     .add(new protobuf.Field('deviceId', 1, 'string'))
@@ -404,7 +426,7 @@ class ProtobufCodec {
             // Event.type is a SCREAMING_SNAKE_CASE enum string (e.g. LIMIT_REACHED).
             // A GroupMessageNotification, BroadcastNotification, or Ack decoded here
             // carries a UUID (messageId / broadcastId) in field 1, which never matches
-            // this shape — so this reliably rejects those overlapping frame types and
+            // this shape, so this reliably rejects those overlapping frame types and
             // lets Event be probed before them.
             if (!decoded.type || !/^[A-Z][A-Z0-9_]*$/.test(decoded.type)) {
                 return null;

package/dist/transport/sse-transport.d.ts

@@ -1,5 +1,5 @@
 /**
- * SSE-lane primitive (Phase 4.2.1 v1).
+ * SSE-lane primitive.
  *
  * Standalone client for the platform's HTTP fallback transport
  * (`GET /v1/transport/stream` for receive, `POST /v1/transport/send` for

package/dist/transport/sse-transport.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * SSE-lane primitive (Phase 4.2.1 v1).
+ * SSE-lane primitive.
  *
  * Standalone client for the platform's HTTP fallback transport
  * (`GET /v1/transport/stream` for receive, `POST /v1/transport/send` for

package/dist/transport/webtransport-transport.d.ts

@@ -1,8 +1,8 @@
 /**
- * WebTransport (HTTP/3) lane primitive (Phase 4.3).
+ * WebTransport (HTTP/3) lane primitive.
  *
- * Standalone client for the platform's WebTransport endpoint, terminated by
- * the `droponair-webtransport` Go sidecar and bridged into sdk-be `/ws`.
+ * Standalone client for the platform's WebTransport endpoint, which carries
+ * the same session as the WebSocket lane.
  * Browser-native `WebTransport` API; no polyfill ships with the SDK.
  *
  * Browser support as of 2026-05:

package/dist/transport/webtransport-transport.js

@@ -1,9 +1,9 @@
 "use strict";
 /**
- * WebTransport (HTTP/3) lane primitive (Phase 4.3).
+ * WebTransport (HTTP/3) lane primitive.
  *
- * Standalone client for the platform's WebTransport endpoint, terminated by
- * the `droponair-webtransport` Go sidecar and bridged into sdk-be `/ws`.
+ * Standalone client for the platform's WebTransport endpoint, which carries
+ * the same session as the WebSocket lane.
  * Browser-native `WebTransport` API; no polyfill ships with the SDK.
  *
  * Browser support as of 2026-05:

package/dist/version.d.ts

@@ -7,7 +7,7 @@
  *   MINOR, additive feature (e.g. multi-device payloads, new call event type)
  *   PATCH, bug-fix / perf improvement with no wire or API change
  */
-export declare const SDK_VERSION = "0.25.0";
+export declare const SDK_VERSION = "0.26.0";
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can

package/dist/version.js

@@ -10,7 +10,7 @@ exports.PROTOCOL_VERSION = exports.PAYLOAD_FORMAT_VERSION = exports.SDK_VERSION
  *   MINOR, additive feature (e.g. multi-device payloads, new call event type)
  *   PATCH, bug-fix / perf improvement with no wire or API change
  */
-exports.SDK_VERSION = '0.25.0';
+exports.SDK_VERSION = '0.26.0';
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@droponair/sdk-js",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "End-to-end encrypted messaging, voice and video calling SDK. The relay never sees your keys or message content.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",