@shipeasy/sdk 6.3.1 → 7.0.0

package/dist/server/index.d.ts

@@ -125,6 +125,10 @@ interface ExperimentResult<P> {
     inExperiment: boolean;
     group: string;
     params: P;
+    /** The universe this experiment belongs to. Carried in the SSR bootstrap +
+     *  `/sdk/evaluate` so the client can resolve `universe(name).assign()` by
+     *  finding the enrolled experiment in a universe. */
+    universe?: string;
 }
 /**
  * Why a flag evaluated the way it did (LaunchDarkly variationDetail parity).
@@ -170,13 +174,46 @@ interface ExperimentGroup {
 interface Experiment {
     universe: string;
     targetingGate?: string | null;
+    /**
+     * Per-experiment holdout flag (a `type='holdout'` gate). When set and the flag
+     * passes for a unit, that unit is *held out* of THIS experiment — never
+     * assigned, sees the universe defaults. Checked after the universe holdout,
+     * before allocation. Mirrors @shipeasy/core §B3.
+     */
+    holdoutGate?: string | null;
     allocationPct: number;
+    /**
+     * Contiguous half-open slice `[poolOffsetBp, poolOffsetBp + poolSizeBp)` of the
+     * *universe* hash space this experiment claims. Used only when `hashVersion >= 2`
+     * (pooled assignment / real mutual exclusion, §B4): the unit's universe segment
+     * must fall in this range to be in the experiment. Null ⇒ fall back to the
+     * legacy independent-salt `allocationPct` gate.
+     */
+    poolOffsetBp?: number | null;
+    poolSizeBp?: number | null;
+    /**
+     * A tail of the group split kept empty (basis points) so a new variant can be
+     * appended into it while running without reshuffling enrolled units. Group
+     * weights sum to `10000 − reservedHeadroomBp`; a unit hashing into the reserved
+     * tail is treated as not-assigned (sees universe defaults). §B5.
+     */
+    reservedHeadroomBp?: number | null;
     salt: string;
     groups: ExperimentGroup[];
     status: "draft" | "running" | "stopped" | "archived";
+    /** Bucketing scheme version. `>= 2` unlocks pooled (mutually-exclusive) assignment. */
+    hashVersion?: number;
     /** Attribute to bucket on (e.g. company_id); defaults to user_id/anonymous_id. */
     bucketBy?: string | null;
 }
