@shopkit/ab 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# @shopkit/ab
+
+Section-level A/B testing for the storefront edge.
+
+Answers one question per request: **does this URL belong to a running
+experiment, and if so, which arm is this visitor in?**
+
+Everything else — authoring variants, setting the split, promoting a winner —
+happens in the visual editor and the admin dashboard.
+
+## Constraints this package is built to
+
+It runs in Next.js **middleware**, on the request path, for every merchant —
+including the ones who never use A/B. So:
+
+- **No React, no DOM, no dependencies.** ~2.6 kB in the edge bundle.
+- **Nothing throws.** Every public function has a safe return.
+- **Fails open.** A broken backend degrades A/B testing and nothing else.
+
+## Usage
+
+```ts
+import {
+  getManifest, matchExperiment, isExcludedPath,
+  assignArm, readArmCookie, serialiseArmCookie, selectionFor,
+  ARM_COOKIE, ARM_COOKIE_MAX_AGE_S,
+} from "@shopkit/ab";
+
+try {
+  if (isExcludedPath(pathname)) return response;
+
+  const manifest = await getManifest({ baseUrl, themeId });
+  const exp = matchExperiment(pathname, manifest);
+  if (!exp) return response;
+
+  const stored = readArmCookie(request.cookies.get(ARM_COOKIE)?.value);
+  const arm = assignArm(exp, stored);
+
+  response.cookies.set(ARM_COOKIE, serialiseArmCookie({ ...stored, [exp.id]: arm }), {
+    maxAge: ARM_COOKIE_MAX_AGE_S, path: "/", sameSite: "lax",
+  });
+
+  if (arm === "a") return response;                       // no rewrite at all
+  return NextResponse.rewrite(new URL(`${pathname}/variant/b`, request.url));
+} catch {
+  // Never break a request over an experiment.
+}
+```
+
+`arm === "a"` returns with **no rewrite** — existing route, existing cache
+entry, byte-identical to a storefront without this feature.
+
+## Behaviour worth knowing
+
+| | |
+| --- | --- |
+| Manifest TTL | 30s per pod, matching the endpoint's `s-maxage=30` |
+| Timeout | 250ms, then the request proceeds as "no experiments" |
+| Failure backoff | 5s — a down backend costs one attempt per window, not one per request |
+| Concurrent misses | Coalesced to a single fetch |
+| Assignment | Stored in one cookie, read **before** the split is consulted |
+
+That last row is the rule the dashboard promises merchants: **changing the split
+affects new visitors only.** A visitor already on Variant B stays there when the
+merchant ramps 25% → 50%.
+
+## Not in scope
+
+Rendering. This package never sees page content and does not know what a variant
+contains — `selectionFor()` returns `{ [sectionId]: arm }` for
+`applySectionVariants` in `@shopkit/builder` to apply.

package/dist/index.d.mts

