@droponair/sdk-js 0.25.1 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # 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
@@ -483,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

@@ -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

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. */
@@ -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;
     }>;
@@ -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.
@@ -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 };
@@ -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));
         }

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;
@@ -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/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;

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'))

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.1";
+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.1';
+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.1",
+  "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",