@buoy-gg/external-sync 2.1.15

package/LICENSE

@@ -0,0 +1,58 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-present Buoy. All rights reserved.
+
+This software and its source code are proprietary and confidential.
+
+NOTICE: This is NOT open source software. This software is licensed,
+not sold, and is protected by copyright laws and international treaties.
+
+TERMS AND CONDITIONS:
+
+1. LICENSE GRANT
+   Subject to the terms of this Agreement and payment of applicable fees,
+   Buoy grants you a limited, non-exclusive, non-transferable license
+   to use the compiled software packages in your applications.
+
+2. RESTRICTIONS
+   You may NOT:
+   - Copy, modify, or distribute the source code
+   - Reverse engineer, decompile, or disassemble the software
+   - Remove or alter any proprietary notices or labels
+   - Sublicense, rent, lease, or lend the software
+   - Use the software to create competing products
+   - Share access credentials with unauthorized parties
+
+3. OWNERSHIP
+   React Buoy retains all right, title, and interest in the software,
+   including all intellectual property rights. This license does not
+   grant you any rights to trademarks or service marks.
+
+4. TERMINATION
+   This license is effective until terminated. Your rights under this
+   license will terminate automatically without notice if you fail to
+   comply with any of its terms. Upon termination, you must cease all
+   use and destroy all copies of the software.
+
+5. DISCLAIMER OF WARRANTIES
+   THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+6. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL BUOY BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR IN
+   CONNECTION WITH THIS LICENSE OR THE USE OF THE SOFTWARE.
+
+7. GOVERNING LAW
+   This Agreement shall be governed by and construed in accordance with
+   the laws of the United States, without regard to its conflict of
+   law provisions.
+
+For licensing inquiries and subscription information:
+- Website: https://buoy.gg
+- Email: AustinLovesWorking@gmail.com
+
+Unauthorized reproduction or distribution of this software, or any
+portion of it, may result in severe civil and criminal penalties,
+and will be prosecuted to the maximum extent possible under the law.

package/lib/commonjs/index.js

@@ -0,0 +1,26 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "SYNC_PROTOCOL_VERSION", {
+  enumerable: true,
+  get: function () {
+    return _types.SYNC_PROTOCOL_VERSION;
+  }
+});
+Object.defineProperty(exports, "useExternalSync", {
+  enumerable: true,
+  get: function () {
+    return _useExternalSync.useExternalSync;
+  }
+});
+Object.defineProperty(exports, "useExternalSyncSocket", {
+  enumerable: true,
+  get: function () {
+    return _useExternalSyncSocket.useExternalSyncSocket;
+  }
+});
+var _useExternalSync = require("./useExternalSync");
+var _useExternalSyncSocket = require("./useExternalSyncSocket");
+var _types = require("./types");

package/lib/commonjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/lib/commonjs/types.js

