@shipeasy/sdk 5.0.0 → 5.2.0

package/dist/openfeature-web/index.d.ts

@@ -0,0 +1,332 @@
+import { Provider, EvaluationContext, Logger, ResolutionDetails, JsonValue } from '@openfeature/web-sdk';
+
+type SeeExtras = Record<string, string | number | boolean | null | undefined>;
+type SeeKind = "caught" | "uncaught" | "unhandled_rejection" | "network" | "violation";
+/** Built by `causesThe(subject).to(outcome)` — never constructed by hand. */
+interface Consequence {
+    readonly __seConsequence: true;
+    readonly subject: string;
+    readonly outcome: string;
+}
+
+declare global {
+    interface Window {
+        i18n?: {
+            t: (key: string, vars?: Record<string, string | number>) => string;
+            ready: (cb: () => void) => void;
+            on: (event: "update", cb: () => void) => () => void;
+            locale: string | null;
+        };
+    }
+}
+interface User {
+    user_id?: string;
+    [attr: string]: unknown;
+}
+interface ExperimentResult<P> {
+    inExperiment: boolean;
+    group: string;
+    params: P;
+}
+/** Options object form of `getExperiment` — the legacy `decode`/`variants`
+ *  positional args plus per-call exposure control. */
+interface GetExperimentOptions<P> {
+    /** Decode the raw stored params into the typed shape callers want. */
+    decode?: (raw: unknown) => P;
+    /** Variant-specific param overrides merged on top of group params. */
+    variants?: Record<string, Partial<P>>;
+    /**
+     * Override automatic exposure logging for this read. Defaults to the client's
+     * setting (`disableAutoExposure` flips it). `false` reads the variant without
+     * logging an exposure — pair with `logExposure(name)` at render time.
+     */
+    logExposure?: boolean;
+}
+/**
+ * Why a flag evaluated the way it did (LaunchDarkly variationDetail parity).
+ * Computed at the client boundary:
+ *   - CLIENT_NOT_READY — no eval result yet (identify() hasn't resolved)
+ *   - FLAG_NOT_FOUND   — the gate name isn't present in the eval result
+ *   - OFF              — folded into DEFAULT here (the server pre-evaluates the
+ *     gate's enabled/killed state into a plain boolean, so the browser can't
+ *     distinguish a disabled gate from one a rule denied)
+ *   - OVERRIDE         — a local override or a ?se_gate_/?se_ks_ URL override
+ *     decided the value
+ *   - RULE_MATCH       — the gate evaluated true
+ *   - DEFAULT          — the gate evaluated false
+ */
+declare const FLAG_REASONS: readonly ["CLIENT_NOT_READY", "FLAG_NOT_FOUND", "OFF", "OVERRIDE", "RULE_MATCH", "DEFAULT"];
+type FlagReason = (typeof FLAG_REASONS)[number];
+interface FlagDetail {
+    value: boolean;
+    reason: FlagReason;
+}
+/** Options object form of `getConfig` — keeps the legacy `decode` callback and
+ *  adds a `defaultValue` returned when the config key is absent. */
+interface GetConfigOptions<T = unknown> {
+    /** Decode the raw stored value into the typed shape callers want. */
+    decode?: (raw: unknown) => T;
+    /** Returned when the config key is absent (not overridden, not in the eval result). */
+    defaultValue?: T;
+}
+interface EvalExpResult {
+    inExperiment: boolean;
+    group: string;
+    params: Record<string, unknown>;
+}
+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>>;
+    /**
+     * Newly-assigned sticky entries (doc 20 §2). The worker returns these so the
+     * browser can merge them into the `__se_sticky` cookie. Present only when
+     * sticky bucketing is on and at least one assignment was made/refreshed.
+     */
+    sticky?: Record<string, StickyCookieEntry>;
+}
+/** One persisted sticky assignment: group + 8-char salt prefix (reshuffle key). */
+interface StickyCookieEntry {
+    g: string;
+    s: string;
+}
+interface AutoCollectGroups {
+    vitals: boolean;
+    errors: boolean;
+    engagement: boolean;
+}
+type FlagsClientBrowserEnv = "dev" | "staging" | "prod";
+interface FlagsClientBrowserOptions {
+    sdkKey: string;
+    baseUrl?: string;
+    autoGuardrails?: boolean;
+    /**
+     * Per-group enablement for auto-collected metrics. When set, overrides the
+     * blanket `autoGuardrails` flag for the specific groups listed. Any group
+     * not present in the object falls back to `autoGuardrails` (defaulting to
+     * true when `autoGuardrails` is true).
+     */
+    autoGuardrailGroups?: Partial<AutoCollectGroups>;
+    /**
+     * Emit `__auto_*` metric events for ALL visitors, not just experiment
+     * participants. Default false: auto-metrics are gated on the visitor having
+     * seen ≥1 experiment exposure (the only data the analysis pipeline reads;
+     * ungated emission is pure AE write cost at scale — see cost.md).
+     */
+    autoCollectAlways?: boolean;
+    /** Which published env to read values from. Defaults to "prod". */
+    env?: FlagsClientBrowserEnv;
+    /**
+     * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
+     * getExperiment/getKillswitch call fires one fire-and-forget sendBeacon so
+     * usage is counted by Cloudflare's native per-path analytics. Pass `true` to
+     * disable entirely.
+     */
+    disableTelemetry?: boolean;
+    /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
+    telemetryUrl?: string;
+    /**
+     * Suppress automatic exposure logging in `getExperiment` (Statsig's
+     * `disableExposureLogging`). Default false — reading an enrolled variant
+     * auto-logs a deduped exposure. When true, no exposure fires unless you call
+     * `logExposure(name)` yourself, or pass `{ logExposure: true }` per call.
+     */
+    disableAutoExposure?: boolean;
+    /**
+     * Attribute names usable for targeting but never persisted in analytics
+     * (LD/Statsig `privateAttributes`). They are sent to `/sdk/evaluate` under
+     * `private_attributes` so the edge can evaluate with them (unavoidable —
+     * the edge evaluates), but the worker never stores them, and the listed keys
+     * are stripped from any `track(props)` payload.
+     */
+    privateAttributes?: string[];
+    /**
+     * Sticky bucketing (doc 20 §2). ON by default in the browser: a unit's
+     * first-assigned variant is locked in the `__se_sticky` cookie so changing an
+     * experiment's allocation % or group weights never silently re-buckets
+     * enrolled users. Changing the experiment salt is the deliberate reshuffle
+     * lever. Pass `false` to opt out (pure deterministic eval).
+     */
+    stickyBucketing?: boolean;
+    /**
+     * Test mode — no network at all. identify()/init are no-ops (never call
+     * /sdk/evaluate), track() is a no-op, telemetry is forced off, and the client
+     * starts "ready" with an empty eval result. Prefer the
+     * {@link FlagsClientBrowser.forTesting} factory over passing this directly.
+     */
+    testMode?: boolean;
+}
+declare class FlagsClientBrowser {
+    private readonly sdkKey;
+    private readonly baseUrl;
+    private readonly autoGuardrails;
+    private readonly autoGuardrailGroups;
+    private readonly autoCollectAlways;
+    private readonly disableAutoExposure;
+    private readonly privateAttributes;
+    private readonly stickyBucketing;
+    private readonly env;
+    private evalResult;
+    private anonId;
+    private userId;
+    private buffer;
+    private telemetry;
+    private seeLimiter;
+    private guardrailsInstalled;
+    private listeners;
+    private overrideListenerInstalled;
+    private identifySeq;
+    private readonly testMode;
+    private readonly flagOverrides;
+    private readonly configOverrides;
+    private readonly experimentOverrides;
+    private onOverrideChange;
+    constructor(opts: FlagsClientBrowserOptions);
+    /**
+     * Build a no-network, immediately-usable browser client for tests
+     * (Statsig-style). identify() is a no-op (never calls /sdk/evaluate), track()
+     * is a no-op, telemetry is disabled, and the client is already ready — seed
+     * every entity with overrideFlag/overrideConfig/overrideExperiment. No SDK
+     * key required.
+     *
+     * ```ts
+     * const client = FlagsClientBrowser.forTesting();
+     * client.overrideFlag("new_checkout", true);
+     * client.getFlag("new_checkout"); // true
+     * ```
+     */
+    static forTesting(opts?: Partial<FlagsClientBrowserOptions>): FlagsClientBrowser;
+    identify(user: User): Promise<void>;
+    /**
+     * Report a structured error into the errors primitive. Flushes immediately
+     * (beacon-first) — error occurrences are near-real-time, never queued behind
+     * the 5s metric batch. Spam-guarded by a 30s dedup window + per-session cap.
+     */
+    reportError(problem: unknown, consequence: Consequence, extras?: SeeExtras, kind?: SeeKind, correlationId?: string): void;
+    get ready(): boolean;
+    private notify;
+    initFromBootstrap(data: EvalResponse): void;
+    /** Force `getFlag(name)` to return `value`, ignoring URL overrides + eval. */
+    overrideFlag(name: string, value: boolean): void;
+    /** Force `getConfig(name)` to return `value`, ignoring URL overrides + eval. */
+    overrideConfig(name: string, value: unknown): void;
+    /**
+     * Force `getExperiment(name, …)` to return `{ inExperiment: true, group, params }`,
+     * ignoring URL overrides, the eval result, and exposure logging.
+     */
+    overrideExperiment(name: string, group: string, params: Record<string, unknown>): void;
+    /** Remove every programmatic override set via the override* methods. */
+    clearOverrides(): void;
+    /**
+     * Evaluate a gate and report WHY (LaunchDarkly variationDetail parity). A
+     * local override OR a ?se_gate_/?se_ks_ URL override short-circuits BEFORE
+     * telemetry; otherwise exactly one "gate" beacon is emitted. The server
+     * pre-evaluates a gate's enabled/killed state into a plain boolean, so OFF
+     * folds into DEFAULT here (the browser can't tell "disabled" from "rule
+     * denied").
+     */
+    getFlagDetail(name: string): FlagDetail;
+    /**
+     * Read a feature gate. Returns `defaultValue` ONLY when the gate cannot be
+     * evaluated (not ready or flag not found) — never for a gate that legitimately
+     * evaluates to false. Plain `getFlag(name)` keeps returning false for a
+     * missing flag.
+     */
+    getFlag(name: string, 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, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
+    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, opts: GetExperimentOptions<P>): ExperimentResult<P>;
+    /**
+     * Manually log an exposure for an enrolled experiment (Statsig's
+     * `manuallyLogExposure`). Reads the cached eval result; if the visitor is in
+     * the experiment, pushes the session-deduped exposure. Pair this with the
+     * render of the treatment when reading with `{ logExposure: false }` (or
+     * `disableAutoExposure: true`). No-op if the visitor isn't enrolled.
+     */
+    logExposure(name: string): void;
+    /**
+     * Subscribe to state changes — fires after identify() completes and on
+     * `se:override:change` events from the devtools overlay. Returns an
+     * unsubscribe function. Used by framework adapters to trigger re-renders.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Publishes the SDK to `window.__shipeasy` so the devtools overlay can read
+     * current values. Idempotent. Returns the bridge object for tests.
+     */
+    installBridge(): ShipeasySdkBridge | null;
+    track(eventName: string, props?: Record<string, unknown>): void;
+    /** Drop caller-marked private attributes from an outbound props bag. */
+    private stripPrivate;
+    /**
+     * 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;
+}
+/** Bridge written to window.__shipeasy — mirrors @shipeasy/devtools' contract. */
+interface ShipeasySdkBridge {
+    getFlag(name: string): boolean;
+    getExperiment(name: string): {
+        inExperiment: boolean;
+        group: string;
+    } | undefined;
+    getConfig(name: string): unknown;
+}
+
+/**
+ * OpenFeature **web** provider for Shipeasy.
+ *
+ * ```ts
+ * import { OpenFeature } from "@openfeature/web-sdk";
+ * import { FlagsClientBrowser } from "@shipeasy/sdk/client";
+ * import { ShipeasyProvider } from "@shipeasy/sdk/openfeature-web";
+ *
+ * const client = new FlagsClientBrowser({ sdkKey: NEXT_PUBLIC_SHIPEASY_CLIENT_KEY });
+ * await OpenFeature.setContext({ targetingKey: "u1", plan: "pro" });
+ * await OpenFeature.setProviderAndWait(new ShipeasyProvider(client));
+ *
+ * const on = OpenFeature.getClient().getBooleanValue("new_checkout", false);
+ * ```
+ *
+ * The browser evaluates at the edge, so the provider maps OpenFeature's static
+ * context onto `client.identify()` (via `initialize` + `onContextChange`) and
+ * reads the cached eval result synchronously in the resolve methods.
+ * `@openfeature/web-sdk` is an optional peer dependency.
+ */
+
+/**
+ * Shipeasy OpenFeature provider (client/web paradigm). Wraps a
+ * `FlagsClientBrowser`. Context changes are reconciled through `identify()`;
+ * flag reads come from the cached eval result.
+ */
+declare class ShipeasyProvider implements Provider {
+    private readonly client;
+    readonly metadata: {
+        readonly name: "shipeasy";
+    };
+    readonly runsOn: "client";
+    constructor(client: FlagsClientBrowser);
+    /** Identify with the initial static context so the first read is warm. */
+    initialize(context?: EvaluationContext): Promise<void>;
+    /** Re-identify when the application author changes the static context. */
+    onContextChange(_old: EvaluationContext, next: EvaluationContext): Promise<void>;
+    resolveBooleanEvaluation(flagKey: string, defaultValue: boolean, _context: EvaluationContext, _logger?: Logger): ResolutionDetails<boolean>;
+    resolveStringEvaluation(flagKey: string, defaultValue: string, _context: EvaluationContext, _logger?: Logger): ResolutionDetails<string>;
+    resolveNumberEvaluation(flagKey: string, defaultValue: number, _context: EvaluationContext, _logger?: Logger): ResolutionDetails<number>;
+    resolveObjectEvaluation<T extends JsonValue>(flagKey: string, defaultValue: T, _context: EvaluationContext, _logger?: Logger): ResolutionDetails<T>;
+    /** OpenFeature `track()` → Shipeasy `track()` (uses the identified user/anon). */
+    track(trackingEventName: string, _context: EvaluationContext, details?: Record<string, unknown>): void;
+}
+
+export { ShipeasyProvider };

package/dist/openfeature-web/index.js

@@ -0,0 +1,120 @@
+"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/openfeature-web/index.ts
+var openfeature_web_exports = {};
+__export(openfeature_web_exports, {
+  ShipeasyProvider: () => ShipeasyProvider
+});
+module.exports = __toCommonJS(openfeature_web_exports);
+var import_web_sdk = require("@openfeature/web-sdk");
+
+// src/openfeature/shared.ts
+var REASON_MAP = {
+  RULE_MATCH: { reason: "TARGETING_MATCH" },
+  DEFAULT: { reason: "DEFAULT" },
+  OFF: { reason: "DISABLED" },
+  OVERRIDE: { reason: "STATIC" },
+  FLAG_NOT_FOUND: { reason: "ERROR", errorCode: "FLAG_NOT_FOUND" },
+  CLIENT_NOT_READY: { reason: "ERROR", errorCode: "PROVIDER_NOT_READY" }
+};
+function mapFlagReason(reason) {
+  return REASON_MAP[reason] ?? { reason: "UNKNOWN" };
+}
+function toUser(ctx) {
+  if (!ctx) return {};
+  const { targetingKey, ...rest } = ctx;
+  const user = { ...rest };
+  if (typeof targetingKey === "string" && targetingKey.length > 0) {
+    user.user_id = targetingKey;
+  }
+  return user;
+}
+function resolveConfigValue(raw, type) {
+  if (raw === void 0) return { kind: "default" };
+  const ok = type === "object" ? typeof raw === "object" && raw !== null : typeof raw === type;
+  if (!ok) {
+    return {
+      kind: "type_mismatch",
+      message: `flag value ${JSON.stringify(raw)} is not of type ${type}`
+    };
+  }
+  return { kind: "match", value: raw };
+}
+
+// src/openfeature-web/index.ts
+var ERROR_CODE = {
+  FLAG_NOT_FOUND: import_web_sdk.ErrorCode.FLAG_NOT_FOUND,
+  PROVIDER_NOT_READY: import_web_sdk.ErrorCode.PROVIDER_NOT_READY,
+  TYPE_MISMATCH: import_web_sdk.ErrorCode.TYPE_MISMATCH
+};
+function resolveConfig(raw, defaultValue, type) {
+  const r = resolveConfigValue(raw, type);
+  if (r.kind === "default") return { value: defaultValue, reason: "DEFAULT" };
+  if (r.kind === "type_mismatch") {
+    return {
+      value: defaultValue,
+      reason: "ERROR",
+      errorCode: ERROR_CODE.TYPE_MISMATCH,
+      errorMessage: r.message
+    };
+  }
+  return { value: r.value, reason: "TARGETING_MATCH" };
+}
+var ShipeasyProvider = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  metadata = { name: "shipeasy" };
+  runsOn = "client";
+  /** Identify with the initial static context so the first read is warm. */
+  async initialize(context) {
+    await this.client.identify(toUser(context));
+  }
+  /** Re-identify when the application author changes the static context. */
+  async onContextChange(_old, next) {
+    await this.client.identify(toUser(next));
+  }
+  resolveBooleanEvaluation(flagKey, defaultValue, _context, _logger) {
+    const detail = this.client.getFlagDetail(flagKey);
+    const m = mapFlagReason(detail.reason);
+    if (m.errorCode) {
+      return { value: defaultValue, reason: m.reason, errorCode: ERROR_CODE[m.errorCode] };
+    }
+    return { value: detail.value, reason: m.reason };
+  }
+  resolveStringEvaluation(flagKey, defaultValue, _context, _logger) {
+    return resolveConfig(this.client.getConfig(flagKey), defaultValue, "string");
+  }
+  resolveNumberEvaluation(flagKey, defaultValue, _context, _logger) {
+    return resolveConfig(this.client.getConfig(flagKey), defaultValue, "number");
+  }
+  resolveObjectEvaluation(flagKey, defaultValue, _context, _logger) {
+    return resolveConfig(this.client.getConfig(flagKey), defaultValue, "object");
+  }
+  /** OpenFeature `track()` → Shipeasy `track()` (uses the identified user/anon). */
+  track(trackingEventName, _context, details) {
+    this.client.track(trackingEventName, details);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ShipeasyProvider
+});

