@droponair/sdk-js 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -6,12 +6,28 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.23.0], 2026-06-01
+
+### Added
+
+- **Idempotent retries via `sendMessage(..., { clientMessageId })`.** Pass a stable id to reuse across retries of the same logical message. The relay now dedups by `(appId, fromUserId, messageId)`, so re-sending after a lost ack or a reconnect delivers the message at most once instead of creating duplicates. Omit it for new messages and a fresh id is generated (unchanged default behavior). Requires relay support shipped alongside this release; wire format and `PROTOCOL_VERSION` are unchanged (the `clientMessageId` field already existed).
+
+---
+
+## [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 (4.5b).** 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.
+- **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
 
@@ -23,11 +39,11 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ### 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.
 
 ---
 
@@ -35,12 +51,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.
 
 ---
 
@@ -48,11 +64,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.
 
 ---
@@ -61,7 +77,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`
@@ -326,7 +342,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.
 
 ---
 
@@ -342,7 +357,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.

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

@@ -101,6 +101,7 @@ export declare class MessagingClient implements DropOnAirClient {
     disconnect(): void;
     sendMessage(toUserId: string, plaintextMessage: string, options?: {
         attachments?: AttachmentRef[];
+        clientMessageId?: string;
     }): Promise<{
         messageId: string;
     }>;

package/dist/core/messaging-client.js

@@ -337,7 +337,10 @@ class MessagingClient {
             throw new Error('JWT_EXPIRED: Secure messaging session is reconnecting; please retry in a moment');
         }
         const myDeviceId = this.deviceId ?? await this.getOrCreateDeviceId();
-        const messageId = crypto.randomUUID();
+        // Reuse a caller-supplied id for idempotent retries: the relay dedups by
+        // (appId, fromUserId, messageId), so re-sending with the same id is a no-op
+        // delivery instead of a duplicate. Defaults to a fresh id for new messages.
+        const messageId = options?.clientMessageId ?? crypto.randomUUID();
         const timestamp = Date.now();
         const myIdentity = await this.cryptoService.getOrCreateIdentity();
         const myPublicKeyBytes = (0, bytes_1.fromBase64)(myIdentity.publicKey);

package/dist/core/types.d.ts

@@ -304,9 +304,16 @@ export interface DropOnAirClient {
     /**
      * Send a 1:1 E2EE message. Optionally attach one or more attachments
      * prepared via {@link prepareAttachmentAndUpload} or {@link createUploadSession}.
+     *
+     * Pass `options.clientMessageId` to reuse a stable id across retries: the relay
+     * dedups by `(appId, fromUserId, messageId)`, so re-sending a message with the
+     * same id delivers it at most once instead of creating a duplicate. Omit it for
+     * new messages and a fresh id is generated. The chosen id is returned as
+     * `messageId`.
      */
     sendMessage(toUserId: string, plaintextMessage: string, options?: {
         attachments?: import('../attachment/attachment-types').AttachmentRef[];
+        clientMessageId?: string;
     }): Promise<{
         messageId: string;
     }>;

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