@@ -0,0 +1,222 @@
+/**
+ * Section-level A/B testing — the shapes the edge works with.
+ *
+ * Read on the storefront request path: no React, no DOM, no dependencies.
+ */
+/** Arm "a" IS Variant A, "b" IS Variant B — no mapping stored, so none can drift. */
+type Arm = "a" | "b";
+/** One running experiment, as the manifest reports it. */
+interface ActiveExperiment {
+    id: string;
+    /**
+     * The template under test, e.g. `bblunt-2_home_default`. Unusable at the edge
+     * (a URL doesn't reveal the template suffix) — the RENDER checks it.
+     */
+    templateKey: string;
+    /** `home | products | collection` — the route family the edge matches on. */
+    pageType: string;
+    /** Percent of visitors on arm B. 1–99. */
+    split: number;
+    /**
+     * Narrows which paths are rewritten; empty means every URL of this `pageType`.
+     * Not targeting — only avoids arm-B cache entries for out-of-scope URLs.
+     */
+    targetUrls: string[];
+    /** The slots that vary. They flip TOGETHER — all B, or all A, never a mix. */
+    sectionIds: string[];
+}
+/** The response body of `GET /experiments/active`. */
+interface Manifest {
+    /** Master switch. Already applied server-side; reported so a UI can say why. */
+    masterEnabled: boolean;
+    /** Content fingerprint, not a counter — compare for inequality only. */
+    revision: number;
+    experiments: ActiveExperiment[];
+}
+/** `{ [experimentId]: arm }` — the visitor's stored assignments. */
+type ArmAssignments = Record<string, Arm>;
+/** `{ [sectionId]: variantId }` — what `applySectionVariants` consumes. */
+type SectionVariantSelection = Record<string, Arm>;
+
+/**
+ * How long a cached manifest is considered fresh.
+ *
+ * 10s, not 30: `getManifestSync` never awaits a refresh, so a shorter window
+ * costs no latency — it only decides how quickly a start/pause reaches the
+ * edge. The endpoint's own `s-maxage=30` still bounds how often the backend is
+ * actually touched.
+ */
+declare const MANIFEST_TTL_MS = 10000;
+/** Data Cache tag. Must match the revalidate webhook, which purges it. */
+declare const MANIFEST_CACHE_TAG = "editor-experiments";
+/**
+ * How long to wait for the manifest before giving up.
+ *
+ * Was 250ms, taken from the TRD's edge budget. **That number does not survive
+ * contact with a real backend.** Measured 2026-09-07: 143ms from a warm shell to
+ * the deployed backend, but the first call from a cold Node process — DNS, TLS
+ * handshake, module init — reliably exceeded 250ms. The result was silent and
+ * expensive: every render timed out, failed open to an empty manifest, and both
+ * arms of a running experiment rendered the same page. The split looked like it
+ * worked (the cookie was set) while the content never changed.
+ *
+ * 1500ms is still a hard bound, and it is paid at most once per pod per TTL
+ * because a hit is cached and concurrent misses coalesce. A timeout still fails
+ * open — it just no longer fires on a perfectly healthy backend.
+ */
+declare const MANIFEST_TIMEOUT_MS = 1500;
+interface GetManifestOptions {
+    /** Editor backend origin, e.g. `https://visual-editor-be.example.com`. */
+    baseUrl: string;
+    /** `themeId` — the same value as `merchant_mappings.merchantName`. */
+    themeId: string;
+    ttlMs?: number;
+    timeoutMs?: number;
+    /** Quiet period after a failure. See MANIFEST_FAILURE_BACKOFF_MS. */
+    failureBackoffMs?: number;
+    /** Injectable for tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injectable for tests; must be monotonic-ish. Defaults to Date.now. */
+    now?: () => number;
+}
+/**
+ * The manifest for a theme, awaiting a refresh when the copy on hand is stale.
+ *
+ * For the RENDER only. It may block, which a page can afford and middleware
+ * cannot — and unlike `getManifestSync` it never reports "no experiments" for a
+ * theme that has them, so the render cannot refuse a page middleware bucketed.
+ *
+ * **Never throws and never returns null.** A failed refresh keeps serving the
+ * last good copy — stale experiment data is a far smaller problem than a
+ * storefront that stops splitting traffic mid-test because of one bad response.
+ * With no copy at all, callers get an empty manifest, which reads as "no
+ * experiments" and renders every page exactly as it did before this feature.
+ */
+declare function getManifest(opts: GetManifestOptions): Promise<Manifest>;
+/**
+ * The manifest for a theme, without ever touching the network.
+ *
+ * For MIDDLEWARE, which runs before every render: awaiting here adds the fetch's
+ * latency to a shopper's TTFB, and when the backend is down that is the full
+ * timeout on a share of every merchant's traffic — including merchants running
+ * no experiment at all.
+ *
+ * Returns whatever is cached and refreshes in the background. A cold pod
+ * therefore reports EMPTY for its first few requests, so those visitors are not
+ * bucketed and see the control page — a handful of sessions per deploy, failing
+ * in the safe direction. The render keeps the awaiting version above, so it can
+ * never decline a page middleware already bucketed.
+ */
+declare function getManifestSync(opts: GetManifestOptions): Manifest;
+/** Drop cached manifests. Tests only — nothing in the request path calls this. */
+declare function __resetManifestCache(): void;
+
+/**
+ * Which family a path belongs to, or null. Order matters: a nested product URL
+ * is a PRODUCT page, so the collection prefix must not be tested first.
+ */
+declare function pageTypeOf(pathname: string): string | null;
+/**
+ * Does `pathname` satisfy one of the merchant's `targetUrls`? Empty means every
+ * URL in the family. A non-empty list only narrows, never expands. One trailing
+ * `*` is supported — deliberately not a regex on the request path.
+ */
+declare function matchesTargetUrls(pathname: string, targetUrls: string[] | undefined): boolean;
+/**
+ * The experiment covering this request, or null.
+ *
+ * Returns null — never throws — for a manifest that is empty, malformed, or has
+ * the master switch off. Callers are on the request path and have nothing
+ * useful to do with an exception.
+ *
+ * `templateKey` is passed by the render and omitted by middleware, which only
+ * has a URL. Omitting it in the render is the bug it exists for: an experiment
+ * on ONE product template varied every product page, because both templates
+ * shared a section id.
+ *
+ * When several experiments cover one path the FIRST is taken; a database index
+ * keeps one active experiment per template, so at most one can apply at render.
+ */
+declare function matchExperiment(pathname: string, manifest: Manifest | null | undefined, templateKey?: string): ActiveExperiment | null;
+/**
+ * Paths never bucketed. The `/variant/` guard matters most: middleware rewrites
+ * TO those, so matching again would rewrite a rewrite.
+ */
+declare function isExcludedPath(pathname: string): boolean;
+/**
+ * `{themeId}_{templateName}_{suffix}`, as the resolver composes it. Absent,
+ * empty and "default" must all map to `_default`, or no experiment on a default
+ * template could ever match.
+ */
+declare function templateKeyOf(themeId: string, templateName: string, suffix?: string | null): string;
+
+/**
+ * Putting a visitor on one side of a test, and keeping them there.
+ *
+ * The dashboard promises "split changes affect new visitors only", which forces
+ * STORED assignment: a stateless hash would re-bucket the whole audience the
+ * moment the split moves. Read the cookie first; consult the split only when
+ * nothing is stored.
+ */
+/** One cookie holds every assignment, so a merchant running three tests spends one. */
+declare const ARM_COOKIE = "_ab_arm";
+/** Long enough to outlive any sane test, so returning visitors stay comparable. */
+declare const ARM_COOKIE_MAX_AGE_S: number;
+/**
+ * Analytics dimension NAMES — three flat scalars for the event enricher.
+ *
+ * No longer cookies. Middleware matches on page type alone and cannot know the
+ * resolved template, so it could report an arm the render then declined. The
+ * render publishes these on `window.__ab` instead, and the enrichers key off
+ * these same names. Kept here so the writer and the readers share one source.
+ *
+ * Flat because GA4 drops nested objects — which is why the UUID-keyed
+ * `ARM_COOKIE` cannot double as the reporting signal.
+ */
+/** The template under test, e.g. `bblunt-2_products_pdp3`. */
+declare const AB_EXPERIMENT_COOKIE = "ab_experiment";
+/** Which side of the split this visitor is on: `a` or `b`. */
+declare const AB_ARM_COOKIE = "ab_arm";
+/**
+ * The route family: `home` | `products` | `collection`. Looks redundant beside
+ * `ab_experiment`, but GA4 explorations cannot pattern-match a dimension, so
+ * "how did the PDP tests do overall" needs its own field. Values are the
+ * manifest's own `pageType` so cookie and API cannot disagree.
+ */
+declare const AB_PAGE_COOKIE = "ab_page";
+/**
+ * The arm for this experiment. `stored` wins whenever valid; `split` is read
+ * only for an unassigned visitor. `random` is injectable so tests can assert
+ * the boundary rather than sample it.
+ */
+declare function assignArm(experiment: Pick<ActiveExperiment, "id" | "split">, stored: ArmAssignments | null | undefined, random?: () => number): Arm;
+/**
+ * Parse the assignment cookie, tolerating any encoding depth: the server sees
+ * plain JSON (Next decodes once), the client sees it encoded. Hard-coding one
+ * makes the other silently return `{}`, which reads as "no assignment" and
+ * re-buckets the visitor. Unparseable is treated as absent, never an error.
+ */
+declare function readArmCookie(raw: string | undefined | null): ArmAssignments;
+/**
+ * Serialise assignments. Plain JSON, not encoded — every cookie API encodes on
+ * the way out, and doing it here too produced a double-encoded value.
+ *
+ * Bounded: an unbounded map grows the cookie until it breaks the header. The
+ * NEWEST entries are kept, by insertion order — so a caller re-assigning an
+ * existing experiment must delete the key before re-adding it, or object spread
+ * leaves it at its original position and the trim can drop the very experiment
+ * being assigned.
+ */
+declare function serialiseArmCookie(assignments: ArmAssignments, maxEntries?: number): string;
+/**
+ * Every tested section pinned to the visitor's arm. All sections flip together,
+ * or the result is unattributable to any single change.
+ *
+ * **Arm A is pinned explicitly, not left to the live body.** After a promote,
+ * `liveVariantId` is "b" — so "render the live body" means render B, and an
+ * un-pinned arm A would compare B with itself. Pinning costs nothing: the
+ * overlay returns by reference when a section already shows the wanted variant.
+ */
+declare function selectionFor(experiment: Pick<ActiveExperiment, "sectionIds">, arm: Arm): SectionVariantSelection | undefined;
+
+export { AB_ARM_COOKIE, AB_EXPERIMENT_COOKIE, AB_PAGE_COOKIE, ARM_COOKIE, ARM_COOKIE_MAX_AGE_S, type ActiveExperiment, type Arm, type ArmAssignments, type GetManifestOptions, MANIFEST_CACHE_TAG, MANIFEST_TIMEOUT_MS, MANIFEST_TTL_MS, type Manifest, type SectionVariantSelection, __resetManifestCache, assignArm, getManifest, getManifestSync, isExcludedPath, matchExperiment, matchesTargetUrls, pageTypeOf, readArmCookie, selectionFor, serialiseArmCookie, templateKeyOf };

