@shipeasy/sdk 1.0.0

package/dist/client/index.d.mts

@@ -0,0 +1,48 @@
+declare const version = "1.0.0";
+interface User {
+    user_id?: string;
+    [attr: string]: unknown;
+}
+interface ExperimentResult<P> {
+    inExperiment: boolean;
+    group: string;
+    params: P;
+}
+interface EvalFlagResult {
+    enabled: boolean;
+}
+interface EvalExpResult {
+    in_experiment: boolean;
+    group: string;
+    params: Record<string, unknown>;
+}
+interface EvalResponse {
+    flags: Record<string, EvalFlagResult>;
+    experiments: Record<string, EvalExpResult>;
+}
+interface FlagsClientBrowserOptions {
+    sdkKey: string;
+    baseUrl?: string;
+    autoGuardrails?: boolean;
+}
+declare class FlagsClientBrowser {
+    private readonly sdkKey;
+    private readonly baseUrl;
+    private readonly autoGuardrails;
+    private evalResult;
+    private anonId;
+    private userId;
+    private buffer;
+    private guardrailsInstalled;
+    constructor(opts: FlagsClientBrowserOptions);
+    identify(user: User): Promise<void>;
+    initFromBootstrap(data: EvalResponse): void;
+    getFlag(name: string): boolean;
+    getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
+    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
+    track(eventName: string, props?: Record<string, unknown>): void;
+    flush(): Promise<void>;
+    destroy(): void;
+}
+
+export { type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserOptions, type User, version };

package/dist/client/index.d.ts

@@ -0,0 +1,48 @@
+declare const version = "1.0.0";
+interface User {
+    user_id?: string;
+    [attr: string]: unknown;
+}
+interface ExperimentResult<P> {
+    inExperiment: boolean;
+    group: string;
+    params: P;
+}
+interface EvalFlagResult {
+    enabled: boolean;
+}
+interface EvalExpResult {
+    in_experiment: boolean;
+    group: string;
+    params: Record<string, unknown>;
+}
+interface EvalResponse {
+    flags: Record<string, EvalFlagResult>;
+    experiments: Record<string, EvalExpResult>;
+}
+interface FlagsClientBrowserOptions {
+    sdkKey: string;
+    baseUrl?: string;
+    autoGuardrails?: boolean;
+}
+declare class FlagsClientBrowser {
+    private readonly sdkKey;
+    private readonly baseUrl;
+    private readonly autoGuardrails;
+    private evalResult;
+    private anonId;
+    private userId;
+    private buffer;
+    private guardrailsInstalled;
+    constructor(opts: FlagsClientBrowserOptions);
+    identify(user: User): Promise<void>;
+    initFromBootstrap(data: EvalResponse): void;
+    getFlag(name: string): boolean;
+    getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
+    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
+    track(eventName: string, props?: Record<string, unknown>): void;
+    flush(): Promise<void>;
+    destroy(): void;
+}
+
+export { type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserOptions, type User, version };

package/dist/client/index.js

