@shipeasy/sdk 1.0.0 → 1.2.0

package/dist/client/index.mjs

@@ -123,13 +123,15 @@ var EventBuffer = class {
     });
   }
 };
+var MAX_ERRORS_PER_SESSION = 5;
 function installAutoGuardrails(buffer, userId, anonId) {
   if (typeof window === "undefined" || typeof PerformanceObserver === "undefined") return;
   let lcp = null;
   let inp = null;
   let clsBad = false;
-  let jsError = false;
-  let netError = false;
+  let jsErrorCount = 0;
+  let netErrorCount = 0;
+  let navTimingFlushed = false;
   try {
     const lcpObs = new PerformanceObserver((list) => {
       const entries = list.getEntries();
@@ -163,30 +165,112 @@ function installAutoGuardrails(buffer, userId, anonId) {
   } catch {
   }
   const origOnError = window.onerror;
-  window.onerror = (...args) => {
-    if (!jsError) {
-      jsError = true;
-      buffer.pushMetric("__auto_js_error", userId, anonId, { value: 1 });
+  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 (typeof origOnError === "function") return origOnError(...args);
+    if (typeof origOnError === "function") return origOnError(msg, source, lineno, _colno, err);
     return false;
   };
-  window.addEventListener("unhandledrejection", () => {
-    if (!jsError) {
-      jsError = true;
-      buffer.pushMetric("__auto_js_error", userId, anonId, { value: 1 });
+  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 origFetch = window.fetch;
   window.fetch = async function(...args) {
-    const res = await origFetch.apply(this, args);
-    if (!netError && res.status >= 500) {
-      netError = true;
-      buffer.pushMetric("__auto_network_error", userId, anonId, { value: 1 });
+    const startedAt = typeof performance !== "undefined" ? performance.now() : 0;
+    const url = typeof args[0] === "string" ? args[0] : args[0].toString();
+    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)
+        });
+      }
+      throw err;
+    }
+    if (res.status >= 500 && netErrorCount < MAX_ERRORS_PER_SESSION) {
+      netErrorCount += 1;
+      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)
+      });
     }
     return res;
   };
-  const flush = () => {
+  const flushNavTiming = () => {
+    if (navTimingFlushed) return;
+    navTimingFlushed = true;
+    try {
+      const navList = performance.getEntriesByType("navigation");
+      const nav = navList[0];
+      if (nav) {
+        const start = nav.startTime ?? 0;
+        if (nav.loadEventEnd > 0) {
+          buffer.pushMetric("__auto_page_load", userId, anonId, {
+            value: nav.loadEventEnd - start
+          });
+        }
+        if (nav.responseStart > 0) {
+          buffer.pushMetric("__auto_ttfb", userId, anonId, {
+            value: nav.responseStart - start
+          });
+        }
+        if (nav.domContentLoadedEventEnd > 0) {
+          buffer.pushMetric("__auto_dom_ready", userId, anonId, {
+            value: nav.domContentLoadedEventEnd - start
+          });
+        }
+      }
+      const paints = performance.getEntriesByType("paint");
+      for (const p of paints) {
+        if (p.name === "first-paint") {
+          buffer.pushMetric("__auto_fp", userId, anonId, { value: p.startTime });
+        } else if (p.name === "first-contentful-paint") {
+          buffer.pushMetric("__auto_fcp", userId, anonId, { value: p.startTime });
+        }
+      }
+    } catch {
+    }
+  };
+  if (document.readyState === "complete") {
+    setTimeout(flushNavTiming, 0);
+  } else {
+    window.addEventListener(
+      "load",
+      () => {
+        setTimeout(flushNavTiming, 0);
+      },
+      { once: true }
+    );
+  }
+  const flushOnHide = () => {
+    flushNavTiming();
     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 });
@@ -195,7 +279,7 @@ function installAutoGuardrails(buffer, userId, anonId) {
     buffer.flush(true);
   };
   document.addEventListener("visibilitychange", () => {
-    if (document.visibilityState === "hidden") flush();
+    if (document.visibilityState === "hidden") flushOnHide();
   });
 }
 function getOrCreateAnonId() {
@@ -211,18 +295,75 @@ function getOrCreateAnonId() {
   }
   return id;
 }
