@droponair/sdk-js 0.3.1 → 0.5.0

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

@@ -1,6 +1,7 @@
 import { CryptoService } from '../crypto/crypto-service';
 import { SessionManager } from './session-manager';
-import { BroadcastCallback, CallEventCallback, DropOnAirClient, EventCallback, GroupCallEventCallback, GroupInfo, GroupMessageCallback, InitializeOptions, MessageCallback, TurnCredentials } from './types';
+import { BroadcastCallback, CallEventCallback, DropOnAirClient, EventCallback, GroupCallEventCallback, GroupInfo, GroupMessageCallback, InitializeOptions, MessageCallback, MessageDeleteCallback, MessageEditCallback, TurnCredentials } from './types';
+import { AttachmentRef, CreateUploadSessionOptions, DownloadedAttachment, PrepareAttachmentOptions, UploadSession } from '../attachment/attachment-types';
 export declare class MessagingClient implements DropOnAirClient {
     private readonly options;
     private readonly cryptoService;
@@ -12,6 +13,7 @@ export declare class MessagingClient implements DropOnAirClient {
     private readonly keyDirectoryEndpoint;
     private readonly fetchFn;
     private readonly codec;
+    private attachmentClient;
     private ws;
     private shouldReconnect;
     private reconnectTimer;
@@ -68,6 +70,8 @@ export declare class MessagingClient implements DropOnAirClient {
     private readonly messageListeners;
     private readonly eventListeners;
     private readonly broadcastListeners;
+    private readonly messageEditListeners;
+    private readonly messageDeleteListeners;
     /** ------------------------------------------------------------------
      * Lightweight structured logger. Only active when options.debug === true.
      * Fields are safe to log: no plaintext, no private keys, no full JWTs.
@@ -82,14 +86,31 @@ export declare class MessagingClient implements DropOnAirClient {
     /** Redact a JWT to keep subject + expiry visible while hiding the signature. */
     private jwtSummary;
     constructor(options: InitializeOptions, cryptoService: CryptoService, sessionManager: SessionManager, storage: import('./types').KeyStorageAdapter);
+    prepareAttachmentAndUpload(bytes: Uint8Array, options: PrepareAttachmentOptions): Promise<AttachmentRef>;
+    createUploadSession(options: CreateUploadSessionOptions): Promise<UploadSession>;
+    finalizeAttachment(attachmentId: string, sha256: string): Promise<void>;
+    downloadAttachment(ref: AttachmentRef): Promise<DownloadedAttachment>;
     connect(): Promise<void>;
     disconnect(): void;
-    sendMessage(toUserId: string, plaintextMessage: string): Promise<{
+    sendMessage(toUserId: string, plaintextMessage: string, options?: {
+        attachments?: AttachmentRef[];
+    }): Promise<{
         messageId: string;
     }>;
     ack(messageId: string): Promise<void>;
     onMessage(callback: MessageCallback): () => void;
     onEvent(callback: EventCallback): () => void;
+    onMessageEdit(callback: MessageEditCallback): () => void;
+    onMessageDelete(callback: MessageDeleteCallback): () => void;
+    editMessage(originalMessageId: string, toUserId: string, newPlaintext: string): Promise<{
+        editId: string;
+    }>;
+    editCleartextMessage(originalMessageId: string, toUserId: string, newPlaintext: string): Promise<{
+        editId: string;
+    }>;
+    deleteMessage(originalMessageId: string, toUserId: string, scope: 'FOR_EVERYONE' | 'FOR_ME'): Promise<{
+        deleteId: string;
+    }>;
     sendCleartextMessage(toUserId: string, plaintext: string): Promise<{
         messageId: string;
     }>;
@@ -137,6 +158,8 @@ export declare class MessagingClient implements DropOnAirClient {
     private handleIncomingGroupMessage;
     private emitGroupCallEvent;
     private connectWebSocket;
+    private handleIncomingMessageEdit;
+    private handleIncomingMessageDelete;
     private handleIncomingEnvelope;
     private getPeerSharedKey;
     /** Get or create a persistent device UUID for this SDK instance. */

package/dist/core/messaging-client.js

@@ -4,6 +4,7 @@ exports.MessagingClient = void 0;
 const bytes_1 = require("./bytes");
 const protobuf_codec_1 = require("../transport/protobuf-codec");
 const version_1 = require("../version");
+const attachment_client_1 = require("../attachment/attachment-client");
 const STORAGE_DEVICE_ID = 'droponair.device.id.v1';
 class MessagingClient {
     reconnectDelayMs() {
@@ -218,6 +219,8 @@ class MessagingClient {
         this.messageListeners = new Set();
         this.eventListeners = new Set();
         this.broadcastListeners = new Set();
+        this.messageEditListeners = new Set();
+        this.messageDeleteListeners = new Set();
         this.wsUrl = options.messagingWsUrl ?? 'wss://sdk.droponair.com/ws';
         this.httpUrl = options.messagingHttpUrl ?? 'https://sdk.droponair.com';
         this.tokenExchangeEndpoint = options.tokenExchangeEndpoint ?? '/api/messaging/token-exchange';
@@ -233,6 +236,36 @@ class MessagingClient {
             return resolvedFetch.call(fetchContext, input, init);
         });
         this.autoAckIncomingMessages = options.autoAckIncomingMessages !== false;
+        this.attachmentClient = new attachment_client_1.AttachmentClient({
+            httpUrl: this.httpUrl,
+            fetchFn: this.fetchFn,
+            getValidDropOnAirJwt: () => this.getValidDropOnAirJwt(false),
+            fetchDeviceKeys: (userId) => this.fetchDeviceKeys(userId),
+            fetchMyOtherDeviceKeys: (myDeviceId) => this.fetchMyOtherDeviceKeys(myDeviceId),
+            getCurrentUserId: () => {
+                if (!this.currentUserId)
+                    throw new Error('Not connected; userId unknown');
+                return this.currentUserId;
+            },
+            getCurrentDeviceId: () => this.deviceId ? Promise.resolve(this.deviceId) : this.getOrCreateDeviceId(),
+            getKeyStorage: () => this.storage,
+            cryptoService: this.cryptoService,
+            log: (stage, data) => this.log(stage, data),
+            logError: (stage, data) => this.logError(stage, data),
+        });
+    }
+    // Attachment API (phase1/attachments, PROTOCOL_VERSION 4+)
+    async prepareAttachmentAndUpload(bytes, options) {
+        return this.attachmentClient.prepareAttachmentAndUpload(bytes, options);
+    }
+    async createUploadSession(options) {
+        return this.attachmentClient.createUploadSession(options);
+    }
+    async finalizeAttachment(attachmentId, sha256) {
+        return this.attachmentClient.finalize(attachmentId, sha256);
+    }
+    async downloadAttachment(ref) {
+        return this.attachmentClient.downloadAttachment(ref);
     }
     async connect() {
         this.log('connect_start');
@@ -265,7 +298,7 @@ class MessagingClient {
         }
         this.emitEvent({ type: 'DISCONNECTED' });
     }
-    async sendMessage(toUserId, plaintextMessage) {
+    async sendMessage(toUserId, plaintextMessage, options) {
         if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
             throw new Error('DropOnAir websocket is not connected');
         }
@@ -325,6 +358,9 @@ class MessagingClient {
                 devicePayloads,
                 senderDeviceId: myDeviceId,
             };
+            if (options?.attachments && options.attachments.length > 0) {
+                envelope.attachments = options.attachments.map(a => this.attachmentClient.toWire(a));
+            }
             this.ws.send(this.codec.encodeEnvelope(envelope));
         }
         else {
@@ -345,6 +381,9 @@ class MessagingClient {
                 encryptedPayload,
                 clientMessageId: messageId
             };
+            if (options?.attachments && options.attachments.length > 0) {
+                envelope.attachments = options.attachments.map(a => this.attachmentClient.toWire(a));
+            }
             this.ws.send(this.codec.encodeEnvelope(envelope));
         }
         return { messageId };
@@ -363,6 +402,129 @@ class MessagingClient {
         this.eventListeners.add(callback);
         return () => this.eventListeners.delete(callback);
     }
+    onMessageEdit(callback) {
+        this.messageEditListeners.add(callback);
+        return () => this.messageEditListeners.delete(callback);
+    }
+    onMessageDelete(callback) {
+        this.messageDeleteListeners.add(callback);
+        return () => this.messageDeleteListeners.delete(callback);
+    }
+    // ---------------------------------------------------------------------------
+    // Message edit and delete (PROTOCOL_VERSION 3+)
+    // ---------------------------------------------------------------------------
+    async editMessage(originalMessageId, toUserId, newPlaintext) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('DropOnAir websocket is not connected');
+        }
+        if (!this.currentUserId) {
+            throw new Error('Missing sender identity from DropOnAir JWT subject');
+        }
+        if (this.rateLimited) {
+            throw new Error('Sending is temporarily blocked by LIMIT_REACHED');
+        }
+        if (this.dropOnAirJwt && (0, bytes_1.isJwtExpired)(this.dropOnAirJwt)) {
+            throw new Error('JWT_EXPIRED: Secure messaging session is reconnecting; please retry in a moment');
+        }
+        const myDeviceId = this.deviceId ?? await this.getOrCreateDeviceId();
+        const editId = crypto.randomUUID();
+        const timestamp = Date.now();
+        // Encrypt new content for all recipient devices + sender's other devices,
+        // exactly mirroring sendMessage. The relay never sees plaintext.
+        const myIdentity = await this.cryptoService.getOrCreateIdentity();
+        const myPublicKeyBytes = (0, bytes_1.fromBase64)(myIdentity.publicKey);
+        const peerDeviceKeys = await this.fetchDeviceKeys(toUserId);
+        const myOtherDeviceKeys = await this.fetchMyOtherDeviceKeys(myDeviceId);
+        const allTargetKeys = [
+            ...peerDeviceKeys.map(dk => ({ ...dk, isRecipient: true })),
+            ...myOtherDeviceKeys.map(dk => ({ ...dk, isRecipient: false })),
+        ];
+        if (allTargetKeys.length === 0) {
+            throw new Error('No recipient device keys available for edit');
+        }
+        const devicePayloads = [];
+        for (const target of allTargetKeys) {
+            const peerUserIdForHkdf = target.isRecipient ? toUserId : this.currentUserId;
+            const sharedKey = await this.cryptoService.deriveSharedSecret(peerUserIdForHkdf, target.publicKey, this.currentUserId);
+            const encrypted = await this.cryptoService.encrypt(newPlaintext, sharedKey, {
+                messageId: editId,
+                senderId: this.currentUserId,
+                recipientId: toUserId,
+                timestamp,
+            });
+            devicePayloads.push({
+                deviceId: target.deviceId,
+                encryptedPayload: encrypted,
+                senderPublicKey: myPublicKeyBytes,
+            });
+        }
+        const frame = {
+            type: 'MESSAGE_EDIT',
+            editId,
+            originalMessageId,
+            appId: this.options.appId,
+            fromUserId: this.currentUserId,
+            toUserId,
+            timestamp,
+            encryptionType: 0, // E2EE
+            devicePayloads,
+            senderDeviceId: myDeviceId,
+            clientEditId: editId,
+        };
+        this.ws.send(this.codec.encodeMessageEditFrame(frame));
+        return { editId };
+    }
+    async editCleartextMessage(originalMessageId, toUserId, newPlaintext) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('DropOnAir websocket is not connected');
+        }
+        if (!this.currentUserId) {
+            throw new Error('Missing sender identity from DropOnAir JWT subject');
+        }
+        if (this.dropOnAirJwt && (0, bytes_1.isJwtExpired)(this.dropOnAirJwt)) {
+            throw new Error('JWT_EXPIRED: Secure messaging session is reconnecting; please retry in a moment');
+        }
+        const editId = crypto.randomUUID();
+        const frame = {
+            type: 'MESSAGE_EDIT',
+            editId,
+            originalMessageId,
+            appId: this.options.appId,
+            fromUserId: this.currentUserId,
+            toUserId,
+            timestamp: Date.now(),
+            encryptionType: 1, // CLEARTEXT
+            plaintextPayload: newPlaintext,
+            clientEditId: editId,
+        };
+        this.ws.send(this.codec.encodeMessageEditFrame(frame));
+        return { editId };
+    }
+    async deleteMessage(originalMessageId, toUserId, scope) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('DropOnAir websocket is not connected');
+        }
+        if (!this.currentUserId) {
+            throw new Error('Missing sender identity from DropOnAir JWT subject');
+        }
+        if (this.dropOnAirJwt && (0, bytes_1.isJwtExpired)(this.dropOnAirJwt)) {
+            throw new Error('JWT_EXPIRED: Secure messaging session is reconnecting; please retry in a moment');
+        }
+        const deleteId = crypto.randomUUID();
+        const frame = {
+            type: 'MESSAGE_DELETE',
+            deleteId,
+            originalMessageId,
+            appId: this.options.appId,
+            fromUserId: this.currentUserId,
+            toUserId,
+            timestamp: Date.now(),
+            scope,
+            clientDeleteId: deleteId,
+        };
+        this.ws.send(this.codec.encodeMessageDeleteFrame(frame));
+        return { deleteId };
+    }
     // ---------------------------------------------------------------------------
     // Cleartext messaging (no E2EE key exchange required)
     // ---------------------------------------------------------------------------
