@buoy-gg/core 7.0.21 → 7.0.23

package/lib/commonjs/floatingMenu/externalSyncGate.js

@@ -0,0 +1,49 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.externalSyncOptions = externalSyncOptions;
+exports.shouldMountExternalSync = shouldMountExternalSync;
+/**
+ * Decides whether FloatingDevTools mounts <AutoExternalSync /> — i.e. whether
+ * this build is allowed to dial the Buoy Desktop broker.
+ *
+ * Kept as a pure function in its own module (no react-native / no guarded
+ * requires) so the rule is unit-testable: the gate used to be an inline
+ * `isDevelopment && ...` in JSX, which silently made release builds unable to
+ * reach the desktop dashboard or MCP with no way to opt in from app code.
+ *
+ * The rule has two halves that must BOTH hold in a release build, because a
+ * shipped app must never contact a broker on an end user's device:
+ *   1. a real Pro license (never the Weekend Pass — see useProAccess), and
+ *   2. an EXPLICIT opt-in from app code (`externalSync.enableInRelease`).
+ * Dev builds keep the zero-config behavior: sync is on unless turned off.
+ */
+
+/** The options object from the prop, or undefined when it's a boolean. */
+function externalSyncOptions(externalSync) {
+  return typeof externalSync === "object" && externalSync !== null ? externalSync : undefined;
+}
+function shouldMountExternalSync({
+  isDevelopment,
+  isLicensed,
+  externalSync,
+  isAvailable
+}) {
+  // Turned off outright, or the package isn't installed — nothing to mount.
+  if (externalSync === false) return false;
+  if (!isAvailable) return false;
+
+  // Dev builds: zero-config, on by default (historical behavior).
+  if (isDevelopment) return true;
+
+  // Release builds: opt-in only, and Pro only. `enableInRelease` has to be set
+  // by the app itself, so an app that just ships FloatingDevTools with a Pro
+  // key still never opens a socket on a customer's phone.
+  //
+  // The `isLicensed` half is belt-and-braces: FloatingDevTools already renders
+  // nothing at all for an unlicensed release build. Keep it anyway so this rule
+  // stands on its own and can't be broken by a change to that earlier return.
+  return isLicensed && externalSyncOptions(externalSync)?.enableInRelease === true;
+}

package/lib/commonjs/floatingMenu/sync/appSyncAdapter.js

@@ -27,12 +27,24 @@ var _sharedUi = require("@buoy-gg/shared-ui");
  * and reporting it too early.
  */
 const REALM_STARTED_AT = Date.now();
