@shipeasy/sdk 2.3.0 → 2.5.0

package/dist/client/index.d.mts

@@ -27,6 +27,12 @@ interface EvalResponse {
     flags: Record<string, boolean>;
     configs: Record<string, unknown>;
     experiments: Record<string, EvalExpResult>;
+    /**
+     * Killswitch state, flattened by the server. A boolean means the killswitch
+     * is whole-killed; an object means it's not whole-killed and carries per-
+     * switch booleans.
+     */
+    killswitches?: Record<string, boolean | Record<string, boolean>>;
 }
 interface AutoCollectGroups {
     vitals: boolean;
@@ -83,6 +89,12 @@ declare class FlagsClientBrowser {
      */
     installBridge(): ShipeasySdkBridge | null;
     track(eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * Read a killswitch from the server's evaluated state. Without `switchKey`,
+     * returns true when the killswitch is whole-killed. With `switchKey`, returns
+     * the per-switch state. Returns false for unknown killswitches / switches.
+     */
+    getKillswitch(name: string, switchKey?: string): boolean;
     flush(): Promise<void>;
     destroy(): void;
 }
@@ -180,6 +192,12 @@ interface BootstrapPayload {
         group: string;
         params: Record<string, unknown>;
     }>;
+    /**
+     * Killswitch state, flattened by the server. A value of `boolean` means the
+     * killswitch is killed as a whole (no per-switch detail); a `Record` means
+     * the killswitch is not whole-killed and the map carries per-switch state.
+     */
+    killswitches?: Record<string, boolean | Record<string, boolean>>;
     /** Set by getBootstrapHtml() for auto-init. Not part of evaluate() output. */
     apiKey?: string;
     apiUrl?: string;
@@ -205,6 +223,16 @@ declare const flags: {
     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, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
     track(eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * Read a killswitch. Without `switchKey`, returns true when the killswitch is
+     * killed as a whole. With `switchKey`, returns true when that specific switch
+     * is on. Unknown killswitches / switches return false.
+     *
+     * Priority: bootstrap → CDN evalResult (post-mount) → false. Matches the
+     * pattern used by `flags.get` / `flags.getConfig` so SSR-hydrated values are
+     * available synchronously on first render.
+     */
+    ks(name: string, switchKey?: string): boolean;
     flush(): Promise<void>;
     /**
      * Called by FlagsBoundary after React hydration to unlock flag reads.

package/dist/client/index.d.ts

@@ -27,6 +27,12 @@ interface EvalResponse {
     flags: Record<string, boolean>;
     configs: Record<string, unknown>;
     experiments: Record<string, EvalExpResult>;
+    /**
+     * Killswitch state, flattened by the server. A boolean means the killswitch
+     * is whole-killed; an object means it's not whole-killed and carries per-
+     * switch booleans.
+     */
+    killswitches?: Record<string, boolean | Record<string, boolean>>;
 }
 interface AutoCollectGroups {
     vitals: boolean;
@@ -83,6 +89,12 @@ declare class FlagsClientBrowser {
      */
     installBridge(): ShipeasySdkBridge | null;
     track(eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * Read a killswitch from the server's evaluated state. Without `switchKey`,
+     * returns true when the killswitch is whole-killed. With `switchKey`, returns
+     * the per-switch state. Returns false for unknown killswitches / switches.
+     */
+    getKillswitch(name: string, switchKey?: string): boolean;
     flush(): Promise<void>;
     destroy(): void;
 }
@@ -180,6 +192,12 @@ interface BootstrapPayload {
         group: string;
         params: Record<string, unknown>;
     }>;
+    /**
+     * Killswitch state, flattened by the server. A value of `boolean` means the
+     * killswitch is killed as a whole (no per-switch detail); a `Record` means
+     * the killswitch is not whole-killed and the map carries per-switch state.
+     */
+    killswitches?: Record<string, boolean | Record<string, boolean>>;
     /** Set by getBootstrapHtml() for auto-init. Not part of evaluate() output. */
     apiKey?: string;
     apiUrl?: string;
@@ -205,6 +223,16 @@ declare const flags: {
     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, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
     track(eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * Read a killswitch. Without `switchKey`, returns true when the killswitch is
+     * killed as a whole. With `switchKey`, returns true when that specific switch
+     * is on. Unknown killswitches / switches return false.
+     *
+     * Priority: bootstrap → CDN evalResult (post-mount) → false. Matches the
+     * pattern used by `flags.get` / `flags.getConfig` so SSR-hydrated values are
+     * available synchronously on first render.
+     */
+    ks(name: string, switchKey?: string): boolean;
     flush(): Promise<void>;
     /**
      * Called by FlagsBoundary after React hydration to unlock flag reads.

package/dist/client/index.js

@@ -306,6 +306,23 @@ function installAutoGuardrails(buffer, userId, anonId, groups) {
     } catch {
     }
   };
+  if (groups.engagement) {
+    try {
+      buffer.pushMetric("__auto_session_active", userId, anonId, { value: 1 });
+    } catch {
+    }
+    let lastEmit = Date.now();
+    const SESSION_GAP_MS = 30 * 60 * 1e3;
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState !== "visible") return;
+      if (Date.now() - lastEmit < SESSION_GAP_MS) return;
+      try {
+        buffer.pushMetric("__auto_session_active", userId, anonId, { value: 1 });
+        lastEmit = Date.now();
+      } catch {
+      }
+    });
+  }
   const needHide = groups.vitals || groups.engagement;
   if (needHide) {
     if (document.readyState === "complete") {
@@ -558,6 +575,19 @@ var FlagsClientBrowser = class {
   track(eventName, props) {
     this.buffer.pushMetric(eventName, this.userId, this.anonId, props);
   }
+  /**
+   * Read a killswitch from the server's evaluated state. Without `switchKey`,
+   * returns true when the killswitch is whole-killed. With `switchKey`, returns
+   * the per-switch state. Returns false for unknown killswitches / switches.
+   */
+  getKillswitch(name, switchKey) {
+    if (this.evalResult === null) return false;
+    const ks = this.evalResult.killswitches?.[name];
+    if (ks === void 0) return false;
+    if (typeof ks === "boolean") return switchKey === void 0 ? ks : false;
+    if (switchKey === void 0) return false;
+    return ks[switchKey] === true;
+  }
   async flush() {
     await this.buffer.flushAsync();
   }
@@ -777,6 +807,26 @@ var flags = {
   track(eventName, props) {
     _client?.track(eventName, props);
   },
+  /**
+   * Read a killswitch. Without `switchKey`, returns true when the killswitch is
+   * killed as a whole. With `switchKey`, returns true when that specific switch
+   * is on. Unknown killswitches / switches return false.
+   *
+   * Priority: bootstrap → CDN evalResult (post-mount) → false. Matches the
+   * pattern used by `flags.get` / `flags.getConfig` so SSR-hydrated values are
+   * available synchronously on first render.
+   */
+  ks(name, switchKey) {
+    const bs = getBootstrap();
+    if (bs !== null && bs.killswitches && name in bs.killswitches) {
+      const ks = bs.killswitches[name];
+      if (typeof ks === "boolean") return switchKey === void 0 ? ks : false;
+      if (switchKey === void 0) return false;
+      return ks[switchKey] === true;
+    }
+    if (!_mountedAndReady) return false;
+    return _client?.getKillswitch(name, switchKey) ?? false;
+  },
   flush() {
     return _client?.flush() ?? Promise.resolve();
   },

package/dist/client/index.mjs

@@ -263,6 +263,23 @@ function installAutoGuardrails(buffer, userId, anonId, groups) {
     } catch {
     }
   };
+  if (groups.engagement) {
+    try {
+      buffer.pushMetric("__auto_session_active", userId, anonId, { value: 1 });
+    } catch {
+    }
+    let lastEmit = Date.now();
+    const SESSION_GAP_MS = 30 * 60 * 1e3;
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState !== "visible") return;
+      if (Date.now() - lastEmit < SESSION_GAP_MS) return;
+      try {
+        buffer.pushMetric("__auto_session_active", userId, anonId, { value: 1 });
+        lastEmit = Date.now();
+      } catch {
+      }
+    });
+  }
   const needHide = groups.vitals || groups.engagement;
   if (needHide) {
     if (document.readyState === "complete") {
@@ -515,6 +532,19 @@ var FlagsClientBrowser = class {
   track(eventName, props) {
     this.buffer.pushMetric(eventName, this.userId, this.anonId, props);
   }
+  /**
+   * Read a killswitch from the server's evaluated state. Without `switchKey`,
+   * returns true when the killswitch is whole-killed. With `switchKey`, returns
+   * the per-switch state. Returns false for unknown killswitches / switches.
+   */
+  getKillswitch(name, switchKey) {
+    if (this.evalResult === null) return false;
+    const ks = this.evalResult.killswitches?.[name];
+    if (ks === void 0) return false;
+    if (typeof ks === "boolean") return switchKey === void 0 ? ks : false;
+    if (switchKey === void 0) return false;
+    return ks[switchKey] === true;
+  }
   async flush() {
     await this.buffer.flushAsync();
   }
@@ -734,6 +764,26 @@ var flags = {
   track(eventName, props) {
     _client?.track(eventName, props);
   },
+  /**
+   * Read a killswitch. Without `switchKey`, returns true when the killswitch is
+   * killed as a whole. With `switchKey`, returns true when that specific switch
+   * is on. Unknown killswitches / switches return false.
+   *
+   * Priority: bootstrap → CDN evalResult (post-mount) → false. Matches the
+   * pattern used by `flags.get` / `flags.getConfig` so SSR-hydrated values are
+   * available synchronously on first render.
+   */
+  ks(name, switchKey) {
+    const bs = getBootstrap();
+    if (bs !== null && bs.killswitches && name in bs.killswitches) {
+      const ks = bs.killswitches[name];
+      if (typeof ks === "boolean") return switchKey === void 0 ? ks : false;
+      if (switchKey === void 0) return false;
+      return ks[switchKey] === true;
+    }
+    if (!_mountedAndReady) return false;
+    return _client?.getKillswitch(name, switchKey) ?? false;
+  },
   flush() {
     return _client?.flush() ?? Promise.resolve();
   },

package/dist/server/index.d.mts

@@ -9,10 +9,36 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
+interface GateRule {
+    attr: string;
+    op: "eq" | "neq" | "in" | "not_in" | "gt" | "gte" | "lt" | "lte" | "contains" | "regex";
+    value: unknown;
+}
+interface Gate {
+    rules: GateRule[];
+    rolloutPct: number;
+    salt: string;
+    enabled: 0 | 1 | boolean;
+    killswitch?: 0 | 1 | boolean;
+}
+interface Killswitch {
+    killed: 0 | 1 | boolean;
+    switches?: Record<string, 0 | 1 | boolean>;
+}
+interface FlagsBlob {
+    version: string;
+    plan: string;
+    gates: Record<string, Gate>;
+    configs: Record<string, {
+        value: unknown;
+    }>;
+    killswitches: Record<string, Killswitch>;
+}
 interface BootstrapPayload {
     flags: Record<string, boolean>;
     configs: Record<string, unknown>;
     experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
+    killswitches: Record<string, boolean | Record<string, boolean>>;
 }
 type FlagsClientEnv = "dev" | "staging" | "prod";
 interface FlagsClientOptions {
@@ -20,6 +46,11 @@ interface FlagsClientOptions {
     baseUrl?: string;
     /** Which published env to read values from. Defaults to "prod". */
     env?: FlagsClientEnv;
+    /**
+     * Preload the flags blob synchronously without a network fetch. Primarily
+     * for tests; production callers should rely on init()/initOnce().
+     */
+    initialBlob?: FlagsBlob;
 }
 declare class FlagsClient {
     private readonly apiKey;
@@ -54,6 +85,7 @@ declare class FlagsClient {
      * synchronously without waiting for identify() to resolve.
      */
     evaluate(user: User, rawUrl?: string): BootstrapPayload;
+    getKillswitch(name: string, switchKey?: string): boolean;
 }
 interface I18nForRequest {
     strings: Record<string, string>;
@@ -165,6 +197,12 @@ declare const flags: {
     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>;
+    /**
+     * Read a killswitch. Without `switchKey`, returns true when the whole
+     * killswitch is killed. With `switchKey`, returns true when that specific
+     * switch is on. Unknown killswitches / switches return false.
+     */
+    ks(name: string, switchKey?: string): boolean;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
     /**
      * Evaluate all flags / configs / experiments for a user against the locally

package/dist/server/index.d.ts

@@ -9,10 +9,36 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
+interface GateRule {
+    attr: string;
+    op: "eq" | "neq" | "in" | "not_in" | "gt" | "gte" | "lt" | "lte" | "contains" | "regex";
+    value: unknown;
+}
+interface Gate {
+    rules: GateRule[];
+    rolloutPct: number;
+    salt: string;
+    enabled: 0 | 1 | boolean;
+    killswitch?: 0 | 1 | boolean;
+}
+interface Killswitch {
+    killed: 0 | 1 | boolean;
+    switches?: Record<string, 0 | 1 | boolean>;
+}
+interface FlagsBlob {
+    version: string;
+    plan: string;
+    gates: Record<string, Gate>;
+    configs: Record<string, {
+        value: unknown;
+    }>;
+    killswitches: Record<string, Killswitch>;
+}
 interface BootstrapPayload {
     flags: Record<string, boolean>;
     configs: Record<string, unknown>;
     experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
+    killswitches: Record<string, boolean | Record<string, boolean>>;
 }
 type FlagsClientEnv = "dev" | "staging" | "prod";
 interface FlagsClientOptions {
@@ -20,6 +46,11 @@ interface FlagsClientOptions {
     baseUrl?: string;
     /** Which published env to read values from. Defaults to "prod". */
     env?: FlagsClientEnv;
+    /**
+     * Preload the flags blob synchronously without a network fetch. Primarily
+     * for tests; production callers should rely on init()/initOnce().
+     */
+    initialBlob?: FlagsBlob;
 }
 declare class FlagsClient {
     private readonly apiKey;
@@ -54,6 +85,7 @@ declare class FlagsClient {
      * synchronously without waiting for identify() to resolve.
      */
     evaluate(user: User, rawUrl?: string): BootstrapPayload;
+    getKillswitch(name: string, switchKey?: string): boolean;
 }
 interface I18nForRequest {
     strings: Record<string, string>;
@@ -165,6 +197,12 @@ declare const flags: {
     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>;
+    /**
+     * Read a killswitch. Without `switchKey`, returns true when the whole
+     * killswitch is killed. With `switchKey`, returns true when that specific
+     * switch is on. Unknown killswitches / switches return false.
+     */
+    ks(name: string, switchKey?: string): boolean;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
     /**
      * Evaluate all flags / configs / experiments for a user against the locally

package/dist/server/index.js

@@ -203,6 +203,10 @@ var FlagsClient = class {
     this.apiKey = opts.apiKey;
     this.baseUrl = (opts.baseUrl ?? "https://cdn.shipeasy.ai").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
+    if (opts.initialBlob) {
+      this.flagsBlob = opts.initialBlob;
+      this.initialized = true;
+    }
   }
   async init() {
     await this.fetchAll();
@@ -343,6 +347,7 @@ var FlagsClient = class {
     const flags2 = {};
     const configs = {};
     const experiments = {};
+    const killswitches = {};
     for (const [name, gate] of Object.entries(this.flagsBlob?.gates ?? {})) {
       flags2[name] = evalGateInternal(gate, user);
     }
@@ -352,6 +357,15 @@ var FlagsClient = class {
     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 ?? {})) {
+      if (ks.switches && Object.keys(ks.switches).length > 0) {
+        const out = {};
+        for (const [k, v] of Object.entries(ks.switches)) out[k] = isEnabled(v);
+        killswitches[name] = out;
+      } else {
+        killswitches[name] = isEnabled(ks.killed);
+      }
+    }
     if (rawUrl) {
       const ov = parseOverrides(rawUrl);
       Object.assign(flags2, ov.gates);
@@ -360,7 +374,13 @@ var FlagsClient = class {
         experiments[name] = { inExperiment: true, group, params: {} };
       }
     }
-    return { flags: flags2, configs, experiments };
+    return { flags: flags2, configs, experiments, killswitches };
+  }
+  getKillswitch(name, switchKey) {
+    const ks = this.flagsBlob?.killswitches?.[name];
+    if (!ks) return false;
+    if (switchKey === void 0) return isEnabled(ks.killed);
+    return isEnabled(ks.switches?.[switchKey]);
   }
 };
 var _I18N_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n");
@@ -589,6 +609,14 @@ var flags = {
       params: defaultParams
     };
   },
+  /**
+   * Read a killswitch. Without `switchKey`, returns true when the whole
+   * killswitch is killed. With `switchKey`, returns true when that specific
+   * switch is on. Unknown killswitches / switches return false.
+   */
+  ks(name, switchKey) {
+    return _server?.getKillswitch(name, switchKey) ?? false;
+  },
   track(userId, eventName, props) {
     _server?.track(userId, eventName, props);
   },
@@ -598,7 +626,12 @@ var flags = {
    * overrides. Returns an empty payload when the blob hasn't been fetched yet.
    */
   evaluate(user, rawUrl) {
-    return _server?.evaluate(user, rawUrl) ?? { flags: {}, configs: {}, experiments: {} };
+    return _server?.evaluate(user, rawUrl) ?? {
+      flags: {},
+      configs: {},
+      experiments: {},
+      killswitches: {}
+    };
   }
 };
 // Annotate the CommonJS export names for ESM import in node:

package/dist/server/index.mjs

@@ -160,6 +160,10 @@ var FlagsClient = class {
     this.apiKey = opts.apiKey;
     this.baseUrl = (opts.baseUrl ?? "https://cdn.shipeasy.ai").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
+    if (opts.initialBlob) {
+      this.flagsBlob = opts.initialBlob;
+      this.initialized = true;
+    }
   }
   async init() {
     await this.fetchAll();
@@ -300,6 +304,7 @@ var FlagsClient = class {
     const flags2 = {};
     const configs = {};
     const experiments = {};
+    const killswitches = {};
     for (const [name, gate] of Object.entries(this.flagsBlob?.gates ?? {})) {
       flags2[name] = evalGateInternal(gate, user);
     }
@@ -309,6 +314,15 @@ var FlagsClient = class {
     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 ?? {})) {
+      if (ks.switches && Object.keys(ks.switches).length > 0) {
+        const out = {};
+        for (const [k, v] of Object.entries(ks.switches)) out[k] = isEnabled(v);
+        killswitches[name] = out;
+      } else {
+        killswitches[name] = isEnabled(ks.killed);
+      }
+    }
     if (rawUrl) {
       const ov = parseOverrides(rawUrl);
       Object.assign(flags2, ov.gates);
@@ -317,7 +331,13 @@ var FlagsClient = class {
         experiments[name] = { inExperiment: true, group, params: {} };
       }
     }
-    return { flags: flags2, configs, experiments };
+    return { flags: flags2, configs, experiments, killswitches };
+  }
+  getKillswitch(name, switchKey) {
+    const ks = this.flagsBlob?.killswitches?.[name];
+    if (!ks) return false;
+    if (switchKey === void 0) return isEnabled(ks.killed);
+    return isEnabled(ks.switches?.[switchKey]);
   }
 };
 var _I18N_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n");
@@ -546,6 +566,14 @@ var flags = {
       params: defaultParams
     };
   },
+  /**
+   * Read a killswitch. Without `switchKey`, returns true when the whole
+   * killswitch is killed. With `switchKey`, returns true when that specific
+   * switch is on. Unknown killswitches / switches return false.
+   */
+  ks(name, switchKey) {
+    return _server?.getKillswitch(name, switchKey) ?? false;
+  },
   track(userId, eventName, props) {
     _server?.track(userId, eventName, props);
   },
@@ -555,7 +583,12 @@ var flags = {
    * overrides. Returns an empty payload when the blob hasn't been fetched yet.
    */
   evaluate(user, rawUrl) {
-    return _server?.evaluate(user, rawUrl) ?? { flags: {}, configs: {}, experiments: {} };
+    return _server?.evaluate(user, rawUrl) ?? {
+      flags: {},
+      configs: {},
+      experiments: {},
+      killswitches: {}
+    };
   }
 };
 export {

package/package.json

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