@kadi.build/file-sharing 1.2.0 → 1.3.0

package/types/DownloadMonitor.d.ts

@@ -0,0 +1,100 @@
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+
+export interface DownloadRecord {
+  id: string;
+  file: string;
+  totalSize: number;
+  clientIp: string;
+  bytesTransferred: number;
+  progress: number;
+  speed: number;
+  startTime: number;
+  endTime?: number;
+  duration?: number;
+  status: 'active' | 'completed' | 'failed' | 'cancelled';
+  error?: string;
+  [key: string]: any;
+}
+
+export interface DownloadMetadata {
+  file?: string;
+  totalSize?: number;
+  size?: number;
+  clientIp?: string;
+  [key: string]: any;
+}
+
+export interface DownloadStats {
+  totalBytes: number;
+  totalDownloads: number;
+  activeCount: number;
+  failedCount: number;
+  averageSpeed: number;
+  peakConcurrent: number;
+  activeDownloads: DownloadRecord[];
+}
+
+export class DownloadMonitor extends EventEmitter {
+  constructor();
+
+  activeDownloads: Map<string, DownloadRecord>;
+  completedDownloads: DownloadRecord[];
+  stats: Omit<DownloadStats, 'activeDownloads'>;
+
+  /**
+   * Register a new download being tracked
+   * @param id - Unique download identifier
+   * @param metadata - Download metadata
+   */
+  startDownload(id: string, metadata?: DownloadMetadata): DownloadRecord;
+
+  /**
+   * Update download progress
+   * @param id - Download identifier
+   * @param bytesTransferred - Bytes transferred so far
+   */
+  updateProgress(id: string, bytesTransferred: number): void;
+
+  /**
+   * Mark a download as completed
+   * @param id - Download identifier
+   */
+  completeDownload(id: string): void;
+
+  /**
+   * Mark a download as failed
+   * @param id - Download identifier
+   * @param error - The error that caused the failure
+   */
+  failDownload(id: string, error: Error): void;
+
+  /**
+   * Cancel an active download
+   * @param id - Download identifier
+   */
+  cancelDownload(id: string): void;
+
+  /**
+   * Get current download statistics
+   */
+  getStats(): DownloadStats;
+
+  /**
+   * Get all active downloads
+   */
+  getActiveDownloads(): DownloadRecord[];
+
+  /**
+   * Get completed downloads
+   * @param limit - Max number of records to return (default: 100)
+   */
+  getCompletedDownloads(limit?: number): DownloadRecord[];
+
+  /**
+   * Clear completed download history
+   */
+  clearHistory(): void;
+}
+
+export default DownloadMonitor;

package/types/EventNotifier.d.ts

@@ -0,0 +1,71 @@
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+
+export interface EventNotifierConfig {
+  /** Maximum number of retry attempts for failed notifications (default: 3) */
+  maxRetries?: number;
+  /** Delay in ms between retries (default: 1000) */
+  retryDelay?: number;
+  /** Request timeout in ms (default: 5000) */
+  timeout?: number;
+}
+
+export interface WebhookOptions {
+  /** Custom HTTP headers to send with notifications */
+  headers?: Record<string, string>;
+}
+
+export interface WebhookInfo {
+  url: string;
+  events: string[];
+  active: boolean;
+  failCount: number;
+  lastNotified: string | null;
+}
+
+export interface NotificationHistoryEntry {
+  event: string;
+  timestamp: string;
+  recipientCount: number;
+}
+
+export class EventNotifier extends EventEmitter {
+  constructor(config?: EventNotifierConfig);
+
+  config: Required<EventNotifierConfig>;
+  webhooks: Map<string, any>;
+
+  /**
+   * Register a webhook for event notifications
+   * @param url - Webhook URL to send notifications to
+   * @param events - Array of event names to subscribe to (empty = all events)
+   * @param options - Additional options (headers, etc.)
+   */
+  addWebhook(url: string, events?: string[], options?: WebhookOptions): void;
+
+  /**
+   * Remove a registered webhook
+   * @param url - Webhook URL to remove
+   */
+  removeWebhook(url: string): void;
+
+  /**
+   * Send a notification for an event
+   * @param event - Event name
+   * @param data - Event data payload
+   */
+  notify(event: string, data?: Record<string, any>): Promise<void>;
+
+  /**
+   * Get list of registered webhooks
+   */
+  getWebhooks(): WebhookInfo[];
+
+  /**
+   * Get notification history
+   * @param limit - Max records to return (default: 50)
+   */
+  getHistory(limit?: number): NotificationHistoryEntry[];
+}
+
+export default EventNotifier;

