api-ape 3.0.2 → 4.1.0

package/server/index.js

@@ -1,91 +1,342 @@
 /**
- * api-ape server entry point
- * 
- * V3 Usage:
- *   const api = require('api-ape')           // Get client proxy (default)
- *   const { ape } = require('api-ape')       // Get server/API function
- * 
- *   // ESM
- *   import api, { ape } from 'api-ape'
- * 
- * Server Setup:
- *   ape(server, { where: 'api' })            // First arg is HTTP server → setup
- * 
- * API Call:
- *   api.ape({ data: 'foo' })                 // Calls /ape endpoint
- *   // or equivalently:
- *   ape({ data: 'foo' })                     // Also calls /ape (detects it's not a server)
- * 
- * The ape function intelligently detects:
- *   - HTTP server (has .listen/.on) → Server setup mode
- *   - Anything else → API call to /ape
+ * @fileoverview api-ape Server Entry Point
+ *
+ * This is the main entry point for the api-ape framework. It provides a unified
+ * interface for both server setup and client API calls, with intelligent detection
+ * of the intended usage mode.
+ *
+ * ## Dual-Purpose Design
+ *
+ * The `ape` function serves two purposes:
+ * 1. **Server Setup**: When called with an HTTP server, it initializes WebSocket handling
+ * 2. **API Call**: When called with data, it makes an API call to the `/ape` endpoint
+ *
+ * This design allows the same import to be used for both server-side setup
+ * and making API calls from Node.js code.
+ *
+ * ## Usage Patterns
+ *
+ * ### CommonJS
+ * ```javascript
+ * const api = require('api-ape')           // Get client proxy (default export)
+ * const { ape } = require('api-ape')       // Get server/API function
+ *
+ * // Server setup (first arg is HTTP server)
+ * ape(httpServer, { where: 'api' })
+ *
+ * // API call (first arg is data)
+ * api.users({ action: 'list' })
+ * ```
+ *
+ * ### ES Modules
+ * ```javascript
+ * import api, { ape } from 'api-ape'
+ *
+ * // Same usage as CommonJS
+ * ```
+ *
+ * ## Server Detection
+ *
+ * The `ape` function detects HTTP servers by checking for:
+ * - `.listen()` method (http.Server)
+ * - `.on()` method (EventEmitter)
+ * - `.address()` method (bound server)
+ *
+ * If none of these are present, the call is treated as an API request.
+ *
+ * ## Exports
+ *
+ * | Export      | Type     | Description                              |
+ * |-------------|----------|------------------------------------------|
+ * | `default`   | Proxy    | Client API proxy for making calls        |
+ * | `ape`       | Function | Server setup or API call to /ape         |
+ * | `api`       | Proxy    | Same as default export                   |
+ * | `broadcast` | Function | Send message to all connected clients    |
+ * | `publish`   | Function | Send message to channel subscribers      |
+ * | `clients`   | Map      | Read-only map of connected clients       |
+ *
+ * @module server/index
+ * @see {@link module:server/lib/main} for server initialization
+ * @see {@link module:server/lib/broadcast} for broadcast functionality
+ * @see {@link module:server/client} for Node.js client API
+ *
+ * @example <caption>Basic Server Setup</caption>
+ * const http = require('http')
+ * const { ape } = require('api-ape')
+ *
+ * const server = http.createServer((req, res) => {
+ *   res.end('Hello World')
+ * })
+ *
+ * // Initialize api-ape with your API directory
+ * ape(server, { where: 'api' })
+ *
+ * server.listen(3000, () => {
+ *   console.log('Server running on port 3000')
+ * })
+ *
+ * @example <caption>Express Integration</caption>
+ * const express = require('express')
+ * const { ape } = require('api-ape')
+ *
+ * const app = express()
+ * const server = app.listen(3000)
+ *
+ * ape(server, {
+ *   where: 'api',
+ *   onConnect: (socket, req, send) => {
+ *     console.log('Client connected')
+ *     return {
+ *       embed: { userId: getUserId(req) },
+ *       onDisconnect: () => console.log('Client disconnected')
+ *     }
+ *   }
+ * })
+ *
+ * @example <caption>Broadcasting to Clients</caption>
+ * const { ape, broadcast, clients } = require('api-ape')
+ *
+ * // Broadcast to all connected clients
+ * broadcast('notification', { message: 'Server update!' })
+ *
+ * // Broadcast to all except sender
+ * broadcast('chat', { text: 'Hello' }, excludeClientId)
+ *
+ * // Check connected clients
+ * console.log(`${clients.size} clients connected`)
+ *
+ * @example <caption>Making API Calls from Node.js</caption>
+ * const api = require('api-ape')
+ *
+ * // Configure connection (if not on same server)
+ * api.connect('localhost', 3000)
+ *
+ * // Make API calls
+ * const users = await api.users.list()
+ * const result = await api.chat({ message: 'Hello!' })
  */
 
