@dropgate/core 2.2.1 → 3.0.0

package/dist/index.d.cts

@@ -75,6 +75,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.
@@ -133,9 +135,15 @@ interface BaseProgressEvent {
  */
 interface UploadProgressEvent extends BaseProgressEvent {
     /** Current phase of the operation. */
-    phase: 'server-info' | 'server-compat' | 'crypto' | 'init' | 'chunk' | 'complete' | 'done' | 'retry-wait' | 'retry';
+    phase: 'server-info' | 'server-compat' | 'crypto' | 'init' | 'file-start' | 'chunk' | 'file-complete' | 'complete' | 'done' | 'retry-wait' | 'retry';
     /** Human-readable status text. */
     text?: string;
+    /** Index of the current file being uploaded (0-based). Only present for multi-file uploads. */
+    fileIndex?: number;
+    /** Total number of files being uploaded. Only present for multi-file uploads. */
+    totalFiles?: number;
+    /** Name of the current file being uploaded. Only present for multi-file uploads. */
+    currentFileName?: string;
     /** Current chunk index (0-based). */
     chunkIndex?: number;
     /** Total number of chunks. */
@@ -147,18 +155,26 @@ interface UploadProgressEvent extends BaseProgressEvent {
 interface UploadResult {
     /** Full download URL including encryption key fragment if encrypted. */
     downloadUrl: string;
-    /** Unique file identifier on the server. */
-    fileId: string;
-    /** Upload session identifier. */
-    uploadId: string;
+    /** Unique file identifier on the server (set for single-file uploads). */
+    fileId?: string;
+    /** Unique bundle identifier on the server (set for multi-file uploads). */
+    bundleId?: string;
+    /** Upload session identifier (set for single-file uploads). */
+    uploadId?: string;
     /** Server base URL used for the upload. */
     baseUrl: string;
     /** Base64-encoded encryption key (only present if encrypted). */
     keyB64?: string;
+    /** Per-file results (only present for multi-file uploads). */
+    files?: Array<{
+        fileId: string;
+        name: string;
+        size: number;
+    }>;
 }
 /**
  * Upload session with cancellation support.
- * Returned by uploadFile() to allow cancelling uploads in progress.
+ * Returned by uploadFiles() to allow cancelling uploads in progress.
  */
 interface UploadSession {
     /** Promise that resolves with upload result when complete. */
@@ -237,19 +253,16 @@ interface FileSource {
     /** Read the entire file as an ArrayBuffer. */
     arrayBuffer(): Promise<ArrayBuffer>;
 }
-/**
- * Logger function type for debug and diagnostic output.
- * @param level - Log level (debug, info, warn, error).
- * @param message - Log message.
- * @param meta - Optional metadata object.
- */
-type LoggerFn = (level: 'debug' | 'info' | 'warn' | 'error', message: string, meta?: unknown) => void;
 /**
  * Options for constructing a DropgateClient instance.
  */
 interface DropgateClientOptions {
     /** Client version string for compatibility checking with the server. */
     clientVersion: string;
+    /** Server URL string (e.g. 'https://dropgate.link') or ServerTarget object. Required. */
+    server: string | ServerTarget;
+    /** If true, automatically retry with HTTP when HTTPS connection fails in connect(). Default: false. */
+    fallbackToHttp?: boolean;
     /** Upload chunk size in bytes (default: 5MB). */
     chunkSize?: number;
     /** Custom fetch implementation (uses global fetch by default). */
@@ -258,8 +271,6 @@ interface DropgateClientOptions {
     cryptoObj?: CryptoAdapter;
     /** Custom base64 encoder/decoder. */
     base64?: Base64Adapter;
-    /** Custom logger function for debug output. */
-    logger?: LoggerFn;
 }
 /**
  * Common server target options specifying the server to connect to.
@@ -273,22 +284,24 @@ interface ServerTarget {
     secure?: boolean;
 }
 /**
- * Options for uploading a file to the server.
+ * Options for uploading one or more files to the server.
+ * Single files use the standard upload protocol. Multiple files use the bundle protocol.
+ * Server connection is configured once in the DropgateClient constructor.
  */
-interface UploadOptions extends ServerTarget {
-    /** File to upload. */
-    file: FileSource;
+interface UploadFilesOptions {
+    /** File(s) to upload. A single FileSource or an array of FileSources. */
+    files: FileSource | FileSource[];
     /** File lifetime in milliseconds (0 = server default). */
     lifetimeMs: number;
-    /** Whether to encrypt the file with E2EE. Defaults to true if server supports E2EE. */
+    /** Whether to encrypt the file(s) with E2EE. Defaults to true if server supports E2EE. */
     encrypt?: boolean;
-    /** Override the filename sent to the server. */
-    filenameOverride?: string;
+    /** Override filenames sent to the server, keyed by file index. */
+    filenameOverrides?: Record<number, string>;
     /** Callback for progress updates. */
     onProgress?: (evt: UploadProgressEvent) => void;
     /** Callback when upload is cancelled by user. */
     onCancel?: () => void;
-    /** Max downloads before file is deleted (0 = unlimited). */
+    /** Max downloads before file/bundle is deleted (0 = unlimited). */
     maxDownloads?: number;
     /** AbortSignal to cancel the upload. */
     signal?: AbortSignal;
@@ -316,7 +329,9 @@ interface UploadOptions extends ServerTarget {
 /**
  * Options for fetching server information.
  */
-interface GetServerInfoOptions extends ServerTarget {
+interface GetServerInfoOptions {
+    /** Server URL string (e.g. 'https://dropgate.link') or ServerTarget object. */
+    server: string | ServerTarget;
     /** Request timeout in milliseconds (default: 5000ms). */
     timeoutMs?: number;
     /** AbortSignal to cancel the request. */
@@ -324,12 +339,21 @@ interface GetServerInfoOptions extends ServerTarget {
     /** Custom fetch implementation (uses global fetch by default). */
     fetchFn?: FetchFn;
 }
+/**
+ * Options for the connect() method on DropgateClient.
+ */
+interface ConnectOptions {
+    /** Request timeout in milliseconds (default: 5000ms). */
+    timeoutMs?: number;
+    /** AbortSignal to cancel the request. */
+    signal?: AbortSignal;
+}
 /**
  * Options for validating upload inputs before starting an upload.
  */
 interface ValidateUploadOptions {
-    /** File to validate. */
-    file: FileSource;
+    /** File(s) to validate. */
+    files: FileSource | FileSource[];
     /** Requested file lifetime in milliseconds. */
     lifetimeMs: number;
     /** Whether encryption will be used. Defaults to true if server supports E2EE. */
@@ -355,22 +379,49 @@ interface FileMetadata {
  */
 interface DownloadProgressEvent extends BaseProgressEvent {
     /** Current phase of the download. */
-    phase: 'server-info' | 'server-compat' | 'metadata' | 'downloading' | 'decrypting' | 'complete';
+    phase: 'server-info' | 'server-compat' | 'metadata' | 'downloading' | 'decrypting' | 'zipping' | 'complete';
     /** Human-readable status text. */
     text?: string;
+    /** Index of the current file being downloaded (0-based). Only present for bundle downloads. */
+    fileIndex?: number;
+    /** Total number of files in the bundle. Only present for bundle downloads. */
+    totalFiles?: number;
+    /** Name of the current file being downloaded. Only present for bundle downloads. */
+    currentFileName?: string;
 }
 /**
- * Options for downloading a file.
+ * Options for downloading one or more files.
+ * Use `fileId` for single-file downloads or `bundleId` for multi-file bundle downloads.
+ * Server connection is configured once in the DropgateClient constructor.
  */
-interface DownloadOptions extends ServerTarget {
-    /** File ID to download. */
-    fileId: string;
-    /** Base64-encoded decryption key (required for encrypted files). */
+interface DownloadFilesOptions {
+    /** File ID to download (for single-file downloads). */
+    fileId?: string;
+    /** Bundle ID to download (for multi-file bundle downloads). */
+    bundleId?: string;
+    /** Base64-encoded decryption key (required for encrypted files/bundles). */
     keyB64?: string;
+    /** If true and bundleId is set, streams all files as a single ZIP via onData. */
+    asZip?: boolean;
+    /** Filename for the generated ZIP (default: "dropgate-bundle.zip"). Only used with asZip. */
+    zipFilename?: string;
     /** Callback for progress updates. */
     onProgress?: (evt: DownloadProgressEvent) => void;
-    /** Callback for received data chunks. Consumer handles file writing. */
+    /** Callback for received data chunks (single-file or ZIP stream). Consumer handles writing. */
     onData?: (chunk: Uint8Array) => Promise<void> | void;
+    /** Callback when a file download begins (bundle non-ZIP mode). Consumer opens a new write stream. */
+    onFileStart?: (file: {
+        name: string;
+        size: number;
+        index: number;
+    }) => void;
+    /** Callback for received data chunks per file (bundle non-ZIP mode). */
+    onFileData?: (chunk: Uint8Array) => Promise<void> | void;
+    /** Callback when a file download ends (bundle non-ZIP mode). Consumer closes the write stream. */
+    onFileEnd?: (file: {
+        name: string;
+        index: number;
+    }) => void;
     /** AbortSignal to cancel the download. */
     signal?: AbortSignal;
     /** Request timeout in milliseconds (default: 60000ms). */
@@ -380,15 +431,43 @@ interface DownloadOptions extends ServerTarget {
  * Result of a file download.
  */
 interface DownloadResult {
-    /** Decrypted filename. */
-    filename: string;
-    /** Total bytes received. */
+    /** Decrypted filename (for single-file downloads). */
+    filename?: string;
+    /** Decrypted filenames (for bundle downloads). */
+    filenames?: string[];
+    /** Total bytes received across all files. */
     receivedBytes: number;
-    /** Whether the file was encrypted. */
+    /** Whether the file(s) were encrypted. */
     wasEncrypted: boolean;
-    /** The file data (only if onData callback was not provided). */
+    /** The file data (only for small single files when onData callback was not provided). */
     data?: Uint8Array;
 }
+/**
+ * Bundle metadata returned from the server.
+ */
+interface BundleMetadata {
+    /** Whether the bundle files are encrypted. */
+    isEncrypted: boolean;
+    /** Total size of all files in bytes. */
+    totalSizeBytes: number;
+    /** Number of files in the bundle. */
+    fileCount: number;
+    /** Whether the bundle manifest is encrypted (sealed). Only the downloader can read the file list. */
+    sealed?: boolean;
+    /** Base64-encoded encrypted manifest blob (only present for sealed bundles). */
+    encryptedManifest?: string;
+    /** Individual file metadata entries. Populated from server for unsealed bundles, or from decrypted manifest for sealed bundles. */
+    files: Array<{
+        /** File ID for downloading this individual file. */
+        fileId: string;
+        /** File size in bytes (encrypted size if encrypted). */
+        sizeBytes: number;
+        /** Original filename (only for unencrypted files). */
+        filename?: string;
+        /** Encrypted filename (only for encrypted files). */
+        encryptedFilename?: string;
+    }>;
+}
 
 /**
  * Convert a Uint8Array to a base64 string
@@ -490,6 +569,10 @@ declare function decryptFilenameFromBase64(cryptoObj: CryptoAdapter, encryptedFi
 
 /**
  * Compute SHA-256 hash of data and return as hex string.
+ *
+ * Uses crypto.subtle when available. Falls back to a pure-JS
+ * implementation for integrity hashing on insecure contexts.
+ * The fallback MUST NOT be used for encryption operations.
  */
 declare function sha256Hex(cryptoObj: CryptoAdapter, data: ArrayBuffer): Promise<string>;
 /**
@@ -512,125 +595,48 @@ declare function encryptToBlob(cryptoObj: CryptoAdapter, dataBuffer: ArrayBuffer
 declare function encryptFilenameToBase64(cryptoObj: CryptoAdapter, filename: string, key: CryptoKey): Promise<string>;
 
 /**
- * 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.
- */
-declare class DropgateClient {
-    /** Client version string for compatibility checking. */
-    readonly clientVersion: string;
-    /** Chunk size in bytes for upload splitting. */
-    readonly chunkSize: number;
-    /** Fetch implementation used for HTTP requests. */
-    readonly fetchFn: FetchFn;
-    /** Crypto implementation for encryption operations. */
-    readonly cryptoObj: CryptoAdapter;
-    /** Base64 encoder/decoder for binary data. */
-    readonly base64: Base64Adapter;
-    /** Optional logger for debug output. */
-    readonly logger: LoggerFn | null;
-    /**
-     * Create a new DropgateClient instance.
-     * @param opts - Client configuration options.
-     * @throws {DropgateValidationError} If clientVersion is missing or invalid.
-     */
-    constructor(opts: DropgateClientOptions);
-    /**
-     * Resolve a user-entered sharing code or URL via the server.
-     * @param value - The sharing code or URL to resolve.
-     * @param opts - Server target and request options.
-     * @returns The resolved share target information.
-     * @throws {DropgateProtocolError} If the share lookup fails.
-     */
-    resolveShareTarget(value: string, opts: GetServerInfoOptions): Promise<ShareTargetResult>;
+ * Streaming ZIP writer that assembles files into a ZIP archive on the fly.
+ * Uses fflate's store mode (no compression) for maximum speed and minimal memory usage.
+ * Works in both Node.js and browser environments.
+ */
+declare class StreamingZipWriter {
+    private zip;
+    private currentFile;
+    private onData;
+    private finalized;
+    private pendingWrites;
+    constructor(onData: (chunk: Uint8Array) => void | Promise<void>);
     /**
-     * Check version compatibility between this client and a server.
-     * 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.
+     * Begin a new file entry in the ZIP.
+     * Must call endFile() before starting another file.
+     * @param name - Filename within the ZIP archive.
      */
-    checkCompatibility(opts: GetServerInfoOptions): Promise<CompatibilityResult & {
-        serverInfo: ServerInfo;
-        baseUrl: string;
-    }>;
+    startFile(name: string): void;
     /**
-     * Validate file and upload settings against server capabilities.
-     * @param opts - Validation options containing file, settings, and server info.
-     * @returns True if validation passes.
-     * @throws {DropgateValidationError} If any validation check fails.
+     * Write a chunk of data to the current file entry.
+     * @param data - The data chunk to write.
      */
-    validateUploadInputs(opts: ValidateUploadOptions): boolean;
+    writeChunk(data: Uint8Array): void;
     /**
-     * Upload a file to the server with optional encryption.
-     * @param opts - Upload options including file, server target, and settings.
-     * @returns Upload result containing the download URL and file identifiers.
-     * @throws {DropgateValidationError} If input validation fails.
-     * @throws {DropgateNetworkError} If the server cannot be reached.
-     * @throws {DropgateProtocolError} If the server returns an error.
-     * @throws {DropgateAbortError} If the upload is cancelled.
+     * End the current file entry.
      */
-    uploadFile(opts: UploadOptions): Promise<UploadSession>;
+    endFile(): void;
     /**
-     * Download a file from the server with optional decryption.
-     *
-     * **Important:** For large files, you must provide an `onData` callback to stream
-     * data incrementally. Without it, the entire file is buffered in memory, which will
-     * cause memory exhaustion for large files. Files exceeding 100MB without an `onData`
-     * callback will throw a validation error.
-     *
-     * @param opts - Download options including file ID, server target, and optional key.
-     * @param opts.onData - Streaming callback that receives data chunks. Required for files > 100MB.
-     * @returns Download result containing filename and received bytes.
-     * @throws {DropgateValidationError} If input validation fails or file is too large without onData.
-     * @throws {DropgateNetworkError} If the server cannot be reached.
-     * @throws {DropgateProtocolError} If the server returns an error.
-     * @throws {DropgateAbortError} If the download is cancelled.
+     * Finalize the ZIP archive. Must be called after all files are written.
+     * Waits for all pending async writes to complete before resolving.
      */
-    downloadFile(opts: DownloadOptions): Promise<DownloadResult>;
-    private attemptChunkUpload;
+    finalize(): Promise<void>;
 }
 
-/**
- * Get the default Base64 adapter for the current environment.
- * Automatically detects Node.js Buffer vs browser btoa/atob.
- */
-declare function getDefaultBase64(): Base64Adapter;
-/**
- * Get the default crypto object for the current environment.
- * Returns globalThis.crypto if available.
- */
-declare function getDefaultCrypto(): CryptoAdapter | undefined;
-/**
- * Get the default fetch function for the current environment.
- * Returns globalThis.fetch if available.
- */
-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';
+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.
@@ -702,21 +708,6 @@ interface DataConnection {
     /** Internal WebRTC data channel (for buffer monitoring). */
     _dc?: RTCDataChannel;
 }
-/**
- * Common server configuration for P2P connections.
- */
-interface P2PServerConfig {
-    /** 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[];
-}
 /** Status event for P2P operations. */
 interface P2PStatusEvent {
     phase: string;
@@ -734,6 +725,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 {
@@ -747,20 +747,76 @@ 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;
+}
+/**
+ * Return value from startP2PSend containing session control.
+ */
+interface P2PSendSession {
+    /** The PeerJS peer instance. */
+    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;
+}
+/**
+ * Return value from startP2PReceive containing session control.
+ */
+interface P2PReceiveSession {
+    /** The PeerJS peer instance. */
+    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;
+}
 /**
- * Options for starting a P2P send session.
+ * Options for DropgateClient.p2pSend().
+ * Server connection, serverInfo, peerjsPath, iceServers, and cryptoObj
+ * are all provided internally by the client.
  */
-interface P2PSendOptions extends P2PServerConfig {
-    /** File to send. */
-    file: FileSource;
+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;
-    /** Server info (optional, for capability checking). */
-    serverInfo?: ServerInfo;
     /** Custom code generator function. */
     codeGenerator?: (cryptoObj?: CryptoAdapter) => string;
-    /** Crypto object for secure code generation. */
-    cryptoObj?: CryptoAdapter;
     /** Max attempts to register a peer ID. */
     maxAttempts?: number;
     /** Chunk size for data transfer. */
@@ -773,6 +829,12 @@ interface P2PSendOptions extends P2PServerConfig {
     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. */
@@ -787,36 +849,21 @@ interface P2PSendOptions extends P2PServerConfig {
     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;
 }
 /**
- * Return value from startP2PSend containing session control.
+ * Options for DropgateClient.p2pReceive().
+ * Server connection, serverInfo, peerjsPath, and iceServers
+ * are all provided internally by the client.
  */
-interface P2PSendSession {
-    /** The PeerJS peer instance. */
-    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 extends P2PServerConfig {
+interface P2PReceiveFileOptions {
     /** Sharing code to connect to. */
     code: string;
     /** PeerJS Peer constructor - REQUIRED. */
     Peer: PeerConstructor;
-    /** Server info (optional, for capability checking). */
-    serverInfo?: ServerInfo;
     /**
      * Whether to automatically send the "ready" signal after receiving metadata.
      * Default: true.
@@ -841,6 +888,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. */
@@ -850,81 +908,191 @@ interface P2PReceiveOptions extends P2PServerConfig {
     /** Callback when transfer is cancelled by either party. */
     onCancel?: (evt: P2PCancellationEvent) => void;
 }
+
 /**
- * Return value from startP2PReceive containing session control.
+ * Estimate total upload size including encryption overhead.
  */
-interface P2PReceiveSession {
-    /** The PeerJS peer instance. */
-    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;
-}
-
+declare function estimateTotalUploadSizeBytes(fileSizeBytes: number, totalChunks: number, isEncrypted: boolean): number;
 /**
- * Start a direct transfer (P2P) sender session.
- *
- * IMPORTANT: Consumer must provide the PeerJS Peer constructor.
- * This removes DOM coupling (no script injection).
- *
- * Example:
- * ```js
- * import Peer from 'peerjs';
- * import { startP2PSend } from '@dropgate/core/p2p';
+ * 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 operations.
+ * Handles server communication, encryption, chunked uploads, downloads, and P2P transfers.
  *
- * const session = await startP2PSend({
- *   file: myFile,
- *   Peer,
- *   host: 'dropgate.link',
- *   secure: true,
- *   onCode: (code) => console.log('Share this code:', code),
- *   onProgress: (evt) => console.log(`${evt.percent}% sent`),
- *   onComplete: () => console.log('Done!'),
- * });
- * ```
- */
-declare function startP2PSend(opts: P2PSendOptions): Promise<P2PSendSession>;
+ * Server connection is configured once in the constructor — all methods use
+ * the stored server URL and cached server info automatically.
+ */
+declare class DropgateClient {
+    /** Client version string for compatibility checking. */
+    readonly clientVersion: string;
+    /** Chunk size in bytes for upload splitting. */
+    readonly chunkSize: number;
+    /** Fetch implementation used for HTTP requests. */
+    readonly fetchFn: FetchFn;
+    /** Crypto implementation for encryption operations. */
+    readonly cryptoObj: CryptoAdapter;
+    /** Base64 encoder/decoder for binary data. */
+    readonly base64: Base64Adapter;
+    /** Resolved base URL (e.g. 'https://dropgate.link'). May change during HTTP fallback. */
+    baseUrl: string;
+    /** Whether to automatically retry with HTTP when HTTPS fails. */
+    private _fallbackToHttp;
+    /** Cached compatibility result (null until first connect()). */
+    private _compat;
+    /** In-flight connect promise to deduplicate concurrent calls. */
+    private _connectPromise;
+    /**
+     * Create a new DropgateClient instance.
+     * @param opts - Client configuration options including server URL.
+     * @throws {DropgateValidationError} If clientVersion or server is missing or invalid.
+     */
+    constructor(opts: DropgateClientOptions);
+    /**
+     * Get the server target (host, port, secure) derived from the current baseUrl.
+     * Useful for passing to standalone functions that still need a ServerTarget.
+     */
+    get serverTarget(): ServerTarget;
+    /**
+     * Connect to the server: fetch server info and check version compatibility.
+     * Results are cached — subsequent calls return instantly without network requests.
+     * Concurrent calls are deduplicated.
+     *
+     * @param opts - Optional timeout and abort signal.
+     * @returns Compatibility result with server info.
+     * @throws {DropgateNetworkError} If the server cannot be reached.
+     * @throws {DropgateProtocolError} If the server returns an invalid response.
+     */
+    connect(opts?: ConnectOptions): Promise<CompatibilityResult & {
+        serverInfo: ServerInfo;
+        baseUrl: string;
+    }>;
+    private _fetchAndCheckCompat;
+    /**
+     * Pure version compatibility check (no network calls).
+     */
+    private _checkVersionCompat;
+    /**
+     * Resolve a user-entered sharing code or URL via the server.
+     * @param value - The sharing code or URL to resolve.
+     * @param opts - Optional timeout and abort signal.
+     * @returns The resolved share target information.
+     * @throws {DropgateProtocolError} If the share lookup fails.
+     */
+    resolveShareTarget(value: string, opts?: ConnectOptions): Promise<ShareTargetResult>;
+    /**
+     * Fetch metadata for a single file from the server.
+     * @param fileId - The file ID to fetch metadata for.
+     * @param opts - Optional connection options (timeout, signal).
+     * @returns File metadata including size, filename, and encryption status.
+     * @throws {DropgateNetworkError} If the server cannot be reached.
+     * @throws {DropgateProtocolError} If the file is not found or server returns an error.
+     */
+    getFileMetadata(fileId: string, opts?: ConnectOptions): Promise<FileMetadata>;
+    /**
+     * Fetch metadata for a bundle from the server and derive computed fields.
+     * For sealed bundles, decrypts the manifest to extract file list.
+     * Automatically derives totalSizeBytes and fileCount from the files array.
+     * @param bundleId - The bundle ID to fetch metadata for.
+     * @param keyB64 - Base64-encoded decryption key (required for encrypted bundles).
+     * @param opts - Optional connection options (timeout, signal).
+     * @returns Complete bundle metadata with all files and computed fields.
+     * @throws {DropgateNetworkError} If the server cannot be reached.
+     * @throws {DropgateProtocolError} If the bundle is not found or server returns an error.
+     * @throws {DropgateValidationError} If decryption key is missing for encrypted bundle.
+     */
+    getBundleMetadata(bundleId: string, keyB64?: string, opts?: ConnectOptions): Promise<BundleMetadata>;
+    /**
+     * Validate file and upload settings against server capabilities.
+     * @param opts - Validation options containing file, settings, and server info.
+     * @returns True if validation passes.
+     * @throws {DropgateValidationError} If any validation check fails.
+     */
+    validateUploadInputs(opts: ValidateUploadOptions): boolean;
+    /**
+     * Upload one or more files to the server with optional encryption.
+     * Single files use the standard upload protocol.
+     * Multiple files use the bundle protocol, grouping files under a single download link.
+     *
+     * @param opts - Upload options including file(s) and settings.
+     * @returns Upload session with result promise and cancellation support.
+     */
+    uploadFiles(opts: UploadFilesOptions): Promise<UploadSession>;
+    /**
+     * Upload a single file's chunks to the server. Used internally by uploadFiles().
+     */
+    private _uploadFileChunks;
+    /**
+     * Download one or more files from the server with optional decryption.
+     *
+     * For single files, use `fileId`. For bundles, use `bundleId`.
+     * With `asZip: true` on bundles, streams a ZIP archive via `onData`.
+     * Without `asZip`, delivers files individually via `onFileStart`/`onFileData`/`onFileEnd`.
+     *
+     * @param opts - Download options including file/bundle ID and optional key.
+     * @returns Download result containing filename(s) and received bytes.
+     */
+    downloadFiles(opts: DownloadFilesOptions): Promise<DownloadResult>;
+    /**
+     * Download a single file, handling encryption/decryption internally.
+     * Preserves the original downloadFile() behavior.
+     */
+    private _downloadSingleFile;
+    /**
+     * Stream a single file's content into a callback, handling decryption if needed.
+     * Returns total bytes received from the network (encrypted size).
+     */
+    private _streamFileIntoCallback;
+    /**
+     * Start a P2P send session. Connects to the signalling server and waits for a receiver.
+     *
+     * Server info, peerjsPath, iceServers, and cryptoObj are provided automatically
+     * from the client's cached server info and configuration.
+     *
+     * @param opts - P2P send options (file, Peer constructor, callbacks, tuning).
+     * @returns P2P send session with control methods.
+     * @throws {DropgateValidationError} If P2P is not enabled on the server.
+     * @throws {DropgateNetworkError} If the signalling server cannot be reached.
+     */
+    p2pSend(opts: P2PSendFileOptions): Promise<P2PSendSession>;
+    /**
+     * Start a P2P receive session. Connects to a sender via their sharing code.
+     *
+     * Server info, peerjsPath, and iceServers are provided automatically
+     * from the client's cached server info.
+     *
+     * @param opts - P2P receive options (code, Peer constructor, callbacks, tuning).
+     * @returns P2P receive session with control methods.
+     * @throws {DropgateValidationError} If P2P is not enabled on the server.
+     * @throws {DropgateNetworkError} If the signalling server cannot be reached.
+     */
+    p2pReceive(opts: P2PReceiveFileOptions): Promise<P2PReceiveSession>;
+    private _attemptChunkUpload;
+}
 
 /**
- * Start a direct transfer (P2P) receiver session.
- *
- * IMPORTANT: Consumer must provide the PeerJS Peer constructor and handle file writing.
- * This removes DOM coupling (no streamSaver).
- *
- * Example:
- * ```js
- * import Peer from 'peerjs';
- * import { startP2PReceive } from '@dropgate/core/p2p';
- *
- * let writer;
- * const session = await startP2PReceive({
- *   code: 'ABCD-1234',
- *   Peer,
- *   host: 'dropgate.link',
- *   secure: true,
- *   onMeta: ({ name, total }) => {
- *     // Consumer creates file writer
- *     writer = createWriteStream(name);
- *   },
- *   onData: async (chunk) => {
- *     // Consumer writes data
- *     await writer.write(chunk);
- *   },
- *   onComplete: () => {
- *     writer.close();
- *     console.log('Done!');
- *   },
- * });
- * ```
- */
-declare function startP2PReceive(opts: P2PReceiveOptions): Promise<P2PReceiveSession>;
+ * Get the default Base64 adapter for the current environment.
+ * Automatically detects Node.js Buffer vs browser btoa/atob.
+ */
+declare function getDefaultBase64(): Base64Adapter;
+/**
+ * Get the default crypto object for the current environment.
+ * Returns globalThis.crypto if available.
+ */
+declare function getDefaultCrypto(): CryptoAdapter | undefined;
+/**
+ * Get the default fetch function for the current environment.
+ * Returns globalThis.fetch if available.
+ */
+declare function getDefaultFetch(): FetchFn | undefined;
 
 /**
  * Check if a hostname is localhost
@@ -944,31 +1112,4 @@ declare function generateP2PCode(cryptoObj?: CryptoAdapter): string;
  */
 declare function isP2PCodeLike(code: string): boolean;
 
-/**
- * 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(config?: P2PServerConfig): PeerOptions;
-interface CreatePeerWithRetriesOptions {
-    code?: string | null;
-    codeGenerator: () => string;
-    maxAttempts: number;
-    buildPeer: (id: string) => PeerInstance;
-    onCode?: (code: string, attempt: number) => void;
-}
-/**
- * Create a peer with retries if the code is already taken
- */
-declare function createPeerWithRetries(opts: CreatePeerWithRetriesOptions): Promise<{
-    peer: PeerInstance;
-    code: string;
-}>;
-
-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 };
+export { AES_GCM_IV_BYTES, AES_GCM_TAG_BYTES, type AbortSignalWithCleanup, type Base64Adapter, type BaseProgressEvent, type BundleMetadata, type CompatibilityResult, type ConnectOptions, type CryptoAdapter, DEFAULT_CHUNK_SIZE, type DataConnection, type DataConnectionEvents, type DownloadFilesOptions, 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 P2PCancellationEvent, type P2PCapabilities, type P2PConnectionHealthEvent, type P2PMetadataEvent, type P2PReceiveCompleteEvent, type P2PReceiveFileOptions, type P2PReceiveProgressEvent, type P2PReceiveSession, type P2PReceiveState, type P2PResumeInfo, type P2PSendFileOptions, type P2PSendProgressEvent, type P2PSendSession, type P2PSendState, type P2PStatusEvent, type PeerConstructor, type PeerInstance, type PeerInstanceEvents, type PeerOptions, type SemverParts, type ServerCapabilities, type ServerInfo, type ServerTarget, type ShareTargetResult, StreamingZipWriter, type UploadCapabilities, type UploadFilesOptions, type UploadProgressEvent, type UploadResult, type UploadSession, type ValidateUploadOptions, type WebUICapabilities, arrayBufferToBase64, base64ToBytes, buildBaseUrl, bytesToBase64, decryptChunk, decryptFilenameFromBase64, encryptFilenameToBase64, encryptToBlob, estimateTotalUploadSizeBytes, exportKeyBase64, fetchJson, generateAesGcmKey, generateP2PCode, getDefaultBase64, getDefaultCrypto, getDefaultFetch, getServerInfo, importKeyFromBase64, isLocalhostHostname, isP2PCodeLike, isSecureContextForP2P, lifetimeToMs, makeAbortSignal, parseSemverMajorMinor, parseServerUrl, sha256Hex, sleep, validatePlainFilename };