@droponair/sdk-js 0.21.0 → 0.22.1

package/CHANGELOG.md

@@ -6,15 +6,36 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.22.1], 2026-05-31
+
+### Fixed
+
+- **Message send/receive broken when attachments support is compiled in.** The protobuf reflection tree shared a single `AttachmentRef` type instance across `Envelope`, `GroupEnvelope`, and `GroupMessageNotification`. Because a protobufjs reflection object can have only one parent, adding it to a later message re-parented it and removed it from `Envelope`, so encoding any 1:1 message threw `no such Type or Enum 'AttachmentRef' in Type Envelope` before a frame was ever produced. Each message now builds its own `AttachmentRef` (and nested `DeviceWrappedKey` / `EncryptionType`) instance. Wire format is unchanged, this is purely a client-side construction fix. Also resolves the same latent failure on `GroupMessageNotification` decode.
+
+---
+
+## [0.22.0], 2026-05-25
+
+### Added
+
+- **MessagingClient transport selection.** `initialize({ transport: 'ws' | 'sse' | 'wt' | 'auto' })` lets your app choose the signaling lane at init time. Default stays `'ws'`, so existing integrations are byte-identical. `'auto'` queries `GET /api/info.transports` and picks the best available lane from what the runtime supports. WebSocket close-code semantics (1008 JWT-expiry surfacing, 4001 JWT-refresh-on-event) are preserved on the WebSocket path; SSE/WT synthesize close events.
+- **MQTT (IoT) broadcast lane.** Broadcasts now mirror to MQTT topic `droponair/v1/broadcast/{appId}/{channelId}` on `mqtts://mqtt.droponair.com:8883`. For IoT subscribers that consume your broadcasts without our full SDK. Subscribe-only, per-app credentials, TLS only. Visible via `GET /api/info` (`transports` includes `"mqtt"`, `features` includes `"transport_mqtt"`). No SDK API change, the lane is consumed directly by MQTT clients.
+
+### Changed
+
+- `MessagingClient` now uses an internal `MessagingTransport` adapter rather than a direct `WebSocket` reference. WebSocket remains the default; no protocol change. Adapters: `WebSocketMessagingTransport` (default), `SseMessagingTransport`, `WtMessagingTransport`.
+
+---
+
 ## [0.21.0], 2026-05-24
 
 ### Added
 
-- **Transport auto-select helper (Phase 4.6).** New `selectTransport({ httpUrl })` reads `/api/info.transports`, intersects with the runtime's `WebTransport`/`WebSocket`/`EventSource` availability, and returns the best lane (preference: WebTransport -> WebSocket -> SSE; overridable via `preference`). Caller then constructs the corresponding primitive. Pluggable `fetchFn` for Node + tests.
+- **Transport auto-select helper.** New `selectTransport({ httpUrl })` reads `/api/info.transports`, intersects with the runtime's `WebTransport`/`WebSocket`/`EventSource` availability, and returns the best lane (preference: WebTransport -> WebSocket -> SSE; overridable via `preference`). Caller then constructs the corresponding primitive. Pluggable `fetchFn` for Node + tests.
 
 ### Notes
 
-- Foundation for an `init({ transport: 'auto' })` shortcut once full `MessagingClient` integration lands (4.2.1b). Today it's a small standalone helper so existing customers can adopt the pattern without waiting.
+- Foundation for an `init({ transport: 'auto' })` shortcut once full `MessagingClient` integration lands in a follow-up release. Today it's a small standalone helper so existing customers can adopt the pattern without waiting.
 
 ---
 
@@ -22,12 +43,12 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ### Added
 
-- **WebTransport (HTTP/3) transport primitive (Phase 4.3).** New `WebTransportTransport` class uses the browser-native `WebTransport` API to ride the platform's `/v1/transport/wt` HTTP/3 endpoint, terminated by the `droponair-webtransport` sidecar. Same shape as `SseTransport`: `onFrame`, `sendEnvelope`, `connect`, `close`. Caller brings own protobuf decoder. Browser-only for v1 (Chromium 97+, Firefox 125+, Safari TP-only); Node 22+ has experimental support behind flags.
+- **WebTransport (HTTP/3) transport primitive.** New `WebTransportTransport` class uses the browser-native `WebTransport` API to ride the platform's `/v1/transport/wt` HTTP/3 endpoint,. Same shape as `SseTransport`: `onFrame`, `sendEnvelope`, `connect`, `close`. Caller brings own protobuf decoder. Browser-only for v1 (Chromium 97+, Firefox 125+, Safari TP-only); Node 22+ has experimental support behind flags.
 
 ### Notes
 
 - WebTransport gives multi-stream perf wins over WebSocket on flaky cellular and similar networks. WebSocket on `/ws` remains the default; this primitive is opt-in for environments that have native WebTransport.