@@ -0,0 +1,317 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client/index.ts
+var client_exports = {};
+__export(client_exports, {
+  FlagsClientBrowser: () => FlagsClientBrowser,
+  version: () => version
+});
+module.exports = __toCommonJS(client_exports);
+var version = "1.0.0";
+var FLUSH_INTERVAL_MS = 5e3;
+var MAX_BUFFER = 100;
+var ANON_ID_KEY = "__se_anon_id";
+var SEEN_KEY = "__se_seen";
+var PENDING_ALIAS_KEY = "__se_pending_alias";
+var EventBuffer = class {
+  constructor(collectUrl, sdkKey) {
+    this.collectUrl = collectUrl;
+    this.sdkKey = sdkKey;
+    if (typeof window !== "undefined") {
+      this.timer = setInterval(() => this.flush(), FLUSH_INTERVAL_MS);
+      window.addEventListener("beforeunload", () => this.flush());
+      document.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "hidden") this.flush(true);
+      });
+      try {
+        const stored = sessionStorage.getItem(SEEN_KEY);
+        if (stored) this.exposureSeen = new Set(JSON.parse(stored));
+      } catch {
+      }
+    }
+  }
+  collectUrl;
+  sdkKey;
+  queue = [];
+  exposureSeen = /* @__PURE__ */ new Set();
+  timer = null;
+  destroy() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  pushExposure(experiment, group, userId, anonId) {
+    const key = `${userId || anonId}:${experiment}`;
+    if (this.exposureSeen.has(key)) return;
+    this.exposureSeen.add(key);
+    try {
+      sessionStorage.setItem(SEEN_KEY, JSON.stringify([...this.exposureSeen]));
+    } catch {
+    }
+    this.enqueue({
+      type: "exposure",
+      experiment,
+      group,
+      user_id: userId,
+      anonymous_id: anonId,
+      ts: Date.now()
+    });
+  }
+  pushMetric(eventName, userId, anonId, props) {
+    this.enqueue({
+      type: "metric",
+      event_name: eventName,
+      user_id: userId,
+      anonymous_id: anonId,
+      ts: Date.now(),
+      ...props ? { properties: props } : {}
+    });
+  }
+  async alias(anonymousId, userId) {
+    const record = { anonymousId, userId, ts: Date.now() };
+    try {
+      localStorage.setItem(PENDING_ALIAS_KEY, JSON.stringify(record));
+    } catch {
+    }
+    await this.flushAsync();
+    await this._sendAlias(anonymousId, userId);
+    try {
+      localStorage.removeItem(PENDING_ALIAS_KEY);
+    } catch {
+    }
+  }
+  async flushPendingAlias() {
+    try {
+      const raw = localStorage.getItem(PENDING_ALIAS_KEY);
+      if (!raw) return;
+      const record = JSON.parse(raw);
+      if (Date.now() - record.ts > 7 * 864e5) {
+        localStorage.removeItem(PENDING_ALIAS_KEY);
+        return;
+      }
+      await this._sendAlias(record.anonymousId, record.userId);
+      localStorage.removeItem(PENDING_ALIAS_KEY);
+    } catch {
+    }
+  }
+  async _sendAlias(anonymousId, userId) {
+    this.enqueue({ type: "identify", anonymous_id: anonymousId, user_id: userId, ts: Date.now() });
+    await this.flushAsync();
+  }
+  enqueue(ev) {
+    this.queue.push(ev);
+    if (this.queue.length >= MAX_BUFFER) this.flush();
+  }
+  flush(useBeacon = false) {
+    if (!this.queue.length) return;
+    const batch = this.queue.splice(0);
+    const body = JSON.stringify({ events: batch });
+    if (useBeacon && typeof navigator !== "undefined" && navigator.sendBeacon) {
+      navigator.sendBeacon(this.collectUrl, new Blob([body], { type: "text/plain" }));
+      return;
+    }
+    fetch(this.collectUrl, {
+      method: "POST",
+      headers: { "X-SDK-Key": this.sdkKey, "Content-Type": "application/json" },
+      body,
+      keepalive: true
+    }).catch(() => {
+    });
+  }
+  async flushAsync() {
+    if (!this.queue.length) return;
+    const batch = this.queue.splice(0);
+    const body = JSON.stringify({ events: batch });
+    await fetch(this.collectUrl, {
+      method: "POST",
+      headers: { "X-SDK-Key": this.sdkKey, "Content-Type": "application/json" },
+      body
+    }).catch(() => {
+    });
+  }
+};
+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;
+  try {
+    const lcpObs = new PerformanceObserver((list) => {
+      const entries = list.getEntries();
+      if (entries.length)
+        lcp = entries[entries.length - 1].startTime;
+    });
+    lcpObs.observe({ type: "largest-contentful-paint", buffered: true });
+  } catch {
+  }
+  try {
+    const inpObs = new PerformanceObserver((list) => {
+      for (const e of list.getEntries()) {
+        const dur = e.duration ?? 0;
+        if (inp === null || dur > inp) inp = dur;
+      }
+    });
+    inpObs.observe({
+      type: "event",
+      buffered: true,
+      durationThreshold: 16
+    });
+  } catch {
+  }
+  try {
+    const clsObs = new PerformanceObserver((list) => {
+      for (const e of list.getEntries()) {
+        if (e.value > 0.1) clsBad = true;
+      }
+    });
+    clsObs.observe({ type: "layout-shift", buffered: true });
+  } catch {
+  }
+  const origOnError = window.onerror;
+  window.onerror = (...args) => {
+    if (!jsError) {
+      jsError = true;
+      buffer.pushMetric("__auto_js_error", userId, anonId, { value: 1 });
+    }
+    if (typeof origOnError === "function") return origOnError(...args);
+    return false;
+  };
+  window.addEventListener("unhandledrejection", () => {
+    if (!jsError) {
+      jsError = true;
+      buffer.pushMetric("__auto_js_error", userId, anonId, { value: 1 });
+    }
+  });
+  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 });
+    }
+    return res;
+  };
+  const flush = () => {
+    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 });
+    const abandoned = lcp === null ? 1 : 0;
+    buffer.pushMetric("__auto_abandoned", userId, anonId, { value: abandoned });
+    buffer.flush(true);
+  };
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "hidden") flush();
+  });
+}
+function getOrCreateAnonId() {
+  try {
+    const stored = localStorage.getItem(ANON_ID_KEY);
+    if (stored) return stored;
+  } catch {
+  }
+  const id = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `anon_${Math.random().toString(36).slice(2)}`;
+  try {
+    localStorage.setItem(ANON_ID_KEY, id);
+  } catch {
+  }
+  return id;
+}
+var FlagsClientBrowser = class {
+  sdkKey;
+  baseUrl;
+  autoGuardrails;
+  evalResult = null;
+  anonId;
+  userId = "";
+  buffer;
+  guardrailsInstalled = false;
+  constructor(opts) {
+    this.sdkKey = opts.sdkKey;
+    this.baseUrl = (opts.baseUrl ?? "https://edge.shipeasy.dev").replace(/\/$/, "");
+    this.autoGuardrails = opts.autoGuardrails !== false;
+    this.anonId = getOrCreateAnonId();
+    this.buffer = new EventBuffer(`${this.baseUrl}/collect`, this.sdkKey);
+    void this.buffer.flushPendingAlias();
+  }
+  async identify(user) {
+    const prevUserId = this.userId;
+    this.userId = user.user_id ?? "";
+    if (this.anonId && this.userId && this.userId !== prevUserId) {
+      await this.buffer.alias(this.anonId, this.userId);
+    }
+    const res = await fetch(`${this.baseUrl}/sdk/evaluate`, {
+      method: "POST",
+      headers: { "X-SDK-Key": this.sdkKey, "Content-Type": "application/json" },
+      body: JSON.stringify({ user })
+    });
+    if (!res.ok) throw new Error(`/sdk/evaluate returned ${res.status}`);
+    this.evalResult = await res.json();
+    if (this.autoGuardrails && !this.guardrailsInstalled) {
+      this.guardrailsInstalled = true;
+      installAutoGuardrails(this.buffer, this.userId, this.anonId);
+    }
+  }
+  initFromBootstrap(data) {
+    this.evalResult = data;
+  }
+  getFlag(name) {
+    return this.evalResult?.flags[name]?.enabled ?? false;
+  }
+  getConfig(name, decode) {
+    void name;
+    void decode;
+    return void 0;
+  }
+  getExperiment(name, defaultParams, decode) {
+    const notIn = {
+      inExperiment: false,
+      group: "control",
+      params: defaultParams
+    };
+    const entry = this.evalResult?.experiments[name];
+    if (!entry || !entry.in_experiment) return notIn;
+    this.buffer.pushExposure(name, entry.group, this.userId, this.anonId);
+    if (!decode) return { inExperiment: true, group: entry.group, params: entry.params };
+    try {
+      return { inExperiment: true, group: entry.group, params: decode(entry.params) };
+    } catch (err) {
+      console.warn(`[shipeasy] getExperiment('${name}') decode failed:`, String(err));
+      return notIn;
+    }
+  }
+  track(eventName, props) {
+    this.buffer.pushMetric(eventName, this.userId, this.anonId, props);
+  }
+  async flush() {
+    await this.buffer.flushAsync();
+  }
+  destroy() {
+    this.buffer.flush();
+    this.buffer.destroy();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FlagsClientBrowser,
+  version
+});

