@dropgate/core 2.2.0 → 3.0.0

package/dist/p2p/index.d.ts

@@ -12,6 +12,8 @@ interface UploadCapabilities {
     maxFileDownloads?: number;
     /** Whether end-to-end encryption is supported. */
     e2ee?: boolean;
+    /** Expected upload chunk size in bytes (server-configured). */
+    chunkSize?: number;
 }
 /**
  * Server P2P (direct transfer) capabilities.
@@ -96,11 +98,11 @@ interface FileSource {
  * Finite state machine states for P2P send sessions.
  * Prevents race conditions and ensures callbacks fire in correct order.
  */
-type P2PSendState = 'initializing' | 'listening' | 'negotiating' | 'transferring' | 'finishing' | 'completed' | 'cancelled' | 'closed';
+type P2PSendState = 'initializing' | 'listening' | 'handshaking' | 'negotiating' | 'transferring' | 'finishing' | 'awaiting_ack' | 'completed' | 'cancelled' | 'closed';
 /**
  * Finite state machine states for P2P receive sessions.
  */
-type P2PReceiveState = 'initializing' | 'connecting' | 'negotiating' | 'transferring' | 'completed' | 'cancelled' | 'closed';
+type P2PReceiveState = 'initializing' | 'connecting' | 'handshaking' | 'negotiating' | 'transferring' | 'completed' | 'cancelled' | 'closed';
 /**
  * PeerJS Peer constructor interface.
  * Consumer must provide this constructor to P2P functions.
@@ -204,6 +206,15 @@ interface P2PMetadataEvent {
     total: number;
     /** Call this to signal the sender to begin transfer (when autoReady is false). */
     sendReady?: () => void;
