api-ape 2.1.0 → 2.2.2

package/client/browser.js

@@ -1,33 +1,23 @@
 import connectSocket from './connectSocket.js'
 
-// Auto-configure for current page
-const port = window.location.port || (window.location.protocol === 'https:' ? 443 : 80)
-connectSocket.configure({ port: parseInt(port, 10) })
-
 const { sender, setOnReciver, onConnectionChange, getTransport } = connectSocket()
 connectSocket.autoReconnect()
 
 // Global API - use defineProperty to bypass Proxy interception
-window.ape = sender
-Object.defineProperty(window.ape, 'on', {
+window.api = sender
+Object.defineProperty(window.api, 'on', {
     value: setOnReciver,
     writable: false,
     enumerable: false,
     configurable: false
 })
-Object.defineProperty(window.ape, 'onConnectionChange', {
+Object.defineProperty(window.api, 'onConnectionChange', {
     value: onConnectionChange,
     writable: false,
     enumerable: false,
     configurable: false
 })
-Object.defineProperty(window.ape, 'configure', {
-    value: connectSocket.configure,
-    writable: false,
-    enumerable: false,
-    configurable: false
-})
-Object.defineProperty(window.ape, 'getTransport', {
+Object.defineProperty(window.api, 'getTransport', {
     value: getTransport,
     writable: false,
     enumerable: false,

package/client/connectSocket.js

@@ -1,19 +1,23 @@
 import messageHash from '../utils/messageHash'
 import jss from '../utils/jss'
-import { createStreamingTransport, configure as configureStreaming } from './transports/streaming'
+import { createStreamingTransport } from './transports/streaming'
 
 let connect;
 
 // Connection state enum
 const ConnectionState = {
+  Offline: 'offline',         // navigator.onLine = false
+  Walled: 'walled',           // Captive portal detected (ping failed)
   Disconnected: 'disconnected',
   Connecting: 'connecting',
   Connected: 'connected',
   Closing: 'closing'
 }
 
-// Connection state tracking
-let connectionState = ConnectionState.Disconnected
+// Connection state tracking - start with offline check
+let connectionState = (typeof navigator !== 'undefined' && !navigator.onLine)
+  ? ConnectionState.Offline
+  : ConnectionState.Disconnected
 const connectionChangeListeners = []
 
 function notifyConnectionChange(newState) {
@@ -24,50 +28,129 @@ function notifyConnectionChange(newState) {
 }
 
 // Configuration
-let configuredPort = null
-let configuredHost = null
 let configuredTransport = 'auto' // 'auto' | 'websocket' | 'polling'
 
 // Transport state
 let currentTransport = null // 'websocket' | 'polling'
 let streamingTransport = null
 let wsRetryTimer = null
+let networkCheckTimer = null
 const WS_FALLBACK_TIMEOUT = 4000 // Time to wait for WS before fallback
 const WS_RETRY_INTERVAL = 30000  // Retry WebSocket while in polling mode
+const PING_TIMEOUT = 3000        // Timeout for ping check
+const MAX_PING_CLOCK_SKEW = 60000 // Max allowed time difference (60s)
 
 /**
- * Configure api-ape client connection
- * @param {object} opts
- * @param {number} [opts.port] - WebSocket port (default: 9010 for local, 443/80 for remote)
- * @param {string} [opts.host] - WebSocket host (default: auto-detect from window.location)
- * @param {string} [opts.transport] - Transport mode: 'auto' | 'websocket' | 'polling'
+ * Check if running in dev/local mode
  */
-function configure(opts = {}) {
-  if (opts.port) {
-    configuredPort = opts.port
-    configureStreaming({ port: opts.port })
-  }
-  if (opts.host) {
-    configuredHost = opts.host
-    configureStreaming({ host: opts.host })
-  }
-  if (opts.transport) {
-    configuredTransport = opts.transport
+function isDevMode() {
+  if (typeof window === 'undefined') return false
+  return ['localhost', '127.0.0.1', '[::1]'].includes(window.location.hostname)
+}
+
+/**
+ * Build ping URL for captive portal detection
+ */
+function getPingUrl() {
+  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/ping`
+}
+
+/**
+ * Check for captive portal by pinging /api/ape/ping
+ * Returns 'ok' if real internet, 'walled' if captive portal detected
+ */
+async function checkCaptivePortal() {
+  try {
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), PING_TIMEOUT)
+
+    const response = await fetch(getPingUrl(), {
+      cache: 'no-store',
+      signal: controller.signal
+    })
+    clearTimeout(timeoutId)
+
+    if (!response.ok) {
+      if (isDevMode()) {
+        console.error('🦍 [DEV] Ping failed: HTTP', response.status)
+      }
+      return 'walled'
+    }
+
+    const data = await response.json()
+
+    // Verify response is genuine (not a captive portal redirect page)
+    if (data?.ok !== true) {
+      if (isDevMode()) {
+        console.error('🦍 [DEV] Ping failed: invalid response', data)
+      }
+      return 'walled'
+    }
+
+    // Validate timestamp to detect proxy replay attacks
+    if (typeof data.ts === 'number') {
+      const now = Date.now()
+      const skew = Math.abs(now - data.ts)
+      if (skew > MAX_PING_CLOCK_SKEW) {
+        if (isDevMode()) {
+          console.error('🦍 [DEV] Ping failed: timestamp too old/stale (skew:', skew, 'ms)')
+        }
+        return 'walled'
+      }
+    }
+
+    return 'ok'
+  } catch (err) {
+    if (isDevMode()) {
+      console.error('🦍 [DEV] Ping failed:', err.message || err)
+    }
+    return 'walled'
   }
 }
 
+/**
+ * Setup navigator.onLine event listeners
+ */
+function setupOnlineListeners() {
+  if (typeof window === 'undefined') return
+
+  window.addEventListener('online', () => {
+    console.log('🦍 Browser went online, checking network...')
+    // Trigger reconnection attempt
+    attemptConnection()
+  })
+
+  window.addEventListener('offline', () => {
+    console.log('🦍 Browser went offline')
+    notifyConnectionChange(ConnectionState.Offline)
+  })
+}
+
+// Setup listeners on module load (browser only)
+if (typeof window !== 'undefined') {
+  setupOnlineListeners()
+}
+
+
+
 /**
  * Get WebSocket URL - auto-detects from window.location, keeps /api/ape path
  */
 function getSocketUrl() {
-  const hostname = configuredHost || window.location.hostname
+  const hostname = window.location.hostname
   const localServers = ["localhost", "127.0.0.1", "[::1]"]
   const isLocal = localServers.includes(hostname)
   const isHttps = window.location.protocol === "https:"
 
   // Default port: 9010 for local dev, otherwise use window.location.port or implicit 443/80
-  const defaultPort = isLocal ? 9010 : (window.location.port || (isHttps ? 443 : 80))
-  const port = configuredPort || defaultPort
+  const port = isLocal ? 9010 : (window.location.port || (isHttps ? 443 : 80))
 
   // Build URL - keep /api/ape path
   const protocol = isHttps ? "wss" : "ws"
@@ -83,7 +166,7 @@ const totalRequestTimeout = 10000
 
 const joinKey = "/"
 // Properties accessed directly on `ape` that should NOT be intercepted
-const reservedKeys = new Set(['on', 'onConnectionChange', 'configure', 'getTransport'])
+const reservedKeys = new Set(['on', 'onConnectionChange', 'getTransport'])
 const handler = {
   get(fn, key) {
     // Skip proxy interception for reserved keys - return actual property
@@ -387,7 +470,7 @@ function cleanLinkedKeys(obj) {
 /**
  * Fetch binary resources and hydrate data object
  */
-async function fetchLinkedResources(data, hostId) {
+async function fetchLinkedResources(data, clientId) {
   const resources = findLinkedResources(data)
 
   if (resources.length === 0) {
@@ -398,11 +481,10 @@ async function fetchLinkedResources(data, hostId) {
 
   const cleanedData = cleanLinkedKeys(data)
 
-  const hostname = configuredHost || window.location.hostname
+  const hostname = window.location.hostname
   const isLocal = ["localhost", "127.0.0.1", "[::1]"].includes(hostname)
   const isHttps = window.location.protocol === "https:"
-  const defaultPort = isLocal ? 9010 : (window.location.port || (isHttps ? 443 : 80))
-  const port = configuredPort || defaultPort
+  const port = isLocal ? 9010 : (window.location.port || (isHttps ? 443 : 80))
   const protocol = isHttps ? "https" : "http"
   const portSuffix = (isLocal || (port !== 80 && port !== 443)) ? `:${port}` : ""
   const baseUrl = `${protocol}://${hostname}${portSuffix}`
@@ -412,7 +494,7 @@ async function fetchLinkedResources(data, hostId) {
       const response = await fetch(`${baseUrl}/api/ape/data/${hash}`, {
         credentials: 'include',
         headers: {
-          'X-Ape-Host-Id': hostId || ''
+          'X-Ape-Client-Id': clientId || ''
         }
       })
 
@@ -431,17 +513,46 @@ async function fetchLinkedResources(data, hostId) {
   return cleanedData
 }
 
-function connectSocket() {
-  // Skip if already connected or connecting
-  if (__socket && __socket.readyState !== WebSocket.CLOSED) {
-    return buildClientInterface()
-  }
-  if (currentTransport === 'polling' && streamingTransport?.isConnected()) {
-    return buildClientInterface()
+/**
+ * Attempt to establish connection with network pre-checks
+ */
+async function attemptConnection() {
+  // Check if browser is online
+  if (typeof navigator !== 'undefined' && !navigator.onLine) {
+    notifyConnectionChange(ConnectionState.Offline)
+    return
   }
 
+  // Perform captive portal check
   notifyConnectionChange(ConnectionState.Connecting)
+  const pingResult = await checkCaptivePortal()
 
+  if (pingResult === 'walled') {
+    notifyConnectionChange(ConnectionState.Walled)
+    // Retry network check periodically
+    scheduleNetworkRetry()
+    return
+  }
+
+  // Network is good, proceed with socket connection
+  proceedWithConnection()
+}
+
+/**
+ * Schedule a retry of network check (for walled/offline states)
+ */
+function scheduleNetworkRetry() {
+  if (networkCheckTimer) return
+  networkCheckTimer = setTimeout(() => {
+    networkCheckTimer = null
+    attemptConnection()
+  }, WS_RETRY_INTERVAL)
+}
+
+/**
+ * Proceed with WebSocket/polling connection after network checks pass
+ */
+function proceedWithConnection() {
   // Determine which transport to use
   if (configuredTransport === 'polling') {
     switchToStreaming()
@@ -449,6 +560,22 @@ function connectSocket() {
     // 'auto' or 'websocket' - try WebSocket first
     tryWebSocket(false)
   }
+}
+
+function connectSocket() {
+  // Skip if already connected or connecting
+  if (__socket && __socket.readyState !== WebSocket.CLOSED) {
+    return buildClientInterface()
+  }
+  if (currentTransport === 'polling' && streamingTransport?.isConnected()) {
+    return buildClientInterface()
+  }
+  if (connectionState === ConnectionState.Connecting) {
+    return buildClientInterface()
+  }
+
+  // Start connection with network pre-checks
+  attemptConnection()
 
   return buildClientInterface()
 }
@@ -547,11 +674,10 @@ async function uploadBinaryData(queryId, uploads) {
   if (uploads.length === 0) return
 
   // Build base URL
-  const hostname = configuredHost || window.location.hostname
+  const hostname = window.location.hostname
   const isLocal = ["localhost", "127.0.0.1", "[::1]"].includes(hostname)
   const isHttps = window.location.protocol === "https:"
-  const defaultPort = isLocal ? 9010 : (window.location.port || (isHttps ? 443 : 80))
-  const port = configuredPort || defaultPort
+  const port = isLocal ? 9010 : (window.location.port || (isHttps ? 443 : 80))
   const protocol = isHttps ? "https" : "http"
   const portSuffix = (isLocal || (port !== 80 && port !== 443)) ? `:${port}` : ""
   const baseUrl = `${protocol}://${hostname}${portSuffix}`
@@ -723,9 +849,8 @@ function buildClientInterface() {
 }
 
 connectSocket.autoReconnect = () => reconnect = true
-connectSocket.configure = configure
 connectSocket.ConnectionState = ConnectionState
 connect = connectSocket
 
 export default connect;
-export { configure, ConnectionState };
+export { ConnectionState };

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

@@ -5,29 +5,16 @@ import jss from '../../utils/jss'
  * Uses fetch + ReadableStream for receiving, POST for sending
  */
 
-// Configuration
-let configuredPort = null
-let configuredHost = null
-
-/**
- * Configure transport connection options
- */
-function configure(opts = {}) {
-    if (opts.port) configuredPort = opts.port
-    if (opts.host) configuredHost = opts.host
-}
-
 /**
  * Get base URL for polling endpoints
  */
 function getPollUrl() {
-    const hostname = configuredHost || window.location.hostname
+    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 defaultPort = isLocal ? 9010 : (window.location.port || (isHttps ? 443 : 80))
-    const port = configuredPort || defaultPort
+    const port = isLocal ? 9010 : (window.location.port || (isHttps ? 443 : 80))
 
     const protocol = isHttps ? "https" : "http"
     const portSuffix = (isLocal || (port !== 80 && port !== 443)) ? `:${port}` : ""
@@ -250,4 +237,4 @@ function createStreamingTransport() {
     }
 }
 
-export { createStreamingTransport, configure, getPollUrl }
+export { createStreamingTransport, getPollUrl }