package/types/FileSharingServer.d.ts

@@ -0,0 +1,229 @@
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+import type { HttpServerProvider, HttpAuthConfig } from './HttpServerProvider.js';
+import type { S3Server } from './S3Server.js';
+import type { DownloadMonitor, DownloadStats } from './DownloadMonitor.js';
+import type { ShutdownManager } from './ShutdownManager.js';
+import type { MonitoringDashboard } from './MonitoringDashboard.js';
+import type { EventNotifier } from './EventNotifier.js';
+
+export interface TunnelConfig {
+  /** Enable tunneling (default: false) */
+  enabled?: boolean;
+  /** Tunnel service to use (default: 'kadi') */
+  service?: string;
+  /** Extra service-specific options */
+  options?: Record<string, any>;
+  /** Auto-reconnect on failure (default: true) */
+  autoReconnect?: boolean;
+  /** Reconnect delay in ms (default: 5000) */
+  reconnectDelay?: number;
+  /** Auto-fallback to other services */
+  autoFallback?: boolean;
+  /** KĀDI tunnel auth token */
+  kadiToken?: string;
+  /** KĀDI broker server address */
+  kadiServer?: string;
+  /** KĀDI tunnel domain */
+  kadiDomain?: string;
+  /** KĀDI frpc port */
+  kadiPort?: number;
+  /** KĀDI SSH gateway port */
+  kadiSshPort?: number;
+  /** KĀDI tunnel mode ('ssh' | 'frpc' | 'auto') */
+  kadiMode?: string;
+  /** KĀDI agent identifier */
+  kadiAgentId?: string;
+  /** KĀDI transport ('wss' | 'tcp') */
+  kadiTransport?: string;
+  /** KĀDI WSS gateway hostname */
+  kadiWssControlHost?: string;
+  /** Ngrok auth token */
+  ngrokAuthToken?: string;
+  /** Override for TunnelManager options */
+  managerOptions?: Record<string, any>;
+  /** Port to tunnel (defaults to s3Port if running, else httpPort) */
+  port?: number;
+}
+
+export interface MonitoringConfig {
+  /** Enable monitoring (default: true) */
+  enabled?: boolean;
+  /** Enable console dashboard (default: false) */
+  dashboard?: boolean;
+  /** Webhook configurations */
+  webhooks?: Array<{
+    url: string;
+    events?: string[];
+    options?: Record<string, any>;
+  }>;
+}
+
+export interface ShutdownConfig {
+  /** Timeout in ms for graceful shutdown (default: 30000) */
+  gracefulTimeout?: number;
+  /** Whether to finish active downloads (default: true) */
+  finishActiveDownloads?: boolean;
+  /** Timeout in ms before force kill (default: 60000) */
+  forceKillTimeout?: number;
+}
+
+export interface FileSharingServerConfig {
+  /** Directory to serve files from (default: process.cwd()) */
+  staticDir?: string;
+  /** HTTP port (default: 3000) */
+  port?: number;
+  /** Bind host (default: '0.0.0.0') */
+  host?: string;
+  /** Enable local S3-compatible API (default: false) */
+  enableS3?: boolean;
+  /** S3 server port (default: 9000) */
+  s3Port?: number;
+  /** S3 server config overrides */
+  s3Config?: Record<string, any>;
+  /** Enable directory listing (default: true) */
+  enableDirectoryListing?: boolean;
+  /** Enable CORS (default: true) */
+  cors?: boolean;
+  /** HTTP authentication config */
+  auth?: HttpAuthConfig | null;
+  /** Tunnel configuration */
+  tunnel?: TunnelConfig;
+  /** Monitoring configuration */
+  monitoring?: MonitoringConfig;
+  /** Shutdown configuration */
+  shutdown?: ShutdownConfig;
+  /** Additional HTTP server config overrides */
+  httpConfig?: Record<string, any>;
+}
+
+export interface ServerInfo {
+  isRunning: boolean;
+  localUrl: string;
+  publicUrl: string | null;
+  s3Endpoint: string | null;
+  staticDir: string;
+  stats: DownloadStats;
+  uptime: number;
+  tunnelStatus: TunnelInfo | null;
+}
+
+export interface TunnelInfo {
+  id: string;
+  publicUrl: string;
+  [key: string]: any;
+}
+
+export interface FileEntry {
+  name: string;
+  type: 'file' | 'directory';
+  size: number;
+  modified: string;
+}
+
+export class FileSharingServer extends EventEmitter {
+  constructor(config?: FileSharingServerConfig);
+
+  config: FileSharingServerConfig & {
+    staticDir: string;
+    port: number;
+    host: string;
+    enableS3: boolean;
+    s3Port: number;
+    tunnel: Required<Pick<TunnelConfig, 'enabled' | 'service' | 'options' | 'autoReconnect' | 'reconnectDelay'>> & TunnelConfig;
+  };
+
+  /** The file manager instance */
+  fileManager: any;
+  /** The HTTP server provider instance */
+  httpServer: HttpServerProvider;
+  /** The S3 server instance (null if S3 disabled) */
+  s3Server: S3Server | null;
+  /** The tunnel manager instance */
+  tunnelManager: any;
+  /** The download monitor instance */
+  downloadMonitor: DownloadMonitor;
+  /** The shutdown manager instance */
+  shutdownManager: ShutdownManager;
+  /** The monitoring dashboard instance */
+  monitoringDashboard: MonitoringDashboard;
+  /** The event notifier instance */
+  eventNotifier: EventNotifier;
+  /** Whether the server is running */
+  isRunning: boolean;
+  /** Active tunnel info (null if no tunnel active) */
+  tunnel: TunnelInfo | null;
+
+  /** HTTP port */
+  readonly port: number;
+  /** Public tunnel URL (null if no tunnel) */
+  readonly tunnelUrl: string | null;
+  /** S3 endpoint URL (null if S3 not running) */
+  readonly s3Endpoint: string | null;
+  /** Served directory */
+  readonly staticDir: string;
+
+  /**
+   * Start the file sharing server
+   */
+  start(): Promise<ServerInfo>;
+
+  /**
+   * Stop the file sharing server.
+   * Gracefully shuts down all components.
+   */
+  stop(): Promise<void>;
+
+  /**
+   * Enable tunnel to expose server publicly
+   * @param options - Tunnel options
+   */
+  enableTunnel(options?: TunnelConfig): Promise<TunnelInfo>;
+
+  /**
+   * Disable active tunnel
+   */
+  disableTunnel(): Promise<void>;
+
+  /**
+   * Enable S3-compatible API dynamically
+   * @param options - S3 server options
+   */
+  enableS3(options?: Record<string, any>): Promise<{ port: number; endpoint: string }>;
+
+  /**
+   * Disable S3 API
+   */
+  disableS3(): Promise<void>;
+
+  /**
+   * Get current server information and statistics
+   */
+  getInfo(): ServerInfo;
+
+  /**
+   * Get download statistics
+   */
+  getStats(): DownloadStats;
+
+  /**
+   * List files in the served directory
+   * @param subPath - Optional subdirectory path
+   */
+  listFiles(subPath?: string): Promise<FileEntry[]>;
+
+  /**
+   * Add a webhook for event notifications
+   * @param url - Webhook URL
+   * @param events - Events to subscribe to
+   */
+  addWebhook(url: string, events?: string[]): void;
+
+  /**
+   * Remove a webhook
+   * @param url - Webhook URL to remove
+   */
+  removeWebhook(url: string): void;
+}
+
+export default FileSharingServer;

