@botim/mp-debug-sdk 0.7.0 → 0.7.1

package/dist/types.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";;;AAAO,IAAM,cAAA,GAAiB","file":"types.cjs","sourcesContent":["export const SCHEMA_VERSION = 2 as const;\n\nexport type EventLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';\n\nexport type EventType =\n  | 'console'\n  | 'network'\n  | 'error'\n  | 'lifecycle'\n  | 'bridge'\n  | 'perf'\n  | 'command-ack'\n  | 'command-rejected';\n\nexport interface DebugEventBase {\n  v: typeof SCHEMA_VERSION;\n  sid: string;\n  seq: number;\n  ts: number;\n  type: EventType;\n  level: EventLevel;\n  meta?: EventMeta;\n}\n\nexport interface EventMeta {\n  route?: string;\n  build?: string;\n  appVersion?: string;\n  deviceId?: string;\n  userIdHash?: string;\n  /** Set on command-ack / command-rejected events to correlate with the originating CommandRequest. */\n  commandId?: string;\n  /**\n   * Set ONLY on synthesized rollup events emitted by the SDK's deduper.\n   * Carries the count of suppressed identical events in the just-closed\n   * window. Original (non-suppressed) events do NOT carry this field.\n   */\n  dedup?: {\n    /** Stable signature used to bucket the suppressed events. */\n    signature: string;\n    /** Number of suppressed occurrences (excludes the leading event that was already emitted). */\n    count: number;\n    /** Timestamp of the first occurrence in the window. */\n    firstTs: number;\n    /** Timestamp of the last occurrence in the window. */\n    lastTs: number;\n  };\n}\n\nexport type SerializedValue =\n  | { k: 'primitive'; v: string | number | boolean | null }\n  | { k: 'undefined' }\n  | { k: 'string'; v: string; truncated?: boolean }\n  | { k: 'json'; v: string; truncated?: boolean }\n  | { k: 'error'; name: string; message: string; stack?: string }\n  | { k: 'circular' }\n  | { k: 'function'; name?: string }\n  | { k: 'unserializable'; reason: string };\n\nexport interface ConsolePayload {\n  method: 'log' | 'info' | 'warn' | 'error' | 'debug';\n  args: SerializedValue[];\n}\n\nexport type NetworkPhase = 'request' | 'response' | 'error';\n\nexport interface NetworkPayload {\n  phase: NetworkPhase;\n  reqId: string;\n  method: string;\n  url: string;\n  status?: number;\n  /** HTTP status text (e.g., \"OK\", \"Not Found\"). Lets the admin show \"200 OK\". */\n  statusText?: string;\n  durationMs?: number;\n  reqHeaders?: Record<string, string>;\n  reqBody?: string;\n  reqBodyTruncated?: boolean;\n  resHeaders?: Record<string, string>;\n  resBody?: string;\n  resBodyTruncated?: boolean;\n  errorMessage?: string;\n  errorName?: string;\n  /** Stack trace for the failing call. Captured at the failure site so\n   *  operators can locate the originating code path. For fetch this is\n   *  `err.stack` from the rejected promise; for XHR (which doesn't carry\n   *  an Error object on `error`/`timeout`/`abort`) we synthesise a stack\n   *  from the call site of `xhr.send()`. */\n  errorStack?: string;\n  /** Flattened cause chain (`err.cause.cause...`) — undici-style fetch\n   *  failures frequently wrap the useful reason here (e.g. `ECONNREFUSED`\n   *  inside a generic `TypeError: fetch failed`). One line per cause. */\n  errorCause?: string;\n}\n\nexport type ErrorSource = 'window.error' | 'unhandledrejection' | 'manual';\n\nexport interface ErrorPayload {\n  message: string;\n  name?: string;\n  stack?: string;\n  source: ErrorSource;\n  filename?: string;\n  lineno?: number;\n  colno?: number;\n}\n\nexport type LifecycleEvent =\n  | 'launch'\n  | 'pageShow'\n  | 'pageHide'\n  | 'route'\n  | 'background'\n  | 'foreground'\n  | 'visibilityChange';\n\nexport interface LifecyclePayload {\n  event: LifecycleEvent;\n  data?: Record<string, unknown>;\n}\n\nexport interface BridgePayload {\n  fn: string;\n  argsPreview?: string;\n  result?: 'ok' | 'error';\n  durationMs?: number;\n  errorMessage?: string;\n}\n\nexport interface PerfPayload {\n  metric: string;\n  value: number;\n  unit?: string;\n}\n\n/** Payload for command-ack: the handler ran, here's its result. */\nexport interface CommandAckPayload {\n  command: string;\n  ok: boolean;\n  /** Handler return value, JSON-serializable. */\n  result?: unknown;\n  durationMs?: number;\n}\n\n/** Payload for command-rejected: relay sent a command we won't run. */\nexport interface CommandRejectedPayload {\n  command: string;\n  reason:\n    | 'unknown-command'\n    | 'rate-limited'\n    | 'invalid-args'\n    | 'handler-threw'\n    | 'overridden';\n  details?: string;\n}\n\nexport type DebugEvent =\n  | (DebugEventBase & { type: 'console';           payload: ConsolePayload })\n  | (DebugEventBase & { type: 'network';           payload: NetworkPayload })\n  | (DebugEventBase & { type: 'error';             payload: ErrorPayload })\n  | (DebugEventBase & { type: 'lifecycle';         payload: LifecyclePayload })\n  | (DebugEventBase & { type: 'bridge';            payload: BridgePayload })\n  | (DebugEventBase & { type: 'perf';              payload: PerfPayload })\n  | (DebugEventBase & { type: 'command-ack';       payload: CommandAckPayload })\n  | (DebugEventBase & { type: 'command-rejected';  payload: CommandRejectedPayload });\n\nexport interface UploadBatch {\n  sessionToken: string;\n  events: DebugEvent[];\n}\n\nexport interface UploadAck {\n  acceptedSeq: number;\n  rejected?: Array<{ seq: number; reason: string }>;\n}\n\nexport type StreamFrame =\n  | { kind: 'hello'; sid: string; devices: number }\n  | { kind: 'event'; event: DebugEvent }\n  | { kind: 'device-join'; deviceInfo: DeviceInfo }\n  | { kind: 'device-leave'; deviceId: string }\n  | { kind: 'gap'; deviceId: string; expectedSeq: number; gotSeq: number }\n  | { kind: 'session-end'; reason: string };\n\nexport interface DeviceInfo {\n  deviceId: string;\n  platform: 'ios' | 'android' | 'web' | 'unknown';\n  osVersion?: string;\n  appName?: string;\n  appVersion?: string;\n  appBuild?: string;\n  userAgent?: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Build-time identity (resolved by the Vite plugin from `botim.{env}.json`)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport type BotimEnv = 'dev' | 'uat' | 'beta' | 'prod';\n\n/**\n * The contents of `botim.{env}.json`, resolved at build time and injected\n * into the bundle via the virtual module `virtual:botim/config`.\n */\nexport interface BotimConfig {\n  miniProgramId: string;\n  env: BotimEnv;\n  /** Short hash of the resolved config or the build, set by the plugin. */\n  buildSignature: string;\n  appName?: string;\n  appVersion?: string;\n  /** Forward-compatible bag for fields the relay may add later. */\n  [extra: string]: unknown;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Consent\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface ConsentInput {\n  /** JWT issued by the BOTIM host runtime — strongest form. */\n  hostToken?: string;\n  /** Explicit user opt-in (e.g., set after a privacy dialog). */\n  userOptIn?: boolean;\n  /**\n   * If true, the SDK shows an in-app consent modal on first load and\n   * persists the user's choice in `localStorage` (key\n   * `__botim_debug_consent_<mpId>`). On subsequent loads the cached\n   * decision is honored without re-prompting. The modal sets\n   * `userOptIn: true` if the user accepts, or short-circuits attach if\n   * they decline. Mutually orthogonal to `hostToken`/`userOptIn`: those\n   * still take effect if explicitly set.\n   *\n   * No-op when `document` / `window` are unavailable (non-DOM runtimes).\n   */\n  promptUser?: boolean;\n  /**\n   * Optional copy override for the consent modal. Keys map to the\n   * default English strings; provide any subset to localize.\n   */\n  promptCopy?: ConsentPromptCopy;\n}\n\nexport interface ConsentPromptCopy {\n  /** Short headline. Default: \"Enable BOTIM debug logging?\" */\n  title?: string;\n  /**\n   * Body paragraphs (rendered as separate <p> elements). Default\n   * explains what data is collected and that the user can revoke.\n   */\n  body?: string[];\n  /** Default: \"Allow\" */\n  acceptLabel?: string;\n  /** Default: \"Skip\" */\n  declineLabel?: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Wire protocol — attach\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface AttachRequest {\n  miniProgramId: string;\n  env: BotimEnv;\n  buildSignature: string;\n  deviceInfo: DeviceInfo;\n  consent: ConsentInput;\n  schemaVersion: typeof SCHEMA_VERSION;\n}\n\nexport interface AttachResponse {\n  sid: string;\n  deviceToken: string;\n  expiresAt: number;\n  ingestUrl: string;\n  /** Endpoint the device long-polls for AI-issued commands. */\n  commandPollUrl: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Wire protocol — commands (relay → device → ack)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface CommandRequest {\n  /** Relay-issued unique id, echoed in the resulting ack/rejected event. */\n  id: string;\n  /** Registered command name (kebab-case). */\n  name: string;\n  /** Arbitrary JSON args, validated by the handler. */\n  args?: Record<string, unknown>;\n  /** Optional deadline; handlers SHOULD respect it. */\n  deadlineTs?: number;\n}\n\n/** Long-poll response shape from `commandPollUrl`. */\nexport interface CommandPollResponse {\n  commands: CommandRequest[];\n  /** Suggested seconds until the next poll. */\n  nextDelayMs?: number;\n}\n\nexport type CommandHandler = (\n  args: Record<string, unknown>,\n  ctx: CommandContext,\n) => unknown | Promise<unknown>;\n\nexport interface CommandContext {\n  commandId: string;\n  command: string;\n  signal: AbortSignal;\n}\n"]}
+{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";;;AAAO,IAAM,cAAA,GAAiB","file":"types.cjs","sourcesContent":["export const SCHEMA_VERSION = 2 as const;\n\nexport type EventLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';\n\nexport type EventType =\n  | 'console'\n  | 'network'\n  | 'error'\n  | 'lifecycle'\n  | 'bridge'\n  | 'perf'\n  | 'command-ack'\n  | 'command-rejected';\n\nexport interface DebugEventBase {\n  v: typeof SCHEMA_VERSION;\n  sid: string;\n  seq: number;\n  ts: number;\n  type: EventType;\n  level: EventLevel;\n  meta?: EventMeta;\n}\n\nexport interface EventMeta {\n  route?: string;\n  build?: string;\n  appVersion?: string;\n  deviceId?: string;\n  userIdHash?: string;\n  /** Set on command-ack / command-rejected events to correlate with the originating CommandRequest. */\n  commandId?: string;\n  /**\n   * Set ONLY on synthesized rollup events emitted by the SDK's deduper.\n   * Carries the count of suppressed identical events in the just-closed\n   * window. Original (non-suppressed) events do NOT carry this field.\n   */\n  dedup?: {\n    /** Stable signature used to bucket the suppressed events. */\n    signature: string;\n    /** Number of suppressed occurrences (excludes the leading event that was already emitted). */\n    count: number;\n    /** Timestamp of the first occurrence in the window. */\n    firstTs: number;\n    /** Timestamp of the last occurrence in the window. */\n    lastTs: number;\n  };\n}\n\nexport type SerializedValue =\n  | { k: 'primitive'; v: string | number | boolean | null }\n  | { k: 'undefined' }\n  | { k: 'string'; v: string; truncated?: boolean }\n  | { k: 'json'; v: string; truncated?: boolean }\n  | { k: 'error'; name: string; message: string; stack?: string }\n  | { k: 'circular' }\n  | { k: 'function'; name?: string }\n  | { k: 'unserializable'; reason: string };\n\nexport interface ConsolePayload {\n  method: 'log' | 'info' | 'warn' | 'error' | 'debug';\n  args: SerializedValue[];\n}\n\nexport type NetworkPhase = 'request' | 'response' | 'error';\n\nexport interface NetworkPayload {\n  phase: NetworkPhase;\n  reqId: string;\n  method: string;\n  url: string;\n  status?: number;\n  /** HTTP status text (e.g., \"OK\", \"Not Found\"). Lets the admin show \"200 OK\". */\n  statusText?: string;\n  durationMs?: number;\n  reqHeaders?: Record<string, string>;\n  reqBody?: string;\n  reqBodyTruncated?: boolean;\n  resHeaders?: Record<string, string>;\n  resBody?: string;\n  resBodyTruncated?: boolean;\n  errorMessage?: string;\n  errorName?: string;\n  /** Stack trace for the failing call. Captured at the failure site so\n   *  operators can locate the originating code path. For fetch this is\n   *  `err.stack` from the rejected promise; for XHR (which doesn't carry\n   *  an Error object on `error`/`timeout`/`abort`) we synthesise a stack\n   *  from the call site of `xhr.send()`. */\n  errorStack?: string;\n  /** Flattened cause chain (`err.cause.cause...`) — undici-style fetch\n   *  failures frequently wrap the useful reason here (e.g. `ECONNREFUSED`\n   *  inside a generic `TypeError: fetch failed`). One line per cause. */\n  errorCause?: string;\n}\n\nexport type ErrorSource = 'window.error' | 'unhandledrejection' | 'manual';\n\nexport interface ErrorPayload {\n  message: string;\n  name?: string;\n  stack?: string;\n  source: ErrorSource;\n  filename?: string;\n  lineno?: number;\n  colno?: number;\n}\n\nexport type LifecycleEvent =\n  | 'launch'\n  | 'pageShow'\n  | 'pageHide'\n  | 'route'\n  | 'background'\n  | 'foreground'\n  | 'visibilityChange';\n\nexport interface LifecyclePayload {\n  event: LifecycleEvent;\n  data?: Record<string, unknown>;\n}\n\nexport interface BridgePayload {\n  fn: string;\n  argsPreview?: string;\n  result?: 'ok' | 'error';\n  durationMs?: number;\n  errorMessage?: string;\n}\n\nexport interface PerfPayload {\n  metric: string;\n  value: number;\n  unit?: string;\n}\n\n/** Payload for command-ack: the handler ran, here's its result. */\nexport interface CommandAckPayload {\n  command: string;\n  ok: boolean;\n  /** Handler return value, JSON-serializable. */\n  result?: unknown;\n  durationMs?: number;\n}\n\n/** Payload for command-rejected: relay sent a command we won't run. */\nexport interface CommandRejectedPayload {\n  command: string;\n  reason:\n    | 'unknown-command'\n    | 'rate-limited'\n    | 'invalid-args'\n    | 'handler-threw'\n    | 'overridden';\n  details?: string;\n}\n\nexport type DebugEvent =\n  | (DebugEventBase & { type: 'console';           payload: ConsolePayload })\n  | (DebugEventBase & { type: 'network';           payload: NetworkPayload })\n  | (DebugEventBase & { type: 'error';             payload: ErrorPayload })\n  | (DebugEventBase & { type: 'lifecycle';         payload: LifecyclePayload })\n  | (DebugEventBase & { type: 'bridge';            payload: BridgePayload })\n  | (DebugEventBase & { type: 'perf';              payload: PerfPayload })\n  | (DebugEventBase & { type: 'command-ack';       payload: CommandAckPayload })\n  | (DebugEventBase & { type: 'command-rejected';  payload: CommandRejectedPayload });\n\nexport interface UploadBatch {\n  sessionToken: string;\n  events: DebugEvent[];\n}\n\nexport interface UploadAck {\n  acceptedSeq: number;\n  rejected?: Array<{ seq: number; reason: string }>;\n}\n\nexport type StreamFrame =\n  | { kind: 'hello'; sid: string; devices: number }\n  | { kind: 'event'; event: DebugEvent }\n  | { kind: 'device-join'; deviceInfo: DeviceInfo }\n  | { kind: 'device-leave'; deviceId: string }\n  | { kind: 'gap'; deviceId: string; expectedSeq: number; gotSeq: number }\n  | { kind: 'session-end'; reason: string };\n\nexport interface DeviceInfo {\n  deviceId: string;\n  platform: 'ios' | 'android' | 'web' | 'unknown';\n  osVersion?: string;\n  appName?: string;\n  appVersion?: string;\n  appBuild?: string;\n  userAgent?: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Build-time identity (resolved by the Vite plugin from `botim.{env}.json`)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport type BotimEnv = 'dev' | 'uat' | 'beta' | 'prod';\n\n/**\n * The contents of `botim.{env}.json`, resolved at build time and injected\n * into the bundle via the virtual module `virtual:botim/config`.\n */\nexport interface BotimConfig {\n  miniProgramId: string;\n  env: BotimEnv;\n  /** Short hash of the resolved config or the build, set by the plugin. */\n  buildSignature: string;\n  appName?: string;\n  appVersion?: string;\n  /** Forward-compatible bag for fields the relay may add later. */\n  [extra: string]: unknown;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Consent\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface ConsentInput {\n  /** JWT issued by the BOTIM host runtime — strongest form. */\n  hostToken?: string;\n  /** Explicit user opt-in (e.g., set after a privacy dialog). */\n  userOptIn?: boolean;\n  /**\n   * Controls whether the SDK shows its built-in consent modal.\n   *\n   * Default behavior (as of 0.7.1) is to **show the modal automatically**\n   * whenever:\n   *   • the host did NOT provide `userOptIn: true` or a `hostToken`, AND\n   *   • a DOM is available (`document` and `window` exist).\n   *\n   * The user's decision is persisted in `localStorage` under the key\n   * `__botim_debug_consent_<mpId>` so subsequent loads attach silently\n   * (or stay disabled, if declined) without re-prompting.\n   *\n   * Set to `false` to suppress the modal — useful for automated test\n   * harnesses, hosts that wire their own consent UX upstream, or any\n   * environment where a blocking dialog is undesirable. When suppressed,\n   * `assertConsent` runs as before: it requires `userOptIn` or\n   * `hostToken` in `prod`, and is a no-op in non-prod envs.\n   *\n   * Set to `true` for symmetry / explicitness — same effect as the\n   * default when no other consent signal is present.\n   *\n   * Has no effect in non-DOM runtimes (native bridges, SSR) since the\n   * modal can't be rendered there. Provide `userOptIn`/`hostToken` for\n   * those.\n   */\n  promptUser?: boolean;\n  /**\n   * Optional copy override for the consent modal. Keys map to the\n   * default English strings; provide any subset to localize.\n   */\n  promptCopy?: ConsentPromptCopy;\n}\n\nexport interface ConsentPromptCopy {\n  /** Short headline. Default: \"Enable BOTIM debug logging?\" */\n  title?: string;\n  /**\n   * Body paragraphs (rendered as separate <p> elements). Default\n   * explains what data is collected and that the user can revoke.\n   */\n  body?: string[];\n  /** Default: \"Allow\" */\n  acceptLabel?: string;\n  /** Default: \"Skip\" */\n  declineLabel?: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Wire protocol — attach\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface AttachRequest {\n  miniProgramId: string;\n  env: BotimEnv;\n  buildSignature: string;\n  deviceInfo: DeviceInfo;\n  consent: ConsentInput;\n  schemaVersion: typeof SCHEMA_VERSION;\n}\n\nexport interface AttachResponse {\n  sid: string;\n  deviceToken: string;\n  expiresAt: number;\n  ingestUrl: string;\n  /** Endpoint the device long-polls for AI-issued commands. */\n  commandPollUrl: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Wire protocol — commands (relay → device → ack)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface CommandRequest {\n  /** Relay-issued unique id, echoed in the resulting ack/rejected event. */\n  id: string;\n  /** Registered command name (kebab-case). */\n  name: string;\n  /** Arbitrary JSON args, validated by the handler. */\n  args?: Record<string, unknown>;\n  /** Optional deadline; handlers SHOULD respect it. */\n  deadlineTs?: number;\n}\n\n/** Long-poll response shape from `commandPollUrl`. */\nexport interface CommandPollResponse {\n  commands: CommandRequest[];\n  /** Suggested seconds until the next poll. */\n  nextDelayMs?: number;\n}\n\nexport type CommandHandler = (\n  args: Record<string, unknown>,\n  ctx: CommandContext,\n) => unknown | Promise<unknown>;\n\nexport interface CommandContext {\n  commandId: string;\n  command: string;\n  signal: AbortSignal;\n}\n"]}