package/dist/client/index.mjs

@@ -0,0 +1,291 @@
+// src/client/index.ts
+var version = "1.0.0";
+var FLUSH_INTERVAL_MS = 5e3;
+var MAX_BUFFER = 100;
+var ANON_ID_KEY = "__se_anon_id";
+var SEEN_KEY = "__se_seen";
+var PENDING_ALIAS_KEY = "__se_pending_alias";
+var EventBuffer = class {
+  constructor(collectUrl, sdkKey) {
+    this.collectUrl = collectUrl;
+    this.sdkKey = sdkKey;
+    if (typeof window !== "undefined") {
+      this.timer = setInterval(() => this.flush(), FLUSH_INTERVAL_MS);
+      window.addEventListener("beforeunload", () => this.flush());
+      document.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "hidden") this.flush(true);
+      });
+      try {
+        const stored = sessionStorage.getItem(SEEN_KEY);
+        if (stored) this.exposureSeen = new Set(JSON.parse(stored));
+      } catch {
+      }
+    }
+  }
+  collectUrl;
+  sdkKey;
+  queue = [];
+  exposureSeen = /* @__PURE__ */ new Set();
+  timer = null;
+  destroy() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  pushExposure(experiment, group, userId, anonId) {
+    const key = `${userId || anonId}:${experiment}`;
+    if (this.exposureSeen.has(key)) return;
+    this.exposureSeen.add(key);
+    try {
+      sessionStorage.setItem(SEEN_KEY, JSON.stringify([...this.exposureSeen]));
+    } catch {
+    }
+    this.enqueue({
+      type: "exposure",
+      experiment,
+      group,
+      user_id: userId,
+      anonymous_id: anonId,
+      ts: Date.now()
+    });
+  }
+  pushMetric(eventName, userId, anonId, props) {
+    this.enqueue({
+      type: "metric",
+      event_name: eventName,
+      user_id: userId,
+      anonymous_id: anonId,
+      ts: Date.now(),
+      ...props ? { properties: props } : {}
+    });
+  }
+  async alias(anonymousId, userId) {
+    const record = { anonymousId, userId, ts: Date.now() };
+    try {
+      localStorage.setItem(PENDING_ALIAS_KEY, JSON.stringify(record));
+    } catch {
+    }
+    await this.flushAsync();
+    await this._sendAlias(anonymousId, userId);
+    try {
+      localStorage.removeItem(PENDING_ALIAS_KEY);
+    } catch {
+    }
+  }
+  async flushPendingAlias() {
+    try {
+      const raw = localStorage.getItem(PENDING_ALIAS_KEY);
+      if (!raw) return;
+      const record = JSON.parse(raw);
+      if (Date.now() - record.ts > 7 * 864e5) {
+        localStorage.removeItem(PENDING_ALIAS_KEY);
+        return;
+      }
+      await this._sendAlias(record.anonymousId, record.userId);
+      localStorage.removeItem(PENDING_ALIAS_KEY);
+    } catch {
+    }
+  }
+  async _sendAlias(anonymousId, userId) {
+    this.enqueue({ type: "identify", anonymous_id: anonymousId, user_id: userId, ts: Date.now() });
+    await this.flushAsync();
+  }
+  enqueue(ev) {
+    this.queue.push(ev);
+    if (this.queue.length >= MAX_BUFFER) this.flush();
+  }
+  flush(useBeacon = false) {
+    if (!this.queue.length) return;
+    const batch = this.queue.splice(0);
+    const body = JSON.stringify({ events: batch });
+    if (useBeacon && typeof navigator !== "undefined" && navigator.sendBeacon) {
+      navigator.sendBeacon(this.collectUrl, new Blob([body], { type: "text/plain" }));
+      return;
+    }
+    fetch(this.collectUrl, {
+      method: "POST",
+      headers: { "X-SDK-Key": this.sdkKey, "Content-Type": "application/json" },
+      body,
+      keepalive: true
+    }).catch(() => {
+    });
+  }
+  async flushAsync() {
+    if (!this.queue.length) return;
+    const batch = this.queue.splice(0);
+    const body = JSON.stringify({ events: batch });
+    await fetch(this.collectUrl, {
+      method: "POST",
+      headers: { "X-SDK-Key": this.sdkKey, "Content-Type": "application/json" },
+      body
+    }).catch(() => {
+    });
+  }
+};
+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;
+  try {
+    const lcpObs = new PerformanceObserver((list) => {
+      const entries = list.getEntries();
+      if (entries.length)
+        lcp = entries[entries.length - 1].startTime;
+    });
+    lcpObs.observe({ type: "largest-contentful-paint", buffered: true });
+  } catch {
+  }
+  try {
+    const inpObs = new PerformanceObserver((list) => {
+      for (const e of list.getEntries()) {
+        const dur = e.duration ?? 0;
+        if (inp === null || dur > inp) inp = dur;
+      }
+    });
+    inpObs.observe({
+      type: "event",
+      buffered: true,
+      durationThreshold: 16
+    });
+  } catch {
+  }
+  try {
+    const clsObs = new PerformanceObserver((list) => {
+      for (const e of list.getEntries()) {
+        if (e.value > 0.1) clsBad = true;
+      }
+    });
+    clsObs.observe({ type: "layout-shift", buffered: true });
+  } catch {
+  }
+  const origOnError = window.onerror;
+  window.onerror = (...args) => {
+    if (!jsError) {
+      jsError = true;
+      buffer.pushMetric("__auto_js_error", userId, anonId, { value: 1 });
+    }
+    if (typeof origOnError === "function") return origOnError(...args);
+    return false;
+  };
+  window.addEventListener("unhandledrejection", () => {
+    if (!jsError) {
+      jsError = true;
+      buffer.pushMetric("__auto_js_error", userId, anonId, { value: 1 });
+    }
+  });
+  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 });
+    }
+    return res;
+  };
+  const flush = () => {
+    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 });
+    const abandoned = lcp === null ? 1 : 0;
+    buffer.pushMetric("__auto_abandoned", userId, anonId, { value: abandoned });
+    buffer.flush(true);
+  };
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "hidden") flush();
+  });
+}
+function getOrCreateAnonId() {
+  try {
+    const stored = localStorage.getItem(ANON_ID_KEY);
+    if (stored) return stored;
+  } catch {
+  }
+  const id = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `anon_${Math.random().toString(36).slice(2)}`;
+  try {
+    localStorage.setItem(ANON_ID_KEY, id);
+  } catch {
+  }
+  return id;
+}
+var FlagsClientBrowser = class {
+  sdkKey;
+  baseUrl;
+  autoGuardrails;
+  evalResult = null;
+  anonId;
+  userId = "";
+  buffer;
+  guardrailsInstalled = false;
+  constructor(opts) {
+    this.sdkKey = opts.sdkKey;
+    this.baseUrl = (opts.baseUrl ?? "https://edge.shipeasy.dev").replace(/\/$/, "");
+    this.autoGuardrails = opts.autoGuardrails !== false;
+    this.anonId = getOrCreateAnonId();
+    this.buffer = new EventBuffer(`${this.baseUrl}/collect`, this.sdkKey);
+    void this.buffer.flushPendingAlias();
+  }
+  async identify(user) {
+    const prevUserId = this.userId;
+    this.userId = user.user_id ?? "";
+    if (this.anonId && this.userId && this.userId !== prevUserId) {
+      await this.buffer.alias(this.anonId, this.userId);
+    }
+    const res = await fetch(`${this.baseUrl}/sdk/evaluate`, {
+      method: "POST",
+      headers: { "X-SDK-Key": this.sdkKey, "Content-Type": "application/json" },
+      body: JSON.stringify({ user })
+    });
+    if (!res.ok) throw new Error(`/sdk/evaluate returned ${res.status}`);
+    this.evalResult = await res.json();
+    if (this.autoGuardrails && !this.guardrailsInstalled) {
+      this.guardrailsInstalled = true;
+      installAutoGuardrails(this.buffer, this.userId, this.anonId);
+    }
+  }
+  initFromBootstrap(data) {
+    this.evalResult = data;
+  }
+  getFlag(name) {
+    return this.evalResult?.flags[name]?.enabled ?? false;
+  }
+  getConfig(name, decode) {
+    void name;
+    void decode;
+    return void 0;
+  }
+  getExperiment(name, defaultParams, decode) {
+    const notIn = {
+      inExperiment: false,
+      group: "control",
+      params: defaultParams
+    };
+    const entry = this.evalResult?.experiments[name];
+    if (!entry || !entry.in_experiment) return notIn;
+    this.buffer.pushExposure(name, entry.group, this.userId, this.anonId);
+    if (!decode) return { inExperiment: true, group: entry.group, params: entry.params };
+    try {
+      return { inExperiment: true, group: entry.group, params: decode(entry.params) };
+    } catch (err) {
+      console.warn(`[shipeasy] getExperiment('${name}') decode failed:`, String(err));
+      return notIn;
+    }
+  }
+  track(eventName, props) {
+    this.buffer.pushMetric(eventName, this.userId, this.anonId, props);
+  }
+  async flush() {
+    await this.buffer.flushAsync();
+  }
+  destroy() {
+    this.buffer.flush();
+    this.buffer.destroy();
+  }
+};
+export {
+  FlagsClientBrowser,
+  version
+};