+
+/**
+ * Where this bundle came from, resolved once at module load.
+ *
+ * Reported so a remote driver can recover the app when the app itself can no
+ * longer be asked to: after a fatal render error the React tree is gone, every
+ * tool action goes unanswered, and `reloadApp` below is unreachable. The dev
+ * server's reload path runs natively and still works — but only for a driver
+ * that learned this origin while the app was healthy.
+ */
+const DEV_SERVER_ORIGIN = (0, _sharedUi.getDevServerOrigin)();
 const appSyncAdapter = exports.appSyncAdapter = {
-  version: 1,
+  version: 2,
   getSnapshot: () => {
     const strategy = (0, _sharedUi.resolveReloadStrategy)("auto");
     return {
       startedAt: REALM_STARTED_AT,
+      devServerOrigin: DEV_SERVER_ORIGIN,
       reload: {
         available: strategy !== null,
         strategy
@@ -50,7 +62,8 @@ const appSyncAdapter = exports.appSyncAdapter = {
      */
     ping: () => ({
       ok: true,
-      startedAt: REALM_STARTED_AT
+      startedAt: REALM_STARTED_AT,
+      devServerOrigin: DEV_SERVER_ORIGIN
     }),
     /**
      * Reload the app's JS bundle: RN's `DevSettings.reload()` in dev builds,

package/lib/commonjs/telemetry/installPing.js

@@ -0,0 +1,124 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.__resetInstallPingForTests = __resetInstallPingForTests;
+exports.sendInstallPing = sendInstallPing;
+var _reactNative = require("react-native");
+var _sharedUi = require("@buoy-gg/shared-ui");
+var _version = require("../version.js");
+/**
+ * Anonymous install ping.
+ *
+ * Answers the one question licensing data cannot: how many people run Buoy at
+ * all. Keygen sees every free and paid key, but by definition it cannot see an
+ * install that never claimed one — so without this, "what fraction of installs
+ * have an account" has no denominator.
+ *
+ * Constraints this is built to honor:
+ *
+ *  - **Development only.** Never fires from a shipped app. Buoy is a developer
+ *    tool; pinging from a release build would phone home from an end user's
+ *    device — someone who never chose to use Buoy — which is not a trade we are
+ *    willing to make for a metric.
+ *  - **No PII, no fingerprint.** The install id is a random UUID minted here.
+ *    It is not derived from hardware, account, project, or app identity, so it
+ *    cannot be correlated to a person or joined against anything else we hold.
+ *  - **No tool usage.** What you open and inspect stays on your machine, which
+ *    is the whole security story for enterprise adoption. Only the four fields
+ *    below ever leave.
+ *  - **Silent and harmless.** Fire-and-forget, throttled to once a day, and
+ *    every failure path is swallowed. It can never block, slow, or break an app.
+ *
+ * Opt out with `Buoy.init({ telemetry: false })`.
+ */
+
+/** Same `@react_buoy` prefix as every other Buoy key, so it is inspectable. */
+const STORAGE_KEY = "@react_buoy_install";
+const ENDPOINT = "https://buoy.gg/api/t";
+
+/** One ping per install per day is enough to count installs and daily actives. */
+const PING_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** RFC4122 v4, from Math.random — this is a counter, not a credential. */
+function uuid() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, c => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 0x3 | 0x8;
+    return v.toString(16);
+  });
+}
+async function readState() {
+  try {
+    const raw = await _sharedUi.persistentStorage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.installId !== "string") return null;
+    return {
+      installId: parsed.installId,
+      lastPingAt: typeof parsed.lastPingAt === "number" ? parsed.lastPingAt : 0
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Told once, on the very first ping of a new install — not on every launch.
+ *
+ * A dev tool that phones home silently deserves the reputation it would get.
+ * One line, the first time, saying exactly what leaves and how to stop it.
+ */
+function announceOnce() {
+  console.log("[Buoy] Anonymous usage ping enabled: a random install id, the Buoy " + "version, your platform, and your license tier — no project, app, or " + "tool data, and only in development. Opt out with " + "Buoy.init({ telemetry: false }). Details: https://buoy.gg/docs/telemetry");
+}
+let sentThisSession = false;
+
+/**
+ * Send the ping if it is due. Safe to call on every mount: it is idempotent
+ * within a session, throttled to once a day across sessions, and resolves
+ * without throwing no matter what fails.
+ */
+async function sendInstallPing(options) {
+  // Never from a shipped app — see the header. This is the single most
+  // important line in the file.
+  const isDevelopment = typeof __DEV__ !== "undefined" && __DEV__;
+  if (!isDevelopment) return;
+  if (!options.enabled) return;
+  if (sentThisSession) return;
+  sentThisSession = true;
+  try {
+    const existing = await readState();
+    const now = Date.now();
+    if (existing && now - existing.lastPingAt < PING_INTERVAL_MS) return;
+    const installId = existing?.installId ?? uuid();
+    if (!existing) announceOnce();
+
+    // Recorded BEFORE the request, so a server that is down or unreachable
+    // can't turn into a ping every single mount.
+    await _sharedUi.persistentStorage.setItem(STORAGE_KEY, JSON.stringify({
+      installId,
+      lastPingAt: now
+    }));
+    await fetch(ENDPOINT, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        installId,
+        version: _version.SDK_VERSION,
+        platform: _reactNative.Platform.OS,
+        tier: options.tier
+      })
+    });
+  } catch {
+    // Offline, firewalled, endpoint down — all fine. A metric is never worth
+    // a warning in someone else's console.
+  }
+}
+
+/** Test seam: forget that a ping already went out this session. */
+function __resetInstallPingForTests() {
+  sentThisSession = false;
+}

package/lib/commonjs/version.js

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SDK_VERSION = void 0;
+/**
+ * This package's published version.
+ *
+ * Hardcoded rather than read from package.json: `require("../package.json")`
+ * resolves to a different depth from `src/` than from the built `lib/`, and
+ * react-native-builder-bob (babel) has no build-time `define` the way tsup does
+ * for @buoy-gg/mcp.
+ *
+ * Drift is prevented by a test that fails when this disagrees with
+ * package.json, so a version bump that forgets this file cannot ship.
+ */
+const SDK_VERSION = exports.SDK_VERSION = "7.0.22";

package/lib/module/Buoy.js

@@ -16,6 +16,17 @@
  */
 
 import { LicenseManager } from "@buoy-gg/license";
+/**
+ * Telemetry stays on unless an app explicitly opts out. Read at ping time
+ * rather than captured, so `Buoy.init()` still wins if it runs after mount.
+ */
+let telemetryEnabled = true;
+
+/** Whether the anonymous install ping is allowed to fire. */
+export function isTelemetryEnabled() {
+  return telemetryEnabled;
+}
+
 /**
  * Buoy SDK namespace
  *
@@ -44,6 +55,8 @@ export const Buoy = {
    * ```
    */
   init(config) {
+    if (config.telemetry === false) telemetryEnabled = false;
+
     // If no license key or empty string, clear any cached license
     if (!config.licenseKey || config.licenseKey.trim() === "") {
       LicenseManager.initialize().then(() => LicenseManager.clearLicense()).catch(() => {});

package/lib/module/floatingMenu/FloatingDevTools.js

@@ -6,6 +6,8 @@ import { AppHostProvider } from "./AppHost";
 import { FloatingMenu } from "./FloatingMenu.js";
 import { AppOverlay } from "./AppHost";
 import { autoDiscoverPresets, autoDiscoverPresetsWithCustom } from "./autoDiscoverPresets.js";
+import { sendInstallPing } from "../telemetry/installPing.js";
+import { isTelemetryEnabled } from "../Buoy.js";
 import { renderAppIcon } from "./AppIcon.js";
 import { DevToolsVisibilityProvider } from "./DevToolsVisibilityContext.js";
 import { reportOptionalRequireError } from "./optionalRequire.js";
@@ -15,6 +17,7 @@ import { validateDialConfig } from "./defaultConfig.js";
 import { DefaultConfigProvider } from "./DefaultConfigContext.js";
 import { LicenseManager, useProAccess, useLicense } from "@buoy-gg/license";
 import { AutoExternalSync, isExternalSyncAvailable } from "./autoExternalSync.js";
+import { externalSyncOptions, shouldMountExternalSync } from "./externalSyncGate.js";
 
 /**
  * Environment variable configuration
@@ -129,8 +132,20 @@ export const FloatingDevTools = ({
   // Get full license state for requireLicense gating
   const {
     licenseKey,
-    isInitialized
+    isInitialized,
+    tier
   } = useLicense();
+
+  // Anonymous install ping — dev-only, once a day, no project or tool data.
+  // Deliberately waits for the license to resolve so the tier it reports is
+  // the real one rather than the "anonymous" the manager starts at.
+  useEffect(() => {
+    if (!isInitialized) return;
+    void sendInstallPing({
+      tier,
+      enabled: isTelemetryEnabled()
+    });
+  }, [isInitialized, tier]);
   const [showLicenseModal, setShowLicenseModal] = useState(false);
 
   // Initialize license manager on mount, and set/clear license key when prop changes.
@@ -375,25 +390,47 @@ export const FloatingDevTools = ({
     });
   }, [finalApps]);
 
-  // Gate: Free tier only works in development mode
-  // Pro users can use DevTools everywhere (dev + production)
+  // Gate: only a PAID license works outside development.
+  //
+  // Both untiered surfaces below it — anonymous (no key) and free (a key on the
+  // Free policy) — stay dev-only. `isLicensed` is safe to gate on because
+  // `isPro` is a strict mirror of `tier === "pro"`, so a free key reports false
+  // here even though it validates perfectly well.
+  //
+  // When Business on-device login lands, this becomes the boundary that a
+  // logged-in QA/support seat crosses WITHOUT a key in the build — i.e.
+  // `isLicensed || tierSource === "session"`. Nothing else should.
   const isDevelopment = typeof __DEV__ !== "undefined" && __DEV__;
   if (!isDevelopment && !isLicensed) {
-    // Free user in production - don't render DevTools
+    // Anonymous or free user in production - don't render DevTools.
+    // NOTE for whoever relaxes this for the free tier: desktop sync does NOT
+    // ride on this check. It re-tests `isLicensed` itself (externalSyncGate),
+    // so opening this door does not open a broker socket. Keep it that way.
     return null;
   }
 
+  // Zero-config in dev; in a release bundle the app must opt in explicitly
+  // (externalSync.enableInRelease) AND hold a real Pro license — see
+  // externalSyncGate.ts for why both halves are required.
+  const syncEnabled = shouldMountExternalSync({
+    isDevelopment,
+    isLicensed,
+    externalSync,
+    isAvailable: isExternalSyncAvailable()
+  });
+
   // Headless (sync-only): tool adapters + route tracking + desktop sync, no
   // on-device UI. requireLicense is intentionally skipped — there's nothing
   // to gate. All hooks above already ran, so hook order is preserved, and
-  // AutoExternalSync is additionally dev-gated (the broker must never be
-  // contacted in production).
+  // AutoExternalSync still obeys `syncEnabled` (the broker must never be
+  // contacted from a shipped build that didn't ask for it).
   if (headless) {
     return /*#__PURE__*/_jsxs(_Fragment, {
-      children: [ReduxAutoInstrument && /*#__PURE__*/_jsx(ReduxAutoInstrument, {}), ConsoleRoot && /*#__PURE__*/_jsx(ConsoleRoot, {}), RouteTracker && /*#__PURE__*/_jsx(RouteTracker, {}), isDevelopment && externalSync !== false && isExternalSyncAvailable() && /*#__PURE__*/_jsx(AutoExternalSync, {
-        options: typeof externalSync === "object" ? externalSync : undefined,
+      children: [ReduxAutoInstrument && /*#__PURE__*/_jsx(ReduxAutoInstrument, {}), ConsoleRoot && /*#__PURE__*/_jsx(ConsoleRoot, {}), RouteTracker && /*#__PURE__*/_jsx(RouteTracker, {}), syncEnabled && /*#__PURE__*/_jsx(AutoExternalSync, {
+        options: externalSyncOptions(externalSync),
         requiredEnvVars: requiredEnvVars,
         isPro: isLicensed,
+        tier: tier,
         licenseKey: licenseKey,
         customApps: syncApps
       })]
@@ -431,10 +468,11 @@ export const FloatingDevTools = ({
                 environment: resolvedEnvironment
               }), /*#__PURE__*/_jsx(AppOverlay, {})]
             })
-          }), children, DebugBordersOverlay && /*#__PURE__*/_jsx(DebugBordersOverlay, {}), HighlightUpdatesOverlay && /*#__PURE__*/_jsx(HighlightUpdatesOverlay, {}), ImageOverlayOverlay && /*#__PURE__*/_jsx(ImageOverlayOverlay, {}), PerfMonitorOverlay && /*#__PURE__*/_jsx(PerfMonitorOverlay, {}), JsTopOverlay && /*#__PURE__*/_jsx(JsTopOverlay, {}), ImpersonateOverlay && /*#__PURE__*/_jsx(ImpersonateOverlay, {}), ReduxAutoInstrument && /*#__PURE__*/_jsx(ReduxAutoInstrument, {}), ConsoleRoot && /*#__PURE__*/_jsx(ConsoleRoot, {}), RouteTracker && /*#__PURE__*/_jsx(RouteTracker, {}), isDevelopment && externalSync !== false && isExternalSyncAvailable() && /*#__PURE__*/_jsx(AutoExternalSync, {
-            options: typeof externalSync === "object" ? externalSync : undefined,
+          }), children, DebugBordersOverlay && /*#__PURE__*/_jsx(DebugBordersOverlay, {}), HighlightUpdatesOverlay && /*#__PURE__*/_jsx(HighlightUpdatesOverlay, {}), ImageOverlayOverlay && /*#__PURE__*/_jsx(ImageOverlayOverlay, {}), PerfMonitorOverlay && /*#__PURE__*/_jsx(PerfMonitorOverlay, {}), JsTopOverlay && /*#__PURE__*/_jsx(JsTopOverlay, {}), ImpersonateOverlay && /*#__PURE__*/_jsx(ImpersonateOverlay, {}), ReduxAutoInstrument && /*#__PURE__*/_jsx(ReduxAutoInstrument, {}), ConsoleRoot && /*#__PURE__*/_jsx(ConsoleRoot, {}), RouteTracker && /*#__PURE__*/_jsx(RouteTracker, {}), syncEnabled && /*#__PURE__*/_jsx(AutoExternalSync, {
+            options: externalSyncOptions(externalSync),
             requiredEnvVars: requiredEnvVars,
             isPro: isLicensed,
+            tier: tier,
             licenseKey: licenseKey,
             customApps: syncApps
           })]

package/lib/module/floatingMenu/ToolHost.js

@@ -22,6 +22,7 @@ const FALLBACK_CONTEXT = {
   isSearchActive: false,
   clearSearch: noop,
   close: noop,
+  minimize: noop,
   showToast: noop,
   setHeaderOverride: noop
 };
@@ -152,10 +153,13 @@ export function ToolModalShell({
     isSearchActive,
     clearSearch,
     close: onClose,
+    // Bare call: JsModal persists its own dimensions, so restoring brings
+    // the tool back the size the user last left it.
+    minimize: () => onMinimize(),
     showToast,
     setHeaderOverride,
     instanceId: app.instanceId
-  }), [search, isSearchActive, clearSearch, onClose, showToast, app.instanceId]);
+  }), [search, isSearchActive, clearSearch, onClose, onMinimize, showToast, app.instanceId]);
   const title = headerOverride?.title ?? config.title ?? app.title ?? app.id;
   const subtitle = headerOverride?.subtitle ?? config.subtitle;
   const onBack = headerOverride?.onBack;

