api-ape 2.1.0 → 2.2.3

package/README.md

@@ -1,8 +1,12 @@
 # 🦍 api-ape
 
 [![npm version](https://img.shields.io/npm/v/api-ape.svg)](https://www.npmjs.com/package/api-ape)
-[![license](https://img.shields.io/npm/l/api-ape.svg)](https://github.com/codemeasandwich/api-ape/blob/main/LICENSE)
 [![GitHub issues](https://img.shields.io/github/issues/codemeasandwich/api-ape)](https://github.com/codemeasandwich/api-ape/issues)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#zero-dependencies)
+[![CSRF protected](https://img.shields.io/badge/CSRF%20🚷-protected-green.svg)](#csrf-protection)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/api-ape)](https://bundlephobia.com/package/api-ape)
+[![JJS Encoding](https://img.shields.io/badge/encoding-JJS-blue.svg)](#jjs-encoding)
+[![license](https://img.shields.io/npm/l/api-ape.svg)](https://github.com/codemeasandwich/api-ape/blob/main/LICENSE)
 
 **Remote Procedure Events (RPE)** — A lightweight WebSocket framework for building real-time APIs. Call server functions from the browser like local methods. Get real-time broadcasts with zero setup.
 
@@ -69,16 +73,36 @@ Include the bundled client and start calling:
 <script src="/api/ape.js"></script>
 <script>
   // Call server functions like local methods
-  const result = await ape.hello('World')
+  const result = await api.hello('World')
   console.log(result) // "Hello, World!"
   
   // Listen for broadcasts
-  ape.on('message', ({ data }) => {
+  api.on('message', ({ data }) => {
     console.log('New message:', data)
   })
 </script>
 ```
 
+### Client (React, Vue, etc.)
+
+With bundlers, use the unified import — no async setup needed:
+
+```js
+import api from 'api-ape'
+
+// Just use it! Calls are buffered until connected.
+const result = await api.hello('World')
+
+// Listen for broadcasts
+api.on('message', ({ data }) => console.log(data))
+
+// Track connection state
+api.onConnectionChange((state) => {
+  console.log('Connection:', state)
+  // 'offline' | 'walled' | 'disconnected' | 'connecting' | 'connected'
+})
+```
+
 **That's it!** Your server function is now callable from the browser.
 
 ---
@@ -87,7 +111,7 @@ Include the bundled client and start calling:
 
 * **Auto-wiring** — Drop JS files in a folder, they become API endpoints automatically
 * **Real-time broadcasts** — Built-in `broadcast()` and `broadcastOthers()` methods for pushing to clients
-* **Promise-based calls** — Chainable paths like `ape.users.list()` map to `api/users/list.js`
+* **Promise-based calls** — Chainable paths like `api.users.list()` map to `api/users/list.js`
 * **Automatic reconnection** — Client auto-reconnects on disconnect with exponential backoff
 * **HTTP streaming fallback** — Automatically falls back to long polling when WebSockets are blocked
 * **JJS Encoding** — Extended JSON supporting Date, RegExp, Error, Set, Map, undefined, and circular refs
@@ -118,88 +142,74 @@ Inside controller functions, `this` provides:
 | `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 (browser, OS, device) |
 
 ### Client
 
-#### `ape.<path>.<method>(...args)`
+#### `api.<path>.<method>(...args)`
 
 Call a server function. Returns a Promise.
 
 ```js
 // Calls api/users/list.js
-const users = await ape.users.list()
+const users = await api.users.list()
 
 // Calls api/users/create.js with data
-const user = await ape.users.create({ name: 'Alice' })
+const user = await api.users.create({ name: 'Alice' })
 
 // Nested paths work too
-// ape.admin.users -> api/admin/users.js
-// ape.admin.users.delete -> api/admin/users/delete.js
-await ape.admin.users.delete(userId)
+// api.admin.users -> api/admin/users.js
+// api.admin.users.delete -> api/admin/users/delete.js
+await api.admin.users.delete(userId)
 ```
 
-#### `ape.on(type, handler)`
+#### `api.on(type, handler)`
 
 Listen for server broadcasts.
 
 ```js
-ape.on('notification', ({ data, err, type }) => {
+api.on('notification', ({ data, err, type }) => {
   console.log('Received:', data)
 })
 ```
 
-#### `ape.configure(options)`
-
-Configure client connection options.
-
-```js
-// Configure transport mode
-ape.configure({ transport: 'auto' })      // Auto-detect (default)
-ape.configure({ transport: 'websocket' }) // Force WebSocket only
-ape.configure({ transport: 'polling' })   // Force HTTP streaming
-
-// Configure connection details
-ape.configure({ 
-  port: 9010,
-  host: 'example.com',
-  transport: 'auto'
-})
-```
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `port` | `number` | Server port (default: auto-detect) |
-| `host` | `string` | Server hostname (default: auto-detect) |
-| `transport` | `string` | Transport mode: `'auto'`, `'websocket'`, or `'polling'` |
-
-#### `ape.getTransport()`
+#### `api.getTransport()`
 
 Get the currently active transport type.
 
 ```js
-const transport = ape.getTransport()
+const transport = api.getTransport()
 console.log(transport) // 'websocket' | 'polling' | null
 ```
 
-#### `ape.onConnectionChange(handler)`
+#### `api.onConnectionChange(handler)`
 
 Listen for connection state changes.
 
 ```js
-const unsubscribe = ape.onConnectionChange((state) => {
+const unsubscribe = api.onConnectionChange((state) => {
   console.log('Connection state:', state)
-  // 'disconnected' | 'connecting' | 'connected'
 })
 
 // Later: stop listening
 unsubscribe()
 ```
 
+**Connection States:**
+
+| State | Description |
+|-------|-------------|
+| `offline` | Browser reports no network (`navigator.onLine = false`) |
+| `walled` | Captive portal detected (can't reach server) |
+| `disconnected` | Had connection, lost it |
+| `connecting` | Actively connecting to server |
+| `connected` | Connected and ready |
+
 ---
 
 ## Configuration
@@ -208,8 +218,7 @@ unsubscribe()
 
 ```js
 ape(server, {
-  where: 'api',           // Controller directory
-  onConnent: undefined    // Lifecycle hook (optional)
+  where: 'api'  // Controller directory
 })
 ```
 
@@ -220,12 +229,12 @@ Customize behavior per connection:
 ```js
 ape(server, {
   where: 'api',
-  onConnent(socket, req, hostId) {
+  onConnent(socket, req, clientId) {
     return {
       // Embed values into `this` for all controllers
       embed: {
         userId: req.session?.userId,
-        clientId: String(hostId)
+        id: String(clientId)
       },
       
       // Before/after hooks
@@ -316,7 +325,7 @@ module.exports = async function(id) {
 
 ```js
 try {
-  const result = await ape.data.get(id)
+  const result = await api.data.get(id)
   console.log(result)
 } catch (err) {
   console.error('Server error:', err)
@@ -325,82 +334,25 @@ try {
 
 ---
 
-## JJS Encoding
-
-api-ape uses **JJS (JSON SuperSet)** encoding, which extends JSON to support:
-
-| Type | Supported |
-|------|-----------|
-| `Date` | ✅ Preserved as Date objects |
-| `RegExp` | ✅ Preserved as RegExp |
-| `Error` | ✅ Preserved with name, message, stack |
-| `undefined` | ✅ Preserved (not converted to null) |
-| `Set` | ✅ Preserved as Set |
-| `Map` | ✅ Preserved as Map |
-| Circular refs | ✅ Handled via pointers |
-
-This is automatic — send a Date, receive a Date. No configuration needed.
-
----
-
-## HTTP Streaming Fallback
-
-api-ape automatically falls back to HTTP streaming when WebSockets are unavailable or blocked by firewalls/proxies.
-
-### How It Works
-
-1. **WebSocket First**: Client attempts WebSocket connection (4 second timeout)
-2. **Auto-Fallback**: On failure, switches to HTTP streaming transport
-3. **Background Retry**: Keeps attempting WebSocket reconnection every 30 seconds
-4. **Auto-Upgrade**: Switches back to WebSocket when available
-
-### Streaming Transport
-
-When in polling mode:
-- **GET `/api/ape/poll`**: Long-lived connection, server streams JSON messages
-- **POST `/api/ape/poll`**: Client sends messages
-- Cookie-based session (`apeHostId`) for authentication
-- Heartbeat every 20 seconds to prevent proxy timeout
-
-### Force Transport Mode
-
-```js
-// Force HTTP streaming (useful for testing)
-ape.configure({ transport: 'polling' })
-
-// Force WebSocket only (fail if unavailable)
-ape.configure({ transport: 'websocket' })
-
-// Auto-detect (default)
-ape.configure({ transport: 'auto' })
-```
-
-### Check Active Transport
-
-```js
-if (ape.getTransport() === 'polling') {
-  console.log('Using HTTP streaming fallback')
-}
-```
-
----
-
 ## Examples & Demos
 
 The repository contains working examples:
 
-* **`example/ExpressJs/`** — Simple real-time chat app
+* **[`example/ExpressJs/`](example/ExpressJs/)** — Simple real-time chat app
   - Minimal setup with Express.js
   - Broadcast messages to other clients
   - Message history
 
-* **`example/NextJs/`** — Production-ready chat application
+* **[`example/NextJs/`](example/NextJs/)** — Production-ready chat application
   - Custom Next.js server integration
   - React hooks integration
   - User presence tracking
   - Docker support
   - Connection lifecycle hooks
 
+* **[`example/Vite/`](example/Vite/)** — Vite + Vue example
+* **[`example/Bun/`](example/Bun/)** — Bun runtime example
+
 ### Run an Example
 
 **ExpressJs:**
@@ -427,74 +379,6 @@ docker-compose up --build
 
 ---
 
-## Troubleshooting & FAQ
-
-### CORS Errors in Browser
-
-Ensure your server allows WebSocket connections from your origin. api-ape uses the `ws` library which handles WebSocket upgrades on the HTTP server level.
-
-### 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` → `ape.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
-
-api-ape supports transparent binary file transfers. Simply return `Buffer` data from controllers:
-
-```js
-// api/files/download.js
-module.exports = function(filename) {
-  return {
-    name: filename,
-    data: fs.readFileSync(`./uploads/${filename}`)  // Buffer
-  }
-}
-```
-
-The client receives `ArrayBuffer` automatically:
-
-```js
-const result = await ape.files.download('image.png')
-console.log(result.data)  // ArrayBuffer
-
-// Display as image
-const blob = new Blob([result.data])
-img.src = URL.createObjectURL(blob)
-```
-
-**Uploads work the same way:**
-
-```js
-// Client
-const arrayBuffer = await file.arrayBuffer()
-await ape.files.upload({ name: file.name, data: arrayBuffer })
-
-// Server (api/files/upload.js)
-module.exports = function({ name, data }) {
-  fs.writeFileSync(`./uploads/${name}`, data)  // data is Buffer
-  return { success: true }
-}
-```
-
-Binary data is transferred via temporary HTTP endpoints (`/api/ape/data/:hash`) with session verification and auto-cleanup.
-
-### TypeScript Support
-
-Type definitions are included (`index.d.ts`). For full type safety, you may need to:
-* Define interfaces for your controller parameters and return types
-* Use type assertions when calling `ape.<path>.<method>()`
-
----
-
 ## Tests & CI
 
 ```bash
@@ -507,7 +391,6 @@ npm run test:cover  # Coverage report
 - `npm test` — Run all tests
 - `npm run test:watch` — Watch mode for development
 - `npm run test:cover` — Generate coverage report
-- `npm run test:update` — Update snapshots
 
 **Supported:** Node.js 14+, modern browsers (Chrome, Firefox, Safari, Edge)
 
@@ -542,11 +425,34 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## Zero Dependencies
+
+api-ape has **zero runtime dependencies**. The WebSocket implementation is built-in:
+
+- **Node.js 24+**: Uses native `node:ws` module
+- **Bun / Deno**: Uses framework-provided WebSocket support
+- **Earlier Node.js**: Uses built-in RFC 6455 compliant WebSocket server
+
+No `npm install` surprises, no dependency audits, no supply chain concerns.
+
+---
+
 ## Security
 
 **Reporting vulnerabilities:** Please report security issues via [GitHub Security Advisories](https://github.com/codemeasandwich/api-ape/security/advisories) or email the maintainer.
 
-**Security considerations:**
+### CSRF Protection
+
+api-ape includes built-in **Cross-Site Request Forgery (CSRF)** protection via Origin validation:
+
+- **Origin Header Check** — Every WebSocket connection validates the `Origin` header against the `Host` header
+- **Automatic Rejection** — Connections from mismatched origins are destroyed immediately
+- **No Configuration Needed** — Protection is enabled by default
+
+This prevents malicious sites from making requests to your api-ape server while impersonating logged-in users.
+
+### Security Considerations
+
 * Validate all input in controllers
 * Use authentication/authorization in `onConnent` hooks
 * Sanitize data before broadcasting
@@ -559,34 +465,117 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 ```
 api-ape/
 ├── client/
-│   ├── browser.js       # Browser entry point (window.ape)
-│   └── connectSocket.js # WebSocket client with auto-reconnect
+│   ├── index.js             # Unified client entry point (auto-buffered)
+│   ├── browser.js           # Browser entry point (window.ape)
+│   ├── connectSocket.js     # WebSocket client with auto-reconnect
+│   └── transports/
+│       └── streaming.js     # HTTP streaming fallback transport
 ├── server/
 │   ├── lib/
-│   │   ├── main.js      # HTTP server integration
-│   │   ├── loader.js    # Auto-loads controller files
-│   │   ├── broadcast.js # Client tracking & broadcast
-│   │   └── wiring.js    # WebSocket handler setup
+│   │   ├── main.js          # HTTP server integration
+│   │   ├── loader.js        # Auto-loads controller files
+│   │   ├── broadcast.js     # Client tracking & broadcast
+│   │   ├── wiring.js        # WebSocket handler setup
+│   │   ├── fileTransfer.js  # Binary file transfer via HTTP
+│   │   ├── longPolling.js   # HTTP streaming fallback handler
+│   │   ├── bun.js           # Bun runtime support
+│   │   ├── wsProvider.js    # WebSocket provider abstraction
+│   │   └── ws/              # Native WebSocket implementation
 │   ├── socket/
-│   │   ├── receive.js   # Incoming message handler
-│   │   └── send.js      # Outgoing message handler
-│   └── security/
-│       └── reply.js      # Duplicate request protection
+│   │   ├── open.js          # Connection handler
+│   │   ├── receive.js       # Incoming message handler
+│   │   └── send.js          # Outgoing message handler
+│   ├── security/
+│   │   ├── reply.js         # Duplicate request protection
+│   │   ├── origin.js        # Origin validation
+│   │   └── extractRootDomain.js # Domain extraction utility
+│   └── utils/
+│       ├── deepRequire.js   # Deep module loader
+│       ├── genId.js         # ID generation
+│       └── parseUserAgent.js # Browser/OS/device parser
 ├── utils/
-│   ├── jss.js           # JSON SuperSet encoder/decoder
-│   └── messageHash.js   # Request deduplication
+│   ├── jss.js               # JSON SuperSet encoder/decoder
+│   └── messageHash.js       # Request deduplication hashing
 └── example/
-    ├── ExpressJs/       # Chat app example
-    └── NextJs/          # Next.js integration
+    ├── ExpressJs/           # Minimal chat app example
+    ├── NextJs/              # Next.js production example
+    ├── Vite/                # Vite/Vue example
+    └── Bun/                 # Bun runtime example
+```
+
+---
+
+## Troubleshooting & FAQ
+
+### CORS Errors in Browser
+
+Ensure your server allows WebSocket connections from your origin. api-ape uses the `ws` library which handles WebSocket upgrades on the HTTP server level.
+
+### 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
+
+api-ape supports transparent binary file transfers. Simply return `Buffer` data from controllers:
+
+```js
+// api/files/download.js
+module.exports = function(filename) {
+  return {
+    name: filename,
+    data: fs.readFileSync(`./uploads/${filename}`)  // Buffer
+  }
+}
+```
+
+The client receives `ArrayBuffer` automatically:
+
+```js
+const result = await api.files.download('image.png')
+console.log(result.data)  // ArrayBuffer
+
+// Display as image
+const blob = new Blob([result.data])
+img.src = URL.createObjectURL(blob)
 ```
 
+**Uploads work the same way:**
+
+```js
+// Client
+const arrayBuffer = await file.arrayBuffer()
+await api.files.upload({ name: file.name, data: arrayBuffer })
+
+// Server (api/files/upload.js)
+module.exports = function({ name, data }) {
+  fs.writeFileSync(`./uploads/${name}`, data)  // data is Buffer
+  return { success: true }
+}
+```
+
+### TypeScript Support
+
+Type definitions are included (`index.d.ts`). For full type safety, you may need to:
+* Define interfaces for your controller parameters and return types
+* Use type assertions when calling `api.<path>.<method>()`
+
 ---
 
 ## License & Authors
 
 **License:** MIT
 
-**Author:** [Brian Shannon](https://github.com/codemeasandwich)
+**Author:** [Brian Shannon](https://www.linkedin.com/in/brianshann/)
 
 **Repository:** [github.com/codemeasandwich/api-ape](https://github.com/codemeasandwich/api-ape)
 

package/client/README.md

@@ -6,7 +6,8 @@ WebSocket client library with auto-reconnection and proxy-based API calls.
 
 | File | Description |
 |------|-------------|
-| `browser.js` | Browser entry point - exposes `window.ape` |
+| `index.js` | **Unified entry** — auto-initializing client with call buffering |
+| `browser.js` | Browser entry point — exposes `window.ape` |
 | `connectSocket.js` | WebSocket client with auto-reconnect, queuing, and JJS encoding |
 
 ## Usage
@@ -17,36 +18,44 @@ WebSocket client library with auto-reconnection and proxy-based API calls.
 <script src="/api/ape.js"></script>
 <script>
   // Call server functions
-  ape.hello('World').then(result => console.log(result))
+  api.hello('World').then(result => console.log(result))
   
   // Listen for broadcasts
-  ape.on('message', ({ data }) => console.log(data))
+  api.on('message', ({ data }) => console.log(data))
 </script>
 ```
 
-### ES Module Import
+### ES Module Import (React, Vue, etc.)
 
 ```bash
 npm i api-ape
 ```
 
 ```js
-import ape from 'api-ape'
+import api from 'api-ape'
 
-// Configure
-ape.configure({ port: 3000 })
-
-// Connect and enable auto-reconnect
-const { sender, setOnReciver } = ape()
-ape.autoReconnect()
-
-// Use sender as API
-sender.users.list().then(users => ...)
+// Just use it! Calls are buffered until connected.
+api.users.list().then(users => console.log(users))
 
 // Listen for broadcasts
-setOnReciver('newUser', ({ data }) => ...)
+api.on('message', ({ data }) => console.log(data))
+
+// Track connection state
+api.onConnectionChange((state) => {
+  console.log('Connection:', state)
+  // 'offline' | 'walled' | 'disconnected' | 'connecting' | 'connected'
+})
 ```
 
+**Connection States:**
+- `offline` — Browser reports no network
+- `walled` — Captive portal detected (WiFi without real internet)
+- `disconnected` — Had connection, lost it
+- `connecting` — Actively connecting
+- `connected` — Ready to use
+
+**No async setup needed!** The client auto-initializes and buffers calls until connected.
+
 ## Features
 
 - **Proxy-based API** — `ape.path.method(data)` converts to WebSocket calls
@@ -55,19 +64,6 @@ setOnReciver('newUser', ({ data }) => ...)
 - **JJS encoding** — Supports Date, RegExp, Error, Set, Map, undefined over the wire
 - **Request timeout** — Configurable timeout (default: 10s)
 
-## Configuration
-
-```js
-ape.configure({
-  port: 3000,    // WebSocket port
-  host: 'api.example.com'  // WebSocket host
-})
-```
-
-Default port detection:
-- Local (`localhost`, `127.0.0.1`): `9010`
-- Remote: Uses current page port or `443`/`80`
-
 ## File Transfers
 
 Binary data is automatically handled. The client fetches binary resources and uploads binary data transparently.
@@ -76,7 +72,7 @@ Binary data is automatically handled. The client fetches binary resources and up
 
 ```js
 // Server returns Buffer, client receives ArrayBuffer
-const result = await ape.files.download('image.png')
+const result = await api.files.download('image.png')
 console.log(result.data)  // ArrayBuffer
 
 // Display as image
@@ -91,7 +87,7 @@ const file = input.files[0]
 const arrayBuffer = await file.arrayBuffer()
 
 // Binary data is uploaded automatically
-await ape.files.upload({
+await api.files.upload({
   name: file.name,
   data: arrayBuffer  // Sent via HTTP PUT
 })
@@ -99,3 +95,14 @@ await ape.files.upload({
 
 Binary transfers use `/api/ape/data/:hash` endpoints with session verification.
 
+## Security
+
+### CSRF Protection
+
+api-ape includes built-in **Cross-Site Request Forgery (CSRF)** protection:
+
+- **Origin Validation** — WebSocket connections validate Origin header against Host
+- **Automatic Rejection** — Mismatched origins are rejected immediately
+- **Session Verification** — Binary transfers verify session cookies
+
+No configuration needed — protection is enabled by default.