@dropgate/core 2.0.0-beta.2 → 2.2.0-beta.1

package/dist/index.d.cts

@@ -114,16 +114,26 @@ 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;
+}
 /**
  * Progress event emitted during upload operations.
  */
-interface ProgressEvent {
-    /** Current phase of the operation (e.g., 'init', 'chunk', 'complete'). */
-    phase: string;
+interface UploadProgressEvent extends BaseProgressEvent {
+    /** Current phase of the operation. */
+    phase: 'server-info' | 'server-compat' | 'crypto' | 'init' | 'chunk' | 'complete' | 'done' | 'retry-wait' | 'retry';
     /** Human-readable status text. */
     text?: string;
-    /** Completion percentage (0-100). */
-    percent?: number;
     /** Current chunk index (0-based). */
     chunkIndex?: number;
     /** Total number of chunks. */
@@ -144,6 +154,18 @@ interface UploadResult {
     /** Base64-encoded encryption key (only present if encrypted). */
     keyB64?: string;
 }
+/**
+ * Upload session with cancellation support.
+ * Returned by uploadFile() to allow cancelling uploads in progress.
+ */
+interface UploadSession {
+    /** Promise that resolves with upload result when complete. */
+    result: Promise<UploadResult>;
+    /** Cancel the upload. */
+    cancel: (reason?: string) => void;
+    /** Get current upload status. */
+    getStatus: () => 'initializing' | 'uploading' | 'completing' | 'completed' | 'cancelled' | 'error';
+}
 /**
  * Result of a client/server compatibility check.
  */
@@ -261,7 +283,9 @@ interface UploadOptions extends ServerTarget {
     /** Override the filename sent to the server. */
     filenameOverride?: string;
     /** Callback for progress updates. */
-    onProgress?: (evt: ProgressEvent) => void;
+    onProgress?: (evt: UploadProgressEvent) => void;
+    /** Callback when upload is cancelled by user. */
+    onCancel?: () => void;
     /** AbortSignal to cancel the upload. */
     signal?: AbortSignal;
     /** Timeout settings for various upload phases. */
@@ -293,6 +317,8 @@ interface GetServerInfoOptions extends ServerTarget {
     timeoutMs?: number;
     /** AbortSignal to cancel the request. */
     signal?: AbortSignal;
+    /** Custom fetch implementation (uses global fetch by default). */
+    fetchFn?: FetchFn;
 }
 /**
  * Options for validating upload inputs before starting an upload.
@@ -323,17 +349,11 @@ interface FileMetadata {
 /**
  * Download progress event.
  */
-interface DownloadProgressEvent {
+interface DownloadProgressEvent extends BaseProgressEvent {
     /** Current phase of the download. */
-    phase: 'metadata' | 'downloading' | 'decrypting' | 'complete';
+    phase: 'server-info' | 'server-compat' | 'metadata' | 'downloading' | 'decrypting' | 'complete';
     /** Human-readable status text. */
     text?: string;
-    /** Bytes received so far. */
-    receivedBytes: number;
-    /** Total bytes expected (may be 0 if unknown). */
-    totalBytes: number;
-    /** Completion percentage (0-100). */
-    percent: number;
 }
 /**
  * Options for downloading a file.
@@ -491,6 +511,17 @@ declare function encryptFilenameToBase64(cryptoObj: CryptoAdapter, filename: str
  * Estimate total upload size including encryption overhead.
  */
 declare function estimateTotalUploadSizeBytes(fileSizeBytes: number, totalChunks: number, isEncrypted: boolean): number;
+/**
+ * Fetch server information from the /api/info endpoint.
+ * @param opts - Server target and request options.
+ * @returns The server base URL and server info object.
+ * @throws {DropgateNetworkError} If the server cannot be reached.
+ * @throws {DropgateProtocolError} If the server returns an invalid response.
+ */
+declare function getServerInfo(opts: GetServerInfoOptions): Promise<{
+    baseUrl: string;
+    serverInfo: ServerInfo;
+}>;
 /**
  * Headless, environment-agnostic client for Dropgate file uploads.
  * Handles server communication, encryption, and chunked uploads.
@@ -514,17 +545,6 @@ declare class DropgateClient {
      * @throws {DropgateValidationError} If clientVersion is missing or invalid.
      */
     constructor(opts: DropgateClientOptions);
-    /**
-     * Fetch server information from the /api/info endpoint.
-     * @param opts - Server target and request options.
-     * @returns The server base URL and server info object.
-     * @throws {DropgateNetworkError} If the server cannot be reached.
-     * @throws {DropgateProtocolError} If the server returns an invalid response.
-     */
-    getServerInfo(opts: GetServerInfoOptions): Promise<{
-        baseUrl: string;
-        serverInfo: ServerInfo;
-    }>;
     /**
      * Resolve a user-entered sharing code or URL via the server.
      * @param value - The sharing code or URL to resolve.
@@ -535,10 +555,16 @@ declare class DropgateClient {
     resolveShareTarget(value: string, opts: GetServerInfoOptions): Promise<ShareTargetResult>;
     /**
      * Check version compatibility between this client and a server.
-     * @param serverInfo - Server info containing the version to check against.
-     * @returns Compatibility result with status and message.
+     * Fetches server info internally using getServerInfo.
+     * @param opts - Server target and request options.
+     * @returns Compatibility result with status, message, and server info.
+     * @throws {DropgateNetworkError} If the server cannot be reached.
+     * @throws {DropgateProtocolError} If the server returns an invalid response.
      */
-    checkCompatibility(serverInfo: ServerInfo): CompatibilityResult;
+    checkCompatibility(opts: GetServerInfoOptions): Promise<CompatibilityResult & {
+        serverInfo: ServerInfo;
+        baseUrl: string;
+    }>;
     /**
      * Validate file and upload settings against server capabilities.
      * @param opts - Validation options containing file, settings, and server info.
@@ -555,7 +581,7 @@ declare class DropgateClient {
      * @throws {DropgateProtocolError} If the server returns an error.
      * @throws {DropgateAbortError} If the upload is cancelled.
      */
-    uploadFile(opts: UploadOptions): Promise<UploadResult>;
+    uploadFile(opts: UploadOptions): Promise<UploadSession>;
     /**
      * Download a file from the server with optional decryption.
      *
@@ -592,6 +618,15 @@ declare function getDefaultCrypto(): CryptoAdapter | undefined;
  */
 declare function getDefaultFetch(): FetchFn | undefined;
 
+/**
+ * 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';
+/**
+ * Finite state machine states for P2P receive sessions.
+ */
+type P2PReceiveState = 'initializing' | 'connecting' | 'negotiating' | 'transferring' | 'completed' | 'cancelled' | 'closed';
 /**
  * PeerJS Peer constructor interface.
  * Consumer must provide this constructor to P2P functions.
@@ -619,16 +654,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?: {
@@ -637,16 +676,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;
@@ -656,58 +699,90 @@ 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;
+}
+/** Cancellation event for P2P operations. */
+interface P2PCancellationEvent {
+    /** Who cancelled the transfer ('sender' or 'receiver'). */
+    cancelledBy: 'sender' | 'receiver';
+    /** Optional cancellation message. */
+    message?: string;
+}
+/**
+ * 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;
+    /** Callback when transfer is cancelled by either party. */
+    onCancel?: (evt: P2PCancellationEvent) => void;
 }
 /**
  * Return value from startP2PSend containing session control.
@@ -717,56 +792,59 @@ 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;
+    /** Callback when transfer is cancelled by either party. */
+    onCancel?: (evt: P2PCancellationEvent) => void;
 }
 /**
  * Return value from startP2PReceive containing session control.
@@ -776,6 +854,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;
 }
 
 /**
@@ -854,17 +940,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;
@@ -880,4 +967,4 @@ declare function createPeerWithRetries(opts: CreatePeerWithRetriesOptions): Prom
     code: string;
 }>;
 
-export { AES_GCM_IV_BYTES, AES_GCM_TAG_BYTES, type AbortSignalWithCleanup, type Base64Adapter, type CompatibilityResult, type CryptoAdapter, DEFAULT_CHUNK_SIZE, type DataConnection, type DownloadOptions, type DownloadProgressEvent, type DownloadResult, DropgateAbortError, DropgateClient, type DropgateClientOptions, DropgateError, type DropgateErrorOptions, DropgateNetworkError, DropgateProtocolError, DropgateTimeoutError, DropgateValidationError, ENCRYPTION_OVERHEAD_PER_CHUNK, type FetchFn, type FetchJsonOptions, type FetchJsonResult, type FileMetadata, type FileSource, type GetServerInfoOptions, type LoggerFn, type P2PCapabilities, type P2PReceiveOptions, type P2PReceiveSession, type P2PSendOptions, type P2PSendSession, type PeerConstructor, type PeerInstance, type PeerOptions, type ProgressEvent, type SemverParts, type ServerCapabilities, type ServerInfo, type ServerTarget, type ShareTargetResult, type UploadCapabilities, type UploadOptions, type UploadResult, type ValidateUploadOptions, type WebUICapabilities, arrayBufferToBase64, base64ToBytes, buildBaseUrl, buildPeerOptions, bytesToBase64, createPeerWithRetries, decryptChunk, decryptFilenameFromBase64, encryptFilenameToBase64, encryptToBlob, estimateTotalUploadSizeBytes, exportKeyBase64, fetchJson, generateAesGcmKey, generateP2PCode, getDefaultBase64, getDefaultCrypto, getDefaultFetch, importKeyFromBase64, isLocalhostHostname, isP2PCodeLike, isSecureContextForP2P, lifetimeToMs, makeAbortSignal, parseSemverMajorMinor, parseServerUrl, sha256Hex, sleep, startP2PReceive, startP2PSend, validatePlainFilename };
+export { AES_GCM_IV_BYTES, AES_GCM_TAG_BYTES, type AbortSignalWithCleanup, type Base64Adapter, type BaseProgressEvent, type CompatibilityResult, type CryptoAdapter, DEFAULT_CHUNK_SIZE, type DataConnection, type DataConnectionEvents, type DownloadOptions, type DownloadProgressEvent, type DownloadResult, DropgateAbortError, DropgateClient, type DropgateClientOptions, DropgateError, type DropgateErrorOptions, DropgateNetworkError, DropgateProtocolError, DropgateTimeoutError, DropgateValidationError, ENCRYPTION_OVERHEAD_PER_CHUNK, type FetchFn, type FetchJsonOptions, type FetchJsonResult, type FileMetadata, type FileSource, type GetServerInfoOptions, type LoggerFn, type P2PCapabilities, type P2PMetadataEvent, type P2PReceiveCompleteEvent, type P2PReceiveOptions, type P2PReceiveProgressEvent, type P2PReceiveSession, type P2PSendOptions, type P2PSendProgressEvent, type P2PSendSession, type P2PServerConfig, type P2PStatusEvent, type PeerConstructor, type PeerInstance, type PeerInstanceEvents, type PeerOptions, type SemverParts, type ServerCapabilities, type ServerInfo, type ServerTarget, type ShareTargetResult, type UploadCapabilities, type UploadOptions, type UploadProgressEvent, type UploadResult, type ValidateUploadOptions, type WebUICapabilities, arrayBufferToBase64, base64ToBytes, buildBaseUrl, buildPeerOptions, bytesToBase64, createPeerWithRetries, decryptChunk, decryptFilenameFromBase64, encryptFilenameToBase64, encryptToBlob, estimateTotalUploadSizeBytes, exportKeyBase64, fetchJson, generateAesGcmKey, generateP2PCode, getDefaultBase64, getDefaultCrypto, getDefaultFetch, getServerInfo, importKeyFromBase64, isLocalhostHostname, isP2PCodeLike, isSecureContextForP2P, lifetimeToMs, makeAbortSignal, parseSemverMajorMinor, parseServerUrl, resolvePeerConfig, sha256Hex, sleep, startP2PReceive, startP2PSend, validatePlainFilename };