package/dist/server/index.d.mts

@@ -0,0 +1,40 @@
+declare const version = "1.0.0";
+interface User {
+    user_id?: string;
+    anonymous_id?: string;
+    [attr: string]: unknown;
+}
+interface ExperimentResult<P> {
+    inExperiment: boolean;
+    group: string;
+    params: P;
+}
+interface FlagsClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+declare class FlagsClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private flagsBlob;
+    private expsBlob;
+    private flagsEtag;
+    private expsEtag;
+    private pollInterval;
+    private timer;
+    private initialized;
+    constructor(opts: FlagsClientOptions);
+    init(): Promise<void>;
+    initOnce(): Promise<void>;
+    destroy(): void;
+    private startPoll;
+    private fetchAll;
+    private fetchFlags;
+    private fetchExps;
+    getFlag(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 };

package/dist/server/index.d.ts

@@ -0,0 +1,40 @@
+declare const version = "1.0.0";
+interface User {
+    user_id?: string;
+    anonymous_id?: string;
+    [attr: string]: unknown;
+}
+interface ExperimentResult<P> {
+    inExperiment: boolean;
+    group: string;
+    params: P;
+}
+interface FlagsClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+declare class FlagsClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private flagsBlob;
+    private expsBlob;
+    private flagsEtag;
+    private expsEtag;
+    private pollInterval;
+    private timer;
+    private initialized;
+    constructor(opts: FlagsClientOptions);
+    init(): Promise<void>;
+    initOnce(): Promise<void>;
+    destroy(): void;
+    private startPoll;
+    private fetchAll;
+    private fetchFlags;
+    private fetchExps;
+    getFlag(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 };