-const serverApe = require('./lib/main')
-const { broadcast, clients } = require('./lib/broadcast')
-const api = require('./client')
-const { _queueOrSend } = require('./client')
+const serverApe = require("./lib/main");
+const { clients, publish } = require("./lib/broadcast");
+const createPublishProxy = require("./lib/broadcast/publishProxy");
+const api = require("./client");
+const { _queueOrSend } = require("./client");
 
-// Attach broadcast utilities to the serverApe function
-serverApe.broadcast = broadcast
-serverApe.clients = clients
+/**
+ * Chained publish proxy for fluent syntax
+ * @type {Proxy}
+ * @private
+ */
+const publishProxy = createPublishProxy();
 
 /**
- * Check if value looks like an HTTP server
+ * Attach pub/sub utilities to the serverApe function for convenience access
+ *
+ * This allows users to access pub/sub functionality directly from the
+ * server setup function: `ape.publish.channel(data)`
+ *
+ * @private
+ */
+serverApe.clients = clients;
+serverApe.publish = publishProxy;
+
+/**
+ * Check if a value looks like an HTTP server instance
+ *
+ * Detects HTTP servers by checking for common server methods.
+ * This heuristic works for:
+ * - Node.js http.Server
+ * - Express app.listen() result
+ * - Koa server
+ * - Fastify server
+ * - Bun.serve() result
+ *
+ * @param {any} val - Value to check
+ * @returns {boolean} True if the value appears to be an HTTP server
+ * @private
+ *
+ * @example
+ * isHttpServer(http.createServer())     // true
+ * isHttpServer(app.listen(3000))        // true (Express)
+ * isHttpServer({ data: 'payload' })     // false
+ * isHttpServer(null)                    // false
  */
 function isHttpServer(val) {
-    return val && typeof val === 'object' && (
-        typeof val.listen === 'function' ||
-        typeof val.on === 'function' ||
-        typeof val.address === 'function'
-    )
+  return (
+    val &&
+    typeof val === "object" &&
+    (typeof val.listen === "function" ||
+      typeof val.on === "function" ||
+      typeof val.address === "function")
+  );
 }
 
 /**
- * Dual-purpose ape function:
- * - Called with HTTP server → Setup server
- * - Called with anything else → API call to /ape
+ * Dual-purpose ape function for server setup or API calls
+ *
+ * This function intelligently detects its intended use:
+ *
+ * ## Server Setup Mode
+ * When the first argument is an HTTP server, initializes api-ape:
+ * - Sets up WebSocket handling on the server
+ * - Loads controllers from the specified directory
+ * - Configures connection lifecycle callbacks
+ * - Enables file transfer handling
+ *
+ * ## API Call Mode
+ * When the first argument is not a server, makes an API call:
+ * - Sends the data to the `/ape` endpoint
+ * - Returns a Promise that resolves with the response
+ *
+ * @param {http.Server|Object|any} firstArg - HTTP server for setup, or data for API call
+ * @param {...any} rest - Additional arguments (options for server setup)
+ * @returns {Object|Promise<any>} Server info object (setup mode) or response Promise (API mode)
+ *
+ * @example <caption>Server Setup</caption>
+ * const server = http.createServer()
+ *
+ * ape(server, {
+ *   where: 'api',                    // Directory containing API controllers
+ *   onConnect: (socket, req, send) => ({
+ *     embed: { userId: '123' },      // Values available in all controllers
+ *     onReceive: (queryId, data, type) => { },
+ *     onSend: (data, type) => { },
+ *     onError: (errString) => { },
+ *     onDisconnect: () => { }
+ *   }),
+ *   fileTransferOptions: {
+ *     startTimeout: 60000,           // Timeout before upload starts
+ *     completeTimeout: 60000         // Timeout for upload completion
+ *   }
+ * })
+ *
+ * @example <caption>API Call</caption>
+ * // Calls the /ape endpoint with the provided data
+ * const result = await ape({ action: 'ping' })
  */
 function ape(firstArg, ...rest) {
-    if (isHttpServer(firstArg)) {
-        // Server setup mode
-        return serverApe(firstArg, ...rest)
-    }
-    // API call mode - directly call the internal queueOrSend
-    return _queueOrSend('/ape', firstArg)
+  if (isHttpServer(firstArg)) {
+    // Server setup mode
+    return serverApe(firstArg, ...rest);
+  }
+  // API call mode - directly call the internal queueOrSend
+  return _queueOrSend("/ape", firstArg);
 }
 