@@ -0,0 +1,84 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SYNC_PROTOCOL_VERSION = void 0;
+// ============================================================
+// DEVTOOL SYNC PROTOCOL (v1)
+//
+// Topology: device is a Socket.IO client; the desktop app hosts
+// the server (broker) and one or more dashboard UIs. The server
+// routes messages between dashboards and devices.
+//
+// Device -> server/dashboard events:
+//   "devtool-capabilities"  DeviceCapabilitiesMessage
+//   "devtool-sync"          DevToolSyncMessage
+//   "devtool-action-result" DevToolActionResultMessage
+//
+// Dashboard/server -> device events:
+//   "devtool-watch"         DevToolWatchMessage
+//   "request-devtool-state" DevToolRequestMessage
+//   "devtool-action"        DevToolActionMessage
+//
+// Backpressure contract: the device sends nothing for a tool until
+// it receives `devtool-watch {watching: true}` for it. The SERVER is
+// responsible for consolidating watch state across dashboards (and
+// for sending `watching: false` when the last watching dashboard
+// closes a panel or disconnects). The device just obeys.
+// ============================================================
+
+/** Version of the envelope/event contract itself (not tool payloads). */
+const SYNC_PROTOCOL_VERSION = exports.SYNC_PROTOCOL_VERSION = 1;
+
+/** What a sync payload represents. "events"/"diff" reserved for future use. */
+
+// ============================================================
+// TOOL ADAPTER
+// ============================================================
+
+/** A remote-invocable action. Thrown errors are reported back to the dashboard. */
+
+/**
+ * The contract each dev tool implements to become remotely syncable.
+ * Works with BaseEventStore or any pattern exposing subscribe + getSnapshot.
+ *
+ * Payloads (snapshots and action results) must be JSON-serializable —
+ * no functions, circular references, or class instances.
+ */
+
+// ============================================================
+// DEVICE -> DASHBOARD MESSAGES
+// ============================================================
+
+/** Announces available tools + actions on connect and when tools change. */
+
+/** Carries a tool's state to the dashboard. */
+
+/** Response to a `devtool-action` request. */
+
+// ============================================================
+// DASHBOARD -> DEVICE MESSAGES
+// ============================================================
+
+/** Server-consolidated signal that a tool gained/lost its audience. */
+
+/** Explicit request for a tool's current state (works even while unwatched). */
+
+/** Invokes a registered action on the device. */
+
+// ============================================================
+// HOOK PROPS
+// ============================================================
+
+// ============================================================
+// PLATFORM
+// ============================================================
+
+/**
+ * Valid platform operating systems that can be used with React Native
+ */
+
+// ============================================================
+// SOCKET HOOK PROPS
+// ============================================================

package/lib/commonjs/useExternalSync.js

