api-ape 2.1.0 → 2.2.2

package/package.json

@@ -1,17 +1,39 @@
 {
   "name": "api-ape",
-  "version": "2.1.0",
+  "version": "2.2.2",
   "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",
   "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "browser": "./client/index.js",
+      "default": "./index.js"
+    },
+    "./client": "./client/index.js",
+    "./client/*": "./client/*",
+    "./server": "./server/index.js",
+    "./server/*": "./server/*"
+  },
+  "files": [
+    "dist/",
+    "client/",
+    "server/",
+    "utils/",
+    "index.js",
+    "index.d.ts",
+    "!**/*.test.js"
+  ],
   "scripts": {
+    "prepare": "cp .hooks/* .git/hooks/ 2>/dev/null && chmod +x .git/hooks/* || true",
     "test": "jest --no-cache",
     "test:watch": "jest --watch --runInBand",
     "test:cover": "jest --coverage --no-cache --detectOpenHandles",
     "demo:express": "cd example/ExpressJs && npm install && npm start",
     "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"
+    "demo:bun": "cd example/Bun && npm install && npm start",
+    "publish": "bash scripts/publish.sh"
   },
   "repository": {
     "type": "git",
@@ -20,7 +42,7 @@
   "keywords": [
     "websocket",
     "realtime",
-    "rpc",
+    "CSRF",
     "api",
     "remote-procedure-call",
     "real-time",
@@ -34,7 +56,7 @@
     "jjs",
     "rpe",
     "nodejs",
-    "framework"
+    "library"
   ],
   "author": "brian shannon",
   "license": "MIT",
@@ -42,10 +64,7 @@
     "url": "https://github.com/codemeasandwich/api-ape/issues"
   },
   "homepage": "https://github.com/codemeasandwich/api-ape#readme",