@@ -910,9 +1072,111 @@ class MessagingClient {
                     this.emitBroadcast(frame.data);
                     return;
                 }
-                await this.handleIncomingEnvelope(frame.data);
+                if (frame.kind === 'messageEdit') {
+                    await this.handleIncomingMessageEdit(frame.data);
+                    return;
+                }
+                if (frame.kind === 'messageDelete') {
+                    this.handleIncomingMessageDelete(frame.data);
+                    return;
+                }
+                if (frame.kind === 'envelope') {
+                    await this.handleIncomingEnvelope(frame.data);
+                }
+            };
+        });
+    }
+    async handleIncomingMessageEdit(frame) {
+        try {
+            this.log('incoming_message_edit_received', {
+                editId: frame.editId,
+                originalMessageId: frame.originalMessageId,
+                fromUserId: frame.fromUserId,
+                toUserId: frame.toUserId,
+                timestamp: frame.timestamp,
+                encryptionType: frame.encryptionType,
+                hasDevicePayloads: !!(frame.devicePayloads && frame.devicePayloads.length > 0),
+            });
+            let plaintext;
+            if (frame.encryptionType === 1) {
+                plaintext = frame.plaintextPayload ?? '';
+            }
+            else if (frame.devicePayloads && frame.devicePayloads.length > 0) {
+                const myDeviceId = this.deviceId ?? await this.getOrCreateDeviceId();
+                const myPayload = frame.devicePayloads.find(dp => dp.deviceId === myDeviceId);
+                if (!myPayload) {
+                    this.log('incoming_message_edit_no_device_payload', {
+                        editId: frame.editId,
+                        myDeviceId,
+                        availableDeviceIds: frame.devicePayloads.map(dp => dp.deviceId),
+                    });
+                    return;
+                }
+                const senderPublicKeyBase64 = (0, bytes_1.toBase64)(myPayload.senderPublicKey);
+                const isSelfSync = frame.fromUserId === this.currentUserId;
+                const peerUserIdForHkdf = isSelfSync ? this.currentUserId : frame.fromUserId;
+                const sharedKey = await this.cryptoService.deriveSharedSecret(peerUserIdForHkdf, senderPublicKeyBase64, this.currentUserId);
+                plaintext = await this.cryptoService.decrypt(myPayload.encryptedPayload, sharedKey, {
+                    messageId: frame.editId,
+                    senderId: frame.fromUserId,
+                    recipientId: frame.toUserId,
+                    timestamp: frame.timestamp,
+                });
+            }
+            else if (frame.encryptedPayload && frame.encryptedPayload.length > 0) {
+                const sharedKey = await this.getPeerSharedKey(frame.fromUserId);
+                plaintext = await this.cryptoService.decrypt(frame.encryptedPayload, sharedKey, {
+                    messageId: frame.editId,
+                    senderId: frame.fromUserId,
+                    recipientId: frame.toUserId,
+                    timestamp: frame.timestamp,
+                });
+            }
+            else {
+                this.log('incoming_message_edit_no_payload', { editId: frame.editId });
+                return;
+            }
+            const event = {
+                editId: frame.editId,
+                originalMessageId: frame.originalMessageId,
+                fromUserId: frame.fromUserId,
+                toUserId: frame.toUserId,
+                timestamp: frame.timestamp,
+                plaintext,
             };
+            for (const listener of this.messageEditListeners) {
+                listener(event);
+            }
+        }
+        catch (error) {
+            this.logError('incoming_message_edit_failed', {
+                editId: frame.editId,
+                originalMessageId: frame.originalMessageId,
+                error: String(error?.message ?? error),
+            });
+            this.emitEvent({ type: 'ERROR', reason: 'DECRYPT_FAILED', metadata: frame.editId });
+        }
+    }
+    handleIncomingMessageDelete(frame) {
+        this.log('incoming_message_delete_received', {
+            deleteId: frame.deleteId,
+            originalMessageId: frame.originalMessageId,
+            fromUserId: frame.fromUserId,
+            toUserId: frame.toUserId,
+            scope: frame.scope,
+            timestamp: frame.timestamp,
         });
+        const event = {
+            deleteId: frame.deleteId,
+            originalMessageId: frame.originalMessageId,
+            fromUserId: frame.fromUserId,
+            toUserId: frame.toUserId,
+            timestamp: frame.timestamp,
+            scope: frame.scope,
+        };
+        for (const listener of this.messageDeleteListeners) {
+            listener(event);
+        }
     }
     async handleIncomingEnvelope(envelope) {
         try {
@@ -964,15 +1228,20 @@ class MessagingClient {
                     timestamp: envelope.timestamp
                 });
             }