@@ -0,0 +1,199 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useExternalSync = useExternalSync;
+var _react = require("react");
+var _logger = require("./utils/logger");
+var _types = require("./types");
+const LOG = "[ExternalSync]";
+
+/**
+ * Device-side sync bridge: syncs any number of dev tools to the desktop
+ * dashboard and executes actions invoked remotely.
+ *
+ * Backpressure: a tool's adapter is only subscribed while a dashboard is
+ * watching it (`devtool-watch`), so unwatched tools cost nothing. The server
+ * re-sends current watch state whenever it receives `devtool-capabilities`,
+ * which the device announces on every (re)connect.
+ *
+ * Usage:
+ * ```ts
+ * useExternalSync({
+ *   tools: {
+ *     storage: {
+ *       version: 1,
+ *       getSnapshot: () => storageEventStore.getEvents(),
+ *       subscribe: (cb) => storageEventStore.subscribeToEvents(cb),
+ *       actions: {
+ *         clearEvents: () => storageEventStore.clearEvents(),
+ *       },
+ *     },
+ *   },
+ *   socket,
+ *   deviceId: 'my-device-id',
+ * });
+ * ```
+ */
+function useExternalSync({
+  tools,
+  socket,
+  deviceId,
+  enabled = true,
+  throttleMs = 200,
+  enableLogs = false
+}) {
+  const toolsRef = (0, _react.useRef)(tools);
+  toolsRef.current = tools;
+
+  // Watch state persists across effect re-runs (e.g. when tools are
+  // added/removed) so an already-watched tool stays subscribed.
+  const watchedRef = (0, _react.useRef)(new Set());
+
+  // Re-run the effect only when tools are added/removed, not on every
+  // object-reference change.
+  const toolIdsKey = Object.keys(tools).sort().join(",");
+  (0, _react.useEffect)(() => {
+    if (!socket || !deviceId || !enabled) return;
+    const unsubs = new Map();
+    const lastEmit = {};
+    const timers = {};
+    const isForThisDevice = targetDeviceId => targetDeviceId === "All" || targetDeviceId === deviceId;
+    const safeEmit = (event, message) => {
+      try {
+        socket.emit(event, message);
+      } catch (error) {
+        (0, _logger.log)(`${LOG} Failed to emit "${event}": ${error}. Payload must be JSON-serializable.`, enableLogs, "error");
+      }
+    };
+    const sendSnapshot = toolId => {
+      const tool = toolsRef.current[toolId];
+      if (!tool) return;
+      lastEmit[toolId] = Date.now();
+      const message = {
+        toolId,
+        persistentDeviceId: deviceId,
+        timestamp: lastEmit[toolId],
+        version: tool.version,
+        kind: "snapshot",
+        payload: tool.getSnapshot()
+      };
+      safeEmit("devtool-sync", message);
+    };
+
+    // Leading + trailing throttle: emit immediately when outside the window,
+    // otherwise schedule a flush for the window's end so the dashboard always
+    // converges to the latest state.
+    const scheduleSnapshot = toolId => {
+      if (timers[toolId]) return;
+      const elapsed = Date.now() - (lastEmit[toolId] ?? 0);
+      if (elapsed >= throttleMs) {
+        sendSnapshot(toolId);
+        return;
+      }
+      timers[toolId] = setTimeout(() => {
+        delete timers[toolId];
+        sendSnapshot(toolId);
+      }, throttleMs - elapsed);
+    };
+    const watchTool = toolId => {
+      const tool = toolsRef.current[toolId];
+      if (!tool || unsubs.has(toolId)) return;
+      unsubs.set(toolId, tool.subscribe(() => scheduleSnapshot(toolId)));
+      (0, _logger.log)(`${LOG} Watching "${toolId}"`, enableLogs);
+    };
+    const unwatchTool = toolId => {
+      unsubs.get(toolId)?.();
+      unsubs.delete(toolId);
+      if (timers[toolId]) {
+        clearTimeout(timers[toolId]);
+        delete timers[toolId];
+      }
+      (0, _logger.log)(`${LOG} Stopped watching "${toolId}"`, enableLogs);
+    };
+    const sendCapabilities = () => {
+      const message = {
+        persistentDeviceId: deviceId,
+        protocolVersion: _types.SYNC_PROTOCOL_VERSION,
+        tools: Object.entries(toolsRef.current).map(([toolId, tool]) => ({
+          toolId,
+          version: tool.version,
+          actions: Object.keys(tool.actions ?? {})
+        }))
+      };
+      safeEmit("devtool-capabilities", message);
+    };
+    const handleWatch = message => {
+      if (!isForThisDevice(message.targetDeviceId)) return;
+      if (message.watching) {
+        watchedRef.current.add(message.toolId);
+        watchTool(message.toolId);
+        sendSnapshot(message.toolId);
+      } else {
+        watchedRef.current.delete(message.toolId);
+        unwatchTool(message.toolId);
+      }
+    };
+    const handleRequest = message => {
+      if (!isForThisDevice(message.targetDeviceId)) return;
+      sendSnapshot(message.toolId);
+    };
+    const handleAction = async message => {
+      if (!isForThisDevice(message.targetDeviceId)) return;
+      const {
+        requestId,
+        toolId,
+        action,
+        params
+      } = message;
+      const result = {
+        requestId,
+        toolId,
+        action,
+        persistentDeviceId: deviceId,
+        timestamp: Date.now(),
+        ok: false
+      };
+      const tool = toolsRef.current[toolId];
+      const fn = tool?.actions?.[action];
+      if (!fn) {
+        result.error = tool ? `Unknown action "${action}" on tool "${toolId}"` : `Unknown tool "${toolId}"`;
+        safeEmit("devtool-action-result", result);
+        return;
+      }
+      try {
+        result.result = await fn(params);
+        result.ok = true;
+      } catch (error) {
+        result.error = error instanceof Error ? error.message : String(error);
+      }
+      result.timestamp = Date.now();
+      safeEmit("devtool-action-result", result);
+    };
+    const handleConnect = () => {
+      // The server replies with current watch state for this device.
+      sendCapabilities();
+    };
+    if (socket.connected) sendCapabilities();
+
+    // Restore subscriptions for tools that were watched before this effect
+    // re-ran (or that arrived after the watch message).
+    for (const toolId of watchedRef.current) {
+      if (toolsRef.current[toolId]) watchTool(toolId);
+    }
+    socket.on("connect", handleConnect);
+    socket.on("devtool-watch", handleWatch);
+    socket.on("request-devtool-state", handleRequest);
+    socket.on("devtool-action", handleAction);
+    return () => {
+      socket.off("connect", handleConnect);
+      socket.off("devtool-watch", handleWatch);
+      socket.off("request-devtool-state", handleRequest);
+      socket.off("devtool-action", handleAction);
+      for (const toolId of [...unsubs.keys()]) unwatchTool(toolId);
+    };
+    // toolIdsKey stands in for `tools` (see comment above its definition).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [socket, deviceId, enabled, throttleMs, enableLogs, toolIdsKey]);
+}

package/lib/commonjs/useExternalSyncSocket.js

@@ -0,0 +1,164 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useExternalSyncSocket = useExternalSyncSocket;
+var _react = require("react");
+var _socket = require("socket.io-client");
+var _platformUtils = require("./utils/platformUtils");
+var _logger = require("./utils/logger");
+/**
+ * Singleton socket instance that persists across component renders.
+ * Multiple components share the same socket connection.
+ */
+let globalSocketInstance = null;
+let currentSocketURL = "";
+
+/**
+ * Hook that manages a Socket.IO connection for device-to-dashboard communication.
+ *
+ * Features:
+ * - Singleton pattern for socket connection
+ * - Platform-specific URL handling (Android emulator -> 10.0.2.2)
+ * - Connection state tracking
+ */
+function useExternalSyncSocket({
+  deviceName,
+  socketURL,
+  persistentDeviceId,
+  extraDeviceInfo,
+  envVariables,
+  platform,
+  enableLogs = false
+}) {
+  const socketRef = (0, _react.useRef)(null);
+  const [socket, setSocket] = (0, _react.useState)(null);
+  const [isConnected, setIsConnected] = (0, _react.useState)(false);
+  const initialized = (0, _react.useRef)(false);
+  const logPrefix = `[${deviceName}]`;
+  const onConnect = () => {
+    (0, _logger.log)(`${logPrefix} Socket connected successfully`, enableLogs);
+    setIsConnected(true);
+  };
+  const onDisconnect = reason => {
+    (0, _logger.log)(`${logPrefix} Socket disconnected. Reason: ${reason}`, enableLogs);
+    setIsConnected(false);
+  };
+  const onConnectError = error => {
+    (0, _logger.log)(`${logPrefix} Socket connection error: ${error.message}`, enableLogs, "error");
+  };
+  const onConnectTimeout = () => {
+    (0, _logger.log)(`${logPrefix} Socket connection timeout`, enableLogs, "error");
+  };
+
+  // Main socket initialization - runs only once
+  (0, _react.useEffect)(() => {
+    if (!persistentDeviceId) return;
+    if (initialized.current) return;
+    initialized.current = true;
+    const platformUrl = (0, _platformUtils.getPlatformSpecificURL)(socketURL, platform);
+    currentSocketURL = platformUrl;
+    (0, _logger.log)(`${logPrefix} Platform: ${platform}, using URL: ${platformUrl}`, enableLogs);
+    try {
+      if (!globalSocketInstance) {
+        (0, _logger.log)(`${logPrefix} Creating new socket instance to ${platformUrl}`, enableLogs);
+        globalSocketInstance = (0, _socket.io)(platformUrl, {
+          autoConnect: true,
+          query: {
+            deviceName,
+            deviceId: persistentDeviceId,
+            platform,
+            extraDeviceInfo: JSON.stringify(extraDeviceInfo),
+            envVariables: JSON.stringify(envVariables)
+          },
+          reconnection: false,
+          transports: ["websocket"]
+        });
+      } else {
+        (0, _logger.log)(`${logPrefix} Reusing existing socket instance to ${platformUrl}`, enableLogs);
+      }
+      socketRef.current = globalSocketInstance;
+      setSocket(socketRef.current);
+      socketRef.current.on("connect_error", onConnectError);
+      socketRef.current.on("connect_timeout", onConnectTimeout);
+      if (socketRef.current.connected) {
+        setIsConnected(true);
+        (0, _logger.log)(`${logPrefix} Socket already connected on init`, enableLogs);
+      }
+      socketRef.current.on("connect", onConnect);
+      socketRef.current.on("disconnect", onDisconnect);
+      return () => {
+        if (socketRef.current) {
+          (0, _logger.log)(`${logPrefix} Cleaning up socket event listeners`, enableLogs);
+          socketRef.current.off("connect", onConnect);
+          socketRef.current.off("disconnect", onDisconnect);
+          socketRef.current.off("connect_error", onConnectError);
+          socketRef.current.off("connect_timeout", onConnectTimeout);
+        }
+      };
+    } catch (error) {
+      (0, _logger.log)(`${logPrefix} Failed to initialize socket: ${error}`, enableLogs, "error");
+    }
+  }, [persistentDeviceId]);
+
+  // Update socket query parameters when deviceName changes
+  (0, _react.useEffect)(() => {
+    if (socketRef.current && socketRef.current.io.opts.query && persistentDeviceId) {
+      (0, _logger.log)(`${logPrefix} Updating device name in socket connection`, enableLogs);
+      socketRef.current.io.opts.query = {
+        ...socketRef.current.io.opts.query,
+        deviceName,
+        deviceId: persistentDeviceId,
+        platform
+      };
+    }
+  }, [deviceName, logPrefix, persistentDeviceId, platform, enableLogs]);
+
+  // Update socket URL when socketURL changes
+  (0, _react.useEffect)(() => {
+    const platformUrl = (0, _platformUtils.getPlatformSpecificURL)(socketURL, platform);
+    if (socketRef.current && currentSocketURL !== platformUrl && persistentDeviceId) {
+      (0, _logger.log)(`${logPrefix} Socket URL changed from ${currentSocketURL} to ${platformUrl}`, enableLogs);
+      try {
+        socketRef.current.disconnect();
+        currentSocketURL = platformUrl;
+        (0, _logger.log)(`${logPrefix} Creating new socket connection to ${platformUrl}`, enableLogs);
+        globalSocketInstance = (0, _socket.io)(platformUrl, {
+          autoConnect: true,
+          query: {
+            deviceName,
+            deviceId: persistentDeviceId,
+            platform,
+            extraDeviceInfo: JSON.stringify(extraDeviceInfo),
+            envVariables: JSON.stringify(envVariables)
+          },
+          reconnection: false,
+          transports: ["websocket"]
+        });
+        socketRef.current = globalSocketInstance;
+        setSocket(socketRef.current);
+      } catch (error) {
+        (0, _logger.log)(`${logPrefix} Failed to update socket connection: ${error}`, enableLogs, "error");
+      }
+    }
+  }, [socketURL, deviceName, logPrefix, persistentDeviceId, platform, enableLogs]);
+  function connect() {
+    if (socketRef.current && !socketRef.current.connected) {
+      (0, _logger.log)(`${logPrefix} Manually connecting to socket server`, enableLogs);
+      socketRef.current.connect();
+    }
+  }
+  function disconnect() {
+    if (socketRef.current && socketRef.current.connected) {
+      (0, _logger.log)(`${logPrefix} Manually disconnecting from socket server`, enableLogs);
+      socketRef.current.disconnect();
+    }
+  }
+  return {
+    socket,
+    connect,
+    disconnect,
+    isConnected
+  };
+}

package/lib/commonjs/utils/logger.js

@@ -0,0 +1,24 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.log = log;
+/**
+ * Helper function for controlled logging.
+ * Only shows logs when enableLogs is true.
+ * Always shows warnings and errors regardless of enableLogs setting.
+ */
+function log(message, enableLogs, type = "log") {
+  if (!enableLogs && type === "log") return;
+  switch (type) {
+    case "warn":
+      console.warn(message);
+      break;
+    case "error":
+      console.error(message);
+      break;
+    default:
+      console.log(message);
+  }
+}

package/lib/commonjs/utils/platformUtils.js

@@ -0,0 +1,24 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getPlatformSpecificURL = void 0;
+/**
+ * Get platform-specific URL for socket connection.
+ * On Android emulator, replaces localhost with 10.0.2.2.
+ */
+const getPlatformSpecificURL = (baseUrl, platform) => {
+  try {
+    const url = new URL(baseUrl);
+    if (platform === "android" && (url.hostname === "localhost" || url.hostname === "127.0.0.1")) {
+      url.hostname = "10.0.2.2";
+      return url.toString();
+    }
+    return baseUrl;
+  } catch (e) {
+    console.warn("Error getting platform-specific URL:", e);
+    return baseUrl;
+  }
+};
+exports.getPlatformSpecificURL = getPlatformSpecificURL;

package/lib/module/index.js

@@ -0,0 +1,16 @@
+"use strict";
+
+// ============================================================
+// HOOKS
+// ============================================================
+export { useExternalSync } from "./useExternalSync";
+export { useExternalSyncSocket } from "./useExternalSyncSocket";
+
+// ============================================================
+// PROTOCOL
+// ============================================================
+export { SYNC_PROTOCOL_VERSION } from "./types";
+
+// ============================================================
+// TYPES
+// ============================================================

package/lib/module/types.js

@@ -0,0 +1,80 @@
+"use strict";
+
+// ============================================================
+// DEVTOOL SYNC PROTOCOL (v1)
+//
+// Topology: device is a Socket.IO client; the desktop app hosts
+// the server (broker) and one or more dashboard UIs. The server
+// routes messages between dashboards and devices.
+//
+// Device -> server/dashboard events:
+//   "devtool-capabilities"  DeviceCapabilitiesMessage
+//   "devtool-sync"          DevToolSyncMessage
+//   "devtool-action-result" DevToolActionResultMessage
+//
+// Dashboard/server -> device events:
+//   "devtool-watch"         DevToolWatchMessage
+//   "request-devtool-state" DevToolRequestMessage
+//   "devtool-action"        DevToolActionMessage
+//
+// Backpressure contract: the device sends nothing for a tool until
+// it receives `devtool-watch {watching: true}` for it. The SERVER is
+// responsible for consolidating watch state across dashboards (and
+// for sending `watching: false` when the last watching dashboard
+// closes a panel or disconnects). The device just obeys.
+// ============================================================
+
+/** Version of the envelope/event contract itself (not tool payloads). */
+export const SYNC_PROTOCOL_VERSION = 1;
+
+/** What a sync payload represents. "events"/"diff" reserved for future use. */
+
+// ============================================================
+// TOOL ADAPTER
+// ============================================================
+
+/** A remote-invocable action. Thrown errors are reported back to the dashboard. */
+
+/**
+ * The contract each dev tool implements to become remotely syncable.
+ * Works with BaseEventStore or any pattern exposing subscribe + getSnapshot.
+ *
+ * Payloads (snapshots and action results) must be JSON-serializable —
+ * no functions, circular references, or class instances.
+ */
+
+// ============================================================
+// DEVICE -> DASHBOARD MESSAGES
+// ============================================================
+
+/** Announces available tools + actions on connect and when tools change. */
+
+/** Carries a tool's state to the dashboard. */
+
+/** Response to a `devtool-action` request. */
+
+// ============================================================
+// DASHBOARD -> DEVICE MESSAGES
+// ============================================================
+
+/** Server-consolidated signal that a tool gained/lost its audience. */
+
+/** Explicit request for a tool's current state (works even while unwatched). */
+
+/** Invokes a registered action on the device. */
+
+// ============================================================
+// HOOK PROPS
+// ============================================================
+
+// ============================================================
+// PLATFORM
+// ============================================================
+
+/**
+ * Valid platform operating systems that can be used with React Native
+ */
+
+// ============================================================
+// SOCKET HOOK PROPS
+// ============================================================