@droponair/sdk-js 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.30.0
+
+### Added
+
+- **Typing indicators.** `sendTyping(conversationId, isTyping)` and `onTyping(callback)`. Nothing in the platform carried this before, so an
+  app that wanted to show someone composing had nowhere to send it.
+- Typing is never stored. It describes this moment and is worth nothing after it,
+  so it reaches only those connected at the time and is never replayed. Treat a
+  start as expiring on its own after a few seconds rather than waiting for the
+  matching stop, which is lost if the sender disconnects mid-sentence.
+- Gated separately from read receipts, which name a message that was read and are
+  opted into per group. Typing says only that somebody is composing and discloses
+  nothing about what, so it needs no per-group opt-in.
+
+## 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

package/README.md

@@ -363,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`
@@ -374,6 +380,22 @@ on `SERVER_RECEIVED`, which is about the relay rather than any member.
 was closed or disconnected is drained automatically when it reconnects and delivered
 through `onGroupMessage` just like a live message. There is nothing to call.
 
+### Typing indicators
+
+Say when someone starts and stops composing, and hear it about others. Nothing is
+stored: it reaches only those connected at the time and is never replayed, so
+treat a start as expiring on its own rather than waiting for the stop, which is
+lost if the sender disconnects mid-sentence.
+
+```typescript
+client.sendTyping(groupId, true);
+client.sendTyping(groupId, false);
+
+client.onTyping((event) => {
+  // event.conversationId, event.fromUserId, event.isTyping
+});
+```
+
 ### 1-to-1 Calls
 
 | Method | Returns | Description |

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, PushPayload } from './types';
+import { BroadcastCallback, CallEventCallback, DropOnAirClient, EventCallback, CreateRoomOptions, GroupCallEventCallback, GroupInfo, GroupMessageCallback, Room, UpdateRoomOptions, SfuToken, SfuRecording, InitializeOptions, MessageCallback, MessageDeleteCallback, MessageEditCallback, TurnCredentials, DeviceInfo, ReadReceiptCallback, TypingCallback, 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;
@@ -90,6 +90,7 @@ export declare class MessagingClient implements DropOnAirClient {
     private readonly broadcastListeners;
     private readonly messageEditListeners;
     private readonly readReceiptListeners;
+    private readonly typingListeners;
     private readonly notificationClearListeners;
     private readonly draftSyncListeners;
     private readonly messageDeleteListeners;
@@ -146,6 +147,11 @@ export declare class MessagingClient implements DropOnAirClient {
      * reported. Fires when another device of the same user calls markRead();
      * use it to clear the unread state your app maintains for that message.
      */
+    /**
+     * Listen for someone starting or stopping typing in a conversation. Nothing is
+     * stored, so this only fires while both sides are connected.
+     */
+    onTyping(callback: TypingCallback): () => void;
     onReadReceipt(callback: ReadReceiptCallback): () => void;
     editMessage(originalMessageId: string, toUserId: string, newPlaintext: string): Promise<{
         editId: string;
@@ -217,6 +223,14 @@ export declare class MessagingClient implements DropOnAirClient {
      * @param conversationId  optional peer userId / group id, echoed back to
      *                        other devices so they can bucket the receipt
      */
+    /**
+     * Say this user started or stopped composing in a conversation.
+     *
+     * Never stored, so it reaches only those connected at the time. Send `false`
+     * when they stop, but treat the indicator as expiring on its own: if the sender
+     * disconnects mid-sentence, the stop never arrives.
+     */
+    sendTyping(conversationId: string, isTyping: boolean): void;
     markRead(messageId: string, conversationId?: string): void;
     /**
      * Tell this user's other devices that the notification(s) for a
@@ -388,6 +402,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

@@ -282,6 +282,7 @@ class MessagingClient {
         this.broadcastListeners = new Set();
         this.messageEditListeners = new Set();
         this.readReceiptListeners = new Set();
+        this.typingListeners = new Set();
         this.notificationClearListeners = new Set();
         this.draftSyncListeners = new Set();
         this.messageDeleteListeners = new Set();
@@ -519,6 +520,14 @@ class MessagingClient {
      * reported. Fires when another device of the same user calls markRead();
      * use it to clear the unread state your app maintains for that message.
      */
+    /**
+     * Listen for someone starting or stopping typing in a conversation. Nothing is
+     * stored, so this only fires while both sides are connected.
+     */
+    onTyping(callback) {
+        this.typingListeners.add(callback);
+        return () => this.typingListeners.delete(callback);
+    }
     onReadReceipt(callback) {
         this.readReceiptListeners.add(callback);
         return () => this.readReceiptListeners.delete(callback);
@@ -777,6 +786,26 @@ class MessagingClient {
      * @param conversationId  optional peer userId / group id, echoed back to
      *                        other devices so they can bucket the receipt
      */
+    /**
+     * Say this user started or stopped composing in a conversation.
+     *
+     * Never stored, so it reaches only those connected at the time. Send `false`
+     * when they stop, but treat the indicator as expiring on its own: if the sender
+     * disconnects mid-sentence, the stop never arrives.
+     */
+    sendTyping(conversationId, isTyping) {
+        if (!this.transport?.isOpen()) {
+            return;
+        }
+        const frame = {
+            type: 'SYNC_TYPING',
+            messageId: '',
+            conversationId,
+            timestamp: Date.now(),
+            payload: isTyping ? 'start' : 'stop',
+        };
+        this.transport.send(this.codec.encodeSyncFrame(frame));
+    }
     markRead(messageId, conversationId) {
         if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
@@ -838,7 +867,24 @@ class MessagingClient {
         return () => this.draftSyncListeners.delete(callback);
     }
     handleIncomingSync(frame) {
-        if (frame.type === 'SYNC_READ_RECEIPT') {
+        if (frame.type === 'SYNC_TYPING') {
+            if (!frame.conversationId || !frame.fromUserId) {
+                return;
+            }
+            const event = {
+                conversationId: frame.conversationId,
+                fromUserId: frame.fromUserId,
+                isTyping: frame.payload !== 'stop',
+                timestamp: frame.timestamp,
+            };
+            for (const listener of this.typingListeners) {
+                try {
+                    listener(event);
+                }
+                catch { /* listener errors must not break the socket */ }
+            }
+        }
+        else if (frame.type === 'SYNC_READ_RECEIPT') {
             const event = {
                 messageId: frame.messageId,
                 conversationId: frame.conversationId || undefined,
@@ -1806,6 +1852,9 @@ class MessagingClient {
                 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) });
                 });
@@ -2277,6 +2326,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/core/types.d.ts

@@ -109,6 +109,24 @@ export interface ReadReceiptEvent {
     fromUserId?: string;
 }
 export type ReadReceiptCallback = (event: ReadReceiptEvent) => void;
+/**
+ * Someone in a conversation started or stopped composing.
+ *
+ * Ephemeral by design: the platform never stores it, so it arrives only while
+ * both sides are connected and nothing is replayed afterwards. Treat a `true` as
+ * expiring on its own after a few seconds rather than waiting for the matching
+ * `false`, which is lost if the sender disconnects mid-sentence.
+ */
+export interface TypingEvent {
+    /** The group or peer the typing is happening in. */
+    conversationId: string;
+    /** Who is typing. */
+    fromUserId: string;
+    /** Whether they started or stopped. */
+    isTyping: boolean;
+    timestamp: number;
+}
+export type TypingCallback = (event: TypingEvent) => void;
 /**
  * Delivered to the user's OTHER devices when one device calls
  * clearNotification(). Use it to clear the conversation's notification badge.

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export { SDK_VERSION, PROTOCOL_VERSION, PAYLOAD_FORMAT_VERSION } from './version
  */
 export declare function createSecureIdentity(store?: IdentityRecordStore): Promise<WebCryptoIdentityProvider | null>;
 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, Room, RoomPolicy, CreateRoomOptions, UpdateRoomOptions, SfuToken, SfuRecording, MessageEditEvent, MessageEditCallback, MessageDeleteEvent, MessageDeleteCallback, DeviceInfo, ReadReceiptEvent, ReadReceiptCallback, NotificationClearEvent, NotificationClearCallback, DraftSyncEvent, DraftSyncCallback, } 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, Room, RoomPolicy, CreateRoomOptions, UpdateRoomOptions, SfuToken, SfuRecording, MessageEditEvent, MessageEditCallback, MessageDeleteEvent, MessageDeleteCallback, DeviceInfo, ReadReceiptEvent, ReadReceiptCallback, TypingEvent, TypingCallback, NotificationClearEvent, NotificationClearCallback, DraftSyncEvent, DraftSyncCallback, } from './core/types';
 export type { AttachmentEncryptionType, AttachmentConversationType, AttachmentRef, DeviceWrappedKey, CreateUploadSessionOptions, UploadSession, PrepareAttachmentOptions, DownloadedAttachment, } from './attachment/attachment-types';
 export { SseTransport, type SseTransportOptions, type SseFrameHandler, type SseStateHandler, } from './transport/sse-transport';
 export { WebTransportTransport, type WebTransportTransportOptions, type WTFrameHandler, type WTStateHandler, } from './transport/webtransport-transport';

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