-- The droponair.com endpoint only advertises `transports: ["webtransport"]` once the `droponair-webtransport` sidecar is up and `app.transport.webtransport-enabled` is flipped on sdk-be. Check `GET /api/info.transports` for the live list.
+- The droponair.com endpoint only advertises `transports: ["webtransport"]` once the HTTP/3 lane is enabled and `app.transport.webtransport-enabled` is flipped on the platform. Check `GET /api/info.transports` for the live list.
 
 ---
 
@@ -35,11 +56,11 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ### Added
 
-- **SSE transport primitive (Phase 4.2.1).** New `SseTransport` class exposes the platform's HTTP-fallback lane (`/v1/transport/stream` + `/v1/transport/send`) as a small standalone client, for environments where WebSocket upgrades are blocked by corporate firewalls but HTTPS GET/POST work. EventSource-based receive (auto-reconnects), `fetch` POST for send. Bring your own protobuf decoder (use the codec already exported from the SDK).
+- **SSE transport primitive.** New `SseTransport` class exposes the platform's HTTP-fallback lane (`/v1/transport/stream` + `/v1/transport/send`) as a small standalone client, for environments where WebSocket upgrades are blocked by corporate firewalls but HTTPS GET/POST work. EventSource-based receive (auto-reconnects), `fetch` POST for send. Bring your own protobuf decoder (use the codec already exported from the SDK).
 
 ### Notes
 
-- v1 is a primitive; full `init({ transport: 'sse' })` integration into `MessagingClient` lands in 4.2.1b. Customers who need the SSE lane today can use `SseTransport` directly alongside the existing WS client.
+- v1 is a primitive; full `init({ transport: 'sse' })` integration into `MessagingClient` lands in a follow-up release. Customers who need the SSE lane today can use `SseTransport` directly alongside the existing WS client.
 - WebSocket on `/ws` remains the default for all SDK calls; this addition is purely opt-in. Older code paths and existing apps are unaffected.
 
 ---
@@ -48,7 +69,7 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ### Added
 
-- **SFU recording (Phase 3.7.5).** Server-side recording for SFU-mode rooms with `mediaEncryption: 'SFU'`. The platform's media server records the composite of every track in the room and uploads the finalized file directly to the customer's storage bucket - the platform never holds the recorded bytes. Storage destinations (S3 / GCS / Azure) are registered once in the panel; the SDK references each by an opaque `destinationId`.
+- **SFU recording.** Server-side recording for SFU-mode rooms with `mediaEncryption: 'SFU'`. The platform's media server records the composite of every track in the room and uploads the finalized file directly to the customer's storage bucket - the platform never holds the recorded bytes. Storage destinations (S3 / GCS / Azure) are registered once in the panel; the SDK references each by an opaque `destinationId`.
 - Three new client methods:
   - `startSfuRecording(roomId, destinationId)` -> `SfuRecording`
   - `stopSfuRecording(roomId, recordingId)` -> `SfuRecording`
