@dropgate/core 2.0.0-beta.1

package/dist/p2p/index.d.ts

@@ -0,0 +1,369 @@
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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>;
+}
+
+/**
+ * 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 { type DataConnection, type P2PReceiveOptions, type P2PReceiveSession, type P2PSendOptions, type P2PSendSession, type PeerConstructor, type PeerInstance, type PeerOptions, buildPeerOptions, createPeerWithRetries, generateP2PCode, isLocalhostHostname, isP2PCodeLike, isSecureContextForP2P, startP2PReceive, startP2PSend };