package/dist/index.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Section-level A/B testing — the shapes the edge works with.
+ *
+ * Read on the storefront request path: no React, no DOM, no dependencies.
+ */
+/** Arm "a" IS Variant A, "b" IS Variant B — no mapping stored, so none can drift. */
+type Arm = "a" | "b";
+/** One running experiment, as the manifest reports it. */
+interface ActiveExperiment {
+    id: string;
+    /**
+     * The template under test, e.g. `bblunt-2_home_default`. Unusable at the edge
+     * (a URL doesn't reveal the template suffix) — the RENDER checks it.
+     */
+    templateKey: string;
+    /** `home | products | collection` — the route family the edge matches on. */
+    pageType: string;
+    /** Percent of visitors on arm B. 1–99. */
+    split: number;
+    /**
+     * Narrows which paths are rewritten; empty means every URL of this `pageType`.
+     * Not targeting — only avoids arm-B cache entries for out-of-scope URLs.
+     */
+    targetUrls: string[];
+    /** The slots that vary. They flip TOGETHER — all B, or all A, never a mix. */
+    sectionIds: string[];
+}
+/** The response body of `GET /experiments/active`. */
+interface Manifest {
+    /** Master switch. Already applied server-side; reported so a UI can say why. */
+    masterEnabled: boolean;
+    /** Content fingerprint, not a counter — compare for inequality only. */
+    revision: number;
+    experiments: ActiveExperiment[];
+}
+/** `{ [experimentId]: arm }` — the visitor's stored assignments. */
+type ArmAssignments = Record<string, Arm>;
+/** `{ [sectionId]: variantId }` — what `applySectionVariants` consumes. */
+type SectionVariantSelection = Record<string, Arm>;
+
+/**
+ * How long a cached manifest is considered fresh.
+ *
+ * 10s, not 30: `getManifestSync` never awaits a refresh, so a shorter window
+ * costs no latency — it only decides how quickly a start/pause reaches the
+ * edge. The endpoint's own `s-maxage=30` still bounds how often the backend is
+ * actually touched.
+ */
+declare const MANIFEST_TTL_MS = 10000;
+/** Data Cache tag. Must match the revalidate webhook, which purges it. */
+declare const MANIFEST_CACHE_TAG = "editor-experiments";
+/**
+ * How long to wait for the manifest before giving up.
+ *
+ * Was 250ms, taken from the TRD's edge budget. **That number does not survive
+ * contact with a real backend.** Measured 2026-09-07: 143ms from a warm shell to
+ * the deployed backend, but the first call from a cold Node process — DNS, TLS
+ * handshake, module init — reliably exceeded 250ms. The result was silent and
+ * expensive: every render timed out, failed open to an empty manifest, and both
+ * arms of a running experiment rendered the same page. The split looked like it
+ * worked (the cookie was set) while the content never changed.
+ *
+ * 1500ms is still a hard bound, and it is paid at most once per pod per TTL
+ * because a hit is cached and concurrent misses coalesce. A timeout still fails
+ * open — it just no longer fires on a perfectly healthy backend.
+ */
+declare const MANIFEST_TIMEOUT_MS = 1500;
+interface GetManifestOptions {
+    /** Editor backend origin, e.g. `https://visual-editor-be.example.com`. */
+    baseUrl: string;
+    /** `themeId` — the same value as `merchant_mappings.merchantName`. */
+    themeId: string;
+    ttlMs?: number;
+    timeoutMs?: number;
+    /** Quiet period after a failure. See MANIFEST_FAILURE_BACKOFF_MS. */
+    failureBackoffMs?: number;
+    /** Injectable for tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injectable for tests; must be monotonic-ish. Defaults to Date.now. */
+    now?: () => number;
+}
+/**
+ * The manifest for a theme, awaiting a refresh when the copy on hand is stale.
+ *
+ * For the RENDER only. It may block, which a page can afford and middleware
+ * cannot — and unlike `getManifestSync` it never reports "no experiments" for a
+ * theme that has them, so the render cannot refuse a page middleware bucketed.
+ *
+ * **Never throws and never returns null.** A failed refresh keeps serving the
+ * last good copy — stale experiment data is a far smaller problem than a
+ * storefront that stops splitting traffic mid-test because of one bad response.
+ * With no copy at all, callers get an empty manifest, which reads as "no
+ * experiments" and renders every page exactly as it did before this feature.
+ */
+declare function getManifest(opts: GetManifestOptions): Promise<Manifest>;
+/**
+ * The manifest for a theme, without ever touching the network.
+ *
+ * For MIDDLEWARE, which runs before every render: awaiting here adds the fetch's
+ * latency to a shopper's TTFB, and when the backend is down that is the full
+ * timeout on a share of every merchant's traffic — including merchants running
+ * no experiment at all.
+ *
+ * Returns whatever is cached and refreshes in the background. A cold pod
+ * therefore reports EMPTY for its first few requests, so those visitors are not
+ * bucketed and see the control page — a handful of sessions per deploy, failing
+ * in the safe direction. The render keeps the awaiting version above, so it can
+ * never decline a page middleware already bucketed.
+ */
+declare function getManifestSync(opts: GetManifestOptions): Manifest;
+/** Drop cached manifests. Tests only — nothing in the request path calls this. */
+declare function __resetManifestCache(): void;
+
+/**
+ * Which family a path belongs to, or null. Order matters: a nested product URL
+ * is a PRODUCT page, so the collection prefix must not be tested first.
+ */
+declare function pageTypeOf(pathname: string): string | null;
+/**
+ * Does `pathname` satisfy one of the merchant's `targetUrls`? Empty means every
+ * URL in the family. A non-empty list only narrows, never expands. One trailing
+ * `*` is supported — deliberately not a regex on the request path.
+ */
+declare function matchesTargetUrls(pathname: string, targetUrls: string[] | undefined): boolean;
+/**
+ * The experiment covering this request, or null.
+ *
+ * Returns null — never throws — for a manifest that is empty, malformed, or has
+ * the master switch off. Callers are on the request path and have nothing
+ * useful to do with an exception.
+ *
+ * `templateKey` is passed by the render and omitted by middleware, which only
+ * has a URL. Omitting it in the render is the bug it exists for: an experiment
+ * on ONE product template varied every product page, because both templates
+ * shared a section id.
+ *
+ * When several experiments cover one path the FIRST is taken; a database index
+ * keeps one active experiment per template, so at most one can apply at render.
+ */
+declare function matchExperiment(pathname: string, manifest: Manifest | null | undefined, templateKey?: string): ActiveExperiment | null;
+/**
+ * Paths never bucketed. The `/variant/` guard matters most: middleware rewrites
+ * TO those, so matching again would rewrite a rewrite.
+ */
+declare function isExcludedPath(pathname: string): boolean;
+/**
+ * `{themeId}_{templateName}_{suffix}`, as the resolver composes it. Absent,
+ * empty and "default" must all map to `_default`, or no experiment on a default
+ * template could ever match.
+ */
+declare function templateKeyOf(themeId: string, templateName: string, suffix?: string | null): string;
+
+/**
+ * Putting a visitor on one side of a test, and keeping them there.
+ *
+ * The dashboard promises "split changes affect new visitors only", which forces
+ * STORED assignment: a stateless hash would re-bucket the whole audience the
+ * moment the split moves. Read the cookie first; consult the split only when
+ * nothing is stored.
+ */
+/** One cookie holds every assignment, so a merchant running three tests spends one. */
+declare const ARM_COOKIE = "_ab_arm";
+/** Long enough to outlive any sane test, so returning visitors stay comparable. */
+declare const ARM_COOKIE_MAX_AGE_S: number;
+/**
+ * Analytics dimension NAMES — three flat scalars for the event enricher.
+ *
+ * No longer cookies. Middleware matches on page type alone and cannot know the
+ * resolved template, so it could report an arm the render then declined. The
+ * render publishes these on `window.__ab` instead, and the enrichers key off
+ * these same names. Kept here so the writer and the readers share one source.
+ *
+ * Flat because GA4 drops nested objects — which is why the UUID-keyed
+ * `ARM_COOKIE` cannot double as the reporting signal.
+ */
+/** The template under test, e.g. `bblunt-2_products_pdp3`. */
+declare const AB_EXPERIMENT_COOKIE = "ab_experiment";
+/** Which side of the split this visitor is on: `a` or `b`. */
+declare const AB_ARM_COOKIE = "ab_arm";
+/**
+ * The route family: `home` | `products` | `collection`. Looks redundant beside
+ * `ab_experiment`, but GA4 explorations cannot pattern-match a dimension, so
+ * "how did the PDP tests do overall" needs its own field. Values are the
+ * manifest's own `pageType` so cookie and API cannot disagree.
+ */
+declare const AB_PAGE_COOKIE = "ab_page";
+/**
+ * The arm for this experiment. `stored` wins whenever valid; `split` is read
+ * only for an unassigned visitor. `random` is injectable so tests can assert
+ * the boundary rather than sample it.
+ */
+declare function assignArm(experiment: Pick<ActiveExperiment, "id" | "split">, stored: ArmAssignments | null | undefined, random?: () => number): Arm;
+/**
+ * Parse the assignment cookie, tolerating any encoding depth: the server sees
+ * plain JSON (Next decodes once), the client sees it encoded. Hard-coding one
+ * makes the other silently return `{}`, which reads as "no assignment" and
+ * re-buckets the visitor. Unparseable is treated as absent, never an error.
+ */
+declare function readArmCookie(raw: string | undefined | null): ArmAssignments;
+/**
+ * Serialise assignments. Plain JSON, not encoded — every cookie API encodes on
+ * the way out, and doing it here too produced a double-encoded value.
+ *
+ * Bounded: an unbounded map grows the cookie until it breaks the header. The
+ * NEWEST entries are kept, by insertion order — so a caller re-assigning an
+ * existing experiment must delete the key before re-adding it, or object spread
+ * leaves it at its original position and the trim can drop the very experiment
+ * being assigned.
+ */
+declare function serialiseArmCookie(assignments: ArmAssignments, maxEntries?: number): string;
+/**
+ * Every tested section pinned to the visitor's arm. All sections flip together,
+ * or the result is unattributable to any single change.
+ *
+ * **Arm A is pinned explicitly, not left to the live body.** After a promote,
+ * `liveVariantId` is "b" — so "render the live body" means render B, and an
+ * un-pinned arm A would compare B with itself. Pinning costs nothing: the
+ * overlay returns by reference when a section already shows the wanted variant.
+ */
+declare function selectionFor(experiment: Pick<ActiveExperiment, "sectionIds">, arm: Arm): SectionVariantSelection | undefined;
+
+export { AB_ARM_COOKIE, AB_EXPERIMENT_COOKIE, AB_PAGE_COOKIE, ARM_COOKIE, ARM_COOKIE_MAX_AGE_S, type ActiveExperiment, type Arm, type ArmAssignments, type GetManifestOptions, MANIFEST_CACHE_TAG, MANIFEST_TIMEOUT_MS, MANIFEST_TTL_MS, type Manifest, type SectionVariantSelection, __resetManifestCache, assignArm, getManifest, getManifestSync, isExcludedPath, matchExperiment, matchesTargetUrls, pageTypeOf, readArmCookie, selectionFor, serialiseArmCookie, templateKeyOf };

