api-ape 3.0.1 → 4.1.0

package/client/connection/fileUtils.js

@@ -0,0 +1,346 @@
+/**
+ * @fileoverview Common utilities for file handling in api-ape client
+ *
+ * This module provides shared utility functions used by both file upload
+ * (fileHandling.js) and file download (fileDownload.js) modules.
+ *
+ * ## Key Functions
+ *
+ * - **Binary Detection**: `isBinaryData()`, `getBinaryTag()`
+ * - **Hash Generation**: `generateUploadHash()`
+ * - **Object Traversal**: `setValueAtPath()`, `findTaggedProps()`, `cleanTaggedKeys()`
+ *
+ * ## Tag System
+ *
+ * api-ape uses special key suffixes to mark binary data references:
+ * - `<!L>` - Server-linked binary (download from server)
+ * - `<!F>` - File share (client-to-client transfer)
+ * - `<!A>` - ArrayBuffer upload
+ * - `<!B>` - Blob upload
+ *
+ * @module client/connection/fileUtils
+ * @see {@link module:client/connection/fileHandling} for upload processing
+ * @see {@link module:client/connection/fileDownload} for download processing
+ *
+ * @example
+ * import {
+ *   isBinaryData,
+ *   findTaggedProps,
+ *   setValueAtPath
+ * } from './fileUtils'
+ *
+ * // Check for binary data
+ * const data = new ArrayBuffer(100)
+ * console.log(isBinaryData(data)) // true
+ *
+ * // Find tagged properties in response
+ * const response = { 'image<!L>': 'abc123', name: 'photo.jpg' }
+ * const tags = findTaggedProps(response, 'L')
+ * // [{ path: 'image', hash: 'abc123', originalKey: 'image<!L>' }]
+ */
+
+/**
+ * Check if a value is binary data
+ *
+ * Detects ArrayBuffer, TypedArray views (Uint8Array, Int32Array, etc.),
+ * and Blob objects. Used to determine if a value needs special handling
+ * during serialization.
+ *
+ * @param {any} value - The value to check
+ * @returns {boolean} True if the value is binary data, false otherwise
+ *
+ * @example
+ * // ArrayBuffer
+ * isBinaryData(new ArrayBuffer(10))  // true
+ *
+ * // TypedArray views
+ * isBinaryData(new Uint8Array(10))   // true
+ * isBinaryData(new Float32Array(10)) // true
+ *
+ * // Blob (browser only)
+ * isBinaryData(new Blob(['hello']))  // true
+ *
+ * // Non-binary
+ * isBinaryData('string')             // false
+ * isBinaryData({ key: 'value' })     // false
+ * isBinaryData(null)                 // false
+ * isBinaryData(undefined)            // false
+ */
+export function isBinaryData(value) {
+  if (value === null || value === undefined) return false;
+  return (
+    value instanceof ArrayBuffer ||
+    ArrayBuffer.isView(value) ||
+    (typeof Blob !== "undefined" && value instanceof Blob)
+  );
+}
+
+/**
+ * Get the binary type tag for a value
+ *
+ * Returns a single character tag indicating the binary data type:
+ * - `'A'` for ArrayBuffer and TypedArray views
+ * - `'B'` for Blob objects
+ *
+ * This tag is used in the wire protocol to indicate how to
+ * reconstruct the binary data on the receiving end.
+ *
+ * @param {ArrayBuffer|ArrayBufferView|Blob} value - The binary value to tag
+ * @returns {'A'|'B'} The type tag character
+ *
+ * @example
+ * getBinaryTag(new ArrayBuffer(10))       // 'A'
+ * getBinaryTag(new Uint8Array(10))        // 'A'
+ * getBinaryTag(new Blob(['hello']))       // 'B'
+ *
+ * @example
+ * // Used when building upload metadata
+ * const tag = getBinaryTag(fileData)
+ * const key = `attachment<!${tag}>`  // 'attachment<!A>' or 'attachment<!B>'
+ */
+export function getBinaryTag(value) {
+  if (typeof Blob !== "undefined" && value instanceof Blob) return "B";
+  return "A";
+}
+
+/**
+ * Generate a simple hash for binary upload path identification
+ *
+ * Creates a short hash string from a path string, used to uniquely
+ * identify binary data uploads. Uses a simple string hashing algorithm
+ * with base-36 encoding for compact representation.
+ *
+ * Note: This is not cryptographically secure - it's for identification only.
+ *
+ * @param {string} path - The property path to hash (e.g., 'user.avatar')
+ * @returns {string} Base-36 encoded hash string
+ *
+ * @example
+ * generateUploadHash('image')           // e.g., 'k3m9x'
+ * generateUploadHash('user.avatar')     // e.g., 'p7n2w'
+ * generateUploadHash('files.0')         // e.g., 'q1r8t'
+ *
+ * @example
+ * // Used in upload processing
+ * const hash = generateUploadHash('documents.contract')
+ * const uploadUrl = `/api/ape/data/${queryId}/${hash}`
+ */
+export function generateUploadHash(path) {
+  let hash = 0;
+  for (let i = 0; i < path.length; i++) {
+    const char = path.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash; // Convert to 32-bit integer
+  }
+  return Math.abs(hash).toString(36);
+}
+
+/**
+ * Set a value at a nested dot-notation path in an object
+ *
+ * Traverses an object following a dot-separated path and sets
+ * the value at the final key. The path must be valid (all intermediate
+ * objects must exist).
+ *
+ * @param {Object} obj - The object to modify
+ * @param {string} path - Dot-notation path (e.g., 'user.profile.avatar')
+ * @param {any} value - The value to set at the path
+ * @returns {void}
+ * @throws {TypeError} If intermediate path segments don't exist
+ *
+ * @example
+ * const data = { user: { profile: { name: 'Alice' } } }
+ *
+ * setValueAtPath(data, 'user.profile.avatar', new ArrayBuffer(100))
+ * // data.user.profile.avatar is now the ArrayBuffer
+ *
+ * @example
+ * // Simple path
+ * const obj = { image: 'placeholder' }
+ * setValueAtPath(obj, 'image', binaryData)
+ *
+ * @example
+ * // Array index path
+ * const obj = { files: [null, null] }
+ * setValueAtPath(obj, 'files.0', fileBuffer)
+ * setValueAtPath(obj, 'files.1', anotherBuffer)
+ */
+export function setValueAtPath(obj, path, value) {
+  const parts = path.split(".");
+  let current = obj;
+
+  // Navigate to parent of target property
+  for (let i = 0; i < parts.length - 1; i++) {
+    current = current[parts[i]];
+  }
+
+  // Set the value at the final key
+  current[parts[parts.length - 1]] = value;
+}
+
+/**
+ * Find properties with a specific tag suffix in a nested object
+ *
+ * Recursively searches through an object (including arrays) for keys
+ * ending with a tag suffix like `<!L>`, `<!F>`, `<!A>`, or `<!B>`.
+ * Returns information about each tagged property found.
+ *
+ * ## Tag Types
+ * - `L` - Linked binary resource (server sends hash, client downloads)
+ * - `F` - File share (client-to-client transfer)
+ * - `A` - ArrayBuffer upload marker
+ * - `B` - Blob upload marker
+ *
+ * @param {Object|Array|any} obj - The object to search
+ * @param {string} tag - The tag to look for (without <! and >)
+ * @param {string} [path=''] - Current path (used internally for recursion)
+ * @returns {Array<{path: string, hash: string, originalKey: string}>} Array of found tagged properties
+ *
+ * @example
+ * // Find server-linked binary references
+ * const response = {
+ *   name: 'Report',
+ *   'pdf<!L>': 'hash123',
+ *   'thumbnail<!L>': 'hash456'
+ * }
+ *
+ * const links = findTaggedProps(response, 'L')
+ * // Returns:
+ * // [
+ * //   { path: 'pdf', hash: 'hash123', originalKey: 'pdf<!L>' },
+ * //   { path: 'thumbnail', hash: 'hash456', originalKey: 'thumbnail<!L>' }
+ * // ]
+ *
+ * @example
+ * // Find nested tagged properties
+ * const data = {
+ *   user: {
+ *     'avatar<!L>': 'avatarHash',
+ *     documents: [
+ *       { 'file<!L>': 'doc1Hash' },
+ *       { 'file<!L>': 'doc2Hash' }
+ *     ]
+ *   }
+ * }
+ *
+ * const links = findTaggedProps(data, 'L')
+ * // Returns paths: 'user.avatar', 'user.documents.0.file', 'user.documents.1.file'
+ *
+ * @example
+ * // Find file share tags
+ * const message = { 'attachment<!F>': 'shareHash123' }
+ * const shares = findTaggedProps(message, 'F')
+ */
+export function findTaggedProps(obj, tag, path = "") {
+  const results = [];
+
+  // Base case: null, undefined, or non-object
+  if (obj === null || obj === undefined || typeof obj !== "object") {
+    return results;
+  }
+
+  // Handle arrays - recurse into each element
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      results.push(
+        ...findTaggedProps(obj[i], tag, path ? `${path}.${i}` : String(i)),
+      );
+    }
+    return results;
+  }
+
+  // Handle objects - check each key for tag suffix
+  const suffix = `<!${tag}>`;
+
+  for (const key of Object.keys(obj)) {
+    if (key.endsWith(suffix)) {
+      // Found a tagged key - extract the clean name and hash
+      const cleanKey = key.slice(0, -4); // Remove <!X> suffix (4 chars)
+      results.push({
+        path: path ? `${path}.${cleanKey}` : cleanKey,
+        hash: obj[key],
+        originalKey: key,
+      });
+    } else {
+      // Not tagged - recurse into value
+      results.push(
+        ...findTaggedProps(obj[key], tag, path ? `${path}.${key}` : key),
+      );
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Clean tagged keys from an object (rename `key<!X>` to `key`)
+ *
+ * Creates a new object with tag suffixes removed from keys.
+ * Recursively processes nested objects and arrays.
+ *
+ * This is used after finding tagged properties to create a clean
+ * object structure where the tags have been replaced with actual values.
+ *
+ * @param {Object|Array|any} obj - The object to clean
+ * @param {string} tag - The tag to remove (without <! and >)
+ * @returns {Object|Array|any} New object with cleaned keys
+ *
+ * @example
+ * // Clean L-tagged keys
+ * const response = {
+ *   name: 'Photo',
+ *   'image<!L>': 'hash123',
+ *   size: 1024
+ * }
+ *
+ * const cleaned = cleanTaggedKeys(response, 'L')
+ * // Returns: { name: 'Photo', image: 'hash123', size: 1024 }
+ *
+ * @example
+ * // Nested cleaning
+ * const data = {
+ *   user: {
+ *     'avatar<!L>': 'avatarHash'
+ *   }
+ * }
+ *
+ * const cleaned = cleanTaggedKeys(data, 'L')
+ * // Returns: { user: { avatar: 'avatarHash' } }
+ *
+ * @example
+ * // Array handling
+ * const files = [
+ *   { 'data<!L>': 'hash1' },
+ *   { 'data<!L>': 'hash2' }
+ * ]
+ *
+ * const cleaned = cleanTaggedKeys(files, 'L')
+ * // Returns: [{ data: 'hash1' }, { data: 'hash2' }]
+ */
+export function cleanTaggedKeys(obj, tag) {
+  // Base case: null, undefined, or non-object - return as-is
+  if (obj === null || obj === undefined || typeof obj !== "object") {
+    return obj;
+  }
+
+  // Handle arrays - map each element
+  if (Array.isArray(obj)) {
+    return obj.map((item) => cleanTaggedKeys(item, tag));
+  }
+
+  // Handle objects - process each key
+  const cleaned = {};
+  const suffix = `<!${tag}>`;
+
+  for (const key of Object.keys(obj)) {
+    if (key.endsWith(suffix)) {
+      // Remove the tag suffix from the key
+      cleaned[key.slice(0, -4)] = obj[key];
+    } else {
+      // Keep key as-is, but recursively clean the value
+      cleaned[key] = cleanTaggedKeys(obj[key], tag);
+    }
+  }
+
+  return cleaned;
+}

package/client/connection/files.md

@@ -0,0 +1,71 @@
+# Connection Module Files
+
+This module handles the core mechanics of maintaining a WebSocket connection to an api-ape server. It manages connection state, message sending, request/response correlation, and binary file transfers.
+
+## Guidelines
+
+- **Browser-safe only** — All code must run in browsers without Node.js APIs
+- **State consistency** — Connection state changes must flow through `state.js`
+- **QueryId correlation** — All requests must use `sender.js` for proper response matching
+- **Binary handling** — File transfers use the tag system (`<!B>`, `<!A>`, `<!L>`) — coordinate with `fileHandling.js`
+- **Network detection** — Changes to connectivity detection should account for captive portals
+
+## Directory Structure
+
+```
+connection/
+├── fileDownload.js    # Binary file download handling
+├── fileHandling.js    # File upload/download coordination
+├── fileUtils.js       # File transfer utilities
+├── messageHandler.js  # Message processing and dispatch
+├── network.js         # Network state detection
+├── proxy.js           # Proxy-based API generation
+├── sender.js          # Message sending with queryId correlation
+├── state.js           # Connection state machine
+└── subscriptions.js   # Pub/sub subscription manager
+```
+
+## Files
+
+### `proxy.js`
+
+Creates the Proxy-based API that allows `api.users.list()` syntax. Intercepts property access and method calls, converting them into WebSocket messages with the appropriate endpoint path.
+
+### `sender.js`
+
+Handles message serialization and request/response correlation. Generates unique `queryId` for each request, tracks pending requests, manages timeouts, and resolves Promises when responses arrive.
+
+### `state.js`
+
+Connection state machine that tracks the current connection status. Emits state change events and provides the `onConnectionChange` callback functionality.
+
+**States:** `offline` → `connecting` → `connected` → `disconnected` → `walled`
+
+### `network.js`
+
+Detects network conditions to provide accurate connection state:
+- **Offline** — Browser reports no network (`navigator.onLine`)
+- **Walled garden** — Captive portal detected (WiFi login page)
+- **Online** — Full internet connectivity confirmed
+
+### `fileDownload.js`
+
+Handles downloading binary data from the server. When a response contains `<!L>` (link) tags, fetches the binary data via HTTP GET with session cookies for authentication.
+
+### `fileHandling.js`
+
+Coordinates file uploads and downloads by detecting special tags in messages:
+- `<!B>` / `<!A>` — Binary data that needs to be uploaded
+- `<!L>` — Download links that need to be fetched
+
+### `fileUtils.js`
+
+Shared utilities for file transfer operations including content type detection, hash generation, and ArrayBuffer/Buffer conversions.
+
+### `messageHandler.js`
+
+Handles incoming message processing and dispatch. Processes binary data hydration (fetching linked resources) and dispatches messages to registered handlers and subscription callbacks. Provides the `setOnReceiver` function for registering message handlers.
+
+### `subscriptions.js`
+
+Manages channel subscriptions for the chained subscription syntax. Tracks local callbacks per channel, sends subscribe/unsubscribe messages to server, dispatches incoming data to callbacks, and handles resubscription on reconnect.

package/client/connection/messageHandler.js

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Message handling utilities for api-ape client
+ *
+ * Handles incoming message processing, including binary data hydration
+ * and dispatching to registered handlers and subscription callbacks.
+ *
+ * @module client/connection/messageHandler
+ */
+
+import {
+  fetchLinkedResources,
+  fetchSharedFiles,
+} from "./fileDownload";
+import {
+  hasSubscribers,
+  dispatch as dispatchToSubscribers,
+} from "./subscriptions";
+
+/**
+ * Array of universal message receivers (called for all message types)
+ * @type {Array<function({err: any, type: string, data: any}): void>}
+ * @private
+ */
+const receiverArray = [];
+
+/**
+ * Map of type-specific message receivers
+ * @type {Object.<string, Array<function({err: any, type: string, data: any}): void>>}
+ * @private
+ */
+const ofTypesOb = {};
+
+/**
+ * Process incoming message data to hydrate binary resources
+ *
+ * This function handles two types of binary data references:
+ * - L-tagged: Binary data linked from server responses (fetchLinkedResources)
+ * - F-tagged: Shared files from other clients (fetchSharedFiles)
+ *
+ * @param {any} data - Raw data from server message
+ * @param {Error|null} err - Error from the message, if any
+ * @returns {Promise<any>} Hydrated data with binary resources fetched
+ *
+ * @example
+ * // Server sends: { image<!L>: 'abc123' }
+ * // After hydration: { image: ArrayBuffer }
+ */
+export async function processIncomingData(data, err) {
+  if (!data || err) return data;
+  try {
+    let result = await fetchLinkedResources(data);
+    return await fetchSharedFiles(result);
+  } catch (e) {
+    console.error(`🦍 Failed to hydrate data:`, e);
+    return data;
+  }
+}
+
+/**
+ * Dispatch a received message to all registered handlers
+ *
+ * Messages are delivered to:
+ * 1. Chained subscription callbacks (new v2 syntax)
+ * 2. Type-specific handlers registered via setOnReceiver(type, handler)
+ * 3. Universal handlers registered via setOnReceiver(handler)
+ *
+ * @param {string} type - Message type identifier
+ * @param {Error|null} err - Error payload, if any
+ * @param {any} data - Message data payload
+ */
+export function dispatchMessage(type, err, data) {
+  // Dispatch to chained subscription callbacks (v2 syntax)
+  if (hasSubscribers(type)) {
+    dispatchToSubscribers(type, data);
+  }
+
+  // Legacy handlers
+  if (ofTypesOb[type]) ofTypesOb[type].forEach((w) => w({ err, type, data }));
+  receiverArray.forEach((w) => w({ err, type, data }));
+}
+
+/**
+ * Register a message receiver/handler
+ *
+ * @param {string|function} onTypeStFn - Message type to listen for, or universal handler function
+ * @param {function=} handlerFn - Handler function (if first arg is type string)
+ *
+ * @example
+ * // Type-specific handler
+ * setOnReceiver('notification', (msg) => {
+ *   console.log('Got notification:', msg.data)
+ * })
+ *
+ * // Universal handler (receives all messages)
+ * setOnReceiver((msg) => {
+ *   console.log('Got message:', msg.type, msg.data)
+ * })
+ */
+export function setOnReceiver(onTypeStFn, handlerFn) {
+  if (typeof onTypeStFn === "string") {
+    ofTypesOb[onTypeStFn] = [handlerFn];
+  } else if (!receiverArray.includes(onTypeStFn)) {
+    receiverArray.push(onTypeStFn);
+  }
+}