@@ -313,7 +334,6 @@ This project follows [Semantic Versioning](https://semver.org/).
 - Wire-level additive: legacy 0.4.x clients ignore the new `Envelope.attachments` field (proto3 forwards-compat). Existing apps continue to work unchanged.
 - v1 storage adapters supported by the server: S3-compatible (S3, R2, MinIO, B2, Wasabi), Google Cloud Storage, Azure Blob.
 - Plan limits: `maxAttachmentSizeMb` per file + `maxAttachmentsPerMonth`. FREE = attachments disabled. PRO = 25 MB / 1000 per month. GROWTH = 100 MB / 10000. PAYG = 250 MB / metered. ENTERPRISE = custom.
-- Requires sdk-be `0.5.0` server.
 
 ---
 
@@ -329,7 +349,6 @@ This project follows [Semantic Versioning](https://semver.org/).
 ### Notes
 - Each edit and each `FOR_EVERYONE` delete counts as **one** MESSAGE usage record (subject to plan quotas + rate limits).
 - Wire-level additive: legacy 0.3.x clients ignore unknown frame types (proto3 forwards-compat), so existing TwinFlame and CrowdSyncer apps continue to work unchanged.
-- Requires sdk-be `0.4.0` server.
 
 ---
 

package/README.md

@@ -183,7 +183,7 @@ E2EE invariant: the push body is sender-supplied cleartext metadata only (e.g. "
 
 ### Message Edit & Delete
 
-Available since SDK `0.4.0` and requires sdk-be `0.4.0`.
+Available since SDK `0.4.0`.
 
 ```typescript
 // Edit an encrypted message
@@ -213,7 +213,7 @@ client.onMessageDelete((del) => {
 
 ### Attachments (Customer-Managed Storage)
 
-Available since SDK `0.5.0` and requires sdk-be `0.5.0`. Configure your bucket once in the DropOnAir panel (S3-compatible, GCS, or Azure Blob). DropOnAir never holds file bytes - the SDK uploads/downloads directly against your bucket via short-lived presigned URLs.
+Available since SDK `0.5.0`. Configure your bucket once in the DropOnAir panel (S3-compatible, GCS, or Azure Blob). DropOnAir never holds file bytes - the SDK uploads/downloads directly against your bucket via short-lived presigned URLs.
 
 ```typescript
 // Convenience: encrypt + upload + finalize in one call, then send with the message.
@@ -435,6 +435,23 @@ await wt.sendEnvelope(envelopeBytes);
 
 Uses the browser-native `WebTransport` API; opens a single bidirectional stream and rides raw bytes both ways. Browser support: Chromium 97+ (stable), Firefox 125+ (stable), Safari Technology Preview only, Node 22+ behind experimental flags. The `droponair.com` endpoint advertises `transports: ["webtransport"]` only when the `droponair-webtransport` sidecar is live; check `GET /api/info.transports` and `features.transport_webtransport` to detect availability. Bring your own protobuf decoder. WebSocket remains the default; this primitive is purely opt-in.
 
+### Transport auto-select
+
+Available since SDK `0.21.0`. `selectTransport({ httpUrl })` queries `/api/info.transports`, intersects with what the runtime supports (`WebTransport` / `WebSocket` / `EventSource`), and returns the best lane for this client + platform pair. Default preference: WebTransport → WebSocket → SSE (overridable).
+
+```typescript
+import { selectTransport, WebTransportTransport, SseTransport } from '@droponair/sdk-js';
+
+const lane = await selectTransport({ httpUrl: 'https://sdk.droponair.com' });
+switch (lane) {
+  case 'webtransport': /* new WebTransportTransport(...) */ break;
+  case 'sse':          /* new SseTransport(...) */          break;
+  default:             /* fall through to your WebSocket client */
+}
+```
+
+Foundation for an `init({ transport: 'auto' })` shortcut once full `MessagingClient` integration lands (a follow-up). Today it's a small standalone helper so existing customers can adopt the pattern without waiting.
+
 ### Call Recording
 
 Available since SDK `0.16.0`. The SDK **signals** recording state on a group or room call; your app does the actual media capture (`MediaRecorder`) and uploads the file to your own storage — the platform never holds the media. The recording signal is broadcast to every participant (including anyone who joins later); that transparency is enforced server-side.

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

@@ -14,7 +14,8 @@ export declare class MessagingClient implements DropOnAirClient {
     private readonly fetchFn;
     private readonly codec;
     private attachmentClient;
-    private ws;
+    private transport;
+    private resolvedTransportName;
     private shouldReconnect;
     private reconnectTimer;
     private dropOnAirJwt;
@@ -324,6 +325,7 @@ export declare class MessagingClient implements DropOnAirClient {
     private emitBroadcast;
     private handleIncomingGroupMessage;
     private emitGroupCallEvent;
+    private resolveTransport;
     private connectWebSocket;
     private handleIncomingMessageEdit;
     private handleIncomingMessageDelete;

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/transport/messaging-transport.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Internal transport interface used by `MessagingClient`. Abstracts the
+ * WebSocket, SSE-fallback, and WebTransport lanes behind a single
+ * lifecycle surface so the client can pick a lane at init time without
+ * the rest of the SDK caring which one is in use.
+ *
+ * Public consumers of the SDK continue to use the standalone primitives
+ * (`SseTransport`, `WebTransportTransport`); this interface is an internal
+ * adapter target only.
+ */
+export interface MessagingTransportClose {
+    code: number;
+    reason: string;
+}
+export interface MessagingTransportEvents {
+    onOpen(handler: () => void): void;
+    onFrame(handler: (bytes: Uint8Array) => void): void;
+    onClose(handler: (info: MessagingTransportClose) => void): void;
+    onError(handler: (err: Error) => void): void;
+}
+export interface MessagingTransport extends MessagingTransportEvents {
+    /** Human-readable transport name, mirrors the `/api/info.transports` token. */
+    readonly name: 'ws' | 'sse' | 'wt';
+    /** Open the underlying stream. Resolves once frames can be sent and received. */
+    connect(): Promise<void>;
+    /** Send a raw protobuf frame (no framing of its own). */
+    send(bytes: Uint8Array): void;
+    /** True if the transport can accept `send()` right now. */
+    isOpen(): boolean;
+    /** Close the stream. Idempotent. `code`/`reason` are best-effort hints. */
+    close(code?: number, reason?: string): void;
+}
+export type MessagingTransportSelection = 'ws' | 'sse' | 'wt' | 'auto';

package/dist/transport/messaging-transport.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/transport/protobuf-codec.js

@@ -42,29 +42,38 @@ const DeviceEncryptedPayloadType = new protobuf.Type('DeviceEncryptedPayload')
     .add(new protobuf.Field('deviceId', 1, 'string'))
     .add(new protobuf.Field('encryptedPayload', 2, 'bytes'))
     .add(new protobuf.Field('senderPublicKey', 3, 'bytes'));
-// Per-device wrapped file key for E2EE attachments (PROTOCOL_VERSION 4+)
-const DeviceWrappedKeyType = new protobuf.Type('DeviceWrappedKey')
-    .add(new protobuf.Field('deviceId', 1, 'string'))
-    .add(new protobuf.Field('wrappedKey', 2, 'bytes'))
-    .add(new protobuf.Field('senderPublicKey', 3, 'bytes'))
-    .add(new protobuf.Field('nonce', 4, 'bytes'));
-// Reference to an out-of-band attachment in customer-managed storage.
-const AttachmentRefEncTypeEnum = new protobuf.Enum('EncryptionType', { E2EE: 0, CLEARTEXT: 1 });
-const AttachmentRefType = new protobuf.Type('AttachmentRef')
-    .add(AttachmentRefEncTypeEnum)
-    .add(DeviceWrappedKeyType)
-    .add(new protobuf.Field('attachmentId', 1, 'string'))
-    .add(new protobuf.Field('storageHint', 2, 'string'))
-    .add(new protobuf.Field('mimeType', 3, 'string'))
-    .add(new protobuf.Field('sizeBytes', 4, 'int64'))
-    .add(new protobuf.Field('sha256', 5, 'string'))
-    .add(new protobuf.Field('encryptionType', 6, 'EncryptionType'))
-    .add(new protobuf.Field('wrappedKeys', 7, 'DeviceWrappedKey', 'repeated'))
-    .add(new protobuf.Field('thumbnailAttachmentId', 8, 'string'));
+// Reference to an out-of-band attachment in customer-managed storage, plus its
+// nested per-device wrapped file key (PROTOCOL_VERSION 4+).
+//
+// A protobufjs reflection object can have only ONE parent: calling `.add(obj)`
+// on a second message re-parents `obj` and silently removes it from the first.
+// Envelope, GroupEnvelope and GroupMessageNotification each nest AttachmentRef,
+// so each needs its OWN instance, built fresh here. Sharing a single instance
+// across them re-parented it onto the last adder and orphaned it from Envelope,
+// breaking every 1:1 send with "no such Type or Enum 'AttachmentRef' in Type
+// Envelope". The EncryptionType enum and DeviceWrappedKey type are nested inside
+// each AttachmentRef and so are rebuilt per call for the same reason.
+function buildAttachmentRefType() {
+    return new protobuf.Type('AttachmentRef')
+        .add(new protobuf.Enum('EncryptionType', { E2EE: 0, CLEARTEXT: 1 }))
+        .add(new protobuf.Type('DeviceWrappedKey')
+        .add(new protobuf.Field('deviceId', 1, 'string'))
+        .add(new protobuf.Field('wrappedKey', 2, 'bytes'))
+        .add(new protobuf.Field('senderPublicKey', 3, 'bytes'))
+        .add(new protobuf.Field('nonce', 4, 'bytes')))
+        .add(new protobuf.Field('attachmentId', 1, 'string'))
+        .add(new protobuf.Field('storageHint', 2, 'string'))
+        .add(new protobuf.Field('mimeType', 3, 'string'))
+        .add(new protobuf.Field('sizeBytes', 4, 'int64'))
+        .add(new protobuf.Field('sha256', 5, 'string'))
+        .add(new protobuf.Field('encryptionType', 6, 'EncryptionType'))
+        .add(new protobuf.Field('wrappedKeys', 7, 'DeviceWrappedKey', 'repeated'))
+        .add(new protobuf.Field('thumbnailAttachmentId', 8, 'string'));
+}
 const EnvelopeType = new protobuf.Type('Envelope')
     .add(EncryptionTypeEnum)
     .add(DeviceEncryptedPayloadType) // nested type must be added first
-    .add(AttachmentRefType)
+    .add(buildAttachmentRefType())
     .add(new protobuf.Field('messageId', 1, 'string'))
     .add(new protobuf.Field('appId', 2, 'string'))
     .add(new protobuf.Field('fromUserId', 3, 'string'))
@@ -128,7 +137,7 @@ const GroupEnvelopeEncryptionTypeEnum = new protobuf.Enum('EncryptionType', { E2
 const GroupEnvelopeType = new protobuf.Type('GroupEnvelope')
     .add(GroupEnvelopeEncryptionTypeEnum)
     .add(GroupMemberPayloadType)
-    .add(AttachmentRefType)
+    .add(buildAttachmentRefType())
     .add(new protobuf.Field('messageId', 1, 'string'))
     .add(new protobuf.Field('appId', 2, 'string'))
     .add(new protobuf.Field('groupId', 3, 'string'))
@@ -149,6 +158,7 @@ const GroupNotifDeviceType = new protobuf.Type('DeviceEncryptedPayload')
 const GroupMessageNotificationType = new protobuf.Type('GroupMessageNotification')
     .add(GroupNotifEncryptionTypeEnum)
     .add(GroupNotifDeviceType)
+    .add(buildAttachmentRefType())
     .add(new protobuf.Field('messageId', 1, 'string'))
     .add(new protobuf.Field('groupId', 2, 'string'))
     .add(new protobuf.Field('fromUserId', 3, 'string'))

package/dist/transport/sse-messaging-transport.d.ts

@@ -0,0 +1,28 @@
+import { type SseTransportOptions } from './sse-transport';
+import type { MessagingTransport, MessagingTransportClose } from './messaging-transport';
+/**
+ * SSE adapter for {@link MessagingTransport}. Wraps the standalone
+ * {@link SseTransport} primitive so `MessagingClient` can use the HTTP
+ * fallback lane behind the same lifecycle API as WebSocket.
+ *
+ * v1 limitations: no auto-reconnect logic at the client layer beyond
+ * what EventSource already does; close events synthesize code 1000.
+ */
+export declare class SseMessagingTransport implements MessagingTransport {
+    readonly name: "sse";
+    private inner;
+    private opened;
+    private openHandler;
+    private frameHandler;
+    private closeHandler;
+    private errorHandler;
+    constructor(options: SseTransportOptions);
+    onOpen(handler: () => void): void;
+    onFrame(handler: (bytes: Uint8Array) => void): void;
+    onClose(handler: (info: MessagingTransportClose) => void): void;
+    onError(handler: (err: Error) => void): void;
+    connect(): Promise<void>;
+    send(bytes: Uint8Array): void;
+    isOpen(): boolean;
+    close(_code?: number, _reason?: string): void;
+}

package/dist/transport/sse-messaging-transport.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SseMessagingTransport = void 0;
+const sse_transport_1 = require("./sse-transport");
+/**
+ * SSE adapter for {@link MessagingTransport}. Wraps the standalone
+ * {@link SseTransport} primitive so `MessagingClient` can use the HTTP
+ * fallback lane behind the same lifecycle API as WebSocket.
+ *
+ * v1 limitations: no auto-reconnect logic at the client layer beyond
+ * what EventSource already does; close events synthesize code 1000.
+ */
+class SseMessagingTransport {
+    constructor(options) {
+        this.name = 'sse';
+        this.opened = false;
+        this.openHandler = null;
+        this.frameHandler = null;
+        this.closeHandler = null;
+        this.errorHandler = null;
+        this.inner = new sse_transport_1.SseTransport(options);
+        this.inner.onFrame((bytes) => this.frameHandler?.(bytes));
+        this.inner.onState((state) => {
+            if (state === 'open') {
+                this.opened = true;
+                this.openHandler?.();
+            }
+            else if (state === 'closed') {
+                this.opened = false;
+                this.closeHandler?.({ code: 1000, reason: 'CLOSED' });
+            }
+            else if (state === 'error') {
+                this.errorHandler?.(new Error('SseMessagingTransport: stream error'));
+            }
+        });
+    }
+    onOpen(handler) { this.openHandler = handler; }
+    onFrame(handler) { this.frameHandler = handler; }
+    onClose(handler) { this.closeHandler = handler; }
+    onError(handler) { this.errorHandler = handler; }
+    async connect() {
+        await this.inner.connect();
+    }
+    send(bytes) {
+        // Fire-and-forget; surface failure via the error handler so the client's
+        // existing `this.transport.send(...)` call sites don't need to await.
+        this.inner.sendEnvelope(bytes).catch((err) => {
+            this.errorHandler?.(err instanceof Error ? err : new Error(String(err)));
+        });
+    }
+    isOpen() {
+        return this.opened;
+    }
+    close(_code, _reason) {
+        this.inner.close();
+        this.opened = false;
+    }
+}
+exports.SseMessagingTransport = SseMessagingTransport;

package/dist/transport/ws-messaging-transport.d.ts

@@ -0,0 +1,24 @@
+import type { MessagingTransport, MessagingTransportClose } from './messaging-transport';
+/**
+ * WebSocket adapter for {@link MessagingTransport}. Wraps the global
+ * WebSocket constructor; the client supplies the full URL (already
+ * carrying the JWT + deviceId query params).
+ */
+export declare class WebSocketMessagingTransport implements MessagingTransport {
+    private readonly url;
+    readonly name: "ws";
+    private ws;
+    private openHandler;
+    private frameHandler;
+    private closeHandler;
+    private errorHandler;
+    constructor(url: string);
+    onOpen(handler: () => void): void;
+    onFrame(handler: (bytes: Uint8Array) => void): void;
+    onClose(handler: (info: MessagingTransportClose) => void): void;
+    onError(handler: (err: Error) => void): void;
+    connect(): Promise<void>;
+    send(bytes: Uint8Array): void;
+    isOpen(): boolean;
+    close(code?: number, reason?: string): void;
+}

package/dist/transport/ws-messaging-transport.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketMessagingTransport = void 0;
+/**
+ * WebSocket adapter for {@link MessagingTransport}. Wraps the global
+ * WebSocket constructor; the client supplies the full URL (already
+ * carrying the JWT + deviceId query params).
+ */
+class WebSocketMessagingTransport {
+    constructor(url) {
+        this.url = url;
+        this.name = 'ws';
+        this.ws = null;
+        this.openHandler = null;
+        this.frameHandler = null;
+        this.closeHandler = null;
+        this.errorHandler = null;
+    }
+    onOpen(handler) { this.openHandler = handler; }
+    onFrame(handler) { this.frameHandler = handler; }
+    onClose(handler) { this.closeHandler = handler; }
+    onError(handler) { this.errorHandler = handler; }
+    connect() {
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(this.url);
+            ws.binaryType = 'arraybuffer';
+            ws.onopen = () => {
+                this.ws = ws;
+                this.openHandler?.();
+                resolve();
+            };
+            ws.onerror = (event) => {
+                const err = new Error('Failed to connect DropOnAir websocket');
+                this.errorHandler?.(err);
+                // If the socket never opened, reject the connect promise.
+                if (ws.readyState !== WebSocket.OPEN) {
+                    reject(err);
+                }
+            };
+            ws.onclose = (event) => {
+                this.ws = null;
+                this.closeHandler?.({ code: event.code, reason: event.reason });
+            };
+            ws.onmessage = (event) => {
+                if (event.data instanceof ArrayBuffer) {
+                    this.frameHandler?.(new Uint8Array(event.data));
+                }
+            };
+        });
+    }
+    send(bytes) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('WebSocketMessagingTransport: not open');
+        }
+        this.ws.send(bytes);
+    }
+    isOpen() {
+        return !!this.ws && this.ws.readyState === WebSocket.OPEN;
+    }
+    close(code, reason) {
+        if (this.ws && this.ws.readyState !== WebSocket.CLOSED) {
+            this.ws.close(code, reason);
+        }
+        this.ws = null;
+    }
+}
+exports.WebSocketMessagingTransport = WebSocketMessagingTransport;

package/dist/transport/wt-messaging-transport.d.ts

@@ -0,0 +1,25 @@
+import { type WebTransportTransportOptions } from './webtransport-transport';
+import type { MessagingTransport, MessagingTransportClose } from './messaging-transport';
+/**
+ * WebTransport (HTTP/3) adapter for {@link MessagingTransport}. Wraps the
+ * standalone {@link WebTransportTransport} primitive so `MessagingClient`
+ * can use the QUIC lane behind the same lifecycle API as WebSocket.
+ */
+export declare class WtMessagingTransport implements MessagingTransport {
+    readonly name: "wt";
+    private inner;
+    private opened;
+    private openHandler;
+    private frameHandler;
+    private closeHandler;
+    private errorHandler;
+    constructor(options: WebTransportTransportOptions);
+    onOpen(handler: () => void): void;
+    onFrame(handler: (bytes: Uint8Array) => void): void;
+    onClose(handler: (info: MessagingTransportClose) => void): void;
+    onError(handler: (err: Error) => void): void;
+    connect(): Promise<void>;
+    send(bytes: Uint8Array): void;
+    isOpen(): boolean;
+    close(_code?: number, _reason?: string): void;
+}

package/dist/transport/wt-messaging-transport.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WtMessagingTransport = void 0;
+const webtransport_transport_1 = require("./webtransport-transport");
+/**
+ * WebTransport (HTTP/3) adapter for {@link MessagingTransport}. Wraps the
+ * standalone {@link WebTransportTransport} primitive so `MessagingClient`
+ * can use the QUIC lane behind the same lifecycle API as WebSocket.
+ */
+class WtMessagingTransport {
+    constructor(options) {
+        this.name = 'wt';
+        this.opened = false;
+        this.openHandler = null;
+        this.frameHandler = null;
+        this.closeHandler = null;
+        this.errorHandler = null;
+        this.inner = new webtransport_transport_1.WebTransportTransport(options);
+        this.inner.onFrame((bytes) => this.frameHandler?.(bytes));
+        this.inner.onState((state) => {
+            if (state === 'open') {
+                this.opened = true;
+                this.openHandler?.();
+            }
+            else if (state === 'closed') {
+                this.opened = false;
+                this.closeHandler?.({ code: 1000, reason: 'CLOSED' });
+            }
+            else if (state === 'error') {
+                this.errorHandler?.(new Error('WtMessagingTransport: session error'));
+            }
+        });
+    }
+    onOpen(handler) { this.openHandler = handler; }
+    onFrame(handler) { this.frameHandler = handler; }
+    onClose(handler) { this.closeHandler = handler; }
+    onError(handler) { this.errorHandler = handler; }
+    async connect() {
+        await this.inner.connect();
+    }
+    send(bytes) {
+        this.inner.sendEnvelope(bytes).catch((err) => {
+            this.errorHandler?.(err instanceof Error ? err : new Error(String(err)));
+        });
+    }
+    isOpen() {
+        return this.opened;
+    }
+    close(_code, _reason) {
+        this.inner.close();
+        this.opened = false;
+    }
+}
+exports.WtMessagingTransport = WtMessagingTransport;

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.21.0";
+export declare const SDK_VERSION = "0.22.1";
 /**
  * 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.21.0';
+exports.SDK_VERSION = '0.22.1';
 /**
  * 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.21.0",
+  "version": "0.22.1",
   "description": "DropOnAir SDK for end-to-end encrypted messaging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",