api-ape 2.0.0 → 2.2.2

package/client/index.js

@@ -0,0 +1,171 @@
+/**
+ * Unified api-ape export for browser
+ * 
+ * Auto-detects browser environment, initializes client, and buffers
+ * calls until the connection is ready. No more getApeClient().then()!
+ * 
+ * Usage:
+ *   import api from 'api-ape'
+ *   
+ *   // Properties are proxied - calls buffer until connected
+ *   api.message({ user: 'Bob', text: 'Hello!' })
+ *   
+ *   // Subscribe to broadcasts
+ *   api.on('message', (data) => console.log(data))
+ *   
+ *   // Check connection state
+ *   api.onConnectionChange((state) => console.log(state))
+ */
+
+// Only run this in browser environments
+const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined'
+
+let clientPromise = null
+let resolvedClient = null
+const bufferedCalls = []
+const bufferedReceivers = []
+const connectionChangeHandlers = []
+let currentConnectionState = 'disconnected'
+
+/**
+ * Initialize the client (called once on first use)
+ */
+function getClient() {
+    if (clientPromise) return clientPromise
+
+    if (!isBrowser) {
+        // Return a dummy object for SSR
+        return Promise.resolve(null)
+    }
+
+    clientPromise = (async () => {
+        const connectSocket = (await import('./connectSocket.js')).default
+
+        // Connect
+        const client = connectSocket()
+        connectSocket.autoReconnect()
+
+        // Track connection state
+        client.onConnectionChange((state) => {
+            currentConnectionState = state
+            connectionChangeHandlers.forEach(fn => fn(state))
+        })
+
+        resolvedClient = client
+
+        // Flush buffered receivers
+        bufferedReceivers.forEach(({ type, handler }) => {
+            client.setOnReciver(type, handler)
+        })
+        bufferedReceivers.length = 0
+
+        // Flush buffered calls
+        bufferedCalls.forEach(({ method, args, resolve, reject }) => {
+            try {
+                const result = client.sender[method](...args)
+                if (result && typeof result.then === 'function') {
+                    result.then(resolve).catch(reject)
+                } else {
+                    resolve(result)
+                }
+            } catch (err) {
+                reject(err)
+            }
+        })
+        bufferedCalls.length = 0
+
+        return client
+    })()
+
+    return clientPromise
+}
+
+/**
+ * Create a sender proxy that buffers calls until client is ready
+ */
+const senderProxy = new Proxy({}, {
+    get(target, prop) {
+        // Reserved properties
+        if (prop === 'on') return on
+        if (prop === 'onConnectionChange') return onConnectionChange
+        if (prop === 'getTransport') return () => resolvedClient?.getTransport?.() || null
+        if (prop === 'then' || prop === 'catch') return undefined // Not a Promise
+
+        // Return a function that either calls directly or buffers
+        return (...args) => {
+            // If client is ready, call directly
+            if (resolvedClient) {
+                return resolvedClient.sender[prop](...args)
+            }
+
+            // Buffer the call and return a Promise
+            return new Promise((resolve, reject) => {
+                bufferedCalls.push({ method: prop, args, resolve, reject })
+                // Ensure client is initializing
+                getClient()
+            })
+        }
+    }
+})
+
+/**
+ * Subscribe to broadcasts from the server
+ * @param {string} type - Broadcast type to listen for
+ * @param {Function} handler - Handler function
+ */
+function on(type, handler) {
+    if (resolvedClient) {
+        resolvedClient.setOnReciver(type, handler)
+    } else {
+        bufferedReceivers.push({ type, handler })
+        getClient()
+    }
+}
+
+/**
+ * Subscribe to connection state changes
+ * @param {Function} handler - Called with state: 'offline' | 'walled' | 'disconnected' | 'connecting' | 'connected'
+ * @returns {Function} Unsubscribe function
+ */
+function onConnectionChange(handler) {
+    connectionChangeHandlers.push(handler)
+    // Immediately call with current state
+    handler(currentConnectionState)
+
+    // If client exists, also register with it
+    if (resolvedClient) {
+        return resolvedClient.onConnectionChange(handler)
+    }
+
+    // Ensure client is initializing
+    getClient()
+
+    // Return unsubscribe function
+    return () => {
+        const idx = connectionChangeHandlers.indexOf(handler)
+        if (idx > -1) connectionChangeHandlers.splice(idx, 1)
+    }
+}
+
+// Define properties on the proxy to avoid Proxy interception issues
+Object.defineProperty(senderProxy, 'on', {
+    value: on,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})
+
+Object.defineProperty(senderProxy, 'onConnectionChange', {
+    value: onConnectionChange,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})
+
+// Auto-initialize in browser
+if (isBrowser) {
+    getClient()
+}
+
+export default senderProxy
+export { on, onConnectionChange, getClient }

package/client/transports/streaming.js