package/dist/index.js

@@ -0,0 +1 @@
+'use strict';var l=Object.freeze({masterEnabled:true,revision:0,experiments:Object.freeze([])}),u=1e4,p="editor-experiments",A=1500,x=5e3,c=new Map,o=new Map,h=64;function y(){if(o.size<h)return;let t=o.keys().next().value;t!==void 0&&(o.delete(t),c.delete(t));}var f=new Map;function I(t){return !t||typeof t!="object"?false:Array.isArray(t.experiments)}async function b(t){let e=t.fetchImpl??fetch,i=new AbortController,n=setTimeout(()=>i.abort(),t.timeoutMs??A);try{let r=`${t.baseUrl.replace(/\/$/,"")}/api/v1/experiments/active?themeId=${encodeURIComponent(t.themeId)}`,s={signal:i.signal,next:{revalidate:3600,tags:[p]}},a=await e(r,s);if(!a.ok)return null;let d=await a.json();return I(d?.data)?d.data:null}catch{return null}finally{clearTimeout(n);}}function M(t){return `${t.baseUrl}::${t.themeId}`}function g(t,e){let i=e.now??Date.now,n=e.failureBackoffMs??x,r=c.get(t);return r!==void 0&&i()-r<n}function E(t,e){let i=f.get(t);if(i)return i;let n=e.now??Date.now,r=b(e).then(s=>(s?(c.delete(t),y(),o.set(t,{at:n(),data:s})):c.set(t,n()),s)).catch(()=>(c.set(t,n()),null)).finally(()=>f.delete(t));return f.set(t,r),r}async function T(t){let e=t.now??Date.now,i=t.ttlMs??u,n=M(t),r=o.get(n);return r&&e()-r.at<i?r.data:g(n,t)?r?.data??l:await E(n,t)??r?.data??l}function C(t){let e=t.now??Date.now,i=t.ttlMs??u,n=M(t),r=o.get(n);return (!r||e()-r.at>=i)&&!g(n,t)&&E(n,t),r?.data??l}function S(){o.clear(),f.clear(),c.clear();}var w="home",v="products",k="collection";function _(t){let e=m(t);return e==="/"?w:e.includes("/products/")?v:e.startsWith("/collections/")?k:null}function m(t){let e=t||"/";return e.length>1&&e.endsWith("/")&&(e=e.slice(0,-1)),e||"/"}function O(t,e){if(!e||e.length===0)return  true;let i=m(t);return e.some(n=>{let r=m(String(n??""));return r?r.endsWith("*")?i.startsWith(r.slice(0,-1)):i===r:false})}function P(t,e,i){if(!e||e.masterEnabled===false)return null;let n=e.experiments;if(!Array.isArray(n)||n.length===0)return null;let r=_(t);return r?n.find(s=>s&&s.pageType===r&&(i===void 0||s.templateKey===i)&&Array.isArray(s.sectionIds)&&s.sectionIds.length>0&&O(t,s.targetUrls))??null:null}function F(t){return t.startsWith("/_next")||t.startsWith("/api/")||t.includes("/variant/")||/\.[a-z0-9]+$/i.test(t)}function R(t,e,i){let n=typeof i=="string"?i.trim():"";return `${t}_${e}_${n||"default"}`}var G="_ab_arm",K=7776e3,N="ab_experiment",U="ab_arm",B="ab_page";function j(t,e,i=Math.random){let n=e?.[t.id];if(n==="a"||n==="b")return n;let r=t.split;return !Number.isFinite(r)||r<1||r>99?"a":i()*100<r?"b":"a"}function $(t){if(!t)return {};let e=t;for(let i=0;i<3;i++)try{let n=JSON.parse(e);if(!n||typeof n!="object"||Array.isArray(n))return {};let r={};for(let[s,a]of Object.entries(n))(a==="a"||a==="b")&&(r[s]=a);return r}catch{try{let n=decodeURIComponent(e);if(n===e)return {};e=n;}catch{return {}}}return {}}function D(t,e=20){let i=Object.entries(t).slice(-e);return JSON.stringify(Object.fromEntries(i))}function W(t,e){let i=t.sectionIds;if(!Array.isArray(i)||i.length===0)return;let n={};for(let r of i)typeof r=="string"&&r&&(n[r]=e);return Object.keys(n).length>0?n:void 0}exports.AB_ARM_COOKIE=U;exports.AB_EXPERIMENT_COOKIE=N;exports.AB_PAGE_COOKIE=B;exports.ARM_COOKIE=G;exports.ARM_COOKIE_MAX_AGE_S=K;exports.MANIFEST_CACHE_TAG=p;exports.MANIFEST_TIMEOUT_MS=A;exports.MANIFEST_TTL_MS=u;exports.__resetManifestCache=S;exports.assignArm=j;exports.getManifest=T;exports.getManifestSync=C;exports.isExcludedPath=F;exports.matchExperiment=P;exports.matchesTargetUrls=O;exports.pageTypeOf=_;exports.readArmCookie=$;exports.selectionFor=W;exports.serialiseArmCookie=D;exports.templateKeyOf=R;

