@mushi-mushi/core 1.22.5 → 1.23.0

package/README.md

@@ -23,7 +23,7 @@ Core types, API client, and shared utilities for every Mushi SDK package.
 
 | Type                       | Purpose                                                                                       |
 |----------------------------|-----------------------------------------------------------------------------------------------|
-| `MushiPreset`              | `'production-calm' \| 'beta-loud' \| 'internal-debug' \| 'manual-only'` posture bundles.      |
+| `MushiPreset`              | Posture bundles: `'production-calm' \| 'beta-loud' \| 'internal-debug' \| 'manual-only'` plus the tiers `'minimal' \| 'standard' \| 'full'`. See [Config presets](#config-presets--precedence). |
 | `MushiWidgetAnchor`        | Raw-CSS positioning (`top` / `right` / `bottom` / `left`) for the widget launcher.            |
 | `MushiPrivacyConfig`       | `maskSelectors`, `blockSelectors`, `allowUserRemoveScreenshot` for screenshot redaction.       |
 | `MushiUrlMatcher`          | `string \| RegExp` element used by `capture.ignoreUrls` and `apiCascade.ignoreUrls`.          |
@@ -46,6 +46,61 @@ Constants: `MUSHI_INTERNAL_HEADER` (`'X-Mushi-Internal'`),
 `MUSHI_INTERNAL_INIT_MARKER`, and the `MushiInternalRequestKind` literal union
 are re-exported so framework adapters can build their own self-noise filters.
 
+## Config presets & precedence
+
+Pass `preset` to pick a posture bundle instead of hand-assembling
+`widget` / `capture` / `proactive` flags. `expandPreset(config)` expands the
+preset into those nested objects; **your explicit config always wins** on every
+key (the merge is per-sub-object, so overriding one `capture` flag keeps the
+rest of the preset's defaults).
+
+| Field                | `minimal`      | `standard`         | `full`           |
+|----------------------|----------------|--------------------|------------------|
+| Widget               | on (`auto`)    | on (SDK default)   | on (`auto`)      |
+| `capture.console`    | ✅              | default            | ✅                |
+| `capture.network`    | ❌              | default            | ✅                |
+| `capture.performance`| ❌              | default            | ✅                |
+| `capture.screenshot` | `on-report`    | default            | `auto`           |
+| `capture.replay`     | `off`          | default            | `lite`           |
+| Proactive triggers   | none           | default            | all on           |
+
+- **`minimal`** — widget + console capture only, screenshot on report; no
+  network/performance/replay, no proactive nudges. Leanest footprint.
+- **`standard`** — today's SDK defaults. Expansion is a **no-op** (the config
+  is returned untouched); the preset exists so the intent is explicit and
+  documented.
+- **`full`** — every capture channel on (including a self-contained `lite`
+  session replay) and all proactive triggers. Loudest / most data.
+
+The four legacy postures — `production-calm`, `beta-loud`, `internal-debug`,
+`manual-only` — are still supported and expand the same way.
+
+### Precedence
+
+Highest wins. `resolveEnvConfig()` only ever supplies
+`projectId` / `apiKey` / `apiEndpoint`, so it never competes with a preset for
+the nested option objects.
+
+| Priority | Source                              | Example                                   |
+|----------|-------------------------------------|-------------------------------------------|
+| 1 (wins) | Explicit config                     | `capture: { network: true }`              |
+| 2        | `preset`                            | `preset: 'minimal'` → `network: false`    |
+| 3        | Environment variables               | `NEXT_PUBLIC_MUSHI_*` / `VITE_MUSHI_*`    |
+| 4        | SDK defaults                        | built-in fallbacks                        |
+
+### Validation
+
+`validateConfig(config)` runs at init and **fails loud but never throws**: it
+`console.error`s on unknown top-level keys (usually a typo) and on an invalid
+`preset` value, then continues. Set `MUSHI_SILENT=1` to suppress the warnings.
+
+```typescript
+import { expandPreset, validateConfig } from '@mushi-mushi/core';
+
+validateConfig(config);              // warns on typos / bad preset (never throws)
+const resolved = expandPreset(config); // preset → nested objects, explicit wins
+```
+
 ## Usage
 
 ```typescript

package/dist/index.cjs

@@ -601,6 +601,219 @@ function resolveEnvConfig() {
   if (apiEndpoint) result.apiEndpoint = apiEndpoint;
   return result;
 }
+var ENV_PREFIXES = ["VITE_", "NEXT_PUBLIC_", "NUXT_PUBLIC_", "EXPO_PUBLIC_", ""];
+var FIELD_SUFFIX = {
+  projectId: "MUSHI_PROJECT_ID",
+  apiKey: "MUSHI_API_KEY"
+};
+function diagnoseEnvConfig() {
+  const resolved = resolveEnvConfig();
+  const missing = [];
+  if (!resolved.projectId) missing.push("projectId");
+  if (!resolved.apiKey) missing.push("apiKey");
+  if (missing.length === 0) {
+    return { resolved, missing, nearMisses: [], message: null };
+  }
+  const importMetaEnv = (() => {
+    try {
+      const env = undefined;
+      return typeof env === "object" && env !== null ? env : null;
+    } catch {
+      return null;
+    }
+  })();
+  const processEnv = (() => {
+    try {
+      return typeof process !== "undefined" && process.env ? process.env : null;
+    } catch {
+      return null;
+    }
+  })();
+  const nearMisses = [];
+  for (const field of missing) {
+    for (const prefix of ENV_PREFIXES) {
+      const key = `${prefix}${FIELD_SUFFIX[field]}`;
+      if (importMetaEnv && importMetaEnv[key]) {
+        nearMisses.push({ field, key, via: "import.meta.env" });
+      } else if (processEnv && processEnv[key]) {
+        nearMisses.push({ field, key, via: "process.env" });
+      }
+    }
+  }
+  const expectedPrefix = importMetaEnv ? "VITE_MUSHI_*" : "NEXT_PUBLIC_MUSHI_* (Next.js), EXPO_PUBLIC_MUSHI_* (Expo), or MUSHI_* (Node / React Native)";
+  const lines = [`[mushi] Missing ${missing.join(" and ")} \u2014 the SDK will not initialize.`];
+  for (const m of nearMisses) {
+    lines.push(
+      `[mushi] Found ${m.key} in ${m.via}, but this runtime did not resolve it \u2014 it is either the wrong prefix for your bundler or not exposed to the client bundle.`
+    );
+  }
+  lines.push(`[mushi] This runtime reads: ${expectedPrefix}. Set the matching variable(s) and restart your dev server.`);
+  if (nearMisses.length === 0) {
+    lines.push(
+      `[mushi] If you already set the variable, check the prefix: a mis-prefixed var is stripped from client bundles and resolves to undefined with no error.`
+    );
+  }
+  return { resolved, missing, nearMisses, message: lines.join("\n") };
+}
+
+// src/presets.ts
+var KNOWN_PRESETS = [
+  "production-calm",
+  "beta-loud",
+  "internal-debug",
+  "manual-only",
+  "minimal",
+  "standard",
+  "full"
+];
+var KNOWN_CONFIG_KEYS = [
+  "projectId",
+  "apiKey",
+  "apiEndpoint",
+  "timeout",
+  "maxRetries",
+  "circuitBreaker",
+  "preset",
+  "runtimeConfig",
+  "sentry",
+  "widget",
+  "capture",
+  "privacy",
+  "proactive",
+  "preFilter",
+  "integrations",
+  "offline",
+  "rewards",
+  "assistant",
+  "debug",
+  "enabled",
+  "appVersion",
+  "beforeSendFeedback",
+  "onCrashedLastRun"
+];
+function presetDefaults(preset) {
+  switch (preset) {
+    case "manual-only":
+      return {
+        widget: { trigger: "manual", outdatedBanner: "console-only" },
+        capture: { console: true, network: true, performance: false, screenshot: "on-report", elementSelector: false },
+        proactive: { rageClick: false, longTask: false, apiCascade: false, errorBoundary: false }
+      };
+    case "beta-loud":
+      return {
+        widget: { trigger: "auto", outdatedBanner: "banner" },
+        capture: { console: true, network: true, performance: true, screenshot: "auto", elementSelector: true },
+        proactive: { rageClick: true, longTask: true, apiCascade: true, errorBoundary: true }
+      };
+    case "internal-debug":
+      return {
+        widget: { trigger: "auto", outdatedBanner: "banner", brandFooter: true },
+        capture: { console: true, network: true, performance: true, screenshot: "auto", elementSelector: true },
+        proactive: {
+          rageClick: true,
+          longTask: true,
+          apiCascade: true,
+          errorBoundary: true,
+          cooldown: { maxProactivePerSession: 10, dismissCooldownHours: 0, suppressAfterDismissals: 99 }
+        }
+      };
+    case "production-calm":
+      return {
+        widget: { trigger: "auto", outdatedBanner: "console-only" },
+        capture: { console: true, network: true, performance: false, screenshot: "on-report", elementSelector: false },
+        proactive: { rageClick: false, longTask: false, apiCascade: false, errorBoundary: false }
+      };
+    // Lean posture: widget on, console capture only, screenshot on-report,
+    // no network/performance/replay, no proactive nudges.
+    case "minimal":
+      return {
+        widget: { trigger: "auto" },
+        capture: {
+          console: true,
+          network: false,
+          performance: false,
+          screenshot: "on-report",
+          replay: "off",
+          elementSelector: false
+        },
+        proactive: { rageClick: false, longTask: false, apiCascade: false, errorBoundary: false }
+      };
+    // Everything-on posture: full capture (incl. self-contained `lite` replay)
+    // and every proactive trigger.
+    case "full":
+      return {
+        widget: { trigger: "auto" },
+        capture: {
+          console: true,
+          network: true,
+          performance: true,
+          screenshot: "auto",
+          replay: "lite",
+          elementSelector: true
+        },
+        proactive: { rageClick: true, longTask: true, apiCascade: true, errorBoundary: true }
+      };
+    // 'standard' and anything unrecognised → no expansion.
+    default:
+      return void 0;
+  }
+}
+function expandPreset(config) {
+  const defaults = presetDefaults(config.preset);
+  if (!defaults) return config;
+  return {
+    ...config,
+    widget: {
+      ...defaults.widget,
+      ...config.widget
+    },
+    capture: {
+      ...defaults.capture,
+      ...config.capture
+    },
+    proactive: {
+      ...defaults.proactive,
+      ...config.proactive,
+      cooldown: {
+        ...defaults.proactive?.cooldown,
+        ...config.proactive?.cooldown
+      }
+    }
+  };
+}
+function isSilenced() {
+  const truthy = (v) => v === "1" || v === "true";
+  try {
+    if (typeof process !== "undefined" && process.env && truthy(process.env.MUSHI_SILENT)) return true;
+  } catch {
+  }
+  try {
+    const env = undefined;
+    if (env && typeof env === "object" && (truthy(env.MUSHI_SILENT) || truthy(env.VITE_MUSHI_SILENT))) return true;
+  } catch {
+  }
+  return false;
+}
+function validateConfig(config) {
+  try {
+    if (isSilenced()) return;
+    if (!config || typeof config !== "object") return;
+    const unknownKeys = Object.keys(config).filter((key) => !KNOWN_CONFIG_KEYS.includes(key));
+    if (unknownKeys.length > 0) {
+      console.error(
+        `[mushi] Unknown config key${unknownKeys.length > 1 ? "s" : ""}: ${unknownKeys.map((k) => `\`${k}\``).join(", ")} \u2014 check for typos (see MushiConfig). Ignored.`
+      );
+    }
+    if (config.preset !== void 0 && !KNOWN_PRESETS.includes(config.preset)) {
+      console.error(
+        `[mushi] Unknown preset \`${String(config.preset)}\` \u2014 expected one of ${KNOWN_PRESETS.map(
+          (p) => `'${p}'`
+        ).join(", ")}. Preset ignored.`
+      );
+    }
+  } catch {
+  }
+}
 
 // src/pre-filter.ts
 var DEFAULT_MIN_LENGTH = 10;
@@ -2206,7 +2419,9 @@ exports.createOfflineQueue = createOfflineQueue;
 exports.createPiiScrubber = createPiiScrubber;
 exports.createPreFilter = createPreFilter;
 exports.createRateLimiter = createRateLimiter;
+exports.diagnoseEnvConfig = diagnoseEnvConfig;
 exports.estimateJsonBytes = estimateJsonBytes;
+exports.expandPreset = expandPreset;
 exports.faviconUrlCandidates = faviconUrlCandidates;
 exports.formatBytes = formatBytes;
 exports.getDeviceFingerprintHash = getDeviceFingerprintHash;
@@ -2235,5 +2450,6 @@ exports.resolveWidgetAccent = resolveWidgetAccent;
 exports.safeWidgetHex = safeWidgetHex;
 exports.scrubPii = scrubPii;
 exports.sha256Hex = sha256Hex;
+exports.validateConfig = validateConfig;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map