@getdashfy/server 0.1.0

package/dist/index.js

@@ -0,0 +1,1225 @@
+import path, { extname } from 'path';
+import cors from '@fastify/cors';
+import fastifyStatic from '@fastify/static';
+import { getErrorMessage } from '@getdashfy/utils';
+import { watch } from 'chokidar';
+import Fastify from 'fastify';
+import { Server } from 'socket.io';
+import { EventEmitter } from 'events';
+import { request as request$1 } from 'undici';
+import { readFile } from 'fs/promises';
+import { parse } from 'yaml';
+import { z } from 'zod';
+import pino from 'pino';
+
+// src/dashfy.ts
+
+// ../types/dist/index.js
+var WebSocketEvent = /* @__PURE__ */ ((WebSocketEvent2) => {
+  WebSocketEvent2["CONNECT"] = "connect";
+  WebSocketEvent2["DISCONNECT"] = "disconnect";
+  WebSocketEvent2["ERROR"] = "error";
+  WebSocketEvent2["CONFIGURATION"] = "configuration";
+  WebSocketEvent2["RECONNECT"] = "reconnect";
+  WebSocketEvent2["RECONNECT_ATTEMPT"] = "reconnect_attempt";
+  WebSocketEvent2["RECONNECT_ERROR"] = "reconnect_error";
+  WebSocketEvent2["RECONNECT_FAILED"] = "reconnect_failed";
+  WebSocketEvent2["API_SUBSCRIPTION"] = "api.subscription";
+  WebSocketEvent2["API_UNSUBSCRIPTION"] = "api.unsubscription";
+  WebSocketEvent2["API_DATA"] = "api.data";
+  WebSocketEvent2["API_ERROR"] = "api.error";
+  return WebSocketEvent2;
+})(WebSocketEvent || {});
+
+// src/constants.ts
+var DEFAULT_PORT = 5001;
+var DEFAULT_HOST = "0.0.0.0";
+var DEFAULT_POLL_INTERVAL = 15e3;
+var DEFAULT_PUSH_INTERVAL = 2e3;
+var SOCKET_PING_TIMEOUT = 6e4;
+var SOCKET_PING_INTERVAL = 25e3;
+var DEFAULT_REQUEST_TIMEOUT = 1e4;
+function createPushIntervalFactory(logger, prefix) {
+  return (options = {}) => {
+    const { interval = DEFAULT_PUSH_INTERVAL } = options;
+    const intervals = /* @__PURE__ */ new Map();
+    const logKey = (key) => prefix ? `${prefix}.${key}` : key;
+    return (key, callback, fetchFn) => {
+      const stop = () => {
+        const existing = intervals.get(key);
+        if (!existing) {
+          return;
+        }
+        clearInterval(existing);
+        intervals.delete(key);
+        logger.info(`[${logKey(key)}] Stopped push interval`);
+      };
+      if (intervals.has(key)) {
+        return stop;
+      }
+      const pushData = async () => {
+        try {
+          const data = await fetchFn();
+          callback(data);
+        } catch (error) {
+          logger.error(`[${logKey(key)}] Error: ${getErrorMessage(error)}`);
+        }
+      };
+      void pushData();
+      const timer = setInterval(() => {
+        void pushData();
+      }, interval);
+      intervals.set(key, timer);
+      logger.info(`[${logKey(key)}] Started push interval (${interval}ms)`);
+      return stop;
+    };
+  };
+}
+async function request(options) {
+  const { url, method = "GET", headers = {}, body, timeout = DEFAULT_REQUEST_TIMEOUT } = options;
+  const requestHeaders = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    ...headers
+  };
+  const response = await request$1(url, {
+    method,
+    headers: requestHeaders,
+    body: body ? JSON.stringify(body) : void 0,
+    headersTimeout: timeout,
+    bodyTimeout: timeout
+  });
+  if (response.statusCode >= 400) {
+    const errorBody = await response.body.text().catch(() => "");
+    throw new Error(`HTTP ${response.statusCode}: ${errorBody || "Request failed"}`);
+  }
+  return response.body.json();
+}
+
+// src/bus.ts
+var Bus = class extends EventEmitter {
+  logger;
+  pollInterval;
+  apis = /* @__PURE__ */ new Map();
+  clients = /* @__PURE__ */ new Map();
+  subscriptions = /* @__PURE__ */ new Map();
+  /**
+   * Creates a new Bus instance.
+   *
+   * @param options - Bus options
+   * @param options.logger - Logger instance
+   * @param options.pollInterval - Poll interval in milliseconds (default: 15_000)
+   *
+   * @remarks
+   * Changing `pollInterval` after construction only affects subscriptions created afterwards;
+   * timers for already-active poll subscriptions keep their original interval until recreated.
+   */
+  constructor(options) {
+    super();
+    this.logger = options.logger;
+    this.pollInterval = options.pollInterval ?? DEFAULT_POLL_INTERVAL;
+  }
+  /**
+   * Register a new API with the bus.
+   *
+   * An API is an object composed of various methods that can be called by clients.
+   * APIs can operate in two modes:
+   * - `poll`: Methods are called periodically at a fixed interval
+   * - `push`: Methods push data to clients when available
+   *
+   * @param id - Unique identifier for the API
+   * @param apiRegistration - Function that returns an object with API methods
+   * @param mode - API mode: 'poll' (default) or 'push'
+   * @throws {Error} If the API mode is not 'poll' or 'push'
+   * @throws {Error} If an API with the same ID is already registered
+   *
+   * @example
+   * ```ts
+   * bus.registerApi('weather', ({ logger, request }) => ({
+   *   getCurrentWeather: async () => {
+   *     return request({ url: 'https://api.weather.com/current' })
+   *   }
+   * }), 'poll')
+   * ```
+   */
+  registerApi(id, apiRegistration, mode = "poll") {
+    if (mode !== "poll" && mode !== "push") {
+      const errorMessage = `Invalid API mode: ${String(mode)}. Must be 'poll' or 'push'`;
+      this.logger.error(errorMessage);
+      throw new Error(errorMessage);
+    }
+    if (this.apis.has(id)) {
+      const errorMessage = `API '${id}' is already registered`;
+      this.logger.error(errorMessage);
+      throw new Error(errorMessage);
+    }
+    const logger = this.logger.child({ api: id });
+    const methods = apiRegistration({
+      logger,
+      request,
+      createPushInterval: createPushIntervalFactory(logger, id)
+    });
+    this.apis.set(id, { mode, methods });
+    this.logger.info(`Registered API '${id}' (mode: ${mode})`);
+  }
+  /**
+   * Get all registered API identifiers.
+   *
+   * Returns an array of all API IDs that have been registered with the bus,
+   * sorted alphabetically. Useful for debugging, introspection, or displaying
+   * available APIs.
+   *
+   * @returns Array of registered API IDs in alphabetical order
+   *
+   * @example
+   * ```ts
+   * const apis = bus.listApis()
+   * console.log(apis) // ['github', 'news', 'weather']
+   *
+   * // Check if a specific API is registered
+   * if (bus.listApis().includes('github')) {
+   *   console.log('GitHub API is available')
+   * }
+   * ```
+   */
+  listApis() {
+    return Array.from(this.apis.keys()).sort((a, b) => a.localeCompare(b));
+  }
+  /**
+   * Register a new client connection with the bus.
+   *
+   * This should be called when a client establishes a WebSocket connection. The client
+   * is tracked with its socket, an empty subscriptions set, and a connection timestamp.
+   * Once registered, the client can subscribe to API methods.
+   *
+   * @param socket - Socket.IO socket instance representing the connected client
+   * @throws {Error} If a client with the same socket ID is already registered
+   *
+   * @example
+   * ```ts
+   * // In your Socket.IO connection handler
+   * io.on('connection', (socket) => {
+   *   bus.addClient(socket)
+   *
+   *   socket.on('disconnect', () => {
+   *     bus.removeClient(socket.id)
+   *   })
+   * })
+   * ```
+   */
+  addClient(socket) {
+    if (this.clients.has(socket.id)) {
+      const errorMessage = `Client with id ${socket.id} already registered`;
+      this.logger.error(errorMessage);
+      throw new Error(errorMessage);
+    }
+    this.clients.set(socket.id, {
+      socket,
+      subscriptions: /* @__PURE__ */ new Set(),
+      connectedAt: /* @__PURE__ */ new Date()
+    });
+    this.logger.info(`Client with id ${socket.id} connected`);
+  }
+  /**
+   * Remove a client and clean up all associated resources.
+   *
+   * This method removes the client from all subscriptions it was part of. If a subscription
+   * has no remaining clients after removal, the subscription is cleaned up and any polling
+   * timers are cleared. This should be called when a client disconnects to prevent memory leaks.
+   *
+   * @param clientId - The unique identifier of the client to remove (socket.id)
+   * @throws {Error} If the client is not found
+   *
+   * @example
+   * ```ts
+   * // In your Socket.IO disconnect handler
+   * socket.on('disconnect', () => {
+   *   bus.removeClient(socket.id)
+   *   console.log(`Client ${socket.id} removed`)
+   * })
+   * ```
+   */
+  removeClient(clientId) {
+    const clientInfo = this.clients.get(clientId);
+    if (!clientInfo) {
+      const errorMessage = `Client with id ${clientId} not found`;
+      this.logger.error(errorMessage);
+      throw new Error(errorMessage);
+    }
+    for (const subscriptionId of clientInfo.subscriptions) {
+      const subscription = this.subscriptions.get(subscriptionId);
+      if (!subscription) {
+        continue;
+      }
+      subscription.clients.delete(clientId);
+      if (subscription.clients.size === 0) {
+        this.teardownSubscription(subscriptionId);
+      }
+    }
+    this.clients.delete(clientId);
+    this.logger.info(`Client with id ${clientId} disconnected`);
+  }
+  /**
+   * Get the current number of connected clients.
+   *
+   * Returns the real-time count of active client connections. Useful for monitoring,
+   * health checks, or displaying connection statistics.
+   *
+   * @returns Number of currently connected clients
+   *
+   * @example
+   * ```ts
+   * // Display connection stats
+   * const count = bus.clientCount()
+   * console.log(`${count} client(s) connected`)
+   *
+   * // Health check endpoint
+   * app.get('/health', (req, res) => {
+   *   res.json({
+   *     status: 'ok',
+   *     clients: bus.clientCount()
+   *   })
+   * })
+   * ```
+   */
+  clientCount() {
+    return this.clients.size;
+  }
+  /**
+   * Subscribe a client to an API method call.
+   *
+   * This creates or reuses a subscription for the specified API method and adds the client
+   * to receive updates. For poll mode APIs, this starts periodic polling. For push mode APIs,
+   * this sets up the push producer. If cached data exists, it's immediately sent to the client.
+   *
+   * Routing is resolved from `subscription.api` (the registered API) and `subscription.endpoint`
+   * (the method on that API). The `subscription.id` is used as the key for deduping subscriptions,
+   * caching, and client messages; by convention it is `${api}.${endpoint}` (e.g. 'github.repos'),
+   * but this format is not enforced.
+   *
+   * @param clientId - The unique identifier of the connected client
+   * @param subscription - Subscription details including `id`, `api`, `endpoint`, and optional `params`
+   * @throws {Error} If the API ID (`subscription.api`) is empty or undefined
+   * @throws {Error} If the endpoint (`subscription.endpoint`) is empty or undefined
+   * @throws {Error} If the API is not registered
+   * @throws {Error} If the API method does not exist or is not a function
+   *
+   * @remarks
+   * If the client is not registered, the call returns silently (logging a warning) instead of
+   * throwing. If a subscription with the same `id` already exists, the incoming `params` are
+   * ignored: the subscription keeps the `params` supplied by its first subscriber.
+   *
+   * @example
+   * ```ts
+   * // Subscribe to a GitHub API method
+   * bus.subscribe('client-123', {
+   *   id: 'github.repos',
+   *   api: 'github',
+   *   endpoint: 'repos',
+   *   params: { user: 'octocat' }
+   * })
+   *
+   * // Subscribe without parameters
+   * bus.subscribe('client-456', {
+   *   id: 'weather.current',
+   *   api: 'weather',
+   *   endpoint: 'current'
+   * })
+   * ```
+   */
+  subscribe(clientId, subscription) {
+    const clientInfo = this.clients.get(clientId);
+    if (!clientInfo) {
+      this.logger.warn(`Cannot subscribe: client with id ${clientId} not found`);
+      return;
+    }
+    const subscriptionId = subscription.id;
+    const apiId = subscription.api;
+    const methodName = subscription.endpoint;
+    if (!apiId) {
+      const errorMessage = `Invalid API ID in subscription: ${subscriptionId}`;
+      this.logger.error(errorMessage);
+      throw new Error(errorMessage);
+    }
+    if (!methodName) {
+      const errorMessage = `Invalid endpoint in subscription: ${subscriptionId}`;
+      this.logger.error(errorMessage);
+      throw new Error(errorMessage);
+    }
+    const api = this.apis.get(apiId);
+    if (!api) {
+      const errorMessage = `API not found: ${apiId}`;
+      this.logger.error(errorMessage);
+      throw new Error(errorMessage);
+    }
+    const method = api.methods[methodName];
+    if (!method || typeof method !== "function") {
+      const errorMessage = `API method not found: ${apiId}.${methodName}`;
+      this.logger.error(errorMessage);
+      throw new Error(errorMessage);
+    }
+    if (!this.subscriptions.has(subscriptionId)) {
+      this.subscriptions.set(subscriptionId, {
+        id: subscriptionId,
+        api: apiId,
+        endpoint: methodName,
+        params: subscription.params,
+        clients: /* @__PURE__ */ new Set()
+      });
+      this.logger.info(`Created subscription ${subscriptionId}`);
+      if (api.mode === "poll") {
+        void this.processApiCall(subscriptionId, method, subscription.params);
+        const timer = setInterval(() => {
+          void this.processApiCall(subscriptionId, method, subscription.params);
+        }, this.pollInterval);
+        const sub2 = this.subscriptions.get(subscriptionId);
+        if (sub2) {
+          sub2.timer = timer;
+        }
+        this.logger.info(
+          `Started polling for subscription ${subscriptionId} every ${this.pollInterval}ms`
+        );
+      } else if (api.mode === "push") {
+        const producerResult = method((data) => {
+          const message = { id: subscriptionId, data };
+          const sub2 = this.subscriptions.get(subscriptionId);
+          if (sub2) {
+            sub2.cached = message;
+          }
+          this.send(subscriptionId, message, WebSocketEvent.API_DATA);
+        }, subscription.params);
+        Promise.resolve(producerResult).then((result) => {
+          if (typeof result !== "function") {
+            return;
+          }
+          const dispose = result;
+          const sub2 = this.subscriptions.get(subscriptionId);
+          if (sub2) {
+            sub2.pushDispose = dispose;
+          } else {
+            dispose();
+          }
+        }).catch((error) => {
+          this.logger.error(
+            `Push producer for ${subscriptionId} failed: ${getErrorMessage(error)}`
+          );
+        });
+        this.logger.info(`Created push producer for subscription ${subscriptionId}`);
+      }
+    }
+    const sub = this.subscriptions.get(subscriptionId);
+    if (!sub) {
+      this.logger.warn(`Cannot subscribe: subscription ${subscriptionId} not found`);
+      return;
+    }
+    sub.clients.add(clientId);
+    clientInfo.subscriptions.add(subscriptionId);
+    if (sub.cached) {
+      this.logger.info(
+        `Sending cached data to client with id ${clientId} for subscription ${subscriptionId}`
+      );
+      clientInfo.socket.emit(WebSocketEvent.API_DATA, sub.cached);
+    }
+  }
+  /**
+   * Unsubscribe a client from an API method subscription.
+   *
+   * This removes the client from the specified subscription. If this was the last client
+   * subscribed to this API method, the subscription is cleaned up entirely and any polling
+   * timers are cleared to prevent unnecessary API calls and memory leaks.
+   *
+   * If the client or subscription doesn't exist, the method returns silently without error.
+   * This is safe to call multiple times or for non-existent subscriptions.
+   *
+   * @param clientId - The unique identifier of the client to unsubscribe
+   * @param subscriptionId - The subscription ID to unsubscribe from (matches `subscription.id`, conventionally 'api.method')
+   *
+   * @example
+   * ```ts
+   * // Unsubscribe from a specific API
+   * socket.on('unsubscribe', (subscriptionId) => {
+   *   bus.unsubscribe(socket.id, subscriptionId)
+   * })
+   *
+   * // Unsubscribe when widget is removed
+   * bus.unsubscribe('client-123', 'github.repos')
+   * ```
+   */
+  unsubscribe(clientId, subscriptionId) {
+    const clientInfo = this.clients.get(clientId);
+    if (!clientInfo) {
+      this.logger.warn(`Cannot unsubscribe: client with id ${clientId} not found`);
+      return;
+    }
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) {
+      this.logger.warn(`Cannot unsubscribe: subscription ${subscriptionId} not found`);
+      return;
+    }
+    subscription.clients.delete(clientId);
+    clientInfo.subscriptions.delete(subscriptionId);
+    if (subscription.clients.size === 0) {
+      this.teardownSubscription(subscriptionId);
+    }
+  }
+  /**
+   * Get detailed information about all active subscriptions.
+   *
+   * Returns an array of subscription metadata including subscription IDs, client counts,
+   * cache status, and timer status. Useful for monitoring, debugging, and displaying
+   * real-time statistics about API subscriptions.
+   *
+   * @returns Array of subscription info objects, each containing:
+   *   - `id`: Subscription identifier (conventionally 'api.method')
+   *   - `clientCount`: Number of clients subscribed to this API method
+   *   - `hasCachedData`: Whether cached data is available for immediate delivery
+   *   - `hasTimer`: Whether a polling timer is active (poll mode only)
+   *
+   * @remarks
+   * Subscriptions are torn down automatically when their last client leaves, so a
+   * `clientCount` of `0` should not appear during normal operation.
+   *
+   * @example
+   * ```ts
+   * // Get all subscription stats
+   * const subs = bus.getSubscriptionsInfo()
+   * console.log(subs)
+   * // [
+   * //   {
+   * //     id: 'github.repos',
+   * //     clientCount: 3,
+   * //     hasCachedData: true,
+   * //     hasTimer: true
+   * //   },
+   * //   {
+   * //     id: 'weather.current',
+   * //     clientCount: 1,
+   * //     hasCachedData: false,
+   * //     hasTimer: false
+   * //   }
+   * // ]
+   *
+   * // Debug endpoint for monitoring
+   * app.get('/debug/subscriptions', (req, res) => {
+   *   res.json({
+   *     total: bus.getSubscriptionsInfo().length,
+   *     subscriptions: bus.getSubscriptionsInfo()
+   *   })
+   * })
+   * ```
+   */
+  getSubscriptionsInfo() {
+    return Array.from(this.subscriptions.entries()).map(([id, sub]) => ({
+      id,
+      clientCount: sub.clients.size,
+      hasCachedData: !!sub.cached,
+      hasTimer: !!sub.timer
+    }));
+  }
+  /**
+   * Execute an API method call and distribute results to subscribed clients.
+   *
+   * This internal method is called either periodically (for poll mode) or on-demand (for push mode).
+   * It executes the API method with the provided parameters, caches the result, and sends the data
+   * to all clients subscribed to this API method. If the API call fails, an error message is sent
+   * instead and logged.
+   *
+   * @param subscriptionId - The subscription identifier (conventionally 'api.method')
+   * @param method - The API method function to execute
+   * @param params - Optional parameters to pass to the API method
+   *
+   * @remarks
+   * This method handles:
+   * - Executing the API method with error handling
+   * - Caching successful responses for immediate delivery to new subscribers
+   * - Broadcasting data to all subscribed clients via 'api.data' event
+   * - Broadcasting errors to all subscribed clients via 'api.error' event
+   * - Logging execution details for debugging
+   *
+   * @internal
+   */
+  async processApiCall(subscriptionId, method, params) {
+    try {
+      this.logger.debug(`Calling subscription ${subscriptionId}`);
+      const data = await method(params);
+      const message = { id: subscriptionId, data };
+      const subscription = this.subscriptions.get(subscriptionId);
+      if (subscription) {
+        this.logger.info(`Caching response for subscription ${subscriptionId}`);
+        subscription.cached = message;
+      }
+      this.send(subscriptionId, message, WebSocketEvent.API_DATA);
+    } catch (error) {
+      const errorMessage = {
+        id: subscriptionId,
+        error: {
+          message: getErrorMessage(error)
+        }
+      };
+      this.logger.error({ err: error, subscriptionId }, "Subscription execution error");
+      this.send(subscriptionId, errorMessage, WebSocketEvent.API_ERROR);
+    }
+  }
+  /**
+   * Broadcast data to all clients subscribed to a specific API method.
+   *
+   * This internal method iterates through all clients subscribed to the given subscription
+   * and emits the data via Socket.IO. It safely handles cases where clients may have
+   * disconnected but haven't been cleaned up yet.
+   *
+   * @param subscriptionId - The subscription identifier (conventionally 'api.method')
+   * @param data - The data payload to send (API response or error message)
+   * @param type - The message type: 'api.data' for successful responses, 'api.error' for errors
+   *
+   * @remarks
+   * This method:
+   * - Returns silently if the subscription doesn't exist (already cleaned up)
+   * - Skips clients that no longer exist (race condition handling)
+   * - Uses Socket.IO's emit to send data to each client
+   *
+   * @internal
+   */
+  send(subscriptionId, data, type) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) {
+      this.logger.warn(`Cannot send data to subscription ${subscriptionId}: not found`);
+      return;
+    }
+    for (const clientId of subscription.clients) {
+      const clientInfo = this.clients.get(clientId);
+      if (clientInfo) {
+        clientInfo.socket.emit(type, data);
+      }
+    }
+  }
+  /**
+   * Tear down a subscription that has no clients remaining.
+   *
+   * Clears any poll-mode timer and invokes the push-mode disposer (if either is set),
+   * then removes the subscription entry. Safe to call when the subscription is missing.
+   *
+   * @param subscriptionId - The subscription identifier (conventionally 'api.method')
+   *
+   * @internal
+   */
+  teardownSubscription(subscriptionId) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) {
+      return;
+    }
+    if (subscription.timer) {
+      clearInterval(subscription.timer);
+    }
+    if (subscription.pushDispose) {
+      try {
+        subscription.pushDispose();
+      } catch (error) {
+        this.logger.error(`Push dispose for ${subscriptionId} failed: ${getErrorMessage(error)}`);
+      }
+    }
+    this.subscriptions.delete(subscriptionId);
+    this.logger.info(`Removed subscription ${subscriptionId} (no clients)`);
+  }
+};
+var WidgetConfigSchema = z.object({
+  extension: z.string(),
+  widget: z.string(),
+  title: z.string().optional(),
+  columns: z.number().positive(),
+  rows: z.number().positive(),
+  x: z.number().nonnegative(),
+  y: z.number().nonnegative()
+}).passthrough();
+var DashboardConfigSchema = z.object({
+  name: z.string().optional(),
+  title: z.string().optional(),
+  columns: z.number().positive(),
+  rows: z.number().positive(),
+  widgets: z.array(WidgetConfigSchema)
+});
+var DashfyConfigSchema = z.object({
+  port: z.number().positive().default(DEFAULT_PORT),
+  host: z.string().default(DEFAULT_HOST),
+  baseDir: z.string().optional(),
+  theme: z.string().optional(),
+  rotationDuration: z.number().positive().optional(),
+  dashboards: z.array(DashboardConfigSchema).min(1),
+  apis: z.object({
+    pollInterval: z.number().positive().optional()
+  }).passthrough().optional()
+});
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+function detectConfigFormat(filePath) {
+  const extension = extname(filePath).toLowerCase();
+  switch (extension) {
+    case ".json":
+      return "json" /* JSON */;
+    case ".yml":
+    case ".yaml":
+      return "yaml" /* YAML */;
+    default:
+      throw new ConfigError(
+        `Unsupported configuration file format: ${extension}. Supported formats: .json, .yml, .yaml`
+      );
+  }
+}
+function parseConfigContent(content, format) {
+  try {
+    switch (format) {
+      case "json" /* JSON */:
+        return JSON.parse(content);
+      case "yaml" /* YAML */:
+        return parse(content);
+      /* v8 ignore next 3 */
+      default:
+        throw new Error(`Unsupported format: ${format}`);
+    }
+  } catch (error) {
+    throw new ConfigError(
+      `Failed to parse ${format.toUpperCase()} content: ${getErrorMessage(error)}`
+    );
+  }
+}
+async function loadConfig(path2) {
+  try {
+    const format = detectConfigFormat(path2);
+    const content = await readFile(path2, "utf-8");
+    const rawConfig = parseConfigContent(content, format);
+    const config = DashfyConfigSchema.parse(rawConfig);
+    return config;
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      const issues = error.issues.map((issue) => `  - ${issue.path.join(".")}: ${issue.message}`).join("\n");
+      throw new ConfigError(`Configuration validation failed:
+${issues}`);
+    }
+    if (error instanceof ConfigError) {
+      throw error;
+    }
+    throw new Error(`Failed to load configuration from "${path2}": ${getErrorMessage(error)}`);
+  }
+}
+function createLogger(options) {
+  const isDevelopment = process.env.NODE_ENV !== "production";
+  return pino({
+    level: process.env.LOG_LEVEL ?? (isDevelopment ? "info" : "warn"),
+    transport: isDevelopment ? {
+      target: "pino-pretty",
+      options: {
+        colorize: true,
+        translateTime: "HH:MM:ss",
+        ignore: "pid,hostname",
+        singleLine: false
+      }
+    } : void 0,
+    ...options
+  });
+}
+
+// src/dashfy.ts
+var Dashfy = class {
+  app;
+  io;
+  bus;
+  config;
+  logger;
+  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 = {}) {
+    this.logger = options.logger ?? createLogger();
+    if (options.app) {
+      this.app = options.app;
+    } else {
+      this.app = Fastify({
+        logger: options.logger ? false : true,
+        disableRequestLogging: true
+      });
+    }
+    this.bus = new Bus({
+      logger: this.logger.child({ component: "bus" })
+    });
+    this.registerCoreApi();
+  }
+  /**
+   * 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) {
+    this.config = config;
+    if (config.apis?.pollInterval) {
+      this.bus.pollInterval = config.apis.pollInterval;
+      this.logger.info(`Set global poll interval to ${this.bus.pollInterval}ms`);
+    }
+  }
+  /**
+   * 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();
+   * ```
+   */
+  async configureFromFile(configPath, watchConfig = true) {
+    this.configPath = configPath;
+    const config = await loadConfig(configPath);
+    this.configure(config);
+    if (watchConfig) {
+      const watcher = watch(configPath);
+      watcher.on("change", async () => {
+        this.logger.info("Configuration file changed, reloading...");
+        try {
+          const newConfig = await loadConfig(configPath);
+          this.configure(newConfig);
+          if (this.io) {
+            this.io.emit("configuration", this.getPublicConfig(newConfig));
+          }
+          this.logger.info("Configuration reloaded successfully");
+        } catch (error) {
+          this.logger.error({ err: error }, "Failed to reload configuration");
+        }
+      });
+      this.logger.info(`Watching configuration file: ${configPath}`);
+    }
+  }
+  /**
+   * 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, api, mode = "poll") {
+    this.bus.registerApi(id, api, mode);
+  }
+  /**
+   * 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
+   * ```
+   */
+  async start() {
+    if (!this.config) {
+      const errorMessage = "Configuration required. Call configure() or configureFromFile() before starting.";
+      this.logger.error(errorMessage);
+      throw new Error(errorMessage);
+    }
+    await this.app.register(cors, {
+      origin: true,
+      credentials: true
+    });
+    const baseDir = this.config.baseDir ?? process.cwd();
+    const staticPath = path.join(baseDir, "build");
+    try {
+      await this.app.register(fastifyStatic, {
+        root: staticPath,
+        prefix: "/"
+      });
+      this.logger.info(`Serving static files from ${staticPath}`);
+    } catch (_error) {
+      this.logger.warn("Static files directory not found, skipping static serve");
+    }
+    this.app.get("/config", () => {
+      return this.getPublicConfig(this.config);
+    });
+    this.app.get("/health", () => ({
+      status: "ok",
+      uptime: process.uptime(),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }));
+    this.app.get("/api/info", () => ({
+      apis: this.bus.listApis(),
+      clientCount: this.bus.clientCount(),
+      subscriptions: this.bus.getSubscriptionsInfo()
+    }));
+    this.io = new Server(this.app.server, {
+      cors: {
+        origin: "*",
+        credentials: true
+      },
+      transports: ["websocket", "polling"],
+      pingTimeout: SOCKET_PING_TIMEOUT,
+      pingInterval: SOCKET_PING_INTERVAL
+    });
+    this.io.on("error", (error) => {
+      this.logger.error({ err: error }, "Socket.IO server error");
+    });
+    this.io.on("connection", (socket) => {
+      this.logger.info(`Socket connected: ${socket.id}`);
+      this.bus.addClient(socket);
+      if (this.config) {
+        socket.emit("configuration", this.getPublicConfig(this.config));
+      }
+      socket.on(WebSocketEvent.API_SUBSCRIPTION, (subscription) => {
+        this.logger.debug(`Subscription request: ${subscription.id} from ${socket.id}`);
+        try {
+          this.bus.subscribe(socket.id, subscription);
+        } catch (error) {
+          this.logger.error({ err: error }, "Subscription error");
+          socket.emit(WebSocketEvent.API_ERROR, {
+            id: subscription.id,
+            error: {
+              message: getErrorMessage(error)
+            }
+          });
+        }
+      });
+      socket.on(WebSocketEvent.API_UNSUBSCRIPTION, (subscription) => {
+        this.logger.debug(`Unsubscription request: ${subscription.id} from ${socket.id}`);
+        this.bus.unsubscribe(socket.id, subscription.id);
+      });
+      socket.on(WebSocketEvent.DISCONNECT, (reason) => {
+        this.logger.info(`Socket disconnected: ${socket.id} (${reason})`);
+        this.bus.removeClient(socket.id);
+      });
+      socket.on(WebSocketEvent.ERROR, (error) => {
+        this.logger.error({ err: error, socketId: socket.id }, "Socket error");
+      });
+    });
+    const port = process.env.PORT ? Number(process.env.PORT) : this.config.port ?? DEFAULT_PORT;
+    const host = process.env.HOST ?? this.config.host ?? DEFAULT_HOST;
+    await this.app.listen({ port, host });
+    this.logger.info(`\u{1F680} Dashfy server started`);
+    this.logger.info(`   - HTTP: http://${host}:${port}`);
+    this.logger.info(`   - WebSocket: ws://${host}:${port}`);
+    this.logger.info(`   - Registered APIs: ${this.bus.listApis().join(", ")}`);
+  }
+  /**
+   * 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);
+   * });
+   * ```
+   */
+  async stop() {
+    this.logger.info("Stopping Dashfy server...");
+    if (this.io) {
+      await new Promise((resolve, reject) => {
+        void this.io.close((error) => {
+          if (error) {
+            reject(error);
+          } else {
+            resolve();
+          }
+        });
+      });
+    }
+    await this.app.close();
+    this.logger.info("Server stopped");
+  }
+  /**
+   * 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
+   */
+  getPublicConfig(config) {
+    const { apis, ...publicConfig } = config;
+    return publicConfig;
+  }
+  /**
+   * 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
+   */
+  registerCoreApi() {
+    this.registerApi("dashfy", () => ({
+      inspector: async () => Promise.resolve({
+        apis: this.bus.listApis(),
+        clientCount: this.bus.clientCount(),
+        subscriptions: this.bus.getSubscriptionsInfo(),
+        uptime: process.uptime(),
+        version: process.env.npm_package_version ?? "unknown",
+        nodeVersion: process.version
+      })
+    }));
+  }
+};
+
+export { Dashfy };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map