+    /** v3: Total number of files in a multi-file transfer (undefined for single file). */
+    fileCount?: number;
+    /** v3: List of all files (names and sizes) in a multi-file transfer. */
+    files?: Array<{
+        name: string;
+        size: number;
+    }>;
+    /** v3: Total size across all files. */
+    totalSize?: number;
 }
 /** Completion event for P2P receive operations. */
 interface P2PReceiveCompleteEvent {
@@ -217,12 +228,34 @@ interface P2PCancellationEvent {
     /** Optional cancellation message. */
     message?: string;
 }
+/** Connection health event for monitoring. */
+interface P2PConnectionHealthEvent {
+    /** ICE connection state. */
+    iceConnectionState: 'connected' | 'disconnected' | 'failed' | 'checking' | 'new' | 'closed';
+    /** Estimated round-trip time in milliseconds. */
+    rtt?: number;
+    /** Bytes currently buffered waiting to send. */
+    bufferedAmount?: number;
+    /** Milliseconds since last activity. */
+    lastActivityMs: number;
+}
+/** Resumable transfer info. */
+interface P2PResumeInfo {
+    /** Session ID to resume. */
+    sessionId: string;
+    /** Bytes already received in previous session. */
+    receivedBytes: number;
+    /** Total bytes expected. */
+    totalBytes: number;
+    /** Whether resume is possible. */
+    canResume: boolean;
+}
 /**
  * Options for starting a P2P send session.
  */
 interface P2PSendOptions extends P2PServerConfig {
-    /** File to send. */
-    file: FileSource;
+    /** File(s) to send. A single file or an array for multi-file transfers. */
+    file: FileSource | FileSource[];
     /** PeerJS Peer constructor - REQUIRED. */
     Peer: PeerConstructor;
     /** Server info (optional, for capability checking). */
@@ -257,6 +290,16 @@ interface P2PSendOptions extends P2PServerConfig {
     onDisconnect?: () => void;
     /** Callback when transfer is cancelled by either party. */
     onCancel?: (evt: P2PCancellationEvent) => void;
+    /** Enable chunk-level acknowledgments for flow control (default: true). */
+    chunkAcknowledgments?: boolean;
+    /** Maximum unacknowledged chunks before pausing (default: 32). */
+    maxUnackedChunks?: number;
+    /** ICE restart timeout in ms (default: 10000). */
+    iceRestartTimeoutMs?: number;
+    /** Connection health monitoring callback. */
+    onConnectionHealth?: (evt: P2PConnectionHealthEvent) => void;
+    /** Called when receiver requests resume from offset. */
+    onResumeRequest?: (info: P2PResumeInfo) => boolean;
 }
 /**
  * Return value from startP2PSend containing session control.
@@ -311,6 +354,17 @@ interface P2PReceiveOptions extends P2PServerConfig {
     onData?: (chunk: Uint8Array) => Promise<void> | void;
     /** Callback for progress updates. */
     onProgress?: (evt: P2PReceiveProgressEvent) => void;
+    /** Callback when an individual file starts in a multi-file transfer. */
+    onFileStart?: (evt: {
+        fileIndex: number;
+        name: string;
+        size: number;
+    }) => void;
+    /** Callback when an individual file ends in a multi-file transfer. */
+    onFileEnd?: (evt: {
+        fileIndex: number;
+        receivedBytes: number;
+    }) => void;
     /** Callback when transfer completes. */
     onComplete?: (evt: P2PReceiveCompleteEvent) => void;
     /** Callback on error. */
@@ -337,6 +391,109 @@ interface P2PReceiveSession {
     /** Get the current session ID (if received from sender). */
     getSessionId: () => string | null;
 }
+/**
+ * Options for DropgateClient.p2pSend().
+ * Server connection, serverInfo, peerjsPath, iceServers, and cryptoObj
+ * are all provided internally by the client.
+ */
+interface P2PSendFileOptions {
+    /** File(s) to send. A single file or an array for multi-file transfers. */
+    file: FileSource | FileSource[];
+    /** PeerJS Peer constructor - REQUIRED. */
+    Peer: PeerConstructor;
+    /** Custom code generator function. */
+    codeGenerator?: (cryptoObj?: CryptoAdapter) => string;
+    /** Max attempts to register a peer ID. */
+    maxAttempts?: number;
+    /** Chunk size for data transfer. */
+    chunkSize?: number;
+    /** Timeout waiting for end acknowledgment. */
+    endAckTimeoutMs?: number;
+    /** Buffer high water mark for flow control. */
+    bufferHighWaterMark?: number;
+    /** Buffer low water mark for flow control. */
+    bufferLowWaterMark?: number;
+    /** Heartbeat interval in ms for long transfers (default: 5000, 0 to disable). */
+    heartbeatIntervalMs?: number;
+    /** Enable chunk-level acknowledgments for flow control (default: true). */
+    chunkAcknowledgments?: boolean;
+    /** Maximum unacknowledged chunks before pausing (default: 32). */
+    maxUnackedChunks?: number;
+    /** ICE restart timeout in ms (default: 10000). */
+    iceRestartTimeoutMs?: number;
+    /** Callback when code is generated. */
+    onCode?: (code: string, attempt: number) => void;
+    /** Callback for status updates. */
+    onStatus?: (evt: P2PStatusEvent) => void;
+    /** Callback for progress updates. */
+    onProgress?: (evt: P2PSendProgressEvent) => void;
+    /** Callback when transfer completes. */
+    onComplete?: () => void;
+    /** Callback on error. */
+    onError?: (err: Error) => void;
+    /** Callback when receiver disconnects. */
+    onDisconnect?: () => void;
+    /** Callback when transfer is cancelled by either party. */
+    onCancel?: (evt: P2PCancellationEvent) => void;
+    /** Connection health monitoring callback. */
+    onConnectionHealth?: (evt: P2PConnectionHealthEvent) => void;
+    /** Called when receiver requests resume from offset. */
+    onResumeRequest?: (info: P2PResumeInfo) => boolean;
+}
+/**
+ * Options for DropgateClient.p2pReceive().
+ * Server connection, serverInfo, peerjsPath, and iceServers
+ * are all provided internally by the client.
+ */
+interface P2PReceiveFileOptions {
+    /** Sharing code to connect to. */
+    code: string;
+    /** PeerJS Peer constructor - REQUIRED. */
+    Peer: PeerConstructor;
+    /**
+     * Whether to automatically send the "ready" signal after receiving metadata.
+     * Default: true.
+     * Set to false to show a preview and manually control when the transfer starts.
+     * When false, call the sendReady function passed to onMeta to start the transfer.
+     */
+    autoReady?: boolean;
+    /**
+     * Timeout in ms for detecting dead connections (no data received).
+     * Default: 15000 (15 seconds). Set to 0 to disable.
+     */
+    watchdogTimeoutMs?: number;
+    /** Callback for status updates. */
+    onStatus?: (evt: P2PStatusEvent) => void;
+    /**
+     * Callback when file metadata is received.
+     * When autoReady is false, this callback receives a sendReady function
+     * that must be called to signal the sender to begin the transfer.
+     */
+    onMeta?: (evt: P2PMetadataEvent) => void;
+    /** Callback when data chunk is received - consumer handles file writing. */
+    onData?: (chunk: Uint8Array) => Promise<void> | void;
+    /** Callback for progress updates. */
+    onProgress?: (evt: P2PReceiveProgressEvent) => void;
+    /** Callback when an individual file starts in a multi-file transfer. */
+    onFileStart?: (evt: {
+        fileIndex: number;
+        name: string;
+        size: number;
+    }) => void;
+    /** Callback when an individual file ends in a multi-file transfer. */
+    onFileEnd?: (evt: {
+        fileIndex: number;
+        receivedBytes: number;
+    }) => void;
+    /** Callback when transfer completes. */
+    onComplete?: (evt: P2PReceiveCompleteEvent) => void;
+    /** Callback on error. */
+    onError?: (err: Error) => void;
+    /** Callback when sender disconnects. */
+    onDisconnect?: () => void;
+    /** Callback when transfer is cancelled by either party. */
+    onCancel?: (evt: P2PCancellationEvent) => void;
+}
 
 /**
  * Start a direct transfer (P2P) sender session.
@@ -344,6 +501,12 @@ interface P2PReceiveSession {
  * IMPORTANT: Consumer must provide the PeerJS Peer constructor.
  * This removes DOM coupling (no script injection).
  *
+ * Protocol v2 features:
+ * - Explicit version handshake
+ * - Chunk-level acknowledgments for flow control
+ * - Multiple end-ack retries for reliability
+ * - Stream-through design for unlimited file sizes
+ *
  * Example:
  * ```js
  * import Peer from 'peerjs';
@@ -368,6 +531,12 @@ declare function startP2PSend(opts: P2PSendOptions): Promise<P2PSendSession>;
  * IMPORTANT: Consumer must provide the PeerJS Peer constructor and handle file writing.
  * This removes DOM coupling (no streamSaver).
  *
+ * Protocol v2 features:
+ * - Explicit version handshake
+ * - Chunk-level acknowledgments for flow control
+ * - Multiple end-ack sends for reliability
+ * - Stream-through design for unlimited file sizes
+ *
  * Example:
  * ```js
  * import Peer from 'peerjs';
@@ -441,4 +610,196 @@ declare function createPeerWithRetries(opts: CreatePeerWithRetriesOptions): Prom
     code: string;
 }>;
 
-export { type DataConnection, type DataConnectionEvents, type P2PMetadataEvent, type P2PReceiveCompleteEvent, type P2PReceiveOptions, type P2PReceiveProgressEvent, type P2PReceiveSession, type P2PReceiveState, type P2PSendOptions, type P2PSendProgressEvent, type P2PSendSession, type P2PSendState, type P2PServerConfig, type P2PStatusEvent, type PeerConstructor, type PeerInstance, type PeerInstanceEvents, type PeerOptions, buildPeerOptions, createPeerWithRetries, generateP2PCode, isLocalhostHostname, isP2PCodeLike, isSecureContextForP2P, resolvePeerConfig, startP2PReceive, startP2PSend };
+/**
+ * P2P Protocol Definitions
+ *
+ * This file defines the application-level protocol for P2P file transfers.
+ * Protocol version 2 introduces:
+ * - Explicit handshake with version negotiation
+ * - Chunk-level acknowledgments for flow control
+ * - Multiple end-ack retries for reliability
+ * - Resume capability support
+ *
+ * Protocol version 3 introduces:
+ * - Multi-file transfers via file_list, file_end, file_end_ack messages
+ * - Sequential file-by-file transfer within a single session
+ */
+declare const P2P_PROTOCOL_VERSION = 3;
+/**
+ * All possible P2P message types.
+ */
+type P2PMessageType = 'hello' | 'file_list' | 'meta' | 'ready' | 'chunk' | 'chunk_ack' | 'file_end' | 'file_end_ack' | 'end' | 'end_ack' | 'ping' | 'pong' | 'error' | 'cancelled' | 'resume' | 'resume_ack';
+/**
+ * Base interface for all P2P messages.
+ */
+interface P2PMessageBase {
+    t: P2PMessageType;
+}
+/**
+ * Initial handshake message exchanged between sender and receiver.
+ */
+interface P2PHelloMessage extends P2PMessageBase {
+    t: 'hello';
+    protocolVersion: number;
+    sessionId: string;
+}
+/**
+ * v3: File list sent by sender after handshake for multi-file transfers.
+ */
+interface P2PFileListMessage extends P2PMessageBase {
+    t: 'file_list';
+    fileCount: number;
+    files: Array<{
+        name: string;
+        size: number;
+        mime: string;
+    }>;
+    totalSize: number;
+}
+/**
+ * File metadata sent by sender after handshake (single file)
+ * or before each file's chunks in multi-file mode.
+ */
+interface P2PMetaMessage extends P2PMessageBase {
+    t: 'meta';
+    sessionId: string;
+    name: string;
+    size: number;
+    mime: string;
+    /** v3: File index within the file list (0-based). Absent for single-file transfers. */
+    fileIndex?: number;
+}
+/**
+ * Receiver signals readiness to receive data.
+ */
+interface P2PReadyMessage extends P2PMessageBase {
+    t: 'ready';
+}
+/**
+ * Chunk header sent before binary data.
+ * The actual binary data follows immediately after this message.
+ */
+interface P2PChunkMessage extends P2PMessageBase {
+    t: 'chunk';
+    seq: number;
+    offset: number;
+    size: number;
+    total: number;
+}
+/**
+ * Acknowledgment for a received chunk.
+ */
+interface P2PChunkAckMessage extends P2PMessageBase {
+    t: 'chunk_ack';
+    seq: number;
+    received: number;
+}
+/**
+ * v3: Sender signals all chunks for the current file have been sent.
+ */
+interface P2PFileEndMessage extends P2PMessageBase {
+    t: 'file_end';
+    fileIndex: number;
+    attempt?: number;
+}
+/**
+ * v3: Receiver confirms current file receipt.
+ */
+interface P2PFileEndAckMessage extends P2PMessageBase {
+    t: 'file_end_ack';
+    fileIndex: number;
+    received: number;
+    size: number;
+}
+/**
+ * Sender signals all chunks have been sent.
+ */
+interface P2PEndMessage extends P2PMessageBase {
+    t: 'end';
+    attempt?: number;
+}
+/**
+ * Receiver confirms transfer completion.
+ */
+interface P2PEndAckMessage extends P2PMessageBase {
+    t: 'end_ack';
+    received: number;
+    total: number;
+}
+/**
+ * Heartbeat ping.
+ */
+interface P2PPingMessage extends P2PMessageBase {
+    t: 'ping';
+    timestamp: number;
+}
+/**
+ * Heartbeat pong response.
+ */
+interface P2PPongMessage extends P2PMessageBase {
+    t: 'pong';
+    timestamp: number;
+}
+/**
+ * Error message sent when something goes wrong.
+ */
+interface P2PErrorMessage extends P2PMessageBase {
+    t: 'error';
+    message: string;
+    code?: string;
+}
+/**
+ * Cancellation message sent when user cancels transfer.
+ */
+interface P2PCancelledMessage extends P2PMessageBase {
+    t: 'cancelled';
+    reason?: string;
+}
+/**
+ * Resume request sent by receiver to continue interrupted transfer.
+ */
+interface P2PResumeMessage extends P2PMessageBase {
+    t: 'resume';
+    sessionId: string;
+    receivedBytes: number;
+}
+/**
+ * Resume acknowledgment from sender.
+ */
+interface P2PResumeAckMessage extends P2PMessageBase {
+    t: 'resume_ack';
+    resumeFromOffset: number;
+    accepted: boolean;
+}
+/**
+ * Union type of all possible P2P messages.
+ */
+type P2PMessage = P2PHelloMessage | P2PFileListMessage | P2PMetaMessage | P2PReadyMessage | P2PChunkMessage | P2PChunkAckMessage | P2PFileEndMessage | P2PFileEndAckMessage | P2PEndMessage | P2PEndAckMessage | P2PPingMessage | P2PPongMessage | P2PErrorMessage | P2PCancelledMessage | P2PResumeMessage | P2PResumeAckMessage;
+/**
+ * Type guard to check if a value is a valid P2P message.
+ */
+declare function isP2PMessage(value: unknown): value is P2PMessage;
+/**
+ * Check if protocol versions are compatible.
+ */
+declare function isProtocolCompatible(senderVersion: number, receiverVersion: number): boolean;
+/**
+ * Default chunk size for P2P transfers (64KB).
+ * Smaller than standard upload to reduce latency and improve flow control.
+ */
+declare const P2P_CHUNK_SIZE: number;
+/**
+ * Default maximum unacknowledged chunks before sender pauses.
+ * This creates backpressure when receiver is slow.
+ */
+declare const P2P_MAX_UNACKED_CHUNKS = 32;
+/**
+ * Default timeout for waiting on end acknowledgment (ms).
+ */
+declare const P2P_END_ACK_TIMEOUT_MS = 15000;
+/**
+ * Number of times to retry sending end message.
+ */
+declare const P2P_END_ACK_RETRIES = 3;
+
+export { type DataConnection, type DataConnectionEvents, type P2PCancellationEvent, type P2PCancelledMessage, type P2PChunkAckMessage, type P2PChunkMessage, type P2PConnectionHealthEvent, type P2PEndAckMessage, type P2PEndMessage, type P2PErrorMessage, type P2PHelloMessage, type P2PMessage, type P2PMessageBase, type P2PMessageType, type P2PMetaMessage, type P2PMetadataEvent, type P2PPingMessage, type P2PPongMessage, type P2PReadyMessage, type P2PReceiveCompleteEvent, type P2PReceiveFileOptions, type P2PReceiveOptions, type P2PReceiveProgressEvent, type P2PReceiveSession, type P2PReceiveState, type P2PResumeAckMessage, type P2PResumeInfo, type P2PResumeMessage, type P2PSendFileOptions, type P2PSendOptions, type P2PSendProgressEvent, type P2PSendSession, type P2PSendState, type P2PServerConfig, type P2PStatusEvent, P2P_CHUNK_SIZE, P2P_END_ACK_RETRIES, P2P_END_ACK_TIMEOUT_MS, P2P_MAX_UNACKED_CHUNKS, P2P_PROTOCOL_VERSION, type PeerConstructor, type PeerInstance, type PeerInstanceEvents, type PeerOptions, buildPeerOptions, createPeerWithRetries, generateP2PCode, isLocalhostHostname, isP2PCodeLike, isP2PMessage, isProtocolCompatible, isSecureContextForP2P, resolvePeerConfig, startP2PReceive, startP2PSend };