+/** One param the universe owns: a name, a type, and the default a variant
+ *  inherits when it doesn't override the value (§A/§B2). */
+interface UniverseParam {
+    name: string;
+    type: "bool" | "int" | "number" | "string";
+    default: unknown;
+}
+type UniverseParamSchema = UniverseParam[];
 /** One persisted sticky assignment: group + 8-char salt prefix (reshuffle key). */
 interface StickyEntry {
     g: string;
@@ -197,6 +234,13 @@ interface StickyBucketStore {
 declare function createInMemoryStickyStore(seed?: Record<string, Record<string, StickyEntry>>): StickyBucketStore;
 interface Universe {
     holdout_range: [number, number] | null;
+    /**
+     * The universe's config schema — the single source of truth for param names,
+     * types, and defaults (§A). The `assign()` merge layers these defaults *under*
+     * an assigned variant's overrides so an unset param still returns the universe
+     * default. Null/absent ⇒ no defaults (legacy: variant params returned verbatim).
+     */
+    param_schema?: UniverseParamSchema | null;
 }
 interface Killswitch {
     killed: 0 | 1 | boolean;
@@ -223,8 +267,36 @@ interface BootstrapPayload {
     configs: Record<string, unknown>;
     experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
     killswitches: Record<string, boolean | Record<string, boolean>>;
+    /** Per-universe param defaults (name → default map) so the client can resolve
+     *  `universe(name).get(field)` to the universe default even when the unit is
+     *  not enrolled in any experiment there. Only universes with running
+     *  experiments are included. */
+    universes?: Record<string, {
+        defaults: Record<string, unknown>;
+    }>;
 }
 declare const ANON_ID_COOKIE = "__se_anon_id";
+/**
+ * The result of `universe(name).assign(user)` — a user's standing in a universe.
+ * A universe is a mutual-exclusion pool, so a unit lands in **at most one**
+ * experiment. Never throws: an un-enrolled unit still resolves `get()` to the
+ * universe defaults (or your fallback). Reading is side-effect free — the single
+ * exposure is logged once by `assign()` when the unit is enrolled.
+ */
+interface Assignment {
+    /** The experiment the unit landed in, or `null` when not enrolled. */
+    readonly name: string | null;
+    /** The assigned variant/group name, or `null` when not enrolled. */
+    readonly group: string | null;
+    /** True iff the unit is enrolled in an experiment in this universe. */
+    readonly enrolled: boolean;
+    /**
+     * Read a resolved param: the assigned variant's override, else the universe
+     * default, else `fallback`. Works even when not enrolled (variant layer is
+     * absent, so you get `universeDefault ?? fallback`).
+     */
+    get<T = unknown>(field: string, fallback?: T): T | undefined;
+}
 type EngineEnv = "dev" | "staging" | "prod";
 interface EngineOptions {
     apiKey: string;
@@ -257,6 +329,14 @@ interface EngineOptions {
      * SDK entirely. See {@link LogLevel}.
      */
     logLevel?: LogLevel;
+    /**
+     * Opt out of SDK-internal error self-monitoring. When one of the SDK's own
+     * last-resort guards catches an internal failure (an "on our end" bug), the
+     * SDK reports it to Shipeasy's own project so we can track SDK bugs across
+     * apps — never to your project. ON by default; forced off in test mode. Pass
+     * `true` to disable.
+     */
+    disableInternalErrorReporting?: boolean;
     /**
      * Attribute names usable for targeting but never persisted in analytics
      * (LD/Statsig `privateAttributes`). The server evaluates locally so private
@@ -299,6 +379,7 @@ declare class Engine {
     private readonly flagOverrides;
     private readonly configOverrides;
     private readonly experimentOverrides;
+    private readonly exposureSeen;
     private readonly changeListeners;
     constructor(opts: EngineOptions);
     /**
@@ -378,19 +459,47 @@ declare class Engine {
     getFlag(name: string, user: User, defaultValue?: boolean): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getConfig<T = unknown>(name: string, opts: GetConfigOptions<T>): T;
-    getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
+    /**
+     * Bind the per-experiment sticky seam over the configured {@link StickyBucketStore}
+     * for one (unit, experiment). Absent store ⇒ deterministic (no sticky).
+     */
+    private bindSticky;
+    /**
+     * Evaluate one experiment by name for `user` — override → full classify
+     * pipeline (targeting → universe holdout → holdout gate → sticky → allocation
+     * → group), merging the universe defaults under the assigned variant (§B2).
+     * Internal: the public surface is `universe(name).assign(user)`. Reused by the
+     * SSR `evaluate()` bootstrap (keyed by experiment name) and by `assignUniverse`.
+     */
+    private evalExperiment;
+    /**
+     * Assign `user` within `universeName`. A universe is a mutual-exclusion pool,
+     * so a unit lands in **at most one** experiment; the returned {@link Assignment}
+     * exposes the variant + resolved params and auto-logs a single exposure when
+     * enrolled. An un-enrolled unit still resolves `get()` to the universe defaults.
+     * Never throws. This is the sole experiment read path (there is no
+     * `getExperiment` — a caller asks a universe, not an experiment).
+     */
+    assignUniverse(universeName: string, user: User): Assignment;
+    /**
+     * The universe-first experiment read entry point:
+     * `engine.universe("checkout").assign(user)`. Returns a reusable handle bound
+     * to one universe; `assign(user)` picks the ≤1 experiment the unit is pooled
+     * into and auto-logs a single exposure. See {@link assignUniverse}.
+     */
+    universe(name: string): {
+        assign(user: User): Assignment;
+    };
     /** Drop caller-marked private attributes from an outbound props bag. */
     private stripPrivate;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
     /**
-     * Emit an exposure event for an experiment at the server-side decision point
-     * (parity with the browser's auto-exposure). The server is stateless and
-     * never auto-logs, so call this when you actually present the treatment.
-     * Re-evaluates the experiment for `user` (a bare `user_id` string is wrapped
-     * as `{ user_id }`); if the user is enrolled, POSTs a single exposure to
-     * `/collect`. No-op in test mode or when the user isn't enrolled.
+     * POST a single exposure for an enrolled `(user, experiment, group)`. Deduped
+     * per process (bounded set) so repeated `assign()` calls in one server don't
+     * spam `/collect`. Fire-and-forget; no-op in test mode. This is how
+     * `assignUniverse` auto-logs — the browser's auto-exposure parity for SSR.
      */
-    logExposure(user: string | User, name: string): void;
+    private postExposure;
     /**
      * Report a structured error into the errors primitive. Fire-and-forget —
      * never blocks or throws into the request path. Spam-guarded by a 30s
@@ -487,6 +596,13 @@ interface ShipeasyServerConfig {
      * that evaluate many flags per request. See {@link EngineOptions.disableTelemetry}.
      */
     disableTelemetry?: boolean;
+    /**
+     * Opt out of SDK-internal error self-monitoring. Internal SDK failures ("on
+     * our end") are reported to Shipeasy's own project (never yours) so we can
+     * track SDK bugs. ON by default. See
+     * {@link EngineOptions.disableInternalErrorReporting}.
+     */
+    disableInternalErrorReporting?: boolean;
     /**
      * Attribute names usable for targeting but never persisted in analytics
      * (LD/Statsig `privateAttributes`). Stripped from every outbound `track()`
@@ -582,7 +698,17 @@ declare const flags: {
     /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
     getDetail(name: string, user: User): FlagDetail;
     getConfig<T = unknown>(name: string, decodeOrOpts?: ((raw: unknown) => T) | GetConfigOptions<T>): T | undefined;
-    getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
+    /**
+     * Assign `user` within a universe: `flags.universe("checkout").assign(user)`.
+     * A universe is a mutual-exclusion pool, so the unit lands in ≤1 experiment;
+     * the returned {@link Assignment} exposes `.group` / `.get(field, fallback)`
+     * and auto-logs one exposure when enrolled. Before configure() (or on any
+     * error) it returns a safe not-enrolled handle. This replaces the removed
+     * `getExperiment` — read experiments by universe, never by name.
+     */
+    universe(name: string): {
+        assign(user: User): Assignment;
+    };
     /**
      * Read a killswitch. Without `switchKey`, returns true when the whole
      * killswitch is killed. With `switchKey`, returns true when that specific
@@ -590,9 +716,6 @@ declare const flags: {
      */
     ks(name: string, switchKey?: string): boolean;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
-    /** Emit an exposure for an enrolled experiment at the decision point. See
-     *  {@link Engine.logExposure}. No-op before configure(). */
-    logExposure(user: string | User, name: string): void;
     /**
      * Evaluate all flags / configs / experiments for a user against the locally
      * cached blob. Pass the request URL to apply ?se_ks_* / ?se_cf_* / ?se_exp_*
@@ -740,7 +863,15 @@ declare class Client<U = unknown> {
     getFlagDetail(name: string): FlagDetail;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getConfig<T = unknown>(name: string, opts: GetConfigOptions<T>): T;
-    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
+    /**
+     * Assign the bound user within a universe: `client.universe("checkout").assign()`.
+     * The user is already bound at construction, so `assign()` takes no arg. Returns
+     * an {@link Assignment} (`.group` / `.get(field, fallback)`) and auto-logs one
+     * exposure when enrolled. Replaces the removed `getExperiment`.
+     */
+    universe(name: string): {
+        assign(): Assignment;
+    };
     /** Read a killswitch (not user-bound; mirrors {@link Engine.getKillswitch}). */
     getKillswitch(name: string, switchKey?: string): boolean;
     /**
@@ -751,13 +882,6 @@ declare class Client<U = unknown> {
      * 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 {
     /**
@@ -810,4 +934,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-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, LOG_LEVELS, type LabelFile, type LogLevel, 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 };
+export { ANON_ID_COOKIE, type Assignment, 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, LOG_LEVELS, type LabelFile, type LogLevel, 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 UniverseParam, type UniverseParamSchema, 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 };