@shipeasy/sdk 3.0.1 → 4.1.0

package/dist/server/index.mjs

@@ -1,6 +1,263 @@
 // src/server/index.ts
 import { AsyncLocalStorage } from "async_hooks";
-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 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/server/index.ts
+var version = "4.0.0";
 var C1 = 3432918353;
 var C2 = 461845907;
 function murmur3(key) {
@@ -149,6 +406,8 @@ var FlagsClient = class {
   apiKey;
   baseUrl;
   env;
+  telemetry;
+  seeLimiter = new SeeLimiter();
   flagsBlob = null;
   expsBlob = null;
   flagsEtag = null;
@@ -160,6 +419,13 @@ var FlagsClient = class {
     this.apiKey = opts.apiKey;
     this.baseUrl = (opts.baseUrl ?? "https://cdn.shipeasy.ai").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
+    this.telemetry = new Telemetry({
+      endpoint: opts.telemetryUrl ?? DEFAULT_TELEMETRY_URL,
+      sdkKey: this.apiKey,
+      side: "server",
+      env: this.env,
+      disabled: opts.disableTelemetry
+    });
     if (opts.initialBlob) {
       this.flagsBlob = opts.initialBlob;
       this.initialized = true;
@@ -221,17 +487,20 @@ var FlagsClient = class {
     this.expsBlob = await res.json();
   }
   getFlag(name, user) {
+    this.telemetry.emit("gate", name);
     const gate = this.flagsBlob?.gates[name];
     if (!gate) return false;
     return evalGateInternal(gate, user);
   }
   getConfig(name, decode) {
+    this.telemetry.emit("config", name);
     const entry = this.flagsBlob?.configs[name];
     if (!entry) return void 0;
     if (!decode) return entry.value;
     return decode(entry.value);
   }
   getExperiment(name, user, defaultParams, decode) {
+    this.telemetry.emit("experiment", name);
     const notIn = {
       inExperiment: false,
       group: "control",
@@ -291,6 +560,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_*
@@ -306,15 +596,18 @@ var FlagsClient = class {
     const experiments = {};
     const killswitches = {};
     for (const [name, gate] of Object.entries(this.flagsBlob?.gates ?? {})) {
+      this.telemetry.emit("gate", name);
       flags2[name] = evalGateInternal(gate, user);
     }
     for (const [name, entry] of Object.entries(this.flagsBlob?.configs ?? {})) {
+      this.telemetry.emit("config", name);
       configs[name] = entry.value;
     }
     for (const [name] of Object.entries(this.expsBlob?.experiments ?? {})) {
       experiments[name] = this.getExperiment(name, user, {});
     }
     for (const [name, ks] of Object.entries(this.flagsBlob?.killswitches ?? {})) {
+      this.telemetry.emit("ks", name);
       if (ks.switches && Object.keys(ks.switches).length > 0) {
         const out = {};
         for (const [k, v] of Object.entries(ks.switches)) out[k] = isEnabled(v);
@@ -334,6 +627,7 @@ var FlagsClient = class {
     return { flags: flags2, configs, experiments, killswitches };
   }
   getKillswitch(name, switchKey) {
+    this.telemetry.emit("ks", name);
     const ks = this.flagsBlob?.killswitches?.[name];
     if (!ks) return false;
     if (switchKey === void 0) return isEnabled(ks.killed);
@@ -469,7 +763,7 @@ async function shipeasy(opts) {
     );
   }
   const profile = opts.i18nDefaultProfile ?? "en:prod";
-  flags.configure({ apiKey: serverKey });
+  flags.configure({ apiKey: serverKey, disableTelemetry: opts.disableTelemetry });
   let resolvedUrlOverrides = opts.urlOverrides;
   if (!resolvedUrlOverrides) {
     try {
@@ -595,6 +889,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,
@@ -604,6 +912,7 @@ export {
   getBootstrapHtml,
   getShipeasyServerClient,
   i18n,
+  see,
   shipeasy,
   version
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/sdk",
-  "version": "3.0.1",
+  "version": "4.1.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",