@droponair/sdk-js 0.19.0 → 0.22.0

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/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/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/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/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.19.0";
+export declare const SDK_VERSION = "0.22.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.22.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.22.0",
   "description": "DropOnAir SDK for end-to-end encrypted messaging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",