@droponair/sdk-js 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -6,6 +6,31 @@ 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

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

@@ -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>;

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/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.19.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.19.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.19.0",
+  "version": "0.21.0",
   "description": "DropOnAir SDK for end-to-end encrypted messaging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",