@shipeasy/sdk 6.0.0 → 6.2.0

package/dist/openfeature-server/index.js

@@ -25,6 +25,177 @@ __export(openfeature_server_exports, {
 module.exports = __toCommonJS(openfeature_server_exports);
 var import_server_sdk = require("@openfeature/server-sdk");
 
+// src/server/index.ts
+var import_node_async_hooks = require("async_hooks");
+
+// src/see/core.ts
+var SEE_MAX_SUBJECT = 200;
+var SEE_MAX_EXTRA_VALUE = 200;
+var SEE_MAX_EXTRA_KEYS = 20;
+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) {
+  return { __seViolation: true, violationName: String(name) };
+}
+var EXPECTED_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-expected");
+function readExpectedMark(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const v = err[EXPECTED_SYM];
+  return v !== void 0 && v !== null && typeof v === "object" ? v : void 0;
+}
+function markExpected(err, because, extras) {
+  if (typeof err !== "object" || err === null) return;
+  const prev = readExpectedMark(err);
+  const clean = sanitizeExtras(extras);
+  const merged = prev?.extras || clean ? { ...prev?.extras, ...clean } : void 0;
+  const mark = {
+    because: String(because),
+    ...merged ? { extras: merged } : {}
+  };
+  try {
+    Object.defineProperty(err, EXPECTED_SYM, {
+      value: mark,
+      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;
+}
+var scheduleMicrotask = typeof queueMicrotask === "function" ? queueMicrotask : (cb) => {
+  void Promise.resolve().then(cb);
+};
+function startSeeChain(getProblem, dispatch) {
+  let subject;
+  let outcome;
+  let collected;
+  let flushed = false;
+  scheduleMicrotask(() => {
+    if (flushed) return;
+    flushed = true;
+    dispatch(
+      getProblem(),
+      // Bare noun phrase — titles render as "… causes the {subject} …", so a
+      // leading article would double up ("causes the the app").
+      causesThe(subject ?? "app").to(outcome ?? "hit an error"),
+      collected
+    );
+  });
+  const tail = {
+    extras(x) {
+      if (x && typeof x === "object") collected = { ...collected, ...x };
+      return tail;
+    }
+  };
+  const step = {
+    to(o) {
+      outcome = String(o);
+      return tail;
+    }
+  };
+  const start = (s) => {
+    subject = String(s);
+    return step;
+  };
+  return { causes_the: start, causesThe: start };
+}
+function startSeeViolationChain(name, dispatch) {
+  return startSeeChain(() => violation(name), dispatch);
+}
+function startControlFlowChain(err) {
+  return {
+    because(reason) {
+      markExpected(err, reason);
+      const tail = {
+        extras(x) {
+          markExpected(err, reason, x);
+          return tail;
+        }
+      };
+      return tail;
+    }
+  };
+}
+
+// src/server/index.ts
+var _I18N_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n");
+var _EDIT_MODE_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-edit-mode");
+var _i18nALS = new import_node_async_hooks.AsyncLocalStorage();
+var _I18N_CACHE_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n-cache");
+var _i18nCache = globalThis[_I18N_CACHE_SYM] ?? (globalThis[_I18N_CACHE_SYM] = /* @__PURE__ */ new Map());
+globalThis[_I18N_SSR_SYM] = () => {
+  const fromALS = _i18nALS.getStore();
+  if (fromALS && Object.keys(fromALS.strings).length > 0) return fromALS;
+  for (const v of _i18nCache.values()) {
+    if (Object.keys(v.strings).length > 0) return v;
+  }
+  return fromALS ?? null;
+};
+var _EDIT_MODE_ALS_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-edit-mode-als");
+var _editModeALS = globalThis[_EDIT_MODE_ALS_SYM] ?? (globalThis[_EDIT_MODE_ALS_SYM] = new import_node_async_hooks.AsyncLocalStorage());
+var _EDIT_MODE_FALLBACK_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-edit-mode-fallback");
+if (globalThis[_EDIT_MODE_FALLBACK_SYM] === void 0) {
+  globalThis[_EDIT_MODE_FALLBACK_SYM] = false;
+}
+Object.defineProperty(globalThis, _EDIT_MODE_SSR_SYM, {
+  get: () => _editModeALS.getStore() ?? globalThis[_EDIT_MODE_FALLBACK_SYM] ?? false,
+  set: (v) => {
+    const b = Boolean(v);
+    try {
+      _editModeALS.enterWith(b);
+    } catch {
+    }
+    globalThis[_EDIT_MODE_FALLBACK_SYM] = b;
+  },
+  configurable: true
+});
+var _SEE_CORR_ALS_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-correlation-als");
+var seeContext = globalThis[_SEE_CORR_ALS_SYM] ?? (globalThis[_SEE_CORR_ALS_SYM] = new import_node_async_hooks.AsyncLocalStorage());
+var _server = null;
+function getShipeasyServerClient() {
+  return _server;
+}
+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: (err) => startControlFlowChain(err)
+  }
+);
+
 // src/openfeature/shared.ts
 var REASON_MAP = {
   RULE_MATCH: { reason: "TARGETING_MATCH" },
@@ -78,12 +249,31 @@ function resolveConfig(raw, defaultValue, type) {
   return { value: r.value, reason: "TARGETING_MATCH" };
 }
 var ShipeasyProvider = class {
-  constructor(client) {
-    this.client = client;
-  }
-  client;
   metadata = { name: "shipeasy" };
   runsOn = "server";
+  client;
+  /**
+   * Construct the provider. The **global form** (no argument) resolves the
+   * engine built by `configure({ apiKey })`, so the docs build it after
+   * configuration without ever naming the `Engine`:
+   *
+   * ```ts
+   * configure({ apiKey: process.env.SHIPEASY_SERVER_KEY! });
+   * await OpenFeature.setProviderAndWait(new ShipeasyProvider());
+   * ```
+   *
+   * Passing an explicit `Engine` stays supported for advanced/back-compat use.
+   * Throws if no engine is passed and `configure()` has not run.
+   */
+  constructor(client) {
+    const resolved = client ?? getShipeasyServerClient();
+    if (!resolved) {
+      throw new Error(
+        "[shipeasy] new ShipeasyProvider() resolves the configured global engine \u2014 call configure({ apiKey }) first, or pass an Engine explicitly."
+      );
+    }
+    this.client = resolved;
+  }
   /** Fetch the rules blob once. The SDK fires `Ready` when this resolves. */
   async initialize() {
     await this.client.initOnce();

package/dist/openfeature-server/index.mjs

@@ -1,6 +1,177 @@
 // src/openfeature-server/index.ts
 import { ErrorCode } from "@openfeature/server-sdk";
 
+// src/server/index.ts
+import { AsyncLocalStorage } from "async_hooks";
+
+// src/see/core.ts
+var SEE_MAX_SUBJECT = 200;
+var SEE_MAX_EXTRA_VALUE = 200;
+var SEE_MAX_EXTRA_KEYS = 20;
+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) {
+  return { __seViolation: true, violationName: String(name) };
+}
+var EXPECTED_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-expected");
+function readExpectedMark(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const v = err[EXPECTED_SYM];
+  return v !== void 0 && v !== null && typeof v === "object" ? v : void 0;
+}
+function markExpected(err, because, extras) {
+  if (typeof err !== "object" || err === null) return;
+  const prev = readExpectedMark(err);
+  const clean = sanitizeExtras(extras);
+  const merged = prev?.extras || clean ? { ...prev?.extras, ...clean } : void 0;
+  const mark = {
+    because: String(because),
+    ...merged ? { extras: merged } : {}
+  };
+  try {
+    Object.defineProperty(err, EXPECTED_SYM, {
+      value: mark,
+      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;
+}
+var scheduleMicrotask = typeof queueMicrotask === "function" ? queueMicrotask : (cb) => {
+  void Promise.resolve().then(cb);
+};
+function startSeeChain(getProblem, dispatch) {
+  let subject;
+  let outcome;
+  let collected;
+  let flushed = false;
+  scheduleMicrotask(() => {
+    if (flushed) return;
+    flushed = true;
+    dispatch(
+      getProblem(),
+      // Bare noun phrase — titles render as "… causes the {subject} …", so a
+      // leading article would double up ("causes the the app").
+      causesThe(subject ?? "app").to(outcome ?? "hit an error"),
+      collected
+    );
+  });
+  const tail = {
+    extras(x) {
+      if (x && typeof x === "object") collected = { ...collected, ...x };
+      return tail;
+    }
+  };
+  const step = {
+    to(o) {
+      outcome = String(o);
+      return tail;
+    }
+  };
+  const start = (s) => {
+    subject = String(s);
+    return step;
+  };
+  return { causes_the: start, causesThe: start };
+}
+function startSeeViolationChain(name, dispatch) {
+  return startSeeChain(() => violation(name), dispatch);
+}
+function startControlFlowChain(err) {
+  return {
+    because(reason) {
+      markExpected(err, reason);
+      const tail = {
+        extras(x) {
+          markExpected(err, reason, x);
+          return tail;
+        }
+      };
+      return tail;
+    }
+  };
+}
+
+// src/server/index.ts
+var _I18N_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n");
+var _EDIT_MODE_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-edit-mode");
+var _i18nALS = new AsyncLocalStorage();
+var _I18N_CACHE_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n-cache");
+var _i18nCache = globalThis[_I18N_CACHE_SYM] ?? (globalThis[_I18N_CACHE_SYM] = /* @__PURE__ */ new Map());
+globalThis[_I18N_SSR_SYM] = () => {
+  const fromALS = _i18nALS.getStore();
+  if (fromALS && Object.keys(fromALS.strings).length > 0) return fromALS;
+  for (const v of _i18nCache.values()) {
+    if (Object.keys(v.strings).length > 0) return v;
+  }
+  return fromALS ?? null;
+};
+var _EDIT_MODE_ALS_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-edit-mode-als");
+var _editModeALS = globalThis[_EDIT_MODE_ALS_SYM] ?? (globalThis[_EDIT_MODE_ALS_SYM] = new AsyncLocalStorage());
+var _EDIT_MODE_FALLBACK_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-edit-mode-fallback");
+if (globalThis[_EDIT_MODE_FALLBACK_SYM] === void 0) {
+  globalThis[_EDIT_MODE_FALLBACK_SYM] = false;
+}
+Object.defineProperty(globalThis, _EDIT_MODE_SSR_SYM, {
+  get: () => _editModeALS.getStore() ?? globalThis[_EDIT_MODE_FALLBACK_SYM] ?? false,
+  set: (v) => {
+    const b = Boolean(v);
+    try {
+      _editModeALS.enterWith(b);
+    } catch {
+    }
+    globalThis[_EDIT_MODE_FALLBACK_SYM] = b;
+  },
+  configurable: true
+});
+var _SEE_CORR_ALS_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-correlation-als");
+var seeContext = globalThis[_SEE_CORR_ALS_SYM] ?? (globalThis[_SEE_CORR_ALS_SYM] = new AsyncLocalStorage());
+var _server = null;
+function getShipeasyServerClient() {
+  return _server;
+}
+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: (err) => startControlFlowChain(err)
+  }
+);
+
 // src/openfeature/shared.ts
 var REASON_MAP = {
   RULE_MATCH: { reason: "TARGETING_MATCH" },
@@ -54,12 +225,31 @@ function resolveConfig(raw, defaultValue, type) {
   return { value: r.value, reason: "TARGETING_MATCH" };
 }
 var ShipeasyProvider = class {
-  constructor(client) {
-    this.client = client;
-  }
-  client;
   metadata = { name: "shipeasy" };
   runsOn = "server";
+  client;
+  /**
+   * Construct the provider. The **global form** (no argument) resolves the
+   * engine built by `configure({ apiKey })`, so the docs build it after
+   * configuration without ever naming the `Engine`:
+   *
+   * ```ts
+   * configure({ apiKey: process.env.SHIPEASY_SERVER_KEY! });
+   * await OpenFeature.setProviderAndWait(new ShipeasyProvider());
+   * ```
+   *
+   * Passing an explicit `Engine` stays supported for advanced/back-compat use.
+   * Throws if no engine is passed and `configure()` has not run.
+   */
+  constructor(client) {
+    const resolved = client ?? getShipeasyServerClient();
+    if (!resolved) {
+      throw new Error(
+        "[shipeasy] new ShipeasyProvider() resolves the configured global engine \u2014 call configure({ apiKey }) first, or pass an Engine explicitly."
+      );
+    }
+    this.client = resolved;
+  }
   /** Fetch the rules blob once. The SDK fires `Ready` when this resolves. */
   async initialize() {
     await this.client.initOnce();

package/dist/server/index.d.mts

@@ -591,6 +591,20 @@ interface ConfigureOptions<U = unknown> extends Omit<EngineOptions, "apiKey"> {
      * verbatim, so it should carry `user_id`/`anonymous_id` + any targeting attrs).
      */
     attributes?: AttributesFn<U>;
+    /**
+     * Long-running server: start the **background poll** internally (initial fetch
+     * + periodic refresh) so flags stay fresh without a redeploy. Default `false`.
+     * With `poll: false` (default) a one-shot fetch is kicked off fire-and-forget
+     * (serverless-friendly). You never need to call `engine.init()` yourself —
+     * configuration owns the lifecycle.
+     */
+    poll?: boolean;
+    /**
+     * One-shot fetch on configure (fire-and-forget). Default `true`. Ignored when
+     * `poll: true` (the poll does the initial fetch). Set `false` only if you want
+     * to control the first fetch yourself.
+     */
+    init?: boolean;
 }
 /**
  * Configure the SDK once at app boot, then evaluate per user with
@@ -613,6 +627,77 @@ interface ConfigureOptions<U = unknown> extends Omit<EngineOptions, "apiKey"> {
 declare function configure<U = unknown>(opts: ConfigureOptions<U>): Engine;
 /** Test seam: reset the registered attribute transform. */
 declare function _resetConfigureForTests(): void;
+/** Seed shapes shared by {@link configureForTesting} / {@link configureForOffline}. */
+interface ConfigureTestOptions<U = unknown> {
+    /** Same transform as {@link configure} (default identity). */
+    attributes?: AttributesFn<U>;
+    /** `{ name: bool }` — forced `getFlag` results. */
+    flags?: Record<string, boolean>;
+    /** `{ name: value }` — forced `getConfig` results. */
+    configs?: Record<string, unknown>;
+    /** `{ name: [group, params] }` — forced enrolments. */
+    experiments?: Record<string, [string, Record<string, unknown>]>;
+}
+/**
+ * Configure the SDK in **test mode** — a drop-in sibling of {@link configure}
+ * with no network, ever (no api key needed). Seed what your code under test
+ * should see, then read through the ordinary `new Client(user)`:
+ *
+ * ```ts
+ * configureForTesting({ flags: { new_checkout: true } });
+ * const flags = new Client({ user_id: "u_1" });
+ * flags.getFlag("new_checkout"); // true
+ * ```
+ *
+ * Replaces any previously-configured engine, so tests can reconfigure freely.
+ */
+declare function configureForTesting<U = unknown>(opts?: ConfigureTestOptions<U>): Engine;
+/** Options for {@link configureForOffline} — exactly one of `snapshot` / `path`. */
+interface ConfigureOfflineOptions<U = unknown> extends ConfigureTestOptions<U> {
+    /** In-memory `{ flags: <body of /sdk/flags>, experiments: <body of /sdk/experiments> }`. */
+    snapshot?: {
+        flags: FlagsBlob;
+        experiments: ExpsBlob;
+    };
+    /** Path to a JSON file `{ flags, experiments }`. */
+    path?: string;
+}
+/**
+ * Configure the SDK **offline** — evaluate the REAL rules from an in-memory
+ * snapshot or a JSON file, with no network. A drop-in sibling of
+ * {@link configure} (no api key needed). Optional `flags`/`configs`/`experiments`
+ * overrides are layered on top (same shapes as {@link configureForTesting}).
+ * Replaces any previously-configured engine.
+ */
+declare function configureForOffline<U = unknown>(opts: ConfigureOfflineOptions<U>): Engine;
+/**
+ * Force `getFlag(name)` → `value` on the spot, for the current config. A quick
+ * in-test override layered on top of whatever {@link configureForTesting} /
+ * {@link configureForOffline} (or {@link configure}) set up — wins over the blob
+ * until {@link clearOverrides}.
+ */
+declare function overrideFlag(name: string, value: boolean): void;
+/** Force `getConfig(name)` → `value` on the spot (see {@link overrideFlag}). */
+declare function overrideConfig(name: string, value: unknown): void;
+/**
+ * Force `getExperiment(name)` to report enrolment in `group` with `params` on
+ * the spot (see {@link overrideFlag}).
+ */
+declare function overrideExperiment(name: string, group: string, params: Record<string, unknown>): void;
+/**
+ * Drop every on-the-spot flag/config/experiment override — INCLUDING the seed
+ * from {@link configureForTesting} (test mode has no blob beneath, so everything
+ * reverts to the empty-blob defaults). Under {@link configureForOffline} the
+ * snapshot remains and evaluations revert to it.
+ */
+declare function clearOverrides(): void;
+/**
+ * Register a listener fired after a background poll fetches NEW data (a 200, not
+ * a 304). Returns an unsubscribe callable. Requires `configure({ poll: true })`
+ * (no poll thread runs otherwise). Configuration owns the engine; you never
+ * touch it.
+ */
+declare function onChange(listener: () => void): () => void;
 /**
  * A user-bound evaluation handle. Construct one per user/request — it's cheap
  * (it delegates to the {@link Engine} built by {@link configure}); it does NOT
@@ -637,6 +722,21 @@ declare class Client<U = unknown> {
     getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     /** Read a killswitch (not user-bound; mirrors {@link Engine.getKillswitch}). */
     getKillswitch(name: string, switchKey?: string): boolean;
+    /**
+     * Record a conversion/metric event for the bound user. Derives the unit from
+     * the resolved attribute bag (`user_id`, else `anonymous_id`) and delegates to
+     * {@link Engine.track} — so an experiment is end-to-end Client-only (no need to
+     * drop down to the Engine to log a conversion). Fire-and-forget; no-op in test
+     * mode.
+     */
+    track(eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * Emit an exposure event for `name` at this server-side decision point for the
+     * bound user. Delegates to {@link Engine.logExposure} with the resolved
+     * attribute bag (re-evaluates enrolment; no-op when the user isn't enrolled or
+     * in test mode).
+     */
+    logExposure(name: string): void;
 }
 interface SeeApi {
     /**
@@ -689,4 +789,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-export { ANON_ID_COOKIE, type AttributesFn, type BootstrapData, type BootstrapEmitOptions, type BootstrapPayload, Client, type ConfigureOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, type ExpsBlob, FLAG_REASONS, type FetchLabelsOptions, type FlagDetail, type FlagReason, type FlagsBlob, type GetConfigOptions, type I18nForRequest, type LabelFile, type ScriptTagSpec, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type StickyBucketStore, type StickyEntry, type User, type Violation, _murmur3ForTests, _resetConfigureForTests, _resetShipeasyServerForTests, configure, configureShipeasyServer, createInMemoryStickyStore, fetchLabelsForSSR, flags, getBootstrapData, getBootstrapTags, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };
+export { ANON_ID_COOKIE, type AttributesFn, type BootstrapData, type BootstrapEmitOptions, type BootstrapPayload, Client, type ConfigureOfflineOptions, type ConfigureOptions, type ConfigureTestOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, type ExpsBlob, FLAG_REASONS, type FetchLabelsOptions, type FlagDetail, type FlagReason, type FlagsBlob, type GetConfigOptions, type I18nForRequest, type LabelFile, type ScriptTagSpec, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type StickyBucketStore, type StickyEntry, type User, type Violation, _murmur3ForTests, _resetConfigureForTests, _resetShipeasyServerForTests, clearOverrides, configure, configureForOffline, configureForTesting, configureShipeasyServer, createInMemoryStickyStore, fetchLabelsForSSR, flags, getBootstrapData, getBootstrapTags, getShipeasyServerClient, i18n, isExpected, onChange, overrideConfig, overrideExperiment, overrideFlag, see, seeContext, shipeasy, version };

package/dist/server/index.d.ts

@@ -591,6 +591,20 @@ interface ConfigureOptions<U = unknown> extends Omit<EngineOptions, "apiKey"> {
      * verbatim, so it should carry `user_id`/`anonymous_id` + any targeting attrs).
      */
     attributes?: AttributesFn<U>;
+    /**
+     * Long-running server: start the **background poll** internally (initial fetch
+     * + periodic refresh) so flags stay fresh without a redeploy. Default `false`.
+     * With `poll: false` (default) a one-shot fetch is kicked off fire-and-forget
+     * (serverless-friendly). You never need to call `engine.init()` yourself —
+     * configuration owns the lifecycle.
+     */
+    poll?: boolean;
+    /**
+     * One-shot fetch on configure (fire-and-forget). Default `true`. Ignored when
+     * `poll: true` (the poll does the initial fetch). Set `false` only if you want
+     * to control the first fetch yourself.
+     */
+    init?: boolean;
 }
 /**
  * Configure the SDK once at app boot, then evaluate per user with
@@ -613,6 +627,77 @@ interface ConfigureOptions<U = unknown> extends Omit<EngineOptions, "apiKey"> {
 declare function configure<U = unknown>(opts: ConfigureOptions<U>): Engine;
 /** Test seam: reset the registered attribute transform. */
 declare function _resetConfigureForTests(): void;
+/** Seed shapes shared by {@link configureForTesting} / {@link configureForOffline}. */
+interface ConfigureTestOptions<U = unknown> {
+    /** Same transform as {@link configure} (default identity). */
+    attributes?: AttributesFn<U>;
+    /** `{ name: bool }` — forced `getFlag` results. */
+    flags?: Record<string, boolean>;
+    /** `{ name: value }` — forced `getConfig` results. */
+    configs?: Record<string, unknown>;
+    /** `{ name: [group, params] }` — forced enrolments. */
+    experiments?: Record<string, [string, Record<string, unknown>]>;
+}
+/**
+ * Configure the SDK in **test mode** — a drop-in sibling of {@link configure}
+ * with no network, ever (no api key needed). Seed what your code under test
+ * should see, then read through the ordinary `new Client(user)`:
+ *
+ * ```ts
+ * configureForTesting({ flags: { new_checkout: true } });
+ * const flags = new Client({ user_id: "u_1" });
+ * flags.getFlag("new_checkout"); // true
+ * ```
+ *
+ * Replaces any previously-configured engine, so tests can reconfigure freely.
+ */
+declare function configureForTesting<U = unknown>(opts?: ConfigureTestOptions<U>): Engine;
+/** Options for {@link configureForOffline} — exactly one of `snapshot` / `path`. */
+interface ConfigureOfflineOptions<U = unknown> extends ConfigureTestOptions<U> {
+    /** In-memory `{ flags: <body of /sdk/flags>, experiments: <body of /sdk/experiments> }`. */
+    snapshot?: {
+        flags: FlagsBlob;
+        experiments: ExpsBlob;
+    };
+    /** Path to a JSON file `{ flags, experiments }`. */
+    path?: string;
+}
+/**
+ * Configure the SDK **offline** — evaluate the REAL rules from an in-memory
+ * snapshot or a JSON file, with no network. A drop-in sibling of
+ * {@link configure} (no api key needed). Optional `flags`/`configs`/`experiments`
+ * overrides are layered on top (same shapes as {@link configureForTesting}).
+ * Replaces any previously-configured engine.
+ */
+declare function configureForOffline<U = unknown>(opts: ConfigureOfflineOptions<U>): Engine;
+/**
+ * Force `getFlag(name)` → `value` on the spot, for the current config. A quick
+ * in-test override layered on top of whatever {@link configureForTesting} /
+ * {@link configureForOffline} (or {@link configure}) set up — wins over the blob
+ * until {@link clearOverrides}.
+ */
+declare function overrideFlag(name: string, value: boolean): void;
+/** Force `getConfig(name)` → `value` on the spot (see {@link overrideFlag}). */
+declare function overrideConfig(name: string, value: unknown): void;
+/**
+ * Force `getExperiment(name)` to report enrolment in `group` with `params` on
+ * the spot (see {@link overrideFlag}).
+ */
+declare function overrideExperiment(name: string, group: string, params: Record<string, unknown>): void;
+/**
+ * Drop every on-the-spot flag/config/experiment override — INCLUDING the seed
+ * from {@link configureForTesting} (test mode has no blob beneath, so everything
+ * reverts to the empty-blob defaults). Under {@link configureForOffline} the
+ * snapshot remains and evaluations revert to it.
+ */
+declare function clearOverrides(): void;
+/**
+ * Register a listener fired after a background poll fetches NEW data (a 200, not
+ * a 304). Returns an unsubscribe callable. Requires `configure({ poll: true })`
+ * (no poll thread runs otherwise). Configuration owns the engine; you never
+ * touch it.
+ */
+declare function onChange(listener: () => void): () => void;
 /**
  * A user-bound evaluation handle. Construct one per user/request — it's cheap
  * (it delegates to the {@link Engine} built by {@link configure}); it does NOT
@@ -637,6 +722,21 @@ declare class Client<U = unknown> {
     getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     /** Read a killswitch (not user-bound; mirrors {@link Engine.getKillswitch}). */
     getKillswitch(name: string, switchKey?: string): boolean;
+    /**
+     * Record a conversion/metric event for the bound user. Derives the unit from
+     * the resolved attribute bag (`user_id`, else `anonymous_id`) and delegates to
+     * {@link Engine.track} — so an experiment is end-to-end Client-only (no need to
+     * drop down to the Engine to log a conversion). Fire-and-forget; no-op in test
+     * mode.
+     */
+    track(eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * Emit an exposure event for `name` at this server-side decision point for the
+     * bound user. Delegates to {@link Engine.logExposure} with the resolved
+     * attribute bag (re-evaluates enrolment; no-op when the user isn't enrolled or
+     * in test mode).
+     */
+    logExposure(name: string): void;
 }
 interface SeeApi {
     /**
@@ -689,4 +789,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-export { ANON_ID_COOKIE, type AttributesFn, type BootstrapData, type BootstrapEmitOptions, type BootstrapPayload, Client, type ConfigureOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, type ExpsBlob, FLAG_REASONS, type FetchLabelsOptions, type FlagDetail, type FlagReason, type FlagsBlob, type GetConfigOptions, type I18nForRequest, type LabelFile, type ScriptTagSpec, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type StickyBucketStore, type StickyEntry, type User, type Violation, _murmur3ForTests, _resetConfigureForTests, _resetShipeasyServerForTests, configure, configureShipeasyServer, createInMemoryStickyStore, fetchLabelsForSSR, flags, getBootstrapData, getBootstrapTags, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };
+export { ANON_ID_COOKIE, type AttributesFn, type BootstrapData, type BootstrapEmitOptions, type BootstrapPayload, Client, type ConfigureOfflineOptions, type ConfigureOptions, type ConfigureTestOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, type ExpsBlob, FLAG_REASONS, type FetchLabelsOptions, type FlagDetail, type FlagReason, type FlagsBlob, type GetConfigOptions, type I18nForRequest, type LabelFile, type ScriptTagSpec, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type StickyBucketStore, type StickyEntry, type User, type Violation, _murmur3ForTests, _resetConfigureForTests, _resetShipeasyServerForTests, clearOverrides, configure, configureForOffline, configureForTesting, configureShipeasyServer, createInMemoryStickyStore, fetchLabelsForSSR, flags, getBootstrapData, getBootstrapTags, getShipeasyServerClient, i18n, isExpected, onChange, overrideConfig, overrideExperiment, overrideFlag, see, seeContext, shipeasy, version };