@droponair/sdk-js 0.3.0

package/dist/core/messaging-client.js

@@ -0,0 +1,1293 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessagingClient = void 0;
+const bytes_1 = require("./bytes");
+const protobuf_codec_1 = require("../transport/protobuf-codec");
+const version_1 = require("../version");
+const STORAGE_DEVICE_ID = 'droponair.device.id.v1';
+class MessagingClient {
+    reconnectDelayMs() {
+        // Exponential backoff: 2s, 4s, 8s, 16s, 32s, 60s (capped)
+        const delay = Math.min(2000 * Math.pow(2, this.reconnectAttempt), 60000);
+        this.reconnectAttempt++;
+        return delay;
+    }
+    /**
+     * Register a document visibilitychange listener so that when the iOS app
+     * returns from background we can immediately assess the JWT state.
+     *
+     * Background problem: iOS WebView suspends JavaScript (including all
+     * setTimeout timers) while the app is backgrounded.  A proactive-refresh
+     * timer scheduled for t+810 s effectively stops ticking, so if the user
+     * leaves the app open for 15+ minutes the JWT expires before the timer
+     * fires. This listener re-examines the JWT as soon as the user brings the
+     * app back to the foreground and either:
+     *   a) reschedules the timer with the corrected remaining time, or
+     *   b) triggers an immediate reconnect if the token has already expired or
+     *      will expire within the next 90 seconds.
+     */
+    registerVisibilityChangeHandler() {
+        if (typeof document === 'undefined') {
+            return;
+        }
+        this.unregisterVisibilityChangeHandler();
+        this.visibilityChangeHandler = () => {
+            if (document.visibilityState !== 'visible') {
+                return;
+            }
+            this.onAppForeground();
+        };
+        document.addEventListener('visibilitychange', this.visibilityChangeHandler);
+        this.log('visibility_handler_registered');
+    }
+    unregisterVisibilityChangeHandler() {
+        if (typeof document === 'undefined' || !this.visibilityChangeHandler) {
+            return;
+        }
+        document.removeEventListener('visibilitychange', this.visibilityChangeHandler);
+        this.visibilityChangeHandler = null;
+        this.log('visibility_handler_unregistered');
+    }
+    /**
+     * Called every time the app returns to the foreground.
+     * Decides whether to reconnect immediately or just reschedule the proactive
+     * refresh timer with the time remaining from the current JWT's expiry.
+     */
+    onAppForeground() {
+        this.log('app_foreground_detected', {
+            wsState: this.ws?.readyState,
+            shouldReconnect: this.shouldReconnect,
+            ...this.jwtSummary(this.dropOnAirJwt),
+        });
+        if (!this.shouldReconnect) {
+            return;
+        }
+        // If the WebSocket is already gone (background disconnect), the existing
+        // onclose handler will already be scheduling a reconnect, nothing to do.
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            return;
+        }
+        const jwt = this.dropOnAirJwt;
+        if (!jwt) {
+            // No token at all, close and let the reconnect loop fetch a new one.
+            this.log('foreground_reconnect_no_jwt');
+            this.ws.close(1000, 'FOREGROUND_NO_JWT');
+            return;
+        }
+        if ((0, bytes_1.isJwtExpired)(jwt)) {
+            // Token already expired while we were in background, close NOW so the
+            // reconnect fetches a fresh token before the user tries to send anything.
+            this.log('foreground_reconnect_jwt_expired', this.jwtSummary(jwt));
+            this.ws.close(1000, 'FOREGROUND_JWT_EXPIRED');
+            return;
+        }
+        // Token is still valid, reschedule the proactive timer based on actual
+        // remaining time now that JS is running again (the previous timer may have
+        // been frozen). scheduleProactiveTokenRefresh re-arms the timer correctly.
+        this.log('foreground_reschedule_refresh', this.jwtSummary(jwt));
+        this.scheduleProactiveTokenRefresh(jwt);
+    }
+    /**
+     * Schedule a proactive token rotation 90 seconds before the JWT expires.
+     * When it fires, a fresh token is pre-fetched and the current WebSocket is
+     * closed cleanly so the reconnect loop picks up the new token immediately.
+     * This prevents the server from ever rejecting a message due to an expired JWT.
+     */
+    scheduleProactiveTokenRefresh(jwt) {
+        if (this.proactiveRefreshTimer) {
+            clearTimeout(this.proactiveRefreshTimer);
+            this.proactiveRefreshTimer = null;
+        }
+        try {
+            const payload = (0, bytes_1.parseJwtPayload)(jwt);
+            const exp = Number(payload.exp ?? 0);
+            if (!Number.isFinite(exp) || exp <= 0) {
+                return;
+            }
+            const nowSeconds = Math.floor(Date.now() / 1000);
+            const secondsUntilExpiry = exp - nowSeconds;
+            // Rotate 90 seconds before expiry so there is plenty of leeway even if
+            // the token exchange HTTP call takes a few seconds.
+            const rotateInSeconds = Math.max(0, secondsUntilExpiry - 90);
+            this.log('proactive_refresh_scheduled', { exp, secondsUntilExpiry, rotateInSeconds });
+            this.proactiveRefreshTimer = setTimeout(async () => {
+                this.proactiveRefreshTimer = null;
+                if (!this.shouldReconnect || !this.ws) {
+                    return;
+                }
+                this.log('proactive_refresh_triggered', { exp });
+                // Pre-fetch a fresh token so the reconnect uses it without an extra round-trip.
+                try {
+                    await this.getValidDropOnAirJwt(true);
+                }
+                catch (err) {
+                    this.logError('proactive_refresh_token_failed', { error: String(err?.message ?? err) });
+                }
+                // Gracefully close the current connection; onclose will schedule reconnect.
+                if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+                    this.ws.close(1000, 'PROACTIVE_TOKEN_REFRESH');
+                }
+            }, rotateInSeconds * 1000);
+        }
+        catch {
+            // If the JWT cannot be parsed, skip proactive rotation, expiry detection
+            // on the server side will still trigger a normal reconnect.
+        }
+    }
+    /** ------------------------------------------------------------------
+     * Lightweight structured logger. Only active when options.debug === true.
+     * Fields are safe to log: no plaintext, no private keys, no full JWTs.
+     * ------------------------------------------------------------------ */
+    log(stage, details = {}) {
+        if (!this.options.debug) {
+            return;
+        }
+        console.info('[DropOnAirSDK]', JSON.stringify({
+            stage,
+            ts: new Date().toISOString(),
+            ...details,
+        }));
+    }
+    logError(stage, details = {}) {
+        // Always log errors, regardless of debug flag.
+        console.error('[DropOnAirSDK]', JSON.stringify({
+            stage,
+            ts: new Date().toISOString(),
+            ...details,
+        }));
+    }
+    /**
+     * Build the common headers required on every backend API call.
+     * X-Platform and X-API-Version are forwarded when supplied in InitializeOptions.
+     */
+    backendHeaders(userJwt) {
+        return {
+            Authorization: `Bearer ${userJwt}`,
+            'Content-Type': 'application/json',
+            ...(this.options.platformHeader ? { 'X-Platform': this.options.platformHeader } : {}),
+            ...(this.options.apiVersionHeader ? { 'X-API-Version': this.options.apiVersionHeader } : {}),
+        };
+    }
+    /** Redact a JWT to keep subject + expiry visible while hiding the signature. */
+    jwtSummary(jwt) {
+        if (!jwt) {
+            return { jwtPresent: false };
+        }
+        try {
+            const payload = (0, bytes_1.parseJwtPayload)(jwt);
+            return {
+                jwtPresent: true,
+                sub: payload.sub,
+                exp: payload.exp,
+                expired: (0, bytes_1.isJwtExpired)(jwt),
+            };
+        }
+        catch {
+            return { jwtPresent: true, jwtParseError: true };
+        }
+    }
+    constructor(options, cryptoService, sessionManager, storage) {
+        this.options = options;
+        this.cryptoService = cryptoService;
+        this.sessionManager = sessionManager;
+        this.storage = storage;
+        this.codec = new protobuf_codec_1.ProtobufCodec();
+        this.ws = null;
+        this.shouldReconnect = true;
+        this.reconnectTimer = null;
+        this.dropOnAirJwt = null;
+        this.currentUserId = null;
+        this.deviceId = null;
+        this.rateLimited = false;
+        this.reconnectAttempt = 0;
+        this.handlingJwtExpiry = false;
+        this.proactiveRefreshTimer = null;
+        this.visibilityChangeHandler = null;
+        this.deviceKeysCache = new Map();
+        // Call signaling
+        this.callListeners = new Set();
+        /** Pending startCall resolver, only one outgoing call can be in-flight at a time. */
+        this.pendingInviteResolve = null;
+        this.pendingInviteReject = null;
+        // Group messaging & calls
+        this.groupMessageListeners = new Set();
+        this.groupCallListeners = new Set();
+        /** Pending startGroupCall resolver. */
+        this.pendingGroupInviteResolve = null;
+        this.pendingGroupInviteReject = null;
+        this.messageListeners = new Set();
+        this.eventListeners = new Set();
+        this.broadcastListeners = new Set();
+        this.wsUrl = options.messagingWsUrl ?? 'wss://sdk.droponair.com/ws';
+        this.httpUrl = options.messagingHttpUrl ?? 'https://sdk.droponair.com';
+        this.tokenExchangeEndpoint = options.tokenExchangeEndpoint ?? '/api/messaging/token-exchange';
+        this.keyDirectoryEndpoint = options.keyDirectoryEndpoint ?? '/api/messaging/keys';
+        const providedFetch = options.fetchFn;
+        const globalFetch = typeof globalThis !== 'undefined' ? globalThis.fetch : undefined;
+        const resolvedFetch = providedFetch ?? globalFetch;
+        if (!resolvedFetch) {
+            throw new Error('Fetch API is not available in this environment');
+        }
+        this.fetchFn = ((input, init) => {
+            const fetchContext = typeof window !== 'undefined' ? window : globalThis;
+            return resolvedFetch.call(fetchContext, input, init);
+        });
+        this.autoAckIncomingMessages = options.autoAckIncomingMessages !== false;
+    }
+    async connect() {
+        this.log('connect_start');
+        this.shouldReconnect = true;
+        this.reconnectAttempt = 0;
+        this.registerVisibilityChangeHandler();
+        this.deviceId = await this.getOrCreateDeviceId();
+        await this.ensureIdentityPublished();
+        await this.connectWebSocket();
+        this.log('connect_done');
+    }
+    disconnect() {
+        this.shouldReconnect = false;
+        this.rateLimited = false;
+        this.reconnectAttempt = 0;
+        this.sessionManager.clear();
+        this.deviceKeysCache.clear();
+        this.unregisterVisibilityChangeHandler();
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.proactiveRefreshTimer) {
+            clearTimeout(this.proactiveRefreshTimer);
+            this.proactiveRefreshTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        this.emitEvent({ type: 'DISCONNECTED' });
+    }
+    async sendMessage(toUserId, plaintextMessage) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('DropOnAir websocket is not connected');
+        }
+        if (!this.currentUserId) {
+            throw new Error('Missing sender identity from DropOnAir JWT subject');
+        }
+        if (this.rateLimited) {
+            throw new Error('Sending is temporarily blocked by LIMIT_REACHED');
+        }
+        // Guard: if our cached JWT is already expired the server will reject this
+        // frame and close the connection (code 1008).  Fail fast here instead so
+        // the UI immediately shows a retryable FAILED state rather than leaving the
+        // message stuck in PENDING while we wait for the server to kick us off.
+        if (this.dropOnAirJwt && (0, bytes_1.isJwtExpired)(this.dropOnAirJwt)) {
+            throw new Error('JWT_EXPIRED: Secure messaging session is reconnecting; please retry in a moment');
+        }
+        const myDeviceId = this.deviceId ?? await this.getOrCreateDeviceId();
+        const messageId = crypto.randomUUID();
+        const timestamp = Date.now();
+        const myIdentity = await this.cryptoService.getOrCreateIdentity();
+        const myPublicKeyBytes = (0, bytes_1.fromBase64)(myIdentity.publicKey);
+        // Fetch all device keys for the recipient
+        const peerDeviceKeys = await this.fetchDeviceKeys(toUserId);
+        // Fetch my own other device keys for self-sync
+        const myOtherDeviceKeys = await this.fetchMyOtherDeviceKeys(myDeviceId);
+        // Determine whether to use multi-device envelopes or legacy
+        const allTargetKeys = [
+            ...peerDeviceKeys.map(dk => ({ ...dk, isRecipient: true })),
+            ...myOtherDeviceKeys.map(dk => ({ ...dk, isRecipient: false })),
+        ];
+        if (allTargetKeys.length > 0) {
+            // Multi-device path: encrypt once per device key
+            const devicePayloads = [];
+            for (const target of allTargetKeys) {
+                const peerUserIdForHkdf = target.isRecipient ? toUserId : this.currentUserId;
+                const sharedKey = await this.cryptoService.deriveSharedSecret(peerUserIdForHkdf, target.publicKey, this.currentUserId);
+                const encrypted = await this.cryptoService.encrypt(plaintextMessage, sharedKey, {
+                    messageId,
+                    senderId: this.currentUserId,
+                    recipientId: toUserId,
+                    timestamp
+                });
+                devicePayloads.push({
+                    deviceId: target.deviceId,
+                    encryptedPayload: encrypted,
+                    senderPublicKey: myPublicKeyBytes,
+                });
+            }
+            const envelope = {
+                messageId,
+                appId: this.options.appId,
+                fromUserId: this.currentUserId,
+                toUserId,
+                timestamp,
+                encryptedPayload: new Uint8Array(0),
+                clientMessageId: messageId,
+                devicePayloads,
+                senderDeviceId: myDeviceId,
+            };
+            this.ws.send(this.codec.encodeEnvelope(envelope));
+        }
+        else {
+            // Legacy fallback: peer has no device keys (old client)
+            const sharedKey = await this.getPeerSharedKey(toUserId);
+            const encryptedPayload = await this.cryptoService.encrypt(plaintextMessage, sharedKey, {
+                messageId,
+                senderId: this.currentUserId,
+                recipientId: toUserId,
+                timestamp
+            });
+            const envelope = {
+                messageId,
+                appId: this.options.appId,
+                fromUserId: this.currentUserId,
+                toUserId,
+                timestamp,
+                encryptedPayload,
+                clientMessageId: messageId
+            };
+            this.ws.send(this.codec.encodeEnvelope(envelope));
+        }
+        return { messageId };
+    }
+    async ack(messageId) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            return;
+        }
+        this.ws.send(this.codec.encodeAck({ messageId, type: 'PROCESSED' }));
+    }
+    onMessage(callback) {
+        this.messageListeners.add(callback);
+        return () => this.messageListeners.delete(callback);
+    }
+    onEvent(callback) {
+        this.eventListeners.add(callback);
+        return () => this.eventListeners.delete(callback);
+    }
+    // ---------------------------------------------------------------------------
+    // Cleartext messaging (no E2EE key exchange required)
+    // ---------------------------------------------------------------------------
+    async sendCleartextMessage(toUserId, plaintext) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('DropOnAir websocket is not connected');
+        }
+        if (!this.currentUserId) {
+            throw new Error('Missing sender identity from DropOnAir JWT subject');
+        }
+        if (this.rateLimited) {
+            throw new Error('Sending is temporarily blocked by LIMIT_REACHED');
+        }
+        if (this.dropOnAirJwt && (0, bytes_1.isJwtExpired)(this.dropOnAirJwt)) {
+            throw new Error('JWT_EXPIRED: Secure messaging session is reconnecting; please retry in a moment');
+        }
+        const messageId = crypto.randomUUID();
+        const envelope = {
+            messageId,
+            appId: this.options.appId,
+            fromUserId: this.currentUserId,
+            toUserId,
+            timestamp: Date.now(),
+            encryptedPayload: new Uint8Array(0),
+            clientMessageId: messageId,
+            encryptionType: 1, // CLEARTEXT
+            plaintextPayload: plaintext,
+        };
+        this.ws.send(this.codec.encodeEnvelope(envelope));
+        return { messageId };
+    }
+    // ---------------------------------------------------------------------------
+    // Broadcast / Pub-Sub
+    // ---------------------------------------------------------------------------
+    async subscribeBroadcast(channelId) {
+        const jwt = await this.getValidDropOnAirJwt(false);
+        const resp = await this.fetchFn(`${this.httpUrl}/v1/broadcast/channels/${encodeURIComponent(channelId)}/subscribe`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${jwt}` },
+        });
+        if (!resp.ok) {
+            throw new Error(`Failed to subscribe to broadcast channel: ${resp.status}`);
+        }
+    }
+    async unsubscribeBroadcast(channelId) {
+        const jwt = await this.getValidDropOnAirJwt(false);
+        const resp = await this.fetchFn(`${this.httpUrl}/v1/broadcast/channels/${encodeURIComponent(channelId)}/unsubscribe`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${jwt}` },
+        });
+        if (!resp.ok) {
+            throw new Error(`Failed to unsubscribe from broadcast channel: ${resp.status}`);
+        }
+    }
+    async publishBroadcast(channelId, plaintext) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('DropOnAir websocket is not connected');
+        }
+        if (!this.currentUserId) {
+            throw new Error('Missing sender identity from DropOnAir JWT subject');
+        }
+        if (this.rateLimited) {
+            throw new Error('Sending is temporarily blocked by LIMIT_REACHED');
+        }
+        const broadcastId = crypto.randomUUID();
+        const frame = {
+            broadcastId,
+            appId: this.options.appId,
+            channelId,
+            publisherId: this.currentUserId,
+            timestamp: Date.now(),
+            encryptionType: 1, // CLEARTEXT
+            encryptedPayload: new Uint8Array(0),
+            plaintextPayload: plaintext,
+            sequenceNumber: 0,
+        };
+        this.ws.send(this.codec.encodeBroadcastFrame(frame));
+        return { broadcastId };
+    }
+    onBroadcast(callback) {
+        this.broadcastListeners.add(callback);
+        return () => this.broadcastListeners.delete(callback);
+    }
+    onCallEvent(callback) {
+        this.callListeners.add(callback);
+        return () => this.callListeners.delete(callback);
+    }
+    // ---------------------------------------------------------------------------
+    // Group management (REST API)
+    // ---------------------------------------------------------------------------
+    async createGroup(name, memberUserIds) {
+        const jwt = await this.getValidDropOnAirJwt(false);
+        const res = await this.fetchFn(`${this.httpUrl}/api/groups`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ name, memberUserIds: memberUserIds ?? [] }),
+        });
+        if (!res.ok)
+            throw new Error(`createGroup failed (HTTP ${res.status})`);
+        return res.json();
+    }
+    async listGroups() {
+        const jwt = await this.getValidDropOnAirJwt(false);
+        const res = await this.fetchFn(`${this.httpUrl}/api/groups`, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${jwt}` },
+        });
+        if (!res.ok)
+            throw new Error(`listGroups failed (HTTP ${res.status})`);
+        return res.json();
+    }
+    async getGroup(groupId) {
+        const jwt = await this.getValidDropOnAirJwt(false);
+        const res = await this.fetchFn(`${this.httpUrl}/api/groups/${encodeURIComponent(groupId)}`, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${jwt}` },
+        });
+        if (!res.ok)
+            throw new Error(`getGroup failed (HTTP ${res.status})`);
+        return res.json();
+    }
+    async addGroupMembers(groupId, userIds) {
+        const jwt = await this.getValidDropOnAirJwt(false);
+        const res = await this.fetchFn(`${this.httpUrl}/api/groups/${encodeURIComponent(groupId)}/members`, {
+            method: 'PUT',
+            headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ userIds }),
+        });
+        if (!res.ok)
+            throw new Error(`addGroupMembers failed (HTTP ${res.status})`);
+        return res.json();
+    }
+    async removeGroupMember(groupId, userId) {
+        const jwt = await this.getValidDropOnAirJwt(false);
+        const res = await this.fetchFn(`${this.httpUrl}/api/groups/${encodeURIComponent(groupId)}/members/${encodeURIComponent(userId)}`, {
+            method: 'DELETE',
+            headers: { Authorization: `Bearer ${jwt}` },
+        });
+        if (!res.ok)
+            throw new Error(`removeGroupMember failed (HTTP ${res.status})`);
+        return res.json();
+    }
+    async deleteGroup(groupId) {
+        const jwt = await this.getValidDropOnAirJwt(false);
+        const res = await this.fetchFn(`${this.httpUrl}/api/groups/${encodeURIComponent(groupId)}`, {
+            method: 'DELETE',
+            headers: { Authorization: `Bearer ${jwt}` },
+        });
+        if (!res.ok)
+            throw new Error(`deleteGroup failed (HTTP ${res.status})`);
+    }
+    // ---------------------------------------------------------------------------
+    // Group messaging
+    // ---------------------------------------------------------------------------
+    async sendGroupMessage(groupId, plaintext) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('DropOnAir websocket is not connected');
+        }
+        if (!this.currentUserId) {
+            throw new Error('Missing sender identity from DropOnAir JWT subject');
+        }
+        if (this.rateLimited) {
+            throw new Error('Sending is temporarily blocked by LIMIT_REACHED');
+        }
+        if (this.dropOnAirJwt && (0, bytes_1.isJwtExpired)(this.dropOnAirJwt)) {
+            throw new Error('JWT_EXPIRED: Secure messaging session is reconnecting; please retry in a moment');
+        }
+        const myDeviceId = this.deviceId ?? await this.getOrCreateDeviceId();
+        const messageId = crypto.randomUUID();
+        const timestamp = Date.now();
+        // For now, group messages use cleartext (E2EE group fanout requires
+        // fetching device keys for every member, which is a future enhancement).
+        const frame = {
+            messageId,
+            groupId,
+            fromUserId: this.currentUserId,
+            senderDeviceId: myDeviceId,
+            memberPayloads: [],
+            encryptionType: 1, // CLEARTEXT
+            plaintextPayload: plaintext,
+            timestamp,
+        };
+        this.ws.send(this.codec.encodeGroupEnvelope(frame));
+        return { messageId };
+    }
+    onGroupMessage(callback) {
+        this.groupMessageListeners.add(callback);
+        return () => this.groupMessageListeners.delete(callback);
+    }
+    // ---------------------------------------------------------------------------
+    // Group call signaling
+    // ---------------------------------------------------------------------------
+    startGroupCall(groupId) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            return Promise.reject(new Error('DropOnAir websocket is not connected'));
+        }
+        return new Promise((resolve, reject) => {
+            this.pendingGroupInviteResolve = resolve;
+            this.pendingGroupInviteReject = reject;
+            const frame = { type: 'GROUP_CALL_INVITE', callId: '', groupId };
+            this.ws.send(this.codec.encodeGroupCallFrame(frame));
+        });
+    }
+    async joinGroupCall(callId, groupId) {
+        this.sendGroupCallFrame({ type: 'GROUP_CALL_JOIN', callId, groupId });
+    }
+    async leaveGroupCall(callId) {
+        this.sendGroupCallFrame({ type: 'GROUP_CALL_LEAVE', callId, groupId: '' });
+    }
+    async endGroupCall(callId) {
+        this.sendGroupCallFrame({ type: 'GROUP_CALL_END', callId, groupId: '' });
+    }
+    sendGroupCallSignal(type, callId, groupId, targetUserId, payload) {
+        this.sendGroupCallFrame({ type, callId, groupId, targetUserId, payload });
+    }
+    onGroupCallEvent(callback) {
+        this.groupCallListeners.add(callback);
+        return () => this.groupCallListeners.delete(callback);
+    }
+    sendGroupCallFrame(frame) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('DropOnAir websocket is not connected');
+        }
+        this.ws.send(this.codec.encodeGroupCallFrame(frame));
+    }
+    /**
+     * Initiate an outgoing call.
+     * Sends CALL_INVITE to the server; resolves with the server-assigned callId
+     * once the server echoes back CALL_RINGING (which contains the real callId).
+     */
+    startCall(targetUserId) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            return Promise.reject(new Error('DropOnAir websocket is not connected'));
+        }
+        return new Promise((resolve, reject) => {
+            this.pendingInviteResolve = resolve;
+            this.pendingInviteReject = reject;
+            const frame = { type: 'CALL_INVITE', targetUserId };
+            this.ws.send(this.codec.encodeCallFrame(frame));
+        });
+    }
+    async acceptCall(callId) {
+        this.sendCallFrame({ type: 'CALL_ACCEPTED', callId });
+    }
+    async rejectCall(callId) {
+        this.sendCallFrame({ type: 'CALL_REJECTED', callId });
+    }
+    async endCall(callId) {
+        this.sendCallFrame({ type: 'CALL_ENDED', callId });
+    }
+    toggleVideo(callId, enabled) {
+        this.sendCallFrame({ type: 'CALL_VIDEO_TOGGLE', callId, payload: JSON.stringify({ enabled }) });
+    }
+    sendCallSignal(type, callId, payload) {
+        this.sendCallFrame({ type, callId, payload });
+    }
+    async fetchTurnCredentials() {
+        const jwt = await this.getValidDropOnAirJwt(false);
+        const url = `${this.httpUrl}/api/v1/turn/credentials`;
+        const response = await this.fetchFn(url, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' }
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch TURN credentials (HTTP ${response.status})`);
+        }
+        return response.json();
+    }
+    sendCallFrame(frame) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('DropOnAir websocket is not connected');
+        }
+        this.ws.send(this.codec.encodeCallFrame(frame));
+    }
+    emitCallEvent(wire) {
+        // Resolve a pending startCall() promise when CALL_RINGING arrives.
+        if (wire.type === 'CALL_RINGING' && wire.callId && this.pendingInviteResolve) {
+            const resolve = this.pendingInviteResolve;
+            this.pendingInviteResolve = null;
+            this.pendingInviteReject = null;
+            resolve(wire.callId);
+        }
+        // Reject the pending startCall() promise when the server denies the call
+        // (e.g. CALLEE_OFFLINE, CALL_LIMIT_REACHED). Without this the promise
+        // would hang indefinitely.
+        if (wire.type === 'CALL_DENIED_LIMIT_REACHED' && this.pendingInviteReject) {
+            const reject = this.pendingInviteReject;
+            this.pendingInviteResolve = null;
+            this.pendingInviteReject = null;
+            reject(new Error(`CALL_DENIED:${wire.payload ?? ''}`));
+        }
+        const event = {
+            type: wire.type,
+            callId: wire.callId,
+            targetUserId: wire.targetUserId,
+            payload: wire.payload
+        };
+        for (const listener of this.callListeners) {
+            listener(event);
+        }
+    }
+    emitEvent(event) {
+        for (const listener of this.eventListeners) {
+            listener(event);
+        }
+    }
+    emitMessage(message) {
+        for (const listener of this.messageListeners) {
+            listener(message);
+        }
+    }
+    emitBroadcast(wire) {
+        const msg = {
+            broadcastId: wire.broadcastId,
+            channelId: wire.channelId,
+            publisherId: wire.publisherId,
+            timestamp: wire.timestamp,
+            plaintext: wire.plaintextPayload ?? '',
+            sequenceNumber: wire.sequenceNumber,
+        };
+        for (const listener of this.broadcastListeners) {
+            listener(msg);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Group message handling
+    // ---------------------------------------------------------------------------
+    async handleIncomingGroupMessage(notif) {
+        try {
+            this.log('incoming_group_message', {
+                messageId: notif.messageId,
+                groupId: notif.groupId,
+                fromUserId: notif.fromUserId,
+                encryptionType: notif.encryptionType,
+                hasDevicePayloads: !!(notif.devicePayloads && notif.devicePayloads.length > 0),
+            });
+            let plaintext;
+            if (notif.encryptionType === 1) {
+                // Cleartext
+                plaintext = notif.plaintextPayload ?? '';
+            }
+            else if (notif.devicePayloads && notif.devicePayloads.length > 0) {
+                // E2EE, find our device's payload
+                const myDeviceId = this.deviceId ?? await this.getOrCreateDeviceId();
+                const myPayload = notif.devicePayloads.find(dp => dp.deviceId === myDeviceId);
+                if (!myPayload) {
+                    this.log('incoming_group_message_no_device_payload', {
+                        messageId: notif.messageId,
+                        myDeviceId,
+                        availableDeviceIds: notif.devicePayloads.map(dp => dp.deviceId),
+                    });
+                    return;
+                }
+                const senderPublicKeyBase64 = (0, bytes_1.toBase64)(myPayload.senderPublicKey);
+                const peerUserIdForHkdf = notif.fromUserId === this.currentUserId
+                    ? this.currentUserId
+                    : notif.fromUserId;
+                const sharedKey = await this.cryptoService.deriveSharedSecret(peerUserIdForHkdf, senderPublicKeyBase64, this.currentUserId);
+                plaintext = await this.cryptoService.decrypt(myPayload.encryptedPayload, sharedKey, {
+                    messageId: notif.messageId,
+                    senderId: notif.fromUserId,
+                    recipientId: notif.groupId,
+                    timestamp: notif.timestamp,
+                });
+            }
+            else {
+                this.log('incoming_group_message_no_payload', { messageId: notif.messageId });
+                return;
+            }
+            const msg = {
+                messageId: notif.messageId,
+                groupId: notif.groupId,
+                fromUserId: notif.fromUserId,
+                timestamp: notif.timestamp,
+                plaintext,
+            };
+            for (const listener of this.groupMessageListeners) {
+                listener(msg);
+            }
+        }
+        catch (err) {
+            this.logError('incoming_group_message_error', {
+                messageId: notif.messageId,
+                error: String(err?.message ?? err),
+            });
+        }
+    }
+    emitGroupCallEvent(wire) {
+        // Resolve a pending startGroupCall() when RINGING arrives
+        if (wire.type === 'GROUP_CALL_RINGING' && wire.callId && this.pendingGroupInviteResolve) {
+            const resolve = this.pendingGroupInviteResolve;
+            this.pendingGroupInviteResolve = null;
+            this.pendingGroupInviteReject = null;
+            resolve(wire.callId);
+        }
+        if (wire.type === 'GROUP_CALL_ALREADY_ACTIVE' && this.pendingGroupInviteReject) {
+            const reject = this.pendingGroupInviteReject;
+            this.pendingGroupInviteResolve = null;
+            this.pendingGroupInviteReject = null;
+            reject(new Error(`GROUP_CALL_ALREADY_ACTIVE:${wire.payload ?? ''}`));
+        }
+        const event = {
+            type: wire.type,
+            callId: wire.callId,
+            groupId: wire.groupId,
+            targetUserId: wire.targetUserId,
+            payload: wire.payload,
+        };
+        for (const listener of this.groupCallListeners) {
+            listener(event);
+        }
+    }
+    async connectWebSocket() {
+        // Only exchange a fresh token when the cached one is absent or expired/near-expiry.
+        // forceRefresh=true on every reconnect caused a token-exchange call every 2 s.
+        this.dropOnAirJwt = await this.getValidDropOnAirJwt(false);
+        this.currentUserId = this.extractSubject(this.dropOnAirJwt);
+        if ((0, bytes_1.isJwtExpired)(this.dropOnAirJwt)) {
+            this.logError('ws_connect_jwt_expired', this.jwtSummary(this.dropOnAirJwt));
+            throw new Error('DropOnAir JWT expired before websocket connect');
+        }
+        this.log('ws_connect_start', {
+            wsUrl: this.wsUrl,
+            currentUserId: this.currentUserId,
+            ...this.jwtSummary(this.dropOnAirJwt),
+        });
+        await new Promise((resolve, reject) => {
+            const myDeviceId = this.deviceId;
+            let wsUrlWithParams = `${this.wsUrl}?token=${encodeURIComponent(this.dropOnAirJwt)}`;
+            if (myDeviceId) {
+                wsUrlWithParams += `&deviceId=${encodeURIComponent(myDeviceId)}`;
+            }
+            wsUrlWithParams += `&sdkVersion=${encodeURIComponent(version_1.SDK_VERSION)}`;
+            wsUrlWithParams += `&protocolVersion=${version_1.PROTOCOL_VERSION}`;
+            const ws = new WebSocket(wsUrlWithParams);
+            ws.binaryType = 'arraybuffer';
+            ws.onopen = () => {
+                this.ws = ws;
+                this.rateLimited = false;
+                this.log('ws_connected', { wsUrl: this.wsUrl });
+                this.emitEvent({ type: 'CONNECTED' });
+                // Schedule proactive token rotation before this JWT expires so we never
+                // send a message on a token the server will immediately reject.
+                if (this.dropOnAirJwt) {
+                    this.scheduleProactiveTokenRefresh(this.dropOnAirJwt);
+                }
+                this.fetchAndProcessOfflineMessages().catch((err) => {
+                    this.logError('offline_fetch_failed', { error: String(err?.message ?? err) });
+                    this.emitEvent({ type: 'ERROR', reason: 'OFFLINE_FETCH_FAILED' });
+                });
+                resolve();
+            };
+            ws.onerror = (event) => {
+                this.logError('ws_error', { wsUrl: this.wsUrl, eventType: event?.type });
+                reject(new Error('Failed to connect DropOnAir websocket'));
+            };
+            ws.onclose = (event) => {
+                this.ws = null;
+                this.handlingJwtExpiry = false;
+                // Cancel any pending proactive refresh, we are already disconnecting.
+                if (this.proactiveRefreshTimer) {
+                    clearTimeout(this.proactiveRefreshTimer);
+                    this.proactiveRefreshTimer = null;
+                }
+                // When the server closes with 1008 it means the JWT was expired at the
+                // time our frame arrived.  Emit an ERROR event first so any message that
+                // was sent just before the disconnect (and is therefore stuck in PENDING)
+                // gets marked FAILED and shown with a retry button in the UI.
+                if (event.code === 1008) {
+                    this.emitEvent({ type: 'ERROR', reason: 'JWT_EXPIRED' });
+                }
+                this.emitEvent({ type: 'DISCONNECTED' });
+                if (this.shouldReconnect) {
+                    const delay = this.reconnectDelayMs();
+                    this.log('ws_reconnect_scheduled', { attempt: this.reconnectAttempt, delayMs: delay });
+                    this.emitEvent({ type: 'RECONNECTING' });
+                    this.reconnectTimer = setTimeout(() => {
+                        this.connectWebSocket().then(() => {
+                            // Successful reconnect, reset backoff counter.
+                            this.reconnectAttempt = 0;
+                        }).catch(() => {
+                            this.emitEvent({ type: 'ERROR', reason: 'RECONNECT_FAILED' });
+                        });
+                    }, delay);
+                }
+            };
+            ws.onmessage = async (event) => {
+                if (!(event.data instanceof ArrayBuffer)) {
+                    return;
+                }
+                const frame = this.codec.decodeFrame(new Uint8Array(event.data));
+                if (frame.kind === 'event') {
+                    if (frame.data.type === 'LIMIT_REACHED') {
+                        this.rateLimited = true;
+                    }
+                    if (frame.data.type === 'ERROR' && frame.data.reason === 'JWT_EXPIRED') {
+                        this.dropOnAirJwt = null;
+                        this.currentUserId = null;
+                        this.rateLimited = false;
+                        if (!this.handlingJwtExpiry) {
+                            this.handlingJwtExpiry = true;
+                            this.log('ws_jwt_expired_received', {
+                                metadata: frame.data.metadata,
+                                wsState: this.ws?.readyState,
+                            });
+                            if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+                                this.ws.close(4001, 'JWT_EXPIRED');
+                            }
+                        }
+                    }
+                    this.emitEvent({
+                        type: frame.data.type,
+                        reason: frame.data.reason,
+                        metadata: frame.data.metadata
+                    });
+                    return;
+                }
+                if (frame.kind === 'ack') {
+                    this.emitEvent({
+                        type: frame.data.type,
+                        metadata: frame.data.messageId
+                    });
+                    return;
+                }
+                if (frame.kind === 'call') {
+                    this.emitCallEvent(frame.data);
+                    return;
+                }
+                if (frame.kind === 'groupCall') {
+                    this.emitGroupCallEvent(frame.data);
+                    return;
+                }
+                if (frame.kind === 'groupMessage') {
+                    await this.handleIncomingGroupMessage(frame.data);
+                    return;
+                }
+                if (frame.kind === 'groupAck') {
+                    this.emitEvent({
+                        type: frame.data.type,
+                        metadata: JSON.stringify({ messageId: frame.data.messageId, groupId: frame.data.groupId }),
+                    });
+                    return;
+                }
+                if (frame.kind === 'broadcast') {
+                    this.emitBroadcast(frame.data);
+                    return;
+                }
+                await this.handleIncomingEnvelope(frame.data);
+            };
+        });
+    }
+    async handleIncomingEnvelope(envelope) {
+        try {
+            this.log('incoming_envelope_received', {
+                messageId: envelope.messageId,
+                fromUserId: envelope.fromUserId,
+                toUserId: envelope.toUserId,
+                timestamp: envelope.timestamp,
+                hasDevicePayloads: !!(envelope.devicePayloads && envelope.devicePayloads.length > 0),
+                senderDeviceId: envelope.senderDeviceId,
+                autoAckIncomingMessages: this.autoAckIncomingMessages,
+            });
+            let plaintext;
+            // Cleartext path, no crypto needed
+            if (envelope.encryptionType === 1) {
+                plaintext = envelope.plaintextPayload ?? '';
+            }
+            else if (envelope.devicePayloads && envelope.devicePayloads.length > 0) {
+                const myDeviceId = this.deviceId ?? await this.getOrCreateDeviceId();
+                const myPayload = envelope.devicePayloads.find(dp => dp.deviceId === myDeviceId);
+                if (!myPayload) {
+                    this.log('incoming_envelope_no_device_payload', {
+                        messageId: envelope.messageId,
+                        myDeviceId,
+                        availableDeviceIds: envelope.devicePayloads.map(dp => dp.deviceId),
+                    });
+                    return; // Not intended for this device
+                }
+                const senderPublicKeyBase64 = (0, bytes_1.toBase64)(myPayload.senderPublicKey);
+                const isSelfSync = envelope.fromUserId === this.currentUserId;
+                // For HKDF context: when it's a self-sync message, peerUserId = myUserId so
+                // ordering becomes "myId:myId" on both send and receive sides.
+                const peerUserIdForHkdf = isSelfSync ? this.currentUserId : envelope.fromUserId;
+                const sharedKey = await this.cryptoService.deriveSharedSecret(peerUserIdForHkdf, senderPublicKeyBase64, this.currentUserId);
+                plaintext = await this.cryptoService.decrypt(myPayload.encryptedPayload, sharedKey, {
+                    messageId: envelope.messageId,
+                    senderId: envelope.fromUserId,
+                    recipientId: envelope.toUserId,
+                    timestamp: envelope.timestamp
+                });
+            }
+            else {
+                // Legacy single-payload path
+                const sharedKey = await this.getPeerSharedKey(envelope.fromUserId);
+                plaintext = await this.cryptoService.decrypt(envelope.encryptedPayload, sharedKey, {
+                    messageId: envelope.messageId,
+                    senderId: envelope.fromUserId,
+                    recipientId: envelope.toUserId,
+                    timestamp: envelope.timestamp
+                });
+            }
+            this.emitMessage({
+                messageId: envelope.messageId,
+                fromUserId: envelope.fromUserId,
+                toUserId: envelope.toUserId,
+                timestamp: envelope.timestamp,
+                plaintext
+            });
+            this.log('incoming_envelope_emitted', {
+                messageId: envelope.messageId,
+            });
+            if (this.autoAckIncomingMessages) {
+                await this.ack(envelope.messageId);
+                this.log('incoming_envelope_auto_acked', {
+                    messageId: envelope.messageId,
+                });
+            }
+        }
+        catch (error) {
+            this.logError('incoming_envelope_failed', {
+                messageId: envelope.messageId,
+                fromUserId: envelope.fromUserId,
+                toUserId: envelope.toUserId,
+                error: String(error?.message ?? error),
+            });
+            this.emitEvent({ type: 'ERROR', reason: 'DECRYPT_FAILED', metadata: envelope.messageId });
+        }
+    }
+    async getPeerSharedKey(peerUserId) {
+        if (!this.currentUserId) {
+            throw new Error('Current user identity is missing');
+        }
+        const userJwt = await this.options.getUserJwt();
+        const url = `${this.keyDirectoryEndpoint}/${encodeURIComponent(peerUserId)}`;
+        this.log('key_fetch_start', { url, peerUserId });
+        const response = await this.fetchFn(url, {
+            method: 'GET',
+            headers: this.backendHeaders(userJwt),
+        });
+        if (!response.ok) {
+            let errorBody = '';
+            try {
+                errorBody = await response.text();
+            }
+            catch { /* ignore */ }
+            this.logError('key_fetch_failed', {
+                url,
+                peerUserId,
+                status: response.status,
+                statusText: response.statusText,
+                responseBody: errorBody.slice(0, 400),
+            });
+            throw new Error(`Unable to fetch recipient public key from backend (HTTP ${response.status})`);
+        }
+        this.log('key_fetch_ok', { url, peerUserId, status: response.status });
+        const body = (await response.json());
+        const publicKey = body.publicKey;
+        if (!publicKey) {
+            throw new Error(`Recipient ${peerUserId} has no legacy public key available`);
+        }
+        return this.cryptoService.deriveSharedSecret(peerUserId, publicKey, this.currentUserId);
+    }
+    // ---------------------------------------------------------------------------
+    // Multi-device helpers
+    // ---------------------------------------------------------------------------
+    /** Get or create a persistent device UUID for this SDK instance. */
+    async getOrCreateDeviceId() {
+        const existing = await this.storage.get(STORAGE_DEVICE_ID);
+        if (existing) {
+            this.deviceId = existing;
+            return existing;
+        }
+        const id = crypto.randomUUID();
+        await this.storage.set(STORAGE_DEVICE_ID, id);
+        this.deviceId = id;
+        this.log('device_id_created', { deviceId: id });
+        return id;
+    }
+    /**
+     * Fetch all device keys for a given user (cached with short TTL).
+     * Falls back to wrapping the legacy single key into a device key entry.
+     */
+    async fetchDeviceKeys(userId) {
+        // Check cache
+        const cached = this.deviceKeysCache.get(userId);
+        if (cached && (Date.now() - cached.fetchedAt) < MessagingClient.DEVICE_KEYS_CACHE_TTL_MS) {
+            this.log('device_keys_cached', { userId, keyCount: cached.keys.length });
+            return cached.keys;
+        }
+        const userJwt = await this.options.getUserJwt();
+        const url = `${this.keyDirectoryEndpoint}/${encodeURIComponent(userId)}`;
+        this.log('device_keys_fetch_start', { url, userId });
+        const response = await this.fetchFn(url, {
+            method: 'GET',
+            headers: this.backendHeaders(userJwt),
+        });
+        if (!response.ok) {
+            let errorBody = '';
+            try {
+                errorBody = await response.text();
+            }
+            catch { /* ignore */ }
+            this.logError('device_keys_fetch_failed', {
+                url, userId, status: response.status, responseBody: errorBody.slice(0, 400),
+            });
+            throw new Error(`Unable to fetch device keys for ${userId} (HTTP ${response.status})`);
+        }
+        const body = (await response.json());
+        let keys = [];
+        // Prefer multi-device keys if available
+        if (body.deviceKeys && body.deviceKeys.length > 0) {
+            keys = body.deviceKeys;
+        }
+        else if (body.publicKey) {
+            // Legacy fallback: wrap single key as a synthetic device key
+            // No real deviceId available for legacy, empty array means the caller
+            // falls back to the legacy path in sendMessage
+            keys = [];
+        }
+        this.deviceKeysCache.set(userId, { keys, fetchedAt: Date.now() });
+        this.log('device_keys_fetch_ok', { userId, keyCount: keys.length });
+        return keys;
+    }
+    /**
+     * Fetch my own device keys and filter out the current device.
+     * Used for self-sync: encrypt sent messages for my other devices.
+     */
+    async fetchMyOtherDeviceKeys(myDeviceId) {
+        if (!this.currentUserId) {
+            return [];
+        }
+        try {
+            const allMyKeys = await this.fetchDeviceKeys(this.currentUserId);
+            return allMyKeys.filter(dk => dk.deviceId !== myDeviceId);
+        }
+        catch {
+            // If fetching my own keys fails, skip self-sync gracefully
+            this.log('self_sync_keys_fetch_failed', { myDeviceId });
+            return [];
+        }
+    }
+    async ensureIdentityPublished() {
+        const identity = await this.cryptoService.getOrCreateIdentity();
+        const myDeviceId = this.deviceId ?? await this.getOrCreateDeviceId();
+        const userJwt = await this.options.getUserJwt();
+        const url = `${this.keyDirectoryEndpoint}/me`;
+        this.log('key_publish_start', { url, publicKeyLength: identity.publicKey?.length, deviceId: myDeviceId, ...this.jwtSummary(userJwt) });
+        const response = await this.fetchFn(url, {
+            method: 'PUT',
+            headers: this.backendHeaders(userJwt),
+            body: JSON.stringify({ publicKey: identity.publicKey, deviceId: myDeviceId })
+        });
+        if (!response.ok) {
+            let errorBody = '';
+            try {
+                errorBody = await response.text();
+            }
+            catch { /* ignore */ }
+            this.logError('key_publish_failed', {
+                url,
+                status: response.status,
+                statusText: response.statusText,
+                responseBody: errorBody.slice(0, 400),
+            });
+            throw new Error(`Failed to publish identity key to backend (HTTP ${response.status})`);
+        }
+        this.log('key_publish_ok', { url, status: response.status, deviceId: myDeviceId });
+    }
+    async fetchAndProcessOfflineMessages() {
+        const jwt = await this.getValidDropOnAirJwt(false);
+        let page = 0;
+        let totalPages = 1;
+        let totalFetched = 0;
+        let totalProcessed = 0;
+        this.log('offline_fetch_started', {
+            httpUrl: this.httpUrl,
+            pageSize: 100,
+        });
+        while (page < totalPages) {
+            const response = await this.fetchFn(`${this.httpUrl}/v1/messages/offline?page=${page}&size=100`, {
+                method: 'GET',
+                headers: {
+                    Authorization: `Bearer ${jwt}`,
+                    'Content-Type': 'application/json'
+                }
+            });
+            if (!response.ok) {
+                this.logError('offline_fetch_page_failed', {
+                    page,
+                    status: response.status,
+                    statusText: response.statusText,
+                });
+                return;
+            }
+            const body = (await response.json());
+            totalPages = Math.max(body.totalPages || 1, 1);
+            totalFetched += body.messages.length;
+            this.log('offline_fetch_page_ok', {
+                page,
+                pageSize: body.size,
+                pageMessages: body.messages.length,
+                totalElements: body.totalElements,
+                totalPages,
+            });
+            for (const offline of body.messages) {
+                const wireEnvelope = {
+                    messageId: offline.messageId,
+                    appId: offline.appId,
+                    fromUserId: offline.fromUserId,
+                    toUserId: offline.toUserId,
+                    timestamp: new Date(offline.createdAt).getTime(),
+                    encryptedPayload: offline.encryptedPayloadBase64 ? (0, bytes_1.fromBase64)(offline.encryptedPayloadBase64) : new Uint8Array(0),
+                    encryptionType: offline.encryptionType === 'CLEARTEXT' ? 1 : 0,
+                    plaintextPayload: offline.plaintextPayload,
+                };
+                // Multi-device offline payloads
+                if (offline.devicePayloads && offline.devicePayloads.length > 0) {
+                    wireEnvelope.devicePayloads = offline.devicePayloads.map(dp => ({
+                        deviceId: dp.deviceId,
+                        encryptedPayload: (0, bytes_1.fromBase64)(dp.encryptedPayloadBase64),
+                        senderPublicKey: (0, bytes_1.fromBase64)(dp.senderPublicKeyBase64),
+                    }));
+                    wireEnvelope.senderDeviceId = offline.senderDeviceId;
+                }
+                await this.handleIncomingEnvelope(wireEnvelope);
+                totalProcessed += 1;
+            }
+            page += 1;
+        }
+        this.log('offline_fetch_completed', {
+            fetchedMessages: totalFetched,
+            processedMessages: totalProcessed,
+            pagesFetched: page,
+        });
+    }
+    async getValidDropOnAirJwt(forceRefresh) {
+        if (!forceRefresh
+            && this.dropOnAirJwt
+            && !(0, bytes_1.isJwtExpired)(this.dropOnAirJwt)
+            && !this.isJwtExpiringSoon(this.dropOnAirJwt, 30)) {
+            this.log('token_exchange_skipped', { reason: 'cached_jwt_still_valid', ...this.jwtSummary(this.dropOnAirJwt) });
+            return this.dropOnAirJwt;
+        }
+        const userJwt = await this.options.getUserJwt();
+        const url = this.tokenExchangeEndpoint;
+        this.log('token_exchange_start', {
+            url,
+            appId: this.options.appId,
+            publicApiKeyPrefix: this.options.publicApiKey?.slice(0, 10),
+            forceRefresh,
+            ...this.jwtSummary(userJwt),
+        });
+        let response;
+        try {
+            response = await this.fetchFn(url, {
+                method: 'POST',
+                headers: {
+                    ...this.backendHeaders(userJwt),
+                    'X-SDK-Version': version_1.SDK_VERSION,
+                },
+                body: JSON.stringify({
+                    appId: this.options.appId,
+                    publicApiKey: this.options.publicApiKey
+                })
+            });
+        }
+        catch (err) {
+            this.logError('token_exchange_fetch_threw', {
+                url,
+                error: String(err?.message ?? err),
+            });
+            throw new Error(`Token exchange network error: ${err?.message ?? String(err)}`);
+        }
+        if (!response.ok) {
+            let errorBody = '';
+            try {
+                errorBody = await response.text();
+            }
+            catch { /* ignore */ }
+            this.logError('token_exchange_failed', {
+                url,
+                status: response.status,
+                statusText: response.statusText,
+                responseBody: errorBody.slice(0, 800),
+            });
+            throw new Error(`Token exchange failed (HTTP ${response.status}): ${errorBody.slice(0, 200)}`);
+        }
+        const payload = (await response.json());
+        const token = payload.accessToken ?? payload.token;
+        if (!token) {
+            this.logError('token_exchange_missing_token', { url, payloadKeys: Object.keys(payload) });
+            throw new Error('Token exchange response missing accessToken');
+        }
+        if ((0, bytes_1.isJwtExpired)(token)) {
+            this.logError('token_exchange_received_expired_jwt', { url, ...this.jwtSummary(token) });
+            throw new Error('Received expired DropOnAir JWT');
+        }
+        this.dropOnAirJwt = token;
+        this.currentUserId = this.extractSubject(token);
+        this.log('token_exchange_ok', { url, currentUserId: this.currentUserId, expiresIn: payload.expiresIn });
+        return token;
+    }
+    extractSubject(token) {
+        const payload = (0, bytes_1.parseJwtPayload)(token);
+        const sub = payload.sub;
+        if (typeof sub !== 'string' || !sub) {
+            throw new Error('DropOnAir JWT does not contain subject (sub)');
+        }
+        return sub;
+    }
+    isJwtExpiringSoon(jwt, thresholdSeconds) {
+        try {
+            const payload = (0, bytes_1.parseJwtPayload)(jwt);
+            const exp = Number(payload.exp ?? 0);
+            if (!Number.isFinite(exp) || exp <= 0) {
+                return true;
+            }
+            const nowSeconds = Math.floor(Date.now() / 1000);
+            return nowSeconds + thresholdSeconds >= exp;
+        }
+        catch {
+            return true;
+        }
+    }
+}
+exports.MessagingClient = MessagingClient;
+// Multi-device: cached device keys per user with TTL
+MessagingClient.DEVICE_KEYS_CACHE_TTL_MS = 60000;