@dropgate/core 2.0.0-beta.1 → 2.1.0

package/dist/p2p/index.d.ts

@@ -51,6 +51,18 @@ interface ServerInfo {
     /** Server capabilities. */
     capabilities?: ServerCapabilities;
 }
+/**
+ * Base progress event with common fields for all transfer operations.
+ * Provides a consistent interface for upload, download, and P2P progress tracking.
+ */
+interface BaseProgressEvent {
+    /** Completion percentage (0-100). */
+    percent: number;
+    /** Bytes processed so far (sent, received, or uploaded). */
+    processedBytes: number;
+    /** Total bytes expected (may be 0 if unknown). */
+    totalBytes: number;
+}
 /**
  * Crypto adapter interface compatible with the Web Crypto API.
  * Used for encryption operations and secure random generation.
@@ -78,6 +90,15 @@ interface FileSource {
     arrayBuffer(): Promise<ArrayBuffer>;
 }
 
+/**
+ * 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' | 'closed';
+/**
+ * Finite state machine states for P2P receive sessions.
+ */
+type P2PReceiveState = 'initializing' | 'connecting' | 'negotiating' | 'transferring' | 'completed' | 'closed';
 /**
  * PeerJS Peer constructor interface.
  * Consumer must provide this constructor to P2P functions.
@@ -105,16 +126,20 @@ interface PeerOptions {
     /** PeerJS debug level (0-3). */
     debug?: number;
 }
