@droponair/sdk-js 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -6,6 +6,28 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.9.1], 2026-05-19
+
+### Fixed
+
+- **`registerPushToken` / `unregisterPushToken` now exposed on the public `DropOnAirClient` type.** In 0.9.0 the methods were implemented on the `MessagingClient` class but missing from the exported `DropOnAirClient` interface, so TypeScript consumers couldn't call them through the `initialize()` return value. No wire-format change; this is a pure type-surface fix.
+
+---
+
+## [0.9.0], 2026-05-19
+
+### Added
+
+- **Push notification token registration.** New `client.registerPushToken({ platform, token, voipToken? })` and `client.unregisterPushToken({ platform })` methods. The platform delivers a push via APNs (iOS), FCM v1 (Android), or VAPID/Web Push (browser) whenever a sender supplies a `pushPayload` on a message and the recipient device has no live WebSocket session. The token is opaque to the server. For iOS VoIP/CallKit pushes, pass `voipToken` alongside the regular APNs token.
+- **PROTOCOL_VERSION bumped to 5.** Additive only: new optional `pushPayload` field on `Envelope`, `GroupEnvelope`, `CallFrame`, `GroupCallFrame`; new `PushRegistrationFrame` for token registration. Existing 0.8.x clients keep working against the new server (proto3 ignores unknown fields).
+
+### Notes
+
+- E2EE invariant preserved: the push body is sender-supplied cleartext metadata only ("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.
+- Customers configure their own APNs (.p8 + Team/Key/Bundle IDs), FCM service-account JSON, and VAPID keypair via the dashboard. Per-app, not per-environment; use two apps for dev/prod separation.
+
+---
+
 ## [0.8.0], 2026-05-19
 
 ### BREAKING

package/README.md

@@ -96,6 +96,31 @@ const client = await initialize(options);
 | `onMessageDelete(callback)` | `() => void` | Listen for inbound delete tombstones for 1:1 messages |
 | `onEvent(callback)` | `() => void` | Listen for system events (CONNECTED, DELIVERED, ERROR, etc.) |
 | `ack(messageId)` | `Promise<void>` | Manually acknowledge a message |
+| `registerPushToken({ platform, token, voipToken? })` | `Promise<void>` | Register this device for push notifications. `platform` is `'APNS'`, `'FCM'`, or `'WEB_PUSH'`. |
+| `unregisterPushToken({ platform })` | `Promise<void>` | Unregister this device for push notifications (e.g. on logout). |
+
+### Push notifications
+
+Available since SDK `0.9.0`. Customers configure their own APNs / FCM / VAPID credentials in the dashboard. The platform delivers a push only when the sender attaches a `pushPayload` to a message and the recipient device has no live WebSocket session. See the per-product availability and limits on your dashboard's Subscription page.
+
+```typescript
+// iOS, after didRegisterForRemoteNotificationsWithDeviceToken
+await client.registerPushToken({ platform: 'APNS', token: deviceTokenHex });
+
+// iOS + PushKit/CallKit (VoIP)
+await client.registerPushToken({ platform: 'APNS', token: deviceTokenHex, voipToken: voipTokenHex });
+
+// Android, after FirebaseMessaging.getInstance().token
+await client.registerPushToken({ platform: 'FCM', token: fcmToken });
+
+// Browser, the token is the JSON returned by PushManager.subscribe()
+await client.registerPushToken({ platform: 'WEB_PUSH', token: JSON.stringify(subscription) });
+
+// On logout
+await client.unregisterPushToken({ platform: 'APNS' });
+```
+
+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

@@ -111,6 +111,31 @@ export declare class MessagingClient implements DropOnAirClient {
     deleteMessage(originalMessageId: string, toUserId: string, scope: 'FOR_EVERYONE' | 'FOR_ME'): Promise<{
         deleteId: string;
     }>;
+    /**
+     * Register this device's push notification token with the DropOnAir platform.
+     * The token is opaque to the server; the platform fans out push notifications
+     * via the customer's APNs / FCM / VAPID credentials when a sender attaches a
+     * pushPayload to a message and the recipient is offline.
+     *
+     * For iOS apps using VoIP push (PushKit), pass {@code voipToken} alongside the
+     * regular APNs token. The platform will route CALL_INVITE pushes via the VoIP
+     * token and message pushes via the regular token.
+     *
+     * Idempotent: calling twice with the same (platform, deviceId) upserts the
+     * stored token and refreshes its lastSeenAt timestamp.
+     */
+    registerPushToken(opts: {
+        platform: 'APNS' | 'FCM' | 'WEB_PUSH';
+        token: string;
+        voipToken?: string;
+    }): Promise<void>;
+    /**
+     * Unregister this device's push notification token (e.g. on logout). Future
+     * push fan-out for this (appId, userId, deviceId, platform) tuple is dropped.
+     */
+    unregisterPushToken(opts: {
+        platform: 'APNS' | 'FCM' | 'WEB_PUSH';
+    }): Promise<void>;
     sendCleartextMessage(toUserId: string, plaintext: string): Promise<{
         messageId: string;
     }>;

package/dist/core/messaging-client.js

@@ -526,6 +526,57 @@ class MessagingClient {
         return { deleteId };
     }
     // ---------------------------------------------------------------------------
+    // Push notification token registration (PROTOCOL_VERSION 5+)
+    // ---------------------------------------------------------------------------
+    /**
+     * Register this device's push notification token with the DropOnAir platform.
+     * The token is opaque to the server; the platform fans out push notifications
+     * via the customer's APNs / FCM / VAPID credentials when a sender attaches a
+     * pushPayload to a message and the recipient is offline.
+     *
+     * For iOS apps using VoIP push (PushKit), pass {@code voipToken} alongside the
+     * regular APNs token. The platform will route CALL_INVITE pushes via the VoIP
+     * token and message pushes via the regular token.
+     *
+     * Idempotent: calling twice with the same (platform, deviceId) upserts the
+     * stored token and refreshes its lastSeenAt timestamp.
+     */
+    async registerPushToken(opts) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('DropOnAir websocket is not connected');
+        }
+        if (!opts.token || opts.token.trim().length === 0) {
+            throw new Error('Push token must not be empty');
+        }
+        const deviceId = this.deviceId ?? await this.getOrCreateDeviceId();
+        const frame = {
+            type: 'PUSH_REGISTER',
+            platform: opts.platform,
+            token: opts.token,
+            voipToken: opts.voipToken ?? '',
+            deviceId,
+        };
+        this.ws.send(this.codec.encodePushRegistrationFrame(frame));
+    }
+    /**
+     * Unregister this device's push notification token (e.g. on logout). Future
+     * push fan-out for this (appId, userId, deviceId, platform) tuple is dropped.
+     */
+    async unregisterPushToken(opts) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('DropOnAir websocket is not connected');
+        }
+        const deviceId = this.deviceId ?? await this.getOrCreateDeviceId();
+        const frame = {
+            type: 'PUSH_UNREGISTER',
+            platform: opts.platform,
+            token: '',
+            voipToken: '',
+            deviceId,
+        };
+        this.ws.send(this.codec.encodePushRegistrationFrame(frame));
+    }
+    // ---------------------------------------------------------------------------
     // Cleartext messaging (no E2EE key exchange required)
     // ---------------------------------------------------------------------------
     async sendCleartextMessage(toUserId, plaintext) {

package/dist/core/types.d.ts

@@ -170,6 +170,23 @@ export interface DropOnAirClient {
     onMessageEdit(callback: MessageEditCallback): () => void;
     /** Register a listener for incoming message-delete notifications. */
     onMessageDelete(callback: MessageDeleteCallback): () => void;
+    /**
+     * Register this device's push notification token. The platform delivers a
+     * push via APNs / FCM / Web Push when a sender attaches a pushPayload to
+     * a message and the recipient has no live WebSocket session. The token is
+     * opaque to the server. For iOS PushKit/CallKit, pass {@code voipToken}
+     * alongside the regular APNs token so incoming call invites wake the app
+     * via the VoIP push channel.
+     */
+    registerPushToken(opts: {
+        platform: 'APNS' | 'FCM' | 'WEB_PUSH';
+        token: string;
+        voipToken?: string;
+    }): Promise<void>;
+    /** Unregister this device's push notification token (e.g. on logout). */
+    unregisterPushToken(opts: {
+        platform: 'APNS' | 'FCM' | 'WEB_PUSH';
+    }): Promise<void>;
     /**
      * Convenience: encrypts (E2EE), uploads to the customer's bucket, finalizes,
      * and returns an AttachmentRef ready to pass into {@link sendMessage}.

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

@@ -136,6 +136,18 @@ export interface WireMessageEditFrame {
     plaintextPayload?: string;
     clientEditId?: string;
 }
+/**
+ * Push token registration / unregister. Client -> server only. The server
+ * acks with a regular Ack frame of type 'PUSH_REGISTERED' or
+ * 'PUSH_UNREGISTERED' and correlation 'PUSH:<deviceId>:<platform>'.
+ */
+export interface WirePushRegistrationFrame {
+    type: 'PUSH_REGISTER' | 'PUSH_UNREGISTER';
+    platform: 'APNS' | 'FCM' | 'WEB_PUSH';
+    token: string;
+    voipToken?: string;
+    deviceId: string;
+}
 /** Tombstone frame, scope FOR_EVERYONE or FOR_ME. */
 export interface WireMessageDeleteFrame {
     type: string;
@@ -189,6 +201,7 @@ export declare class ProtobufCodec {
     encodeGroupAck(value: WireGroupAck): Uint8Array;
     encodeMessageEditFrame(value: WireMessageEditFrame): Uint8Array;
     encodeMessageDeleteFrame(value: WireMessageDeleteFrame): Uint8Array;
+    encodePushRegistrationFrame(value: WirePushRegistrationFrame): Uint8Array;
     decodeFrame(payload: Uint8Array): InboundFrame;
     private tryDecodeEnvelope;
     private tryDecodeAck;

package/dist/transport/protobuf-codec.js

@@ -208,6 +208,15 @@ const MessageDeleteFrameType = new protobuf.Type('MessageDeleteFrame')
     .add(new protobuf.Field('timestamp', 7, 'int64'))
     .add(new protobuf.Field('scope', 8, 'string'))
     .add(new protobuf.Field('clientDeleteId', 9, 'string'));
+// Push token registration frame (PROTOCOL_VERSION 5+). Client to server only;
+// the server emits a PUSH_REGISTERED / PUSH_UNREGISTERED Ack back. The token
+// is opaque to the server and stored against (appId, userId, deviceId, platform).
+const PushRegistrationFrameType = new protobuf.Type('PushRegistrationFrame')
+    .add(new protobuf.Field('type', 1, 'string'))
+    .add(new protobuf.Field('platform', 2, 'string'))
+    .add(new protobuf.Field('token', 3, 'string'))
+    .add(new protobuf.Field('voipToken', 4, 'string'))
+    .add(new protobuf.Field('deviceId', 5, 'string'));
 class ProtobufCodec {
     encodeEnvelope(value) {
         return EnvelopeType.encode(value).finish();
@@ -236,6 +245,9 @@ class ProtobufCodec {
     encodeMessageDeleteFrame(value) {
         return MessageDeleteFrameType.encode(value).finish();
     }
+    encodePushRegistrationFrame(value) {
+        return PushRegistrationFrameType.encode(value).finish();
+    }
     decodeFrame(payload) {
         // Edit and delete frames must be probed BEFORE Envelope, the type
         // discriminator at field 1 ("MESSAGE_EDIT" / "MESSAGE_DELETE") would

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.8.0";
+export declare const SDK_VERSION = "0.9.1";
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can
@@ -19,4 +19,4 @@ export declare const PAYLOAD_FORMAT_VERSION = 1;
  * Increment when adding required proto fields or changing frame semantics.
  * The server advertises its supported range via GET /api/info.
  */
-export declare const PROTOCOL_VERSION = 4;
+export declare const PROTOCOL_VERSION = 5;

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.8.0';
+exports.SDK_VERSION = '0.9.1';
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can
@@ -22,4 +22,4 @@ exports.PAYLOAD_FORMAT_VERSION = 1;
  * Increment when adding required proto fields or changing frame semantics.
  * The server advertises its supported range via GET /api/info.
  */
-exports.PROTOCOL_VERSION = 4;
+exports.PROTOCOL_VERSION = 5;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@droponair/sdk-js",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "DropOnAir SDK for end-to-end encrypted messaging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",