-// Copy properties from serverApe to ape
-ape.broadcast = broadcast
-ape.clients = clients
-
-// Store original serverApe for direct access if needed
-ape._serverApe = serverApe
-
-// Define ape on the proxy's target so it can be destructured
-// The proxy handler checks Reflect.has first, so this will be found
-Object.defineProperty(api, 'ape', {
-    value: ape,
-    writable: false,
-    enumerable: true,
-    configurable: false
-})
-
-// Default export: the proxy (so const api = require('api-ape') works)
-module.exports = api
-
-// Also export named exports for ESM compatibility
-module.exports.ape = ape
-module.exports.api = api
-module.exports.broadcast = broadcast
-module.exports.clients = clients
-module.exports.default = api
-
-
-
-
+/**
+ * Publish a message to all subscribers of a channel
+ *
+ * Supports both chained syntax and direct function call:
+ *
+ * @example
+ * // Chained syntax (v2)
+ * ape.publish.news.banking({ headline: 'Market Update' })
+ * ape.publish.health({ status: 'ok', uptime: process.uptime() })
+ *
+ * // Direct call (legacy, still supported)
+ * ape.publish('/health', { status: 'ok', uptime: process.uptime() })
+ *
+ * // Clients subscribed to '/health' will receive:
+ * // { type: '/health', data: { status: 'ok', uptime: 12345 } }
+ */
+ape.publish = publishProxy;
 
+/**
+ * Read-only Map of connected clients
+ *
+ * Provides access to all currently connected clients. Each client entry
+ * includes methods for sending messages and accessing client metadata.
+ *
+ * The Map is read-only - attempts to modify it will throw an error.
+ * Client connections are managed internally by api-ape.
+ *
+ * @type {Map<string, ClientWrapper>}
+ *
+ * @property {number} size - Number of connected clients
+ *
+ * @example
+ * // Check number of connected clients
+ * console.log(`${ape.clients.size} clients online`)
+ *
+ * // Iterate over clients
+ * ape.clients.forEach((client, clientId) => {
+ *   console.log(`Client ${clientId}: ${client.agent.browser?.name}`)
+ * })
+ *
+ * // Send to specific client
+ * const client = ape.clients.get(clientId)
+ * if (client) {
+ *   client.send('notification', { message: 'Hello!' })
+ * }
+ *
+ * // Access client properties
+ * for (const client of ape.clients.values()) {
+ *   console.log({
+ *     clientId: client.clientId,
+ *     sessionId: client.sessionId,
+ *     embed: client.embed,
+ *     agent: client.agent
+ *   })
+ * }
+ */
+ape.clients = clients;
 
+/**
+ * Store reference to original serverApe for direct access if needed
+ *
+ * This is primarily for internal use or advanced scenarios where
+ * direct access to the server initialization function is required.
+ *
+ * @type {Function}
+ * @private
+ */
+ape._serverApe = serverApe;
 
+/**
+ * Define ape on the proxy's target so it can be destructured
+ *
+ * The proxy handler checks Reflect.has first, so this property
+ * will be found when destructuring: `const { ape } = require('api-ape')`
+ *
+ * @private
+ */
+Object.defineProperty(api, "ape", {
+  value: ape,
+  writable: false,
+  enumerable: true,
+  configurable: false,
+});
 
