@buoy-gg/external-sync 2.1.15

package/lib/module/useExternalSync.js

@@ -0,0 +1,195 @@
+"use strict";
+
+import { useEffect, useRef } from "react";
+import { log } from "./utils/logger";
+import { SYNC_PROTOCOL_VERSION } from "./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',
+ * });
+ * ```
+ */
+export function useExternalSync({
+  tools,
+  socket,
+  deviceId,
+  enabled = true,
+  throttleMs = 200,
+  enableLogs = false
+}) {
+  const toolsRef = 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 = 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(",");
+  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) {
+        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)));
+      log(`${LOG} Watching "${toolId}"`, enableLogs);
+    };
+    const unwatchTool = toolId => {
+      unsubs.get(toolId)?.();
+      unsubs.delete(toolId);
+      if (timers[toolId]) {
+        clearTimeout(timers[toolId]);
+        delete timers[toolId];
+      }
+      log(`${LOG} Stopped watching "${toolId}"`, enableLogs);
+    };
+    const sendCapabilities = () => {
+      const message = {
+        persistentDeviceId: deviceId,
+        protocolVersion: 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/module/useExternalSyncSocket.js

@@ -0,0 +1,160 @@
+"use strict";
+
+import { useEffect, useRef, useState } from "react";
+import { io as socketIO } from "socket.io-client";
+import { getPlatformSpecificURL } from "./utils/platformUtils";
+import { log } from "./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
+ */
+export function useExternalSyncSocket({
+  deviceName,
+  socketURL,
+  persistentDeviceId,
+  extraDeviceInfo,
+  envVariables,
+  platform,
+  enableLogs = false
+}) {
+  const socketRef = useRef(null);
+  const [socket, setSocket] = useState(null);
+  const [isConnected, setIsConnected] = useState(false);
+  const initialized = useRef(false);
+  const logPrefix = `[${deviceName}]`;
+  const onConnect = () => {
+    log(`${logPrefix} Socket connected successfully`, enableLogs);
+    setIsConnected(true);
+  };
+  const onDisconnect = reason => {
+    log(`${logPrefix} Socket disconnected. Reason: ${reason}`, enableLogs);
+    setIsConnected(false);
+  };
+  const onConnectError = error => {
+    log(`${logPrefix} Socket connection error: ${error.message}`, enableLogs, "error");
+  };
+  const onConnectTimeout = () => {
+    log(`${logPrefix} Socket connection timeout`, enableLogs, "error");
+  };
+
+  // Main socket initialization - runs only once
+  useEffect(() => {
+    if (!persistentDeviceId) return;
+    if (initialized.current) return;
+    initialized.current = true;
+    const platformUrl = getPlatformSpecificURL(socketURL, platform);
+    currentSocketURL = platformUrl;
+    log(`${logPrefix} Platform: ${platform}, using URL: ${platformUrl}`, enableLogs);
+    try {
+      if (!globalSocketInstance) {
+        log(`${logPrefix} Creating new socket instance to ${platformUrl}`, enableLogs);
+        globalSocketInstance = socketIO(platformUrl, {
+          autoConnect: true,
+          query: {
+            deviceName,
+            deviceId: persistentDeviceId,
+            platform,
+            extraDeviceInfo: JSON.stringify(extraDeviceInfo),
+            envVariables: JSON.stringify(envVariables)
+          },
+          reconnection: false,
+          transports: ["websocket"]
+        });
+      } else {
+        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);
+        log(`${logPrefix} Socket already connected on init`, enableLogs);
+      }
+      socketRef.current.on("connect", onConnect);
+      socketRef.current.on("disconnect", onDisconnect);
+      return () => {
+        if (socketRef.current) {
+          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) {
+      log(`${logPrefix} Failed to initialize socket: ${error}`, enableLogs, "error");
+    }
+  }, [persistentDeviceId]);
+
+  // Update socket query parameters when deviceName changes
+  useEffect(() => {
+    if (socketRef.current && socketRef.current.io.opts.query && persistentDeviceId) {
+      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
+  useEffect(() => {
+    const platformUrl = getPlatformSpecificURL(socketURL, platform);
+    if (socketRef.current && currentSocketURL !== platformUrl && persistentDeviceId) {
+      log(`${logPrefix} Socket URL changed from ${currentSocketURL} to ${platformUrl}`, enableLogs);
+      try {
+        socketRef.current.disconnect();
+        currentSocketURL = platformUrl;
+        log(`${logPrefix} Creating new socket connection to ${platformUrl}`, enableLogs);
+        globalSocketInstance = socketIO(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) {
+        log(`${logPrefix} Failed to update socket connection: ${error}`, enableLogs, "error");
+      }
+    }
+  }, [socketURL, deviceName, logPrefix, persistentDeviceId, platform, enableLogs]);
+  function connect() {
+    if (socketRef.current && !socketRef.current.connected) {
+      log(`${logPrefix} Manually connecting to socket server`, enableLogs);
+      socketRef.current.connect();
+    }
+  }
+  function disconnect() {
+    if (socketRef.current && socketRef.current.connected) {
+      log(`${logPrefix} Manually disconnecting from socket server`, enableLogs);
+      socketRef.current.disconnect();
+    }
+  }
+  return {
+    socket,
+    connect,
+    disconnect,
+    isConnected
+  };
+}

package/lib/module/utils/logger.js

@@ -0,0 +1,20 @@
+"use strict";
+
+/**
+ * Helper function for controlled logging.
+ * Only shows logs when enableLogs is true.
+ * Always shows warnings and errors regardless of enableLogs setting.
+ */
+export 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/module/utils/platformUtils.js

@@ -0,0 +1,19 @@
+"use strict";
+
+/**
+ * Get platform-specific URL for socket connection.
+ * On Android emulator, replaces localhost with 10.0.2.2.
+ */
+export 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;
+  }
+};

package/lib/typescript/index.d.ts

@@ -0,0 +1,5 @@
+export { useExternalSync } from "./useExternalSync";
+export { useExternalSyncSocket } from "./useExternalSyncSocket";
+export { SYNC_PROTOCOL_VERSION } from "./types";
+export type { ToolSyncAdapter, ToolAction, ToolCapability, SyncKind, UseExternalSyncProps, UseExternalSyncSocketProps, DeviceCapabilitiesMessage, DevToolSyncMessage, DevToolActionMessage, DevToolActionResultMessage, DevToolWatchMessage, DevToolRequestMessage, PlatformOS, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAKhE,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAKhD,YAAY,EACV,eAAe,EACf,UAAU,EACV,cAAc,EACd,QAAQ,EACR,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,EACrB,UAAU,GACX,MAAM,SAAS,CAAC"}

package/lib/typescript/types.d.ts

@@ -0,0 +1,114 @@
+import type { Socket } from "socket.io-client";
+/** Version of the envelope/event contract itself (not tool payloads). */
+export declare const SYNC_PROTOCOL_VERSION = 1;
+/** What a sync payload represents. "events"/"diff" reserved for future use. */
+export type SyncKind = "snapshot";
+/** A remote-invocable action. Thrown errors are reported back to the dashboard. */
+export type ToolAction = (params: unknown) => unknown | Promise<unknown>;
+/**
+ * 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.
+ */
+export interface ToolSyncAdapter {
+    /** Version of this tool's payload shape. Bump on breaking changes. */
+    version: number;
+    /** Current full state — sent when a dashboard starts watching or requests state. */
+    getSnapshot: () => unknown;
+    /**
+     * Fires on state changes. Only called while at least one dashboard is
+     * watching this tool; the bridge subscribes/unsubscribes on demand so
+     * stores with auto start/stop lifecycles stay idle when unwatched.
+     */
+    subscribe: (onChange: () => void) => () => void;
+    /** Remote-invocable actions, keyed by action name. */
+    actions?: Record<string, ToolAction>;
+}
+/** Announces available tools + actions on connect and when tools change. */
+export interface DeviceCapabilitiesMessage {
+    persistentDeviceId: string;
+    protocolVersion: number;
+    tools: ToolCapability[];
+}
+export interface ToolCapability {
+    toolId: string;
+    version: number;
+    actions: string[];
+}
+/** Carries a tool's state to the dashboard. */
+export interface DevToolSyncMessage {
+    toolId: string;
+    persistentDeviceId: string;
+    timestamp: number;
+    /** Tool payload version (ToolSyncAdapter.version). */
+    version: number;
+    kind: SyncKind;
+    payload: unknown;
+}
+/** Response to a `devtool-action` request. */
+export interface DevToolActionResultMessage {
+    requestId: string;
+    toolId: string;
+    action: string;
+    persistentDeviceId: string;
+    timestamp: number;
+    ok: boolean;
+    /** Present when ok. JSON-serializable value returned by the action. */
+    result?: unknown;
+    /** Present when not ok. */
+    error?: string;
+}
+/** Server-consolidated signal that a tool gained/lost its audience. */
+export interface DevToolWatchMessage {
+    toolId: string;
+    targetDeviceId: string;
+    watching: boolean;
+}
+/** Explicit request for a tool's current state (works even while unwatched). */
+export interface DevToolRequestMessage {
+    toolId: string;
+    targetDeviceId: string;
+}
+/** Invokes a registered action on the device. */
+export interface DevToolActionMessage {
+    requestId: string;
+    toolId: string;
+    targetDeviceId: string;
+    action: string;
+    params?: unknown;
+}
+export interface UseExternalSyncProps {
+    /** Map of toolId -> adapter. Each key becomes the toolId in messages. */
+    tools: Record<string, ToolSyncAdapter>;
+    /** Connected socket instance (from useExternalSyncSocket). */
+    socket: Socket | null;
+    /** Persistent device identifier. */
+    deviceId: string;
+    /** Enable/disable sync. @default true */
+    enabled?: boolean;
+    /**
+     * Minimum ms between snapshot emits per tool. Trailing-edge: a change
+     * arriving inside the window is flushed when the window ends, so the
+     * dashboard always converges to the latest state. @default 200
+     */
+    throttleMs?: number;
+    /** @default false */
+    enableLogs?: boolean;
+}
+/**
+ * Valid platform operating systems that can be used with React Native
+ */
+export type PlatformOS = "ios" | "android" | "web" | "windows" | "macos" | "native" | "tv" | "tvos" | "visionos" | "maccatalyst";
+export interface UseExternalSyncSocketProps {
+    deviceName: string;
+    socketURL: string;
+    persistentDeviceId: string | null;
+    extraDeviceInfo?: Record<string, string>;
+    envVariables?: Record<string, string>;
+    platform: PlatformOS;
+    /** @default false */
+    enableLogs?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/lib/typescript/useExternalSync.d.ts

@@ -0,0 +1,30 @@
+import { type UseExternalSyncProps } from "./types";
+/**
+ * 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',
+ * });
+ * ```
+ */
+export declare function useExternalSync({ tools, socket, deviceId, enabled, throttleMs, enableLogs, }: UseExternalSyncProps): void;
+//# sourceMappingURL=useExternalSync.d.ts.map

