@droponair/sdk-js 0.19.0 → 0.22.0

package/dist/core/messaging-client.js

@@ -3,6 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MessagingClient = void 0;
 const bytes_1 = require("./bytes");
 const protobuf_codec_1 = require("../transport/protobuf-codec");
+const auto_select_1 = require("../transport/auto-select");
+const ws_messaging_transport_1 = require("../transport/ws-messaging-transport");
+const sse_messaging_transport_1 = require("../transport/sse-messaging-transport");
+const wt_messaging_transport_1 = require("../transport/wt-messaging-transport");
 const version_1 = require("../version");
 const attachment_client_1 = require("../attachment/attachment-client");
 const STORAGE_DEVICE_ID = 'droponair.device.id.v1';
@@ -56,7 +60,7 @@ class MessagingClient {
      */
     onAppForeground() {
         this.log('app_foreground_detected', {
-            wsState: this.ws?.readyState,
+            wsState: (this.transport?.isOpen() ? 'OPEN' : 'CLOSED'),
             shouldReconnect: this.shouldReconnect,
             ...this.jwtSummary(this.dropOnAirJwt),
         });
@@ -65,21 +69,21 @@ class MessagingClient {
         }
         // 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) {
+        if (!this.transport?.isOpen()) {
             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');
+            this.transport.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');
+            this.transport.close(1000, 'FOREGROUND_JWT_EXPIRED');
             return;
         }
         // Token is still valid, reschedule the proactive timer based on actual
@@ -113,7 +117,7 @@ class MessagingClient {
             this.log('proactive_refresh_scheduled', { exp, secondsUntilExpiry, rotateInSeconds });
             this.proactiveRefreshTimer = setTimeout(async () => {
                 this.proactiveRefreshTimer = null;
-                if (!this.shouldReconnect || !this.ws) {
+                if (!this.shouldReconnect || !this.transport) {
                     return;
                 }
                 this.log('proactive_refresh_triggered', { exp });
@@ -125,8 +129,8 @@ class MessagingClient {
                     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');
+                if (this.transport?.isOpen()) {
+                    this.transport.close(1000, 'PROACTIVE_TOKEN_REFRESH');
                 }
             }, rotateInSeconds * 1000);
         }
@@ -193,7 +197,8 @@ class MessagingClient {
         this.sessionManager = sessionManager;
         this.storage = storage;
         this.codec = new protobuf_codec_1.ProtobufCodec();
-        this.ws = null;
+        this.transport = null;
+        this.resolvedTransportName = null;
         this.shouldReconnect = true;
         this.reconnectTimer = null;
         this.dropOnAirJwt = null;
@@ -308,14 +313,14 @@ class MessagingClient {
             clearTimeout(this.proactiveRefreshTimer);
             this.proactiveRefreshTimer = null;
         }
-        if (this.ws) {
-            this.ws.close();
-            this.ws = null;
+        if (this.transport) {
+            this.transport.close();
+            this.transport = null;
         }
         this.emitEvent({ type: 'DISCONNECTED' });
     }
     async sendMessage(toUserId, plaintextMessage, options) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
         if (!this.currentUserId) {
@@ -377,7 +382,7 @@ class MessagingClient {
             if (options?.attachments && options.attachments.length > 0) {
                 envelope.attachments = options.attachments.map(a => this.attachmentClient.toWire(a));
             }
-            this.ws.send(this.codec.encodeEnvelope(envelope));
+            this.transport.send(this.codec.encodeEnvelope(envelope));
         }
         else {
             // Legacy fallback: peer has no device keys (old client)
@@ -400,15 +405,15 @@ class MessagingClient {
             if (options?.attachments && options.attachments.length > 0) {
                 envelope.attachments = options.attachments.map(a => this.attachmentClient.toWire(a));
             }
-            this.ws.send(this.codec.encodeEnvelope(envelope));
+            this.transport.send(this.codec.encodeEnvelope(envelope));
         }
         return { messageId };
     }
     async ack(messageId) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             return;
         }
-        this.ws.send(this.codec.encodeAck({ messageId, type: 'PROCESSED' }));
+        this.transport.send(this.codec.encodeAck({ messageId, type: 'PROCESSED' }));
     }
     onMessage(callback) {
         this.messageListeners.add(callback);
@@ -439,7 +444,7 @@ class MessagingClient {
     // Message edit and delete (PROTOCOL_VERSION 3+)
     // ---------------------------------------------------------------------------
     async editMessage(originalMessageId, toUserId, newPlaintext) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
         if (!this.currentUserId) {
@@ -496,11 +501,11 @@ class MessagingClient {
             senderDeviceId: myDeviceId,
             clientEditId: editId,
         };
-        this.ws.send(this.codec.encodeMessageEditFrame(frame));
+        this.transport.send(this.codec.encodeMessageEditFrame(frame));
         return { editId };
     }
     async editCleartextMessage(originalMessageId, toUserId, newPlaintext) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
         if (!this.currentUserId) {
@@ -522,11 +527,11 @@ class MessagingClient {
             plaintextPayload: newPlaintext,
             clientEditId: editId,
         };
-        this.ws.send(this.codec.encodeMessageEditFrame(frame));
+        this.transport.send(this.codec.encodeMessageEditFrame(frame));
         return { editId };
     }
     async deleteMessage(originalMessageId, toUserId, scope) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
         if (!this.currentUserId) {
@@ -547,7 +552,7 @@ class MessagingClient {
             scope,
             clientDeleteId: deleteId,
         };
-        this.ws.send(this.codec.encodeMessageDeleteFrame(frame));
+        this.transport.send(this.codec.encodeMessageDeleteFrame(frame));
         return { deleteId };
     }
     // ---------------------------------------------------------------------------
@@ -567,7 +572,7 @@ class MessagingClient {
      * stored token and refreshes its lastSeenAt timestamp.
      */
     async registerPushToken(opts) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
         if (!opts.token || opts.token.trim().length === 0) {
@@ -581,14 +586,14 @@ class MessagingClient {
             voipToken: opts.voipToken ?? '',
             deviceId,
         };
-        this.ws.send(this.codec.encodePushRegistrationFrame(frame));
+        this.transport.send(this.codec.encodePushRegistrationFrame(frame));
     }
     /**
      * Unregister this device's push notification token (e.g. on logout). Future
      * push fan-out for this (appId, userId, deviceId, platform) tuple is dropped.
      */
     async unregisterPushToken(opts) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
         const deviceId = this.deviceId ?? await this.getOrCreateDeviceId();
@@ -599,7 +604,7 @@ class MessagingClient {
             voipToken: '',
             deviceId,
         };
-        this.ws.send(this.codec.encodePushRegistrationFrame(frame));
+        this.transport.send(this.codec.encodePushRegistrationFrame(frame));
     }
     // ---------------------------------------------------------------------------
     // Device trust (PROTOCOL_VERSION 5+ / Phase 2b)
@@ -650,8 +655,8 @@ class MessagingClient {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
-        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
-            this.ws.close(4001, 'DEVICE_REVOKED');
+        if (this.transport?.isOpen()) {
+            this.transport.close(4001, 'DEVICE_REVOKED');
         }
     }
     // ---------------------------------------------------------------------------
@@ -671,7 +676,7 @@ class MessagingClient {
      *                        other devices so they can bucket the receipt
      */
     markRead(messageId, conversationId) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
         const frame = {
@@ -680,7 +685,7 @@ class MessagingClient {
             conversationId: conversationId ?? '',
             timestamp: Date.now(),
         };
-        this.ws.send(this.codec.encodeSyncFrame(frame));
+        this.transport.send(this.codec.encodeSyncFrame(frame));
     }
     /**
      * Tell this user's other devices that the notification(s) for a
@@ -689,7 +694,7 @@ class MessagingClient {
      * the matching badge. The relay never decides what "dismissed" means.
      */
     clearNotification(conversationId) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
         const frame = {
@@ -698,7 +703,7 @@ class MessagingClient {
             conversationId,
             timestamp: Date.now(),
         };
-        this.ws.send(this.codec.encodeSyncFrame(frame));
+        this.transport.send(this.codec.encodeSyncFrame(frame));
     }
     /**
      * Push the current draft text for a conversation to this user's other
@@ -708,7 +713,7 @@ class MessagingClient {
      * feature is disabled the server silently drops the frame.
      */
     syncDraft(conversationId, draftText) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
         const frame = {
@@ -718,7 +723,7 @@ class MessagingClient {
             timestamp: Date.now(),
             payload: draftText,
         };
-        this.ws.send(this.codec.encodeSyncFrame(frame));
+        this.transport.send(this.codec.encodeSyncFrame(frame));
     }
     /** Register a listener for notification-clear syncs from the user's other devices. */
     onNotificationCleared(callback) {
@@ -775,7 +780,7 @@ class MessagingClient {
     // Cleartext messaging (no E2EE key exchange required)
     // ---------------------------------------------------------------------------
     async sendCleartextMessage(toUserId, plaintext) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
         if (!this.currentUserId) {
@@ -799,7 +804,7 @@ class MessagingClient {
             encryptionType: 1, // CLEARTEXT
             plaintextPayload: plaintext,
         };
-        this.ws.send(this.codec.encodeEnvelope(envelope));
+        this.transport.send(this.codec.encodeEnvelope(envelope));
         return { messageId };
     }
     // ---------------------------------------------------------------------------
@@ -826,7 +831,7 @@ class MessagingClient {
         }
     }
     async publishBroadcast(channelId, plaintext) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
         if (!this.currentUserId) {
@@ -847,7 +852,7 @@ class MessagingClient {
             plaintextPayload: plaintext,
             sequenceNumber: 0,
         };
-        this.ws.send(this.codec.encodeBroadcastFrame(frame));
+        this.transport.send(this.codec.encodeBroadcastFrame(frame));
         return { broadcastId };
     }
     onBroadcast(callback) {
@@ -1060,12 +1065,12 @@ class MessagingClient {
      * call joinRoom again).
      */
     joinRoom(roomId) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             return Promise.reject(new Error('DropOnAir websocket is not connected'));
         }
         return new Promise((resolve, reject) => {
             this.pendingRoomJoins.set(roomId, { resolve, reject });
-            this.ws.send(this.codec.encodeGroupCallFrame({
+            this.transport.send(this.codec.encodeGroupCallFrame({
                 type: 'GROUP_CALL_JOIN',
                 callId: '',
                 groupId: '',
@@ -1092,7 +1097,7 @@ class MessagingClient {
      * {@link sendCleartextGroupMessage} instead.
      */
     async sendGroupMessage(groupId, plaintext, memberUserIds, options) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
         if (!this.currentUserId) {
@@ -1170,7 +1175,7 @@ class MessagingClient {
         if (options?.attachments && options.attachments.length > 0) {
             frame.attachments = options.attachments.map(a => this.attachmentClient.toWire(a));
         }
-        this.ws.send(this.codec.encodeGroupEnvelope(frame));
+        this.transport.send(this.codec.encodeGroupEnvelope(frame));
         return { messageId };
     }
     /**
@@ -1182,7 +1187,7 @@ class MessagingClient {
      * per-recipient before sending.
      */
     async sendCleartextGroupMessage(groupId, plaintext) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
         if (!this.currentUserId) {
@@ -1209,7 +1214,7 @@ class MessagingClient {
             plaintextPayload: plaintext,
             memberPayloads: [],
         };
-        this.ws.send(this.codec.encodeGroupEnvelope(frame));
+        this.transport.send(this.codec.encodeGroupEnvelope(frame));
         return { messageId };
     }
     onGroupMessage(callback) {
@@ -1220,14 +1225,14 @@ class MessagingClient {
     // Group call signaling
     // ---------------------------------------------------------------------------
     startGroupCall(groupId) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             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));
+            this.transport.send(this.codec.encodeGroupCallFrame(frame));
         });
     }
     async joinGroupCall(callId, groupId) {
@@ -1382,10 +1387,10 @@ class MessagingClient {
         this.sendGroupCallFrame({ type: 'GROUP_CALL_RECORDING_AVAILABLE', callId, groupId: '', payload: location });
     }
     sendGroupCallFrame(frame) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
-        this.ws.send(this.codec.encodeGroupCallFrame(frame));
+        this.transport.send(this.codec.encodeGroupCallFrame(frame));
     }
     /**
      * Initiate an outgoing call.
@@ -1393,14 +1398,14 @@ class MessagingClient {
      * once the server echoes back CALL_RINGING (which contains the real callId).
      */
     startCall(targetUserId) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             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));
+            this.transport.send(this.codec.encodeCallFrame(frame));
         });
     }
     async acceptCall(callId) {
@@ -1437,10 +1442,10 @@ class MessagingClient {
         return response.json();
     }
     sendCallFrame(frame) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.transport?.isOpen()) {
             throw new Error('DropOnAir websocket is not connected');
         }
-        this.ws.send(this.codec.encodeCallFrame(frame));
+        this.transport.send(this.codec.encodeCallFrame(frame));
     }
     emitCallEvent(wire) {
         // Resolve a pending startCall() promise when CALL_RINGING arrives.
@@ -1598,6 +1603,44 @@ class MessagingClient {
             listener(event);
         }
     }
+    async resolveTransport(jwt) {
+        const selection = this.options.transport ?? 'ws';
+        let chosen = 'ws';
+        if (selection === 'auto') {
+            try {
+                const lane = await (0, auto_select_1.selectTransport)({ httpUrl: this.httpUrl, fetchFn: this.fetchFn });
+                chosen = lane === 'webtransport' ? 'wt' : lane === 'sse' ? 'sse' : 'ws';
+            }
+            catch (err) {
+                this.logError('transport_auto_select_failed', { error: String(err?.message ?? err) });
+                chosen = 'ws';
+            }
+        }
+        else {
+            chosen = selection;
+        }
+        this.resolvedTransportName = chosen;
+        if (chosen === 'sse') {
+            return new sse_messaging_transport_1.SseMessagingTransport({
+                httpUrl: this.httpUrl,
+                getJwt: async () => jwt,
+                fetchFn: this.fetchFn,
+            });
+        }
+        if (chosen === 'wt') {
+            return new wt_messaging_transport_1.WtMessagingTransport({
+                httpUrl: this.httpUrl,
+                getJwt: async () => jwt,
+            });
+        }
+        const myDeviceId = this.deviceId;
+        let wsUrlWithParams = `${this.wsUrl}?token=${encodeURIComponent(jwt)}`;
+        if (myDeviceId)
+            wsUrlWithParams += `&deviceId=${encodeURIComponent(myDeviceId)}`;
+        wsUrlWithParams += `&sdkVersion=${encodeURIComponent(version_1.SDK_VERSION)}`;
+        wsUrlWithParams += `&protocolVersion=${version_1.PROTOCOL_VERSION}`;
+        return new ws_messaging_transport_1.WebSocketMessagingTransport(wsUrlWithParams);
+    }
     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.
@@ -1607,28 +1650,21 @@ class MessagingClient {
             this.logError('ws_connect_jwt_expired', this.jwtSummary(this.dropOnAirJwt));
             throw new Error('DropOnAir JWT expired before websocket connect');
         }
+        const transport = await this.resolveTransport(this.dropOnAirJwt);
         this.log('ws_connect_start', {
+            transport: this.resolvedTransportName,
             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;
+            let opened = false;
+            transport.onOpen(() => {
+                this.transport = transport;
+                opened = true;
                 this.rateLimited = false;
-                this.log('ws_connected', { wsUrl: this.wsUrl });
+                this.log('ws_connected', { transport: this.resolvedTransportName, 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);
                 }
@@ -1637,24 +1673,22 @@ class MessagingClient {
                     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;
+            });
+            transport.onError((err) => {
+                this.logError('ws_error', { wsUrl: this.wsUrl, error: err.message });
+                if (!opened) {
+                    reject(new Error('Failed to connect DropOnAir websocket'));
+                }
+            });
+            transport.onClose((info) => {
+                this.transport = 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) {
+                // 1008 = server-side JWT expiry; surface so PENDING sends can FAIL.
+                if (info.code === 1008) {
                     this.emitEvent({ type: 'ERROR', reason: 'JWT_EXPIRED' });
                 }
                 this.emitEvent({ type: 'DISCONNECTED' });
@@ -1664,19 +1698,15 @@ class MessagingClient {
                     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));
+            });
+            transport.onFrame(async (bytes) => {
+                const frame = this.codec.decodeFrame(bytes);
                 if (frame.kind === 'event') {
                     if (frame.data.type === 'LIMIT_REACHED') {
                         this.rateLimited = true;
@@ -1693,10 +1723,10 @@ class MessagingClient {
                             this.handlingJwtExpiry = true;
                             this.log('ws_jwt_expired_received', {
                                 metadata: frame.data.metadata,
-                                wsState: this.ws?.readyState,
+                                wsState: (this.transport?.isOpen() ? 'OPEN' : 'CLOSED'),
                             });
-                            if (this.ws && this.ws.readyState === WebSocket.OPEN) {
-                                this.ws.close(4001, 'JWT_EXPIRED');
+                            if (this.transport?.isOpen()) {
+                                this.transport.close(4001, 'JWT_EXPIRED');
                             }
                         }
                     }
@@ -1752,7 +1782,13 @@ class MessagingClient {
                 if (frame.kind === 'envelope') {
                     await this.handleIncomingEnvelope(frame.data);
                 }
-            };
+            });
+            transport.connect().catch((err) => {
+                if (!opened) {
+                    this.logError('ws_error', { wsUrl: this.wsUrl, error: String(err?.message ?? err) });
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                }
+            });
         });
     }
     async handleIncomingMessageEdit(frame) {

package/dist/core/types.d.ts

@@ -276,6 +276,14 @@ export interface InitializeOptions {
      * Set false to let app decide when a message is actually seen/read and call `ack(messageId)` manually.
      */
     autoAckIncomingMessages?: boolean;
+    /**
+     * Signaling transport lane. WebSocket (`'ws'`) is the default and works on
+     * every network. `'sse'` uses HTTP fallback for restrictive corporate
+     * networks. `'wt'` uses WebTransport (HTTP/3) where browsers support it.
+     * `'auto'` queries `GET /api/info.transports` and picks the best available
+     * lane from the runtime. The platform never enforces a choice.
+     */
+    transport?: 'ws' | 'sse' | 'wt' | 'auto';
 }
 /** A registered device as returned by {@link DropOnAirClient.listMyDevices}. */
 export interface DeviceInfo {

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export declare function initialize(options: InitializeOptions): Promise<DropOnAi
 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 { 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';
+export { selectTransport, type TransportLane, type SelectTransportOptions, } from './transport/auto-select';
 declare const _default: {
     initialize: typeof initialize;
 };

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SseTransport = exports.PAYLOAD_FORMAT_VERSION = exports.PROTOCOL_VERSION = exports.SDK_VERSION = void 0;
+exports.selectTransport = exports.WebTransportTransport = exports.SseTransport = exports.PAYLOAD_FORMAT_VERSION = exports.PROTOCOL_VERSION = exports.SDK_VERSION = void 0;
 exports.initialize = initialize;
 const messaging_client_1 = require("./core/messaging-client");
 const session_manager_1 = require("./core/session-manager");
@@ -29,4 +29,10 @@ async function initialize(options) {
 // Phase 4.2.1: HTTP fallback lane primitive for restrictive networks.
 var sse_transport_1 = require("./transport/sse-transport");
 Object.defineProperty(exports, "SseTransport", { enumerable: true, get: function () { return sse_transport_1.SseTransport; } });
+// Phase 4.3: WebTransport (HTTP/3) lane primitive.
+var webtransport_transport_1 = require("./transport/webtransport-transport");
+Object.defineProperty(exports, "WebTransportTransport", { enumerable: true, get: function () { return webtransport_transport_1.WebTransportTransport; } });
+// Phase 4.6: transport auto-select - intersects runtime + platform support.
+var auto_select_1 = require("./transport/auto-select");
+Object.defineProperty(exports, "selectTransport", { enumerable: true, get: function () { return auto_select_1.selectTransport; } });
 exports.default = { initialize };

package/dist/transport/auto-select.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Transport auto-select (Phase 4.6).
+ *
+ * Tiny helper that probes which transport lanes the runtime AND the platform
+ * BOTH support, and returns the best one for this client/host pair.
+ *
+ * Preference order (best -> fallback):
+ *   1. webtransport - multi-stream, lower head-of-line blocking
+ *   2. websocket    - universal default
+ *   3. sse          - HTTP-only fallback for restrictive networks
+ *
+ * The function fetches `<httpUrl>/api/info` once, intersects its
+ * `transports` array with the runtime's capabilities, and returns the
+ * highest-preference match. Caller then instantiates the corresponding
+ * primitive (`WebTransportTransport` / WebSocket / `SseTransport`) and
+ * uses it as their lane.
+ *
+ * @example
+ * ```ts
+ * import { selectTransport, WebTransportTransport, SseTransport } from '@droponair/sdk-js';
+ * const lane = await selectTransport({ httpUrl: 'https://sdk.droponair.com' });
+ * switch (lane) {
+ *   case 'webtransport': // construct WebTransportTransport break;
+ *   case 'sse':          // construct SseTransport          break;
+ *   default:             // fall through to WebSocket
+ * }
+ * ```
+ */
+export type TransportLane = 'webtransport' | 'websocket' | 'sse';
+export interface SelectTransportOptions {
+    /** Base URL of the platform's REST API (no trailing slash). */
+    httpUrl: string;
+    /**
+     * Override the default WT -> WS -> SSE preference order. Useful for tests
+     * or when a specific lane is preferred (e.g. force `sse` first on a known
+     * firewalled network).
+     */
+    preference?: TransportLane[];
+    /** Custom fetch impl, useful for Node polyfills + test doubles. */
+    fetchFn?: typeof fetch;
+}
+/**
+ * Returns the highest-preference transport lane available on BOTH the
+ * runtime and the platform. Throws if no lane is supported (extremely
+ * unusual; WebSocket is the universal floor).
+ */
+export declare function selectTransport(options: SelectTransportOptions): Promise<TransportLane>;