package/dist/openfeature-web/index.mjs

@@ -0,0 +1,95 @@
+// src/openfeature-web/index.ts
+import { ErrorCode } from "@openfeature/web-sdk";
+
+// src/openfeature/shared.ts
+var REASON_MAP = {
+  RULE_MATCH: { reason: "TARGETING_MATCH" },
+  DEFAULT: { reason: "DEFAULT" },
+  OFF: { reason: "DISABLED" },
+  OVERRIDE: { reason: "STATIC" },
+  FLAG_NOT_FOUND: { reason: "ERROR", errorCode: "FLAG_NOT_FOUND" },
+  CLIENT_NOT_READY: { reason: "ERROR", errorCode: "PROVIDER_NOT_READY" }
+};
+function mapFlagReason(reason) {
+  return REASON_MAP[reason] ?? { reason: "UNKNOWN" };
+}
+function toUser(ctx) {
+  if (!ctx) return {};
+  const { targetingKey, ...rest } = ctx;
+  const user = { ...rest };
+  if (typeof targetingKey === "string" && targetingKey.length > 0) {
+    user.user_id = targetingKey;
+  }
+  return user;
+}
+function resolveConfigValue(raw, type) {
+  if (raw === void 0) return { kind: "default" };
+  const ok = type === "object" ? typeof raw === "object" && raw !== null : typeof raw === type;
+  if (!ok) {
+    return {
+      kind: "type_mismatch",
+      message: `flag value ${JSON.stringify(raw)} is not of type ${type}`
+    };
+  }
+  return { kind: "match", value: raw };
+}
+
+// src/openfeature-web/index.ts
+var ERROR_CODE = {
+  FLAG_NOT_FOUND: ErrorCode.FLAG_NOT_FOUND,
+  PROVIDER_NOT_READY: ErrorCode.PROVIDER_NOT_READY,
+  TYPE_MISMATCH: ErrorCode.TYPE_MISMATCH
+};
+function resolveConfig(raw, defaultValue, type) {
+  const r = resolveConfigValue(raw, type);
+  if (r.kind === "default") return { value: defaultValue, reason: "DEFAULT" };
+  if (r.kind === "type_mismatch") {
+    return {
+      value: defaultValue,
+      reason: "ERROR",
+      errorCode: ERROR_CODE.TYPE_MISMATCH,
+      errorMessage: r.message
+    };
+  }
+  return { value: r.value, reason: "TARGETING_MATCH" };
+}
+var ShipeasyProvider = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  metadata = { name: "shipeasy" };
+  runsOn = "client";
+  /** Identify with the initial static context so the first read is warm. */
+  async initialize(context) {
+    await this.client.identify(toUser(context));
+  }
+  /** Re-identify when the application author changes the static context. */
+  async onContextChange(_old, next) {
+    await this.client.identify(toUser(next));
+  }
+  resolveBooleanEvaluation(flagKey, defaultValue, _context, _logger) {
+    const detail = this.client.getFlagDetail(flagKey);
+    const m = mapFlagReason(detail.reason);
+    if (m.errorCode) {
+      return { value: defaultValue, reason: m.reason, errorCode: ERROR_CODE[m.errorCode] };
+    }
+    return { value: detail.value, reason: m.reason };
+  }
+  resolveStringEvaluation(flagKey, defaultValue, _context, _logger) {
+    return resolveConfig(this.client.getConfig(flagKey), defaultValue, "string");
+  }
+  resolveNumberEvaluation(flagKey, defaultValue, _context, _logger) {
+    return resolveConfig(this.client.getConfig(flagKey), defaultValue, "number");
+  }
+  resolveObjectEvaluation(flagKey, defaultValue, _context, _logger) {
+    return resolveConfig(this.client.getConfig(flagKey), defaultValue, "object");
+  }
+  /** OpenFeature `track()` → Shipeasy `track()` (uses the identified user/anon). */
+  track(trackingEventName, _context, details) {
+    this.client.track(trackingEventName, details);
+  }
+};
+export {
+  ShipeasyProvider
+};