+function collectBrowserAttrs() {
+  if (typeof window === "undefined") return {};
+  const attrs = {};
+  try {
+    if (typeof navigator !== "undefined" && navigator.language) attrs.locale = navigator.language;
+  } catch {
+  }
+  try {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    if (tz) attrs.timezone = tz;
+  } catch {
+  }
+  try {
+    if (document.referrer) attrs.referrer = document.referrer;
+  } catch {
+  }
+  try {
+    attrs.path = window.location.pathname;
+  } catch {
+  }
+  try {
+    if (window.screen) {
+      attrs.screen_width = window.screen.width;
+      attrs.screen_height = window.screen.height;
+    }
+  } catch {
+  }
+  try {
+    if (typeof navigator !== "undefined" && typeof navigator.userAgent === "string") {
+      attrs.user_agent = navigator.userAgent;
+    }
+  } catch {
+  }
+  return attrs;
+}
+function readExperimentOverridesFromUrl() {
+  if (typeof window === "undefined") return {};
+  const out = {};
+  try {
+    const params = new URLSearchParams(window.location.search);
+    for (const [k, v] of params) {
+      if (!v || v === "default" || v === "none") continue;
+      if (k.startsWith("se_exp_")) out[k.slice("se_exp_".length)] = v;
+      else if (k.startsWith("se-exp-")) out[k.slice("se-exp-".length)] = v;
+    }
+  } catch {
+  }
+  return out;
+}
 var FlagsClientBrowser = class {
   sdkKey;
   baseUrl;
   autoGuardrails;
+  env;
   evalResult = null;
   anonId;
   userId = "";
   buffer;
   guardrailsInstalled = false;
+  listeners = /* @__PURE__ */ new Set();
+  overrideListenerInstalled = false;
+  onOverrideChange = () => {
+    this.installBridge();
+    this.notify();
+  };
   constructor(opts) {
     this.sdkKey = opts.sdkKey;
     this.baseUrl = (opts.baseUrl ?? "https://edge.shipeasy.dev").replace(/\/$/, "");
+    this.env = opts.env ?? "prod";
     this.autoGuardrails = opts.autoGuardrails !== false;
     this.anonId = getOrCreateAnonId();
     this.buffer = new EventBuffer(`${this.baseUrl}/collect`, this.sdkKey);
@@ -234,10 +375,18 @@ var FlagsClientBrowser = class {
     if (this.anonId && this.userId && this.userId !== prevUserId) {
       await this.buffer.alias(this.anonId, this.userId);
     }
-    const res = await fetch(`${this.baseUrl}/sdk/evaluate`, {
+    const userPayload = {
+      ...collectBrowserAttrs(),
+      anonymous_id: this.anonId,
+      ...user
+    };
+    const res = await fetch(`${this.baseUrl}/sdk/evaluate?env=${this.env}`, {
       method: "POST",
       headers: { "X-SDK-Key": this.sdkKey, "Content-Type": "application/json" },
-      body: JSON.stringify({ user })
+      body: JSON.stringify({
+        user: userPayload,
+        experiment_overrides: readExperimentOverridesFromUrl()
+      })
     });
     if (!res.ok) throw new Error(`/sdk/evaluate returned ${res.status}`);
     this.evalResult = await res.json();
@@ -245,26 +394,54 @@ var FlagsClientBrowser = class {
       this.guardrailsInstalled = true;
       installAutoGuardrails(this.buffer, this.userId, this.anonId);
     }
+    this.notify();
+  }
+  get ready() {
+    return this.evalResult !== null;
+  }
+  notify() {
+    for (const l of this.listeners) {
+      try {
+        l();
+      } catch (err) {
+        console.warn("[shipeasy] subscriber threw:", String(err));
+      }
+    }
   }
   initFromBootstrap(data) {
     this.evalResult = data;
   }
   getFlag(name) {
-    return this.evalResult?.flags[name]?.enabled ?? false;
+    const ov = readGateOverride(name);
+    if (ov !== null) return ov;
+    return this.evalResult?.flags[name] ?? false;
   }
   getConfig(name, decode) {
-    void name;
-    void decode;
-    return void 0;
+    const ov = readConfigOverride(name);
+    const raw = ov !== void 0 ? ov : this.evalResult?.configs?.[name];
+    if (raw === void 0) return void 0;
+    if (!decode) return raw;
+    try {
+      return decode(raw);
+    } catch (err) {
+      console.warn(`[shipeasy] getConfig('${name}') decode failed:`, String(err));
+      return void 0;
+    }
   }
-  getExperiment(name, defaultParams, decode) {
+  getExperiment(name, defaultParams, decode, variants) {
     const notIn = {
       inExperiment: false,
       group: "control",
       params: defaultParams
     };
+    const ov = readExpOverride(name);
+    if (ov !== null) {
+      const variantParams = variants?.[ov];
+      const params = variantParams ? { ...defaultParams, ...variantParams } : defaultParams;
+      return { inExperiment: true, group: ov, params };
+    }
     const entry = this.evalResult?.experiments[name];
-    if (!entry || !entry.in_experiment) return notIn;
+    if (!entry || !entry.inExperiment) return notIn;
     this.buffer.pushExposure(name, entry.group, this.userId, this.anonId);
     if (!decode) return { inExperiment: true, group: entry.group, params: entry.params };
     try {
@@ -274,6 +451,39 @@ var FlagsClientBrowser = class {
       return notIn;
     }
   }
+  /**
+   * Subscribe to state changes — fires after identify() completes and on
+   * `se:override:change` events from the devtools overlay. Returns an
+   * unsubscribe function. Used by framework adapters to trigger re-renders.
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    if (!this.overrideListenerInstalled && typeof window !== "undefined") {
+      this.overrideListenerInstalled = true;
+      window.addEventListener("se:override:change", this.onOverrideChange);
+    }
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * Publishes the SDK to `window.__shipeasy` so the devtools overlay can read
+   * current values. Idempotent. Returns the bridge object for tests.
+   */
+  installBridge() {
+    if (typeof window === "undefined") return null;
+    const bridge = {
+      getFlag: (n) => this.getFlag(n),
+      getExperiment: (n) => {
+        const r = this.getExperiment(n, {});
+        return { inExperiment: r.inExperiment, group: r.group };
+      },
+      getConfig: (n) => this.getConfig(n)
+    };
+    window.__shipeasy = bridge;
+    window.dispatchEvent(new CustomEvent("se:state:update"));
+    return bridge;
+  }
   track(eventName, props) {
     this.buffer.pushMetric(eventName, this.userId, this.anonId, props);
   }
@@ -283,9 +493,266 @@ var FlagsClientBrowser = class {
   destroy() {
     this.buffer.flush();
     this.buffer.destroy();
+    this.listeners.clear();
+    if (this.overrideListenerInstalled && typeof window !== "undefined") {
+      window.removeEventListener("se:override:change", this.onOverrideChange);
+      this.overrideListenerInstalled = false;
+    }
+  }
+};
+var TRUE_RX = /^(true|on|1|yes)$/i;
+var FALSE_RX = /^(false|off|0|no)$/i;
+function parseBool(raw) {
+  if (TRUE_RX.test(raw)) return true;
+  if (FALSE_RX.test(raw)) return false;
+  return null;
+}
+function decodeConfigValue(raw) {
+  if (raw.startsWith("b64:")) {
+    try {
+      const json = atob(raw.slice(4).replace(/-/g, "+").replace(/_/g, "/"));
+      return JSON.parse(json);
+    } catch {
+      return raw;
+    }
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+function readParam(canonical, legacy) {
+  if (typeof window === "undefined" || !window.location) return null;
+  const params = new URLSearchParams(window.location.search);
+  const direct = params.get(canonical);
+  if (direct !== null) return direct;
+  if (legacy) {
+    const legacyVal = params.get(legacy);
+    if (legacyVal !== null) return legacyVal;
+  }
+  return null;
+}
+function readGateOverride(name) {
+  const v = readParam(`se_ks_${name}`) ?? readParam(`se_gate_${name}`) ?? readParam(`se-gate-${name}`);
+  return v === null ? null : parseBool(v);
+}
+function readConfigOverride(name) {
+  const v = readParam(`se_config_${name}`, `se-config-${name}`);
+  if (v === null) return void 0;
+  return decodeConfigValue(v);
+}
+function readExpOverride(name) {
+  const v = readParam(`se_exp_${name}`, `se-exp-${name}`);
+  if (v === null || v === "" || v === "default" || v === "none") return null;
+  return v;
+}
+function isDevtoolsRequested() {
+  if (typeof window === "undefined" || !window.location) return false;
+  const p = new URLSearchParams(window.location.search);
+  return p.has("se") || p.has("se_devtools") || p.has("se-devtools");
+}
+function loadDevtools(opts = {}) {
+  if (typeof window === "undefined") return;
+  const wGlobal = window;
+  const mod = wGlobal.__shipeasy_devtools_global;
+  if (!mod) return;
+  mod.init(opts);
+  const w = window;
+  if (!w.__shipeasy_devtools) {
+    let visible = true;
+    w.__shipeasy_devtools = {
+      toggle() {
+        if (visible) {
+          mod.destroy();
+          visible = false;
+        } else {
+          mod.init(opts);
+          visible = true;
+        }
+      }
+    };
+  }
+}
+function attachDevtools(client, opts = {}) {
+  if (typeof window === "undefined") return () => {
+  };
+  const hotkey = opts.hotkey ?? "Shift+Alt+S";
+  const parts = hotkey.split("+");
+  const key = parts[parts.length - 1];
+  const shift = parts.includes("Shift");
+  const alt = parts.includes("Alt");
+  const ctrl = parts.includes("Ctrl") || parts.includes("Control");
+  const meta = parts.includes("Meta") || parts.includes("Cmd");
+  client.installBridge();
+  if (isDevtoolsRequested()) loadDevtools({ adminUrl: opts.adminUrl, edgeUrl: opts.edgeUrl });
+  let loaded = isDevtoolsRequested();
+  function onKeyDown(e) {
+    if (e.key === key && e.shiftKey === shift && e.altKey === alt && e.ctrlKey === ctrl && e.metaKey === meta) {
+      if (!loaded) {
+        loaded = true;
+        loadDevtools({ adminUrl: opts.adminUrl, edgeUrl: opts.edgeUrl });
+      } else {
+        window.__shipeasy_devtools?.toggle();
+      }
+    }
+  }
+  window.addEventListener("keydown", onKeyDown);
+  const unsubBridge = client.subscribe(() => client.installBridge());
+  return () => {
+    window.removeEventListener("keydown", onKeyDown);
+    unsubBridge();
+  };
+}
+var _client = null;
+function configureShipeasy(opts) {
+  if (_client) return _client;
+  _client = new FlagsClientBrowser(opts);
+  return _client;
+}
+function getShipeasyClient() {
+  return _client;
+}
+function _resetShipeasyForTests() {
+  _client?.destroy();
+  _client = null;
+}
+var flags = {
+  configure(opts) {
+    configureShipeasy(opts);
+  },
+  identify(user) {
+    if (!_client) {
+      console.warn("[shipeasy] flags.identify called before configureShipeasy()");
+      return Promise.resolve();
+    }
+    return _client.identify(user);
+  },
+  /** Read a feature gate. Returns false until identify() resolves. */
+  get(name) {
+    return _client?.getFlag(name) ?? false;
+  },
+  getConfig(name, decode) {
+    return _client?.getConfig(name, decode);
+  },
+  getExperiment(name, defaultParams, decode, variants) {
+    return _client?.getExperiment(name, defaultParams, decode, variants) ?? {
+      inExperiment: false,
+      group: "control",
+      params: defaultParams
+    };
+  },
+  track(eventName, props) {
+    _client?.track(eventName, props);
+  },
+  flush() {
+    return _client?.flush() ?? Promise.resolve();
+  },
+  /** Subscribe for change notifications (identify/override). Used by framework adapters. */
+  subscribe(listener) {
+    if (!_client) return () => {
+    };
+    return _client.subscribe(listener);
+  },
+  /** True once identify() has completed and flags are available. */
+  get ready() {
+    return _client?.ready ?? false;
+  }
+};
+var LABEL_MARKER_START = "\uFFF9";
+var LABEL_MARKER_SEP = "\uFFFA";
+var LABEL_MARKER_END = "\uFFFB";
+var LABEL_MARKER_RE = /([^]+)([^]*)/g;
+function encodeLabelMarker(key, value) {
+  return `${LABEL_MARKER_START}${key}${LABEL_MARKER_SEP}${value}${LABEL_MARKER_END}`;
+}
+function labelAttrs(key, variables, desc) {
+  const attrs = { "data-label": key };
+  if (variables) attrs["data-variables"] = JSON.stringify(variables);
+  if (desc) attrs["data-label-desc"] = desc;
+  return attrs;
+}
+var _createElement = null;
+var i18n = {
+  t(key, variables) {
+    if (typeof window !== "undefined" && window.i18n) return window.i18n.t(key, variables);
+    return key;
+  },
+  /**
+   * Translate a key and return a framework element (e.g. React <span>)
+   * carrying `data-label` / `data-variables` attributes so the ShipEasy
+   * devtools "Edit labels" overlay can highlight and edit it in place.
+   *
+   * Requires a one-time setup call: `i18n.configure({ createElement })`.
+   * The returned value is whatever `createElement` returns — pass React's
+   * `createElement`, Vue's `h`, Solid's `createSignal`-based factory, etc.
+   *
+   * Falls back to a plain translated string if `createElement` was not
+   * configured (e.g. server-side or in non-JSX contexts).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  tEl(key, variables, desc) {
+    const text = this.t(key, variables);
+    if (!_createElement) return text;
+    return _createElement("span", labelAttrs(key, variables, desc), text);
+  },
+  /** Wire up the element creator once at app startup (call before any tEl use). */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  configure(opts) {
+    _createElement = opts.createElement;
+  },
+  get locale() {
+    if (typeof window !== "undefined" && window.i18n) return window.i18n.locale;
+    return null;
+  },
+  get ready() {
+    if (typeof window !== "undefined" && window.i18n) return Boolean(window.i18n.locale);
+    return false;
+  },
+  /** Resolves when the loader has installed window.i18n and fetched a profile. */
+  whenReady() {
+    if (typeof window === "undefined") return Promise.resolve();
+    if (window.i18n?.locale) return Promise.resolve();
+    return new Promise((resolve) => {
+      const handler = () => resolve();
+      window.addEventListener("se:i18n:ready", handler, { once: true });
+    });
+  },
+  /** Subscribe to locale/profile updates. Returns an unsubscribe fn. */
+  onUpdate(cb) {
+    if (typeof window === "undefined") return () => {
+    };
+    if (window.i18n) return window.i18n.on("update", cb);
+    let unsub = () => {
+    };
+    const handler = () => {
+      if (window.i18n) unsub = window.i18n.on("update", cb);
+    };
+    window.addEventListener("se:i18n:ready", handler, { once: true });
+    return () => {
+      window.removeEventListener("se:i18n:ready", handler);
+      unsub();
+    };
   }
 };
 export {
   FlagsClientBrowser,
+  LABEL_MARKER_END,
+  LABEL_MARKER_RE,
+  LABEL_MARKER_SEP,
+  LABEL_MARKER_START,
+  _resetShipeasyForTests,
+  attachDevtools,
+  configureShipeasy,
+  encodeLabelMarker,
+  flags,
+  getShipeasyClient,
+  i18n,
+  isDevtoolsRequested,
+  labelAttrs,
+  loadDevtools,
+  readConfigOverride,
+  readExpOverride,
+  readGateOverride,
   version
 };

package/dist/server/index.d.mts

@@ -9,13 +9,17 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
+type FlagsClientEnv = "dev" | "staging" | "prod";
 interface FlagsClientOptions {
     apiKey: string;
     baseUrl?: string;
+    /** Which published env to read values from. Defaults to "prod". */
+    env?: FlagsClientEnv;
 }
 declare class FlagsClient {
     private readonly apiKey;
     private readonly baseUrl;
+    private readonly env;
     private flagsBlob;
     private expsBlob;
     private flagsEtag;
@@ -36,5 +40,38 @@ declare class FlagsClient {
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
 }
+interface LabelFile {
+    v: number;
+    profile: string;
+    chunk: string;
+    strings: Record<string, string>;
+}
+interface FetchLabelsOptions {
+    key: string;
+    profile: string;
+    chunk?: string;
+    cdnBaseUrl?: string;
+    timeoutMs?: number;
+}
+declare function fetchLabelsForSSR(opts: FetchLabelsOptions): Promise<LabelFile | null>;
+declare function configureShipeasyServer(opts: FlagsClientOptions): FlagsClient;
+declare function getShipeasyServerClient(): FlagsClient | null;
+declare function _resetShipeasyServerForTests(): void;
+declare const flags: {
+    configure(opts: FlagsClientOptions): void;
+    /**
+     * Long-running server: starts the background poll. Call once at app boot.
+     * Throws if the initial fetch fails (caller decides whether to crash or degrade).
+     */
+    init(): Promise<void>;
+    /** Serverless / edge: fetch rules once, no background timer. */
+    initOnce(): Promise<void>;
+    /** Stop background timers. Safe to call repeatedly. */
+    destroy(): void;
+    get(name: string, user: User): boolean;
+    getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
+    getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
+    track(userId: string, eventName: string, props?: Record<string, unknown>): void;
+};
 
-export { type ExperimentResult, FlagsClient, type FlagsClientOptions, type User, version };
+export { type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type LabelFile, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getShipeasyServerClient, version };