@droponair/sdk-js 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -6,6 +6,21 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.11.0], 2026-05-20
+
+### 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.
+- 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.
+- 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.
+
+---
+
 ## [0.10.0], 2026-05-20
 
 ### Added

package/README.md

@@ -100,6 +100,22 @@ const client = await initialize(options);
 | `unregisterPushToken({ platform })` | `Promise<void>` | Unregister this device for push notifications (e.g. on logout). |
 | `listMyDevices()` | `Promise<DeviceInfo[]>` | List the current user's registered devices. |
 | `revokeMyDevice(deviceId)` | `Promise<DeviceInfo>` | Revoke one of the current user's devices. Permanent. |
+| `markRead(messageId, conversationId?)` | `void` | Mark a message as read; relays a receipt to the user's other devices. |
+| `onReadReceipt(callback)` | `() => void` | Listen for read receipts from the user's other devices. |
+
+### 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.
+
+```typescript
+// When your UI decides the message has been read
+client.markRead(messageId, peerUserId);
+
+// On the user's other devices
+client.onReadReceipt(e => {
+  // e.messageId was read elsewhere — clear your unread state for it
+});
+```
 
 ### Device trust
 

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, GroupCallEventCallback, GroupInfo, GroupMessageCallback, InitializeOptions, MessageCallback, MessageDeleteCallback, MessageEditCallback, TurnCredentials, DeviceInfo } from './types';
+import { BroadcastCallback, CallEventCallback, DropOnAirClient, EventCallback, GroupCallEventCallback, GroupInfo, GroupMessageCallback, InitializeOptions, MessageCallback, MessageDeleteCallback, MessageEditCallback, TurnCredentials, DeviceInfo, ReadReceiptCallback } from './types';
 import { AttachmentRef, CreateUploadSessionOptions, DownloadedAttachment, PrepareAttachmentOptions, UploadSession } from '../attachment/attachment-types';
 export declare class MessagingClient implements DropOnAirClient {
     private readonly options;
@@ -71,6 +71,7 @@ export declare class MessagingClient implements DropOnAirClient {
     private readonly eventListeners;
     private readonly broadcastListeners;
     private readonly messageEditListeners;
+    private readonly readReceiptListeners;
     private readonly messageDeleteListeners;
     /** ------------------------------------------------------------------
      * Lightweight structured logger. Only active when options.debug === true.
@@ -102,6 +103,12 @@ export declare class MessagingClient implements DropOnAirClient {
     onEvent(callback: EventCallback): () => void;
     onMessageEdit(callback: MessageEditCallback): () => void;
     onMessageDelete(callback: MessageDeleteCallback): () => void;
+    /**
+     * Register a listener for read receipts that this user's OTHER devices
+     * reported. Fires when another device of the same user calls markRead();
+     * use it to clear the unread state your app maintains for that message.
+     */
+    onReadReceipt(callback: ReadReceiptCallback): () => void;
     editMessage(originalMessageId: string, toUserId: string, newPlaintext: string): Promise<{
         editId: string;
     }>;
@@ -157,6 +164,21 @@ export declare class MessagingClient implements DropOnAirClient {
      * show a re-register prompt.
      */
     private handleDeviceRevoked;
+    /**
+     * Mark a message as read. Call this when YOUR app decides a message has
+     * been read - the platform never infers read state for you. The receipt
+     * is relayed to this user's other devices so they can clear their unread
+     * UI for the same message; it is not delivered to the message's sender.
+     *
+     * If the app owner has disabled read receipts in the dashboard, the server
+     * silently drops the frame.
+     *
+     * @param messageId       the message that was read
+     * @param conversationId  optional peer userId / group id, echoed back to
+     *                        other devices so they can bucket the receipt
+     */
+    markRead(messageId: string, conversationId?: string): void;
+    private handleIncomingSync;
     sendCleartextMessage(toUserId: string, plaintext: string): Promise<{
         messageId: string;
     }>;

package/dist/core/messaging-client.js

@@ -220,6 +220,7 @@ class MessagingClient {
         this.eventListeners = new Set();
         this.broadcastListeners = new Set();
         this.messageEditListeners = new Set();
+        this.readReceiptListeners = new Set();
         this.messageDeleteListeners = new Set();
         this.wsUrl = options.messagingWsUrl ?? 'wss://sdk.droponair.com/ws';
         this.httpUrl = options.messagingHttpUrl ?? 'https://sdk.droponair.com';
@@ -410,6 +411,15 @@ class MessagingClient {
         this.messageDeleteListeners.add(callback);
         return () => this.messageDeleteListeners.delete(callback);
     }
+    /**
+     * Register a listener for read receipts that this user's OTHER devices
+     * reported. Fires when another device of the same user calls markRead();
+     * use it to clear the unread state your app maintains for that message.
+     */
+    onReadReceipt(callback) {
+        this.readReceiptListeners.add(callback);
+        return () => this.readReceiptListeners.delete(callback);
+    }
     // ---------------------------------------------------------------------------
     // Message edit and delete (PROTOCOL_VERSION 3+)
     // ---------------------------------------------------------------------------
@@ -630,6 +640,49 @@ class MessagingClient {
         }
     }
     // ---------------------------------------------------------------------------
+    // Cross-device read receipts (PROTOCOL_VERSION 6+ / Phase 2c)
+    // ---------------------------------------------------------------------------
+    /**
+     * Mark a message as read. Call this when YOUR app decides a message has
+     * been read - the platform never infers read state for you. The receipt
+     * is relayed to this user's other devices so they can clear their unread
+     * UI for the same message; it is not delivered to the message's sender.
+     *
+     * If the app owner has disabled read receipts in the dashboard, the server
+     * silently drops the frame.
+     *
+     * @param messageId       the message that was read
+     * @param conversationId  optional peer userId / group id, echoed back to
+     *                        other devices so they can bucket the receipt
+     */
+    markRead(messageId, conversationId) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('DropOnAir websocket is not connected');
+        }
+        const frame = {
+            type: 'SYNC_READ_RECEIPT',
+            messageId,
+            conversationId: conversationId ?? '',
+            timestamp: Date.now(),
+        };
+        this.ws.send(this.codec.encodeSyncFrame(frame));
+    }
+    handleIncomingSync(frame) {
+        if (frame.type === 'SYNC_READ_RECEIPT') {
+            const event = {
+                messageId: frame.messageId,
+                conversationId: frame.conversationId || undefined,
+                timestamp: frame.timestamp,
+            };
+            for (const listener of this.readReceiptListeners) {
+                try {
+                    listener(event);
+                }
+                catch { /* listener errors must not break the socket */ }
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
     // Cleartext messaging (no E2EE key exchange required)
     // ---------------------------------------------------------------------------
     async sendCleartextMessage(toUserId, plaintext) {
@@ -1389,6 +1442,10 @@ class MessagingClient {
                     this.handleIncomingMessageDelete(frame.data);
                     return;
                 }
+                if (frame.kind === 'sync') {
+                    this.handleIncomingSync(frame.data);
+                    return;
+                }
                 if (frame.kind === 'envelope') {
                     await this.handleIncomingEnvelope(frame.data);
                 }

package/dist/core/types.d.ts

@@ -48,6 +48,18 @@ export interface MessageDeleteEvent {
 }
 export type MessageEditCallback = (event: MessageEditEvent) => void;
 export type MessageDeleteCallback = (event: MessageDeleteEvent) => void;
+/**
+ * Delivered to the user's OTHER devices when one device calls markRead().
+ * Use it to clear whatever unread state your app keeps for that message.
+ * It is NOT delivered to the original sender of the message.
+ */
+export interface ReadReceiptEvent {
+    messageId: string;
+    /** Optional peer userId / group id, echoed from markRead() for bucketing. */
+    conversationId?: string;
+    timestamp: number;
+}
+export type ReadReceiptCallback = (event: ReadReceiptEvent) => void;
 export interface BroadcastMessage {
     broadcastId: string;
     channelId: string;
@@ -183,6 +195,14 @@ export interface DropOnAirClient {
     onMessageEdit(callback: MessageEditCallback): () => void;
     /** Register a listener for incoming message-delete notifications. */
     onMessageDelete(callback: MessageDeleteCallback): () => void;
+    /**
+     * Mark a message as read. The integrating app decides when this is called;
+     * the platform never infers read state. The receipt is relayed to the
+     * user's other devices only, never to the message's sender.
+     */
+    markRead(messageId: string, conversationId?: string): void;
+    /** Register a listener for read receipts reported by this user's other devices. */
+    onReadReceipt(callback: ReadReceiptCallback): () => 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

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { InitializeOptions, DropOnAirClient } from './core/types';
 export { SDK_VERSION, PROTOCOL_VERSION, PAYLOAD_FORMAT_VERSION } from './version';
 export declare function initialize(options: InitializeOptions): Promise<DropOnAirClient>;
-export type { InitializeOptions, DropOnAirClient, DropOnAirEvent, MessageCallback, EventCallback, DecryptedMessage, KeyStorageAdapter, CallEvent, CallEventType, CallEventCallback, TurnCredentials, BroadcastMessage, BroadcastCallback, GroupInfo, GroupMemberInfo, DecryptedGroupMessage, GroupMessageCallback, GroupCallEvent, GroupCallEventType, GroupCallEventCallback, MessageEditEvent, MessageEditCallback, MessageDeleteEvent, MessageDeleteCallback, DeviceInfo, } from './core/types';
+export type { InitializeOptions, DropOnAirClient, DropOnAirEvent, MessageCallback, EventCallback, DecryptedMessage, KeyStorageAdapter, CallEvent, CallEventType, CallEventCallback, TurnCredentials, BroadcastMessage, BroadcastCallback, GroupInfo, GroupMemberInfo, DecryptedGroupMessage, GroupMessageCallback, GroupCallEvent, GroupCallEventType, GroupCallEventCallback, MessageEditEvent, MessageEditCallback, MessageDeleteEvent, MessageDeleteCallback, DeviceInfo, ReadReceiptEvent, ReadReceiptCallback, } from './core/types';
 export type { AttachmentEncryptionType, AttachmentConversationType, AttachmentRef, DeviceWrappedKey, CreateUploadSessionOptions, UploadSession, PrepareAttachmentOptions, DownloadedAttachment, } from './attachment/attachment-types';
 declare const _default: {
     initialize: typeof initialize;

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

@@ -148,6 +148,16 @@ export interface WirePushRegistrationFrame {
     voipToken?: string;
     deviceId: string;
 }
+/**
+ * Cross-device state sync frame (PROTOCOL_VERSION 6+). Same shape sent
+ * client -> server and relayed server -> the user's other devices.
+ */
+export interface WireSyncFrame {
+    type: string;
+    messageId: string;
+    conversationId?: string;
+    timestamp: number;
+}
 /** Tombstone frame, scope FOR_EVERYONE or FOR_ME. */
 export interface WireMessageDeleteFrame {
     type: string;
@@ -190,6 +200,9 @@ export type InboundFrame = {
 } | {
     kind: 'messageDelete';
     data: WireMessageDeleteFrame;
+} | {
+    kind: 'sync';
+    data: WireSyncFrame;
 };
 export declare class ProtobufCodec {
     encodeEnvelope(value: WireEnvelope): Uint8Array;
@@ -202,6 +215,7 @@ export declare class ProtobufCodec {
     encodeMessageEditFrame(value: WireMessageEditFrame): Uint8Array;
     encodeMessageDeleteFrame(value: WireMessageDeleteFrame): Uint8Array;
     encodePushRegistrationFrame(value: WirePushRegistrationFrame): Uint8Array;
+    encodeSyncFrame(value: WireSyncFrame): Uint8Array;
     decodeFrame(payload: Uint8Array): InboundFrame;
     private tryDecodeEnvelope;
     private tryDecodeAck;
@@ -211,6 +225,7 @@ export declare class ProtobufCodec {
     private tryDecodeGroupMessageNotification;
     private tryDecodeGroupAck;
     private tryDecodeGroupCallFrame;
+    private tryDecodeSyncFrame;
     private tryDecodeMessageEditFrame;
     private tryDecodeMessageDeleteFrame;
 }

package/dist/transport/protobuf-codec.js

@@ -217,6 +217,14 @@ const PushRegistrationFrameType = new protobuf.Type('PushRegistrationFrame')
     .add(new protobuf.Field('token', 3, 'string'))
     .add(new protobuf.Field('voipToken', 4, 'string'))
     .add(new protobuf.Field('deviceId', 5, 'string'));
+// Cross-device state sync frame (PROTOCOL_VERSION 6+). Same shape both
+// directions: client -> server (request) and server -> the user's other
+// devices (notification). Discriminator is `type` at field 1 ("SYNC_").
+const SyncFrameType = new protobuf.Type('SyncFrame')
+    .add(new protobuf.Field('type', 1, 'string'))
+    .add(new protobuf.Field('messageId', 2, 'string'))
+    .add(new protobuf.Field('conversationId', 3, 'string'))
+    .add(new protobuf.Field('timestamp', 4, 'int64'));
 class ProtobufCodec {
     encodeEnvelope(value) {
         return EnvelopeType.encode(value).finish();
@@ -248,6 +256,9 @@ class ProtobufCodec {
     encodePushRegistrationFrame(value) {
         return PushRegistrationFrameType.encode(value).finish();
     }
+    encodeSyncFrame(value) {
+        return SyncFrameType.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
@@ -260,6 +271,11 @@ class ProtobufCodec {
         if (asDelete) {
             return { kind: 'messageDelete', data: asDelete };
         }
+        // SyncFrame: discriminator "SYNC_" at field 1, probed before Envelope.
+        const asSync = this.tryDecodeSyncFrame(payload);
+        if (asSync) {
+            return { kind: 'sync', data: asSync };
+        }
         const asEnvelope = this.tryDecodeEnvelope(payload);
         if (asEnvelope) {
             return { kind: 'envelope', data: asEnvelope };
@@ -446,6 +462,18 @@ class ProtobufCodec {
             return null;
         }
     }
+    tryDecodeSyncFrame(payload) {
+        try {
+            const decoded = SyncFrameType.decode(payload);
+            if (!decoded.type || !decoded.type.startsWith('SYNC_')) {
+                return null;
+            }
+            return { ...decoded, timestamp: Number(decoded.timestamp) };
+        }
+        catch {
+            return null;
+        }
+    }
     tryDecodeMessageEditFrame(payload) {
         try {
             const decoded = MessageEditFrameType.decode(payload);

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.10.0";
+export declare const SDK_VERSION = "0.11.0";
 /**
  * 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 = 5;
+export declare const PROTOCOL_VERSION = 6;

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.10.0';
+exports.SDK_VERSION = '0.11.0';
 /**
  * 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 = 5;
+exports.PROTOCOL_VERSION = 6;

package/package.json

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