@droponair/sdk-js 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.29.0
+
+### Fixed
+
+- **Delivered and seen no longer depend on the sender being online.** A receipt
+  existed only as a frame on a live socket, so a sender who was away when someone
+  fetched or read the message never learned it and the mark stayed where it was
+  for good. An app that disconnects in the background, which is what an app has to
+  do to be pushed at all, missed nearly all of them. The SDK now catches up on
+  connect and reports the state as the ordinary delivered and read callbacks, so
+  there is no new API to adopt: existing receipt handling starts working.
+
+### Notes
+
+- Catch-up covers the messages you sent most recently and replays their current
+  state, so handling must be idempotent. Marks should only ever move forward.
+- Additive and backward compatible. A relay that predates this answers 404 and
+  the SDK treats that as nothing to catch up on.
+
+## 0.28.0
+
+### Fixed
+
+- **A push token offered before the client connected was thrown away.** The push
+  service hands an app its device token at launch, always before a connection
+  exists, so `registerPushToken` refusing it there lost the token exactly when
+  every app first offers it, and push simply never arrived. The token is now held
+  and registered as soon as a connection exists. It is also re-registered on every
+  connect, because the relay ties a token to a session: after a reconnect or a
+  relay restart the device would otherwise be silently unreachable.
+
+### Notes
+
+- `registerPushToken` no longer rejects a call made before connecting. Existing
+  code that catches that error still compiles and simply stops seeing it.
+- `unregisterPushToken` drops the held token, so it is not re-registered later.
+
 ## 0.27.0
 
 ### Added

package/README.md