package/dist/types.d.cts

@@ -223,15 +223,29 @@ interface ConsentInput {
     /** Explicit user opt-in (e.g., set after a privacy dialog). */
     userOptIn?: boolean;
     /**
-     * If true, the SDK shows an in-app consent modal on first load and
-     * persists the user's choice in `localStorage` (key
-     * `__botim_debug_consent_<mpId>`). On subsequent loads the cached
-     * decision is honored without re-prompting. The modal sets
-     * `userOptIn: true` if the user accepts, or short-circuits attach if
-     * they decline. Mutually orthogonal to `hostToken`/`userOptIn`: those
-     * still take effect if explicitly set.
+     * Controls whether the SDK shows its built-in consent modal.
      *
-     * No-op when `document` / `window` are unavailable (non-DOM runtimes).
+     * Default behavior (as of 0.7.1) is to **show the modal automatically**
+     * whenever:
+     *   • the host did NOT provide `userOptIn: true` or a `hostToken`, AND
+     *   • a DOM is available (`document` and `window` exist).
+     *
+     * The user's decision is persisted in `localStorage` under the key
+     * `__botim_debug_consent_<mpId>` so subsequent loads attach silently
+     * (or stay disabled, if declined) without re-prompting.
+     *
+     * Set to `false` to suppress the modal — useful for automated test
+     * harnesses, hosts that wire their own consent UX upstream, or any
+     * environment where a blocking dialog is undesirable. When suppressed,
+     * `assertConsent` runs as before: it requires `userOptIn` or
+     * `hostToken` in `prod`, and is a no-op in non-prod envs.
+     *
+     * Set to `true` for symmetry / explicitness — same effect as the
+     * default when no other consent signal is present.
+     *
+     * Has no effect in non-DOM runtimes (native bridges, SSR) since the
+     * modal can't be rendered there. Provide `userOptIn`/`hostToken` for
+     * those.
      */
     promptUser?: boolean;
     /**

package/dist/types.d.ts

@@ -223,15 +223,29 @@ interface ConsentInput {
     /** Explicit user opt-in (e.g., set after a privacy dialog). */
     userOptIn?: boolean;
     /**
-     * If true, the SDK shows an in-app consent modal on first load and
-     * persists the user's choice in `localStorage` (key
-     * `__botim_debug_consent_<mpId>`). On subsequent loads the cached
-     * decision is honored without re-prompting. The modal sets
-     * `userOptIn: true` if the user accepts, or short-circuits attach if
-     * they decline. Mutually orthogonal to `hostToken`/`userOptIn`: those
-     * still take effect if explicitly set.
+     * Controls whether the SDK shows its built-in consent modal.
      *
-     * No-op when `document` / `window` are unavailable (non-DOM runtimes).
+     * Default behavior (as of 0.7.1) is to **show the modal automatically**
+     * whenever:
+     *   • the host did NOT provide `userOptIn: true` or a `hostToken`, AND
+     *   • a DOM is available (`document` and `window` exist).
+     *
+     * The user's decision is persisted in `localStorage` under the key
+     * `__botim_debug_consent_<mpId>` so subsequent loads attach silently
+     * (or stay disabled, if declined) without re-prompting.
+     *
+     * Set to `false` to suppress the modal — useful for automated test
+     * harnesses, hosts that wire their own consent UX upstream, or any
+     * environment where a blocking dialog is undesirable. When suppressed,
+     * `assertConsent` runs as before: it requires `userOptIn` or
+     * `hostToken` in `prod`, and is a no-op in non-prod envs.
+     *
+     * Set to `true` for symmetry / explicitness — same effect as the
+     * default when no other consent signal is present.
+     *
+     * Has no effect in non-DOM runtimes (native bridges, SSR) since the
+     * modal can't be rendered there. Provide `userOptIn`/`hostToken` for
+     * those.
      */
     promptUser?: boolean;
     /**

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";AAAO,IAAM,cAAA,GAAiB","file":"types.js","sourcesContent":["export const SCHEMA_VERSION = 2 as const;\n\nexport type EventLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';\n\nexport type EventType =\n  | 'console'\n  | 'network'\n  | 'error'\n  | 'lifecycle'\n  | 'bridge'\n  | 'perf'\n  | 'command-ack'\n  | 'command-rejected';\n\nexport interface DebugEventBase {\n  v: typeof SCHEMA_VERSION;\n  sid: string;\n  seq: number;\n  ts: number;\n  type: EventType;\n  level: EventLevel;\n  meta?: EventMeta;\n}\n\nexport interface EventMeta {\n  route?: string;\n  build?: string;\n  appVersion?: string;\n  deviceId?: string;\n  userIdHash?: string;\n  /** Set on command-ack / command-rejected events to correlate with the originating CommandRequest. */\n  commandId?: string;\n  /**\n   * Set ONLY on synthesized rollup events emitted by the SDK's deduper.\n   * Carries the count of suppressed identical events in the just-closed\n   * window. Original (non-suppressed) events do NOT carry this field.\n   */\n  dedup?: {\n    /** Stable signature used to bucket the suppressed events. */\n    signature: string;\n    /** Number of suppressed occurrences (excludes the leading event that was already emitted). */\n    count: number;\n    /** Timestamp of the first occurrence in the window. */\n    firstTs: number;\n    /** Timestamp of the last occurrence in the window. */\n    lastTs: number;\n  };\n}\n\nexport type SerializedValue =\n  | { k: 'primitive'; v: string | number | boolean | null }\n  | { k: 'undefined' }\n  | { k: 'string'; v: string; truncated?: boolean }\n  | { k: 'json'; v: string; truncated?: boolean }\n  | { k: 'error'; name: string; message: string; stack?: string }\n  | { k: 'circular' }\n  | { k: 'function'; name?: string }\n  | { k: 'unserializable'; reason: string };\n\nexport interface ConsolePayload {\n  method: 'log' | 'info' | 'warn' | 'error' | 'debug';\n  args: SerializedValue[];\n}\n\nexport type NetworkPhase = 'request' | 'response' | 'error';\n\nexport interface NetworkPayload {\n  phase: NetworkPhase;\n  reqId: string;\n  method: string;\n  url: string;\n  status?: number;\n  /** HTTP status text (e.g., \"OK\", \"Not Found\"). Lets the admin show \"200 OK\". */\n  statusText?: string;\n  durationMs?: number;\n  reqHeaders?: Record<string, string>;\n  reqBody?: string;\n  reqBodyTruncated?: boolean;\n  resHeaders?: Record<string, string>;\n  resBody?: string;\n  resBodyTruncated?: boolean;\n  errorMessage?: string;\n  errorName?: string;\n  /** Stack trace for the failing call. Captured at the failure site so\n   *  operators can locate the originating code path. For fetch this is\n   *  `err.stack` from the rejected promise; for XHR (which doesn't carry\n   *  an Error object on `error`/`timeout`/`abort`) we synthesise a stack\n   *  from the call site of `xhr.send()`. */\n  errorStack?: string;\n  /** Flattened cause chain (`err.cause.cause...`) — undici-style fetch\n   *  failures frequently wrap the useful reason here (e.g. `ECONNREFUSED`\n   *  inside a generic `TypeError: fetch failed`). One line per cause. */\n  errorCause?: string;\n}\n\nexport type ErrorSource = 'window.error' | 'unhandledrejection' | 'manual';\n\nexport interface ErrorPayload {\n  message: string;\n  name?: string;\n  stack?: string;\n  source: ErrorSource;\n  filename?: string;\n  lineno?: number;\n  colno?: number;\n}\n\nexport type LifecycleEvent =\n  | 'launch'\n  | 'pageShow'\n  | 'pageHide'\n  | 'route'\n  | 'background'\n  | 'foreground'\n  | 'visibilityChange';\n\nexport interface LifecyclePayload {\n  event: LifecycleEvent;\n  data?: Record<string, unknown>;\n}\n\nexport interface BridgePayload {\n  fn: string;\n  argsPreview?: string;\n  result?: 'ok' | 'error';\n  durationMs?: number;\n  errorMessage?: string;\n}\n\nexport interface PerfPayload {\n  metric: string;\n  value: number;\n  unit?: string;\n}\n\n/** Payload for command-ack: the handler ran, here's its result. */\nexport interface CommandAckPayload {\n  command: string;\n  ok: boolean;\n  /** Handler return value, JSON-serializable. */\n  result?: unknown;\n  durationMs?: number;\n}\n\n/** Payload for command-rejected: relay sent a command we won't run. */\nexport interface CommandRejectedPayload {\n  command: string;\n  reason:\n    | 'unknown-command'\n    | 'rate-limited'\n    | 'invalid-args'\n    | 'handler-threw'\n    | 'overridden';\n  details?: string;\n}\n\nexport type DebugEvent =\n  | (DebugEventBase & { type: 'console';           payload: ConsolePayload })\n  | (DebugEventBase & { type: 'network';           payload: NetworkPayload })\n  | (DebugEventBase & { type: 'error';             payload: ErrorPayload })\n  | (DebugEventBase & { type: 'lifecycle';         payload: LifecyclePayload })\n  | (DebugEventBase & { type: 'bridge';            payload: BridgePayload })\n  | (DebugEventBase & { type: 'perf';              payload: PerfPayload })\n  | (DebugEventBase & { type: 'command-ack';       payload: CommandAckPayload })\n  | (DebugEventBase & { type: 'command-rejected';  payload: CommandRejectedPayload });\n\nexport interface UploadBatch {\n  sessionToken: string;\n  events: DebugEvent[];\n}\n\nexport interface UploadAck {\n  acceptedSeq: number;\n  rejected?: Array<{ seq: number; reason: string }>;\n}\n\nexport type StreamFrame =\n  | { kind: 'hello'; sid: string; devices: number }\n  | { kind: 'event'; event: DebugEvent }\n  | { kind: 'device-join'; deviceInfo: DeviceInfo }\n  | { kind: 'device-leave'; deviceId: string }\n  | { kind: 'gap'; deviceId: string; expectedSeq: number; gotSeq: number }\n  | { kind: 'session-end'; reason: string };\n\nexport interface DeviceInfo {\n  deviceId: string;\n  platform: 'ios' | 'android' | 'web' | 'unknown';\n  osVersion?: string;\n  appName?: string;\n  appVersion?: string;\n  appBuild?: string;\n  userAgent?: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Build-time identity (resolved by the Vite plugin from `botim.{env}.json`)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport type BotimEnv = 'dev' | 'uat' | 'beta' | 'prod';\n\n/**\n * The contents of `botim.{env}.json`, resolved at build time and injected\n * into the bundle via the virtual module `virtual:botim/config`.\n */\nexport interface BotimConfig {\n  miniProgramId: string;\n  env: BotimEnv;\n  /** Short hash of the resolved config or the build, set by the plugin. */\n  buildSignature: string;\n  appName?: string;\n  appVersion?: string;\n  /** Forward-compatible bag for fields the relay may add later. */\n  [extra: string]: unknown;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Consent\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface ConsentInput {\n  /** JWT issued by the BOTIM host runtime — strongest form. */\n  hostToken?: string;\n  /** Explicit user opt-in (e.g., set after a privacy dialog). */\n  userOptIn?: boolean;\n  /**\n   * If true, the SDK shows an in-app consent modal on first load and\n   * persists the user's choice in `localStorage` (key\n   * `__botim_debug_consent_<mpId>`). On subsequent loads the cached\n   * decision is honored without re-prompting. The modal sets\n   * `userOptIn: true` if the user accepts, or short-circuits attach if\n   * they decline. Mutually orthogonal to `hostToken`/`userOptIn`: those\n   * still take effect if explicitly set.\n   *\n   * No-op when `document` / `window` are unavailable (non-DOM runtimes).\n   */\n  promptUser?: boolean;\n  /**\n   * Optional copy override for the consent modal. Keys map to the\n   * default English strings; provide any subset to localize.\n   */\n  promptCopy?: ConsentPromptCopy;\n}\n\nexport interface ConsentPromptCopy {\n  /** Short headline. Default: \"Enable BOTIM debug logging?\" */\n  title?: string;\n  /**\n   * Body paragraphs (rendered as separate <p> elements). Default\n   * explains what data is collected and that the user can revoke.\n   */\n  body?: string[];\n  /** Default: \"Allow\" */\n  acceptLabel?: string;\n  /** Default: \"Skip\" */\n  declineLabel?: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Wire protocol — attach\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface AttachRequest {\n  miniProgramId: string;\n  env: BotimEnv;\n  buildSignature: string;\n  deviceInfo: DeviceInfo;\n  consent: ConsentInput;\n  schemaVersion: typeof SCHEMA_VERSION;\n}\n\nexport interface AttachResponse {\n  sid: string;\n  deviceToken: string;\n  expiresAt: number;\n  ingestUrl: string;\n  /** Endpoint the device long-polls for AI-issued commands. */\n  commandPollUrl: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Wire protocol — commands (relay → device → ack)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface CommandRequest {\n  /** Relay-issued unique id, echoed in the resulting ack/rejected event. */\n  id: string;\n  /** Registered command name (kebab-case). */\n  name: string;\n  /** Arbitrary JSON args, validated by the handler. */\n  args?: Record<string, unknown>;\n  /** Optional deadline; handlers SHOULD respect it. */\n  deadlineTs?: number;\n}\n\n/** Long-poll response shape from `commandPollUrl`. */\nexport interface CommandPollResponse {\n  commands: CommandRequest[];\n  /** Suggested seconds until the next poll. */\n  nextDelayMs?: number;\n}\n\nexport type CommandHandler = (\n  args: Record<string, unknown>,\n  ctx: CommandContext,\n) => unknown | Promise<unknown>;\n\nexport interface CommandContext {\n  commandId: string;\n  command: string;\n  signal: AbortSignal;\n}\n"]}
+{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";AAAO,IAAM,cAAA,GAAiB","file":"types.js","sourcesContent":["export const SCHEMA_VERSION = 2 as const;\n\nexport type EventLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';\n\nexport type EventType =\n  | 'console'\n  | 'network'\n  | 'error'\n  | 'lifecycle'\n  | 'bridge'\n  | 'perf'\n  | 'command-ack'\n  | 'command-rejected';\n\nexport interface DebugEventBase {\n  v: typeof SCHEMA_VERSION;\n  sid: string;\n  seq: number;\n  ts: number;\n  type: EventType;\n  level: EventLevel;\n  meta?: EventMeta;\n}\n\nexport interface EventMeta {\n  route?: string;\n  build?: string;\n  appVersion?: string;\n  deviceId?: string;\n  userIdHash?: string;\n  /** Set on command-ack / command-rejected events to correlate with the originating CommandRequest. */\n  commandId?: string;\n  /**\n   * Set ONLY on synthesized rollup events emitted by the SDK's deduper.\n   * Carries the count of suppressed identical events in the just-closed\n   * window. Original (non-suppressed) events do NOT carry this field.\n   */\n  dedup?: {\n    /** Stable signature used to bucket the suppressed events. */\n    signature: string;\n    /** Number of suppressed occurrences (excludes the leading event that was already emitted). */\n    count: number;\n    /** Timestamp of the first occurrence in the window. */\n    firstTs: number;\n    /** Timestamp of the last occurrence in the window. */\n    lastTs: number;\n  };\n}\n\nexport type SerializedValue =\n  | { k: 'primitive'; v: string | number | boolean | null }\n  | { k: 'undefined' }\n  | { k: 'string'; v: string; truncated?: boolean }\n  | { k: 'json'; v: string; truncated?: boolean }\n  | { k: 'error'; name: string; message: string; stack?: string }\n  | { k: 'circular' }\n  | { k: 'function'; name?: string }\n  | { k: 'unserializable'; reason: string };\n\nexport interface ConsolePayload {\n  method: 'log' | 'info' | 'warn' | 'error' | 'debug';\n  args: SerializedValue[];\n}\n\nexport type NetworkPhase = 'request' | 'response' | 'error';\n\nexport interface NetworkPayload {\n  phase: NetworkPhase;\n  reqId: string;\n  method: string;\n  url: string;\n  status?: number;\n  /** HTTP status text (e.g., \"OK\", \"Not Found\"). Lets the admin show \"200 OK\". */\n  statusText?: string;\n  durationMs?: number;\n  reqHeaders?: Record<string, string>;\n  reqBody?: string;\n  reqBodyTruncated?: boolean;\n  resHeaders?: Record<string, string>;\n  resBody?: string;\n  resBodyTruncated?: boolean;\n  errorMessage?: string;\n  errorName?: string;\n  /** Stack trace for the failing call. Captured at the failure site so\n   *  operators can locate the originating code path. For fetch this is\n   *  `err.stack` from the rejected promise; for XHR (which doesn't carry\n   *  an Error object on `error`/`timeout`/`abort`) we synthesise a stack\n   *  from the call site of `xhr.send()`. */\n  errorStack?: string;\n  /** Flattened cause chain (`err.cause.cause...`) — undici-style fetch\n   *  failures frequently wrap the useful reason here (e.g. `ECONNREFUSED`\n   *  inside a generic `TypeError: fetch failed`). One line per cause. */\n  errorCause?: string;\n}\n\nexport type ErrorSource = 'window.error' | 'unhandledrejection' | 'manual';\n\nexport interface ErrorPayload {\n  message: string;\n  name?: string;\n  stack?: string;\n  source: ErrorSource;\n  filename?: string;\n  lineno?: number;\n  colno?: number;\n}\n\nexport type LifecycleEvent =\n  | 'launch'\n  | 'pageShow'\n  | 'pageHide'\n  | 'route'\n  | 'background'\n  | 'foreground'\n  | 'visibilityChange';\n\nexport interface LifecyclePayload {\n  event: LifecycleEvent;\n  data?: Record<string, unknown>;\n}\n\nexport interface BridgePayload {\n  fn: string;\n  argsPreview?: string;\n  result?: 'ok' | 'error';\n  durationMs?: number;\n  errorMessage?: string;\n}\n\nexport interface PerfPayload {\n  metric: string;\n  value: number;\n  unit?: string;\n}\n\n/** Payload for command-ack: the handler ran, here's its result. */\nexport interface CommandAckPayload {\n  command: string;\n  ok: boolean;\n  /** Handler return value, JSON-serializable. */\n  result?: unknown;\n  durationMs?: number;\n}\n\n/** Payload for command-rejected: relay sent a command we won't run. */\nexport interface CommandRejectedPayload {\n  command: string;\n  reason:\n    | 'unknown-command'\n    | 'rate-limited'\n    | 'invalid-args'\n    | 'handler-threw'\n    | 'overridden';\n  details?: string;\n}\n\nexport type DebugEvent =\n  | (DebugEventBase & { type: 'console';           payload: ConsolePayload })\n  | (DebugEventBase & { type: 'network';           payload: NetworkPayload })\n  | (DebugEventBase & { type: 'error';             payload: ErrorPayload })\n  | (DebugEventBase & { type: 'lifecycle';         payload: LifecyclePayload })\n  | (DebugEventBase & { type: 'bridge';            payload: BridgePayload })\n  | (DebugEventBase & { type: 'perf';              payload: PerfPayload })\n  | (DebugEventBase & { type: 'command-ack';       payload: CommandAckPayload })\n  | (DebugEventBase & { type: 'command-rejected';  payload: CommandRejectedPayload });\n\nexport interface UploadBatch {\n  sessionToken: string;\n  events: DebugEvent[];\n}\n\nexport interface UploadAck {\n  acceptedSeq: number;\n  rejected?: Array<{ seq: number; reason: string }>;\n}\n\nexport type StreamFrame =\n  | { kind: 'hello'; sid: string; devices: number }\n  | { kind: 'event'; event: DebugEvent }\n  | { kind: 'device-join'; deviceInfo: DeviceInfo }\n  | { kind: 'device-leave'; deviceId: string }\n  | { kind: 'gap'; deviceId: string; expectedSeq: number; gotSeq: number }\n  | { kind: 'session-end'; reason: string };\n\nexport interface DeviceInfo {\n  deviceId: string;\n  platform: 'ios' | 'android' | 'web' | 'unknown';\n  osVersion?: string;\n  appName?: string;\n  appVersion?: string;\n  appBuild?: string;\n  userAgent?: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Build-time identity (resolved by the Vite plugin from `botim.{env}.json`)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport type BotimEnv = 'dev' | 'uat' | 'beta' | 'prod';\n\n/**\n * The contents of `botim.{env}.json`, resolved at build time and injected\n * into the bundle via the virtual module `virtual:botim/config`.\n */\nexport interface BotimConfig {\n  miniProgramId: string;\n  env: BotimEnv;\n  /** Short hash of the resolved config or the build, set by the plugin. */\n  buildSignature: string;\n  appName?: string;\n  appVersion?: string;\n  /** Forward-compatible bag for fields the relay may add later. */\n  [extra: string]: unknown;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Consent\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface ConsentInput {\n  /** JWT issued by the BOTIM host runtime — strongest form. */\n  hostToken?: string;\n  /** Explicit user opt-in (e.g., set after a privacy dialog). */\n  userOptIn?: boolean;\n  /**\n   * Controls whether the SDK shows its built-in consent modal.\n   *\n   * Default behavior (as of 0.7.1) is to **show the modal automatically**\n   * whenever:\n   *   • the host did NOT provide `userOptIn: true` or a `hostToken`, AND\n   *   • a DOM is available (`document` and `window` exist).\n   *\n   * The user's decision is persisted in `localStorage` under the key\n   * `__botim_debug_consent_<mpId>` so subsequent loads attach silently\n   * (or stay disabled, if declined) without re-prompting.\n   *\n   * Set to `false` to suppress the modal — useful for automated test\n   * harnesses, hosts that wire their own consent UX upstream, or any\n   * environment where a blocking dialog is undesirable. When suppressed,\n   * `assertConsent` runs as before: it requires `userOptIn` or\n   * `hostToken` in `prod`, and is a no-op in non-prod envs.\n   *\n   * Set to `true` for symmetry / explicitness — same effect as the\n   * default when no other consent signal is present.\n   *\n   * Has no effect in non-DOM runtimes (native bridges, SSR) since the\n   * modal can't be rendered there. Provide `userOptIn`/`hostToken` for\n   * those.\n   */\n  promptUser?: boolean;\n  /**\n   * Optional copy override for the consent modal. Keys map to the\n   * default English strings; provide any subset to localize.\n   */\n  promptCopy?: ConsentPromptCopy;\n}\n\nexport interface ConsentPromptCopy {\n  /** Short headline. Default: \"Enable BOTIM debug logging?\" */\n  title?: string;\n  /**\n   * Body paragraphs (rendered as separate <p> elements). Default\n   * explains what data is collected and that the user can revoke.\n   */\n  body?: string[];\n  /** Default: \"Allow\" */\n  acceptLabel?: string;\n  /** Default: \"Skip\" */\n  declineLabel?: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Wire protocol — attach\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface AttachRequest {\n  miniProgramId: string;\n  env: BotimEnv;\n  buildSignature: string;\n  deviceInfo: DeviceInfo;\n  consent: ConsentInput;\n  schemaVersion: typeof SCHEMA_VERSION;\n}\n\nexport interface AttachResponse {\n  sid: string;\n  deviceToken: string;\n  expiresAt: number;\n  ingestUrl: string;\n  /** Endpoint the device long-polls for AI-issued commands. */\n  commandPollUrl: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Wire protocol — commands (relay → device → ack)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface CommandRequest {\n  /** Relay-issued unique id, echoed in the resulting ack/rejected event. */\n  id: string;\n  /** Registered command name (kebab-case). */\n  name: string;\n  /** Arbitrary JSON args, validated by the handler. */\n  args?: Record<string, unknown>;\n  /** Optional deadline; handlers SHOULD respect it. */\n  deadlineTs?: number;\n}\n\n/** Long-poll response shape from `commandPollUrl`. */\nexport interface CommandPollResponse {\n  commands: CommandRequest[];\n  /** Suggested seconds until the next poll. */\n  nextDelayMs?: number;\n}\n\nexport type CommandHandler = (\n  args: Record<string, unknown>,\n  ctx: CommandContext,\n) => unknown | Promise<unknown>;\n\nexport interface CommandContext {\n  commandId: string;\n  command: string;\n  signal: AbortSignal;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botim/mp-debug-sdk",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Remote-debug SDK for BOTIM mini-programs — streams console, network, and error events to a BOTIM debug-relay for live inspection, with an AI-observable command channel.",
   "type": "module",
   "main": "./dist/index.cjs",