+            const attachments = envelope.attachments && envelope.attachments.length > 0
+                ? envelope.attachments.map(w => attachment_client_1.AttachmentClient.fromWire(w))
+                : undefined;
             this.emitMessage({
                 messageId: envelope.messageId,
                 fromUserId: envelope.fromUserId,
                 toUserId: envelope.toUserId,
                 timestamp: envelope.timestamp,
-                plaintext
+                plaintext,
+                attachments,
             });
             this.log('incoming_envelope_emitted', {
                 messageId: envelope.messageId,
+                attachmentCount: attachments?.length ?? 0,
             });
             if (this.autoAckIncomingMessages) {
                 await this.ack(envelope.messageId);
@@ -1190,6 +1459,48 @@ class MessagingClient {
                 await this.handleIncomingEnvelope(wireEnvelope);
                 totalProcessed += 1;
             }
+            // Replay pending edits/tombstones for this page
+            if (body.pendingEdits && body.pendingEdits.length > 0) {
+                for (const offlineEdit of body.pendingEdits) {
+                    const wireEdit = {
+                        type: 'MESSAGE_EDIT',
+                        editId: offlineEdit.editId,
+                        originalMessageId: offlineEdit.originalMessageId,
+                        appId: offlineEdit.appId,
+                        fromUserId: offlineEdit.fromUserId,
+                        toUserId: offlineEdit.toUserId,
+                        timestamp: new Date(offlineEdit.createdAt).getTime(),
+                        encryptionType: offlineEdit.encryptionType === 'CLEARTEXT' ? 1 : 0,
+                        encryptedPayload: offlineEdit.encryptedPayloadBase64
+                            ? (0, bytes_1.fromBase64)(offlineEdit.encryptedPayloadBase64)
+                            : new Uint8Array(0),
+                        plaintextPayload: offlineEdit.plaintextPayload,
+                    };
+                    if (offlineEdit.devicePayloads && offlineEdit.devicePayloads.length > 0) {
+                        wireEdit.devicePayloads = offlineEdit.devicePayloads.map(dp => ({
+                            deviceId: dp.deviceId,
+                            encryptedPayload: (0, bytes_1.fromBase64)(dp.encryptedPayloadBase64),
+                            senderPublicKey: (0, bytes_1.fromBase64)(dp.senderPublicKeyBase64),
+                        }));
+                        wireEdit.senderDeviceId = offlineEdit.senderDeviceId;
+                    }
+                    await this.handleIncomingMessageEdit(wireEdit);
+                }
+            }
+            if (body.pendingTombstones && body.pendingTombstones.length > 0) {
+                for (const offlineTomb of body.pendingTombstones) {
+                    this.handleIncomingMessageDelete({
+                        type: 'MESSAGE_DELETE',
+                        deleteId: offlineTomb.deleteId,
+                        originalMessageId: offlineTomb.originalMessageId,
+                        appId: offlineTomb.appId,
+                        fromUserId: offlineTomb.fromUserId,
+                        toUserId: offlineTomb.toUserId,
+                        timestamp: new Date(offlineTomb.createdAt).getTime(),
+                        scope: offlineTomb.scope,
+                    });
+                }
+            }
             page += 1;
         }
         this.log('offline_fetch_completed', {

package/dist/core/types.d.ts

@@ -10,9 +10,44 @@ export interface DecryptedMessage {
     toUserId: string;
     timestamp: number;
     plaintext: string;
+    /**
+     * Attachment pointers (phase1/attachments, PROTOCOL_VERSION 4+).
+     * Empty/undefined for messages with no attachments. To fetch and decrypt the
+     * bytes, call {@code client.downloadAttachment(ref)}.
+     */
+    attachments?: import('../attachment/attachment-types').AttachmentRef[];
 }
 export type MessageCallback = (message: DecryptedMessage) => void;
 export type EventCallback = (event: DropOnAirEvent) => void;
+/**
+ * Delivered to recipient devices when a sender edits a previously sent message.
+ * For E2EE messages the SDK has already decrypted the new payload.
+ * UI is the application's responsibility, render an "edited" badge if desired.
+ */
+export interface MessageEditEvent {
+    editId: string;
+    originalMessageId: string;
+    fromUserId: string;
+    toUserId: string;
+    timestamp: number;
+    /** New plaintext for both E2EE (after decryption) and CLEARTEXT messages. */
+    plaintext: string;
+}
+/**
+ * Delivered to recipient devices when a sender deletes a previously sent message
+ * with scope FOR_EVERYONE. Application should remove or replace the displayed
+ * content with a "message deleted" placeholder.
+ */
+export interface MessageDeleteEvent {
+    deleteId: string;
+    originalMessageId: string;
+    fromUserId: string;
+    toUserId: string;
+    timestamp: number;
+    scope: 'FOR_EVERYONE' | 'FOR_ME' | string;
+}
+export type MessageEditCallback = (event: MessageEditEvent) => void;
+export type MessageDeleteCallback = (event: MessageDeleteEvent) => void;
 export interface BroadcastMessage {
     broadcastId: string;
     channelId: string;
@@ -100,12 +135,53 @@ export interface InitializeOptions {
 export interface DropOnAirClient {
     connect(): Promise<void>;
     disconnect(): void;
-    sendMessage(toUserId: string, plaintextMessage: string): Promise<{
+    /**
+     * Send a 1:1 E2EE message. Optionally attach one or more attachments
+     * prepared via {@link prepareAttachmentAndUpload} or {@link createUploadSession}.
+     */
+    sendMessage(toUserId: string, plaintextMessage: string, options?: {
+        attachments?: import('../attachment/attachment-types').AttachmentRef[];
+    }): Promise<{
         messageId: string;
     }>;
     onMessage(callback: MessageCallback): () => void;
     onEvent(callback: EventCallback): () => void;
     ack(messageId: string): Promise<void>;
+    /**
+     * Edit a previously sent message. For E2EE messages the new plaintext is
+     * re-encrypted per recipient device exactly like a new message. For
+     * CLEARTEXT messages the server overwrites the stored plaintext.
+     * Edit window is unlimited.
+     */
+    editMessage(originalMessageId: string, toUserId: string, newPlaintext: string): Promise<{
+        editId: string;
+    }>;
+    /**
+     * Delete a previously sent message. Scope FOR_EVERYONE records a server
+     * tombstone and fans out a notification to recipient devices. Scope FOR_ME
+     * is local-only by convention but the server still records the tombstone
+     * (without fan-out) so the deletion survives across the sender's own devices.
+     * Delete window is unlimited.
+     */
+    deleteMessage(originalMessageId: string, toUserId: string, scope: 'FOR_EVERYONE' | 'FOR_ME'): Promise<{
+        deleteId: string;
+    }>;
+    /** Register a listener for incoming message-edit notifications. */
+    onMessageEdit(callback: MessageEditCallback): () => void;
+    /** Register a listener for incoming message-delete notifications. */
+    onMessageDelete(callback: MessageDeleteCallback): () => void;
+    /**
+     * Convenience: encrypts (E2EE), uploads to the customer's bucket, finalizes,
+     * and returns an AttachmentRef ready to pass into {@link sendMessage}.
+     * For CLEARTEXT, bytes are uploaded unencrypted.
+     */
+    prepareAttachmentAndUpload(bytes: Uint8Array, options: import('../attachment/attachment-types').PrepareAttachmentOptions): Promise<import('../attachment/attachment-types').AttachmentRef>;
+    /** Low-level: reserve an upload session (presigned URL) without uploading. */
+    createUploadSession(options: import('../attachment/attachment-types').CreateUploadSessionOptions): Promise<import('../attachment/attachment-types').UploadSession>;
+    /** Low-level: finalize an upload, committing the integrity hash. */
+    finalizeAttachment(attachmentId: string, sha256: string): Promise<void>;
+    /** Download (and for E2EE decrypt) an attachment referenced inside a received message. */
+    downloadAttachment(ref: import('../attachment/attachment-types').AttachmentRef): Promise<import('../attachment/attachment-types').DownloadedAttachment>;
     /** Send a cleartext message to a user (no encryption). */
     sendCleartextMessage(toUserId: string, plaintext: string): Promise<{
         messageId: string;

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import { InitializeOptions, DropOnAirClient } from './core/types';
 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, } from './core/types';
+export type { InitializeOptions, DropOnAirClient, DropOnAirEvent, MessageCallback, EventCallback, DecryptedMessage, KeyStorageAdapter, CallEvent, CallEventType, CallEventCallback, TurnCredentials, BroadcastMessage, BroadcastCallback, GroupInfo, GroupMemberInfo, DecryptedGroupMessage, GroupMessageCallback, GroupCallEvent, GroupCallEventType, GroupCallEventCallback, MessageEditEvent, MessageEditCallback, MessageDeleteEvent, MessageDeleteCallback, } from './core/types';
+export type { AttachmentEncryptionType, AttachmentConversationType, AttachmentRef, DeviceWrappedKey, CreateUploadSessionOptions, UploadSession, PrepareAttachmentOptions, DownloadedAttachment, } from './attachment/attachment-types';
 declare const _default: {
     initialize: typeof initialize;
 };

package/dist/transport/protobuf-codec.d.ts

@@ -4,6 +4,23 @@ export interface WireDeviceEncryptedPayload {
     encryptedPayload: Uint8Array;
     senderPublicKey: Uint8Array;
 }
+/** Per-device wrapped AES-256-GCM file key for E2EE attachments. */
+export interface WireDeviceWrappedKey {
+    deviceId: string;
+    wrappedKey: Uint8Array;
+    senderPublicKey: Uint8Array;
+    nonce: Uint8Array;
+}
+/** Pointer to an attachment in the customer's storage bucket. */
+export interface WireAttachmentRef {
+    attachmentId: string;
+    storageHint: string;
+    mimeType: string;
+    sizeBytes: number;
+    sha256: string;
+    encryptionType: number;
+    wrappedKeys?: WireDeviceWrappedKey[];
+}
 export interface WireEnvelope {
     messageId: string;
     appId: string;
@@ -20,6 +37,8 @@ export interface WireEnvelope {
     encryptionType?: number;
     /** Populated only when encryptionType = CLEARTEXT. */
     plaintextPayload?: string;
+    /** Zero or more attachment pointers (PROTOCOL_VERSION 4+). */
+    attachments?: WireAttachmentRef[];
 }
 export interface WireAck {
     messageId: string;
@@ -93,6 +112,38 @@ export interface WireGroupCallFrame {
     targetUserId?: string;
     payload?: string;
 }
+/**
+ * Edit frame, sender re-encrypts new content for all recipient devices.
+ * Same shape sent in both directions, client to server (request) and
+ * server to recipient devices (notification).
+ */
+export interface WireMessageEditFrame {
+    type: string;
+    editId: string;
+    originalMessageId: string;
+    appId: string;
+    fromUserId: string;
+    toUserId: string;
+    timestamp: number;
+    encryptionType: number;
+    encryptedPayload?: Uint8Array;
+    devicePayloads?: WireDeviceEncryptedPayload[];
+    senderDeviceId?: string;
+    plaintextPayload?: string;
+    clientEditId?: string;
+}
+/** Tombstone frame, scope FOR_EVERYONE or FOR_ME. */
+export interface WireMessageDeleteFrame {
+    type: string;
+    deleteId: string;
+    originalMessageId: string;
+    appId: string;
+    fromUserId: string;
+    toUserId: string;
+    timestamp: number;
+    scope: string;
+    clientDeleteId?: string;
+}
 export type InboundFrame = {
     kind: 'envelope';
     data: WireEnvelope;
@@ -117,6 +168,12 @@ export type InboundFrame = {
 } | {
     kind: 'groupCall';
     data: WireGroupCallFrame;
+} | {
+    kind: 'messageEdit';
+    data: WireMessageEditFrame;
+} | {
+    kind: 'messageDelete';
+    data: WireMessageDeleteFrame;
 };
 export declare class ProtobufCodec {
     encodeEnvelope(value: WireEnvelope): Uint8Array;
@@ -126,6 +183,8 @@ export declare class ProtobufCodec {
     encodeGroupEnvelope(value: WireGroupEnvelope): Uint8Array;
     encodeGroupCallFrame(value: WireGroupCallFrame): Uint8Array;
     encodeGroupAck(value: WireGroupAck): Uint8Array;
+    encodeMessageEditFrame(value: WireMessageEditFrame): Uint8Array;
+    encodeMessageDeleteFrame(value: WireMessageDeleteFrame): Uint8Array;
     decodeFrame(payload: Uint8Array): InboundFrame;
     private tryDecodeEnvelope;
     private tryDecodeAck;
@@ -135,4 +194,6 @@ export declare class ProtobufCodec {
     private tryDecodeGroupMessageNotification;
     private tryDecodeGroupAck;
     private tryDecodeGroupCallFrame;
+    private tryDecodeMessageEditFrame;
+    private tryDecodeMessageDeleteFrame;
 }