@@ -207,6 +207,10 @@ client.onEvent(e => {
 
 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.
 
+
+Register the token as soon as you have it. The SDK holds it until a connection
+exists and registers it then, and re-registers on every connect, so there is no
+need to wait for the client to connect or to retry yourself.
 ```typescript
 // iOS, after didRegisterForRemoteNotificationsWithDeviceToken
 await client.registerPushToken({ platform: 'APNS', token: deviceTokenHex });
@@ -359,6 +363,12 @@ client.onMessage(async (msg) => {
 | `sendCleartextGroupMessage(groupId, plaintext)` | `Promise<{ messageId }>` | Send a plaintext (non-encrypted) group message; server fans out to every other member. |
 | `onGroupMessage(callback)` | `() => void` | Listen for group messages |
 
+Delivered and seen are caught up on every connect, so a sender that was away
+while someone fetched or read still learns about it. The state arrives through
+the same delivered and read callbacks a live receipt uses, so there is nothing
+extra to handle; make sure your handling is idempotent and only ever moves a
+mark forward, since catch-up replays the current state rather than the changes.
+
 **Group delivery is per member.** A group message has many recipients, so the platform
 reports delivery as a set rather than a single flag and leaves the presentation to you.
 `DELIVERED` and `SEEN` arrive as events whose `metadata` carries `messageId`, `groupId`

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

@@ -22,6 +22,11 @@ export declare class MessagingClient implements DropOnAirClient {
     private dropOnAirJwt;
     private currentUserId;
     private deviceId;
+    /**
+     * The push token this device last offered, held until a connection exists and
+     * re-sent on every connect. Cleared by `unregisterPushToken`.
+     */
+    private pendingPushRegistration;
     private rateLimited;
     private reconnectAttempt;
     private connectGeneration;
@@ -169,6 +174,8 @@ export declare class MessagingClient implements DropOnAirClient {
         token: string;
         voipToken?: string;
     }): Promise<void>;
+    /** Registers the held token, if there is one. Called on every connect. */
+    private sendPushRegistration;
     /**
      * Unregister this device's push notification token (e.g. on logout). Future
      * push fan-out for this (appId, userId, deviceId, platform) tuple is dropped.
@@ -381,6 +388,15 @@ export declare class MessagingClient implements DropOnAirClient {
      * live at that instant and is unreachable afterwards, so anyone closed loses it.
      * Fetching is also what tells the sender the message reached this member.
      */
+    /**
+     * Catches up on who has the messages this client sent.
+     *
+     * A receipt used to be a frame on a live socket and nothing else, so a sender
+     * that was away when someone fetched or read never found out and the tick
+     * stayed where it was. The state is kept per member, and this replays it as the
+     * events that would have arrived live, so an app needs no separate path for it.
+     */
+    private fetchGroupReceipts;
     private fetchAndProcessOfflineGroupMessages;
     private fetchAndProcessOfflineMessages;
     private getValidDropOnAirJwt;

package/dist/core/messaging-client.js

@@ -246,6 +246,11 @@ class MessagingClient {
         this.dropOnAirJwt = null;
         this.currentUserId = null;
         this.deviceId = null;
+        /**
+         * The push token this device last offered, held until a connection exists and
+         * re-sent on every connect. Cleared by `unregisterPushToken`.
+         */
+        this.pendingPushRegistration = null;
         this.rateLimited = false;
         this.reconnectAttempt = 0;
         // Monotonic id for each connect attempt. Transport callbacks (onOpen/onError/
@@ -650,18 +655,36 @@ class MessagingClient {
      * stored token and refreshes its lastSeenAt timestamp.
      */
     async registerPushToken(opts) {
-        if (!this.transport?.isOpen()) {
-            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',
+        // The push service hands an app its token at startup, usually before a
+        // connection exists, so refusing the registration here would lose it exactly
+        // when every app first offers it. Hold it instead and send it on connect, and
+        // keep holding it: the relay ties a token to a session, so a reconnect or a
+        // relay restart has to re-register or the device goes quiet.
+        this.pendingPushRegistration = {
             platform: opts.platform,
             token: opts.token,
             voipToken: opts.voipToken ?? '',
+        };
+        if (!this.transport?.isOpen()) {
+            return;
+        }
+        await this.sendPushRegistration();
+    }
+    /** Registers the held token, if there is one. Called on every connect. */
+    async sendPushRegistration() {
+        const pending = this.pendingPushRegistration;
+        if (!pending || !this.transport?.isOpen()) {
+            return;
+        }
+        const deviceId = this.deviceId ?? await this.getOrCreateDeviceId();
+        const frame = {
+            type: 'PUSH_REGISTER',
+            platform: pending.platform,
+            token: pending.token,
+            voipToken: pending.voipToken,
             deviceId,
         };
         this.transport.send(this.codec.encodePushRegistrationFrame(frame));
@@ -671,6 +694,7 @@ class MessagingClient {
      * push fan-out for this (appId, userId, deviceId, platform) tuple is dropped.
      */
     async unregisterPushToken(opts) {
+        this.pendingPushRegistration = null;
         if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
@@ -1779,6 +1803,12 @@ class MessagingClient {
                 if (this.dropOnAirJwt) {
                     this.scheduleProactiveTokenRefresh(this.dropOnAirJwt);
                 }
+                this.sendPushRegistration().catch((err) => {
+                    this.logError('push_registration_failed', { error: String(err) });
+                });
+                this.fetchGroupReceipts().catch((err) => {
+                    this.logError('group_receipts_fetch_failed', { error: String(err) });
+                });
                 this.fetchAndProcessOfflineGroupMessages().catch((err) => {
                     this.logError('group_offline_fetch_failed', { error: String(err) });
                 });
@@ -2250,6 +2280,41 @@ class MessagingClient {
      * live at that instant and is unreachable afterwards, so anyone closed loses it.
      * Fetching is also what tells the sender the message reached this member.
      */
+    /**
+     * Catches up on who has the messages this client sent.
+     *
+     * A receipt used to be a frame on a live socket and nothing else, so a sender
+     * that was away when someone fetched or read never found out and the tick
+     * stayed where it was. The state is kept per member, and this replays it as the
+     * events that would have arrived live, so an app needs no separate path for it.
+     */
+    async fetchGroupReceipts() {
+        const jwt = await this.getValidDropOnAirJwt(false);
+        const response = await this.fetchFn(`${this.httpUrl}/v1/groups/messages/receipts?limit=100`, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' },
+        });
+        // A relay that predates this endpoint answers 404: nothing to catch up on.
+        if (!response.ok) {
+            return;
+        }
+        const body = await response.json();
+        for (const entry of body.messages ?? []) {
+            for (const memberUserId of entry.deliveredTo ?? []) {
+                this.emitEvent({
+                    type: 'DELIVERED',
+                    metadata: JSON.stringify({ messageId: entry.messageId, groupId: entry.groupId, memberUserId }),
+                });
+            }
+            for (const memberUserId of entry.seenBy ?? []) {
+                this.emitEvent({
+                    type: 'SEEN',
+                    metadata: JSON.stringify({ messageId: entry.messageId, groupId: entry.groupId, memberUserId }),
+                });
+            }
+        }
+        this.log('group_receipts_fetched', { messages: (body.messages ?? []).length });
+    }
     async fetchAndProcessOfflineGroupMessages() {
         const jwt = await this.getValidDropOnAirJwt(false);
         let page = 0;

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.27.0";
+export declare const SDK_VERSION = "0.29.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.27.0';
+exports.SDK_VERSION = '0.29.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.27.0",
+  "version": "0.29.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",