@kadi.build/file-sharing 1.2.0 → 1.3.0

package/types/S3Server.d.ts

@@ -0,0 +1,109 @@
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+import type { Server as HttpServer, IncomingMessage } from 'http';
+
+export interface S3ServerConfig {
+  /** S3 server port (default: 9000) */
+  port?: number;
+  /** Bind host (default: '0.0.0.0') */
+  host?: string;
+  /** Root directory for object storage (default: process.cwd()) */
+  rootDir?: string;
+  /** S3 access key ID (default: 'minioadmin') */
+  accessKeyId?: string;
+  /** S3 secret access key (default: 'minioadmin') */
+  secretAccessKey?: string;
+  /** Default bucket name (default: 'local') */
+  bucketName?: string;
+  /** AWS region (default: 'us-east-1') */
+  region?: string;
+  /** Maximum file size in bytes (null = unlimited) */
+  maxFileSize?: number | null;
+}
+
+export interface S3StartResult {
+  port: number;
+  host: string;
+  endpoint: string;
+  serverId: string;
+}
+
+export interface S3BucketInfo {
+  name: string;
+  rootDir: string;
+}
+
+export interface S3ObjectEntry {
+  key: string;
+  size: number;
+  lastModified: string;
+  [key: string]: any;
+}
+
+export interface S3AuthResult {
+  success: boolean;
+  user?: { accessKey: string };
+  error?: string;
+}
+
+export interface S3TemporaryCredentials {
+  accessKey: string;
+  secretKey: string;
+  expiresAt: string;
+  /** Backward-compat alias for expiresAt as Date */
+  expiry: Date;
+}
+
+export class S3Server extends EventEmitter {
+  constructor(config?: S3ServerConfig);
+
+  config: Required<S3ServerConfig>;
+  server: HttpServer | null;
+  isRunning: boolean;
+  multipartUploads: Map<string, any>;
+  requestCount: number;
+
+  /** Stable server identifier */
+  readonly serverId: string;
+
+  /**
+   * Start the S3 server
+   */
+  start(): Promise<S3StartResult>;
+
+  /**
+   * Stop the S3 server
+   */
+  stop(): Promise<void>;
+
+  /**
+   * Get bucket configuration
+   */
+  getBucket(): S3BucketInfo;
+
+  /**
+   * List objects in bucket (programmatic access)
+   * @param prefix - Optional prefix filter
+   */
+  listObjects(prefix?: string): Promise<S3ObjectEntry[]>;
+
+  /**
+   * Validate an incoming request against the server's configured credentials.
+   * @param req - HTTP incoming request
+   */
+  validateAuthentication(req: IncomingMessage): S3AuthResult;
+
+  /**
+   * Programmatically remove a bucket (force-deletes even non-empty directories).
+   * @param bucketName - The bucket/directory name to remove
+   */
+  removeBucket(bucketName: string): Promise<void>;
+
+  /**
+   * Generate temporary S3 credentials with an expiry.
+   * @param opts - Options
+   */
+  generateTemporaryCredentials(opts?: { ttl?: number }): S3TemporaryCredentials;
+}
+
+export default S3Server;

package/types/ShutdownManager.d.ts

@@ -0,0 +1,51 @@
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+
+export interface ShutdownManagerConfig {
+  /** Timeout in ms for graceful shutdown (default: 30000) */
+  gracefulTimeout?: number;
+  /** Whether to wait for active downloads before shutting down (default: true) */
+  finishActiveDownloads?: boolean;
+  /** Timeout in ms before force kill (default: 60000) */
+  forceKillTimeout?: number;
+}
+
+export class ShutdownManager extends EventEmitter {
+  constructor(config?: ShutdownManagerConfig);
+
+  config: Required<ShutdownManagerConfig>;
+  isShuttingDown: boolean;
+  shutdownCallbacks: Array<{ callback: () => Promise<void>; priority: number }>;
+
+  /**
+   * Register a shutdown callback with priority.
+   * Lower priority numbers execute first.
+   * @param callback - Async callback to execute during shutdown
+   * @param priority - Execution priority (lower = earlier, default: 10)
+   */
+  register(callback: () => Promise<void>, priority?: number): void;
+
+  /**
+   * Unregister a previously registered callback
+   * @param callback - The callback to remove
+   */
+  unregister(callback: () => Promise<void>): void;
+
+  /**
+   * Install process signal handlers (SIGINT, SIGTERM)
+   */
+  installSignalHandlers(): void;
+
+  /**
+   * Perform graceful shutdown.
+   * Executes all registered callbacks in priority order with timeout.
+   */
+  shutdown(): Promise<void>;
+
+  /**
+   * Force shutdown - skip remaining callbacks
+   */
+  forceShutdown(): Promise<void>;
+}
+
+export default ShutdownManager;

