@dropgate/core 2.0.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,883 @@
+/**
+ * Default chunk size for file uploads (5MB)
+ */
+declare const DEFAULT_CHUNK_SIZE: number;
+/**
+ * AES-GCM initialization vector size in bytes
+ */
+declare const AES_GCM_IV_BYTES = 12;
+/**
+ * AES-GCM authentication tag size in bytes
+ */
+declare const AES_GCM_TAG_BYTES = 16;
+/**
+ * Total encryption overhead per chunk (IV + tag)
+ */
+declare const ENCRYPTION_OVERHEAD_PER_CHUNK: number;
+
+interface DropgateErrorOptions {
+    code?: string;
+    details?: unknown;
+    cause?: unknown;
+}
+/**
+ * Base error class for all Dropgate errors
+ */
+declare class DropgateError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(message: string, opts?: DropgateErrorOptions);
+}
+/**
+ * Validation error for invalid inputs
+ */
+declare class DropgateValidationError extends DropgateError {
+    constructor(message: string, opts?: DropgateErrorOptions);
+}
+/**
+ * Network error for connection issues
+ */
+declare class DropgateNetworkError extends DropgateError {
+    constructor(message: string, opts?: DropgateErrorOptions);
+}
+/**
+ * Protocol error for server communication issues
+ */
+declare class DropgateProtocolError extends DropgateError {
+    constructor(message: string, opts?: DropgateErrorOptions);
+}
+/**
+ * Abort error - replacement for DOMException with AbortError name
+ * Used when operations are cancelled
+ */
+declare class DropgateAbortError extends DropgateError {
+    constructor(message?: string);
+}
+/**
+ * Timeout error - replacement for DOMException with TimeoutError name
+ * Used when operations exceed their time limit
+ */
+declare class DropgateTimeoutError extends DropgateError {
+    constructor(message?: string);
+}
+
+/**
+ * Server upload capabilities returned from the server info endpoint.
+ */
+interface UploadCapabilities {
+    /** Whether hosted uploads are enabled on the server. */
+    enabled: boolean;
+    /** Maximum file size in megabytes (0 = unlimited). */
+    maxSizeMB?: number;
+    /** Maximum file lifetime in hours (0 = unlimited). */
+    maxLifetimeHours?: number;
+    /** Whether end-to-end encryption is supported. */
+    e2ee?: boolean;
+}
+/**
+ * Server P2P (direct transfer) capabilities.
+ */
+interface P2PCapabilities {
+    /** Whether P2P transfers are enabled on the server. */
+    enabled: boolean;
+    /** Path to the PeerJS signaling server. */
+    peerjsPath?: string;
+    /** ICE servers for WebRTC connectivity. */
+    iceServers?: RTCIceServer[];
+}
+/**
+ * Server Web UI capabilities.
+ */
+interface WebUICapabilities {
+    /** Whether the Web UI is enabled on the server. */
+    enabled: boolean;
+}
+/**
+ * Combined server capabilities object.
+ */
+interface ServerCapabilities {
+    /** Hosted upload capabilities. */
+    upload?: UploadCapabilities;
+    /** P2P transfer capabilities. */
+    p2p?: P2PCapabilities;
+    /** Web UI capabilities. */
+    webUI?: WebUICapabilities;
+}
+/**
+ * Server information returned from the /api/info endpoint.
+ */
+interface ServerInfo {
+    /** Display name of the server. */
+    name?: string;
+    /** Server version string. */
+    version: string;
+    /** Server capabilities. */
+    capabilities?: ServerCapabilities;
+}
+/**
+ * Progress event emitted during upload operations.
+ */
+interface ProgressEvent {
+    /** Current phase of the operation (e.g., 'init', 'chunk', 'complete'). */
+    phase: string;
+    /** Human-readable status text. */
+    text?: string;
+    /** Completion percentage (0-100). */
+    percent?: number;
+    /** Current chunk index (0-based). */
+    chunkIndex?: number;
+    /** Total number of chunks. */
+    totalChunks?: number;
+}
+/**
+ * Result of a successful file upload.
+ */
+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;
+    /** Server base URL used for the upload. */
+    baseUrl: string;
+    /** Base64-encoded encryption key (only present if encrypted). */
+    keyB64?: string;
+}
+/**
+ * Result of a client/server compatibility check.
+ */
+interface CompatibilityResult {
+    /** Whether the client and server versions are compatible. */
+    compatible: boolean;
+    /** Human-readable compatibility message. */
+    message: string;
+    /** Client version string. */
+    clientVersion: string;
+    /** Server version string. */
+    serverVersion: string;
+}
+/**
+ * Result of resolving a share target (code or URL).
+ */
+interface ShareTargetResult {
+    /** Whether the share target is valid. */
+    valid: boolean;
+    /** Type of share target (e.g., 'p2p', 'file'). */
+    type?: string;
+    /** Resolved target identifier. */
+    target?: string;
+    /** Reason for invalidity if not valid. */
+    reason?: string;
+}
+/**
+ * Crypto adapter interface compatible with the Web Crypto API.
+ * Used for encryption operations and secure random generation.
+ */
+interface CryptoAdapter {
+    /** SubtleCrypto interface for cryptographic operations. */
+    readonly subtle: SubtleCrypto;
+    /** Fill an array with cryptographically secure random values. */
+    getRandomValues<T extends ArrayBufferView | null>(array: T): T;
+}
+/**
+ * Fetch function type compatible with the standard fetch API.
+ * @param input - The URL or Request object to fetch.
+ * @param init - Optional fetch configuration.
+ * @returns A Promise that resolves to a Response.
+ */
+type FetchFn = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Base64 adapter for environment-agnostic encoding/decoding.
+ * Allows the library to work in both browser and Node.js environments.
+ */
+interface Base64Adapter {
+    /** Encode bytes to a base64 string. */
+    encode(bytes: Uint8Array): string;
+    /** Decode a base64 string to bytes. */
+    decode(b64: string): Uint8Array;
+}
+/**
+ * File source abstraction for cross-environment compatibility.
+ * Works with browser File/Blob and can be implemented for Node.js streams.
+ */
+interface FileSource {
+    /** File name. */
+    readonly name: string;
+    /** File size in bytes. */
+    readonly size: number;
+    /** MIME type of the file. */
+    readonly type?: string;
+    /** Extract a slice of the file. */
+    slice(start: number, end: number): 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;
+    /** Upload chunk size in bytes (default: 5MB). */
+    chunkSize?: number;
+    /** Custom fetch implementation (uses global fetch by default). */
+    fetchFn?: FetchFn;
+    /** Custom crypto implementation (uses global crypto by default). */
+    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.
+ */
+interface ServerTarget {
+    /** Server hostname (e.g., 'dropgate.link'). */
+    host: string;
+    /** Server port number (omit for default 80/443). */
+    port?: number;
+    /** Whether to use HTTPS (default: true). */
+    secure?: boolean;
+}
+/**
+ * Options for uploading a file to the server.
+ */
+interface UploadOptions extends ServerTarget {
+    /** File to upload. */
+    file: FileSource;
+    /** File lifetime in milliseconds (0 = server default). */
+    lifetimeMs: number;
+    /** Whether to encrypt the file with E2EE. */
+    encrypt: boolean;
+    /** Override the filename sent to the server. */
+    filenameOverride?: string;
+    /** Callback for progress updates. */
+    onProgress?: (evt: ProgressEvent) => void;
+    /** AbortSignal to cancel the upload. */
+    signal?: AbortSignal;
+    /** Timeout settings for various upload phases. */
+    timeouts?: {
+        /** Timeout for fetching server info (default: 5000ms). */
+        serverInfoMs?: number;
+        /** Timeout for upload initialization (default: 15000ms). */
+        initMs?: number;
+        /** Timeout for each chunk upload (default: 60000ms). */
+        chunkMs?: number;
+        /** Timeout for upload completion (default: 30000ms). */
+        completeMs?: number;
+    };
+    /** Retry settings for failed chunk uploads. */
+    retry?: {
+        /** Maximum number of retries per chunk (default: 5). */
+        retries?: number;
+        /** Initial backoff delay in milliseconds (default: 1000ms). */
+        backoffMs?: number;
+        /** Maximum backoff delay in milliseconds (default: 30000ms). */
+        maxBackoffMs?: number;
+    };
+}
+/**
+ * Options for fetching server information.
+ */
+interface GetServerInfoOptions extends ServerTarget {
+    /** 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;
+    /** Requested file lifetime in milliseconds. */
+    lifetimeMs: number;
+    /** Whether encryption will be used. */
+    encrypt: boolean;
+    /** Server info containing capabilities to validate against. */
+    serverInfo: ServerInfo;
+}
+/**
+ * File metadata returned from the server.
+ */
+interface FileMetadata {
+    /** Whether the file is encrypted. */
+    isEncrypted: boolean;
+    /** 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;
+}
+/**
+ * Download progress event.
+ */
+interface DownloadProgressEvent {
+    /** Current phase of the download. */
+    phase: '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.
+ */
+interface DownloadOptions extends ServerTarget {
+    /** File ID to download. */
+    fileId: string;
+    /** Base64-encoded decryption key (required for encrypted files). */
+    keyB64?: string;
+    /** Callback for progress updates. */
+    onProgress?: (evt: DownloadProgressEvent) => void;
+    /** Callback for received data chunks. Consumer handles file writing. */
+    onData?: (chunk: Uint8Array) => Promise<void> | void;
+    /** AbortSignal to cancel the download. */
+    signal?: AbortSignal;
+    /** Request timeout in milliseconds (default: 60000ms). */
+    timeoutMs?: number;
+}
+/**
+ * Result of a file download.
+ */
+interface DownloadResult {
+    /** Decrypted filename. */
+    filename: string;
+    /** Total bytes received. */
+    receivedBytes: number;
+    /** Whether the file was encrypted. */
+    wasEncrypted: boolean;
+    /** The file data (only if onData callback was not provided). */
+    data?: Uint8Array;
+}
+
+/**
+ * Convert a Uint8Array to a base64 string
+ */
+declare function bytesToBase64(bytes: Uint8Array, adapter?: Base64Adapter): string;
+/**
+ * Convert an ArrayBuffer to a base64 string
+ */
+declare function arrayBufferToBase64(buf: ArrayBuffer, adapter?: Base64Adapter): string;
+/**
+ * Convert a base64 string to a Uint8Array
+ */
+declare function base64ToBytes(b64: string, adapter?: Base64Adapter): Uint8Array;
+
+type LifetimeUnit = 'minutes' | 'hours' | 'days' | 'unlimited';
+/**
+ * Convert a lifetime value and unit to milliseconds.
+ * Returns 0 for 'unlimited' or invalid inputs.
+ */
+declare function lifetimeToMs(value: number, unit: LifetimeUnit | string): number;
+
+interface SemverParts {
+    major: number;
+    minor: number;
+}
+/**
+ * Parse a semver string and extract major.minor parts.
+ * Returns { major: 0, minor: 0 } for invalid inputs.
+ */
+declare function parseSemverMajorMinor(version: string | undefined | null): SemverParts;
+
+/**
+ * Validate a plain (non-encrypted) filename.
+ * Throws DropgateValidationError if invalid.
+ */
+declare function validatePlainFilename(filename: string): void;
+
+/**
+ * Parse a server URL string into host, port, and secure components.
+ * If no protocol is specified, defaults to HTTPS.
+ */
+declare function parseServerUrl(urlStr: string): ServerTarget;
+/**
+ * Build a base URL from host, port, and secure options.
+ */
+declare function buildBaseUrl(opts: ServerTarget): string;
+/**
+ * Sleep for a specified duration, with optional abort signal support.
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+interface AbortSignalWithCleanup {
+    signal: AbortSignal;
+    cleanup: () => void;
+}
+/**
+ * Create an AbortSignal that combines a parent signal with a timeout.
+ */
+declare function makeAbortSignal(parentSignal?: AbortSignal | null, timeoutMs?: number): AbortSignalWithCleanup;
+interface FetchJsonResult {
+    res: Response;
+    json: unknown;
+    text: string;
+}
+interface FetchJsonOptions extends Omit<RequestInit, 'signal'> {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Fetch JSON from a URL with timeout and error handling.
+ */
+declare function fetchJson(fetchFn: FetchFn, url: string, opts?: FetchJsonOptions): Promise<FetchJsonResult>;
+
+/**
+ * Import a base64-encoded AES-GCM key.
+ * @param cryptoObj - Crypto adapter for key import.
+ * @param keyB64 - Base64-encoded key bytes.
+ * @param base64 - Optional base64 adapter.
+ * @returns The imported CryptoKey.
+ */
+declare function importKeyFromBase64(cryptoObj: CryptoAdapter, keyB64: string, base64?: Base64Adapter): Promise<CryptoKey>;
+/**
+ * Decrypt an AES-GCM encrypted chunk.
+ * Expected layout: [IV (12 bytes)] + [ciphertext + tag]
+ * @param cryptoObj - Crypto adapter for decryption.
+ * @param encryptedData - The encrypted data with IV prepended.
+ * @param key - The AES-GCM decryption key.
+ * @returns The decrypted data as ArrayBuffer.
+ */
+declare function decryptChunk(cryptoObj: CryptoAdapter, encryptedData: Uint8Array, key: CryptoKey): Promise<ArrayBuffer>;
+/**
+ * Decrypt a base64-encoded encrypted filename.
+ * @param cryptoObj - Crypto adapter for decryption.
+ * @param encryptedFilenameB64 - Base64-encoded encrypted filename.
+ * @param key - The AES-GCM decryption key.
+ * @param base64 - Optional base64 adapter.
+ * @returns The decrypted filename string.
+ */
+declare function decryptFilenameFromBase64(cryptoObj: CryptoAdapter, encryptedFilenameB64: string, key: CryptoKey, base64?: Base64Adapter): Promise<string>;
+
+/**
+ * Compute SHA-256 hash of data and return as hex string.
+ */
+declare function sha256Hex(cryptoObj: CryptoAdapter, data: ArrayBuffer): Promise<string>;
+/**
+ * Generate a new AES-GCM 256-bit encryption key.
+ */
+declare function generateAesGcmKey(cryptoObj: CryptoAdapter): Promise<CryptoKey>;
+/**
+ * Export a CryptoKey to a base64-encoded raw key.
+ */
+declare function exportKeyBase64(cryptoObj: CryptoAdapter, key: CryptoKey): Promise<string>;
+
+/**
+ * Encrypt data using AES-GCM and return as a Blob with IV prepended.
+ * Layout: [IV (12 bytes)] + [ciphertext + tag]
+ */
+declare function encryptToBlob(cryptoObj: CryptoAdapter, dataBuffer: ArrayBuffer, key: CryptoKey): Promise<Blob>;
+/**
+ * Encrypt a filename using AES-GCM and return as base64.
+ */
+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;
+/**
+ * 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);
+    /**
+     * 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.
+     * @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>;
+    /**
+     * 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.
+     */
+    checkCompatibility(serverInfo: ServerInfo): CompatibilityResult;
+    /**
+     * 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 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.
+     */
+    uploadFile(opts: UploadOptions): Promise<UploadResult>;
+    /**
+     * 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.
+     */
+    downloadFile(opts: DownloadOptions): Promise<DownloadResult>;
+    private attemptChunkUpload;
+}
+
+/**
+ * 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;
+
+/**
+ * PeerJS Peer constructor interface.
+ * Consumer must provide this constructor to P2P functions.
+ */
+interface PeerConstructor {
+    new (id?: string, options?: PeerOptions): PeerInstance;
+}
+/**
+ * PeerJS connection options.
+ */
+interface PeerOptions {
+    /** PeerJS server hostname. */
+    host?: string;
+    /** PeerJS server port. */
+    port?: number;
+    /** PeerJS server path. */
+    path?: string;
+    /** Whether to use secure WebSocket connection. */
+    secure?: boolean;
+    /** WebRTC configuration. */
+    config?: {
+        /** ICE servers for NAT traversal. */
+        iceServers?: RTCIceServer[];
+    };
+    /** PeerJS debug level (0-3). */
+    debug?: number;
+}
+/**
+ * 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(event: string, callback: (...args: unknown[]) => void): void;
+    /** Connect to another peer by ID. */
+    connect(peerId: string, options?: {
+        reliable?: boolean;
+    }): DataConnection;
+    /** Destroy this peer and close all connections. */
+    destroy(): 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(event: string, callback: (...args: unknown[]) => void): void;
+    /** Send data to the connected peer. */
+    send(data: unknown): void;
+    /** Close the data connection. */
+    close(): void;
+    /** Internal WebRTC data channel (for buffer monitoring). */
+    _dc?: RTCDataChannel;
+}
+/**
+ * Options for starting a P2P send session.
+ */
+interface P2PSendOptions {
+    /** File to send */
+    file: FileSource;
+    /** PeerJS Peer constructor - REQUIRED */
+    Peer: PeerConstructor;
+    /** 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[];
+    /** 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 */
+    chunkSize?: number;
+    /** Timeout waiting for receiver ready signal */
+    readyTimeoutMs?: 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;
+    /** 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 */
+    onComplete?: () => void;
+    /** Callback on error */
+    onError?: (err: Error) => void;
+}
+/**
+ * Return value from startP2PSend containing session control.
+ */
+interface P2PSendSession {
+    /** The PeerJS peer instance. */
+    peer: PeerInstance;
+    /** The generated sharing code. */
+    code: string;
+    /** Stop the session and clean up resources. */
+    stop: () => void;
+}
+/**
+ * Options for starting a P2P receive session.
+ */
+interface P2PReceiveOptions {
+    /** Sharing code to connect to */
+    code: string;
+    /** PeerJS Peer constructor - REQUIRED */
+    Peer: PeerConstructor;
+    /** 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 */
+    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 */
+    onError?: (err: Error) => void;
+    /** Callback when sender disconnects */
+    onDisconnect?: () => void;
+}
+/**
+ * Return value from startP2PReceive containing session control.
+ */
+interface P2PReceiveSession {
+    /** The PeerJS peer instance. */
+    peer: PeerInstance;
+    /** Stop the session and clean up resources. */
+    stop: () => void;
+}
+
+/**
+ * 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';
+ *
+ * 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>;
+
+/**
+ * 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>;
+
+/**
+ * Check if a hostname is localhost
+ */
+declare function isLocalhostHostname(hostname: string): boolean;
+/**
+ * Check if the current context allows P2P (HTTPS or localhost)
+ */
+declare function isSecureContextForP2P(hostname?: string, isSecureContext?: boolean): boolean;
+/**
+ * Generate a P2P sharing code using cryptographically secure random.
+ * Format: XXXX-0000 (4 letters + 4 digits)
+ */
+declare function generateP2PCode(cryptoObj?: CryptoAdapter): string;
+/**
+ * Check if a string looks like a P2P sharing code
+ */
+declare function isP2PCodeLike(code: string): boolean;
+
+interface BuildPeerOptionsInput {
+    host?: string;
+    port?: number;
+    peerjsPath?: string;
+    secure?: boolean;
+    iceServers?: RTCIceServer[];
+}
+/**
+ * Build PeerJS connection options
+ */
+declare function buildPeerOptions(opts?: BuildPeerOptionsInput): 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 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 };