@droponair/sdk-js 0.18.0 → 0.21.0

package/CHANGELOG.md

@@ -6,6 +6,44 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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.
+
+### 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.
+
+---
+
+## [0.20.0], 2026-05-24
+
+### 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.
+
+### 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.
+
+---
+
+## [0.19.0], 2026-05-24
+
+### 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).
+
+### 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.
+- WebSocket on `/ws` remains the default for all SDK calls; this addition is purely opt-in. Older code paths and existing apps are unaffected.
+
+---
+
 ## [0.18.0], 2026-05-23
 
 ### Added

package/README.md

@@ -397,6 +397,44 @@ await client.stopSfuRecording(room.roomId, rec.recordingId);
 
 Completion lands as the `sfu-recording.completed` webhook (or by polling `listSfuRecordings`) and carries `locationUri` pointing at the finalized file in your bucket. E2EE-encrypted SFU rooms cannot be server-recorded by design (the media server forwards traffic it cannot decrypt) - use the client-side `startRecording` for those.
 
+Live call participants also receive in-band notification frames via the existing group-call event callback so a "🔴 RECORDING" UI badge stays in sync. The event types are `GROUP_CALL_SFU_RECORDING_STARTED` (payload = recordingId), `GROUP_CALL_SFU_RECORDING_STOPPED` (recordingId), and `GROUP_CALL_SFU_RECORDING_AVAILABLE` (`recordingId|locationUri`); the platform also notifies late joiners about any already-active SFU recording on the room. Plan limits (`maxSfuRecordingMinutesPerMonth`) are enforced server-side; deny at `startSfuRecording` returns HTTP 403 with a deny reason such as `MONTHLY_SFU_RECORDING_MINUTES_LIMIT_REACHED`.
+
+### HTTP fallback (SSE) transport
+
+Available since SDK `0.19.0`. For environments where WebSocket upgrades are blocked by a corporate firewall but plain HTTPS GET/POST work, the SDK exports a standalone `SseTransport` primitive that rides the platform's `/v1/transport/stream` (long-lived SSE) and `/v1/transport/send` (POST) endpoints. WebSocket on `/ws` remains the default for `client.connect()`; this primitive is opt-in for the corporate-firewall use case.
+
+```typescript
+import { SseTransport } from '@droponair/sdk-js';
+
+const sse = new SseTransport({
+  httpUrl: 'https://sdk.droponair.com',
+  getJwt: async () => jwt,
+});
+sse.onFrame((bytes) => { /* protobuf decode */ });
+await sse.connect();
+await sse.sendEnvelope(envelopeBytes);
+```
+
+EventSource-based receive (auto-reconnects + 25s keep-alives that defeat proxy idle timeouts), `fetch` POST for send. Bring your own protobuf decoder (use the codec already exported by the SDK). Verify the lane is enabled on the server via `GET /api/info`: the `transports` array includes `"sse"` and `features` includes `"transport_sse"`. v1 covers 1:1 Envelope delivery; call signaling stays on WebSocket. Full `init({ transport: 'sse' })` integration into `MessagingClient` lands in a follow-up.
+
+### WebTransport (HTTP/3) transport
+
+Available since SDK `0.20.0`. For modern browsers + environments with native HTTP/3 support, the SDK exports a `WebTransportTransport` primitive that rides the platform's `/v1/transport/wt` endpoint. Multi-stream and lower head-of-line blocking versus WebSocket; particularly useful on flaky cellular networks.
+
+```typescript
+import { WebTransportTransport } from '@droponair/sdk-js';
+
+const wt = new WebTransportTransport({
+  httpUrl: 'https://sdk.droponair.com',
+  getJwt: async () => jwt,
+});
+wt.onFrame((bytes) => { /* protobuf decode */ });
+await wt.connect();
+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.
+
 ### 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/index.d.ts

@@ -3,6 +3,9 @@ export { SDK_VERSION, PROTOCOL_VERSION, PAYLOAD_FORMAT_VERSION } from './version
 export declare function initialize(options: InitializeOptions): Promise<DropOnAirClient>;
 export type { InitializeOptions, DropOnAirClient, DropOnAirEvent, MessageCallback, EventCallback, DecryptedMessage, KeyStorageAdapter, CallEvent, CallEventType, CallEventCallback, TurnCredentials, BroadcastMessage, BroadcastCallback, GroupInfo, GroupMemberInfo, DecryptedGroupMessage, GroupMessageCallback, GroupCallEvent, GroupCallEventType, GroupCallEventCallback, 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.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");
@@ -26,4 +26,13 @@ async function initialize(options) {
     }
     return client;
 }
+// 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>;

package/dist/transport/auto-select.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * 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
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectTransport = selectTransport;
+const DEFAULT_PREFERENCE = ['webtransport', 'websocket', 'sse'];
+/**
+ * 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).
+ */
+async function selectTransport(options) {
+    const httpUrl = options.httpUrl.replace(/\/+$/, '');
+    const fetchFn = options.fetchFn ?? globalThis.fetch.bind(globalThis);
+    const preference = options.preference ?? DEFAULT_PREFERENCE;
+    const res = await fetchFn(`${httpUrl}/api/info`);
+    if (!res.ok) {
+        throw new Error(`selectTransport: GET /api/info failed (HTTP ${res.status})`);
+    }
+    const info = await res.json();
+    const serverLanes = new Set(info.transports ?? ['websocket']);
+    const runtimeSupports = (lane) => {
+        switch (lane) {
+            case 'webtransport':
+                return typeof globalThis.WebTransport === 'function';
+            case 'websocket':
+                return typeof globalThis.WebSocket === 'function';
+            case 'sse':
+                return typeof globalThis.EventSource === 'function';
+        }
+    };
+    for (const lane of preference) {
+        if (serverLanes.has(lane) && runtimeSupports(lane)) {
+            return lane;
+        }
+    }
+    throw new Error('selectTransport: no transport lane supported by both runtime and platform');
+}

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

@@ -0,0 +1,62 @@
+/**
+ * SSE-lane primitive (Phase 4.2.1 v1).
+ *
+ * Standalone client for the platform's HTTP fallback transport
+ * (`GET /v1/transport/stream` for receive, `POST /v1/transport/send` for
+ * send). Suitable for environments where WebSocket upgrades are blocked
+ * by a corporate firewall but plain HTTPS GET/POST work.
+ *
+ * v1 surface intentionally narrow: this exposes the bytes lane only.
+ * Caller is responsible for parsing the protobuf Envelope (or using the
+ * codec exported from the SDK). Full `init({ transport: 'sse' })`
+ * integration into `MessagingClient` lands in 4.2.1b once the wire
+ * shape stabilises with real-world feedback.
+ *
+ * @example
+ * ```ts
+ * import { SseTransport } from '@droponair/sdk-js';
+ * const sse = new SseTransport({ httpUrl: 'https://sdk.droponair.com', getJwt: async () => myJwt });
+ * sse.onFrame((bytes) => { ... your protobuf decode ... });
+ * await sse.connect();
+ * await sse.sendEnvelope(myEnvelopeBytes);
+ * ```
+ */
+export interface SseTransportOptions {
+    /** Base URL of the platform's REST API (no trailing slash). */
+    httpUrl: string;
+    /** Returns a fresh JWT. Called once per connect. */
+    getJwt: () => Promise<string>;
+    /**
+     * Custom fetch implementation, useful for Node-side polyfills or test
+     * doubles. Defaults to globalThis.fetch.
+     */
+    fetchFn?: typeof fetch;
+    /**
+     * Custom EventSource constructor, useful for environments (e.g. Node)
+     * that need the `eventsource` npm polyfill. Defaults to the global.
+     */
+    eventSourceCtor?: typeof EventSource;
+}
+export type SseFrameHandler = (frame: Uint8Array) => void;
+export type SseStateHandler = (state: 'connecting' | 'open' | 'closed' | 'error') => void;
+export declare class SseTransport {
+    private readonly httpUrl;
+    private readonly getJwt;
+    private readonly fetchFn;
+    private readonly EventSourceCtor;
+    private eventSource;
+    private jwt;
+    private frameHandler;
+    private stateHandler;
+    constructor(options: SseTransportOptions);
+    /** Subscribe to incoming protobuf frames. Replaces any previous handler. */
+    onFrame(handler: SseFrameHandler): void;
+    /** Subscribe to lifecycle state changes. Replaces any previous handler. */
+    onState(handler: SseStateHandler): void;
+    /** Open the long-lived SSE stream. Resolves on first 'ready' event from the server. */
+    connect(): Promise<void>;
+    /** POST a single protobuf Envelope to the server. */
+    sendEnvelope(envelopeBytes: Uint8Array): Promise<void>;
+    /** Close the stream. Idempotent. */
+    close(): void;
+}

package/dist/transport/sse-transport.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * SSE-lane primitive (Phase 4.2.1 v1).
+ *
+ * Standalone client for the platform's HTTP fallback transport
+ * (`GET /v1/transport/stream` for receive, `POST /v1/transport/send` for
+ * send). Suitable for environments where WebSocket upgrades are blocked
+ * by a corporate firewall but plain HTTPS GET/POST work.
+ *
+ * v1 surface intentionally narrow: this exposes the bytes lane only.
+ * Caller is responsible for parsing the protobuf Envelope (or using the
+ * codec exported from the SDK). Full `init({ transport: 'sse' })`
+ * integration into `MessagingClient` lands in 4.2.1b once the wire
+ * shape stabilises with real-world feedback.
+ *
+ * @example
+ * ```ts
+ * import { SseTransport } from '@droponair/sdk-js';
+ * const sse = new SseTransport({ httpUrl: 'https://sdk.droponair.com', getJwt: async () => myJwt });
+ * sse.onFrame((bytes) => { ... your protobuf decode ... });
+ * await sse.connect();
+ * await sse.sendEnvelope(myEnvelopeBytes);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SseTransport = void 0;
+class SseTransport {
+    constructor(options) {
+        this.eventSource = null;
+        this.jwt = null;
+        this.frameHandler = null;
+        this.stateHandler = null;
+        this.httpUrl = options.httpUrl.replace(/\/+$/, '');
+        this.getJwt = options.getJwt;
+        this.fetchFn = options.fetchFn ?? globalThis.fetch.bind(globalThis);
+        this.EventSourceCtor = options.eventSourceCtor ?? globalThis.EventSource;
+        if (typeof this.EventSourceCtor !== 'function') {
+            throw new Error('SseTransport: EventSource is not available; pass options.eventSourceCtor (e.g. the `eventsource` npm package)');
+        }
+    }
+    /** Subscribe to incoming protobuf frames. Replaces any previous handler. */
+    onFrame(handler) {
+        this.frameHandler = handler;
+    }
+    /** Subscribe to lifecycle state changes. Replaces any previous handler. */
+    onState(handler) {
+        this.stateHandler = handler;
+    }
+    /** Open the long-lived SSE stream. Resolves on first 'ready' event from the server. */
+    async connect() {
+        this.close();
+        this.jwt = await this.getJwt();
+        this.stateHandler?.('connecting');
+        const url = `${this.httpUrl}/v1/transport/stream?token=${encodeURIComponent(this.jwt)}`;
+        return new Promise((resolve, reject) => {
+            const es = new this.EventSourceCtor(url);
+            const onReady = () => {
+                this.stateHandler?.('open');
+                resolve();
+            };
+            es.addEventListener('ready', onReady);
+            es.addEventListener('envelope', (e) => {
+                const bytes = decodeBase64(e.data);
+                this.frameHandler?.(bytes);
+            });
+            es.onerror = (e) => {
+                this.stateHandler?.(es.readyState === EventSource.CLOSED ? 'closed' : 'error');
+                if (es.readyState === EventSource.CONNECTING) {
+                    // EventSource auto-reconnects; nothing for us to do.
+                    return;
+                }
+                if (es.readyState === EventSource.CLOSED) {
+                    // Hard close, e.g. 401. Reject the initial promise if still pending.
+                    reject(new Error('SseTransport: stream closed'));
+                }
+            };
+            this.eventSource = es;
+        });
+    }
+    /** POST a single protobuf Envelope to the server. */
+    async sendEnvelope(envelopeBytes) {
+        if (!this.jwt) {
+            throw new Error('SseTransport: not connected (call connect() first)');
+        }
+        const res = await this.fetchFn(`${this.httpUrl}/v1/transport/send`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.jwt}`,
+                'Content-Type': 'application/octet-stream',
+            },
+            // BodyInit accepts ArrayBuffer; this avoids a TS type mismatch on
+            // Uint8Array<ArrayBufferLike> while sending the same bytes.
+            body: envelopeBytes.buffer.slice(envelopeBytes.byteOffset, envelopeBytes.byteOffset + envelopeBytes.byteLength),
+        });
+        if (!res.ok) {
+            throw new Error(`SseTransport: send failed (HTTP ${res.status})`);
+        }
+    }
+    /** Close the stream. Idempotent. */
+    close() {
+        if (this.eventSource) {
+            this.eventSource.close();
+            this.eventSource = null;
+            this.stateHandler?.('closed');
+        }
+    }
+}
+exports.SseTransport = SseTransport;
+function decodeBase64(b64) {
+    if (typeof atob === 'function') {
+        const bin = atob(b64);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            out[i] = bin.charCodeAt(i);
+        return out;
+    }
+    // Node fallback. Buffer is global there.
+    const Buf = globalThis.Buffer;
+    if (Buf)
+        return Buf.from(b64, 'base64');
+    throw new Error('SseTransport: no base64 decoder available (need atob or Buffer)');
+}

package/dist/transport/webtransport-transport.d.ts

@@ -0,0 +1,61 @@
+/**
+ * WebTransport (HTTP/3) lane primitive (Phase 4.3).
+ *
+ * Standalone client for the platform's WebTransport endpoint, terminated by
+ * the `droponair-webtransport` Go sidecar and bridged into sdk-be `/ws`.
+ * Browser-native `WebTransport` API; no polyfill ships with the SDK.
+ *
+ * Browser support as of 2026-05:
+ *   - Chromium 97+ (stable)
+ *   - Firefox 125+ (stable)
+ *   - Safari Technology Preview only (no stable release yet)
+ *   - Node 22+ has experimental WebTransport behind a flag
+ *
+ * v1 surface is intentionally narrow: this exposes the bytes lane only,
+ * caller decodes protobuf. Full `init({ transport: 'webtransport' })`
+ * MessagingClient integration lands later, mirroring the SSE roadmap.
+ *
+ * @example
+ * ```ts
+ * import { WebTransportTransport } from '@droponair/sdk-js';
+ * const wt = new WebTransportTransport({
+ *   httpUrl: 'https://sdk.droponair.com',
+ *   getJwt: async () => myJwt,
+ * });
+ * wt.onFrame((bytes) => { ... protobuf decode ... });
+ * await wt.connect();
+ * await wt.sendEnvelope(envelopeBytes);
+ * ```
+ */
+export interface WebTransportTransportOptions {
+    /** Base URL of the platform's REST API. The WT endpoint is derived as
+     *  `<httpUrl>/v1/transport/wt?token=<jwt>`. */
+    httpUrl: string;
+    /** Returns a fresh JWT. Called once per connect. */
+    getJwt: () => Promise<string>;
+}
+export type WTFrameHandler = (frame: Uint8Array) => void;
+export type WTStateHandler = (state: 'connecting' | 'open' | 'closed' | 'error') => void;
+export declare class WebTransportTransport {
+    private readonly httpUrl;
+    private readonly getJwt;
+    private session;
+    private stream;
+    private writer;
+    private reader;
+    private frameHandler;
+    private stateHandler;
+    private readLoopAbort;
+    constructor(options: WebTransportTransportOptions);
+    /** Subscribe to incoming protobuf frames. Replaces any previous handler. */
+    onFrame(handler: WTFrameHandler): void;
+    /** Subscribe to lifecycle state changes. Replaces any previous handler. */
+    onState(handler: WTStateHandler): void;
+    /** Open the WebTransport session + a single bidirectional stream. */
+    connect(): Promise<void>;
+    /** Write a single protobuf Envelope to the bidirectional stream. */
+    sendEnvelope(envelopeBytes: Uint8Array): Promise<void>;
+    /** Close the session. Idempotent. */
+    close(): void;
+    private startReadLoop;
+}

package/dist/transport/webtransport-transport.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * WebTransport (HTTP/3) lane primitive (Phase 4.3).
+ *
+ * Standalone client for the platform's WebTransport endpoint, terminated by
+ * the `droponair-webtransport` Go sidecar and bridged into sdk-be `/ws`.
+ * Browser-native `WebTransport` API; no polyfill ships with the SDK.
+ *
+ * Browser support as of 2026-05:
+ *   - Chromium 97+ (stable)
+ *   - Firefox 125+ (stable)
+ *   - Safari Technology Preview only (no stable release yet)
+ *   - Node 22+ has experimental WebTransport behind a flag
+ *
+ * v1 surface is intentionally narrow: this exposes the bytes lane only,
+ * caller decodes protobuf. Full `init({ transport: 'webtransport' })`
+ * MessagingClient integration lands later, mirroring the SSE roadmap.
+ *
+ * @example
+ * ```ts
+ * import { WebTransportTransport } from '@droponair/sdk-js';
+ * const wt = new WebTransportTransport({
+ *   httpUrl: 'https://sdk.droponair.com',
+ *   getJwt: async () => myJwt,
+ * });
+ * wt.onFrame((bytes) => { ... protobuf decode ... });
+ * await wt.connect();
+ * await wt.sendEnvelope(envelopeBytes);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebTransportTransport = void 0;
+class WebTransportTransport {
+    constructor(options) {
+        this.session = null;
+        this.stream = null;
+        this.writer = null;
+        this.reader = null;
+        this.frameHandler = null;
+        this.stateHandler = null;
+        this.readLoopAbort = false;
+        this.httpUrl = options.httpUrl.replace(/\/+$/, '');
+        this.getJwt = options.getJwt;
+        if (typeof globalThis.WebTransport !== 'function') {
+            throw new Error('WebTransportTransport: WebTransport is not available in this runtime. ' +
+                'Requires Chromium 97+, Firefox 125+, or Node 22+ with --experimental-* flags.');
+        }
+    }
+    /** Subscribe to incoming protobuf frames. Replaces any previous handler. */
+    onFrame(handler) { this.frameHandler = handler; }
+    /** Subscribe to lifecycle state changes. Replaces any previous handler. */
+    onState(handler) { this.stateHandler = handler; }
+    /** Open the WebTransport session + a single bidirectional stream. */
+    async connect() {
+        this.close();
+        const jwt = await this.getJwt();
+        this.stateHandler?.('connecting');
+        const url = `${this.httpUrl.replace(/^http/, 'https')}/v1/transport/wt?token=${encodeURIComponent(jwt)}`;
+        const WT = globalThis.WebTransport;
+        const session = new WT(url);
+        this.session = session;
+        await session.ready;
+        this.stateHandler?.('open');
+        const stream = await session.createBidirectionalStream();
+        this.stream = stream;
+        this.writer = stream.writable.getWriter();
+        this.reader = stream.readable.getReader();
+        session.closed
+            .then(() => this.stateHandler?.('closed'))
+            .catch(() => this.stateHandler?.('error'));
+        this.startReadLoop().catch((e) => {
+            this.stateHandler?.('error');
+            // eslint-disable-next-line no-console
+            console.warn('WebTransportTransport: read loop ended', e);
+        });
+    }
+    /** Write a single protobuf Envelope to the bidirectional stream. */
+    async sendEnvelope(envelopeBytes) {
+        if (!this.writer) {
+            throw new Error('WebTransportTransport: not connected (call connect() first)');
+        }
+        await this.writer.write(envelopeBytes);
+    }
+    /** Close the session. Idempotent. */
+    close() {
+        this.readLoopAbort = true;
+        if (this.writer) {
+            try {
+                this.writer.releaseLock();
+            }
+            catch { }
+            this.writer = null;
+        }
+        if (this.reader) {
+            try {
+                this.reader.releaseLock();
+            }
+            catch { }
+            this.reader = null;
+        }
+        if (this.session) {
+            try {
+                this.session.close();
+            }
+            catch { }
+            this.session = null;
+        }
+        this.stream = null;
+    }
+    async startReadLoop() {
+        this.readLoopAbort = false;
+        if (!this.reader)
+            return;
+        while (!this.readLoopAbort) {
+            const { value, done } = await this.reader.read();
+            if (done)
+                return;
+            if (value && value.byteLength > 0) {
+                this.frameHandler?.(value);
+            }
+        }
+    }
+}
+exports.WebTransportTransport = WebTransportTransport;

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.18.0";
+export declare const SDK_VERSION = "0.21.0";
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can

package/dist/version.js

@@ -10,7 +10,7 @@ exports.PROTOCOL_VERSION = exports.PAYLOAD_FORMAT_VERSION = exports.SDK_VERSION
  *   MINOR, additive feature (e.g. multi-device payloads, new call event type)
  *   PATCH, bug-fix / perf improvement with no wire or API change
  */
-exports.SDK_VERSION = '0.18.0';
+exports.SDK_VERSION = '0.21.0';
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can

package/package.json

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