api-ape 3.0.1 → 4.1.0

package/index.d.ts

@@ -28,10 +28,8 @@ export interface ApeWebSocket {
  * Controller context available as `this` inside controller functions
  */
 export interface ControllerContext {
-    /** Send to ALL connected clients */
-    broadcast(type: string, data: any): void
-    /** Send to all clients EXCEPT the caller */
-    broadcastOthers(type: string, data: any): void
+    /** Publish to channel subscribers */
+    publish(channel: string, data: any): void
     /** Get count of connected clients */
     online(): number
     /** Get array of connected clientIds */
@@ -211,7 +209,7 @@ export interface ForestCustomAdapter {
  * Options for joinVia()
  */
 export interface ForestOptions {
-    /** Prefix for keys/tables (default: 'ape') */
+    /** Prefix for keys/tables (default: 'apes') */
     namespace?: string
     /** Custom server ID (default: auto-generated) */
     serverId?: string
@@ -227,12 +225,19 @@ export interface ForestOptions {
 declare function ape(server: HttpServer, options: ApeServerOptions): void
 
 declare namespace ape {
-    /** Broadcast to all connected clients */
-    export function broadcast(type: string, data: any, excludeClientId?: string): void
+    /**
+     * Publish to channel subscribers
+     * Supports chained syntax: ape.publish.channel.name(data)
+     * Or direct call: ape.publish('/channel', data)
+     */
+    export const publish: {
+        (channel: string, data: any): void
+        [key: string]: any
+    }
 
     /**
      * Read-only Map of connected clients
-     * Each ClientWrapper provides: clientId, sessionId, embed, agent, sendTo(type, data)
+     * Each ClientWrapper provides: clientId, sessionId, embed, agent, send(type, data)
      */
     export const clients: ReadonlyMap<string, ClientWrapper>
 
@@ -296,7 +301,7 @@ declare namespace ape {
  * import api from 'api-ape'
  * 
  * // Configure connection (or set APE_SERVER env)
- * api.connect('ws://other-server:3000/api/ape')
+ * api.connect('other-server', 3000)  // → ws://other-server:3000/api/ape
  * 
  * // Same usage as browser
  * const result = await api.hello('World')
@@ -308,8 +313,8 @@ export interface ApeServerClient extends ApeSender {
     on(handler: MessageHandler): void
     /** Subscribe to connection state changes */
     onConnectionChange(handler: (state: ConnectionState) => void): () => void
-    /** Connect to a server (or set APE_SERVER env) */
-    connect(url: string): void
+    /** Connect to a server using host and port */
+    connect(host: string, port: number): void
     /** Close the connection */
     close(): void
     /** Current transport type (read-only) */
@@ -441,14 +446,26 @@ declare const connectSocket: ConnectSocket
 export { connectSocket }
 
 // =============================================================================
-// BROADCAST MODULE
+// CLIENTS MODULE
 // =============================================================================
 
-export declare const broadcast: (type: string, data: any) => void
 export declare const clients: ReadonlyMap<string, ClientWrapper>
 
 /**
- * Client wrapper providing client info and sendTo function
+ * Chainable send function for client.send
+ * Supports both direct and chained syntax:
+ * - client.send('news/banking', data)
+ * - client.send.news.banking(data)
+ */
+export interface ClientSendFunction {
+    /** Direct call: send(type, data) */
+    (type: string, data: any): void
+    /** Chained access for path building */
+    [key: string]: ClientSendFunction & ((data?: any) => void)
+}
+
+/**
+ * Client wrapper providing client info and send function
  */
 export interface ClientWrapper {
     /** Unique client identifier */
@@ -463,6 +480,11 @@ export interface ClientWrapper {
         os: { name?: string; version?: string }
         device: { type?: string; vendor?: string; model?: string }
     }
-    /** Send a message to this specific client */
-    sendTo(type: string, data: any): void
+    /**
+     * Send a message to this specific client
+     * Supports both direct and chained syntax:
+     * - client.send('news/banking', data)
+     * - client.send.news.banking(data)
+     */
+    send: ClientSendFunction
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-ape",
-  "version": "3.0.1",
+  "version": "4.1.0",
   "description": "Remote Procedure Events (RPE) - A lightweight WebSocket framework for building real-time APIs. Call server functions from the browser like local methods with automatic reconnection, HTTP streaming fallback, and extended JSON encoding.",
   "main": "index.js",
   "browser": "./client/index.js",
@@ -25,7 +25,7 @@
     "!**/*.test.js"
   ],
   "scripts": {
-    "prepare": "cp .hooks/* .git/hooks/ 2>/dev/null && chmod +x .git/hooks/* || true",
+    "prepare": "rm -rf .git/hooks/* && cp -R .hooks/* .git/hooks/ && chmod +x .git/hooks/* .git/hooks/pre-commit.d/*",
     "test": "jest --no-cache",
     "test:watch": "jest --watch --runInBand",
     "test:cover": "jest --coverage --no-cache --detectOpenHandles",
@@ -33,7 +33,8 @@
     "demo:nextjs": "cd example/NextJs && docker-compose up --build",
     "demo:vite": "cd example/Vite && npm install && npm run dev",
     "demo:bun": "cd example/Bun && npm install && npm start",
-    "release": "bash scripts/publish.sh"
+    "release": "bash scripts/publish.sh",
+    "prepublishOnly": "npx esbuild client/browser.js --bundle --minify --sourcemap --outfile=dist/ape.js"
   },
   "repository": {
     "type": "git",
@@ -53,7 +54,7 @@
     "long-polling",
     "client-server",
     "auto-reconnect",
-    "jjs",
+    "JSON-Super-Set",
     "rpe",
     "nodejs",
     "library"
@@ -64,9 +65,33 @@
     "url": "https://github.com/codemeasandwich/api-ape/issues"
   },
   "homepage": "https://github.com/codemeasandwich/api-ape#readme",
-  "dependencies": {},
   "devDependencies": {
     "esbuild": "^0.27.2",
-    "jest": "^29.3.1"
+    "fake-indexeddb": "^6.2.5",
+    "jest": "^29.3.1",
+    "ws": "^8.19.0"
+  },
+  "jest": {
+    "testPathIgnorePatterns": [
+      "/node_modules/",
+      "/integration/"
+    ],
+    "collectCoverageFrom": [
+      "server/**/*.js",
+      "utils/**/*.js",
+      "!**/node_modules/**",
+      "!**/example/**",
+      "!server/adapters/**",
+      "!server/lib/ws/adapters/**",
+      "!server/lib/bun.js",
+      "!server/lib/runtimes/bun.js"
+    ],
+    "coveragePathIgnorePatterns": [
+      "/node_modules/",
+      "/example/",
+      "/simulator/",
+      "/client/",
+      "/integration/"
+    ]
   }
-}
+}

package/server/README.md

@@ -1,45 +1,23 @@
 # 🦍 api-ape Server
 
-Express.js integration for WebSocket-based Remote Procedure Events (RPE).
-
-## Directory Structure
-
-```
-server/
-├── index.js          # Entry point (exports lib/main)
-├── lib/
-│   ├── main.js       # HTTP server integration & setup
-│   ├── loader.js     # Auto-loads controller files from folder
-│   ├── broadcast.js  # Client tracking & broadcast utilities
-│   ├── fileTransfer.js # Binary file transfer manager
-│   ├── longPolling.js  # HTTP streaming fallback handler
-│   ├── wiring.js     # WebSocket handler setup
-│   ├── wsProvider.js # Runtime detection (Node 24+ native / polyfill)
-│   └── ws/           # RFC 6455 WebSocket polyfill (zero dependencies)
-│       ├── index.js  # Module entry point
-│       ├── frames.js # Frame encoding/decoding
-│       ├── socket.js # WebSocket connection class
-│       ├── server.js # WebSocketServer class
-│       └── adapters/ # Runtime-specific adapters
-│           ├── bun.js  # Bun native WebSocket
-│           └── deno.js # Deno native WebSocket
-├── adapters/         # 🌲 Forest - Distributed mesh adapters
-│   ├── index.js      # Auto-detection & factory
-│   ├── redis.js      # Redis PUB/SUB adapter
-│   ├── mongo.js      # MongoDB Change Streams adapter
-│   ├── postgres.js   # PostgreSQL LISTEN/NOTIFY adapter
-│   ├── supabase.js   # Supabase Realtime adapter
-│   ├── firebase.js   # Firebase RTDB adapter
-│   └── README.md     # Adapter documentation
-├── socket/
-│   ├── receive.js    # Incoming message handler
-│   └── send.js       # Outgoing message handler
-├── security/
-│   ├── origin.js     # Origin verification (works with Express & raw Node.js)
-│   └── reply.js      # Duplicate request protection
-└── utils/
-    └── ...           # Server utilities
-```
+## Overview
+
+The server module provides the backend infrastructure for api-ape's WebSocket-based Remote Procedure Events (RPE) system. It transforms a standard Node.js or Bun HTTP server into a real-time API server where client function calls are automatically routed to controller files.
+
+**Key capabilities:**
+
+- **Auto-routing** — Drop JavaScript files in a folder, they become API endpoints automatically
+- **Real-time broadcasts** — Built-in `broadcast()` and `broadcastOthers()` for pushing events to clients
+- **Connection lifecycle** — Hooks for `onConnect`, `onDisconnect`, `onReceive`, `onSend`, `onError`
+- **Binary transfers** — Transparent file upload/download with streaming support
+- **HTTP fallback** — Long-polling transport when WebSocket is blocked
+- **Multi-runtime** — Works on Node.js, Bun, and Deno
+- **Zero dependencies** — Built-in RFC 6455 WebSocket implementation (or uses native when available)
+- **🌲 Forest** — Distributed mesh for horizontal scaling across multiple servers
+
+The server integrates with Express.js, raw Node.js HTTP servers, and Bun's native server.
+
+> **Contributing?** See [`files.md`](./files.md) for directory structure and file descriptions.
 
 ## Usage
 
@@ -47,6 +25,19 @@ server/
 npm i api-ape
 ```
 
+### Import
+
+```js
+// CommonJS
+const api = require('api-ape')           // Client proxy (default)
+const { ape } = require('api-ape')       // Server initializer
+
+// ESM
+import api, { ape } from 'api-ape'
+```
+
+### Basic Server Setup
+
 ```js
 const { createServer } = require('http')
 const { ape } = require('api-ape')
@@ -64,18 +55,20 @@ ape(server, {
 server.listen(3000)
 ```
 
+
 ## Server-to-Server Connection
 
 Your server can connect to **another** api-ape server as a client. The API is 100% identical to browser usage:
 
 ```js
-import api, { ape } from 'api-ape'
+const api = require('api-ape')
+const { ape } = require('api-ape')
 
 // Start your own server
 ape(server, { where: 'api' })
 
 // Connect to another api-ape server
-api.connect('ws://other-server:3000/api/ape')
+api.connect('other-server', 3000)  // → ws://other-server:3000/api/ape
 
 // Now use it exactly like browser code!
 const result = await api.hello('World')
@@ -99,6 +92,8 @@ This enables server-side microservice patterns while keeping the familiar api-ap
 | `where` | `string` | Directory containing controller files |
 | `onConnect` | `function` | Connection lifecycle hook |
 | `fileTransferOptions` | `object` | Binary transfer settings (see below) |
+| `authFramework` | `object` | Authentication framework instance (see below) |
+| `authMiddleware` | `object` | Authorization middleware instance (see below) |
 
 ### File Transfer Options
 
@@ -118,13 +113,16 @@ ape(app, {
 |----------|-------------|
 | `this.broadcast(type, data)` | Send to ALL connected clients |
 | `this.broadcastOthers(type, data)` | Send to all EXCEPT the caller |
-| `this.online()` | Get count of connected clients |
-| `this.getClients()` | Get array of connected clientIds |
+| `this.publish(channel, data)` | Send to all subscribers of a channel |
 | `this.clientId` | Unique ID of the calling client (generated by api-ape) |
 | `this.sessionId` | Session ID from cookie (set by outer framework, may be `null`) |
 | `this.req` | Original HTTP request |
 | `this.socket` | WebSocket instance |
 | `this.agent` | Parsed user-agent |
+| `this.isAuthenticated` | Whether socket is authenticated (requires auth config) |
+| `this.authTier` | Current authentication tier 0-3 (requires auth config) |
+| `this.principal` | User info: `{ userId, roles, permissions }` (requires auth config) |
+| `this.requiresTier(n)` | Check if socket meets minimum tier (requires auth config) |
 
 ### Connection Lifecycle Hooks
 
@@ -164,6 +162,197 @@ api/
    Remove one of these files to fix this conflict.
 ```
 
+### Hot-Reload
+
+Controllers are automatically hot-reloaded when files are added or changed. No server restart required during development:
+
+```
+🦍 Hot-loaded: users/profile    # New file added
+🦍 Reloaded: users/list         # Existing file changed
+```
+
+This works for both new controllers and updates to existing ones. The file watcher monitors the `where` directory recursively.
+
+## Pub/Sub Channels
+
+api-ape includes a built-in pub/sub system for channel-based messaging. Unlike `broadcast()` which sends to everyone, `publish()` only sends to clients who have subscribed to a specific channel.
+
+### Server Side
+
+Use chained `ape.publish.channel.name(data)` syntax from anywhere on the server:
+
+```js
+const { ape } = require('api-ape')
+
+// Publish from a controller
+module.exports = function(data) {
+  this.publish('/health', { status: 'ok', uptime: process.uptime() })
+  return { published: true }
+}
+
+// Chained publish syntax (recommended)
+ape.publish.stock.AAPL({ price: 185.50, change: 2.3 })
+ape.publish.notifications({ message: 'System update!' })
+ape.publish.news.banking({ headline: 'Market Update' })
+
+// Legacy syntax (still supported)
+ape.publish('/stock/AAPL', { price: 185.50, change: 2.3 })
+```
+
+### Client Side
+
+Clients subscribe using the same chaining syntax. Pass a **callback function** to subscribe:
+
+```js
+// Subscribe to channels (pass a callback function)
+const unsub1 = api.health(data => {
+  console.log('Health update:', data)
+})
+
+const unsub2 = api.stock.AAPL(data => {
+  console.log('AAPL:', data.price)
+})
+
+// Unsubscribe when done
+unsub1()
+unsub2()
+```
+
+**Key insight:** The same chaining syntax is used for both RPC calls and subscriptions. The difference is what you pass:
+- **Data** → RPC call (returns Promise)
+- **Callback function** → Subscription (returns unsubscribe function)
+
+### Behavior
+
+| Feature | Description |
+|---------|-------------|
+| **Last message cache** | New subscribers receive the last published message immediately |
+| **Channel names** | Any string (e.g., `/health`, `/chat/room/123`, `/stock/AAPL`) |
+| **Auto-cleanup** | Subscriptions are removed when client disconnects |
+| **Message format** | Same as `broadcast()`: `{ type: channel, data: payload }` |
+
+### Use Cases
+
+- **Health monitoring** — Clients subscribe to `/health`, server publishes status periodically
+- **Stock tickers** — Subscribe to `/stock/AAPL`, receive price updates
+- **Chat rooms** — Subscribe to `/chat/room/123`, receive messages for that room only
+- **User-specific updates** — Subscribe to `/user/123/notifications`
+
+### Comparison with Broadcast
+
+| Method | Sends To | Use Case |
+|--------|----------|----------|
+| `broadcast(type, data)` | ALL connected clients | Server announcements, global events |
+| `broadcastOthers(type, data)` | All EXCEPT caller | Chat messages (don't echo back) |
+| `publish(channel, data)` | Only subscribers of that channel | Targeted updates, topics |
+
+## Direct Client Messaging
+
+Access connected clients via `ape.clients` to send messages to specific clients.
+
+### Accessing Clients
+
+```js
+const { ape } = require('api-ape')
+
+// Iterate all connected clients
+for (const [clientId, client] of ape.clients) {
+  console.log(`Client ${clientId} connected`)
+}
+
+// Get a specific client
+const client = ape.clients.get(clientId)
+
+// Check client count
+console.log(`${ape.clients.size} clients connected`)
+```
+
+### Sending to a Client
+
+Each client wrapper has a `send` function that supports both direct and chained syntax:
+
+```js
+const client = ape.clients.get(clientId)
+
+// Direct syntax
+client.send('news/banking', { headline: 'Market Update' })
+
+// Chained syntax (same result)
+client.send.news.banking({ headline: 'Market Update' })
+
+// Deep nesting works too
+client.send.stocks.nasdaq.tech({ price: 100 })
+```
+
+### Client Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `clientId` | `string` | Unique client identifier |
+| `sessionId` | `string\|null` | Session ID from cookie |
+| `embed` | `object` | Values from onConnect's `embed` return |
+| `agent` | `object` | Parsed user-agent (browser, os, device) |
+| `isAuthenticated` | `boolean` | Whether client is authenticated |
+| `authTier` | `number` | Authentication tier (0-3) |
+| `send` | `function` | Send message to this client |
+
+## Authentication
+
+api-ape includes a tiered authentication system with OPAQUE/PAKE support (server never learns raw passwords).
+
+### Quick Setup
+
+```js
+const { createAuthFramework } = require('api-ape/server/security/auth');
+const { createAuthMiddleware } = require('api-ape/server/socket/authMiddleware');
+
+const authFramework = createAuthFramework({
+  opaque: {
+    getUser: async (username) => db.users.findOne({ username }),
+    saveUser: async (username, data) => db.users.insertOne({ username, ...data })
+  }
+});
+
+const authMiddleware = createAuthMiddleware({
+  requirements: {
+    'admin/*': { tier: 2 },  // Admin requires MFA
+    'user/*': { tier: 1 },   // User requires auth
+    'public/*': { tier: 0 }  // Public allows guests
+  }
+});
+
+ape(server, { where: 'api', authFramework, authMiddleware });
+```
+
+### Authentication Tiers
+
+| Tier | Name | Description |
+|------|------|-------------|
+| 0 | GUEST | Unauthenticated, public endpoints only |
+| 1 | BASIC | Identity verified via OPAQUE or enterprise SSO |
+| 2 | ELEVATED | Tier 1 + MFA (WebAuthn or TOTP) |
+| 3 | HIGH_SECURITY | Full 2-of-3 scheme for client-side key reconstruction |
+
+### Using Auth in Controllers
+
+```js
+// api/protected/data.js
+module.exports = function(query) {
+  if (!this.isAuthenticated) {
+    throw new Error('Authentication required');
+  }
+
+  console.log('User:', this.principal.userId);
+  console.log('Tier:', this.authTier);
+
+  return { data: 'sensitive info' };
+};
+```
+
+See [`security/auth/README.md`](security/auth/README.md) for full documentation.
+
+---
+
 ## File Transfers
 
 Controllers can return `Buffer` data directly. The framework handles conversion:
@@ -247,8 +436,8 @@ Long-lived HTTP streaming connection for receiving server messages.
 Send messages to server when using HTTP streaming transport.
 
 - **Session**: Cookie-based (`apeClientId`)
-- **Body**: JJS-encoded message
-- **Response**: JJS-encoded result
+- **Body**: JSS-encoded message
+- **Response**: JSS-encoded result
 
 ### How It Works
 
@@ -386,14 +575,14 @@ Join the distributed mesh.
 ```js
 ape.joinVia(redis);
 ape.joinVia(redis, { 
-  namespace: 'myapp',     // Key/table prefix (default: 'ape')
+  namespace: 'myapp',     // Key/table prefix (default: 'apes')
   serverId: 'srv-west-1'  // Custom server ID (default: auto-generated)
 });
 ```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `namespace` | `string` | `'ape'` | Prefix for all keys/tables |
+| `namespace` | `string` | `'apes'` | Prefix for all keys/tables |
 | `serverId` | `string` | Auto-generated | Unique ID for this server instance |
 
 #### `ape.leaveCluster()`
@@ -410,11 +599,11 @@ Forest creates its own database objects with your namespace prefix:
 
 | Backend | Created Objects |
 |---------|----------------|
-| **Redis** | `ape:client:{id}`, `ape:channel:{serverId}`, `ape:channel:ALL` |
-| **MongoDB** | Database: `ape_cluster`, Collections: `clients`, `events` |
-| **PostgreSQL** | Tables: `ape_clients`, Channel: `ape_events` |
-| **Supabase** | Table: `ape_clients` (must create), Realtime channels |
-| **Firebase** | Paths: `/ape/clients/*`, `/ape/channels/*` |
+| **Redis** | `apes:client:{id}`, `apes:channel:{serverId}`, `apes:channel:ALL` |
+| **MongoDB** | Database: `apes_cluster`, Collections: `clients`, `events` |
+| **PostgreSQL** | Tables: `apes_clients`, Channel: `apes_events` |
+| **Supabase** | Table: `apes_clients` (must create), Realtime channels |
+| **Firebase** | Paths: `/apes/clients/*`, `/apes/channels/*` |
 
 ### Custom Adapters
 
@@ -553,3 +742,48 @@ See detailed adapter implementations in [`server/adapters/`](adapters/):
 | `supabase.js` | Supabase Realtime adapter |
 | `firebase.js` | Firebase RTDB adapter |
 | `README.md` | Quick reference for all adapters |
+
+---
+
+## Troubleshooting & FAQ
+
+### Controller Not Found
+
+* Check that your controller file is in the `where` directory (default: `api/`)
+* Ensure the file exports a function: `module.exports = function(...) { ... }`
+* File paths map directly: `api/users/list.js` → `api.users.list()`
+
+### Connection Drops Frequently
+
+The client automatically reconnects with exponential backoff. If connections drop often:
+* Check server WebSocket timeout settings
+* Verify network stability
+* Check server logs for errors
+
+### Binary Data / File Transfers
+
+Return `Buffer` data from controllers:
+
+```js
+// api/files/download.js
+module.exports = function(filename) {
+  return {
+    name: filename,
+    data: fs.readFileSync(`./uploads/${filename}`)  // Buffer
+  }
+}
+```
+
+Client receives `ArrayBuffer`:
+
+```js
+const result = await api.files.download('image.png')
+const blob = new Blob([result.data])
+img.src = URL.createObjectURL(blob)
+```
+
+### TypeScript Support
+
+Type definitions are included (`index.d.ts`). For full type safety:
+* Define interfaces for your controller parameters and return types
+* Use type assertions when calling `api.<path>.<method>()`