+/**
+ * Default export: the client API proxy
+ *
+ * This allows the common pattern: `const api = require('api-ape')`
+ * The proxy intercepts property access to build API endpoint paths.
+ *
+ * @type {Proxy}
+ *
+ * @example
+ * const api = require('api-ape')
+ *
+ * // These are equivalent:
+ * api.users({ action: 'list' })     // Calls /users
+ * api.users.profile({ id: 1 })      // Calls /users/profile
+ * api.chat('/room1', { msg: 'Hi' }) // Calls /chat/room1
+ */
+module.exports = api;
 
+/**
+ * Named exports for ES Module compatibility and destructuring
+ *
+ * @example
+ * // CommonJS destructuring
+ * const { ape, clients } = require('api-ape')
+ *
+ * // ES Modules
+ * import api, { ape, clients } from 'api-ape'
+ */
+module.exports.ape = ape;
+module.exports.api = api;
+module.exports.publish = publishProxy;
+module.exports.clients = clients;
+module.exports.default = api;

package/server/lib/README.md

@@ -0,0 +1,26 @@
+# Server Lib Module
+
+## Overview
+
+The lib module is the core implementation of api-ape's server functionality. It orchestrates everything needed to transform a standard HTTP server into a real-time WebSocket API server with automatic controller routing, client management, and message handling.
+
+**Key capabilities:**
+
+- **Server initialization** — Detect runtime (Node.js, Bun, Deno) and configure appropriate handlers
+- **Controller loading** — Recursively load JavaScript files from a folder and map them to API endpoints
+- **WebSocket management** — Handle connections, message routing, and client lifecycle
+- **Client tracking** — Maintain registry of connected clients with broadcast and pub/sub capabilities
+- **HTTP fallback** — Provide long-polling transport when WebSocket is unavailable
+- **File transfers** — Manage binary upload/download with streaming support
+- **Runtime abstraction** — Unified API across Node.js, Bun, and Deno
+
+This module is the engine that powers the "drop a file, get an endpoint" developer experience.
+
+> **Contributing?** See [`files.md`](./files.md) for directory structure and file descriptions.
+
+## See Also
+
+- [`../README.md`](../README.md) — Server overview and API reference
+- [`runtimes/README.md`](./runtimes/README.md) — Runtime-specific integrations
+- [`ws/README.md`](./ws/README.md) — WebSocket polyfill documentation
+- [`longPolling/README.md`](./longPolling/README.md) — HTTP fallback handlers

package/server/lib/broadcast/clients.js

