@botim/mp-debug-sdk 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,253 @@
+declare const SCHEMA_VERSION: 2;
+type EventLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+type EventType = 'console' | 'network' | 'error' | 'lifecycle' | 'bridge' | 'perf' | 'command-ack' | 'command-rejected';
+interface DebugEventBase {
+    v: typeof SCHEMA_VERSION;
+    sid: string;
+    seq: number;
+    ts: number;
+    type: EventType;
+    level: EventLevel;
+    meta?: EventMeta;
+}
+interface EventMeta {
+    route?: string;
+    build?: string;
+    appVersion?: string;
+    deviceId?: string;
+    userIdHash?: string;
+    /** Set on command-ack / command-rejected events to correlate with the originating CommandRequest. */
+    commandId?: string;
+    /**
+     * Set ONLY on synthesized rollup events emitted by the SDK's deduper.
+     * Carries the count of suppressed identical events in the just-closed
+     * window. Original (non-suppressed) events do NOT carry this field.
+     */
+    dedup?: {
+        /** Stable signature used to bucket the suppressed events. */
+        signature: string;
+        /** Number of suppressed occurrences (excludes the leading event that was already emitted). */
+        count: number;
+        /** Timestamp of the first occurrence in the window. */
+        firstTs: number;
+        /** Timestamp of the last occurrence in the window. */
+        lastTs: number;
+    };
+}
+type SerializedValue = {
+    k: 'primitive';
+    v: string | number | boolean | null;
+} | {
+    k: 'undefined';
+} | {
+    k: 'string';
+    v: string;
+    truncated?: boolean;
+} | {
+    k: 'json';
+    v: string;
+    truncated?: boolean;
+} | {
+    k: 'error';
+    name: string;
+    message: string;
+    stack?: string;
+} | {
+    k: 'circular';
+} | {
+    k: 'function';
+    name?: string;
+} | {
+    k: 'unserializable';
+    reason: string;
+};
+interface ConsolePayload {
+    method: 'log' | 'info' | 'warn' | 'error' | 'debug';
+    args: SerializedValue[];
+}
+type NetworkPhase = 'request' | 'response' | 'error';
+interface NetworkPayload {
+    phase: NetworkPhase;
+    reqId: string;
+    method: string;
+    url: string;
+    status?: number;
+    durationMs?: number;
+    reqHeaders?: Record<string, string>;
+    reqBody?: string;
+    reqBodyTruncated?: boolean;
+    resHeaders?: Record<string, string>;
+    resBody?: string;
+    resBodyTruncated?: boolean;
+    errorMessage?: string;
+    errorName?: string;
+}
+type ErrorSource = 'window.error' | 'unhandledrejection' | 'manual';
+interface ErrorPayload {
+    message: string;
+    name?: string;
+    stack?: string;
+    source: ErrorSource;
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+}
+type LifecycleEvent = 'launch' | 'pageShow' | 'pageHide' | 'route' | 'background' | 'foreground' | 'visibilityChange';
+interface LifecyclePayload {
+    event: LifecycleEvent;
+    data?: Record<string, unknown>;
+}
+interface BridgePayload {
+    fn: string;
+    argsPreview?: string;
+    result?: 'ok' | 'error';
+    durationMs?: number;
+    errorMessage?: string;
+}
+interface PerfPayload {
+    metric: string;
+    value: number;
+    unit?: string;
+}
+/** Payload for command-ack: the handler ran, here's its result. */
+interface CommandAckPayload {
+    command: string;
+    ok: boolean;
+    /** Handler return value, JSON-serializable. */
+    result?: unknown;
+    durationMs?: number;
+}
+/** Payload for command-rejected: relay sent a command we won't run. */
+interface CommandRejectedPayload {
+    command: string;
+    reason: 'unknown-command' | 'rate-limited' | 'invalid-args' | 'handler-threw' | 'overridden';
+    details?: string;
+}
+type DebugEvent = (DebugEventBase & {
+    type: 'console';
+    payload: ConsolePayload;
+}) | (DebugEventBase & {
+    type: 'network';
+    payload: NetworkPayload;
+}) | (DebugEventBase & {
+    type: 'error';
+    payload: ErrorPayload;
+}) | (DebugEventBase & {
+    type: 'lifecycle';
+    payload: LifecyclePayload;
+}) | (DebugEventBase & {
+    type: 'bridge';
+    payload: BridgePayload;
+}) | (DebugEventBase & {
+    type: 'perf';
+    payload: PerfPayload;
+}) | (DebugEventBase & {
+    type: 'command-ack';
+    payload: CommandAckPayload;
+}) | (DebugEventBase & {
+    type: 'command-rejected';
+    payload: CommandRejectedPayload;
+});
+interface UploadBatch {
+    sessionToken: string;
+    events: DebugEvent[];
+}
+interface UploadAck {
+    acceptedSeq: number;
+    rejected?: Array<{
+        seq: number;
+        reason: string;
+    }>;
+}
+type StreamFrame = {
+    kind: 'hello';
+    sid: string;
+    devices: number;
+} | {
+    kind: 'event';
+    event: DebugEvent;
+} | {
+    kind: 'device-join';
+    deviceInfo: DeviceInfo;
+} | {
+    kind: 'device-leave';
+    deviceId: string;
+} | {
+    kind: 'gap';
+    deviceId: string;
+    expectedSeq: number;
+    gotSeq: number;
+} | {
+    kind: 'session-end';
+    reason: string;
+};
+interface DeviceInfo {
+    deviceId: string;
+    platform: 'ios' | 'android' | 'web' | 'unknown';
+    osVersion?: string;
+    appName?: string;
+    appVersion?: string;
+    appBuild?: string;
+    userAgent?: string;
+}
+type BotimEnv = 'dev' | 'uat' | 'beta' | 'prod';
+/**
+ * The contents of `botim.{env}.json`, resolved at build time and injected
+ * into the bundle via the virtual module `virtual:botim/config`.
+ */
+interface BotimConfig {
+    miniProgramId: string;
+    env: BotimEnv;
+    /** Short hash of the resolved config or the build, set by the plugin. */
+    buildSignature: string;
+    appName?: string;
+    appVersion?: string;
+    /** Forward-compatible bag for fields the relay may add later. */
+    [extra: string]: unknown;
+}
+interface ConsentInput {
+    /** JWT issued by the BOTIM host runtime — strongest form. */
+    hostToken?: string;
+    /** Explicit user opt-in (e.g., set after a privacy dialog). */
+    userOptIn?: boolean;
+}
+interface AttachRequest {
+    miniProgramId: string;
+    env: BotimEnv;
+    buildSignature: string;
+    deviceInfo: DeviceInfo;
+    consent: ConsentInput;
+    schemaVersion: typeof SCHEMA_VERSION;
+}
+interface AttachResponse {
+    sid: string;
+    deviceToken: string;
+    expiresAt: number;
+    ingestUrl: string;
+    /** Endpoint the device long-polls for AI-issued commands. */
+    commandPollUrl: string;
+}
+interface CommandRequest {
+    /** Relay-issued unique id, echoed in the resulting ack/rejected event. */
+    id: string;
+    /** Registered command name (kebab-case). */
+    name: string;
+    /** Arbitrary JSON args, validated by the handler. */
+    args?: Record<string, unknown>;
+    /** Optional deadline; handlers SHOULD respect it. */
+    deadlineTs?: number;
+}
+/** Long-poll response shape from `commandPollUrl`. */
+interface CommandPollResponse {
+    commands: CommandRequest[];
+    /** Suggested seconds until the next poll. */
+    nextDelayMs?: number;
+}
+type CommandHandler = (args: Record<string, unknown>, ctx: CommandContext) => unknown | Promise<unknown>;
+interface CommandContext {
+    commandId: string;
+    command: string;
+    signal: AbortSignal;
+}
+
+export { type AttachRequest, type AttachResponse, type BotimConfig, type BotimEnv, type BridgePayload, type CommandAckPayload, type CommandContext, type CommandHandler, type CommandPollResponse, type CommandRejectedPayload, type CommandRequest, type ConsentInput, type ConsolePayload, type DebugEvent, type DebugEventBase, type DeviceInfo, type ErrorPayload, type ErrorSource, type EventLevel, type EventMeta, type EventType, type LifecycleEvent, type LifecyclePayload, type NetworkPayload, type NetworkPhase, type PerfPayload, SCHEMA_VERSION, type SerializedValue, type StreamFrame, type UploadAck, type UploadBatch };