@@ -0,0 +1,240 @@
+import jss from '../../utils/jss'
+
+/**
+ * HTTP Streaming transport - fallback when WebSocket is blocked
+ * Uses fetch + ReadableStream for receiving, POST for sending
+ */
+
+/**
+ * Get base URL for polling endpoints
+ */
+function getPollUrl() {
+    const hostname = window.location.hostname
+    const localServers = ["localhost", "127.0.0.1", "[::1]"]
+    const isLocal = localServers.includes(hostname)
+    const isHttps = window.location.protocol === "https:"
+
+    const port = isLocal ? 9010 : (window.location.port || (isHttps ? 443 : 80))
+
+    const protocol = isHttps ? "https" : "http"
+    const portSuffix = (isLocal || (port !== 80 && port !== 443)) ? `:${port}` : ""
+
+    return `${protocol}://${hostname}${portSuffix}/api/ape/poll`
+}
+
+/**
+ * Parse JSON objects from a streaming buffer by counting braces
+ * Handles strings containing braces correctly
+ */
+function parseStreamBuffer(buffer) {
+    const messages = []
+    let start = -1
+    let depth = 0
+    let inString = false
+    let escaped = false
+
+    for (let i = 0; i < buffer.length; i++) {
+        const char = buffer[i]
+
+        if (escaped) {
+            escaped = false
+            continue
+        }
+
+        if (char === '\\' && inString) {
+            escaped = true
+            continue
+        }
+
+        if (char === '"') {
+            inString = !inString
+            continue
+        }
+
+        if (inString) continue
+
+        if (char === '{') {
+            if (depth === 0) {
+                start = i
+            }
+            depth++
+        } else if (char === '}') {
+            depth--
+            if (depth === 0 && start !== -1) {
+                const jsonStr = buffer.slice(start, i + 1)
+                try {
+                    messages.push(jss.parse(jsonStr))
+                } catch (e) {
+                    console.error('🦍 Failed to parse stream message:', e)
+                }
+                start = -1
+            }
+        }
+    }
+
+    // Return remaining buffer (incomplete message)
+    const remaining = start !== -1 ? buffer.slice(start) : ''
+    return { messages, remaining }
+}
+
+/**
+ * Create streaming transport instance
+ */
+function createStreamingTransport() {
+    let isActive = false
+    let abortController = null
+    let streamBuffer = ''
+    let reconnectTimer = null
+
+    // Callbacks
+    let onMessage = () => { }
+    let onOpen = () => { }
+    let onClose = () => { }
+    let onError = () => { }
+
+    /**
+     * Start the streaming connection
+     */
+    async function connect() {
+        if (isActive) return
+
+        isActive = true
+        abortController = new AbortController()
+
+        try {
+            const response = await fetch(getPollUrl(), {
+                method: 'GET',
+                credentials: 'include',
+                signal: abortController.signal,
+                headers: {
+                    'Accept': 'application/json'
+                }
+            })
+
+            if (!response.ok) {
+                throw new Error(`Stream connect failed: ${response.status}`)
+            }
+
+            onOpen()
+
+            const reader = response.body.getReader()
+            const decoder = new TextDecoder()
+
+            async function read() {
+                while (isActive) {
+                    try {
+                        const { done, value } = await reader.read()
+
+                        if (done) {
+                            // Stream ended - reconnect
+                            scheduleReconnect()
+                            return
+                        }
+
+                        streamBuffer += decoder.decode(value, { stream: true })
+                        const { messages, remaining } = parseStreamBuffer(streamBuffer)
+                        streamBuffer = remaining
+
+                        for (const msg of messages) {
+                            // Skip heartbeat messages
+                            if (msg.type === '__heartbeat__') continue
+                            onMessage(msg)
+                        }
+                    } catch (readErr) {
+                        if (readErr.name === 'AbortError') return
+                        console.error('🦍 Stream read error:', readErr)
+                        scheduleReconnect()
+                        return
+                    }
+                }
+            }
+
+            read()
+
+        } catch (err) {
+            if (err.name === 'AbortError') return
+
+            console.error('🦍 Stream connection error:', err)
+            onError(err)
+            scheduleReconnect()
+        }
+    }
+
+    /**
+     * Schedule reconnection with small delay
+     */
+    function scheduleReconnect() {
+        if (!isActive) return
+
+        if (reconnectTimer) {
+            clearTimeout(reconnectTimer)
+        }
+
+        reconnectTimer = setTimeout(() => {
+            if (isActive) {
+                connect()
+            }
+        }, 500)
+    }
+
+    /**
+     * Send a message via POST
+     */
+    async function send(type, data, createdAt) {
+        const payload = {
+            type,
+            data,
+            createdAt: new Date(createdAt)
+        }
+
+        const response = await fetch(getPollUrl(), {
+            method: 'POST',
+            credentials: 'include',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: jss.stringify(payload)
+        })
+
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }))
+            throw new Error(error.error || `Request failed: ${response.status}`)
+        }
+
+        const result = jss.parse(await response.text())
+        return result.data
+    }
+
+    /**
+     * Close the streaming connection
+     */
+    function close() {
+        isActive = false
+
+        if (reconnectTimer) {
+            clearTimeout(reconnectTimer)
+            reconnectTimer = null
+        }
+
+        if (abortController) {
+            abortController.abort()
+            abortController = null
+        }
+
+        streamBuffer = ''
+        onClose()
+    }
+
+    return {
+        connect,
+        send,
+        close,
+        isConnected: () => isActive,
+        set onMessage(fn) { onMessage = fn },
+        set onOpen(fn) { onOpen = fn },
+        set onClose(fn) { onClose = fn },
+        set onError(fn) { onError = fn }
+    }
+}
+
+export { createStreamingTransport, getPollUrl }