@shipeasy/sdk 3.0.1 → 4.1.0

package/dist/client/index.js

@@ -38,11 +38,273 @@ __export(client_exports, {
   readConfigOverride: () => readConfigOverride,
   readExpOverride: () => readExpOverride,
   readGateOverride: () => readGateOverride,
+  see: () => see,
   shipeasy: () => shipeasy,
   version: () => version
 });
 module.exports = __toCommonJS(client_exports);
-var version = "1.0.0";
+
+// src/telemetry.ts
+async function sha256Hex(input) {
+  const buf = new TextEncoder().encode(input);
+  const digest = await crypto.subtle.digest("SHA-256", buf);
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var DEFAULT_TELEMETRY_URL = "https://t.shipeasy.ai";
+var Telemetry = class {
+  prefix;
+  disabled;
+  dedupeMs;
+  // Last-emit timestamp per `feature/resource`, for the dedup window. Bounded by
+  // the number of distinct keys the app reads.
+  lastEmit = /* @__PURE__ */ new Map();
+  // Resolved once at construction and reused by every emit(), so the per-eval
+  // cost is a Map-free microtask, not a hash.
+  keyHash;
+  constructor(opts) {
+    const endpoint = (opts.endpoint ?? "").replace(/\/$/, "");
+    this.disabled = opts.disabled === true || !opts.sdkKey || !endpoint;
+    this.dedupeMs = opts.dedupeMs ?? 2e3;
+    this.prefix = `${endpoint}/t`;
+    this.keyHash = this.disabled ? null : sha256Hex(opts.sdkKey).then((h) => `${h}/${opts.side}/${encodeURIComponent(opts.env)}`).catch(() => "");
+  }
+  /**
+   * Emit a single best-effort usage beacon for one evaluation. Never blocks the
+   * caller (the hash is already resolved) and never throws — a failed beacon
+   * must never affect the evaluation it measures.
+   */
+  emit(feature, resource) {
+    if (this.disabled || !this.keyHash) return;
+    if (this.dedupeMs > 0) {
+      const dedupeKey = `${feature}/${resource}`;
+      const now = Date.now();
+      const last = this.lastEmit.get(dedupeKey);
+      if (last !== void 0 && now - last < this.dedupeMs) return;
+      this.lastEmit.set(dedupeKey, now);
+    }
+    void this.keyHash.then((suffix) => {
+      if (!suffix) return;
+      send(`${this.prefix}/${suffix}/${feature}/${encodeURIComponent(resource)}`);
+    });
+  }
+};
+function send(url) {
+  try {
+    if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(url);
+      return;
+    }
+    const f = globalThis.fetch;
+    if (typeof f === "function") {
+      void f(url, { method: "GET", keepalive: true }).catch(() => {
+      });
+    }
+  } catch {
+  }
+}
+
+// src/see/core.ts
+var SEE_MAX_MESSAGE = 500;
+var SEE_MAX_STACK = 8e3;
+var SEE_MAX_SUBJECT = 200;
+var SEE_MAX_EXTRA_VALUE = 200;
+var SEE_MAX_EXTRA_KEYS = 20;
+var SEE_DEDUP_WINDOW_MS = 3e4;
+var SEE_MAX_PER_SESSION = 25;
+function causesThe(subject) {
+  return {
+    to(outcome) {
+      return {
+        __seConsequence: true,
+        subject: truncate(String(subject), SEE_MAX_SUBJECT),
+        outcome: truncate(String(outcome), SEE_MAX_SUBJECT)
+      };
+    }
+  };
+}
+function violation(name) {
+  const make = (msg) => ({
+    __seViolation: true,
+    violationName: String(name),
+    ...msg !== void 0 ? { violationMessage: msg } : {},
+    message(m) {
+      return make(String(m));
+    }
+  });
+  return make();
+}
+function isViolation(p) {
+  return typeof p === "object" && p !== null && p.__seViolation === true;
+}
+var EXPECTED_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-expected");
+function markExpected(err, because) {
+  if (typeof err !== "object" || err === null) return;
+  try {
+    Object.defineProperty(err, EXPECTED_SYM, {
+      value: String(because),
+      enumerable: false,
+      configurable: true
+    });
+  } catch {
+  }
+}
+function isExpected(err) {
+  if (typeof err !== "object" || err === null) return false;
+  return err[EXPECTED_SYM] !== void 0;
+}
+function truncate(s, max) {
+  return s.length > max ? s.slice(0, max) : s;
+}
+function sanitizeExtras(extras) {
+  if (!extras || typeof extras !== "object") return void 0;
+  const out = {};
+  let n = 0;
+  for (const [k, v] of Object.entries(extras)) {
+    if (v === null || v === void 0) continue;
+    if (n >= SEE_MAX_EXTRA_KEYS) break;
+    if (typeof v === "string") out[k] = truncate(v, SEE_MAX_EXTRA_VALUE);
+    else if (typeof v === "number" && Number.isFinite(v)) out[k] = v;
+    else if (typeof v === "boolean") out[k] = v;
+    else continue;
+    n += 1;
+  }
+  return n > 0 ? out : void 0;
+}
+function captureCallsiteStack() {
+  const raw = new Error().stack;
+  if (!raw) return void 0;
+  const lines = raw.split("\n");
+  const kept = lines.slice(1).filter((l) => !/@shipeasy[\\/]sdk|see[\\/]core|captureCallsiteStack|\bsee\b\s*\(/.test(l));
+  return kept.length ? kept.join("\n") : void 0;
+}
+function buildSeeEvent(problem, consequence, extras, ctx, kindOverride) {
+  let errorType;
+  let message;
+  let stack;
+  let kind;
+  if (isViolation(problem)) {
+    errorType = problem.violationName;
+    message = problem.violationMessage ?? problem.violationName;
+    stack = captureCallsiteStack();
+    kind = kindOverride ?? "violation";
+  } else if (problem instanceof Error) {
+    errorType = problem.name || "Error";
+    message = problem.message || String(problem);
+    stack = problem.stack ?? void 0;
+    kind = kindOverride ?? "caught";
+  } else {
+    errorType = "Error";
+    message = typeof problem === "string" ? problem : safeString(problem);
+    stack = captureCallsiteStack();
+    kind = kindOverride ?? "caught";
+  }
+  const ev = {
+    type: "error",
+    kind,
+    error_type: truncate(errorType, SEE_MAX_SUBJECT),
+    message: truncate(message, SEE_MAX_MESSAGE),
+    subject: consequence.subject,
+    outcome: consequence.outcome,
+    side: ctx.side,
+    sdk_version: ctx.sdkVersion,
+    ts: Date.now()
+  };
+  if (stack) ev.stack = truncate(stack, SEE_MAX_STACK);
+  const cleanExtras = sanitizeExtras(extras);
+  if (cleanExtras) ev.extras = cleanExtras;
+  if (ctx.url) ev.url = truncate(ctx.url, SEE_MAX_SUBJECT);
+  if (ctx.userId) ev.user_id = ctx.userId;
+  if (ctx.anonId) ev.anonymous_id = ctx.anonId;
+  if (ctx.env) ev.env = ctx.env;
+  return ev;
+}
+function safeString(v) {
+  try {
+    return typeof v === "object" ? JSON.stringify(v) : String(v);
+  } catch {
+    return String(v);
+  }
+}
+var scheduleMicrotask = typeof queueMicrotask === "function" ? queueMicrotask : (cb) => {
+  void Promise.resolve().then(cb);
+};
+function startSeeChain(getProblem, dispatch) {
+  let subject;
+  let outcome;
+  let collected;
+  let flushed = false;
+  scheduleMicrotask(() => {
+    if (flushed) return;
+    flushed = true;
+    dispatch(
+      getProblem(),
+      causesThe(subject ?? "the app").to(outcome ?? "hit an error"),
+      collected
+    );
+  });
+  const tail = {
+    extras(x) {
+      if (x && typeof x === "object") collected = { ...collected, ...x };
+      return tail;
+    }
+  };
+  const step = {
+    to(o) {
+      outcome = String(o);
+      return tail;
+    }
+  };
+  const start = (s) => {
+    subject = String(s);
+    return step;
+  };
+  return { causes_the: start, causesThe: start };
+}
+function startSeeViolationChain(name, dispatch) {
+  let msg;
+  const base = startSeeChain(
+    () => msg !== void 0 ? violation(name).message(msg) : violation(name),
+    dispatch
+  );
+  const chain = {
+    ...base,
+    message(m) {
+      msg = String(m);
+      return chain;
+    }
+  };
+  return chain;
+}
+function topStackLine(stack) {
+  if (!stack) return "";
+  for (const line of stack.split("\n")) {
+    if (/^\s*at |@|:\d+:\d+/.test(line)) return line.trim().slice(0, 200);
+  }
+  return "";
+}
+var SeeLimiter = class {
+  constructor(maxPerSession = SEE_MAX_PER_SESSION, dedupWindowMs = SEE_DEDUP_WINDOW_MS) {
+    this.maxPerSession = maxPerSession;
+    this.dedupWindowMs = dedupWindowMs;
+  }
+  maxPerSession;
+  dedupWindowMs;
+  lastSent = /* @__PURE__ */ new Map();
+  sent = 0;
+  shouldSend(ev) {
+    if (this.sent >= this.maxPerSession) return false;
+    const key = `${ev.kind}|${ev.error_type}|${ev.message.slice(0, 200)}|${topStackLine(ev.stack)}`;
+    const now = Date.now();
+    const prev = this.lastSent.get(key);
+    if (prev !== void 0 && now - prev < this.dedupWindowMs) return false;
+    this.lastSent.set(key, now);
+    this.sent += 1;
+    return true;
+  }
+};
+
+// src/client/index.ts
+var version = "4.0.0";
 var FLUSH_INTERVAL_MS = 5e3;
 var MAX_BUFFER = 100;
 var ANON_ID_KEY = "__se_anon_id";
@@ -76,6 +338,13 @@ var EventBuffer = class {
       this.timer = null;
     }
   }
