@droponair/sdk-js 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -6,6 +6,19 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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/dist/index.d.ts

@@ -3,6 +3,7 @@ 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';
 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.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,7 @@ 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; } });
 exports.default = { initialize };

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