package/types/HttpServerProvider.d.ts

@@ -0,0 +1,152 @@
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+import type { Server as HttpServer, IncomingMessage, ServerResponse } from 'http';
+
+export interface HttpAuthConfig {
+  /** API key for Bearer / X-API-Key authentication */
+  apiKey?: string;
+  /** Bearer token for Authorization header */
+  bearerToken?: string;
+  /** Username for HTTP Basic auth */
+  username?: string;
+  /** Password for HTTP Basic auth */
+  password?: string;
+}
+
+export interface SslConfig {
+  key: string | Buffer;
+  cert: string | Buffer;
+  ca?: string | Buffer;
+}
+
+export interface HttpServerProviderConfig {
+  /** HTTP port (default: 3000) */
+  port?: number;
+  /** Bind host (default: '0.0.0.0') */
+  host?: string;
+  /** Directory to serve files from (default: process.cwd()) */
+  staticDir?: string;
+  /** Whether to show directory listing (default: true) */
+  enableDirectoryListing?: boolean;
+  /** Enable CORS (default: true) */
+  cors?: boolean;
+  /** Authentication configuration */
+  auth?: HttpAuthConfig | null;
+  /** SSL/TLS configuration */
+  ssl?: SslConfig | null;
+  /** Maximum file size in bytes (null = unlimited) */
+  maxFileSize?: number | null;
+  /** Directory for uploads (null = same as staticDir) */
+  uploadDir?: string | null;
+}
+
+export interface HttpStartResult {
+  port: number;
+  host: string;
+  url: string;
+  already?: boolean;
+}
+
+export interface MiddlewareInfo {
+  name: string;
+  priority: number;
+}
+
+export interface CustomRouteInfo {
+  method: string;
+  path: string;
+  priority: number;
+}
+
+type MiddlewareHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  next: (err?: Error) => void
+) => void | Promise<void>;
+
+type RouteHandler = (req: IncomingMessage & { params?: Record<string, string> }, res: ServerResponse) => void | Promise<void>;
+
+export class HttpServerProvider extends EventEmitter {
+  constructor(config?: HttpServerProviderConfig);
+
+  config: Required<HttpServerProviderConfig>;
+  server: HttpServer | null;
+  isRunning: boolean;
+  activeConnections: Map<string, any>;
+  startTime: Date | null;
+  requestCount: number;
+  errorCount: number;
+
+  /**
+   * Start the HTTP server
+   */
+  start(): Promise<HttpStartResult>;
+
+  /**
+   * Stop the HTTP server
+   */
+  stop(): Promise<void>;
+
+  /**
+   * Get active connection count
+   */
+  getActiveConnections(): number;
+
+  /**
+   * Force close all active connections
+   */
+  closeAllConnections(): void;
+
+  /**
+   * Register a named middleware function into the request pipeline.
+   * Middleware runs BEFORE built-in auth and static-file handling.
+   * @param name - Unique middleware identifier
+   * @param handler - Middleware handler function
+   * @param opts - Options
+   */
+  addMiddleware(
+    name: string,
+    handler: MiddlewareHandler,
+    opts?: { priority?: number }
+  ): void;
+
+  /**
+   * Remove a named middleware.
+   * @param name - Middleware identifier to remove
+   */
+  removeMiddleware(name: string): boolean;
+
+  /**
+   * Get the list of registered middleware names (in execution order).
+   */
+  getMiddleware(): MiddlewareInfo[];
+
+  /**
+   * Register a custom route handler.
+   * Custom routes are matched BEFORE built-in static-file/upload handling.
+   * @param method - HTTP method ('GET', 'POST', etc.)
+   * @param urlPath - URL path or Express-style pattern
+   * @param handler - Route handler
+   * @param opts - Options
+   */
+  addCustomRoute(
+    method: string,
+    urlPath: string,
+    handler: RouteHandler,
+    opts?: { priority?: number }
+  ): void;
+
+  /**
+   * Remove a custom route.
+   * @param method - HTTP method
+   * @param urlPath - URL path pattern
+   */
+  removeCustomRoute(method: string, urlPath: string): boolean;
+
+  /**
+   * Get the list of registered custom routes.
+   */
+  getCustomRoutes(): CustomRouteInfo[];
+}
+
+export default HttpServerProvider;

