@shipeasy/sdk 5.3.0 → 6.0.0

package/dist/server/index.d.ts

@@ -181,7 +181,7 @@ interface StickyEntry {
 /**
  * Pluggable sticky-bucketing store for the server (doc 20 §2). Keyed by the
  * bucketing unit; the value is that unit's per-experiment assignments. Absent
- * from {@link FlagsClientOptions} ⇒ today's deterministic behaviour. Use
+ * from {@link EngineOptions} ⇒ today's deterministic behaviour. Use
  * {@link createInMemoryStickyStore} or a cookie-bridge built from request
  * cookies.
  */
@@ -198,7 +198,7 @@ interface Killswitch {
     killed: 0 | 1 | boolean;
     switches?: Record<string, 0 | 1 | boolean>;
 }
-/** Body of `GET /sdk/flags` — the snapshot's `flags` field. See {@link FlagsClient.fromSnapshot}. */
+/** Body of `GET /sdk/flags` — the snapshot's `flags` field. See {@link Engine.fromSnapshot}. */
 interface FlagsBlob {
     version: string;
     plan: string;
@@ -208,7 +208,7 @@ interface FlagsBlob {
     }>;
     killswitches: Record<string, Killswitch>;
 }
-/** Body of `GET /sdk/experiments` — the snapshot's `experiments` field. See {@link FlagsClient.fromSnapshot}. */
+/** Body of `GET /sdk/experiments` — the snapshot's `experiments` field. See {@link Engine.fromSnapshot}. */
 interface ExpsBlob {
     version: string;
     universes: Record<string, Universe>;
@@ -221,12 +221,12 @@ interface BootstrapPayload {
     killswitches: Record<string, boolean | Record<string, boolean>>;
 }
 declare const ANON_ID_COOKIE = "__se_anon_id";
-type FlagsClientEnv = "dev" | "staging" | "prod";
-interface FlagsClientOptions {
+type EngineEnv = "dev" | "staging" | "prod";
+interface EngineOptions {
     apiKey: string;
     baseUrl?: string;
     /** Which published env to read values from. Defaults to "prod". */
-    env?: FlagsClientEnv;
+    env?: EngineEnv;
     /**
      * Preload the flags blob synchronously without a network fetch. Primarily
      * for tests; production callers should rely on init()/initOnce().
@@ -261,12 +261,12 @@ interface FlagsClientOptions {
     /**
      * Test mode — no network at all. init()/initOnce() are no-ops (never fetch),
      * track() is a no-op, telemetry is forced off, and the client starts
-     * "initialized" with an empty blob. Prefer the {@link FlagsClient.forTesting}
+     * "initialized" with an empty blob. Prefer the {@link Engine.forTesting}
      * factory over passing this directly.
      */
     testMode?: boolean;
 }
-declare class FlagsClient {
+declare class Engine {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly env;
@@ -286,7 +286,7 @@ declare class FlagsClient {
     private readonly configOverrides;
     private readonly experimentOverrides;
     private readonly changeListeners;
-    constructor(opts: FlagsClientOptions);
+    constructor(opts: EngineOptions);
     /**
      * Build a no-network, immediately-usable client for tests (Statsig-style).
      * init()/initOnce() are no-ops (never fetch), track() is a no-op, telemetry
@@ -294,12 +294,12 @@ declare class FlagsClient {
      * with overrideFlag/overrideConfig/overrideExperiment. No SDK key required.
      *
      * ```ts
-     * const client = FlagsClient.forTesting();
+     * const client = Engine.forTesting();
      * client.overrideFlag("new_checkout", true);
      * client.getFlag("new_checkout", { user_id: "u1" }); // true
      * ```
      */
-    static forTesting(opts?: Partial<FlagsClientOptions>): FlagsClient;
+    static forTesting(opts?: Partial<EngineOptions>): Engine;
     /**
      * Build a fully OFFLINE client from a pre-captured snapshot — no network ever.
      * Reuses the test-mode plumbing (init()/initOnce()/track() are no-ops,
@@ -313,14 +313,14 @@ declare class FlagsClient {
     static fromSnapshot(snapshot: {
         flags: FlagsBlob;
         experiments: ExpsBlob;
-    }): FlagsClient;
+    }): Engine;
     /**
      * Build a fully OFFLINE client from a snapshot JSON file on disk (Node only —
      * not available in the browser entrypoint). The file must contain
      * `{ "flags": <GET /sdk/flags body>, "experiments": <GET /sdk/experiments body> }`.
-     * See {@link FlagsClient.fromSnapshot}.
+     * See {@link Engine.fromSnapshot}.
      */
-    static fromFile(path: string): FlagsClient;
+    static fromFile(path: string): Engine;
     init(): Promise<void>;
     initOnce(): Promise<void>;
     /** Force `getFlag(name, …)` to return `value`, ignoring the fetched gate. */
@@ -440,8 +440,8 @@ interface FetchLabelsOptions {
     timeoutMs?: number;
 }
 declare function fetchLabelsForSSR(opts: FetchLabelsOptions): Promise<LabelFile | null>;
-declare function configureShipeasyServer(opts: FlagsClientOptions): FlagsClient;
-declare function getShipeasyServerClient(): FlagsClient | null;
+declare function configureShipeasyServer(opts: EngineOptions): Engine;
+declare function getShipeasyServerClient(): Engine | null;
 declare function _resetShipeasyServerForTests(): void;
 interface ShipeasyServerConfig {
     /**
@@ -463,13 +463,13 @@ interface ShipeasyServerConfig {
     /**
      * Disable per-evaluation usage telemetry. ON by default. On Cloudflare
      * Workers each beacon is an outbound subrequest, so disable on hot SSR paths
-     * that evaluate many flags per request. See {@link FlagsClientOptions.disableTelemetry}.
+     * that evaluate many flags per request. See {@link EngineOptions.disableTelemetry}.
      */
     disableTelemetry?: boolean;
     /**
      * Attribute names usable for targeting but never persisted in analytics
      * (LD/Statsig `privateAttributes`). Stripped from every outbound `track()`
-     * payload. See {@link FlagsClientOptions.privateAttributes}.
+     * payload. See {@link EngineOptions.privateAttributes}.
      */
     privateAttributes?: string[];
 }
@@ -477,8 +477,22 @@ interface ShipeasyServerHandle {
     flags: Record<string, boolean>;
     configs: Record<string, unknown>;
     experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
-    /** Returns a vanilla-JS string for a single inline <script> tag. */
-    getBootstrapHtml(): string;
+    /**
+     * Structured `<script>` tag specs to drop into the document head: the
+     * cross-platform `se-bootstrap.js` tag (hydrates window.__SE_BOOTSTRAP +
+     * writes the anon cookie) and, when there are SSR strings or a client key,
+     * the i18n loader tag. Use this in React: scripts inserted via
+     * `dangerouslySetInnerHTML` do NOT execute, so render real `<script>`
+     * elements from these specs (see apps/ui root layout).
+     */
+    getBootstrapData(emit?: BootstrapEmitOptions): BootstrapData;
+    /**
+     * The same tags rendered as an HTML string, for non-React SSR (Express, raw
+     * templates) where the markup is emitted directly into the served HTML (and
+     * therefore executes normally). This is the canonical cross-platform shape
+     * every server SDK mirrors.
+     */
+    getBootstrapTags(emit?: BootstrapEmitOptions): string;
 }
 /**
  * Initialise the ShipEasy server SDK, evaluate flags for this request, and
@@ -487,37 +501,53 @@ interface ShipeasyServerHandle {
  * payloads and i18n falls back to hardcoded strings.
  */
 declare function shipeasy(opts: ShipeasyServerConfig): Promise<ShipeasyServerHandle>;
-interface BootstrapHtmlOptions {
-    /** i18n profile recorded in the bootstrap so the client loader matches SSR. Defaults to "en:prod". */
+interface BootstrapEmitOptions {
+    /** i18n profile recorded on both tags so the client loader matches SSR. Defaults to "en:prod". */
     i18nProfile?: string;
-    /** When true, tEl() embeds label markers so the devtools can highlight them. */
-    editLabels?: boolean;
     /**
-     * Stable anonymous bucketing id the server evaluated against. Emitted into
-     * window.__SE_BOOTSTRAP and persisted (pre-paint) to the first-party
-     * `__se_anon_id` cookie, so the browser SDK buckets identically to SSR.
-     * Normally minted by edge middleware; this write is the fallback for routes
-     * middleware doesn't cover. See experiment-platform/18-identity-bucketing.md.
+     * Stable anonymous bucketing id the server evaluated against. Emitted as
+     * `data-anon-id`; se-bootstrap.js exposes it on window.__SE_BOOTSTRAP and
+     * persists it (pre-paint) to the first-party `__se_anon_id` cookie, so the
+     * browser SDK buckets identically to SSR. Normally minted by edge
+     * middleware; this is the fallback for routes it doesn't cover. See
+     * experiment-platform/18-identity-bucketing.md.
      */
     anonId?: string;
+    /**
+     * Public client key. When provided, the i18n loader tag can revalidate
+     * strings at runtime (`data-key`). Optional — the bootstrap tag NEVER carries
+     * a key, and SSR first paint works keyless via `data-strings`.
+     */
+    clientKey?: string;
+    /** CDN base for the tag `src`s. Defaults to https://cdn.shipeasy.ai. */
+    baseUrl?: string;
+}
+interface ScriptTagSpec {
+    src: string;
+    /** Attribute name → value. An empty-string value renders as a bare boolean attribute (e.g. `data-se-bootstrap`). */
+    attrs: Record<string, string>;
+}
+interface BootstrapData {
+    /** se-bootstrap.js tag — always present. */
+    bootstrap: ScriptTagSpec;
+    /** i18n loader tag — null when there are no SSR strings and no client key. */
+    i18nLoader: ScriptTagSpec | null;
 }
 /**
- * Returns a vanilla-JS string for a single inline <script> tag. Handles
- * everything the client needs at startup EXCEPT the key — no SDK key is ever
- * embedded here (the server only knows the server key, which must stay
- * server-side). The browser supplies its own client key via
- * `shipeasy({ clientKey })` from @shipeasy/sdk/client, which also injects the
- * runtime i18n loader. This script emits:
- *   - window.__se_devtools_config (when devtoolsAdminUrl is set)
- *   - window.__SE_BOOTSTRAP (flags + configs + experiments + i18n DATA + i18nProfile, NO key)
- *   - window.i18n shim from SSR strings (prevents hydration mismatches / FOUC)
- *   - devtools overlay loader when ?se / ?se_devtools is present
- *
- * Framework-agnostic: set innerHTML on a <script> element, nothing else required.
+ * Build the structured `<script>` tag specs for the SSR bootstrap. Render
+ * these as REAL `<script>` elements (React: scripts set via innerHTML do not
+ * execute). No SDK key is ever embedded in the bootstrap tag.
  */
-declare function getBootstrapHtml(bootstrap: BootstrapPayload | null, i18nData: I18nForRequest | null, opts: BootstrapHtmlOptions): string;
+declare function getBootstrapData(bootstrap: BootstrapPayload | null, i18nData: I18nForRequest | null, opts: BootstrapEmitOptions): BootstrapData;
+/**
+ * The bootstrap (and optional i18n loader) tags as an HTML string, for non-React
+ * SSR (Express, raw templates) where the markup is emitted directly into the
+ * served HTML and executes normally. React callers should use
+ * {@link getBootstrapData} and render real `<script>` elements instead.
+ */
+declare function getBootstrapTags(bootstrap: BootstrapPayload | null, i18nData: I18nForRequest | null, opts: BootstrapEmitOptions): string;
 declare const flags: {
-    configure(opts: FlagsClientOptions): void;
+    configure(opts: EngineOptions): void;
     /**
      * Long-running server: starts the background poll. Call once at app boot.
      * Throws if the initial fetch fails (caller decides whether to crash or degrade).
@@ -540,7 +570,7 @@ 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 FlagsClient.logExposure}. No-op before configure(). */
+     *  {@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
@@ -549,6 +579,65 @@ declare const flags: {
      */
     evaluate(user: User, rawUrl?: string): BootstrapPayload;
 };
+/** Transform YOUR application's user object into Shipeasy targeting attributes. */
+type AttributesFn<U = unknown> = (user: U) => User;
+interface ConfigureOptions<U = unknown> extends Omit<EngineOptions, "apiKey"> {
+    /** Server key — the single key the server side accepts (SHIPEASY_SERVER_KEY). */
+    apiKey: string;
+    /**
+     * Map your own user object into the attribute bag every flag/experiment
+     * evaluation sees. Runs once per `new Client(user)`. Omit when you already
+     * pass a plain attribute object (identity transform — the object is used
+     * verbatim, so it should carry `user_id`/`anonymous_id` + any targeting attrs).
+     */
+    attributes?: AttributesFn<U>;
+}
+/**
+ * Configure the SDK once at app boot, then evaluate per user with
+ * `new Client(user)`. Builds the process-wide {@link Engine} (polling + blob
+ * cache + HTTP) and registers the `attributes` transform. The first call wins;
+ * later calls return the existing engine (mirrors {@link configureShipeasyServer}).
+ *
+ * ```ts
+ * import { configure, Client } from "@shipeasy/sdk/server";
+ *
+ * configure({
+ *   apiKey: process.env.SHIPEASY_SERVER_KEY!,
+ *   attributes: (u: MyUser) => ({ user_id: u.id, plan: u.plan, country: u.geo.country }),
+ * });
+ *
+ * const flags = new Client(currentUser);
+ * if (flags.getFlag("new_checkout")) { ... }
+ * ```
+ */
+declare function configure<U = unknown>(opts: ConfigureOptions<U>): Engine;
+/** Test seam: reset the registered attribute transform. */
+declare function _resetConfigureForTests(): 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
+ * open its own connection or poll. The configured `attributes` transform runs
+ * once here, so every getFlag/getConfig/getExperiment reads the same bag.
+ *
+ * ```ts
+ * const flags = new Client(req.user);
+ * flags.getFlag("new_checkout");                  // no user arg — bound at construction
+ * flags.getExperiment("price_test", { price: 9 });
+ * ```
+ */
+declare class Client<U = unknown> {
+    private readonly engine;
+    /** The resolved attribute bag this handle evaluates against. */
+    readonly attributes: User;
+    constructor(user: U);
+    getFlag(name: string, defaultValue?: boolean): boolean;
+    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>;
+    /** Read a killswitch (not user-bound; mirrors {@link Engine.getKillswitch}). */
+    getKillswitch(name: string, switchKey?: string): boolean;
+}
 interface SeeApi {
     /**
      * Report a handled problem and its product consequence:
@@ -600,4 +689,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type ExpsBlob, FLAG_REASONS, type FetchLabelsOptions, type FlagDetail, type FlagReason, type FlagsBlob, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type GetConfigOptions, type I18nForRequest, type LabelFile, 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, _resetShipeasyServerForTests, configureShipeasyServer, createInMemoryStickyStore, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };
+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 };

package/dist/server/index.js

@@ -31,15 +31,19 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var server_exports = {};
 __export(server_exports, {
   ANON_ID_COOKIE: () => ANON_ID_COOKIE,
+  Client: () => Client,
+  Engine: () => Engine,
   FLAG_REASONS: () => FLAG_REASONS,
-  FlagsClient: () => FlagsClient,
   _murmur3ForTests: () => _murmur3ForTests,
+  _resetConfigureForTests: () => _resetConfigureForTests,
   _resetShipeasyServerForTests: () => _resetShipeasyServerForTests,
+  configure: () => configure,
   configureShipeasyServer: () => configureShipeasyServer,
   createInMemoryStickyStore: () => createInMemoryStickyStore,
   fetchLabelsForSSR: () => fetchLabelsForSSR,
   flags: () => flags,
-  getBootstrapHtml: () => getBootstrapHtml,
+  getBootstrapData: () => getBootstrapData,
+  getBootstrapTags: () => getBootstrapTags,
   getShipeasyServerClient: () => getShipeasyServerClient,
   i18n: () => i18n,
   isExpected: () => isExpected,
@@ -542,7 +546,7 @@ function parseOverrides(rawUrl) {
   }
   return { gates, configs, experiments };
 }
-var FlagsClient = class _FlagsClient {
+var Engine = class _Engine {
   apiKey;
   baseUrl;
   env;
@@ -557,7 +561,7 @@ var FlagsClient = class _FlagsClient {
   pollInterval = 30;
   timer = null;
   initialized = false;
-  // Test mode: built by `FlagsClient.forTesting()`. When set, init()/initOnce()
+  // Test mode: built by `Engine.forTesting()`. When set, init()/initOnce()
   // never fetch, track() is a no-op, and telemetry is off — the client is a
   // fully self-contained, network-free seam for unit tests.
   testMode;
@@ -598,13 +602,13 @@ var FlagsClient = class _FlagsClient {
    * with overrideFlag/overrideConfig/overrideExperiment. No SDK key required.
    *
    * ```ts
-   * const client = FlagsClient.forTesting();
+   * const client = Engine.forTesting();
    * client.overrideFlag("new_checkout", true);
    * client.getFlag("new_checkout", { user_id: "u1" }); // true
    * ```
    */
   static forTesting(opts) {
-    return new _FlagsClient({ apiKey: "", ...opts, testMode: true });
+    return new _Engine({ apiKey: "", ...opts, testMode: true });
   }
   /**
    * Build a fully OFFLINE client from a pre-captured snapshot — no network ever.
@@ -617,7 +621,7 @@ var FlagsClient = class _FlagsClient {
    * `{ flags: <GET /sdk/flags body>, experiments: <GET /sdk/experiments body> }`.
    */
   static fromSnapshot(snapshot) {
-    const client = new _FlagsClient({ apiKey: "", testMode: true });
+    const client = new _Engine({ apiKey: "", testMode: true });
     client.flagsBlob = snapshot.flags;
     client.expsBlob = snapshot.experiments;
     client.initialized = true;
@@ -627,13 +631,13 @@ var FlagsClient = class _FlagsClient {
    * Build a fully OFFLINE client from a snapshot JSON file on disk (Node only —
    * not available in the browser entrypoint). The file must contain
    * `{ "flags": <GET /sdk/flags body>, "experiments": <GET /sdk/experiments body> }`.
-   * See {@link FlagsClient.fromSnapshot}.
+   * See {@link Engine.fromSnapshot}.
    */
   static fromFile(path) {
     const fs = require("fs");
     const raw = fs.readFileSync(path, "utf8");
     const snapshot = JSON.parse(raw);
-    return _FlagsClient.fromSnapshot(snapshot);
+    return _Engine.fromSnapshot(snapshot);
   }
   async init() {
     if (this.testMode) {
@@ -1093,7 +1097,7 @@ async function fetchLabelsForSSR(opts) {
 var _server = null;
 function configureShipeasyServer(opts) {
   if (_server) return _server;
-  _server = new FlagsClient(opts);
+  _server = new Engine(opts);
   return _server;
 }
 function getShipeasyServerClient() {
@@ -1161,46 +1165,62 @@ async function shipeasy(opts) {
     flags: bootstrap.flags,
     configs: bootstrap.configs,
     experiments: bootstrap.experiments,
-    getBootstrapHtml() {
-      return getBootstrapHtml(bootstrap, i18nData, {
-        editLabels,
+    getBootstrapData(emit) {
+      return getBootstrapData(bootstrap, i18nData, {
         i18nProfile: profile,
-        anonId
+        anonId,
+        ...emit
+      });
+    },
+    getBootstrapTags(emit) {
+      return getBootstrapTags(bootstrap, i18nData, {
+        i18nProfile: profile,
+        anonId,
+        ...emit
       });
     }
   };
 }
-function getBootstrapHtml(bootstrap, i18nData, opts) {
-  const parts = [];
-  const apiUrl = "https://cdn.shipeasy.ai";
+var DEFAULT_CDN = "https://cdn.shipeasy.ai";
+function getBootstrapData(bootstrap, i18nData, opts) {
+  const base = (opts.baseUrl ?? DEFAULT_CDN).replace(/\/$/, "");
   const profile = opts.i18nProfile ?? "en:prod";
-  const payload = {
-    flags: bootstrap?.flags ?? {},
-    configs: bootstrap?.configs ?? {},
-    experiments: bootstrap?.experiments ?? {},
-    // No key here — the server only knows the server key, which must never reach
-    // the browser. The client supplies its own client key via shipeasy({ clientKey }).
-    i18nProfile: profile,
-    apiUrl
+  const attrs = {
+    "data-se-bootstrap": "",
+    "data-flags": JSON.stringify(bootstrap?.flags ?? {}),
+    "data-configs": JSON.stringify(bootstrap?.configs ?? {}),
+    "data-experiments": JSON.stringify(bootstrap?.experiments ?? {}),
+    "data-killswitches": JSON.stringify(bootstrap?.killswitches ?? {}),
+    "data-i18n-profile": profile,
+    "data-api-url": base
   };
-  if (i18nData) payload.i18n = i18nData;
-  if (opts.editLabels) payload.editLabels = true;
-  if (opts.anonId) payload.anonId = opts.anonId;
-  parts.push(
-    `(function(){var Q=new URLSearchParams(location.search).has('se_edit_labels');var C=/(?:^|;\\s*)se_edit_labels=1(?:;|$)/.test(document.cookie);if(!Q&&!C)return;if(Q){try{document.cookie='se_edit_labels=1;path=/;max-age=86400;samesite=lax';}catch(_){}}var R;function P(v){if(!v||typeof v.t!=='function'||v.__sePatched)return;var O=v.t.bind(v);v.__sePatched=true;window._sei18n_t=O;v.t=function(k,vars){var r=O(k,vars);if(r===k)return k;var V='';try{if(vars&&typeof vars==='object'){var hasKey=false;for(var _k in vars){hasKey=true;break;}if(hasKey)V=JSON.stringify(vars);}}catch(_){V='';}return '\\uFFF9'+k+'\\uFFFA'+V+'\\uFFFA'+r+'\\uFFFB';};}Object.defineProperty(window,'i18n',{configurable:true,get:function(){return R;},set:function(v){P(v);R=v;}});})();`
-  );
-  parts.push(`window.__SE_BOOTSTRAP=${JSON.stringify(payload)};`);
-  if (opts.anonId) {
-    parts.push(
-      `(function(){try{var k=${JSON.stringify(ANON_ID_COOKIE)},v=${JSON.stringify(opts.anonId)};if(('; '+document.cookie).indexOf('; '+k+'=')===-1){document.cookie=k+'='+v+';path=/;max-age=31536000;samesite=lax'+(location.protocol==='https:'?';secure':'');}}catch(_){}})();`
-    );
-  }
-  if (i18nData?.strings && Object.keys(i18nData.strings).length > 0) {
-    parts.push(
-      `(function(){var d=window.__SE_BOOTSTRAP.i18n;if(!d)return;window.i18n={locale:d.locale,t:function(k,v){var r=d.strings[k];if(!r)return k;return v?r.replace(/\\{\\{(\\w+)\\}\\}/g,function(_,p){return v[p]!==undefined?String(v[p]):'{{'+p+'}}'}):r;},on:function(){return function(){};}};})();`
-    );
+  if (opts.anonId) attrs["data-anon-id"] = opts.anonId;
+  const bootstrapTag = { src: `${base}/sdk/bootstrap.js`, attrs };
+  let i18nLoader = null;
+  const hasStrings = !!(i18nData?.strings && Object.keys(i18nData.strings).length > 0);
+  if (hasStrings || opts.clientKey) {
+    const i18nAttrs = { "data-profile": profile };
+    if (opts.clientKey) i18nAttrs["data-key"] = opts.clientKey;
+    if (hasStrings) {
+      i18nAttrs["data-strings"] = JSON.stringify(i18nData.strings);
+      i18nAttrs["data-locale"] = i18nData.locale;
+    }
+    i18nLoader = { src: `${base}/sdk/i18n/loader.js`, attrs: i18nAttrs };
   }
-  return parts.join("");
+  return { bootstrap: bootstrapTag, i18nLoader };
+}
+function escapeAttr(v) {
+  return v.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function renderScriptTag(spec) {
+  const attrs = Object.entries(spec.attrs).map(([k, v]) => v === "" ? ` ${k}` : ` ${k}="${escapeAttr(v)}"`).join("");
+  return `<script src="${escapeAttr(spec.src)}"${attrs}></script>`;
+}
+function getBootstrapTags(bootstrap, i18nData, opts) {
+  const data = getBootstrapData(bootstrap, i18nData, opts);
+  const tags = [data.bootstrap];
+  if (data.i18nLoader) tags.push(data.i18nLoader);
+  return tags.map(renderScriptTag).join("");
 }
 var flags = {
   configure(opts) {
@@ -1252,7 +1272,7 @@ var flags = {
     _server?.track(userId, eventName, props);
   },
   /** Emit an exposure for an enrolled experiment at the decision point. See
-   *  {@link FlagsClient.logExposure}. No-op before configure(). */
+   *  {@link Engine.logExposure}. No-op before configure(). */
   logExposure(user, name) {
     _server?.logExposure(user, name);
   },
@@ -1270,6 +1290,50 @@ var flags = {
     };
   }
 };
+var _identityAttributes = (user) => user && typeof user === "object" ? user : {};
+var _attributes = _identityAttributes;
+function configure(opts) {
+  const { attributes, ...engineOpts } = opts;
+  _attributes = attributes ?? _identityAttributes;
+  const engine = configureShipeasyServer(engineOpts);
+  void engine.initOnce().catch(() => {
+  });
+  return engine;
+}
+function _resetConfigureForTests() {
+  _attributes = _identityAttributes;
+}
+var Client = class {
+  engine;
+  /** The resolved attribute bag this handle evaluates against. */
+  attributes;
+  constructor(user) {
+    const engine = getShipeasyServerClient();
+    if (!engine) {
+      throw new Error(
+        "[shipeasy] new Client(user) called before configure({ apiKey }). Call configure() once at app boot from @shipeasy/sdk/server."
+      );
+    }
+    this.engine = engine;
+    this.attributes = _attributes(user);
+  }
+  getFlag(name, defaultValue = false) {
+    return this.engine.getFlag(name, this.attributes, defaultValue);
+  }
+  getFlagDetail(name) {
+    return this.engine.getFlagDetail(name, this.attributes);
+  }
+  getConfig(name, decodeOrOpts) {
+    return this.engine.getConfig(name, decodeOrOpts);
+  }
+  getExperiment(name, defaultParams, decode) {
+    return this.engine.getExperiment(name, this.attributes, defaultParams, decode);
+  }
+  /** Read a killswitch (not user-bound; mirrors {@link Engine.getKillswitch}). */
+  getKillswitch(name, switchKey) {
+    return this.engine.getKillswitch(name, switchKey);
+  }
+};
 function dispatchSee(problem, consequence, extras, kind) {
   if (!_server) {
     console.warn("[shipeasy] see() called before shipeasy({ serverKey }) \u2014 error dropped");
@@ -1287,15 +1351,19 @@ var see = Object.assign(
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ANON_ID_COOKIE,
+  Client,
+  Engine,
   FLAG_REASONS,
-  FlagsClient,
   _murmur3ForTests,
+  _resetConfigureForTests,
   _resetShipeasyServerForTests,
+  configure,
   configureShipeasyServer,
   createInMemoryStickyStore,
   fetchLabelsForSSR,
   flags,
-  getBootstrapHtml,
+  getBootstrapData,
+  getBootstrapTags,
   getShipeasyServerClient,
   i18n,
   isExpected,