package/dist/index.mjs

@@ -0,0 +1 @@
+var l=Object.freeze({masterEnabled:true,revision:0,experiments:Object.freeze([])}),u=1e4,p="editor-experiments",A=1500,x=5e3,c=new Map,o=new Map,h=64;function y(){if(o.size<h)return;let t=o.keys().next().value;t!==void 0&&(o.delete(t),c.delete(t));}var f=new Map;function I(t){return !t||typeof t!="object"?false:Array.isArray(t.experiments)}async function b(t){let e=t.fetchImpl??fetch,i=new AbortController,n=setTimeout(()=>i.abort(),t.timeoutMs??A);try{let r=`${t.baseUrl.replace(/\/$/,"")}/api/v1/experiments/active?themeId=${encodeURIComponent(t.themeId)}`,s={signal:i.signal,next:{revalidate:3600,tags:[p]}},a=await e(r,s);if(!a.ok)return null;let d=await a.json();return I(d?.data)?d.data:null}catch{return null}finally{clearTimeout(n);}}function M(t){return `${t.baseUrl}::${t.themeId}`}function g(t,e){let i=e.now??Date.now,n=e.failureBackoffMs??x,r=c.get(t);return r!==void 0&&i()-r<n}function E(t,e){let i=f.get(t);if(i)return i;let n=e.now??Date.now,r=b(e).then(s=>(s?(c.delete(t),y(),o.set(t,{at:n(),data:s})):c.set(t,n()),s)).catch(()=>(c.set(t,n()),null)).finally(()=>f.delete(t));return f.set(t,r),r}async function T(t){let e=t.now??Date.now,i=t.ttlMs??u,n=M(t),r=o.get(n);return r&&e()-r.at<i?r.data:g(n,t)?r?.data??l:await E(n,t)??r?.data??l}function C(t){let e=t.now??Date.now,i=t.ttlMs??u,n=M(t),r=o.get(n);return (!r||e()-r.at>=i)&&!g(n,t)&&E(n,t),r?.data??l}function S(){o.clear(),f.clear(),c.clear();}var w="home",v="products",k="collection";function _(t){let e=m(t);return e==="/"?w:e.includes("/products/")?v:e.startsWith("/collections/")?k:null}function m(t){let e=t||"/";return e.length>1&&e.endsWith("/")&&(e=e.slice(0,-1)),e||"/"}function O(t,e){if(!e||e.length===0)return  true;let i=m(t);return e.some(n=>{let r=m(String(n??""));return r?r.endsWith("*")?i.startsWith(r.slice(0,-1)):i===r:false})}function P(t,e,i){if(!e||e.masterEnabled===false)return null;let n=e.experiments;if(!Array.isArray(n)||n.length===0)return null;let r=_(t);return r?n.find(s=>s&&s.pageType===r&&(i===void 0||s.templateKey===i)&&Array.isArray(s.sectionIds)&&s.sectionIds.length>0&&O(t,s.targetUrls))??null:null}function F(t){return t.startsWith("/_next")||t.startsWith("/api/")||t.includes("/variant/")||/\.[a-z0-9]+$/i.test(t)}function R(t,e,i){let n=typeof i=="string"?i.trim():"";return `${t}_${e}_${n||"default"}`}var G="_ab_arm",K=7776e3,N="ab_experiment",U="ab_arm",B="ab_page";function j(t,e,i=Math.random){let n=e?.[t.id];if(n==="a"||n==="b")return n;let r=t.split;return !Number.isFinite(r)||r<1||r>99?"a":i()*100<r?"b":"a"}function $(t){if(!t)return {};let e=t;for(let i=0;i<3;i++)try{let n=JSON.parse(e);if(!n||typeof n!="object"||Array.isArray(n))return {};let r={};for(let[s,a]of Object.entries(n))(a==="a"||a==="b")&&(r[s]=a);return r}catch{try{let n=decodeURIComponent(e);if(n===e)return {};e=n;}catch{return {}}}return {}}function D(t,e=20){let i=Object.entries(t).slice(-e);return JSON.stringify(Object.fromEntries(i))}function W(t,e){let i=t.sectionIds;if(!Array.isArray(i)||i.length===0)return;let n={};for(let r of i)typeof r=="string"&&r&&(n[r]=e);return Object.keys(n).length>0?n:void 0}export{U as AB_ARM_COOKIE,N as AB_EXPERIMENT_COOKIE,B as AB_PAGE_COOKIE,G as ARM_COOKIE,K as ARM_COOKIE_MAX_AGE_S,p as MANIFEST_CACHE_TAG,A as MANIFEST_TIMEOUT_MS,u as MANIFEST_TTL_MS,S as __resetManifestCache,j as assignArm,T as getManifest,C as getManifestSync,F as isExcludedPath,P as matchExperiment,O as matchesTargetUrls,_ as pageTypeOf,$ as readArmCookie,W as selectionFor,D as serialiseArmCookie,R as templateKeyOf};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@shopkit/ab",
+  "version": "0.1.0",
+  "description": "Section-level A/B testing: reads the edge manifest, matches a request to an experiment, and assigns a visitor to an arm",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "keywords": [
+    "ab-testing",
+    "experiments",
+    "edge",
+    "middleware",
+    "shopkit"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}