-  "dependencies": {
-    "ua-parser-js": "^1.0.37",
-    "ws": "^8.14.0"
-  },
+  "dependencies": {},
   "devDependencies": {
     "esbuild": "^0.27.2",
     "jest": "^29.3.1"

package/server/README.md

@@ -13,7 +13,16 @@ server/
 │   ├── broadcast.js  # Client tracking & broadcast utilities
 │   ├── fileTransfer.js # Binary file transfer manager
 │   ├── longPolling.js  # HTTP streaming fallback handler
-│   └── wiring.js     # WebSocket handler setup
+│   ├── 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
 ├── socket/
 │   ├── receive.js    # Incoming message handler
 │   └── send.js       # Outgoing message handler
@@ -76,8 +85,9 @@ 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 hostIds |
-| `this.hostId` | Unique ID of the calling client |
+| `this.getClients()` | Get array of connected clientIds |
+| `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 |
@@ -102,15 +112,15 @@ Drop JS files in your `where` directory:
 
 ```
 api/
-├── hello.js      → ape.hello(data)
-├── users.js      → ape.users(data)
+├── hello.js      → api.hello(data)
+├── users.js      → api.users(data)
 ├── posts/
-│   ├── index.js  → ape.posts(data)     # index.js maps to parent folder
-│   ├── list.js   → ape.posts.list(data)
-│   └── create.js → ape.posts.create(data)
+│   ├── index.js  → api.posts(data)     # index.js maps to parent folder
+│   ├── list.js   → api.posts.list(data)
+│   └── create.js → api.posts.create(data)
 ```
 
-**Note**: Both `api/users.js` and `api/users/index.js` map to the same endpoint `ape.users(data)`. Use `index.js` when you want to group related files in a folder.
+**Note**: Both `api/users.js` and `api/users/index.js` map to the same endpoint `api.users(data)`. Use `index.js` when you want to group related files in a folder.
 
 **⚠️ Duplicate Detection**: If both files exist, api-ape will throw an error on startup:
 ```
@@ -159,7 +169,7 @@ api-ape automatically provides HTTP streaming endpoints as a fallback when WebSo
 
 Long-lived HTTP streaming connection for receiving server messages.
 
-- **Session**: Cookie-based (`apeHostId`)
+- **Session**: Cookie-based (`apeClientId`)
 - **Response**: Streaming JSON messages
 - **Heartbeat**: Every 20 seconds
 - **Auto-reconnect**: Client reconnects after 25 seconds
@@ -168,7 +178,7 @@ Long-lived HTTP streaming connection for receiving server messages.
 
 Send messages to server when using HTTP streaming transport.
 
-- **Session**: Cookie-based (`apeHostId`)
+- **Session**: Cookie-based (`apeClientId`)
 - **Body**: JJS-encoded message
 - **Response**: JJS-encoded result
 
@@ -180,3 +190,34 @@ Send messages to server when using HTTP streaming transport.
 4. Automatically upgrades back to WebSocket when available
 
 The fallback is **completely transparent** to your controllers - they work identically with both transports.
+
+---
+
+## Zero-Dependency WebSocket
+
+api-ape includes its own RFC 6455 WebSocket implementation with **zero npm dependencies**.
+
+### Runtime Detection
+
+The server automatically detects and uses the best available WebSocket implementation:
+
+1. **Deno**: Uses native `Deno.upgradeWebSocket()` API
+2. **Bun**: Uses native `Bun.serve()` WebSocket handlers
+3. **Node.js 24+** (stable): Uses native `node:ws` module
+4. **Earlier Node.js**: Uses built-in RFC 6455 polyfill
+
+```javascript
+// Automatic - no configuration needed
+ape(server, { where: 'api' })
+```
+
+### Polyfill Features
+
+The built-in polyfill implements:
+
+- Full RFC 6455 handshake (SHA-1 + GUID)
+- Text and binary frames
+- Frame fragmentation
+- Ping/pong heartbeats
+- Proper close handshake
+- Masking (client→server)

package/server/lib/broadcast.js

@@ -11,31 +11,48 @@ const connectedClients = new Set()
  */
 function addClient(clientInfo) {
     connectedClients.add(clientInfo)
+    console.log(`🟢 Client added: ${clientInfo.clientId} (total: ${connectedClients.size})`)
 }
 
 /**
  * Remove a client from the connected set
+ * Accepts either the client object or { clientId } for lookup
  */
 function removeClient(clientInfo) {
-    connectedClients.delete(clientInfo)
+    const sizeBefore = connectedClients.size
+    // If exact reference found, delete it
+    if (connectedClients.has(clientInfo)) {
+        connectedClients.delete(clientInfo)
+        console.log(`🔴 Client removed (ref): ${clientInfo.clientId} (total: ${connectedClients.size})`)
+        return
+    }
+    // Otherwise search by clientId (needed for long polling cleanup)
+    for (const client of connectedClients) {
+        if (client.clientId === clientInfo.clientId) {
+            connectedClients.delete(client)
+            console.log(`🔴 Client removed (lookup): ${clientInfo.clientId} (total: ${connectedClients.size})`)
+            return
+        }
+    }
+    console.log(`⚠️ Client not found for removal: ${clientInfo.clientId} (total: ${connectedClients.size})`)
 }
 
 /**
  * Broadcast to all connected clients
  * @param {string} type - Message type
  * @param {any} data - Data to send
- * @param {string} [excludeHostId] - Optional hostId to exclude (e.g., sender)
+ * @param {string} [excludeClientId] - Optional clientId to exclude (e.g., sender)
  */
-function broadcast(type, data, excludeHostId) {
-    console.log(`📢 Broadcasting "${type}" to ${connectedClients.size} clients`, excludeHostId ? `(excluding ${excludeHostId})` : '')
+function broadcast(type, data, excludeClientId) {
+    console.log(`📢 Broadcasting "${type}" to ${connectedClients.size} clients`, excludeClientId ? `(excluding ${excludeClientId})` : '')
     connectedClients.forEach(client => {
-        if (excludeHostId && client.hostId === excludeHostId) {
+        if (excludeClientId && client.clientId === excludeClientId) {
             return // Skip excluded client
         }
         try {
             client.send(false, type, data, false)
         } catch (e) {
-            console.error(`📢 Broadcast failed to ${client.hostId}:`, e.message)
+            console.error(`📢 Broadcast failed to ${client.clientId}:`, e.message)
         }
     })
 }
@@ -48,10 +65,10 @@ function online() {
 }
 
 /**
- * Get all connected client hostIds
+ * Get all connected client clientIds
  */
 function getClients() {
-    return Array.from(connectedClients).map(c => c.hostId)
+    return Array.from(connectedClients).map(c => c.clientId)
 }
 
 module.exports = {

package/server/lib/bun.js

@@ -0,0 +1,122 @@
+/**
+ * Bun-specific api-ape integration
+ * Returns handlers for use with Bun.serve()
+ * 
+ * Usage:
+ * ```ts
+ * import { apeBun } from 'api-ape/bun'
+ * 
+ * const ape = apeBun({ where: 'api', onConnent: ... })
+ * 
+ * Bun.serve({
+ *   port: 3000,
+ *   fetch: ape.fetch,
+ *   websocket: ape.websocket
+ * })
+ * ```
+ */
+
+const loader = require('./loader')
+const wiring = require('./wiring')
+const path = require('path')
+const fs = require('fs')
+const { getFileTransferManager } = require('./fileTransfer')
+const { BunWebSocket, BunWebSocketServer } = require('./ws/adapters/bun')
+
+/**
+ * Create api-ape handlers for Bun.serve()
+ * @param {{ where: string, onConnent?: Function, fileTransferOptions?: Object }} options
+ */
+function apeBun({ where, onConnent, fileTransferOptions }) {
+    const controllers = loader(where)
+    const fileTransfer = getFileTransferManager(fileTransferOptions)
+    const wss = new BunWebSocketServer({ noServer: true })
+
+    const wsPath = `/${where}/ape`
+    const wiringHandler = wiring(controllers, onConnent, fileTransfer)
+
+    // Handle connections
+    wss.on('connection', wiringHandler)
+
+    /**
+     * Bun fetch handler - handles HTTP requests and WebSocket upgrades
+     */
+    function fetch(req, server) {
+        const url = new URL(req.url)
+        const pathname = url.pathname
+
+        // WebSocket upgrade
+        if (pathname === wsPath) {
+            const upgrade = req.headers.get('upgrade')
+            if (upgrade?.toLowerCase() === 'websocket') {
+                // Use Bun's native upgrade
+                const success = server.upgrade(req, {
+                    data: { req }
+                })
+                if (success) {
+                    return undefined // Bun handles the response
+                }
+                return new Response('WebSocket upgrade failed', { status: 500 })
+            }
+        }
+
+        // Serve client bundle
+        if (pathname === `/${where}/ape.js`) {
+            try {
+                const filePath = path.join(__dirname, '../../dist/ape.js')
+                const data = fs.readFileSync(filePath)
+                return new Response(data, {
+                    headers: { 'Content-Type': 'application/javascript' }
+                })
+            } catch {
+                return new Response('Client bundle not found', { status: 500 })
+            }
+        }
+
+        // Not an api-ape route
+        return null
+    }
+
+    /**
+     * Bun websocket handlers
+     */
+    const websocket = {
+        open(ws) {
+            const wrapper = new BunWebSocket(ws)
+            wss._clients.set(ws, wrapper)
+
+            const { req } = ws.data || {}
+            wiringHandler(wrapper, req)
+        },
+
+        message(ws, message) {
+            const wrapper = wss._clients.get(ws)
+            if (wrapper) {
+                wrapper._onMessage(message)
+            }
+        },
+
+        close(ws, code, reason) {
+            const wrapper = wss._clients.get(ws)
+            if (wrapper) {
+                wrapper._onClose(code, reason)
+                wss._clients.delete(ws)
+            }
+        },
+
+        error(ws, error) {
+            const wrapper = wss._clients.get(ws)
+            if (wrapper) {
+                wrapper._onError(error)
+            }
+        }
+    }
+
+    return {
+        fetch,
+        websocket,
+        wss
+    }
+}
+
+module.exports = { apeBun }

package/server/lib/longPolling.js

@@ -2,35 +2,35 @@ const { addClient, removeClient, broadcast } = require('./broadcast')
 const makeid = require('../utils/genId')
 const jss = require('../../utils/jss')
 
-// Active streaming connections: hostId -> { res, messageQueue, heartbeatTimer }
+// Active streaming connections: clientId -> { res, messageQueue, heartbeatTimer }
 const streamClients = new Map()
 
 // Pending message handlers for POST requests: queryId -> { resolve, reject, timer }
 const pendingRequests = new Map()
 
 /**
- * Set apeHostId cookie if not present
+ * Set apeClientId cookie if not present
  */
-function ensureHostId(req, res) {
+function ensureClientId(req, res) {
     const cookies = req.headers.cookie || ''
-    const match = cookies.match(/(?:^|;\s*)apeHostId=([^;]*)/)
+    const match = cookies.match(/(?:^|;\s*)apeClientId=([^;]*)/)
 
     if (match) {
         return match[1]
     }
 
-    // Generate new hostId and set cookie
-    const hostId = makeid(20)
-    res.setHeader('Set-Cookie', `apeHostId=${hostId}; Path=/; HttpOnly; SameSite=Strict`)
-    return hostId
+    // Generate new clientId and set cookie
+    const clientId = makeid(20)
+    res.setHeader('Set-Cookie', `apeClientId=${clientId}; Path=/; HttpOnly; SameSite=Strict`)
+    return clientId
 }
 
 /**
- * Get hostId from cookie
+ * Get clientId from cookie
  */
-function getHostId(req) {
+function getClientId(req) {
     const cookies = req.headers.cookie || ''
-    const match = cookies.match(/(?:^|;\s*)apeHostId=([^;]*)/)
+    const match = cookies.match(/(?:^|;\s*)apeClientId=([^;]*)/)
     return match ? match[1] : null
 }
 
@@ -52,7 +52,7 @@ function createLongPollingHandler(controllers, onConnent, fileTransfer) {
      * Keeps connection open and writes JSON messages as they arrive
      */
     function handleStreamGet(req, res) {
-        const hostId = ensureHostId(req, res)
+        const clientId = ensureClientId(req, res)
 
         // Set up streaming response headers
         res.writeHead(200, {
@@ -81,7 +81,7 @@ function createLongPollingHandler(controllers, onConnent, fileTransfer) {
                 cleanup()
             }
         }
-        send.toString = () => hostId
+        send.toString = () => clientId
 
         // Clean up on close
         const cleanup = () => {
@@ -92,8 +92,8 @@ function createLongPollingHandler(controllers, onConnent, fileTransfer) {
                 clearInterval(clientState.heartbeatTimer)
             }
 
-            streamClients.delete(hostId)
-            removeClient({ hostId })
+            streamClients.delete(clientId)
+            removeClient({ clientId })
 
             // Notify disconnect handler if registered
             if (clientState.onDisconnect) {
@@ -117,9 +117,9 @@ function createLongPollingHandler(controllers, onConnent, fileTransfer) {
         }, 20000)
 
         // Register client for broadcasts
-        const clientInfo = { hostId, send }
+        const clientInfo = { clientId, send }
         addClient(clientInfo)
-        streamClients.set(hostId, clientState)
+        streamClients.set(clientId, clientState)
 
         // Call onConnent hook if provided
         if (onConnent) {
@@ -154,9 +154,9 @@ function createLongPollingHandler(controllers, onConnent, fileTransfer) {
      * Process message through controllers, return response
      */
     function handleStreamPost(req, res, controllers) {
-        const hostId = getHostId(req)
+        const clientId = getClientId(req)
 
-        if (!hostId) {
+        if (!clientId) {
             return sendJson(res, 401, { error: 'Missing session. GET /api/ape/poll first.' })
         }
 
@@ -178,16 +178,21 @@ function createLongPollingHandler(controllers, onConnent, fileTransfer) {
                 }
 
                 // Get client state for embed values
-                const clientState = streamClients.get(hostId)
+                const clientState = streamClients.get(clientId)
                 const embedValues = clientState?.embed || {}
 
+                // Extract sessionId from cookies (set by outer framework)
+                const sessionIdMatch = (req.headers.cookie || '').match(/(?:^|;\s*)sessionId=([^;]*)/)
+                const sessionId = sessionIdMatch ? sessionIdMatch[1] : null
+
                 // Build controller context
                 const context = {
                     ...embedValues,
-                    hostId,
+                    clientId,
+                    sessionId,  // Session ID from cookie (set by outer framework)
                     req,
                     broadcast: (t, d) => broadcast(t, d),
-                    broadcastOthers: (t, d) => broadcast(t, d, hostId),
+                    broadcastOthers: (t, d) => broadcast(t, d, clientId),
                     online: () => streamClients.size,
                     getClients: () => Array.from(streamClients.keys())
                 }
@@ -218,4 +223,4 @@ function createLongPollingHandler(controllers, onConnent, fileTransfer) {
     }
 }
 
-module.exports = { createLongPollingHandler, getHostId, ensureHostId }
+module.exports = { createLongPollingHandler, getClientId, ensureClientId }