+  /** True once this visitor has been exposed to ≥1 experiment (this tab or a
+   *  prior page in the session — the dedup set persists in sessionStorage).
+   *  Gates auto-metric emission: vitals from non-participants are never read
+   *  by the analysis pipeline and would be pure AE write cost (see cost.md). */
+  hasExposures() {
+    return this.exposureSeen.size > 0;
+  }
   pushExposure(experiment, group, userId, anonId) {
     const key = `${userId || anonId}:${experiment}`;
     if (this.exposureSeen.has(key)) return;
@@ -141,16 +410,29 @@ var EventBuffer = class {
   flush(useBeacon = false) {
     if (!this.queue.length) return;
     const batch = this.queue.splice(0);
-    const body = JSON.stringify({ events: batch });
+    this.send(batch, useBeacon);
+  }
+  /**
+   * Bypass the 5s queue and ship events immediately — used by see() error
+   * reporting so occurrences land near-real-time and survive page unload.
+   * Beacon-first (fire-and-forget, unload-safe), keepalive fetch fallback.
+   */
+  sendNow(events) {
+    this.send(events, true);
+  }
+  send(batch, useBeacon) {
     if (useBeacon && typeof navigator !== "undefined" && navigator.sendBeacon) {
       const beaconBody = JSON.stringify({ k: this.sdkKey, events: batch });
-      navigator.sendBeacon(this.collectUrl, new Blob([beaconBody], { type: "text/plain" }));
-      return;
+      try {
+        if (navigator.sendBeacon(this.collectUrl, new Blob([beaconBody], { type: "text/plain" })))
+          return;
+      } catch {
+      }
     }
     fetch(this.collectUrl, {
       method: "POST",
       headers: { "X-SDK-Key": this.sdkKey, "Content-Type": "application/json" },
-      body,
+      body: JSON.stringify({ events: batch }),
       keepalive: true
     }).catch(() => {
     });
@@ -167,14 +449,12 @@ var EventBuffer = class {
     });
   }
 };