@@ -0,0 +1,219 @@
+/**
+ * @fileoverview Client Tracking for api-ape Server
+ *
+ * Manages connected WebSocket clients with a read-only proxy for external access.
+ *
+ * @module server/lib/broadcast/clients
+ * @see {@link module:server/lib/broadcast} for the main broadcast module
+ */
+
+const createSendProxy = require("./sendProxy");
+
+/**
+ * Internal Map of connected clients
+ * @type {Map<string, ClientWrapper>}
+ * @private
+ */
+const _clients = new Map();
+
+/**
+ * Create a ClientWrapper that exposes client info and send function
+ *
+ * @param {Object} clientInfo - Raw client info from wiring/longPolling
+ * @returns {Object} Public client interface
+ * @private
+ */
+function createClientWrapper(clientInfo) {
+  return {
+    get clientId() {
+      return clientInfo.clientId;
+    },
+    get sessionId() {
+      return clientInfo.sessionId || null;
+    },
+    get embed() {
+      return clientInfo.embed || {};
+    },
+    get agent() {
+      return clientInfo.agent || {};
+    },
+    /**
+     * Get current auth state for this client
+     * @returns {Object|null} Auth state or null if not tracked
+     */
+    get authState() {
+      if (clientInfo.socketAuth) {
+        return clientInfo.socketAuth.getState();
+      }
+      return null;
+    },
+    /**
+     * Check if client is authenticated
+     * @returns {boolean} Whether client is authenticated
+     */
+    get isAuthenticated() {
+      if (clientInfo.socketAuth) {
+        return clientInfo.socketAuth.isAuthenticated();
+      }
+      return false;
+    },
+    /**
+     * Get auth tier for this client
+     * @returns {number} Auth tier (0-3)
+     */
+    get authTier() {
+      if (clientInfo.socketAuth) {
+        return clientInfo.socketAuth.getTier();
+      }
+      return 0;
+    },
+    /**
+     * Send a message to this client
+     *
+     * Supports both direct and chained syntax:
+     * - client.send('news/banking', data)
+     * - client.send.news.banking(data)
+     *
+     * @type {Function & Proxy}
+     */
+    send: createSendProxy((type, data) => {
+      if (clientInfo.send) {
+        try {
+          clientInfo.send(false, type, data, false);
+        } catch (e) {
+          /* istanbul ignore next */
+          console.error(
+            `📢 send failed for ${clientInfo.clientId}:`,
+            e.message,
+          );
+        }
+      }
+    }),
+  };
+}
+
+/**
+ * Read-only proxy for the clients Map
+ *
+ * Allows read operations but blocks modifications.
+ * @type {Map<string, ClientWrapper>}
+ */
+const clients = new Proxy(_clients, {
+  /**
+   * Proxy get handler - intercepts property access
+   * @param {Map} target - The underlying clients Map
+   * @param {string|symbol} prop - Property being accessed
+   * @returns {any} The property value or bound method
+   */
+  get(target, prop) {
+    if (prop === "set" || prop === "delete" || prop === "clear") {
+      return () => {
+        throw new Error(
+          `ape.clients.${prop}() is not allowed. Clients are managed internally by api-ape.`,
+        );
+      };
+    }
+    if (prop === "size") {
+      return target.size;
+    }
+    const value = target[prop];
+    if (typeof value === "function") {
+      return value.bind(target);
+    }
+    /* istanbul ignore next */
+    return value;
+  },
+});
+
+/**
+ * Add a client to the connected clients map
+ *
+ * @param {Object} clientInfo - Client information object
+ * @param {Function} [onAdd] - Optional callback after adding
+ * @private
+ */
+function addClient(clientInfo, onAdd) {
+  const wrapper = createClientWrapper(clientInfo);
+  _clients.set(clientInfo.clientId, wrapper);
+  wrapper._raw = clientInfo;
+  console.log(
+    `🟢 Client added: ${clientInfo.clientId} (total: ${_clients.size})`,
+  );
+  if (onAdd) onAdd(clientInfo.clientId);
+}
+
+/**
+ * Remove a client from the connected clients map
+ *
+ * @param {string|Object} clientIdOrInfo - Client ID or info object with clientId
+ * @param {Function} [onRemove] - Optional cleanup callback (receives clientId)
+ * @private
+ */
+function removeClient(clientIdOrInfo, onRemove) {
+  const clientId =
+    typeof clientIdOrInfo === "string"
+      ? clientIdOrInfo
+      : clientIdOrInfo.clientId;
+
+  if (_clients.has(clientId)) {
+    _clients.delete(clientId);
+    if (onRemove) onRemove(clientId);
+    console.log(`🔴 Client removed: ${clientId} (total: ${_clients.size})`);
+  } else {
+    console.log(
+      `⚠️ Client not found for removal: ${clientId} (total: ${_clients.size})`,
+    );
+  }
+}
+
+/**
+ * Update a client's embed values after onConnect resolves
+ *
+ * @param {string} clientId - The client's unique identifier
+ * @param {Object} embed - The embed values from onConnect
+ * @private
+ */
+function updateClientEmbed(clientId, embed) {
+  const wrapper = _clients.get(clientId);
+  if (wrapper && wrapper._raw) {
+    wrapper._raw.embed = embed;
+  }
+}
+
+/**
+ * Update a client's send function after it's ready
+ *
+ * @param {string} clientId - The client's unique identifier
+ * @param {Function} send - The send function for this client
+ * @private
+ */
+function updateClientSend(clientId, send) {
+  const wrapper = _clients.get(clientId);
+  if (wrapper && wrapper._raw) {
+    wrapper._raw.send = send;
+  }
+}
+
+/**
+ * Update a client's auth state manager
+ *
+ * @param {string} clientId - The client's unique identifier
+ * @param {Object} socketAuth - Socket auth manager instance
+ * @private
+ */
+function updateClientAuth(clientId, socketAuth) {
+  const wrapper = _clients.get(clientId);
+  if (wrapper && wrapper._raw) {
+    wrapper._raw.socketAuth = socketAuth;
+  }
+}
+
+module.exports = {
+  clients,
+  _clients,
+  addClient,
+  removeClient,
+  updateClientEmbed,
+  updateClientSend,
+  updateClientAuth,
+};