package/dist/server/index.js

@@ -0,0 +1,272 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server/index.ts
+var server_exports = {};
+__export(server_exports, {
+  FlagsClient: () => FlagsClient,
+  version: () => version
+});
+module.exports = __toCommonJS(server_exports);
+var version = "1.0.0";
+var C1 = 3432918353;
+var C2 = 461845907;
+function murmur3(key) {
+  const bytes = new TextEncoder().encode(key);
+  const len = bytes.length;
+  const nblocks = len >>> 2;
+  let h1 = 0;
+  for (let i = 0; i < nblocks; i++) {
+    const off = i * 4;
+    let k12 = bytes[off] | bytes[off + 1] << 8 | bytes[off + 2] << 16 | bytes[off + 3] << 24;
+    k12 = Math.imul(k12, C1);
+    k12 = k12 << 15 | k12 >>> 17;
+    k12 = Math.imul(k12, C2);
+    h1 ^= k12;
+    h1 = h1 << 13 | h1 >>> 19;
+    h1 = Math.imul(h1, 5) + 3864292196;
+    h1 |= 0;
+  }
+  let k1 = 0;
+  const tail = nblocks * 4;
+  switch (len & 3) {
+    case 3:
+      k1 ^= bytes[tail + 2] << 16;
+    // fallthrough
+    case 2:
+      k1 ^= bytes[tail + 1] << 8;
+    // fallthrough
+    case 1:
+      k1 ^= bytes[tail];
+      k1 = Math.imul(k1, C1);
+      k1 = k1 << 15 | k1 >>> 17;
+      k1 = Math.imul(k1, C2);
+      h1 ^= k1;
+  }
+  h1 ^= len;
+  h1 ^= h1 >>> 16;
+  h1 = Math.imul(h1, 2246822507);
+  h1 ^= h1 >>> 13;
+  h1 = Math.imul(h1, 3266489909);
+  h1 ^= h1 >>> 16;
+  return h1 >>> 0;
+}
+function isEnabled(v) {
+  return v === 1 || v === true;
+}
+function toNum(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  if (typeof v === "string" && v !== "" && Number.isFinite(Number(v))) return Number(v);
+  return null;
+}
+function matchRule(rule, user) {
+  const actual = user[rule.attr];
+  switch (rule.op) {
+    case "eq":
+      return actual === rule.value;
+    case "neq":
+      return actual !== rule.value;
+    case "in":
+      return Array.isArray(rule.value) && rule.value.includes(actual);
+    case "not_in":
+      return Array.isArray(rule.value) && !rule.value.includes(actual);
+    case "gt":
+    case "gte":
+    case "lt":
+    case "lte": {
+      const a = toNum(actual);
+      const b = toNum(rule.value);
+      if (a === null || b === null) return false;
+      if (rule.op === "gt") return a > b;
+      if (rule.op === "gte") return a >= b;
+      if (rule.op === "lt") return a < b;
+      return a <= b;
+    }
+    case "contains":
+      if (typeof actual === "string" && typeof rule.value === "string")
+        return actual.includes(rule.value);
+      if (Array.isArray(actual)) return actual.includes(rule.value);
+      return false;
+    case "regex":
+      if (typeof actual !== "string" || typeof rule.value !== "string") return false;
+      try {
+        return new RegExp(rule.value).test(actual);
+      } catch {
+        return false;
+      }
+    default:
+      return false;
+  }
+}
+function evalGateInternal(gate, user) {
+  if (isEnabled(gate.killswitch)) return false;
+  if (!isEnabled(gate.enabled)) return false;
+  for (const rule of gate.rules ?? []) {
+    if (!matchRule(rule, user)) return false;
+  }
+  const uid = user.user_id ?? user.anonymous_id;
+  if (!uid) return false;
+  return murmur3(`${gate.salt}:${uid}`) % 1e4 < gate.rolloutPct;
+}
+var FlagsClient = class {
+  apiKey;
+  baseUrl;
+  flagsBlob = null;
+  expsBlob = null;
+  flagsEtag = null;
+  expsEtag = null;
+  pollInterval = 30;
+  timer = null;
+  initialized = false;
+  constructor(opts) {
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl ?? "https://edge.shipeasy.dev").replace(/\/$/, "");
+  }
+  async init() {
+    await this.fetchAll();
+    this.initialized = true;
+    this.startPoll();
+  }
+  async initOnce() {
+    if (this.initialized) return;
+    await this.fetchAll();
+    this.initialized = true;
+  }
+  destroy() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  startPoll() {
+    this.timer = setInterval(() => {
+      this.fetchAll().catch(
+        (err) => console.warn("[shipeasy] background poll failed:", String(err))
+      );
+    }, this.pollInterval * 1e3);
+  }
+  async fetchAll() {
+    const [interval] = await Promise.all([this.fetchFlags(), this.fetchExps()]);
+    if (interval !== null && interval !== this.pollInterval) {
+      this.pollInterval = interval;
+      if (this.timer !== null) {
+        clearInterval(this.timer);
+        this.startPoll();
+      }
+    }
+  }
+  async fetchFlags() {
+    const headers = { "X-SDK-Key": this.apiKey };
+    if (this.flagsEtag) headers["If-None-Match"] = this.flagsEtag;
+    const res = await globalThis.fetch(`${this.baseUrl}/sdk/flags`, { headers });
+    const interval = Number(res.headers.get("X-Poll-Interval") ?? "30") || 30;
+    if (res.status === 304) return interval;
+    if (!res.ok) throw new Error(`/sdk/flags returned ${res.status}`);
+    const etag = res.headers.get("ETag");
+    if (etag) this.flagsEtag = etag;
+    this.flagsBlob = await res.json();
+    return interval;
+  }
+  async fetchExps() {
+    const headers = { "X-SDK-Key": this.apiKey };
+    if (this.expsEtag) headers["If-None-Match"] = this.expsEtag;
+    const res = await globalThis.fetch(`${this.baseUrl}/sdk/experiments`, { headers });
+    if (res.status === 304) return;
+    if (!res.ok) throw new Error(`/sdk/experiments returned ${res.status}`);
+    const etag = res.headers.get("ETag");
+    if (etag) this.expsEtag = etag;
+    this.expsBlob = await res.json();
+  }
+  getFlag(name, user) {
+    const gate = this.flagsBlob?.gates[name];
+    if (!gate) return false;
+    return evalGateInternal(gate, user);
+  }
+  getConfig(name, decode) {
+    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) {
+    const notIn = {
+      inExperiment: false,
+      group: "control",
+      params: defaultParams
+    };
+    if (!this.flagsBlob || !this.expsBlob) return notIn;
+    const exp = this.expsBlob.experiments[name];
+    if (!exp || exp.status !== "running") return notIn;
+    if (exp.targetingGate) {
+      const gate = this.flagsBlob.gates[exp.targetingGate];
+      if (!gate || !evalGateInternal(gate, user)) return notIn;
+    }
+    const uid = user.user_id ?? user.anonymous_id;
+    if (!uid) return notIn;
+    const universe = this.expsBlob.universes[exp.universe];
+    const holdoutRange = universe?.holdout_range ?? null;
+    if (holdoutRange) {
+      const seg = murmur3(`${exp.universe}:${uid}`) % 1e4;
+      const [lo, hi] = holdoutRange;
+      if (seg >= lo && seg <= hi) return notIn;
+    }
+    if (murmur3(`${exp.salt}:alloc:${uid}`) % 1e4 >= exp.allocationPct) return notIn;
+    const groupHash = murmur3(`${exp.salt}:group:${uid}`) % 1e4;
+    let cumulative = 0;
+    for (let i = 0; i < exp.groups.length; i++) {
+      const g = exp.groups[i];
+      cumulative += g.weight;
+      if (groupHash < cumulative || i === exp.groups.length - 1) {
+        if (!decode) {
+          return { inExperiment: true, group: g.name, params: g.params };
+        }
+        try {
+          return { inExperiment: true, group: g.name, params: decode(g.params) };
+        } catch (err) {
+          console.warn(`[shipeasy] getExperiment('${name}') decode failed:`, String(err));
+          return notIn;
+        }
+      }
+    }
+    return notIn;
+  }
+  track(userId, eventName, props) {
+    const body = JSON.stringify({
+      events: [
+        {
+          type: "metric",
+          event_name: eventName,
+          user_id: userId,
+          ts: Date.now(),
+          ...props !== void 0 ? { properties: props } : {}
+        }
+      ]
+    });
+    globalThis.fetch(`${this.baseUrl}/collect`, {
+      method: "POST",
+      headers: { "X-SDK-Key": this.apiKey, "Content-Type": "text/plain" },
+      body
+    }).catch((err) => console.warn("[shipeasy] track failed:", String(err)));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FlagsClient,
+  version
+});