package/types/index.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @kadi.build/file-sharing - Type declarations
+ *
+ * File sharing service with tunneling and local S3-compatible interface.
+ */
+
+import type { FileSharingServerConfig } from './FileSharingServer.js';
+import type { FileSharingServer } from './FileSharingServer.js';
+import type { HttpAuthConfig } from './HttpServerProvider.js';
+
+// Core classes
+export {
+  FileSharingServer,
+  FileSharingServerConfig,
+  TunnelConfig,
+  MonitoringConfig,
+  ShutdownConfig,
+  ServerInfo,
+  TunnelInfo,
+  FileEntry,
+} from './FileSharingServer.js';
+
+export {
+  HttpServerProvider,
+  HttpServerProviderConfig,
+  HttpAuthConfig,
+  SslConfig,
+  HttpStartResult,
+  MiddlewareInfo,
+  CustomRouteInfo,
+} from './HttpServerProvider.js';
+
+export {
+  S3Server,
+  S3ServerConfig,
+  S3StartResult,
+  S3BucketInfo,
+  S3ObjectEntry,
+  S3AuthResult,
+  S3TemporaryCredentials,
+} from './S3Server.js';
+
+export {
+  DownloadMonitor,
+  DownloadRecord,
+  DownloadMetadata,
+  DownloadStats,
+} from './DownloadMonitor.js';
+
+export {
+  ShutdownManager,
+  ShutdownManagerConfig,
+} from './ShutdownManager.js';
+
+export {
+  MonitoringDashboard,
+  MonitoringDashboardConfig,
+  DashboardStats,
+  DashboardServerInfo,
+} from './MonitoringDashboard.js';
+
+export {
+  EventNotifier,
+  EventNotifierConfig,
+  WebhookOptions,
+  WebhookInfo,
+  NotificationHistoryEntry,
+} from './EventNotifier.js';
+
+// Default export
+export { FileSharingServer as default } from './FileSharingServer.js';
+
+/**
+ * Create a FileSharingServer with default options
+ */
+export function createFileSharingServer(options?: FileSharingServerConfig): FileSharingServer;
+
+export interface QuickShareOptions {
+  /** HTTP port (default: 3000) */
+  port?: number;
+  /** Enable tunnel (default: false) */
+  tunnel?: boolean;
+  /** Tunnel service name (default: 'kadi') */
+  tunnelService?: string;
+  /** KĀDI auth token */
+  kadiToken?: string;
+  /** Ngrok auth token */
+  ngrokAuthToken?: string;
+  /** HTTP auth config */
+  auth?: HttpAuthConfig | null;
+  /** Extra tunnel options */
+  tunnelOptions?: Record<string, any>;
+}
+
+export interface QuickShareResult {
+  server: FileSharingServer;
+  localUrl: string;
+  publicUrl?: string;
+}
+
+/**
+ * Quick share - one-liner to share a directory
+ * @param directory - Directory to share
+ * @param options - Options
+ */
+export function createQuickShare(
+  directory: string,
+  options?: QuickShareOptions
+): Promise<QuickShareResult>;
+
+// Re-exports from dependencies (convenience)
+// Note: These types come from the respective packages.
+// If those packages don't have types, consumers should install them separately.
+export declare const FileManager: any;
+export declare const createFileManager: (...args: any[]) => any;
+export declare const TunnelManager: any;