package/types/MonitoringDashboard.d.ts

@@ -0,0 +1,64 @@
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+
+export interface MonitoringDashboardConfig {
+  /** Refresh interval in ms (default: 1000) */
+  refreshInterval?: number;
+  /** Whether to show progress bars in output (default: true) */
+  showProgressBars?: boolean;
+  /** Max number of active downloads to display (default: 10) */
+  maxDisplayItems?: number;
+}
+
+export interface DashboardStats {
+  totalBytes: number;
+  totalDownloads: number;
+  activeCount: number;
+  activeDownloads: Array<{
+    id?: string;
+    file?: string;
+    progress?: number;
+    [key: string]: any;
+  }>;
+  averageSpeed: number;
+  peakConcurrent: number;
+  uptime: number;
+}
+
+export interface DashboardServerInfo {
+  localUrl?: string;
+  publicUrl?: string;
+  s3Endpoint?: string;
+  [key: string]: any;
+}
+
+export class MonitoringDashboard extends EventEmitter {
+  constructor(config?: MonitoringDashboardConfig);
+
+  config: Required<MonitoringDashboardConfig>;
+  isRunning: boolean;
+
+  /**
+   * Start the monitoring dashboard
+   */
+  start(): Promise<{ running: boolean }>;
+
+  /**
+   * Stop the monitoring dashboard
+   */
+  stop(): Promise<void>;
+
+  /**
+   * Update dashboard statistics
+   * @param stats - New stats to display
+   */
+  updateStats(stats: Partial<DashboardStats>): void;
+
+  /**
+   * Set server information
+   * @param info - Server info (localUrl, publicUrl, etc.)
+   */
+  setServerInfo(info: DashboardServerInfo): void;
+}
+
+export default MonitoringDashboard;