package/dist/types.js

@@ -0,0 +1,6 @@
+// src/types.ts
+var SCHEMA_VERSION = 2;
+
+export { SCHEMA_VERSION };
+//# sourceMappingURL=types.js.map
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +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  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}\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\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/vite/plugin.cjs

@@ -0,0 +1,178 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/vite/plugin.ts
+var plugin_exports = {};
+__export(plugin_exports, {
+  BotimConfigError: () => BotimConfigError,
+  botimDebug: () => botimDebug,
+  resolveBotimConfig: () => resolveBotimConfig
+});
+module.exports = __toCommonJS(plugin_exports);
+
+// src/vite/resolve-config.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_node_crypto = require("crypto");
+
+// src/errors.ts
+var BRAND = "@botim/debug-sdk";
+var BotimConfigError = class extends Error {
+  constructor(message, opts = { code: "invalid-config" }) {
+    super(`[${BRAND}] ${message}`);
+    this.name = "BotimConfigError";
+    this.code = opts.code;
+    this.path = opts.path;
+  }
+};
+
+// src/vite/resolve-config.ts
+var VALID_ENVS = ["dev", "uat", "beta", "prod"];
+var ID_PATTERN = /^[a-z][a-z0-9_-]{1,63}$/i;
+function defaultMapMode(mode) {
+  if (mode === "development") return "dev";
+  if (mode === "production") return "prod";
+  return mode;
+}
+function isBotimEnv(s) {
+  return VALID_ENVS.includes(s);
+}
+function resolveBotimConfig(mode, root, opts = {}) {
+  if (!mode) {
+    throw new BotimConfigError("mode is required", { code: "no-mode" });
+  }
+  const mapped = (opts.mapMode ?? defaultMapMode)(mode);
+  if (typeof mapped !== "string" || !isBotimEnv(mapped)) {
+    throw new BotimConfigError(
+      `mode "${mode}" mapped to "${mapped}" which is not a valid BotimEnv (expected one of: ${VALID_ENVS.join(", ")})`,
+      { code: "invalid-env" }
+    );
+  }
+  const env = mapped;
+  const projectRoot = (0, import_node_path.isAbsolute)(root) ? root : (0, import_node_path.resolve)(process.cwd(), root);
+  const filePath = (0, import_node_path.resolve)(projectRoot, `botim.${env}.json`);
+  if (!(0, import_node_fs.existsSync)(filePath)) {
+    throw new BotimConfigError(
+      `expected config file not found: ${filePath}
+       Create botim.${env}.json at the project root with at least { "mp_id": "..." }.`,
+      { code: "config-missing", path: filePath }
+    );
+  }
+  const raw = (0, import_node_fs.readFileSync)(filePath, "utf8");
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new BotimConfigError(`failed to parse JSON in ${filePath}: ${detail}`, {
+      code: "config-invalid-json",
+      path: filePath
+    });
+  }
+  if (parsed.deleted === 1) {
+    throw new BotimConfigError(
+      `${filePath} reports the mini-program as deleted (deleted: 1). Cannot ship debug SDK against a retired mini-program.`,
+      { code: "config-deleted", path: filePath }
+    );
+  }
+  const idValue = parsed.mp_id ?? parsed.miniProgramId;
+  if (typeof idValue !== "string" || idValue.length === 0) {
+    throw new BotimConfigError(
+      `${filePath} is missing required field "mp_id" (must be a non-empty string)`,
+      { code: "config-missing-field", path: filePath }
+    );
+  }
+  if (!ID_PATTERN.test(idValue)) {
+    throw new BotimConfigError(
+      `${filePath} field "mp_id" must match ${ID_PATTERN.toString()} (got: ${JSON.stringify(idValue)})`,
+      { code: "config-invalid-id", path: filePath }
+    );
+  }
+  const md5 = typeof parsed.app?.md5 === "string" ? parsed.app.md5 : typeof parsed.package_url?.md5 === "string" ? parsed.package_url.md5 : void 0;
+  const versionForSig = typeof parsed.version === "string" && parsed.version || typeof parsed.app?.version === "string" && parsed.app.version || void 0;
+  let buildSignature;
+  if (typeof parsed.buildSignature === "string" && parsed.buildSignature.length > 0) {
+    buildSignature = parsed.buildSignature;
+  } else if (versionForSig && md5) {
+    buildSignature = `v${versionForSig}+md5:${md5.slice(0, 12)}`;
+  } else {
+    buildSignature = "sha256:" + (0, import_node_crypto.createHash)("sha256").update(raw).digest("hex").slice(0, 12);
+  }
+  const cfg = {
+    // Spread first so the canonical fields below override anything inherited.
+    ...parsed,
+    miniProgramId: idValue,
+    env,
+    buildSignature,
+    appName: typeof parsed.app_id === "string" ? parsed.app_id : parsed.appName,
+    appVersion: versionForSig ?? (typeof parsed.appVersion === "string" ? parsed.appVersion : void 0)
+  };
+  return cfg;
+}
+
+// src/vite/plugin.ts
+var VIRTUAL_ID = "virtual:botim/config";
+var RESOLVED_VIRTUAL_ID = "\0" + VIRTUAL_ID;
+function botimDebug(options = {}) {
+  let resolved = null;
+  let resolvedFromMode = null;
+  let resolvedError = null;
+  return {
+    name: "@botim/debug-sdk:vite",
+    enforce: "pre",
+    configResolved(viteConfig) {
+      const mode = options.mode ?? viteConfig.mode;
+      const root = options.root ?? viteConfig.root;
+      try {
+        resolved = resolveBotimConfig(mode, root, { mapMode: options.mapMode });
+        if (options.relayUrl) {
+          resolved.relayUrl = options.relayUrl.replace(/\/+$/, "");
+        }
+        resolvedFromMode = mode;
+      } catch (err) {
+        resolved = null;
+        resolvedError = err instanceof Error ? err : new Error(String(err));
+        resolvedFromMode = mode;
+      }
+    },
+    resolveId(id) {
+      if (id === VIRTUAL_ID) return RESOLVED_VIRTUAL_ID;
+      return null;
+    },
+    load(id) {
+      if (id !== RESOLVED_VIRTUAL_ID) return null;
+      if (!resolved) {
+        const message = resolvedError?.message ?? `[@botim/debug-sdk] virtual:botim/config requested but configResolved did not run (mode=${resolvedFromMode ?? "unknown"})`;
+        this.error(message);
+      }
+      const body = `// AUTO-GENERATED by @botim/debug-sdk:vite \u2014 do not edit.
+export const botimConfig = Object.freeze(${JSON.stringify(resolved)});
+export default botimConfig;
+`;
+      return { code: body, map: null };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BotimConfigError,
+  botimDebug,
+  resolveBotimConfig
+});
+//# sourceMappingURL=plugin.cjs.map

package/dist/vite/plugin.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/vite/plugin.ts","../../src/vite/resolve-config.ts","../../src/errors.ts"],"sourcesContent":["/**\n * Vite plugin for `@botim/debug-sdk`.\n *\n * - Reads `botim.{mode}.json` from the consumer's project root at build time.\n * - Validates required fields; fails the build loudly if anything is wrong.\n * - Exposes the resolved config via the virtual module `virtual:botim/config`\n *   as `export const botimConfig: Readonly<BotimConfig>`.\n *\n * The plugin's only Vite-specific surface is the `Plugin` type; we keep the\n * import as `type-only` so `vite` remains an *optional* peer dependency. A\n * consumer that never installs Vite will never load this file (it's only\n * reachable via the `./vite` subpath export).\n */\n\nimport type { Plugin } from 'vite';\nimport { resolveBotimConfig } from './resolve-config.js';\nimport type { BotimConfig, BotimEnv } from '../types.js';\n\nconst VIRTUAL_ID = 'virtual:botim/config';\nconst RESOLVED_VIRTUAL_ID = '\\0' + VIRTUAL_ID;\n\nexport interface BotimDebugPluginOptions {\n  /**\n   * Override Vite's `mode`. Useful when the build is driven outside Vite's\n   * usual `--mode` flag, or in tests. If omitted, the plugin uses the mode\n   * Vite resolves from the CLI / config.\n   */\n  mode?: string;\n  /**\n   * Map Vite's mode to a BotimEnv. Defaults: `development` → `dev`,\n   * `production` → `prod`, others pass through verbatim.\n   */\n  mapMode?: (mode: string) => BotimEnv | string;\n  /**\n   * Project root override. Defaults to Vite's resolved `config.root`.\n   */\n  root?: string;\n  /**\n   * Relay endpoint to bake into `virtual:botim/config` as `relayUrl`. The\n   * SDK reads this at runtime so the host app can call:\n   *\n   *   enableRemoteDebug({ endpoint: botimConfig.relayUrl, … })\n   *\n   * Without this option, hosts must either set up a Vite proxy\n   * (`server.proxy: { '/v1': 'http://localhost:8090' }`) and pass\n   * `endpoint: location.origin`, OR pass an explicit URL at the call\n   * site. Passing it through the plugin centralises the wiring and makes\n   * mode-specific URLs trivial: read process.env.RELAY_URL in\n   * vite.config and forward it here.\n   *\n   * The relay must allow the page's origin via CORS (CORS_ORIGINS env on\n   * @botim/debug-relay defaults to \"*\"). Trailing slash is stripped at\n   * resolve time so `/v1/attach` joins cleanly.\n   */\n  relayUrl?: string;\n}\n\nexport function botimDebug(options: BotimDebugPluginOptions = {}): Plugin {\n  let resolved: BotimConfig | null = null;\n  let resolvedFromMode: string | null = null;\n  let resolvedError: Error | null = null;\n\n  return {\n    name: '@botim/debug-sdk:vite',\n    enforce: 'pre',\n\n    configResolved(viteConfig) {\n      const mode = options.mode ?? viteConfig.mode;\n      const root = options.root ?? viteConfig.root;\n      try {\n        resolved = resolveBotimConfig(mode, root, { mapMode: options.mapMode });\n        // Merge the host-provided relay URL into the resolved config bag.\n        // Strip trailing slash so callers don't get `/v1//attach` if they\n        // pass `https://relay.example.com/`.\n        if (options.relayUrl) {\n          (resolved as BotimConfig & { relayUrl: string }).relayUrl =\n            options.relayUrl.replace(/\\/+$/, '');\n        }\n        resolvedFromMode = mode;\n      } catch (err) {\n        // Stash the error; surface it the moment a build module imports the\n        // virtual module. We don't throw from `configResolved` directly because\n        // some consumers run Vite for non-build tasks (e.g. `vite-node` for\n        // tooling) where the virtual module is never imported and a hard fail\n        // would be a regression.\n        resolved = null;\n        resolvedError = err instanceof Error ? err : new Error(String(err));\n        resolvedFromMode = mode;\n      }\n    },\n\n    resolveId(id) {\n      if (id === VIRTUAL_ID) return RESOLVED_VIRTUAL_ID;\n      return null;\n    },\n\n    load(id) {\n      if (id !== RESOLVED_VIRTUAL_ID) return null;\n\n      if (!resolved) {\n        const message =\n          resolvedError?.message ??\n          `[@botim/debug-sdk] virtual:botim/config requested but configResolved did not run (mode=${resolvedFromMode ?? 'unknown'})`;\n        // `this.error` aborts the build with a properly attributed Vite error.\n        this.error(message);\n      }\n\n      // Frozen so a runtime mutation can't accidentally taint the constant.\n      const body =\n        `// AUTO-GENERATED by @botim/debug-sdk:vite — do not edit.\\n` +\n        `export const botimConfig = Object.freeze(${JSON.stringify(resolved)});\\n` +\n        `export default botimConfig;\\n`;\n      return { code: body, map: null };\n    },\n  };\n}\n\nexport { resolveBotimConfig } from './resolve-config.js';\nexport { BotimConfigError } from '../errors.js';\nexport type { BotimConfig, BotimEnv } from '../types.js';\n","/**\n * Build-time resolver for `botim.{env}.json`.\n *\n * The real BOTIM config schema is large and platform-managed (logos, package\n * URLs, framework metadata, grayscale rollout, etc). The SDK only needs a few\n * canonical fields, so this resolver acts as a *normalizer*:\n *\n *   external schema        →    SDK-internal `BotimConfig`\n *   ───────────────             ──────────────────────────\n *   mp_id                  →    miniProgramId\n *   app_id                 →    appId         (extra; preserved)\n *   version                →    appVersion\n *   app.md5 | package_url.md5 → buildSignature (deterministic per release)\n *   <env from filename>    →    env\n *\n * Reads `botim.{env}.json` from the consumer's project root. Build-time only:\n * uses Node `fs`/`crypto`. Must NEVER be imported from device-targeted code.\n */\n\nimport { readFileSync, existsSync } from 'node:fs';\nimport { resolve, isAbsolute } from 'node:path';\nimport { createHash } from 'node:crypto';\n\nimport { BotimConfigError } from '../errors.js';\nimport type { BotimConfig, BotimEnv } from '../types.js';\n\nconst VALID_ENVS: readonly BotimEnv[] = ['dev', 'uat', 'beta', 'prod'];\n/**\n * Mini-program ids in the real config are short kebab/snake-case slugs like\n * `mbrx_p2p` — case-insensitive, allows `_` and `-`, must start with a letter.\n */\nconst ID_PATTERN = /^[a-z][a-z0-9_-]{1,63}$/i;\n\nexport interface ResolveOptions {\n  /** Map a Vite mode (e.g. \"development\", \"staging\") to a BotimEnv. */\n  mapMode?: (mode: string) => BotimEnv | string;\n}\n\n/** Built-in mapping; consumers can override via `mapMode`. */\nfunction defaultMapMode(mode: string): string {\n  if (mode === 'development') return 'dev';\n  if (mode === 'production') return 'prod';\n  return mode;\n}\n\nfunction isBotimEnv(s: string): s is BotimEnv {\n  return (VALID_ENVS as readonly string[]).includes(s);\n}\n\ninterface RawBotimFile {\n  /** Canonical mini-program id used by the BOTIM platform, e.g. \"mbrx_p2p\". */\n  mp_id?: string;\n  /** Reverse-DNS app id, e.g. \"me.botim.rd.p2p\". Different concept from mp_id. */\n  app_id?: string;\n  /** Release version of the mini-program package, e.g. \"0.0.127\". */\n  version?: string;\n  /** Optional override; otherwise we derive from version+md5. */\n  buildSignature?: string;\n  /** Per-package metadata; when present we use `app.md5` for the signature. */\n  app?: { version?: string; md5?: string; updateUrl?: string };\n  /** Older/alternate location for the same md5. */\n  package_url?: { md5?: string; version?: string };\n  /** Operational flags maintained by the platform. */\n  disabled?: number;\n  deleted?: number;\n  mp_status?: number;\n  /** Forward-compat for everything else (logos, framework, grayscale, ...). */\n  [extra: string]: unknown;\n  /** Legacy alias accepted for forward/back compat. */\n  miniProgramId?: string;\n}\n\n/**\n * Resolve `botim.{env}.json` for the given Vite `mode` from `root`.\n *\n * Throws `BotimConfigError` synchronously on:\n *  - unknown env after `mapMode` is applied\n *  - missing or unreadable file\n *  - invalid JSON\n *  - missing/invalid `mp_id` (or its legacy `miniProgramId` alias)\n *  - the platform marking the mini-program as deleted (`deleted: 1`)\n */\nexport function resolveBotimConfig(\n  mode: string,\n  root: string,\n  opts: ResolveOptions = {},\n): BotimConfig {\n  if (!mode) {\n    throw new BotimConfigError('mode is required', { code: 'no-mode' });\n  }\n\n  const mapped = (opts.mapMode ?? defaultMapMode)(mode);\n  if (typeof mapped !== 'string' || !isBotimEnv(mapped)) {\n    throw new BotimConfigError(\n      `mode \"${mode}\" mapped to \"${mapped}\" which is not a valid BotimEnv (expected one of: ${VALID_ENVS.join(', ')})`,\n      { code: 'invalid-env' },\n    );\n  }\n  const env: BotimEnv = mapped;\n\n  const projectRoot = isAbsolute(root) ? root : resolve(process.cwd(), root);\n  const filePath = resolve(projectRoot, `botim.${env}.json`);\n\n  if (!existsSync(filePath)) {\n    throw new BotimConfigError(\n      `expected config file not found: ${filePath}\\n` +\n        `       Create botim.${env}.json at the project root with at least { \"mp_id\": \"...\" }.`,\n      { code: 'config-missing', path: filePath },\n    );\n  }\n\n  const raw = readFileSync(filePath, 'utf8');\n  let parsed: RawBotimFile;\n  try {\n    parsed = JSON.parse(raw) as RawBotimFile;\n  } catch (err) {\n    const detail = err instanceof Error ? err.message : String(err);\n    throw new BotimConfigError(`failed to parse JSON in ${filePath}: ${detail}`, {\n      code: 'config-invalid-json',\n      path: filePath,\n    });\n  }\n\n  // Hard-stop on a decommissioned mini-program — refusing the build is far\n  // safer than shipping a debug SDK that targets a relay slot the platform\n  // has retired.\n  if (parsed.deleted === 1) {\n    throw new BotimConfigError(\n      `${filePath} reports the mini-program as deleted (deleted: 1). Cannot ship debug SDK against a retired mini-program.`,\n      { code: 'config-deleted', path: filePath },\n    );\n  }\n\n  // Read the canonical id; fall back to the SDK-internal alias for repos that\n  // hand-write a config without the platform's `mp_id` field.\n  const idValue = (parsed.mp_id ?? parsed.miniProgramId) as unknown;\n  if (typeof idValue !== 'string' || idValue.length === 0) {\n    throw new BotimConfigError(\n      `${filePath} is missing required field \"mp_id\" (must be a non-empty string)`,\n      { code: 'config-missing-field', path: filePath },\n    );\n  }\n  if (!ID_PATTERN.test(idValue)) {\n    throw new BotimConfigError(\n      `${filePath} field \"mp_id\" must match ${ID_PATTERN.toString()} (got: ${JSON.stringify(idValue)})`,\n      { code: 'config-invalid-id', path: filePath },\n    );\n  }\n\n  // ── Derive a stable, release-correlated buildSignature ────────────────────\n  // Preference order:\n  //   1. explicit buildSignature in the file (consumers may pin one)\n  //   2. version + package md5 (deterministic per release; survives unrelated\n  //      platform-side mutations like update_time / mp_status_time)\n  //   3. sha256 of the file contents (last-resort fallback)\n  const md5 =\n    typeof parsed.app?.md5 === 'string'\n      ? parsed.app.md5\n      : typeof parsed.package_url?.md5 === 'string'\n        ? parsed.package_url.md5\n        : undefined;\n  const versionForSig =\n    (typeof parsed.version === 'string' && parsed.version) ||\n    (typeof parsed.app?.version === 'string' && parsed.app.version) ||\n    undefined;\n\n  let buildSignature: string;\n  if (typeof parsed.buildSignature === 'string' && parsed.buildSignature.length > 0) {\n    buildSignature = parsed.buildSignature;\n  } else if (versionForSig && md5) {\n    buildSignature = `v${versionForSig}+md5:${md5.slice(0, 12)}`;\n  } else {\n    buildSignature = 'sha256:' + createHash('sha256').update(raw).digest('hex').slice(0, 12);\n  }\n\n  const cfg: BotimConfig = {\n    // Spread first so the canonical fields below override anything inherited.\n    ...parsed,\n    miniProgramId: idValue,\n    env,\n    buildSignature,\n    appName: typeof parsed.app_id === 'string' ? parsed.app_id : (parsed.appName as string | undefined),\n    appVersion:\n      versionForSig ?? (typeof parsed.appVersion === 'string' ? parsed.appVersion : undefined),\n  };\n\n  return cfg;\n}\n\nexport const __test__ = { defaultMapMode, ID_PATTERN, VALID_ENVS };\n","/**\n * Errors that escape the SDK into host code.\n *\n * The SDK's no-throw invariant has exactly two carve-outs:\n *  - `BotimConfigError` — thrown synchronously by `enableRemoteDebug` when the\n *    resolved `BotimConfig` is missing or invalid. Prevents any I/O.\n *  - `BotimConsentError` — thrown synchronously by `enableRemoteDebug` when\n *    consent has not been granted in a `prod` build. Prevents any I/O.\n *\n * Both are intentionally synchronous and pre-installation: at the moment they\n * fire, no globals have been wrapped, no listeners installed, no network sent.\n */\n\nconst BRAND = '@botim/debug-sdk' as const;\n\nexport class BotimConfigError extends Error {\n  readonly name = 'BotimConfigError';\n  readonly code: string;\n  readonly path?: string;\n\n  constructor(message: string, opts: { code: string; path?: string } = { code: 'invalid-config' }) {\n    super(`[${BRAND}] ${message}`);\n    this.code = opts.code;\n    this.path = opts.path;\n  }\n}\n\nexport class BotimConsentError extends Error {\n  readonly name = 'BotimConsentError';\n  constructor(message: string) {\n    super(`[${BRAND}] ${message}`);\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/vite/plugin.d.cts

@@ -0,0 +1,127 @@
+import { Plugin } from 'vite';
+
+type BotimEnv = 'dev' | 'uat' | 'beta' | 'prod';
+/**
+ * The contents of `botim.{env}.json`, resolved at build time and injected
+ * into the bundle via the virtual module `virtual:botim/config`.
+ */
+interface BotimConfig {
+    miniProgramId: string;
+    env: BotimEnv;
+    /** Short hash of the resolved config or the build, set by the plugin. */
+    buildSignature: string;
+    appName?: string;
+    appVersion?: string;
+    /** Forward-compatible bag for fields the relay may add later. */
+    [extra: string]: unknown;
+}
+
+/**
+ * Build-time resolver for `botim.{env}.json`.
+ *
+ * The real BOTIM config schema is large and platform-managed (logos, package
+ * URLs, framework metadata, grayscale rollout, etc). The SDK only needs a few
+ * canonical fields, so this resolver acts as a *normalizer*:
+ *
+ *   external schema        →    SDK-internal `BotimConfig`
+ *   ───────────────             ──────────────────────────
+ *   mp_id                  →    miniProgramId
+ *   app_id                 →    appId         (extra; preserved)
+ *   version                →    appVersion
+ *   app.md5 | package_url.md5 → buildSignature (deterministic per release)
+ *   <env from filename>    →    env
+ *
+ * Reads `botim.{env}.json` from the consumer's project root. Build-time only:
+ * uses Node `fs`/`crypto`. Must NEVER be imported from device-targeted code.
+ */
+
+interface ResolveOptions {
+    /** Map a Vite mode (e.g. "development", "staging") to a BotimEnv. */
+    mapMode?: (mode: string) => BotimEnv | string;
+}
+/**
+ * Resolve `botim.{env}.json` for the given Vite `mode` from `root`.
+ *
+ * Throws `BotimConfigError` synchronously on:
+ *  - unknown env after `mapMode` is applied
+ *  - missing or unreadable file
+ *  - invalid JSON
+ *  - missing/invalid `mp_id` (or its legacy `miniProgramId` alias)
+ *  - the platform marking the mini-program as deleted (`deleted: 1`)
+ */
+declare function resolveBotimConfig(mode: string, root: string, opts?: ResolveOptions): BotimConfig;
+
+/**
+ * Errors that escape the SDK into host code.
+ *
+ * The SDK's no-throw invariant has exactly two carve-outs:
+ *  - `BotimConfigError` — thrown synchronously by `enableRemoteDebug` when the
+ *    resolved `BotimConfig` is missing or invalid. Prevents any I/O.
+ *  - `BotimConsentError` — thrown synchronously by `enableRemoteDebug` when
+ *    consent has not been granted in a `prod` build. Prevents any I/O.
+ *
+ * Both are intentionally synchronous and pre-installation: at the moment they
+ * fire, no globals have been wrapped, no listeners installed, no network sent.
+ */
+declare class BotimConfigError extends Error {
+    readonly name = "BotimConfigError";
+    readonly code: string;
+    readonly path?: string;
+    constructor(message: string, opts?: {
+        code: string;
+        path?: string;
+    });
+}
+
+/**
+ * Vite plugin for `@botim/debug-sdk`.
+ *
+ * - Reads `botim.{mode}.json` from the consumer's project root at build time.
+ * - Validates required fields; fails the build loudly if anything is wrong.
+ * - Exposes the resolved config via the virtual module `virtual:botim/config`
+ *   as `export const botimConfig: Readonly<BotimConfig>`.
+ *
+ * The plugin's only Vite-specific surface is the `Plugin` type; we keep the
+ * import as `type-only` so `vite` remains an *optional* peer dependency. A
+ * consumer that never installs Vite will never load this file (it's only
+ * reachable via the `./vite` subpath export).
+ */
+
+interface BotimDebugPluginOptions {
+    /**
+     * Override Vite's `mode`. Useful when the build is driven outside Vite's
+     * usual `--mode` flag, or in tests. If omitted, the plugin uses the mode
+     * Vite resolves from the CLI / config.
+     */
+    mode?: string;
+    /**
+     * Map Vite's mode to a BotimEnv. Defaults: `development` → `dev`,
+     * `production` → `prod`, others pass through verbatim.
+     */
+    mapMode?: (mode: string) => BotimEnv | string;
+    /**
+     * Project root override. Defaults to Vite's resolved `config.root`.
+     */
+    root?: string;
+    /**
+     * Relay endpoint to bake into `virtual:botim/config` as `relayUrl`. The
+     * SDK reads this at runtime so the host app can call:
+     *
+     *   enableRemoteDebug({ endpoint: botimConfig.relayUrl, … })
+     *
+     * Without this option, hosts must either set up a Vite proxy
+     * (`server.proxy: { '/v1': 'http://localhost:8090' }`) and pass
+     * `endpoint: location.origin`, OR pass an explicit URL at the call
+     * site. Passing it through the plugin centralises the wiring and makes
+     * mode-specific URLs trivial: read process.env.RELAY_URL in
+     * vite.config and forward it here.
+     *
+     * The relay must allow the page's origin via CORS (CORS_ORIGINS env on
+     * @botim/debug-relay defaults to "*"). Trailing slash is stripped at
+     * resolve time so `/v1/attach` joins cleanly.
+     */
+    relayUrl?: string;
+}
+declare function botimDebug(options?: BotimDebugPluginOptions): Plugin;
+
+export { type BotimConfig, BotimConfigError, type BotimDebugPluginOptions, type BotimEnv, botimDebug, resolveBotimConfig };