@shipeasy/sdk 4.3.0 → 4.5.0

package/dist/client/index.js

@@ -729,17 +729,40 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
     });
   }
 }
-function getOrCreateAnonId() {
+function readAnonCookie() {
   try {
-    const stored = localStorage.getItem(ANON_ID_KEY);
-    if (stored) return stored;
+    const m = ("; " + document.cookie).match(/; __se_anon_id=([^;]+)/);
+    return m ? decodeURIComponent(m[1]) : null;
   } catch {
+    return null;
+  }
+}
+function writeAnonCookie(id) {
+  try {
+    const secure = location.protocol === "https:" ? ";secure" : "";
+    document.cookie = `${ANON_ID_KEY}=${id};path=/;max-age=31536000;samesite=lax${secure}`;
+  } catch {
+  }
+}
+function getOrCreateAnonId() {
+  let id = readAnonCookie();
+  if (!id && typeof window !== "undefined") {
+    id = window.__SE_BOOTSTRAP?.anonId ?? null;
+  }
+  if (!id) {
+    try {
+      id = localStorage.getItem(ANON_ID_KEY);
+    } catch {
+    }
+  }
+  if (!id) {
+    id = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `anon_${Math.random().toString(36).slice(2)}`;
   }
-  const id = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `anon_${Math.random().toString(36).slice(2)}`;
   try {
     localStorage.setItem(ANON_ID_KEY, id);
   } catch {
   }
+  writeAnonCookie(id);
   return id;
 }
 function collectBrowserAttrs() {

package/dist/client/index.mjs

@@ -681,17 +681,40 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
     });
   }
 }
