@getdashfy/server 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,422 @@
+import { PollMode, Subscription, DashfyConfig, APIRegistration } from '@getdashfy/types';
+import { FastifyInstance } from 'fastify';
+import { Logger } from 'pino';
+import { Socket } from 'socket.io';
+
+interface API {
+    mode: PollMode;
+    methods: Record<string, (...args: any[]) => Promise<unknown>>;
+}
+interface BusOptions {
+    logger: Logger;
+    pollInterval?: number;
+}
+interface ClientInfo {
+    socket: Socket;
+    subscriptions: Set<string>;
+    connectedAt: Date;
+}
+interface DashfyOptions {
+    logger?: Logger;
+    app?: FastifyInstance;
+}
+interface SubscriptionData extends Subscription {
+    clients: Set<string>;
+    timer?: NodeJS.Timeout;
+    pushDispose?: () => void;
+    cached?: {
+        id: string;
+        data: unknown;
+    };
+}
+interface SubscriptionInfo {
+    id: string;
+    clientCount: number;
+    hasCachedData: boolean;
+    hasTimer: boolean;
+}
+
+/**
+ * Main Dashfy server class that manages the dashboard application.
+ *
+ * Orchestrates HTTP server (Fastify), WebSocket communication (Socket.IO),
+ * API registration (Bus), and configuration handling with hot-reload support.
+ *
+ * @example
+ * ```ts
+ * import { Dashfy } from '@getdashfy/server'
+ *
+ * const dashfy = new Dashfy()
+ *
+ * // Load configuration from JSON (or YAML)
+ * await dashfy.configureFromFile('./dashfy.config.json')
+ *
+ * // Register APIs
+ * dashfy.registerApi('github', () => ({
+ *   async stars(params: { owner: string; repo: string }) {
+ *     const res = await fetch(`https://api.github.com/repos/${params.owner}/${params.repo}`)
+ *     const data = await res.json()
+ *     return { stars: data.stargazers_count }
+ *   }
+ * }))
+ *
+ * // Start server
+ * await dashfy.start()
+ * // Server running at http://0.0.0.0:5001
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Push mode for real-time data
+ * dashfy.registerApi('metrics', () => ({
+ *   cpuUsage(callback: (data: unknown) => void) {
+ *     const interval = setInterval(() => {
+ *       callback({ usage: process.cpuUsage(), timestamp: Date.now() })
+ *     }, 1000)
+ *     return () => clearInterval(interval) // cleanup
+ *   }
+ * }), 'push')
+ * ```
+ */
+declare class Dashfy {
+    private app;
+    private io?;
+    private bus;
+    private config?;
+    private logger;
+    private configPath?;
+    /**
+     * Creates a new Dashfy instance.
+     *
+     * @param options - Dashfy options
+     * @param options.logger - Logger instance
+     * @param options.app - Existing Fastify instance. When provided,
+     *                      Dashfy will use this instance instead of creating a new one,
+     *                      allowing integration with existing Fastify middleware and routes.
+     *
+     * @example
+     * ```ts
+     * // Integrate Dashfy with existing Fastify app
+     * import Fastify from 'fastify'
+     * import { Dashfy } from '@getdashfy/server'
+     *
+     * const app = Fastify()
+     *
+     * // Add your custom routes
+     * app.get('/custom-api', async (request, reply) => {
+     *   return { message: 'Custom endpoint' }
+     * })
+     *
+     * // Initialize Dashfy with existing app
+     * const dashfy = new Dashfy({ app })
+     * await dashfy.configureFromFile('./dashfy.config.json')
+     * await dashfy.start()
+     * ```
+     */
+    constructor(options?: DashfyOptions);
+    /**
+     * Configures the Dashfy server with the provided configuration object.
+     *
+     * This method accepts a configuration object and applies it to the server instance.
+     * If a global poll interval is specified in the configuration, it will be applied
+     * to the message bus for all poll-mode APIs.
+     *
+     * @param config - The Dashfy configuration object containing server settings,
+     *                 dashboards, and optional API configuration
+     *
+     * @remarks
+     * This method should be called before {@link start}. For loading configuration
+     * from a JSON or YAML file, use {@link configureFromFile} instead.
+     *
+     * @example
+     * ```ts
+     * const dashfy = new Dashfy();
+     *
+     * // Configure with a configuration object
+     * dashfy.configure({
+     *   port: 5001,
+     *   host: 'localhost',
+     *   dashboards: [
+     *     {
+     *       id: 'main',
+     *       title: 'Main Dashboard',
+     *       widgets: []
+     *     }
+     *   ],
+     *   apis: {
+     *     pollInterval: 30000 // 30 seconds
+     *   }
+     * });
+     *
+     * await dashfy.start();
+     * ```
+     */
+    configure(config: DashfyConfig): void;
+    /**
+     * Loads and applies configuration from a file (JSON or YAML).
+     *
+     * This method reads a configuration file (supports .json, .yml, .yaml formats),
+     * validates it against the schema, and applies it to the server instance. It also
+     * optionally watches the file for changes and automatically reloads the configuration
+     * when the file is modified. When changes are detected, all connected clients are
+     * notified via Socket.IO.
+     *
+     * @param configPath - Path to the configuration file (absolute or relative).
+     *                     Supports .json, .yml, .yaml extensions
+     * @param watchConfig - Whether to watch the configuration file for changes.
+     *                      When `true`, the configuration will be automatically reloaded
+     *                      on file changes. Defaults to `true`
+     *
+     * @throws {Error} If the configuration file cannot be read or fails validation
+     *
+     * @remarks
+     * This method should be called before {@link start}. If you already have a
+     * configuration object, use {@link configure} instead.
+     *
+     * When the configuration is reloaded due to file changes:
+     * - The new configuration is validated before applying
+     * - Connected clients receive the updated configuration (excluding sensitive API data)
+     * - If validation fails, the old configuration remains active
+     *
+     * @example
+     * ```ts
+     * const dashfy = new Dashfy();
+     *
+     * // Load configuration from JSON file with auto-reload
+     * await dashfy.configureFromFile('./dashfy.config.json');
+     *
+     * // Load configuration from YAML file with auto-reload
+     * await dashfy.configureFromFile('./dashfy.config.yaml');
+     *
+     * // Load without watching for changes (production)
+     * await dashfy.configureFromFile('./dashfy.config.yaml', false);
+     *
+     * await dashfy.start();
+     * ```
+     */
+    configureFromFile(configPath: string, watchConfig?: boolean): Promise<void>;
+    /**
+     * Registers an API with the message bus for data retrieval.
+     *
+     * This method allows you to register custom APIs that widgets can subscribe to
+     * for fetching data. APIs can operate in either poll mode (periodic fetching)
+     * or push mode (real-time updates via callbacks).
+     *
+     * @param id - Unique identifier for the API (e.g., 'github', 'weather', 'analytics')
+     * @param api - Factory function that returns an object containing API methods.
+     *              Each method should be async and return data that widgets can consume
+     * @param mode - The API mode: `poll` (default) for periodic polling,
+     *               or `push` for real-time push-based updates
+     *
+     * @throws {Error} If an API with the same ID is already registered
+     * @throws {Error} If the API mode is invalid
+     *
+     * @remarks
+     * - In **poll mode**, the bus automatically calls API methods at regular intervals
+     * - In **push mode**, API methods receive a callback to push data when available
+     * - APIs should be registered before calling {@link start}
+     * - The core `dashfy` API is automatically registered and provides system information
+     *
+     * @example
+     * ```ts
+     * const dashfy = new Dashfy();
+     *
+     * // Register a poll-mode API (default)
+     * dashfy.registerApi('github', () => ({
+     *   async stars(params: { owner: string; repo: string }) {
+     *     const response = await fetch(
+     *       `https://api.github.com/repos/${params.owner}/${params.repo}`
+     *     );
+     *     const data = await response.json();
+     *     return { stars: data.stargazers_count };
+     *   }
+     * }));
+     *
+     * // Register a push-mode API for real-time updates
+     * dashfy.registerApi('metrics', () => ({
+     *   async cpuUsage(callback: (data: unknown) => void) {
+     *     const interval = setInterval(() => {
+     *       const usage = process.cpuUsage();
+     *       callback({ cpu: usage });
+     *     }, 1000);
+     *
+     *     return () => clearInterval(interval);
+     *   }
+     * }), 'push');
+     * ```
+     */
+    registerApi(id: string, api: APIRegistration, mode?: PollMode): void;
+    /**
+     * Starts the Dashfy server and begins listening for connections.
+     *
+     * This method initializes and starts all server components including the HTTP server,
+     * WebSocket connections, static file serving, and API endpoints. It must be called
+     * after configuration is loaded via {@link configure} or {@link configureFromFile}.
+     *
+     * @throws {Error} If configuration has not been set before calling this method
+     *
+     * @remarks
+     * **What this method does:**
+     * 1. Validates that configuration is loaded
+     * 2. Sets up CORS for cross-origin requests
+     * 3. Serves static files from the `build` directory (if available)
+     * 4. Registers HTTP endpoints:
+     *    - `GET /config` - Returns public configuration (excludes sensitive API data)
+     *    - `GET /health` - Health check endpoint with uptime and status
+     *    - `GET /api/info` - Returns registered APIs and connection info
+     * 5. Initializes Socket.IO for real-time WebSocket communication
+     * 6. Sets up Socket.IO event handlers:
+     *    - `connection` - Client connects, receives configuration
+     *    - `api.subscription` - Widget subscribes to data
+     *    - `api.unsubscription` - Widget unsubscribes from data
+     *    - `disconnect` - Client disconnects, cleanup performed
+     *    - `error` - Socket error handling
+     * 7. Starts listening on configured host and port
+     *
+     * **Port and Host Resolution:**
+     * - Port: `process.env.PORT` → `config.port` → `5001` (default)
+     * - Host: `process.env.HOST` → `config.host` → `0.0.0.0` (default)
+     *
+     * @example
+     * ```ts
+     * const dashfy = new Dashfy();
+     *
+     * // Configure the server
+     * await dashfy.configureFromFile('./dashfy.config.json');
+     *
+     * // Register custom APIs
+     * dashfy.registerApi('github', () => ({
+     *   async stars(params: { owner: string; repo: string }) {
+     *     // ... fetch GitHub stars
+     *   }
+     * }));
+     *
+     * // Start the server
+     * await dashfy.start();
+     * // Server is now running and accepting connections
+     * ```
+     *
+     * @example
+     * ```ts
+     * // With environment variables
+     * process.env.PORT = '3000';
+     * process.env.HOST = 'localhost';
+     *
+     * const dashfy = new Dashfy();
+     * await dashfy.configureFromFile('./dashfy.config.json');
+     * await dashfy.start();
+     * // Server running on http://localhost:3000
+     * ```
+     */
+    start(): Promise<void>;
+    /**
+     * Gracefully stops the Dashfy server and cleans up all resources.
+     *
+     * This method performs a graceful shutdown of the server, closing all active
+     * connections and releasing resources. It closes the Socket.IO server (if initialized)
+     * and the underlying Fastify HTTP server.
+     *
+     * @remarks
+     * **Shutdown process:**
+     * 1. Logs shutdown initiation
+     * 2. Closes Socket.IO server (disconnects all WebSocket clients)
+     * 3. Closes Fastify HTTP server (stops accepting new connections)
+     * 4. Waits for all pending requests to complete
+     * 5. Logs shutdown completion
+     *
+     * This method is safe to call even if the server was never started or is already stopped.
+     * All connected clients will be disconnected, and their subscriptions will be cleaned up
+     * automatically by the bus.
+     *
+     * @example
+     * ```ts
+     * const dashfy = new Dashfy();
+     * await dashfy.configureFromFile('./dashfy.config.json');
+     * await dashfy.start();
+     *
+     * // Later, gracefully shut down the server
+     * await dashfy.stop();
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Graceful shutdown on process signals
+     * const dashfy = new Dashfy();
+     * await dashfy.configureFromFile('./dashfy.config.json');
+     * await dashfy.start();
+     *
+     * process.on('SIGTERM', async () => {
+     *   console.log('SIGTERM received, shutting down gracefully...');
+     *   await dashfy.stop();
+     *   process.exit(0);
+     * });
+     *
+     * process.on('SIGINT', async () => {
+     *   console.log('SIGINT received, shutting down gracefully...');
+     *   await dashfy.stop();
+     *   process.exit(0);
+     * });
+     * ```
+     */
+    stop(): Promise<void>;
+    /**
+     * Returns a sanitized configuration object without sensitive API data.
+     *
+     * Removes the `apis` property from the configuration before sending it to clients,
+     * as it may contain sensitive server-side settings like polling intervals or API keys.
+     *
+     * @param config - The full Dashfy configuration object
+     * @returns Configuration object without the `apis` property
+     *
+     * @internal
+     */
+    private getPublicConfig;
+    /**
+     * Registers the core `dashfy` API that provides system introspection and monitoring.
+     *
+     * This internal method is automatically called during construction to register
+     * a built-in API that exposes server health, statistics, and debugging information.
+     * The `dashfy` API is available to all widgets for monitoring server state.
+     *
+     * @remarks
+     * **Available methods:**
+     * - `inspector()` - Returns comprehensive system information including:
+     *   - `apis`: List of all registered API identifiers
+     *   - `clientCount`: Number of currently connected WebSocket clients
+     *   - `subscriptions`: Detailed information about all active subscriptions
+     *   - `uptime`: Server process uptime in seconds
+     *   - `version`: Dashfy server version (from package.json)
+     *   - `nodeVersion`: Node.js runtime version
+     *
+     * This API is useful for:
+     * - Building admin/monitoring dashboards
+     * - Debugging subscription and connection issues
+     * - Health checks and system monitoring
+     * - Displaying server statistics to users
+     *
+     * @example
+     * ```ts
+     * // Widgets can subscribe to the dashfy API
+     * // In a widget configuration:
+     * {
+     *   api: 'dashfy',
+     *   method: 'inspector'
+     * }
+     *
+     * // This returns:
+     * {
+     *   apis: ['dashfy', 'github', 'weather'],
+     *   clientCount: 5,
+     *   subscriptions: [...],
+     *   uptime: 3600.5,
+     *   version: '0.1.0',
+     *   nodeVersion: 'v20.10.0'
+     * }
+     * ```
+     *
+     * @internal
+     */
+    private registerCoreApi;
+}
+
+export { type API, type BusOptions, type ClientInfo, Dashfy, type DashfyOptions, type SubscriptionData, type SubscriptionInfo };