api-ape 0.0.0 → 1.0.1

package/example/ExpressJs/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "chat-example",
+  "scripts": {
+    "start": "node backend.js"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "scribbles": "^1.5.0"
+  }
+}

package/example/ExpressJs/styles.css

@@ -0,0 +1,128 @@
+* {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+}
+
+body {
+    min-height: 100vh;
+    background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
+    color: #fff;
+    font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif;
+    display: flex;
+    justify-content: center;
+    padding: 2rem;
+}
+
+chat-app {
+    max-width: 500px;
+    width: 100%;
+}
+
+.chat-container {
+    background: rgba(255, 255, 255, 0.05);
+    border-radius: 20px;
+    overflow: hidden;
+    box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
+}
+
+.header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 1rem 1.5rem;
+    background: rgba(255, 255, 255, 0.1);
+}
+
+.title {
+    font-size: 1.25rem;
+    font-weight: bold;
+    background: linear-gradient(90deg, #00d2ff, #3a7bd5);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+}
+
+.user-badge {
+    font-size: 0.85rem;
+    color: #0f0;
+    font-weight: bold;
+}
+
+.messages {
+    height: 350px;
+    overflow-y: auto;
+    padding: 1rem;
+}
+
+.messages::-webkit-scrollbar {
+    width: 6px;
+}
+
+.messages::-webkit-scrollbar-track {
+    background: rgba(255, 255, 255, 0.05);
+}
+
+.messages::-webkit-scrollbar-thumb {
+    background: rgba(255, 255, 255, 0.2);
+    border-radius: 3px;
+}
+
+.empty-state {
+    text-align: center;
+    color: #666;
+    margin-top: 140px;
+}
+
+.message {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    padding: 0.75rem 1rem;
+    margin-bottom: 0.5rem;
+    background: rgba(255, 255, 255, 0.05);
+    border-radius: 12px;
+    border-left: 3px solid #3a7bd5;
+}
+
+.message.mine {
+    background: rgba(0, 210, 255, 0.15);
+    border-left-color: #00d2ff;
+}
+
+.message .username {
+    color: #00d2ff;
+    font-size: 0.85rem;
+    font-weight: bold;
+}
+
+.message .text {
+    color: #fff;
+}
+
+.input-area {
+    display: flex;
+    gap: 0.5rem;
+    padding: 1rem;
+    border-top: 1px solid rgba(255, 255, 255, 0.1);
+}
+
+.message-input {
+    flex: 1;
+    padding: 0.75rem 1rem;
+    font-size: 1rem;
+    border: none;
+    border-radius: 50px;
+    background: rgba(255, 255, 255, 0.1);
+    color: #fff;
+    outline: none;
+    transition: background 0.2s;
+}
+
+.message-input::placeholder {
+    color: rgba(255, 255, 255, 0.5);
+}
+
+.message-input:focus {
+    background: rgba(255, 255, 255, 0.15);
+}

package/example/NextJs/.dockerignore

@@ -0,0 +1,29 @@
+# Dependencies
+node_modules
+
+# Next.js build output
+.next
+
+# Git
+.git
+.gitignore
+
+# IDE
+.idea
+.vscode
+*.swp
+*.swo
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Testing
+coverage
+
+# Misc
+.DS_Store
+*.pem
+.env*.local
+README.md

package/example/NextJs/Dockerfile

@@ -0,0 +1,52 @@
+# Install dependencies only when needed
+FROM node:18-alpine AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+# Install dependencies based on the preferred package manager
+COPY package.json package-lock.json* ./
+RUN npm ci
+
+# Rebuild the source code only when needed
+FROM node:18-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# Next.js collects completely anonymous telemetry data about general usage.
+# Learn more here: https://nextjs.org/telemetry
+# Uncomment the following line in case you want to disable telemetry during the build.
+# ENV NEXT_TELEMETRY_DISABLED 1
+
+RUN npm run build
+
+# Production image, copy all the files and run next
+FROM node:18-alpine AS runner
+WORKDIR /app
+
+ENV NODE_ENV production
+# Uncomment the following line in case you want to disable telemetry during runtime.
+# ENV NEXT_TELEMETRY_DISABLED 1
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+COPY --from=builder /app/public ./public
+
+# Set the correct permission for prerender cache
+RUN mkdir .next
+RUN chown nextjs:nodejs .next
+
+# Automatically leverage output traces to reduce image size
+# https://nextjs.org/docs/advanced-features/output-file-tracing
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE 3000
+
+ENV PORT 3000
+ENV HOSTNAME "0.0.0.0"
+
+CMD ["node", "server.js"]

package/example/NextJs/Dockerfile.dev

@@ -0,0 +1,27 @@
+# Development Dockerfile with hot reload support
+# Context: api-ape root (not example/NextJs)
+FROM node:18-alpine
+
+WORKDIR /api-ape
+
+# First install api-ape root dependencies (ws, ua-parser-js, etc.)
+COPY package.json package-lock.json* ./
+RUN npm install
+
+# Then install NextJs example dependencies
+WORKDIR /api-ape/example/NextJs
+COPY example/NextJs/package.json example/NextJs/package-lock.json* ./
+RUN npm install
+
+# Copy all source files
+WORKDIR /api-ape
+COPY . .
+
+# Back to NextJs example
+WORKDIR /api-ape/example/NextJs
+
+# Expose port
+EXPOSE 3000
+
+# Run in development mode
+CMD ["npm", "run", "dev"]

package/example/NextJs/README.md

@@ -0,0 +1,113 @@
+# 🦍 NextJs — Complete Example
+
+A full-featured real-time chat application with Next.js and api-ape.
+
+## Quick Start
+
+```bash
+npm install
+npm run dev
+```
+
+Open http://localhost:3000 in your browser.
+
+## Docker
+
+```bash
+docker-compose up --build
+```
+
+## Project Structure
+
+```
+NextJs/
+├── server.js             # Custom Next.js server with api-ape
+├── api/
+│   └── message.js        # Message controller
+├── ape/
+│   ├── index.js          # Ape exports
+│   ├── client.js         # Browser client wrapper
+│   ├── onConnect.js      # Connection lifecycle
+│   ├── onDisconnect.js   # Disconnect handler
+│   ├── onReceive.js      # Message logging
+│   ├── onSend.js         # Send logging
+│   ├── onError.js        # Error handling
+│   └── embed.js          # Embedded context values
+├── pages/
+│   └── index.tsx         # Chat UI
+└── styles/
+    └── Chat.module.css   # Chat styling
+```
+
+## Features
+
+- **Custom Server** — Express + Next.js with api-ape integration
+- **Connection Lifecycle** — onConnect, onDisconnect, onReceive, onSend hooks
+- **User Presence** — Track online users count
+- **Message History** — New users receive chat history
+- **React Integration** — Hooks-based client usage
+- **Docker Support** — Production-ready containerization
+
+## How It Works
+
+### Server (server.js)
+
+```js
+const express = require('express')
+const next = require('next')
+const ape = require('api-ape')
+const { onConnect } = require('./ape/onConnect')
+
+const app = next({ dev: true })
+const server = express()
+
+ape(server, { where: 'api', onConnent: onConnect })
+server.all('*', app.getRequestHandler())
+server.listen(3000)
+```
+
+### Connection Lifecycle (ape/onConnect.js)
+
+```js
+module.exports.onConnect = (socket, req, send) => ({
+  embed: { userId: generateId() },
+  onReceive: (queryId, data, type) => { ... },
+  onSend: (data, type) => { ... },
+  onDisconnent: () => { ... }
+})
+```
+
+### React Client (pages/index.tsx)
+
+```bash
+npm i api-ape
+```
+
+```jsx
+import ape from 'api-ape'
+
+// Configure and connect
+ape.configure({ port: 3000 })
+const { sender, setOnReciver } = ape()
+ape.autoReconnect()
+
+useEffect(() => {
+  setOnReciver('message', ({ data }) => {
+    setMessages(prev => [...prev, data.message])
+  })
+}, [])
+
+// Send message
+sender.message({ user, text }).then(response => { ... })
+```
+
+## Key Concepts Demonstrated
+
+| Concept | File |
+|---------|------|
+| Custom Next.js server | `server.js` |
+| Connection lifecycle hooks | `ape/onConnect.js` |
+| Embedded context values | `ape/embed.js` |
+| React hooks integration | `pages/index.tsx` |
+| Client wrapper | `ape/client.js` |
+| Message validation | `api/message.js` |

package/example/NextJs/ape/client.js

@@ -0,0 +1,66 @@
+/**
+ * api-ape client singleton
+ * Initializes once and is ready for use throughout the app
+ */
+
+let apeClient = null
+let isConnecting = false
+let connectionPromise = null
+
+/**
+ * Get the api-ape client - initializes on first call
+ */
+export async function getApeClient() {
+    if (apeClient) {
+        return apeClient
+    }
+
+    if (isConnecting) {
+        return connectionPromise
+    }
+
+    isConnecting = true
+    connectionPromise = initClient()
+
+    try {
+        apeClient = await connectionPromise
+        return apeClient
+    } finally {
+        isConnecting = false
+    }
+}
+
+/**
+ * Initialize the api-ape client
+ */
+async function initClient() {
+    if (typeof window === 'undefined') {
+        return null
+    }
+
+    const module = await import('api-ape/client/connectSocket')
+    const connectSocket = module.default
+
+    // Configure for current port
+    const port = window.location.port || (window.location.protocol === 'https:' ? 443 : 80)
+    connectSocket.configure({ port: parseInt(port, 10) })
+
+    // Connect and get sender/receiver
+    const { sender, setOnReciver } = connectSocket()
+
+    // Enable auto-reconnect
+    connectSocket.autoReconnect()
+
+    console.log('🦍 api-ape client initialized')
+
+    return { sender, setOnReciver, connectSocket }
+}
+
+/**
+ * Check if client is connected
+ */
+export function isConnected() {
+    return apeClient !== null
+}
+
+export default getApeClient

package/example/NextJs/ape/embed.js

@@ -0,0 +1,12 @@
+/**
+ * api-ape embed data
+ */
+
+function createEmbed(clientID, sessionID) {
+    return {
+        clientID,
+        sessionID: sessionID || 'session-' + clientID,
+    }
+}
+
+module.exports = { createEmbed }

package/example/NextJs/ape/index.js

@@ -0,0 +1,23 @@
+/**
+ * api-ape handlers - main export
+ */
+
+const { onConnect, history, online } = require('./onConnect')
+const { createEmbed } = require('./embed')
+const { onReceive } = require('./onReceive')
+const { onSend } = require('./onSend')
+const { onError } = require('./onError')
+const { onDisconnect } = require('./onDisconnect')
+const chat = require('./logic/chat')
+
+module.exports = {
+    onConnect,
+    history,
+    online,
+    createEmbed,
+    onReceive,
+    onSend,
+    onError,
+    onDisconnect,
+    chat
+}

package/example/NextJs/ape/logic/chat.js

@@ -0,0 +1,62 @@
+/**
+ * Chat controller for api-ape
+ * Uses this.broadcastOthers from api-ape
+ */
+
+// In-memory message store
+const messages = []
+const MAX_MESSAGES = 100
+
+/**
+ * Message controller - called when client sends type="message"
+ * Uses this.broadcastOthers to send to all OTHER clients
+ */
+function message(data) {
+    const { user, text } = data
+
+    if (!user || !text) {
+        throw new Error('Missing user or text')
+    }
+
+    const msg = {
+        user,
+        text,
+        time: new Date().toISOString()
+    }
+
+    // Store message
+    messages.push(msg)
+    if (messages.length > MAX_MESSAGES) {
+        messages.shift()
+    }
+
+    // Broadcast to all OTHER clients (exclude sender)
+    // this.broadcastOthers is provided by api-ape!
+    this.broadcastOthers('message', { message: msg })
+
+    // Return to sender (fulfills promise)
+    return { ok: true, message: msg }
+}
+
+/**
+ * Get message history
+ */
+function history() {
+    return messages.slice(-50)
+}
+
+/**
+ * Get history controller - called when client sends type="history"
+ */
+function getHistory() {
+    return {
+        history: history(),
+        users: this.online()
+    }
+}
+
+module.exports = {
+    message,
+    history: getHistory,
+    _history: history  // internal use
+}

package/example/NextJs/ape/onConnect.js

@@ -0,0 +1,69 @@
+/**
+ * api-ape onConnect handler
+ * Creates the handlers object returned from onConnent
+ */
+
+const { createEmbed } = require('./embed')
+const { onReceive } = require('./onReceive')
+const { onSend } = require('./onSend')
+const { onError } = require('./onError')
+const { broadcast, online } = require('api-ape/server/lib/broadcast')
+
+// Get message history from the message controller
+function getHistory() {
+    try {
+        const messageController = require('../api/message')
+        return messageController.getHistory ? messageController.getHistory() : []
+    } catch (e) {
+        return []
+    }
+}
+
+function onConnect(socket, req, send) {
+    const clientID = send.toString()
+    console.log(`🦍 Client connected: ${clientID}`)
+
+    const embed = createEmbed(clientID, req.headers?.['x-session-id'])
+
+    // Send init message with history and user count after a tiny delay
+    // (to ensure client is ready to receive)
+    setTimeout(() => {
+        console.log(`📤 Sending init to ${clientID}, users: ${online()}`)
+        try {
+            send('init', {
+                history: getHistory(),
+                users: online()
+            })
+            console.log(`✅ Init sent to ${clientID}`)
+        } catch (e) {
+            console.error(`❌ Failed to send init:`, e)
+        }
+
+        // Broadcast updated user count to all clients
+        broadcast('users', { count: online() })
+    }, 100)
+
+    return {
+        embed,
+
+        onReceive: (queryId, payload, type) =>
+            onReceive(clientID, queryId, payload, type),
+
+        onSend: (payload, type) =>
+            onSend(clientID, payload, type),
+
+        onError: (errStr) =>
+            onError(clientID, errStr),
+
+        onDisconnent: () => {
+            console.info(`👋 Disconnected [${clientID}]`)
+            // Broadcast updated user count after disconnect
+            // Use setTimeout to ensure client is removed first
+            setTimeout(() => {
+                broadcast('users', { count: online() })
+            }, 50)
+        }
+    }
+}
+
+module.exports = { onConnect }

package/example/NextJs/ape/onDisconnect.js

@@ -0,0 +1,13 @@
+/**
+ * api-ape onDisconnect handler
+ */
+
+const { broadcast, online } = require('./logic/chat')
+
+function onDisconnect(clientID, unsubscribe) {
+    console.info(`👋 Disconnected [${clientID}]`)
+    unsubscribe()
+    broadcast('users', { count: online() })
+}
+
+module.exports = { onDisconnect }

package/example/NextJs/ape/onError.js

@@ -0,0 +1,9 @@
+/**
+ * api-ape onError handler
+ */
+
+function onError(clientID, errStr) {
+    console.error(`🦍 Error [${clientID}]:`, errStr)
+}
+
+module.exports = { onError }

package/example/NextJs/ape/onReceive.js

@@ -0,0 +1,15 @@
+/**
+ * api-ape onReceive handler
+ */
+
+function onReceive(clientID, queryId, payload, type) {
+    console.log(`📥 [${clientID}] ${type}:`, JSON.stringify(payload).slice(0, 50))
+
+    return (err, result) => {
+        if (err) {
+            console.error(`❌ [${clientID}] Error:`, err.message)
+        }
+    }
+}
+
+module.exports = { onReceive }

package/example/NextJs/ape/onSend.js

@@ -0,0 +1,15 @@
+/**
+ * api-ape onSend handler
+ */
+
+function onSend(clientID, payload, type) {
+    console.log(`📤 [${clientID}] ${type}`)
+
+    return (err, result) => {
+        if (err) {
+            console.error(`❌ [${clientID}] Send failed:`, err.message)
+        }
+    }
+}
+
+module.exports = { onSend }

package/example/NextJs/api/message.js

@@ -0,0 +1,44 @@
+/**
+ * Message controller for api-ape
+ * Called when client sends type="message"
+ * 
+ * Uses this.broadcastOthers from api-ape to broadcast to all other clients
+ */
+
+// In-memory message store
+const messages = []
+const MAX_MESSAGES = 100
+
+/**
+ * Message handler - receives { user, text } from client
+ * Broadcasts to all OTHER clients, returns to sender
+ */
+module.exports = function message(data) {
+    const { user, text } = data
+
+    if (!user || !text) {
+        throw new Error('Missing user or text')
+    }
+
+    const msg = {
+        user,
+        text,
+        time: new Date().toISOString()
+    }
+
+    // Store message
+    messages.push(msg)
+    if (messages.length > MAX_MESSAGES) {
+        messages.shift()
+    }
+
+    // Broadcast to all OTHER clients (exclude sender)
+    // this.broadcastOthers is provided by api-ape!
+    this.broadcastOthers('message', { message: msg })
+
+    // Return to sender (fulfills promise)
+    return { ok: true, message: msg }
+}
+
+// Export history for other uses
+module.exports.getHistory = () => messages.slice(-50)