+/** Event handlers for PeerInstance. */
+interface PeerInstanceEvents {
+    open: (id: string) => void;
+    connection: (conn: DataConnection) => void;
+    error: (err: Error) => void;
+    close: () => void;
+}
 /**
  * PeerJS Peer instance interface.
  * Represents a connection to the PeerJS signaling server.
  */
 interface PeerInstance {
     /** Register an event handler. */
-    on(event: 'open', callback: (id: string) => void): void;
-    on(event: 'connection', callback: (conn: DataConnection) => void): void;
-    on(event: 'error', callback: (err: Error) => void): void;
-    on(event: 'close', callback: () => void): void;
+    on<K extends keyof PeerInstanceEvents>(event: K, callback: PeerInstanceEvents[K]): void;
     on(event: string, callback: (...args: unknown[]) => void): void;
     /** Connect to another peer by ID. */
     connect(peerId: string, options?: {
@@ -123,16 +148,20 @@ interface PeerInstance {
     /** Destroy this peer and close all connections. */
     destroy(): void;
 }
+/** Event handlers for DataConnection. */
+interface DataConnectionEvents {
+    open: () => void;
+    data: (data: unknown) => void;
+    close: () => void;
+    error: (err: Error) => void;
+}
 /**
  * PeerJS DataConnection interface.
  * Represents a WebRTC data channel connection between peers.
  */
 interface DataConnection {
     /** Register an event handler. */
-    on(event: 'open', callback: () => void): void;
-    on(event: 'data', callback: (data: unknown) => void): void;
-    on(event: 'close', callback: () => void): void;
-    on(event: 'error', callback: (err: Error) => void): void;
+    on<K extends keyof DataConnectionEvents>(event: K, callback: DataConnectionEvents[K]): void;
     on(event: string, callback: (...args: unknown[]) => void): void;
     /** Send data to the connected peer. */
     send(data: unknown): void;
@@ -142,58 +171,81 @@ interface DataConnection {
     _dc?: RTCDataChannel;
 }
 /**
- * Options for starting a P2P send session.
+ * Common server configuration for P2P connections.
  */
-interface P2PSendOptions {
-    /** File to send */
-    file: FileSource;
-    /** PeerJS Peer constructor - REQUIRED */
-    Peer: PeerConstructor;
-    /** Server info (optional, for capability checking) */
-    serverInfo?: ServerInfo;
-    /** PeerJS server host */
+interface P2PServerConfig {
+    /** PeerJS server host. */
     host?: string;
-    /** PeerJS server port */
+    /** PeerJS server port. */
     port?: number;
-    /** PeerJS server path (default: /peerjs) */
+    /** PeerJS server path (default: /peerjs). */
     peerjsPath?: string;
-    /** Whether to use secure connection */
+    /** Whether to use secure connection. */
     secure?: boolean;
-    /** ICE servers for WebRTC */
+    /** ICE servers for WebRTC. */
     iceServers?: RTCIceServer[];
-    /** Custom code generator function */
+}
+/** Status event for P2P operations. */
+interface P2PStatusEvent {
+    phase: string;
+    message: string;
+}
+/** Progress event for P2P send operations. */
+interface P2PSendProgressEvent extends BaseProgressEvent {
+}
+/** Progress event for P2P receive operations. */
+interface P2PReceiveProgressEvent extends BaseProgressEvent {
+}
+/** Metadata event when receiving a file. */
+interface P2PMetadataEvent {
+    name: string;
+    total: number;
+    /** Call this to signal the sender to begin transfer (when autoReady is false). */
+    sendReady?: () => void;
+}
+/** Completion event for P2P receive operations. */
+interface P2PReceiveCompleteEvent {
+    received: number;
+    total: number;
+}
+/**
+ * Options for starting a P2P send session.
+ */
+interface P2PSendOptions extends P2PServerConfig {
+    /** File to send. */
+    file: FileSource;
+    /** PeerJS Peer constructor - REQUIRED. */
+    Peer: PeerConstructor;
+    /** Server info (optional, for capability checking). */
+    serverInfo?: ServerInfo;
+    /** Custom code generator function. */
     codeGenerator?: (cryptoObj?: CryptoAdapter) => string;
-    /** Crypto object for secure code generation */
+    /** Crypto object for secure code generation. */
     cryptoObj?: CryptoAdapter;
-    /** Max attempts to register a peer ID */
+    /** Max attempts to register a peer ID. */
     maxAttempts?: number;
-    /** Chunk size for data transfer */
+    /** Chunk size for data transfer. */
     chunkSize?: number;
-    /** Timeout waiting for receiver ready signal */
-    readyTimeoutMs?: number;
-    /** Timeout waiting for end acknowledgment */
+    /** Timeout waiting for end acknowledgment. */
     endAckTimeoutMs?: number;
-    /** Buffer high water mark for flow control */
+    /** Buffer high water mark for flow control. */
     bufferHighWaterMark?: number;
-    /** Buffer low water mark for flow control */
+    /** Buffer low water mark for flow control. */
     bufferLowWaterMark?: number;
-    /** Callback when code is generated */
+    /** Heartbeat interval in ms for long transfers (default: 5000, 0 to disable). */
+    heartbeatIntervalMs?: number;
+    /** Callback when code is generated. */
     onCode?: (code: string, attempt: number) => void;
-    /** Callback for status updates */
-    onStatus?: (evt: {
-        phase: string;
-        message: string;
-    }) => void;
-    /** Callback for progress updates */
-    onProgress?: (evt: {
-        sent: number;
-        total: number;
-        percent: number;
-    }) => void;
-    /** Callback when transfer completes */
+    /** 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 */
+    /** Callback on error. */
     onError?: (err: Error) => void;
+    /** Callback when receiver disconnects. */
+    onDisconnect?: () => void;
 }
 /**
  * Return value from startP2PSend containing session control.
@@ -203,55 +255,56 @@ interface P2PSendSession {
     peer: PeerInstance;
     /** The generated sharing code. */
     code: string;
+    /** The unique session ID for this transfer. */
+    sessionId: string;
     /** Stop the session and clean up resources. */
     stop: () => void;
+    /** Get the current session state. */
+    getStatus: () => P2PSendState;
+    /** Get the number of bytes sent so far. */
+    getBytesSent: () => number;
+    /** Get the connected receiver's peer ID (if connected). */
+    getConnectedPeerId: () => string | null;
 }
 /**
  * Options for starting a P2P receive session.
  */
-interface P2PReceiveOptions {
-    /** Sharing code to connect to */
+interface P2PReceiveOptions extends P2PServerConfig {
+    /** Sharing code to connect to. */
     code: string;
-    /** PeerJS Peer constructor - REQUIRED */
+    /** PeerJS Peer constructor - REQUIRED. */
     Peer: PeerConstructor;
-    /** Server info (optional, for capability checking) */
+    /** Server info (optional, for capability checking). */
     serverInfo?: ServerInfo;
-    /** PeerJS server host */
-    host?: string;
-    /** PeerJS server port */
-    port?: number;
-    /** PeerJS server path (default: /peerjs) */
-    peerjsPath?: string;
-    /** Whether to use secure connection */
-    secure?: boolean;
-    /** ICE servers for WebRTC */
-    iceServers?: RTCIceServer[];
-    /** Callback for status updates */
-    onStatus?: (evt: {
-        phase: string;
-        message: string;
-    }) => void;
-    /** Callback when file metadata is received */
-    onMeta?: (evt: {
-        name: string;
-        total: number;
-    }) => void;
-    /** Callback when data chunk is received - consumer handles file writing */
+    /**
+     * 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: {
-        received: number;
-        total: number;
-        percent: number;
-    }) => void;
-    /** Callback when transfer completes */
-    onComplete?: (evt: {
-        received: number;
-        total: number;
-    }) => void;
-    /** Callback on error */
+    /** Callback for progress updates. */
+    onProgress?: (evt: P2PReceiveProgressEvent) => void;
+    /** Callback when transfer completes. */
+    onComplete?: (evt: P2PReceiveCompleteEvent) => void;
+    /** Callback on error. */
     onError?: (err: Error) => void;
-    /** Callback when sender disconnects */
+    /** Callback when sender disconnects. */
     onDisconnect?: () => void;
 }
 /**
@@ -262,6 +315,14 @@ interface P2PReceiveSession {
     peer: PeerInstance;
     /** Stop the session and clean up resources. */
     stop: () => void;
+    /** Get the current session state. */
+    getStatus: () => P2PReceiveState;
+    /** Get the number of bytes received so far. */
+    getBytesReceived: () => number;
+    /** Get the expected total bytes (0 if metadata not received). */
+    getTotalBytes: () => number;
+    /** Get the current session ID (if received from sender). */
+    getSessionId: () => string | null;
 }
 
 /**
@@ -340,17 +401,18 @@ declare function generateP2PCode(cryptoObj?: CryptoAdapter): string;
  */
 declare function isP2PCodeLike(code: string): boolean;
 
-interface BuildPeerOptionsInput {
-    host?: string;
-    port?: number;
-    peerjsPath?: string;
-    secure?: boolean;
-    iceServers?: RTCIceServer[];
-}
 /**
- * Build PeerJS connection options
+ * Resolve P2P server configuration from user options and server capabilities.
+ * User-provided values take precedence over server capabilities.
+ */
+declare function resolvePeerConfig(userConfig: P2PServerConfig, serverCaps?: P2PCapabilities): {
+    path: string;
+    iceServers: RTCIceServer[];
+};
+/**
+ * Build PeerJS connection options from P2P server configuration.
  */
-declare function buildPeerOptions(opts?: BuildPeerOptionsInput): PeerOptions;
+declare function buildPeerOptions(config?: P2PServerConfig): PeerOptions;
 interface CreatePeerWithRetriesOptions {
     code?: string | null;
     codeGenerator: () => string;
@@ -366,4 +428,4 @@ declare function createPeerWithRetries(opts: CreatePeerWithRetriesOptions): Prom
     code: string;
 }>;
 
-export { type DataConnection, type P2PReceiveOptions, type P2PReceiveSession, type P2PSendOptions, type P2PSendSession, type PeerConstructor, type PeerInstance, type PeerOptions, buildPeerOptions, createPeerWithRetries, generateP2PCode, isLocalhostHostname, isP2PCodeLike, isSecureContextForP2P, startP2PReceive, startP2PSend };
+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 };