@botim/mp-debug-sdk 0.4.1 → 0.6.1

package/dist/index.d.cts

@@ -52,6 +52,36 @@ interface BuiltinHostHooks {
      * The SDK enforces a 1 MB base64/JSON cap regardless.
      */
     screenshot?: () => ScreenshotResult | Promise<ScreenshotResult>;
+    /**
+     * Default-enabled remote-eval command (`exec`). Pass `false` to opt out
+     * of registration entirely; pass an object to inject extra locals into
+     * every snippet's scope.
+     *
+     *   builtins: { exec: false }
+     *     → exec NOT registered; agents calling exec see `unknown-command`.
+     *
+     *   builtins: { exec: { globals: { app, store } } }
+     *     → exec registered; snippets can reference `app` and `store` as
+     *       bare identifiers. Default locals (`BOT`, `window`, `document`)
+     *       are always present.
+     *
+     *   builtins.exec is undefined / not set
+     *     → default behaviour: exec registered with default locals only.
+     *
+     * See `openspec/changes/add-default-exec-builtin/design.md` for the
+     * security rationale (no prod-specific gating in MVP; relies on the
+     * existing `enableRemoteDebug` consent gate).
+     */
+    exec?: false | ExecOptions;
+}
+interface ExecOptions {
+    /**
+     * Additional locals bound into every snippet's scope. Keys MUST be
+     * valid identifier names (the SDK does not validate this — passing a
+     * key like "1foo" or "a-b" will throw at AsyncFunction construction
+     * time and surface as a `command-rejected`).
+     */
+    globals?: Record<string, unknown>;
 }
 type ScreenshotResult = string | {
     data: string;
@@ -71,6 +101,7 @@ type ScreenshotResult = string | {
      */
      | 'html-snapshot';
 };
+declare function getBOT(): unknown;
 
 /**
  * Per-signature sliding-window event deduper.
@@ -211,4 +242,4 @@ declare const DEFAULT_BUFFER_SIZE = 1000;
 declare const DEFAULT_MAX_BATCH_SIZE = 50;
 declare function enableRemoteDebug(options: RemoteDebugOptions): Promise<RemoteDebugHandle>;
 
-export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, ConsentInput, ConsolePayload, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, type DedupOptions, DeviceInfo, ErrorPayload, EventLevel, EventType, NetworkPayload, type RedactionConfig, type RemoteDebugHandle, type RemoteDebugOptions, type SamplingConfig, type SuppressionSummary, enableRemoteDebug };
+export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, ConsentInput, ConsolePayload, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, type DedupOptions, DeviceInfo, ErrorPayload, EventLevel, EventType, type ExecOptions, NetworkPayload, type RedactionConfig, type RemoteDebugHandle, type RemoteDebugOptions, type SamplingConfig, type SuppressionSummary, enableRemoteDebug, getBOT };

package/dist/index.d.ts

@@ -52,6 +52,36 @@ interface BuiltinHostHooks {
      * The SDK enforces a 1 MB base64/JSON cap regardless.
      */
     screenshot?: () => ScreenshotResult | Promise<ScreenshotResult>;
+    /**
+     * Default-enabled remote-eval command (`exec`). Pass `false` to opt out
+     * of registration entirely; pass an object to inject extra locals into
+     * every snippet's scope.
+     *
+     *   builtins: { exec: false }
+     *     → exec NOT registered; agents calling exec see `unknown-command`.
+     *
+     *   builtins: { exec: { globals: { app, store } } }
+     *     → exec registered; snippets can reference `app` and `store` as
+     *       bare identifiers. Default locals (`BOT`, `window`, `document`)
+     *       are always present.
+     *
+     *   builtins.exec is undefined / not set
+     *     → default behaviour: exec registered with default locals only.
+     *
+     * See `openspec/changes/add-default-exec-builtin/design.md` for the
+     * security rationale (no prod-specific gating in MVP; relies on the
+     * existing `enableRemoteDebug` consent gate).
+     */
+    exec?: false | ExecOptions;
+}
+interface ExecOptions {
+    /**
+     * Additional locals bound into every snippet's scope. Keys MUST be
+     * valid identifier names (the SDK does not validate this — passing a
+     * key like "1foo" or "a-b" will throw at AsyncFunction construction
+     * time and surface as a `command-rejected`).
+     */
+    globals?: Record<string, unknown>;
 }
 type ScreenshotResult = string | {
     data: string;
@@ -71,6 +101,7 @@ type ScreenshotResult = string | {
      */
      | 'html-snapshot';
 };
+declare function getBOT(): unknown;
 
 /**
  * Per-signature sliding-window event deduper.
@@ -211,4 +242,4 @@ declare const DEFAULT_BUFFER_SIZE = 1000;
 declare const DEFAULT_MAX_BATCH_SIZE = 50;
 declare function enableRemoteDebug(options: RemoteDebugOptions): Promise<RemoteDebugHandle>;
 
-export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, ConsentInput, ConsolePayload, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, type DedupOptions, DeviceInfo, ErrorPayload, EventLevel, EventType, NetworkPayload, type RedactionConfig, type RemoteDebugHandle, type RemoteDebugOptions, type SamplingConfig, type SuppressionSummary, enableRemoteDebug };
+export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, ConsentInput, ConsolePayload, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, type DedupOptions, DeviceInfo, ErrorPayload, EventLevel, EventType, type ExecOptions, NetworkPayload, type RedactionConfig, type RemoteDebugHandle, type RemoteDebugOptions, type SamplingConfig, type SuppressionSummary, enableRemoteDebug, getBOT };

package/dist/index.js

@@ -270,7 +270,7 @@ function resolveAgainstEndpoint(url, base) {
 function detectDeviceInfo(app, override) {
   const ua = typeof navigator !== "undefined" ? navigator.userAgent : void 0;
   return {
-    deviceId: override?.deviceId ?? generateDeviceId(),
+    deviceId: override?.deviceId ?? loadOrCreateDeviceId(),
     platform: override?.platform ?? detectPlatform(ua),
     osVersion: override?.osVersion,
     appName: override?.appName ?? app.name,
@@ -286,6 +286,21 @@ function detectPlatform(ua) {
   if (/Mozilla|Chrome|Safari|Firefox/i.test(ua)) return "web";
   return "unknown";
 }
+var DEVICE_ID_STORAGE_KEY = "botim-debug-sdk:device-id";
+function loadOrCreateDeviceId() {
+  try {
+    const ls = typeof localStorage !== "undefined" ? localStorage : null;
+    if (ls) {
+      const stored = ls.getItem(DEVICE_ID_STORAGE_KEY);
+      if (stored && stored.length > 0) return stored;
+      const fresh = generateDeviceId();
+      ls.setItem(DEVICE_ID_STORAGE_KEY, fresh);
+      return fresh;
+    }
+  } catch {
+  }
+  return generateDeviceId();
+}
 function generateDeviceId() {
   const c = typeof crypto !== "undefined" ? crypto : void 0;
   if (c?.randomUUID) return c.randomUUID();
@@ -560,6 +575,11 @@ function wrapFetch(opts) {
         method,
         url,
         status: res.status,
+        // statusText carries the human label ("OK", "Not Found"). Pre-HTTP/2
+        // responses always have it; HTTP/2+ defines it as empty by spec but
+        // most browsers synthesize one from the code, so this is reliable
+        // enough to display alongside the status code.
+        statusText: res.statusText || void 0,
         durationMs: Date.now() - start,
         resHeaders: headersFromResponse(res),
         resBody
@@ -573,7 +593,14 @@ function wrapFetch(opts) {
         url,
         durationMs: Date.now() - start,
         errorMessage: err instanceof Error ? err.message : String(err),
-        errorName: err instanceof Error ? err.name : void 0
+        errorName: err instanceof Error ? err.name : void 0,
+        // Stack from the rejected promise — points into fetch internals
+        // and (when present) the call site that issued the request.
+        errorStack: err instanceof Error ? err.stack : void 0,
+        // undici frequently wraps the real reason in `cause` (e.g.
+        // `TypeError: fetch failed` outside, `Error: ECONNREFUSED` inside).
+        // Flatten the chain so operators don't have to dig.
+        errorCause: collectCauseChain(err)
       });
       throw err;
     }
@@ -582,6 +609,24 @@ function wrapFetch(opts) {
     target.fetch = original;
   };
 }
+function collectCauseChain(err) {
+  if (!err || typeof err !== "object") return void 0;
+  const lines = [];
+  let cur = err.cause;
+  const seen = /* @__PURE__ */ new Set();
+  while (cur && lines.length < 5) {
+    if (seen.has(cur)) break;
+    seen.add(cur);
+    if (cur instanceof Error) {
+      lines.push(`${cur.name}: ${cur.message}`);
+      cur = cur.cause;
+    } else {
+      lines.push(String(cur));
+      cur = cur?.cause;
+    }
+  }
+  return lines.length ? lines.join("\n") : void 0;
+}
 function wrapXHR(opts) {
   if (typeof XMLHttpRequest === "undefined") return () => {
   };
@@ -617,6 +662,7 @@ function wrapXHR(opts) {
     }
     s.start = Date.now();
     s.reqBody = typeof body === "string" ? body : void 0;
+    const sendSiteStack = captureCallSiteStack();
     opts.emit({
       phase: "request",
       reqId: s.reqId,
@@ -634,25 +680,32 @@ function wrapXHR(opts) {
         method: s.method,
         url: s.url,
         status: this.status,
+        // XHR exposes statusText directly; same display purpose as fetch.
+        statusText: this.statusText || void 0,
         durationMs: Date.now() - s.start,
         resHeaders: headers,
         resBody
       });
     };
-    const onError = () => {
+    const onError = (kind) => () => {
       opts.emit({
         phase: "error",
         reqId: s.reqId,
         method: s.method,
         url: s.url,
         durationMs: Date.now() - s.start,
-        errorMessage: this.statusText || "xhr error"
+        // Distinguish error/timeout/abort in the message — the standard
+        // XHR `statusText` is empty for `error` and unhelpful for the
+        // others, so we synthesise a clear label.
+        errorMessage: this.statusText || `xhr ${kind}`,
+        errorName: `XHR${kind[0].toUpperCase()}${kind.slice(1)}`,
+        errorStack: sendSiteStack
       });
     };
     this.addEventListener("load", onLoad);
-    this.addEventListener("error", onError);
-    this.addEventListener("timeout", onError);
-    this.addEventListener("abort", onError);
+    this.addEventListener("error", onError("error"));
+    this.addEventListener("timeout", onError("timeout"));
+    this.addEventListener("abort", onError("abort"));
     return origSend.apply(this, [body]);
   };
   return () => {
@@ -661,6 +714,15 @@ function wrapXHR(opts) {
     proto.setRequestHeader = origSetReqHeader;
   };
 }
+function captureCallSiteStack() {
+  try {
+    throw new Error("xhr-callsite");
+  } catch (err) {
+    if (!(err instanceof Error) || !err.stack) return void 0;
+    const lines = err.stack.split("\n");
+    return lines.slice(2).join("\n") || void 0;
+  }
+}
 function parseXhrHeaders(raw) {
   const out = {};
   if (!raw) return out;
@@ -755,6 +817,10 @@ var CommandRegistry = class {
 };
 var MAX_DUMP_BYTES = 64 * 1024;
 var MAX_SCREENSHOT_BYTES = 1024 * 1024;
+var MAX_EXEC_CODE_BYTES = 8 * 1024;
+var DEFAULT_EXEC_TIMEOUT_MS = 5e3;
+var MIN_EXEC_TIMEOUT_MS = 250;
+var MAX_EXEC_TIMEOUT_MS = 3e4;
 async function defaultDomScreenshot() {
   if (typeof document === "undefined" || typeof window === "undefined") {
     throw new Error(
@@ -869,6 +935,9 @@ function registerBuiltins(registry, hooks = {}) {
   registry.register("dump-state", makeDumpState(hooks.getState));
   registry.register("set-feature-flag", makeSetFlag(hooks.setFeatureFlag));
   registry.register("screenshot", makeScreenshot(hooks.screenshot));
+  if (hooks.exec !== false) {
+    registry.register("exec", makeExec(hooks.exec ?? {}));
+  }
 }
 var ping = () => ({ ok: true, ts: Date.now() });
 function makeReload(reload) {
@@ -931,6 +1000,168 @@ function makeScreenshot(screenshot) {
     return { format, data, bytes: data.length };
   };
 }
+var cachedBOT = void 0;
+function getBOT() {
+  if (cachedBOT !== void 0) return cachedBOT;
+  if (typeof window === "undefined") {
+    cachedBOT = null;
+    return null;
+  }
+  try {
+    const w = window;
+    if (w.BOT) {
+      cachedBOT = w.BOT;
+      return cachedBOT;
+    }
+  } catch {
+  }
+  try {
+    const w = window;
+    const ng = w.angular;
+    if (ng?.element && typeof document !== "undefined") {
+      const injector = ng.element(document).injector?.();
+      const bot = injector?.get?.("BOT");
+      if (bot != null) {
+        cachedBOT = bot;
+        return cachedBOT;
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+function makeExec(opts) {
+  const extraGlobalNames = Object.keys(opts.globals ?? {});
+  const extraGlobalValues = extraGlobalNames.map((k) => opts.globals[k]);
+  return async (args, ctx) => {
+    if (typeof args.code !== "string" || args.code.length === 0) {
+      throw new Error("args.code (non-empty string) is required");
+    }
+    if (args.code.length > MAX_EXEC_CODE_BYTES) {
+      throw new Error(`args.code ${args.code.length} bytes exceeds limit ${MAX_EXEC_CODE_BYTES}`);
+    }
+    const timeoutMs = clamp(
+      typeof args.timeoutMs === "number" ? args.timeoutMs : DEFAULT_EXEC_TIMEOUT_MS,
+      MIN_EXEC_TIMEOUT_MS,
+      MAX_EXEC_TIMEOUT_MS
+    );
+    const start = Date.now();
+    const logs = [];
+    const consoleMethods = ["log", "info", "warn", "error", "debug"];
+    const originals = {};
+    if (typeof console !== "undefined") {
+      for (const m of consoleMethods) {
+        const orig = console[m];
+        if (typeof orig !== "function") continue;
+        originals[m] = orig;
+        const captured = (...callArgs) => {
+          logs.push({ method: m, args: callArgs.map(execSafeClone), ts: Date.now() });
+          try {
+            orig.call(console, ...callArgs);
+          } catch {
+          }
+        };
+        console[m] = captured;
+      }
+    }
+    let value;
+    let threw = void 0;
+    try {
+      const AsyncFunction = Object.getPrototypeOf(async function() {
+      }).constructor;
+      const localNames = ["BOT", "window", "document", ...extraGlobalNames];
+      const localValues = [
+        getBOT(),
+        typeof window !== "undefined" ? window : void 0,
+        typeof document !== "undefined" ? document : void 0,
+        ...extraGlobalValues
+      ];
+      let fnTry = null;
+      try {
+        fnTry = new AsyncFunction(...localNames, `return (${args.code});`);
+      } catch (e) {
+        if (!(e instanceof SyntaxError)) throw e;
+      }
+      const fn = fnTry ?? new AsyncFunction(...localNames, args.code);
+      let timer = null;
+      let abortReject = null;
+      const onAbort = () => abortReject?.(new Error("exec cancelled"));
+      ctx.signal?.addEventListener?.("abort", onAbort);
+      try {
+        value = await Promise.race([
+          fn(...localValues),
+          new Promise((_, reject) => {
+            timer = setTimeout(
+              () => reject(new Error(`exec exceeded ${timeoutMs}ms`)),
+              timeoutMs
+            );
+          }),
+          new Promise((_, reject) => {
+            abortReject = reject;
+          })
+        ]);
+      } finally {
+        if (timer) clearTimeout(timer);
+        ctx.signal?.removeEventListener?.("abort", onAbort);
+      }
+    } catch (err) {
+      threw = err;
+    } finally {
+      if (typeof console !== "undefined") {
+        for (const m of consoleMethods) {
+          if (originals[m]) {
+            console[m] = originals[m];
+          }
+        }
+      }
+    }
+    if (threw !== void 0) {
+      const e = threw instanceof Error ? threw : new Error(String(threw));
+      const stackTruncated = typeof e.stack === "string" ? e.stack.split("\n").slice(0, 20).join("\n") : void 0;
+      const detail = {
+        name: e.name,
+        message: e.message,
+        stack: stackTruncated,
+        logs,
+        durationMs: Date.now() - start
+      };
+      const wrapped = new Error(JSON.stringify(detail));
+      wrapped.detail = detail;
+      throw wrapped;
+    }
+    return {
+      ok: true,
+      value: execSafeClone(value),
+      logs,
+      durationMs: Date.now() - start
+    };
+  };
+}
+function clamp(n, lo, hi) {
+  if (!Number.isFinite(n)) return lo;
+  return Math.min(Math.max(n, lo), hi);
+}
+function execSafeClone(v) {
+  try {
+    return JSON.parse(JSON.stringify(v, (_k, val) => {
+      if (typeof val === "function") {
+        return `[Function: ${val.name || "anonymous"}]`;
+      }
+      if (val instanceof Error) {
+        return { name: val.name, message: val.message, stack: val.stack };
+      }
+      if (typeof val === "bigint") return val.toString() + "n";
+      if (typeof val === "undefined") return null;
+      if (val && typeof val === "object" && val.nodeType === 1) {
+        const el = val;
+        return `[${el.tagName ?? "Element"}${el.id ? "#" + el.id : ""}]`;
+      }
+      return val;
+    }));
+  } catch {
+    return { __unserializable: typeof v };
+  }
+}
 function safeStringify(v) {
   try {
     const seen = /* @__PURE__ */ new WeakSet();
@@ -1368,6 +1599,6 @@ async function enableRemoteDebug(options) {
   };
 }
 
-export { BotimConfigError, BotimConsentError, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, SCHEMA_VERSION, enableRemoteDebug };
+export { BotimConfigError, BotimConsentError, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, SCHEMA_VERSION, enableRemoteDebug, getBOT };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map