@botim/mp-debug-sdk 0.7.2 → 1.0.0

package/dist/index.cjs

@@ -264,7 +264,7 @@ var RingBuffer = class {
 // src/transport.ts
 var DEFAULT_MAX_RETRIES = 3;
 var DEFAULT_POLL_TIMEOUT_MS = 25e3;
-var DEFAULT_MIN_BACKOFF_MS = 500;
+var DEFAULT_MIN_BACKOFF_MS = 2e3;
 var DEFAULT_MAX_BACKOFF_MS = 3e4;
 var Transport = class {
   constructor(opts) {
@@ -440,7 +440,7 @@ function sleep(ms) {
 }
 
 // src/attach.ts
-async function attachDevice(endpoint, config, deviceInfo, consent) {
+async function attachDevice(endpoint, config, deviceInfo, consent, token) {
   const base = endpoint.replace(/\/$/, "");
   const url = `${base}/v1/attach`;
   const body = {
@@ -451,9 +451,11 @@ async function attachDevice(endpoint, config, deviceInfo, consent) {
     consent,
     schemaVersion: SCHEMA_VERSION
   };
+  const headers = { "Content-Type": "application/json" };
+  if (token) headers.Authorization = `Bearer ${token}`;
   const res = await fetch(url, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers,
     body: JSON.stringify(body)
   });
   if (!res.ok) {
@@ -1570,7 +1572,7 @@ var DEFAULT_BODY_PATTERNS = [
   /[A-Za-z0-9_-]{40,}/g
 ];
 var DEFAULT_MAX_BODY_BYTES = 4096;
-var DEFAULT_FLUSH_INTERVAL_MS = 8e3;
+var DEFAULT_FLUSH_INTERVAL_MS = 4e3;
 var DEFAULT_BUFFER_SIZE = 1e3;
 var DEFAULT_MAX_BATCH_SIZE = 50;
 var NOOP_HANDLE = {
@@ -1585,6 +1587,10 @@ var NOOP_HANDLE = {
     return false;
   }
 };
+var defaultBotimConfig = null;
+function setDefaultBotimConfig(config) {
+  defaultBotimConfig = config;
+}
 function assertConsent(config, consent) {
   if (config.env !== "prod") return;
   const hasHostToken = typeof consent?.hostToken === "string" && consent.hostToken.length > 0;
@@ -1597,7 +1603,7 @@ function assertConsent(config, consent) {
 function assertConfig(config) {
   if (!config || typeof config !== "object") {
     throw new BotimConfigError(
-      'options.config is required (import botimConfig from "virtual:botim/config")',
+      'config is required \u2014 pass options.config, or register a default via "@botim/mp-debug-sdk/auto"',
       { code: "config-missing" }
     );
   }
@@ -1615,18 +1621,31 @@ function assertConfig(config) {
 }
 async function enableRemoteDebug(options) {
   if (options.enabled === false) return NOOP_HANDLE;
-  assertConfig(options.config);
+  if (!options.endpoint || typeof options.endpoint !== "string") {
+    throw new BotimConfigError(
+      'relay server URL is required \u2014 pass options.endpoint (e.g. "https://relay.example.com")',
+      { code: "endpoint-missing" }
+    );
+  }
+  const resolvedConfig = options.config ?? defaultBotimConfig;
+  if (!resolvedConfig) {
+    throw new BotimConfigError(
+      'no config provided and no default registered \u2014 import { enableRemoteDebug } from "@botim/mp-debug-sdk/auto" (Vite), or pass options.config',
+      { code: "config-missing" }
+    );
+  }
+  assertConfig(resolvedConfig);
   const consentInput = options.consent ?? {};
   const hasExplicitConsent = consentInput.userOptIn === true || typeof consentInput.hostToken === "string" && consentInput.hostToken.length > 0;
   const promptDisabled = consentInput.promptUser === false;
   const canPrompt = typeof document !== "undefined" && typeof window !== "undefined";
   const shouldPrompt = !hasExplicitConsent && !promptDisabled && canPrompt;
   if (shouldPrompt) {
-    const cached = readConsentDecision(options.config.miniProgramId);
+    const cached = readConsentDecision(resolvedConfig.miniProgramId);
     let decision = cached;
     if (decision === null) {
       decision = await promptForConsent(
-        options.config.miniProgramId,
+        resolvedConfig.miniProgramId,
         consentInput.promptCopy
       );
     }
@@ -1636,16 +1655,16 @@ async function enableRemoteDebug(options) {
       consent: { ...consentInput, userOptIn: true }
     };
   }
-  assertConsent(options.config, options.consent);
+  assertConsent(resolvedConfig, options.consent);
   const onError = options.onError ?? (() => {
   });
   const app = options.app ?? {
-    name: options.config.appName ?? options.config.miniProgramId,
-    version: options.config.appVersion ?? "0.0.0"
+    name: resolvedConfig.appName ?? resolvedConfig.miniProgramId,
+    version: resolvedConfig.appVersion ?? "0.0.0"
   };
   const deviceInfo = detectDeviceInfo(app, options.device);
   const consent = options.consent ?? {};
-  const session = await attachDevice(options.endpoint, options.config, deviceInfo, consent);
+  const session = await attachDevice(options.endpoint, resolvedConfig, deviceInfo, consent, options.token);
   const buffer = new RingBuffer({
     capacity: options.bufferSize ?? DEFAULT_BUFFER_SIZE
   });
@@ -1843,6 +1862,7 @@ exports.enableRemoteDebug = enableRemoteDebug;
 exports.getBOT = getBOT;
 exports.promptForConsent = promptForConsent;
 exports.readConsentDecision = readConsentDecision;
+exports.setDefaultBotimConfig = setDefaultBotimConfig;
 exports.writeConsentDecision = writeConsentDecision;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/index.d.cts

@@ -230,6 +230,12 @@ interface RemoteDebugOptions {
     enabled?: boolean;
     /** Relay base URL — your debug-relay deployment (e.g. "https://relay.example.com"). */
     endpoint: string;
+    /**
+     * Relay connect token (rdt_…) minted with `botim-cli relay token --mp <id>`.
+     * REQUIRED when the relay is hosted by botim-gateway (token-gated attach);
+     * ignored by legacy standalone relays.
+     */
+    token?: string;
     /**
      * Optional override for the app identity reported in events. When omitted
      * the SDK falls back to `config.appName` / `config.appVersion` resolved by
@@ -237,11 +243,12 @@ interface RemoteDebugOptions {
      */
     app?: AppInfo;
     /**
-     * Build-time-resolved mini-program identity. In typical usage this is
-     * `botimConfig` imported from `virtual:botim/config` (provided by the
-     * `@botim/debug-sdk/vite` plugin). REQUIRED.
+     * Build-time-resolved mini-program identity. Optional: when omitted, the SDK
+     * uses the config registered via `setDefaultBotimConfig` — which the
+     * `@botim/mp-debug-sdk/auto` entry sets from `virtual:botim/config`. Pass it
+     * explicitly to override.
      */
-    config: BotimConfig;
+    config?: BotimConfig;
     /**
      * Consent for telemetry. Required in `prod`; implicit in non-prod builds.
      */
@@ -281,21 +288,18 @@ declare const DEFAULT_MAX_BODY_BYTES = 4096;
 /**
  * How often the transport drains the buffer to the relay.
  *
- * 8 seconds is deliberately slow: this is a debug telemetry channel, not a
- * realtime one. With a 200ms cadence, a busy session producing ~10 events/sec
- * would make ~5 ingest POSTs/second, hammering the device's network stack
- * and the relay's write path for no human-visible benefit (admins poll at
- * 2s anyway, so end-to-end perceived latency is dominated by their poll).
- *
- * The timer fully drains the buffer per tick (multiple POSTs back-to-back if
- * needed, each capped at maxBatchSize), so the only cost of the longer
- * interval is up to 8s of potential delay before an event reaches the relay.
- *
- * Hosts can opt for tighter latency by setting `flushIntervalMs` explicitly.
+ * 4 seconds balances latency against chattiness — this is a debug telemetry
+ * channel, not a realtime one. A much tighter cadence would make a busy session
+ * (~10 events/sec) fire many ingest POSTs/sec for little human-visible gain
+ * (admins poll at ~2s). The timer fully drains the buffer per tick (back-to-back
+ * POSTs, each capped at maxBatchSize), so the only cost is up to ~4s of delay
+ * before an event reaches the relay. Hosts can set `flushIntervalMs` to tune it.
  */
-declare const DEFAULT_FLUSH_INTERVAL_MS = 8000;
+declare const DEFAULT_FLUSH_INTERVAL_MS = 4000;
 declare const DEFAULT_BUFFER_SIZE = 1000;
 declare const DEFAULT_MAX_BATCH_SIZE = 50;
+/** Register (or, with null, clear) the default BotimConfig used when `enableRemoteDebug` gets no `config`. */
+declare function setDefaultBotimConfig(config: BotimConfig | null): void;
 declare function enableRemoteDebug(options: RemoteDebugOptions): Promise<RemoteDebugHandle>;
 
-export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, type ConsentDecision, ConsentInput, ConsentPromptCopy, 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, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, writeConsentDecision };
+export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, type ConsentDecision, ConsentInput, ConsentPromptCopy, 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, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, setDefaultBotimConfig, writeConsentDecision };

package/dist/index.d.ts

@@ -230,6 +230,12 @@ interface RemoteDebugOptions {
     enabled?: boolean;
     /** Relay base URL — your debug-relay deployment (e.g. "https://relay.example.com"). */
     endpoint: string;
+    /**
+     * Relay connect token (rdt_…) minted with `botim-cli relay token --mp <id>`.
+     * REQUIRED when the relay is hosted by botim-gateway (token-gated attach);
+     * ignored by legacy standalone relays.
+     */
+    token?: string;
     /**
      * Optional override for the app identity reported in events. When omitted
      * the SDK falls back to `config.appName` / `config.appVersion` resolved by
@@ -237,11 +243,12 @@ interface RemoteDebugOptions {
      */
     app?: AppInfo;
     /**
-     * Build-time-resolved mini-program identity. In typical usage this is
-     * `botimConfig` imported from `virtual:botim/config` (provided by the
-     * `@botim/debug-sdk/vite` plugin). REQUIRED.
+     * Build-time-resolved mini-program identity. Optional: when omitted, the SDK
+     * uses the config registered via `setDefaultBotimConfig` — which the
+     * `@botim/mp-debug-sdk/auto` entry sets from `virtual:botim/config`. Pass it
+     * explicitly to override.
      */
-    config: BotimConfig;
+    config?: BotimConfig;
     /**
      * Consent for telemetry. Required in `prod`; implicit in non-prod builds.
      */
@@ -281,21 +288,18 @@ declare const DEFAULT_MAX_BODY_BYTES = 4096;
 /**
  * How often the transport drains the buffer to the relay.
  *
- * 8 seconds is deliberately slow: this is a debug telemetry channel, not a
- * realtime one. With a 200ms cadence, a busy session producing ~10 events/sec
- * would make ~5 ingest POSTs/second, hammering the device's network stack
- * and the relay's write path for no human-visible benefit (admins poll at
- * 2s anyway, so end-to-end perceived latency is dominated by their poll).
- *
- * The timer fully drains the buffer per tick (multiple POSTs back-to-back if
- * needed, each capped at maxBatchSize), so the only cost of the longer
- * interval is up to 8s of potential delay before an event reaches the relay.
- *
- * Hosts can opt for tighter latency by setting `flushIntervalMs` explicitly.
+ * 4 seconds balances latency against chattiness — this is a debug telemetry
+ * channel, not a realtime one. A much tighter cadence would make a busy session
+ * (~10 events/sec) fire many ingest POSTs/sec for little human-visible gain
+ * (admins poll at ~2s). The timer fully drains the buffer per tick (back-to-back
+ * POSTs, each capped at maxBatchSize), so the only cost is up to ~4s of delay
+ * before an event reaches the relay. Hosts can set `flushIntervalMs` to tune it.
  */
-declare const DEFAULT_FLUSH_INTERVAL_MS = 8000;
+declare const DEFAULT_FLUSH_INTERVAL_MS = 4000;
 declare const DEFAULT_BUFFER_SIZE = 1000;
 declare const DEFAULT_MAX_BATCH_SIZE = 50;
+/** Register (or, with null, clear) the default BotimConfig used when `enableRemoteDebug` gets no `config`. */
+declare function setDefaultBotimConfig(config: BotimConfig | null): void;
 declare function enableRemoteDebug(options: RemoteDebugOptions): Promise<RemoteDebugHandle>;
 
-export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, type ConsentDecision, ConsentInput, ConsentPromptCopy, 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, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, writeConsentDecision };
+export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, type ConsentDecision, ConsentInput, ConsentPromptCopy, 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, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, setDefaultBotimConfig, writeConsentDecision };

package/dist/index.js

@@ -262,7 +262,7 @@ var RingBuffer = class {
 // src/transport.ts
 var DEFAULT_MAX_RETRIES = 3;
 var DEFAULT_POLL_TIMEOUT_MS = 25e3;
-var DEFAULT_MIN_BACKOFF_MS = 500;
+var DEFAULT_MIN_BACKOFF_MS = 2e3;
 var DEFAULT_MAX_BACKOFF_MS = 3e4;
 var Transport = class {
   constructor(opts) {
@@ -438,7 +438,7 @@ function sleep(ms) {
 }
 
 // src/attach.ts
-async function attachDevice(endpoint, config, deviceInfo, consent) {
+async function attachDevice(endpoint, config, deviceInfo, consent, token) {
   const base = endpoint.replace(/\/$/, "");
   const url = `${base}/v1/attach`;
   const body = {
@@ -449,9 +449,11 @@ async function attachDevice(endpoint, config, deviceInfo, consent) {
     consent,
     schemaVersion: SCHEMA_VERSION
   };
+  const headers = { "Content-Type": "application/json" };
+  if (token) headers.Authorization = `Bearer ${token}`;
   const res = await fetch(url, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers,
     body: JSON.stringify(body)
   });
   if (!res.ok) {
@@ -1568,7 +1570,7 @@ var DEFAULT_BODY_PATTERNS = [
   /[A-Za-z0-9_-]{40,}/g
 ];
 var DEFAULT_MAX_BODY_BYTES = 4096;
-var DEFAULT_FLUSH_INTERVAL_MS = 8e3;
+var DEFAULT_FLUSH_INTERVAL_MS = 4e3;
 var DEFAULT_BUFFER_SIZE = 1e3;
 var DEFAULT_MAX_BATCH_SIZE = 50;
 var NOOP_HANDLE = {
@@ -1583,6 +1585,10 @@ var NOOP_HANDLE = {
     return false;
   }
 };
+var defaultBotimConfig = null;
+function setDefaultBotimConfig(config) {
+  defaultBotimConfig = config;
+}
 function assertConsent(config, consent) {
   if (config.env !== "prod") return;
   const hasHostToken = typeof consent?.hostToken === "string" && consent.hostToken.length > 0;
@@ -1595,7 +1601,7 @@ function assertConsent(config, consent) {
 function assertConfig(config) {
   if (!config || typeof config !== "object") {
     throw new BotimConfigError(
-      'options.config is required (import botimConfig from "virtual:botim/config")',
+      'config is required \u2014 pass options.config, or register a default via "@botim/mp-debug-sdk/auto"',
       { code: "config-missing" }
     );
   }
@@ -1613,18 +1619,31 @@ function assertConfig(config) {
 }
 async function enableRemoteDebug(options) {
   if (options.enabled === false) return NOOP_HANDLE;
-  assertConfig(options.config);
+  if (!options.endpoint || typeof options.endpoint !== "string") {
+    throw new BotimConfigError(
+      'relay server URL is required \u2014 pass options.endpoint (e.g. "https://relay.example.com")',
+      { code: "endpoint-missing" }
+    );
+  }
+  const resolvedConfig = options.config ?? defaultBotimConfig;
+  if (!resolvedConfig) {
+    throw new BotimConfigError(
+      'no config provided and no default registered \u2014 import { enableRemoteDebug } from "@botim/mp-debug-sdk/auto" (Vite), or pass options.config',
+      { code: "config-missing" }
+    );
+  }
+  assertConfig(resolvedConfig);
   const consentInput = options.consent ?? {};
   const hasExplicitConsent = consentInput.userOptIn === true || typeof consentInput.hostToken === "string" && consentInput.hostToken.length > 0;
   const promptDisabled = consentInput.promptUser === false;
   const canPrompt = typeof document !== "undefined" && typeof window !== "undefined";
   const shouldPrompt = !hasExplicitConsent && !promptDisabled && canPrompt;
   if (shouldPrompt) {
-    const cached = readConsentDecision(options.config.miniProgramId);
+    const cached = readConsentDecision(resolvedConfig.miniProgramId);
     let decision = cached;
     if (decision === null) {
       decision = await promptForConsent(
-        options.config.miniProgramId,
+        resolvedConfig.miniProgramId,
         consentInput.promptCopy
       );
     }
@@ -1634,16 +1653,16 @@ async function enableRemoteDebug(options) {
       consent: { ...consentInput, userOptIn: true }
     };
   }
-  assertConsent(options.config, options.consent);
+  assertConsent(resolvedConfig, options.consent);
   const onError = options.onError ?? (() => {
   });
   const app = options.app ?? {
-    name: options.config.appName ?? options.config.miniProgramId,
-    version: options.config.appVersion ?? "0.0.0"
+    name: resolvedConfig.appName ?? resolvedConfig.miniProgramId,
+    version: resolvedConfig.appVersion ?? "0.0.0"
   };
   const deviceInfo = detectDeviceInfo(app, options.device);
   const consent = options.consent ?? {};
-  const session = await attachDevice(options.endpoint, options.config, deviceInfo, consent);
+  const session = await attachDevice(options.endpoint, resolvedConfig, deviceInfo, consent, options.token);
   const buffer = new RingBuffer({
     capacity: options.bufferSize ?? DEFAULT_BUFFER_SIZE
   });
@@ -1827,6 +1846,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, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, writeConsentDecision };
+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, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, setDefaultBotimConfig, writeConsentDecision };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/vite/plugin.cjs

@@ -44,7 +44,7 @@ var BotimConfigError = class extends Error {
 
 // src/vite/resolve-config.ts
 var VALID_ENVS = ["dev", "uat", "beta", "prod"];
-var ID_PATTERN = /^[a-z][a-z0-9_-]{1,63}$/i;
+var ID_PATTERN = /^[a-z][a-z0-9._-]{1,127}$/i;
 function defaultMapMode(mode) {
   if (mode === "development") return "dev";
   if (mode === "production") return "prod";
@@ -66,30 +66,44 @@ function resolveBotimConfig(mode, root, opts = {}) {
   }
   const env = mapped;
   const projectRoot = (0, import_node_path.isAbsolute)(root) ? root : (0, import_node_path.resolve)(process.cwd(), root);
-  const fileName = resolveFileName(opts.configFileName, env, mode);
-  const filePath = (0, import_node_path.isAbsolute)(fileName) ? fileName : (0, import_node_path.resolve)(projectRoot, fileName);
+  const explicit = opts.configFileName !== void 0;
+  const candidates = explicit ? [
+    {
+      env,
+      path: (() => {
+        const fileName = resolveFileName(opts.configFileName, env, mode);
+        return (0, import_node_path.isAbsolute)(fileName) ? fileName : (0, import_node_path.resolve)(projectRoot, fileName);
+      })()
+    }
+  ] : buildCandidatePaths(projectRoot, env);
   const inline = opts.inlineConfig;
-  const inlineHasIdentity = typeof inline?.mp_id === "string" && inline.mp_id.length > 0 ? true : typeof inline?.miniProgramId === "string" && inline.miniProgramId.length > 0;
+  const inlineHasIdentity = typeof inline?.app_id === "string" && inline.app_id.length > 0 || typeof inline?.miniProgramId === "string" && inline.miniProgramId.length > 0;
+  const source = candidates.find((c) => (0, import_node_fs.existsSync)(c.path));
   let raw;
   let parsedFromFile = {};
-  if ((0, import_node_fs.existsSync)(filePath)) {
-    raw = (0, import_node_fs.readFileSync)(filePath, "utf8");
+  if (source) {
+    raw = (0, import_node_fs.readFileSync)(source.path, "utf8");
     try {
       parsedFromFile = JSON.parse(raw);
     } catch (err) {
       const detail = err instanceof Error ? err.message : String(err);
-      throw new BotimConfigError(`failed to parse JSON in ${filePath}: ${detail}`, {
+      throw new BotimConfigError(`failed to parse JSON in ${source.path}: ${detail}`, {
         code: "config-invalid-json",
-        path: filePath
+        path: source.path
       });
     }
-  } else if (!inlineHasIdentity) {
+    if (source.env !== env) {
+      console.warn(
+        `[@botim/debug-sdk] no config for env "${env}"; borrowed app_id from ${(0, import_node_path.basename)(source.path)} (env stays ${env})`
+      );
+    }
+  } else if (explicit && !inlineHasIdentity) {
+    const wanted = candidates[0].path;
     throw new BotimConfigError(
-      `expected config file not found: ${filePath}
-       Either create ${fileName} at the project root with at least { "mp_id": "..." },
-       pass an explicit { configFileName } / { config: { mp_id: "..." } } to botimDebug(),
-       or supply inlineConfig with mp_id when calling resolveBotimConfig() directly.`,
-      { code: "config-missing", path: filePath }
+      `expected config file not found: ${wanted}
+       Create it with at least { "app_id": "..." }, pass { configFileName },
+       or supply inlineConfig with app_id.`,
+      { code: "config-missing", path: wanted }
     );
   }
   const parsed = {
@@ -103,22 +117,28 @@ function resolveBotimConfig(mode, root, opts = {}) {
     parsed.package_url = { ...parsedFromFile.package_url, ...inline?.package_url };
   }
   if (parsed.deleted === 1) {
+    const label = source?.path ?? "inlineConfig";
     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 }
+      `${label} reports the mini-program as deleted (deleted: 1). Cannot ship debug SDK against a retired mini-program.`,
+      { code: "config-deleted", path: source?.path }
     );
   }
-  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 idValue = parsed.app_id ?? parsed.miniProgramId;
+  let miniProgramId;
+  if (typeof idValue === "string" && idValue.length > 0) {
+    if (!ID_PATTERN.test(idValue)) {
+      const label = source?.path ?? "inlineConfig";
+      throw new BotimConfigError(
+        `${label} field "app_id" must match ${ID_PATTERN.toString()} (got: ${JSON.stringify(idValue)})`,
+        { code: "config-invalid-id", path: source?.path }
+      );
+    }
+    miniProgramId = idValue;
+  } else {
+    miniProgramId = synthesizeMiniProgramId(projectRoot, env);
+    const reason = source ? `config ${(0, import_node_path.basename)(source.path)} has no app_id` : "no botim_config.*.json found for any env";
+    console.warn(
+      `[@botim/debug-sdk] ${reason}; synthesized id ${miniProgramId} (env=${env})`
     );
   }
   const md5 = typeof parsed.app?.md5 === "string" ? parsed.app.md5 : typeof parsed.package_url?.md5 === "string" ? parsed.package_url.md5 : void 0;
@@ -129,13 +149,13 @@ function resolveBotimConfig(mode, root, opts = {}) {
   } else if (versionForSig && md5) {
     buildSignature = `v${versionForSig}+md5:${md5.slice(0, 12)}`;
   } else {
-    const sigSource = raw ?? JSON.stringify({ mp_id: idValue, env, version: versionForSig, app: parsed.app });
+    const sigSource = raw ?? JSON.stringify({ app_id: miniProgramId, env, version: versionForSig, app: parsed.app });
     buildSignature = "sha256:" + (0, import_node_crypto.createHash)("sha256").update(sigSource).digest("hex").slice(0, 12);
   }
   const cfg = {
     // Spread first so the canonical fields below override anything inherited.
     ...parsed,
-    miniProgramId: idValue,
+    miniProgramId,
     env,
     buildSignature,
     appName: typeof parsed.app_id === "string" ? parsed.app_id : parsed.appName,
@@ -168,6 +188,20 @@ function resolveFileName(override, env, mode) {
     { code: "config-invalid-filename" }
   );
 }
+function synthesizeMiniProgramId(projectRoot, env) {
+  const dir = (0, import_node_path.basename)(projectRoot);
+  const hash = (0, import_node_crypto.createHash)("sha256").update(`${dir}:${env}`).digest("hex").slice(0, 8);
+  return `mp-${hash}`;
+}
+function buildCandidatePaths(projectRoot, selected) {
+  const order = [selected, ...VALID_ENVS.filter((e) => e !== selected)];
+  const out = [];
+  for (const e of order) {
+    out.push({ env: e, path: (0, import_node_path.resolve)(projectRoot, `botim_config.${e}.json`) });
+    out.push({ env: e, path: (0, import_node_path.resolve)(projectRoot, `botim.${e}.json`) });
+  }
+  return out;
+}
 
 // src/vite/plugin.ts
 var VIRTUAL_ID = "virtual:botim/config";

package/dist/vite/plugin.d.cts

@@ -25,14 +25,14 @@ interface BotimConfig {
  *
  *   external schema        →    SDK-internal `BotimConfig`
  *   ───────────────             ──────────────────────────
- *   mp_id                  →    miniProgramId
- *   app_id                 →    appId         (extra; preserved)
+ *   app_id (canonical) | miniProgramId (legacy input alias)  →  miniProgramId
  *   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.
+ * Prefers `botim_config.{env}.json`, falls back to legacy `botim.{env}.json`,
+ * and borrows app_id from a sibling env when the requested env has no file.
+ * Build-time only (Node fs/crypto) — never import from device code.
  */
 
 /**
@@ -86,7 +86,7 @@ interface ResolveOptions {
      * JSON (`{ mp_id: 'mbrx_p2p', version: process.env.VERSION }`).
      *
      * When no file exists at the resolved path, the resolver tolerates the
-     * miss as long as `inlineConfig` carries a usable `mp_id` (or its legacy
+     * miss as long as `inlineConfig` carries a usable `app_id` (or its legacy
      * `miniProgramId` alias). This is the file-less workflow — handy for
      * monorepos / native hosts that synthesize identity from env vars.
      */
@@ -99,7 +99,8 @@ interface ResolveOptions {
  *  - unknown env after `mapMode` is applied
  *  - missing or unreadable file
  *  - invalid JSON
- *  - missing/invalid `mp_id` (or its legacy `miniProgramId` alias)
+ *  - missing/invalid `app_id` (or its legacy `miniProgramId` alias); when
+ *    absent on the default file path a stable id is synthesized instead of thrown
  *  - the platform marking the mini-program as deleted (`deleted: 1`)
  */
 declare function resolveBotimConfig(mode: string, root: string, opts?: ResolveOptions): BotimConfig;

package/dist/vite/plugin.d.ts

@@ -25,14 +25,14 @@ interface BotimConfig {
  *
  *   external schema        →    SDK-internal `BotimConfig`
  *   ───────────────             ──────────────────────────
- *   mp_id                  →    miniProgramId
- *   app_id                 →    appId         (extra; preserved)
+ *   app_id (canonical) | miniProgramId (legacy input alias)  →  miniProgramId
  *   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.
+ * Prefers `botim_config.{env}.json`, falls back to legacy `botim.{env}.json`,
+ * and borrows app_id from a sibling env when the requested env has no file.
+ * Build-time only (Node fs/crypto) — never import from device code.
  */
 
 /**
@@ -86,7 +86,7 @@ interface ResolveOptions {
      * JSON (`{ mp_id: 'mbrx_p2p', version: process.env.VERSION }`).
      *
      * When no file exists at the resolved path, the resolver tolerates the
-     * miss as long as `inlineConfig` carries a usable `mp_id` (or its legacy
+     * miss as long as `inlineConfig` carries a usable `app_id` (or its legacy
      * `miniProgramId` alias). This is the file-less workflow — handy for
      * monorepos / native hosts that synthesize identity from env vars.
      */
@@ -99,7 +99,8 @@ interface ResolveOptions {
  *  - unknown env after `mapMode` is applied
  *  - missing or unreadable file
  *  - invalid JSON
- *  - missing/invalid `mp_id` (or its legacy `miniProgramId` alias)
+ *  - missing/invalid `app_id` (or its legacy `miniProgramId` alias); when
+ *    absent on the default file path a stable id is synthesized instead of thrown
  *  - the platform marking the mini-program as deleted (`deleted: 1`)
  */
 declare function resolveBotimConfig(mode: string, root: string, opts?: ResolveOptions): BotimConfig;