-function getOrCreateAnonId() {
+function readAnonCookie() {
   try {
-    const stored = localStorage.getItem(ANON_ID_KEY);
-    if (stored) return stored;
+    const m = ("; " + document.cookie).match(/; __se_anon_id=([^;]+)/);
+    return m ? decodeURIComponent(m[1]) : null;
   } catch {
+    return null;
+  }
+}
+function writeAnonCookie(id) {
+  try {
+    const secure = location.protocol === "https:" ? ";secure" : "";
+    document.cookie = `${ANON_ID_KEY}=${id};path=/;max-age=31536000;samesite=lax${secure}`;
+  } catch {
+  }
+}
+function getOrCreateAnonId() {
+  let id = readAnonCookie();
+  if (!id && typeof window !== "undefined") {
+    id = window.__SE_BOOTSTRAP?.anonId ?? null;
+  }
+  if (!id) {
+    try {
+      id = localStorage.getItem(ANON_ID_KEY);
+    } catch {
+    }
+  }
+  if (!id) {
+    id = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `anon_${Math.random().toString(36).slice(2)}`;
   }
-  const id = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `anon_${Math.random().toString(36).slice(2)}`;
   try {
     localStorage.setItem(ANON_ID_KEY, id);
   } catch {
   }
+  writeAnonCookie(id);
   return id;
 }
 function collectBrowserAttrs() {

package/dist/next/index.d.mts

@@ -0,0 +1,50 @@
+import { NextRequest, NextFetchEvent, NextResponse } from 'next/server';
+
+/** The first-party cookie that carries the stable anonymous bucketing unit. */
+declare const ANON_ID_COOKIE = "__se_anon_id";
+interface AnonIdResult {
+    /** The stable bucketing id for this request (existing cookie, or freshly minted). */
+    anonId: string;
+    /** True when there was no valid cookie and we minted a new id (must be persisted). */
+    minted: boolean;
+}
+/**
+ * Read + validate the `__se_anon_id` cookie, minting one when absent/invalid.
+ * When `requestHeaders` is supplied and we mint, the new id is appended to the
+ * forwarded `cookie` header so THIS request's SSR (and any inner middleware)
+ * already sees it. Pair with {@link commitAnonId} to persist a minted id.
+ */
+declare function readOrMintAnonId(req: NextRequest, requestHeaders?: Headers): AnonIdResult;
+/**
+ * Persist a freshly-minted anon id as a first-party cookie on `res` (no-op when
+ * `minted` is false). Non-httpOnly by contract — the browser SDK reads it via
+ * `document.cookie` to bucket identically to SSR. Returns `res` for chaining.
+ */
+declare function commitAnonId(res: NextResponse, result: AnonIdResult, req: NextRequest): NextResponse;
+type ShipeasyMiddleware = (req: NextRequest, event: NextFetchEvent) => NextResponse | Response | undefined | null | void | Promise<NextResponse | Response | undefined | null | void>;
+/**
+ * Wrap an existing Next middleware so every matched request also mints the
+ * shared `__se_anon_id` cookie. Your middleware runs against a request that
+ * already carries the id (its own logic + SSR see it), and the cookie is set on
+ * whatever response it returns. Called with no argument, returns a standalone
+ * mint-only middleware (what the default {@link middleware} export uses).
+ *
+ * If your middleware forwards custom request headers via
+ * `NextResponse.next({ request: { headers } })`, prefer composing the
+ * {@link readOrMintAnonId} + {@link commitAnonId} primitives inside it — that
+ * preserves your forwarding verbatim; this wrapper rebuilds the pass-through
+ * `next()` and so would drop request-header forwarding the inner handler added.
+ */
+declare function withShipeasy(handler?: ShipeasyMiddleware): ShipeasyMiddleware;
+/** Drop-in middleware: `export { middleware, config } from "@shipeasy/sdk/next";` */
+declare const middleware: ShipeasyMiddleware;
+/**
+ * Matcher for the drop-in middleware: every HTML route (landing + app), skipping
+ * Next internals, API routes, and static files (any path segment with a dot).
+ * Define your own `config` if you need a narrower scope.
+ */
+declare const config: {
+    matcher: string[];
+};
+
+export { ANON_ID_COOKIE, type AnonIdResult, type ShipeasyMiddleware, commitAnonId, config, middleware, readOrMintAnonId, withShipeasy };

package/dist/next/index.d.ts

@@ -0,0 +1,50 @@
+import { NextRequest, NextFetchEvent, NextResponse } from 'next/server';
+
+/** The first-party cookie that carries the stable anonymous bucketing unit. */
+declare const ANON_ID_COOKIE = "__se_anon_id";
+interface AnonIdResult {
+    /** The stable bucketing id for this request (existing cookie, or freshly minted). */
+    anonId: string;
+    /** True when there was no valid cookie and we minted a new id (must be persisted). */
+    minted: boolean;
+}
+/**
+ * Read + validate the `__se_anon_id` cookie, minting one when absent/invalid.
+ * When `requestHeaders` is supplied and we mint, the new id is appended to the
+ * forwarded `cookie` header so THIS request's SSR (and any inner middleware)
+ * already sees it. Pair with {@link commitAnonId} to persist a minted id.
+ */
+declare function readOrMintAnonId(req: NextRequest, requestHeaders?: Headers): AnonIdResult;
+/**
+ * Persist a freshly-minted anon id as a first-party cookie on `res` (no-op when
+ * `minted` is false). Non-httpOnly by contract — the browser SDK reads it via
+ * `document.cookie` to bucket identically to SSR. Returns `res` for chaining.
+ */
+declare function commitAnonId(res: NextResponse, result: AnonIdResult, req: NextRequest): NextResponse;
+type ShipeasyMiddleware = (req: NextRequest, event: NextFetchEvent) => NextResponse | Response | undefined | null | void | Promise<NextResponse | Response | undefined | null | void>;
+/**
+ * Wrap an existing Next middleware so every matched request also mints the
+ * shared `__se_anon_id` cookie. Your middleware runs against a request that
+ * already carries the id (its own logic + SSR see it), and the cookie is set on
+ * whatever response it returns. Called with no argument, returns a standalone
+ * mint-only middleware (what the default {@link middleware} export uses).
+ *
+ * If your middleware forwards custom request headers via
+ * `NextResponse.next({ request: { headers } })`, prefer composing the
+ * {@link readOrMintAnonId} + {@link commitAnonId} primitives inside it — that
+ * preserves your forwarding verbatim; this wrapper rebuilds the pass-through
+ * `next()` and so would drop request-header forwarding the inner handler added.
+ */
+declare function withShipeasy(handler?: ShipeasyMiddleware): ShipeasyMiddleware;
+/** Drop-in middleware: `export { middleware, config } from "@shipeasy/sdk/next";` */
+declare const middleware: ShipeasyMiddleware;
+/**
+ * Matcher for the drop-in middleware: every HTML route (landing + app), skipping
+ * Next internals, API routes, and static files (any path segment with a dot).
+ * Define your own `config` if you need a narrower scope.
+ */
+declare const config: {
+    matcher: string[];
+};
+
+export { ANON_ID_COOKIE, type AnonIdResult, type ShipeasyMiddleware, commitAnonId, config, middleware, readOrMintAnonId, withShipeasy };

package/dist/next/index.js

@@ -0,0 +1,97 @@
+"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/next/index.ts
+var next_exports = {};
+__export(next_exports, {
+  ANON_ID_COOKIE: () => ANON_ID_COOKIE,
+  commitAnonId: () => commitAnonId,
+  config: () => config,
+  middleware: () => middleware,
+  readOrMintAnonId: () => readOrMintAnonId,
+  withShipeasy: () => withShipeasy
+});
+module.exports = __toCommonJS(next_exports);
+var import_server = require("next/server");
+var ANON_ID_COOKIE = "__se_anon_id";
+var ANON_ID_RX = /^[A-Za-z0-9_-]{1,64}$/;
+var ANON_ID_MAX_AGE = 60 * 60 * 24 * 365;
+function mint() {
+  return typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `anon_${Math.random().toString(36).slice(2)}`;
+}
+function appendCookie(headers, name, value) {
+  const existing = headers.get("cookie") ?? "";
+  const parts = existing.split(";").map((c) => c.trim()).filter((c) => c && !c.startsWith(`${name}=`));
+  parts.push(`${name}=${value}`);
+  headers.set("cookie", parts.join("; "));
+}
+function readOrMintAnonId(req, requestHeaders) {
+  const raw = req.cookies.get(ANON_ID_COOKIE)?.value;
+  const valid = !!raw && ANON_ID_RX.test(raw);
+  const anonId = valid ? raw : mint();
+  const minted = !valid;
+  if (minted && requestHeaders) appendCookie(requestHeaders, ANON_ID_COOKIE, anonId);
+  return { anonId, minted };
+}
+function commitAnonId(res, result, req) {
+  if (result.minted) {
+    res.cookies.set(ANON_ID_COOKIE, result.anonId, {
+      httpOnly: false,
+      secure: req.nextUrl.protocol === "https:",
+      sameSite: "lax",
+      path: "/",
+      maxAge: ANON_ID_MAX_AGE
+    });
+  }
+  return res;
+}
+function withShipeasy(handler) {
+  return async (req, event) => {
+    const requestHeaders = new Headers(req.headers);
+    const anon = readOrMintAnonId(req, requestHeaders);
+    if (anon.minted) req.cookies.set(ANON_ID_COOKIE, anon.anonId);
+    const userRes = handler ? await handler(req, event) : void 0;
+    const isPassThrough = !userRes || userRes instanceof import_server.NextResponse && userRes.headers.get("x-middleware-next") === "1";
+    if (isPassThrough) {
+      const res2 = import_server.NextResponse.next({ request: { headers: requestHeaders } });
+      if (userRes instanceof import_server.NextResponse) {
+        userRes.cookies.getAll().forEach((c) => res2.cookies.set(c));
+        userRes.headers.forEach((v, k) => {
+          if (k !== "x-middleware-next") res2.headers.set(k, v);
+        });
+      }
+      return commitAnonId(res2, anon, req);
+    }
+    const res = userRes instanceof import_server.NextResponse ? userRes : userRes instanceof Response ? new import_server.NextResponse(userRes.body, userRes) : import_server.NextResponse.next({ request: { headers: requestHeaders } });
+    return commitAnonId(res, anon, req);
+  };
+}
+var middleware = withShipeasy();
+var config = {
+  matcher: ["/((?!api/|_next/|.*\\..*).*)"]
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ANON_ID_COOKIE,
+  commitAnonId,
+  config,
+  middleware,
+  readOrMintAnonId,
+  withShipeasy
+});

package/dist/next/index.mjs

@@ -0,0 +1,67 @@
+// src/next/index.ts
+import { NextResponse } from "next/server";
+var ANON_ID_COOKIE = "__se_anon_id";
+var ANON_ID_RX = /^[A-Za-z0-9_-]{1,64}$/;
+var ANON_ID_MAX_AGE = 60 * 60 * 24 * 365;
+function mint() {
+  return typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `anon_${Math.random().toString(36).slice(2)}`;
+}
+function appendCookie(headers, name, value) {
+  const existing = headers.get("cookie") ?? "";
+  const parts = existing.split(";").map((c) => c.trim()).filter((c) => c && !c.startsWith(`${name}=`));
+  parts.push(`${name}=${value}`);
+  headers.set("cookie", parts.join("; "));
+}
+function readOrMintAnonId(req, requestHeaders) {
+  const raw = req.cookies.get(ANON_ID_COOKIE)?.value;
+  const valid = !!raw && ANON_ID_RX.test(raw);
+  const anonId = valid ? raw : mint();
+  const minted = !valid;
+  if (minted && requestHeaders) appendCookie(requestHeaders, ANON_ID_COOKIE, anonId);
+  return { anonId, minted };
+}
+function commitAnonId(res, result, req) {
+  if (result.minted) {
+    res.cookies.set(ANON_ID_COOKIE, result.anonId, {
+      httpOnly: false,
+      secure: req.nextUrl.protocol === "https:",
+      sameSite: "lax",
+      path: "/",
+      maxAge: ANON_ID_MAX_AGE
+    });
+  }
+  return res;
+}
+function withShipeasy(handler) {
+  return async (req, event) => {
+    const requestHeaders = new Headers(req.headers);
+    const anon = readOrMintAnonId(req, requestHeaders);
+    if (anon.minted) req.cookies.set(ANON_ID_COOKIE, anon.anonId);
+    const userRes = handler ? await handler(req, event) : void 0;
+    const isPassThrough = !userRes || userRes instanceof NextResponse && userRes.headers.get("x-middleware-next") === "1";
+    if (isPassThrough) {
+      const res2 = NextResponse.next({ request: { headers: requestHeaders } });
+      if (userRes instanceof NextResponse) {
+        userRes.cookies.getAll().forEach((c) => res2.cookies.set(c));
+        userRes.headers.forEach((v, k) => {
+          if (k !== "x-middleware-next") res2.headers.set(k, v);
+        });
+      }
+      return commitAnonId(res2, anon, req);
+    }
+    const res = userRes instanceof NextResponse ? userRes : userRes instanceof Response ? new NextResponse(userRes.body, userRes) : NextResponse.next({ request: { headers: requestHeaders } });
+    return commitAnonId(res, anon, req);
+  };
+}
+var middleware = withShipeasy();
+var config = {
+  matcher: ["/((?!api/|_next/|.*\\..*).*)"]
+};
+export {
+  ANON_ID_COOKIE,
+  commitAnonId,
+  config,
+  middleware,
+  readOrMintAnonId,
+  withShipeasy
+};

package/dist/server/index.d.mts

@@ -134,6 +134,7 @@ interface BootstrapPayload {
     experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
     killswitches: Record<string, boolean | Record<string, boolean>>;
 }
+declare const ANON_ID_COOKIE = "__se_anon_id";
 type FlagsClientEnv = "dev" | "staging" | "prod";
 interface FlagsClientOptions {
     apiKey: string;
@@ -291,6 +292,14 @@ interface BootstrapHtmlOptions {
     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.
+     */
+    anonId?: string;
 }
 /**
  * Returns a vanilla-JS string for a single inline <script> tag. Handles
@@ -380,4 +389,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-export { type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };
+export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };

package/dist/server/index.d.ts

@@ -134,6 +134,7 @@ interface BootstrapPayload {
     experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
     killswitches: Record<string, boolean | Record<string, boolean>>;
 }
+declare const ANON_ID_COOKIE = "__se_anon_id";
 type FlagsClientEnv = "dev" | "staging" | "prod";
 interface FlagsClientOptions {
     apiKey: string;
@@ -291,6 +292,14 @@ interface BootstrapHtmlOptions {
     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.
+     */
+    anonId?: string;
 }
 /**
  * Returns a vanilla-JS string for a single inline <script> tag. Handles
@@ -380,4 +389,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-export { type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };
+export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };

package/dist/server/index.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/server/index.ts
 var server_exports = {};
 __export(server_exports, {
+  ANON_ID_COOKIE: () => ANON_ID_COOKIE,
   FlagsClient: () => FlagsClient,
   _resetShipeasyServerForTests: () => _resetShipeasyServerForTests,
   configureShipeasyServer: () => configureShipeasyServer,
@@ -442,6 +443,11 @@ function matchRule(rule, user) {
       return false;
   }
 }
+var ANON_ID_COOKIE = "__se_anon_id";
+var ANON_ID_RX = /^[A-Za-z0-9_-]{1,64}$/;
+function mintAnonId() {
+  return typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `anon_${Math.random().toString(36).slice(2)}`;
+}
 function evalGateInternal(gate, user) {
   if (isEnabled(gate.killswitch)) return false;
   if (!isEnabled(gate.enabled)) return false;
@@ -449,7 +455,7 @@ function evalGateInternal(gate, user) {
     if (!matchRule(rule, user)) return false;
   }
   const uid = user.user_id ?? user.anonymous_id;
-  if (!uid) return false;
+  if (!uid) return gate.rolloutPct >= 1e4;
   return murmur3(`${gate.salt}:${uid}`) % 1e4 < gate.rolloutPct;
 }
 var TRUE_RX = /^(true|on|1|yes)$/i;
@@ -885,7 +891,23 @@ async function shipeasy(opts) {
     serverKey ? flags.initOnce() : Promise.resolve(),
     serverKey ? i18n.init(serverKey, profile) : Promise.resolve()
   ]);
-  const bootstrap = flags.evaluate(opts.user ?? {}, resolvedUrlOverrides);
+  let anonId;
+  if (!opts.user?.user_id) {
+    if (opts.user?.anonymous_id) {
+      anonId = opts.user.anonymous_id;
+    } else {
+      try {
+        const { cookies } = await import("next/headers");
+        const c = await Promise.resolve(cookies());
+        const raw = c.get?.(ANON_ID_COOKIE)?.value;
+        if (raw && ANON_ID_RX.test(raw)) anonId = raw;
+      } catch {
+      }
+      if (!anonId) anonId = mintAnonId();
+    }
+  }
+  const effectiveUser = anonId ? { anonymous_id: anonId, ...opts.user } : { ...opts.user };
+  const bootstrap = flags.evaluate(effectiveUser, resolvedUrlOverrides);
   const i18nData = i18n.getForRequest();
   return {
     flags: bootstrap.flags,
@@ -894,7 +916,8 @@ async function shipeasy(opts) {
     getBootstrapHtml() {
       return getBootstrapHtml(bootstrap, i18nData, {
         editLabels,
-        i18nProfile: profile
+        i18nProfile: profile,
+        anonId
       });
     }
   };
@@ -914,10 +937,16 @@ function getBootstrapHtml(bootstrap, i18nData, opts) {
   };
   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(){};}};})();`
@@ -1003,6 +1032,7 @@ var see = Object.assign(
 );
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ANON_ID_COOKIE,
   FlagsClient,
   _resetShipeasyServerForTests,
   configureShipeasyServer,

package/dist/server/index.mjs

@@ -396,6 +396,11 @@ function matchRule(rule, user) {
       return false;
   }
 }
+var ANON_ID_COOKIE = "__se_anon_id";
+var ANON_ID_RX = /^[A-Za-z0-9_-]{1,64}$/;
+function mintAnonId() {
+  return typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `anon_${Math.random().toString(36).slice(2)}`;
+}
 function evalGateInternal(gate, user) {
   if (isEnabled(gate.killswitch)) return false;
   if (!isEnabled(gate.enabled)) return false;
@@ -403,7 +408,7 @@ function evalGateInternal(gate, user) {
     if (!matchRule(rule, user)) return false;
   }
   const uid = user.user_id ?? user.anonymous_id;
-  if (!uid) return false;
+  if (!uid) return gate.rolloutPct >= 1e4;
   return murmur3(`${gate.salt}:${uid}`) % 1e4 < gate.rolloutPct;
 }
 var TRUE_RX = /^(true|on|1|yes)$/i;
@@ -839,7 +844,23 @@ async function shipeasy(opts) {
     serverKey ? flags.initOnce() : Promise.resolve(),
     serverKey ? i18n.init(serverKey, profile) : Promise.resolve()
   ]);
-  const bootstrap = flags.evaluate(opts.user ?? {}, resolvedUrlOverrides);
+  let anonId;
+  if (!opts.user?.user_id) {
+    if (opts.user?.anonymous_id) {
+      anonId = opts.user.anonymous_id;
+    } else {
+      try {
+        const { cookies } = await import("next/headers");
+        const c = await Promise.resolve(cookies());
+        const raw = c.get?.(ANON_ID_COOKIE)?.value;
+        if (raw && ANON_ID_RX.test(raw)) anonId = raw;
+      } catch {
+      }
+      if (!anonId) anonId = mintAnonId();
+    }
+  }
+  const effectiveUser = anonId ? { anonymous_id: anonId, ...opts.user } : { ...opts.user };
+  const bootstrap = flags.evaluate(effectiveUser, resolvedUrlOverrides);
   const i18nData = i18n.getForRequest();
   return {
     flags: bootstrap.flags,
@@ -848,7 +869,8 @@ async function shipeasy(opts) {
     getBootstrapHtml() {
       return getBootstrapHtml(bootstrap, i18nData, {
         editLabels,
-        i18nProfile: profile
+        i18nProfile: profile,
+        anonId
       });
     }
   };
@@ -868,10 +890,16 @@ function getBootstrapHtml(bootstrap, i18nData, opts) {
   };
   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(){};}};})();`
@@ -956,6 +984,7 @@ var see = Object.assign(
   }
 );
 export {
+  ANON_ID_COOKIE,
   FlagsClient,
   _resetShipeasyServerForTests,
   configureShipeasyServer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/sdk",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "Shipeasy SDK — feature gates, runtime configs, experiments, and metrics for the Shipeasy hosted service.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://shipeasy.ai",
@@ -21,6 +21,9 @@
       ],
       "server": [
         "./dist/server/index.d.ts"
+      ],
+      "next": [
+        "./dist/next/index.d.ts"
       ]
     }
   },
@@ -39,11 +42,17 @@
       "types": "./dist/client/index.d.ts",
       "default": "./dist/client/index.js"
     },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "import": "./dist/next/index.mjs",
+      "default": "./dist/next/index.js"
+    },
     "./templates/*": "./templates/*.js"
   },
   "files": [
     "dist/server/",
     "dist/client/",
+    "dist/next/",
     "templates/",
     "LICENSE",
     "README.md"
@@ -58,9 +67,18 @@
   "dependencies": {
     "murmurhash-js": "^1.0.0"
   },
+  "peerDependencies": {
+    "next": ">=13"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/murmurhash-js": "^1.0.6",
     "@types/node": "^20.0.0",
+    "next": "^16.2.3",
     "tsup": "^8.3.0",
     "typescript": "^5.7.4",
     "vitest": "^2.1.0",