-var MAX_ERRORS_PER_SESSION = 5;
-function installAutoGuardrails(buffer, userId, anonId, groups) {
+function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignoreUrlPrefixes, always = false) {
   if (typeof window === "undefined" || typeof PerformanceObserver === "undefined") return;
+  const shouldEmit = () => always || buffer.hasExposures();
   let lcp = null;
   let inp = null;
   let clsBad = false;
-  let jsErrorCount = 0;
-  let netErrorCount = 0;
   let navTimingFlushed = false;
   if (groups.vitals) {
     try {
@@ -213,68 +493,71 @@ function installAutoGuardrails(buffer, userId, anonId, groups) {
   if (groups.errors) {
     const origOnError = window.onerror;
     window.onerror = (msg, source, lineno, _colno, err) => {
-      if (jsErrorCount < MAX_ERRORS_PER_SESSION) {
-        jsErrorCount += 1;
-        buffer.pushMetric("__auto_js_error", userId, anonId, {
-          value: 1,
-          kind: "exception",
-          message: typeof msg === "string" ? msg.slice(0, 200) : String(err ?? "").slice(0, 200),
-          source: typeof source === "string" ? source.slice(0, 200) : "",
-          line: lineno ?? 0
-        });
+      if (!isExpected(err)) {
+        const problem = err ?? (typeof msg === "string" && msg ? msg : "Unknown error");
+        reportSee(
+          problem,
+          causesThe("the page").to("hit an unhandled error"),
+          {
+            source: typeof source === "string" ? source : void 0,
+            line: lineno ?? void 0
+          },
+          "uncaught"
+        );
       }
       if (typeof origOnError === "function") return origOnError(msg, source, lineno, _colno, err);
       return false;
     };
     window.addEventListener("unhandledrejection", (e) => {
-      if (jsErrorCount < MAX_ERRORS_PER_SESSION) {
-        jsErrorCount += 1;
-        const reason = e.reason;
-        const message = reason instanceof Error ? reason.message : typeof reason === "string" ? reason : String(reason);
-        buffer.pushMetric("__auto_js_error", userId, anonId, {
-          value: 1,
-          kind: "unhandled_rejection",
-          message: message.slice(0, 200)
-        });
-      }
+      const reason = e.reason;
+      if (isExpected(reason)) return;
+      reportSee(
+        reason ?? "Unhandled promise rejection",
+        causesThe("the page").to("hit an unhandled promise rejection"),
+        void 0,
+        "unhandled_rejection"
+      );
     });
     const origFetch = window.fetch;
     window.fetch = async function(...args) {
       const startedAt = typeof performance !== "undefined" ? performance.now() : 0;
       const url = typeof args[0] === "string" ? args[0] : args[0].toString();
+      const ignored = ignoreUrlPrefixes.some((p) => p && url.startsWith(p));
+      const bareUrl = url.split("?")[0].slice(0, 200);
       let res;
       try {
         res = await origFetch.apply(this, args);
       } catch (err) {
-        if (netErrorCount < MAX_ERRORS_PER_SESSION) {
-          netErrorCount += 1;
-          buffer.pushMetric("__auto_network_error", userId, anonId, {
-            value: 1,
-            kind: "network",
-            status: 0,
-            url: url.slice(0, 200)
-          });
+        if (!ignored && !isExpected(err)) {
+          reportSee(
+            violation("NetworkError").message(`request to ${bareUrl} failed`),
+            causesThe("a network request").to("fail without a response"),
+            { status: 0, url: url.slice(0, 200) },
+            "network"
+          );
         }
         throw err;
       }
-      if (res.status >= 500 && netErrorCount < MAX_ERRORS_PER_SESSION) {
-        netErrorCount += 1;
+      if (!ignored && res.status >= 500) {
         const elapsed = typeof performance !== "undefined" ? performance.now() - startedAt : 0;
-        buffer.pushMetric("__auto_network_error", userId, anonId, {
-          value: 1,
-          kind: "5xx",
-          status: res.status,
-          url: url.slice(0, 200),
-          duration_ms: Math.round(elapsed)
-        });
+        reportSee(
+          violation("Http5xx").message(`request to ${bareUrl} returned ${res.status}`),
+          causesThe("a network request").to(`fail with HTTP ${res.status}`),
+          { status: res.status, url: url.slice(0, 200), duration_ms: Math.round(elapsed) },
+          "network"
+        );
       }
       return res;
     };
   }
   const flushNavTiming = () => {
     if (navTimingFlushed) return;
+    if (!groups.vitals) {
+      navTimingFlushed = true;
+      return;
+    }
+    if (!shouldEmit()) return;
     navTimingFlushed = true;
-    if (!groups.vitals) return;
     try {
       const navList = performance.getEntriesByType("navigation");
       const nav = navList[0];
@@ -309,7 +592,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups) {
   };
   if (groups.engagement) {
     try {
-      buffer.pushMetric("__auto_session_active", userId, anonId, { value: 1 });
+      if (shouldEmit()) buffer.pushMetric("__auto_session_active", userId, anonId, { value: 1 });
     } catch {
     }
     let lastEmit = Date.now();
@@ -317,6 +600,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups) {
     document.addEventListener("visibilitychange", () => {
       if (document.visibilityState !== "visible") return;
       if (Date.now() - lastEmit < SESSION_GAP_MS) return;
+      if (!shouldEmit()) return;
       try {
         buffer.pushMetric("__auto_session_active", userId, anonId, { value: 1 });
         lastEmit = Date.now();
@@ -339,7 +623,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups) {
     }
     const flushOnHide = () => {
       flushNavTiming();
-      if (groups.vitals) {
+      if (groups.vitals && shouldEmit()) {
         if (lcp !== null) buffer.pushMetric("__auto_lcp", userId, anonId, { value: lcp });
         if (inp !== null) buffer.pushMetric("__auto_inp", userId, anonId, { value: inp });
         if (clsBad) buffer.pushMetric("__auto_cls_binary", userId, anonId, { value: 1 });
@@ -422,11 +706,14 @@ var FlagsClientBrowser = class {
   baseUrl;
   autoGuardrails;
   autoGuardrailGroups;
+  autoCollectAlways;
   env;
   evalResult = null;
   anonId;
   userId = "";
   buffer;
+  telemetry;
+  seeLimiter = new SeeLimiter();
   guardrailsInstalled = false;
   listeners = /* @__PURE__ */ new Set();
   overrideListenerInstalled = false;
@@ -442,6 +729,7 @@ var FlagsClientBrowser = class {
     this.baseUrl = (opts.baseUrl ?? "https://edge.shipeasy.dev").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
     this.autoGuardrails = opts.autoGuardrails !== false;
+    this.autoCollectAlways = opts.autoCollectAlways === true;
     const g = opts.autoGuardrailGroups ?? {};
     this.autoGuardrailGroups = {
       vitals: g.vitals ?? this.autoGuardrails,
@@ -450,6 +738,13 @@ var FlagsClientBrowser = class {
     };
     this.anonId = getOrCreateAnonId();
     this.buffer = new EventBuffer(`${this.baseUrl}/collect`, this.sdkKey);
+    this.telemetry = new Telemetry({
+      endpoint: opts.telemetryUrl ?? DEFAULT_TELEMETRY_URL,
+      sdkKey: this.sdkKey,
+      side: "client",
+      env: this.env,
+      disabled: opts.disableTelemetry
+    });
     void this.buffer.flushPendingAlias();
   }
   async identify(user) {
@@ -479,10 +774,38 @@ var FlagsClientBrowser = class {
     const anyGroupOn = this.autoGuardrailGroups.vitals || this.autoGuardrailGroups.errors || this.autoGuardrailGroups.engagement;
     if (anyGroupOn && !this.guardrailsInstalled) {
       this.guardrailsInstalled = true;
-      installAutoGuardrails(this.buffer, this.userId, this.anonId, this.autoGuardrailGroups);
+      installAutoGuardrails(
+        this.buffer,
+        this.userId,
+        this.anonId,
+        this.autoGuardrailGroups,
+        (problem, consequence, extras, kind) => this.reportError(problem, consequence, extras, kind),
+        [`${this.baseUrl}/`, DEFAULT_TELEMETRY_URL],
+        this.autoCollectAlways
+      );
     }
     this.notify();
   }
+  /**
+   * Report a structured error into the errors primitive. Flushes immediately
+   * (beacon-first) — error occurrences are near-real-time, never queued behind
+   * the 5s metric batch. Spam-guarded by a 30s dedup window + per-session cap.
+   */
+  reportError(problem, consequence, extras, kind) {
+    try {
+      const ev = buildSeeEvent(problem, consequence, extras, {
+        side: "client",
+        sdkVersion: version,
+        env: this.env,
+        url: typeof window !== "undefined" && window.location ? window.location.href : void 0,
+        userId: this.userId || void 0,
+        anonId: this.anonId
+      }, kind);
+      if (!this.seeLimiter.shouldSend(ev)) return;
+      this.buffer.sendNow([ev]);
+    } catch {
+    }
+  }
   get ready() {
     return this.evalResult !== null;
   }
@@ -499,12 +822,14 @@ var FlagsClientBrowser = class {
     this.evalResult = data;
   }
   getFlag(name) {
+    this.telemetry.emit("gate", name);
     if (this.evalResult === null) return false;
     const ov = readGateOverride(name);
     if (ov !== null) return ov;
     return this.evalResult.flags[name] ?? false;
   }
   getConfig(name, decode) {
+    this.telemetry.emit("config", name);
     if (this.evalResult === null) return void 0;
     const ov = readConfigOverride(name);
     const raw = ov !== void 0 ? ov : this.evalResult.configs?.[name];
@@ -518,6 +843,7 @@ var FlagsClientBrowser = class {
     }
   }
   getExperiment(name, defaultParams, decode, variants) {
+    this.telemetry.emit("experiment", name);
     const notIn = {
       inExperiment: false,
       group: "control",
@@ -582,6 +908,7 @@ var FlagsClientBrowser = class {
    * the per-switch state. Returns false for unknown killswitches / switches.
    */
   getKillswitch(name, switchKey) {
+    this.telemetry.emit("ks", name);
     if (this.evalResult === null) return false;
     const ks = this.evalResult.killswitches?.[name];
     if (ks === void 0) return false;
@@ -710,13 +1037,16 @@ var _client = null;
 function shipeasy(opts) {
   const ac = opts.autoCollect;
   const blanket = ac === false ? false : true;
-  const groups = ac && typeof ac === "object" ? ac : void 0;
+  const acObj = ac && typeof ac === "object" ? ac : void 0;
+  const groups = acObj ? { vitals: acObj.vitals, errors: acObj.errors, engagement: acObj.engagement } : void 0;
   const baseUrl = opts.baseUrl ?? "https://cdn.shipeasy.ai";
   const client = configureShipeasy({
     sdkKey: opts.clientKey,
     baseUrl,
     autoGuardrails: blanket,
-    autoGuardrailGroups: groups
+    autoGuardrailGroups: groups,
+    autoCollectAlways: acObj?.always === true,
+    disableTelemetry: opts.disableTelemetry
   });
   injectI18nLoader(opts.clientKey, baseUrl, opts.i18nProfile);
   flags.notifyMounted();
@@ -877,6 +1207,20 @@ var flags = {
     return _client?.ready ?? false;
   }
 };
+function dispatchSee(problem, consequence, extras, kind) {
+  if (!_client) {
+    console.warn("[shipeasy] see() called before shipeasy({ clientKey }) \u2014 error dropped");
+    return;
+  }
+  _client.reportError(problem, consequence, extras, kind);
+}
+var see = Object.assign(
+  (problem) => startSeeChain(() => problem, dispatchSee),
+  {
+    Violation: (name) => startSeeViolationChain(name, dispatchSee),
+    ControlFlowException: markExpected
+  }
+);
 var LABEL_MARKER_START = "\uFFF9";
 var LABEL_MARKER_SEP = "\uFFFA";
 var LABEL_MARKER_END = "\uFFFB";
@@ -1129,6 +1473,7 @@ var i18n = {
   readConfigOverride,
   readExpOverride,
   readGateOverride,
+  see,
   shipeasy,
   version
 });