package/lib/typescript/useExternalSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useExternalSync.d.ts","sourceRoot":"","sources":["../../src/useExternalSync.ts"],"names":[],"mappings":"AAEA,OAAO,EAQL,KAAK,oBAAoB,EAC1B,MAAM,SAAS,CAAC;AAIjB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EACL,MAAM,EACN,QAAQ,EACR,OAAc,EACd,UAAgB,EAChB,UAAkB,GACnB,EAAE,oBAAoB,QAgLtB"}

package/lib/typescript/useExternalSyncSocket.d.ts

@@ -0,0 +1,17 @@
+import { Socket } from "socket.io-client";
+import type { UseExternalSyncSocketProps } from "./types";
+/**
+ * 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
+ */
+export declare function useExternalSyncSocket({ deviceName, socketURL, persistentDeviceId, extraDeviceInfo, envVariables, platform, enableLogs, }: UseExternalSyncSocketProps): {
+    socket: Socket<import("@socket.io/component-emitter").DefaultEventsMap, import("@socket.io/component-emitter").DefaultEventsMap> | null;
+    connect: () => void;
+    disconnect: () => void;
+    isConnected: boolean;
+};
+//# sourceMappingURL=useExternalSyncSocket.d.ts.map

package/lib/typescript/useExternalSyncSocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useExternalSyncSocket.d.ts","sourceRoot":"","sources":["../../src/useExternalSyncSocket.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAI1D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAS1D;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,UAAU,EACV,SAAS,EACT,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,UAAkB,GACnB,EAAE,0BAA0B;;;;;EAoM5B"}

package/lib/typescript/utils/logger.d.ts

@@ -0,0 +1,8 @@
+export type LogType = "log" | "warn" | "error";
+/**
+ * Helper function for controlled logging.
+ * Only shows logs when enableLogs is true.
+ * Always shows warnings and errors regardless of enableLogs setting.
+ */
+export declare function log(message: string, enableLogs: boolean, type?: LogType): void;
+//# sourceMappingURL=logger.d.ts.map

package/lib/typescript/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAE/C;;;;GAIG;AACH,wBAAgB,GAAG,CACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,OAAO,EACnB,IAAI,GAAE,OAAe,GACpB,IAAI,CAYN"}

package/lib/typescript/utils/platformUtils.d.ts

@@ -0,0 +1,7 @@
+import type { PlatformOS } from "../types";
+/**
+ * Get platform-specific URL for socket connection.
+ * On Android emulator, replaces localhost with 10.0.2.2.
+ */
+export declare const getPlatformSpecificURL: (baseUrl: string, platform: PlatformOS) => string;
+//# sourceMappingURL=platformUtils.d.ts.map

package/lib/typescript/utils/platformUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platformUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/platformUtils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,MAAM,EACf,UAAU,UAAU,KACnB,MAiBF,CAAC"}