@shipeasy/sdk 3.1.0 → 4.2.0

package/dist/server/index.mjs

@@ -60,8 +60,247 @@ function send(url) {
   }
 }
 
+// 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 {
+  }
+}
+var REPORTED_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-reported");
+var SEE_MAX_CAUSE_DEPTH = 8;
+function readReportStamp(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const v = err[REPORTED_SYM];
+  return v !== void 0 && v !== null && typeof v === "object" ? v : void 0;
+}
+function findCausedBy(problem) {
+  let cur = problem;
+  const seen = /* @__PURE__ */ new Set();
+  for (let depth = 0; depth < SEE_MAX_CAUSE_DEPTH; depth++) {
+    if (typeof cur !== "object" || cur === null || seen.has(cur)) break;
+    seen.add(cur);
+    const stamp = readReportStamp(cur);
+    if (stamp) return stamp;
+    cur = cur.cause;
+  }
+  return void 0;
+}
+function markReported(problem, ev) {
+  if (!(problem instanceof Error)) return;
+  const stamp = {
+    error_type: ev.error_type,
+    message: ev.message,
+    subject: ev.subject,
+    outcome: ev.outcome
+  };
+  if (ev.stack !== void 0) stamp.stack = ev.stack;
+  try {
+    Object.defineProperty(problem, REPORTED_SYM, {
+      value: Object.freeze(stamp),
+      enumerable: false,
+      configurable: true,
+      writable: true
+    });
+  } catch {
+  }
+}
+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 causedBy = findCausedBy(problem);
+  if (causedBy) ev.caused_by = causedBy;
+  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;
+  markReported(problem, ev);
+  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(),
+      // Bare noun phrase — titles render as "… causes the {subject} …", so a
+      // leading article would double up ("causes the the app").
+      causesThe(subject ?? "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/server/index.ts
-var version = "1.0.0";
+var version = "4.0.0";
 var C1 = 3432918353;
 var C2 = 461845907;
 function murmur3(key) {
@@ -211,6 +450,7 @@ var FlagsClient = class {
   baseUrl;
   env;
   telemetry;
+  seeLimiter = new SeeLimiter();
   flagsBlob = null;
   expsBlob = null;
   flagsEtag = null;
@@ -363,6 +603,27 @@ var FlagsClient = class {
       body
     }).catch((err) => console.warn("[shipeasy] track failed:", String(err)));
   }
+  /**
+   * Report a structured error into the errors primitive. Fire-and-forget —
+   * never blocks or throws into the request path. Spam-guarded by a 30s
+   * dedup window + per-process cap.
+   */
+  reportError(problem, consequence, extras, kind) {
+    try {
+      const ev = buildSeeEvent(problem, consequence, extras, {
+        side: "server",
+        sdkVersion: version,
+        env: this.env
+      }, kind);
+      if (!this.seeLimiter.shouldSend(ev)) return;
+      globalThis.fetch(`${this.baseUrl}/collect`, {
+        method: "POST",
+        headers: { "X-SDK-Key": this.apiKey, "Content-Type": "text/plain" },
+        body: JSON.stringify({ events: [ev] })
+      }).catch((err) => console.warn("[shipeasy] see() send failed:", String(err)));
+    } catch {
+    }
+  }
   /**
    * Evaluate all flags, configs, and experiments for a user against the locally
    * cached blob (no network call). Applies ?se_ks_* / ?se_cf_* / ?se_exp_*
@@ -671,6 +932,20 @@ var flags = {
     };
   }
 };
+function dispatchSee(problem, consequence, extras, kind) {
+  if (!_server) {
+    console.warn("[shipeasy] see() called before shipeasy({ serverKey }) \u2014 error dropped");
+    return;
+  }
+  _server.reportError(problem, consequence, extras, kind);
+}
+var see = Object.assign(
+  (problem) => startSeeChain(() => problem, dispatchSee),
+  {
+    Violation: (name) => startSeeViolationChain(name, dispatchSee),
+    ControlFlowException: markExpected
+  }
+);
 export {
   FlagsClient,
   _resetShipeasyServerForTests,
@@ -680,6 +955,7 @@ export {
   getBootstrapHtml,
   getShipeasyServerClient,
   i18n,
+  see,
   shipeasy,
   version
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/sdk",
-  "version": "3.1.0",
+  "version": "4.2.0",
   "description": "Shipeasy SDK — feature gates, runtime configs, experiments, and metrics for the Shipeasy hosted service.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://shipeasy.ai",