package/dist/server/index.mjs

@@ -0,0 +1,246 @@
+// src/server/index.ts
+var version = "1.0.0";
+var C1 = 3432918353;
+var C2 = 461845907;
+function murmur3(key) {
+  const bytes = new TextEncoder().encode(key);
+  const len = bytes.length;
+  const nblocks = len >>> 2;
+  let h1 = 0;
+  for (let i = 0; i < nblocks; i++) {
+    const off = i * 4;
+    let k12 = bytes[off] | bytes[off + 1] << 8 | bytes[off + 2] << 16 | bytes[off + 3] << 24;
+    k12 = Math.imul(k12, C1);
+    k12 = k12 << 15 | k12 >>> 17;
+    k12 = Math.imul(k12, C2);
+    h1 ^= k12;
+    h1 = h1 << 13 | h1 >>> 19;
+    h1 = Math.imul(h1, 5) + 3864292196;
+    h1 |= 0;
+  }
+  let k1 = 0;
+  const tail = nblocks * 4;
+  switch (len & 3) {
+    case 3:
+      k1 ^= bytes[tail + 2] << 16;
+    // fallthrough
+    case 2:
+      k1 ^= bytes[tail + 1] << 8;
+    // fallthrough
+    case 1:
+      k1 ^= bytes[tail];
+      k1 = Math.imul(k1, C1);
+      k1 = k1 << 15 | k1 >>> 17;
+      k1 = Math.imul(k1, C2);
+      h1 ^= k1;
+  }
+  h1 ^= len;
+  h1 ^= h1 >>> 16;
+  h1 = Math.imul(h1, 2246822507);
+  h1 ^= h1 >>> 13;
+  h1 = Math.imul(h1, 3266489909);
+  h1 ^= h1 >>> 16;
+  return h1 >>> 0;
+}
+function isEnabled(v) {
+  return v === 1 || v === true;
+}
+function toNum(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  if (typeof v === "string" && v !== "" && Number.isFinite(Number(v))) return Number(v);
+  return null;
+}
+function matchRule(rule, user) {
+  const actual = user[rule.attr];
+  switch (rule.op) {
+    case "eq":
+      return actual === rule.value;
+    case "neq":
+      return actual !== rule.value;
+    case "in":
+      return Array.isArray(rule.value) && rule.value.includes(actual);
+    case "not_in":
+      return Array.isArray(rule.value) && !rule.value.includes(actual);
+    case "gt":
+    case "gte":
+    case "lt":
+    case "lte": {
+      const a = toNum(actual);
+      const b = toNum(rule.value);
+      if (a === null || b === null) return false;
+      if (rule.op === "gt") return a > b;
+      if (rule.op === "gte") return a >= b;
+      if (rule.op === "lt") return a < b;
+      return a <= b;
+    }
+    case "contains":
+      if (typeof actual === "string" && typeof rule.value === "string")
+        return actual.includes(rule.value);
+      if (Array.isArray(actual)) return actual.includes(rule.value);
+      return false;
+    case "regex":
+      if (typeof actual !== "string" || typeof rule.value !== "string") return false;
+      try {
+        return new RegExp(rule.value).test(actual);
+      } catch {
+        return false;
+      }
+    default:
+      return false;
+  }
+}
+function evalGateInternal(gate, user) {
+  if (isEnabled(gate.killswitch)) return false;
+  if (!isEnabled(gate.enabled)) return false;
+  for (const rule of gate.rules ?? []) {
+    if (!matchRule(rule, user)) return false;
+  }
+  const uid = user.user_id ?? user.anonymous_id;
+  if (!uid) return false;
+  return murmur3(`${gate.salt}:${uid}`) % 1e4 < gate.rolloutPct;
+}
+var FlagsClient = class {
+  apiKey;
+  baseUrl;
+  flagsBlob = null;
+  expsBlob = null;
+  flagsEtag = null;
+  expsEtag = null;
+  pollInterval = 30;
+  timer = null;
+  initialized = false;
+  constructor(opts) {
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl ?? "https://edge.shipeasy.dev").replace(/\/$/, "");
+  }
+  async init() {
+    await this.fetchAll();
+    this.initialized = true;
+    this.startPoll();
+  }
+  async initOnce() {
+    if (this.initialized) return;
+    await this.fetchAll();
+    this.initialized = true;
+  }
+  destroy() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  startPoll() {
+    this.timer = setInterval(() => {
+      this.fetchAll().catch(
+        (err) => console.warn("[shipeasy] background poll failed:", String(err))
+      );
+    }, this.pollInterval * 1e3);
+  }
+  async fetchAll() {
+    const [interval] = await Promise.all([this.fetchFlags(), this.fetchExps()]);
+    if (interval !== null && interval !== this.pollInterval) {
+      this.pollInterval = interval;
+      if (this.timer !== null) {
+        clearInterval(this.timer);
+        this.startPoll();
+      }
+    }
+  }
+  async fetchFlags() {
+    const headers = { "X-SDK-Key": this.apiKey };
+    if (this.flagsEtag) headers["If-None-Match"] = this.flagsEtag;
+    const res = await globalThis.fetch(`${this.baseUrl}/sdk/flags`, { headers });
+    const interval = Number(res.headers.get("X-Poll-Interval") ?? "30") || 30;
+    if (res.status === 304) return interval;
+    if (!res.ok) throw new Error(`/sdk/flags returned ${res.status}`);
+    const etag = res.headers.get("ETag");
+    if (etag) this.flagsEtag = etag;
+    this.flagsBlob = await res.json();
+    return interval;
+  }
+  async fetchExps() {
+    const headers = { "X-SDK-Key": this.apiKey };
+    if (this.expsEtag) headers["If-None-Match"] = this.expsEtag;
+    const res = await globalThis.fetch(`${this.baseUrl}/sdk/experiments`, { headers });
+    if (res.status === 304) return;
+    if (!res.ok) throw new Error(`/sdk/experiments returned ${res.status}`);
+    const etag = res.headers.get("ETag");
+    if (etag) this.expsEtag = etag;
+    this.expsBlob = await res.json();
+  }
+  getFlag(name, user) {
+    const gate = this.flagsBlob?.gates[name];
+    if (!gate) return false;
+    return evalGateInternal(gate, user);
+  }
+  getConfig(name, decode) {
+    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) {
+    const notIn = {
+      inExperiment: false,
+      group: "control",
+      params: defaultParams
+    };
+    if (!this.flagsBlob || !this.expsBlob) return notIn;
+    const exp = this.expsBlob.experiments[name];
+    if (!exp || exp.status !== "running") return notIn;
+    if (exp.targetingGate) {
+      const gate = this.flagsBlob.gates[exp.targetingGate];
+      if (!gate || !evalGateInternal(gate, user)) return notIn;
+    }
+    const uid = user.user_id ?? user.anonymous_id;
+    if (!uid) return notIn;
+    const universe = this.expsBlob.universes[exp.universe];
+    const holdoutRange = universe?.holdout_range ?? null;
+    if (holdoutRange) {
+      const seg = murmur3(`${exp.universe}:${uid}`) % 1e4;
+      const [lo, hi] = holdoutRange;
+      if (seg >= lo && seg <= hi) return notIn;
+    }
+    if (murmur3(`${exp.salt}:alloc:${uid}`) % 1e4 >= exp.allocationPct) return notIn;
+    const groupHash = murmur3(`${exp.salt}:group:${uid}`) % 1e4;
+    let cumulative = 0;
+    for (let i = 0; i < exp.groups.length; i++) {
+      const g = exp.groups[i];
+      cumulative += g.weight;
+      if (groupHash < cumulative || i === exp.groups.length - 1) {
+        if (!decode) {
+          return { inExperiment: true, group: g.name, params: g.params };
+        }
+        try {
+          return { inExperiment: true, group: g.name, params: decode(g.params) };
+        } catch (err) {
+          console.warn(`[shipeasy] getExperiment('${name}') decode failed:`, String(err));
+          return notIn;
+        }
+      }
+    }
+    return notIn;
+  }
+  track(userId, eventName, props) {
+    const body = JSON.stringify({
+      events: [
+        {
+          type: "metric",
+          event_name: eventName,
+          user_id: userId,
+          ts: Date.now(),
+          ...props !== void 0 ? { properties: props } : {}
+        }
+      ]
+    });
+    globalThis.fetch(`${this.baseUrl}/collect`, {
+      method: "POST",
+      headers: { "X-SDK-Key": this.apiKey, "Content-Type": "text/plain" },
+      body
+    }).catch((err) => console.warn("[shipeasy] track failed:", String(err)));
+  }
+};
+export {
+  FlagsClient,
+  version
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@shipeasy/sdk",
+  "version": "1.0.0",
+  "description": "Feature flag and experimentation SDK",
+  "main": "./dist/server/index.js",
+  "module": "./dist/server/index.mjs",
+  "browser": "./dist/client/index.js",
+  "exports": {
+    ".": {
+      "node": "./dist/server/index.js",
+      "browser": "./dist/client/index.js",
+      "default": "./dist/server/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.mjs",
+      "default": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./templates/*": "./templates/*.js"
+  },
+  "files": [
+    "dist/",
+    "templates/"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "murmurhash-js": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/murmurhash-js": "^1.0.6",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.4",
+    "vitest": "^2.1.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}