package/lib/module/floatingMenu/autoExternalSync.js

@@ -4,12 +4,13 @@
  * Zero-config device→desktop sync for FloatingDevTools.
  *
  * When @buoy-gg/external-sync is installed, FloatingDevTools renders
- * <AutoExternalSync /> in dev builds: it connects to the Buoy Desktop broker
- * (port 42831 on the Metro host, so physical devices reach the dev machine
- * automatically — a background retry when the desktop app isn't running) and
- * registers a sync adapter for every installed tool package, discovered with
- * the same guarded-require pattern as autoDiscoverPresets. No <DevToolsSync>
- * wiring needed in the app.
+ * <AutoExternalSync /> in dev builds (and in release builds that opted in via
+ * externalSync.enableInRelease — see externalSyncGate.ts): it connects to the
+ * Buoy Desktop broker (port 42831 on the Metro host, so physical devices reach
+ * the dev machine automatically — a background retry when the desktop app
+ * isn't running) and registers a sync adapter for every installed tool
+ * package, discovered with the same guarded-require pattern as
+ * autoDiscoverPresets. No <DevToolsSync> wiring needed in the app.
  *
  * Identity defaults come from expo-constants when available (app name →
  * "MyApp (ios)" / "myapp-ios"), overridable via the `externalSync` prop.
@@ -175,6 +176,7 @@ export function AutoExternalSync({
   options,
   requiredEnvVars,
   isPro,
+  tier,
   licenseKey,
   customApps
 }) {
@@ -208,10 +210,12 @@ export function AutoExternalSync({
   // record and rebroadcasts, so the desktop dashboard can auto-adopt the key.
   const licenseRef = useRef({
     isPro,
+    tier,
     licenseKey
   });
   licenseRef.current = {
     isPro,
+    tier,
     licenseKey
   };
   useEffect(() => {
@@ -219,6 +223,8 @@ export function AutoExternalSync({
     const emitLicense = () => {
       socket.emit("device-license", {
         isPro: licenseRef.current.isPro ? "1" : "0",
+        // Brokers older than the tier split ignore this; newer ones prefer it.
+        tier: licenseRef.current.tier ?? (licenseRef.current.isPro ? "pro" : "anonymous"),
         licenseKey: licenseRef.current.licenseKey ?? ""
       });
     };
@@ -227,7 +233,7 @@ export function AutoExternalSync({
     return () => {
       socket.off("connect", emitLicense);
     };
-  }, [socket, isPro, licenseKey]);
+  }, [socket, isPro, tier, licenseKey]);
   const tools = useMemo(() => {
     // Core's own adapter — device-level capabilities (JS-bundle reload) that
     // don't belong to any tool package. Registered unconditionally so remote

package/lib/module/floatingMenu/externalSyncGate.js

@@ -0,0 +1,44 @@
+"use strict";
+
+/**
+ * Decides whether FloatingDevTools mounts <AutoExternalSync /> — i.e. whether
+ * this build is allowed to dial the Buoy Desktop broker.
+ *
+ * Kept as a pure function in its own module (no react-native / no guarded
+ * requires) so the rule is unit-testable: the gate used to be an inline
+ * `isDevelopment && ...` in JSX, which silently made release builds unable to
+ * reach the desktop dashboard or MCP with no way to opt in from app code.
+ *
+ * The rule has two halves that must BOTH hold in a release build, because a
+ * shipped app must never contact a broker on an end user's device:
+ *   1. a real Pro license (never the Weekend Pass — see useProAccess), and
+ *   2. an EXPLICIT opt-in from app code (`externalSync.enableInRelease`).
+ * Dev builds keep the zero-config behavior: sync is on unless turned off.
+ */
+
+/** The options object from the prop, or undefined when it's a boolean. */
+export function externalSyncOptions(externalSync) {
+  return typeof externalSync === "object" && externalSync !== null ? externalSync : undefined;
+}
+export function shouldMountExternalSync({
+  isDevelopment,
+  isLicensed,
+  externalSync,
+  isAvailable
+}) {
+  // Turned off outright, or the package isn't installed — nothing to mount.
+  if (externalSync === false) return false;
+  if (!isAvailable) return false;
+
+  // Dev builds: zero-config, on by default (historical behavior).
+  if (isDevelopment) return true;
+
+  // Release builds: opt-in only, and Pro only. `enableInRelease` has to be set
+  // by the app itself, so an app that just ships FloatingDevTools with a Pro
+  // key still never opens a socket on a customer's phone.
+  //
+  // The `isLicensed` half is belt-and-braces: FloatingDevTools already renders
+  // nothing at all for an unlicensed release build. Keep it anyway so this rule
+  // stands on its own and can't be broken by a change to that earlier return.
+  return isLicensed && externalSyncOptions(externalSync)?.enableInRelease === true;
+}

package/lib/module/floatingMenu/sync/appSyncAdapter.js

@@ -1,6 +1,6 @@
 "use strict";
 
-import { resolveReloadStrategy, scheduleReloadApp } from "@buoy-gg/shared-ui";
+import { getDevServerOrigin, resolveReloadStrategy, scheduleReloadApp } from "@buoy-gg/shared-ui";
 
 /**
  * Sync adapter for the "app" pseudo-tool — device-level capabilities that
@@ -24,12 +24,24 @@ import { resolveReloadStrategy, scheduleReloadApp } from "@buoy-gg/shared-ui";
  * and reporting it too early.
  */
 const REALM_STARTED_AT = Date.now();
+
+/**
+ * Where this bundle came from, resolved once at module load.
+ *
+ * Reported so a remote driver can recover the app when the app itself can no
+ * longer be asked to: after a fatal render error the React tree is gone, every
+ * tool action goes unanswered, and `reloadApp` below is unreachable. The dev
+ * server's reload path runs natively and still works — but only for a driver
+ * that learned this origin while the app was healthy.
+ */
+const DEV_SERVER_ORIGIN = getDevServerOrigin();
 export const appSyncAdapter = {
-  version: 1,
+  version: 2,
   getSnapshot: () => {
     const strategy = resolveReloadStrategy("auto");
     return {
       startedAt: REALM_STARTED_AT,
+      devServerOrigin: DEV_SERVER_ORIGIN,
       reload: {
         available: strategy !== null,
         strategy
@@ -47,7 +59,8 @@ export const appSyncAdapter = {
      */
     ping: () => ({
       ok: true,
-      startedAt: REALM_STARTED_AT
+      startedAt: REALM_STARTED_AT,
+      devServerOrigin: DEV_SERVER_ORIGIN
     }),
     /**
      * Reload the app's JS bundle: RN's `DevSettings.reload()` in dev builds,

package/lib/module/telemetry/installPing.js

@@ -0,0 +1,120 @@
+"use strict";
+
+/**
+ * Anonymous install ping.
+ *
+ * Answers the one question licensing data cannot: how many people run Buoy at
+ * all. Keygen sees every free and paid key, but by definition it cannot see an
+ * install that never claimed one — so without this, "what fraction of installs
+ * have an account" has no denominator.
+ *
+ * Constraints this is built to honor:
+ *
+ *  - **Development only.** Never fires from a shipped app. Buoy is a developer
+ *    tool; pinging from a release build would phone home from an end user's
+ *    device — someone who never chose to use Buoy — which is not a trade we are
+ *    willing to make for a metric.
+ *  - **No PII, no fingerprint.** The install id is a random UUID minted here.
+ *    It is not derived from hardware, account, project, or app identity, so it
+ *    cannot be correlated to a person or joined against anything else we hold.
+ *  - **No tool usage.** What you open and inspect stays on your machine, which
+ *    is the whole security story for enterprise adoption. Only the four fields
+ *    below ever leave.
+ *  - **Silent and harmless.** Fire-and-forget, throttled to once a day, and
+ *    every failure path is swallowed. It can never block, slow, or break an app.
+ *
+ * Opt out with `Buoy.init({ telemetry: false })`.
+ */
+
+import { Platform } from "react-native";
+import { persistentStorage } from "@buoy-gg/shared-ui";
+import { SDK_VERSION } from "../version.js";
+
+/** Same `@react_buoy` prefix as every other Buoy key, so it is inspectable. */
+const STORAGE_KEY = "@react_buoy_install";
+const ENDPOINT = "https://buoy.gg/api/t";
+
+/** One ping per install per day is enough to count installs and daily actives. */
+const PING_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** RFC4122 v4, from Math.random — this is a counter, not a credential. */
+function uuid() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, c => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 0x3 | 0x8;
+    return v.toString(16);
+  });
+}
+async function readState() {
+  try {
+    const raw = await persistentStorage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.installId !== "string") return null;
+    return {
+      installId: parsed.installId,
+      lastPingAt: typeof parsed.lastPingAt === "number" ? parsed.lastPingAt : 0
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Told once, on the very first ping of a new install — not on every launch.
+ *
+ * A dev tool that phones home silently deserves the reputation it would get.
+ * One line, the first time, saying exactly what leaves and how to stop it.
+ */
+function announceOnce() {
+  console.log("[Buoy] Anonymous usage ping enabled: a random install id, the Buoy " + "version, your platform, and your license tier — no project, app, or " + "tool data, and only in development. Opt out with " + "Buoy.init({ telemetry: false }). Details: https://buoy.gg/docs/telemetry");
+}
+let sentThisSession = false;
+
+/**
+ * Send the ping if it is due. Safe to call on every mount: it is idempotent
+ * within a session, throttled to once a day across sessions, and resolves
+ * without throwing no matter what fails.
+ */
+export async function sendInstallPing(options) {
+  // Never from a shipped app — see the header. This is the single most
+  // important line in the file.
+  const isDevelopment = typeof __DEV__ !== "undefined" && __DEV__;
+  if (!isDevelopment) return;
+  if (!options.enabled) return;
+  if (sentThisSession) return;
+  sentThisSession = true;
+  try {
+    const existing = await readState();
+    const now = Date.now();
+    if (existing && now - existing.lastPingAt < PING_INTERVAL_MS) return;
+    const installId = existing?.installId ?? uuid();
+    if (!existing) announceOnce();
+
+    // Recorded BEFORE the request, so a server that is down or unreachable
+    // can't turn into a ping every single mount.
+    await persistentStorage.setItem(STORAGE_KEY, JSON.stringify({
+      installId,
+      lastPingAt: now
+    }));
+    await fetch(ENDPOINT, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        installId,
+        version: SDK_VERSION,
+        platform: Platform.OS,
+        tier: options.tier
+      })
+    });
+  } catch {
+    // Offline, firewalled, endpoint down — all fine. A metric is never worth
+    // a warning in someone else's console.
+  }
+}
+
+/** Test seam: forget that a ping already went out this session. */
+export function __resetInstallPingForTests() {
+  sentThisSession = false;
+}

package/lib/module/version.js

@@ -0,0 +1,14 @@
+"use strict";
+
+/**
+ * This package's published version.
+ *
+ * Hardcoded rather than read from package.json: `require("../package.json")`
+ * resolves to a different depth from `src/` than from the built `lib/`, and
+ * react-native-builder-bob (babel) has no build-time `define` the way tsup does
+ * for @buoy-gg/mcp.
+ *
+ * Drift is prevented by a test that fails when this disagrees with
+ * package.json, so a version bump that forgets this file cannot ship.
+ */
+export const SDK_VERSION = "7.0.22";