@heyplaybook/hydrogen 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -62,7 +62,10 @@ for (const cookie of playbook.setCookieHeaders) {
62
62
  ```
63
63
 
64
64
  `createPlaybook` waits at most 300 ms for the test rules (1.5 s on a cold start), then
65
- uses the last good copy, or control for everyone. Rules are cached for 60 seconds. To
65
+ uses the last good copy, or control for everyone. Rules are cached for 60 seconds. If
66
+ the rules fetch fails or hangs, `createPlaybook` stops calling Playbook for 30 seconds
67
+ and renders straight away with the last good copy (or control), so an outage costs
68
+ at most one 1.5 s wait every 30 seconds per worker. To
66
69
  start the rules fetch earlier, call `prefetchRuleset({platformUrl, shopId, waitUntil})`
67
70
  at the top of your request handler.
68
71
 
@@ -162,7 +165,13 @@ banner that feeds it works with no extra code.
162
165
  - `?pb_preview=<token>`: a signed preview link from Playbook. The package verifies it with
163
166
  the platform, forces that arm, and keeps it in an HttpOnly session cookie
164
167
  (`SameSite=None; Secure`, because Playbook frames the store cross-site).
165
- `?pb_preview=off` clears it.
168
+ `?pb_preview=off` clears it. The cookie is only honoured on a framed request
169
+ (`Sec-Fetch-Dest: iframe`); a normal top-level visit clears it, so a reviewer never
170
+ carries a preview out of Playbook.
171
+ - A preview is **isolated** (0.2.0+): only the previewed test renders, every other test
172
+ serves its control (`reason: 'preview-isolated'`), overrides for other tests are ignored,
173
+ and the visit writes no visitor cookies and has no visitor id (`visitorId: null`), so it
174
+ sends no exposures or events and leaves no assignment behind.
166
175
  - `createPlaybook({overrides})`: force arms for QA from your own code, for example on
167
176
  preview hosts only. Forced arms ignore status and traffic split, still respect page
168
177
  targeting, and never send exposures.
package/dist/index.d.ts CHANGED
@@ -38,7 +38,9 @@ interface PlaybookRuleset {
38
38
  }
39
39
  /** One test's resolved outcome for the current visitor (ships to the client). */
40
40
  /** Why a visitor got this arm (debug/QA; mirrors the platform core's AssignReason). */
41
- type PlaybookAssignReason = 'preview' | 'override' | 'winner' | 'not-running' | 'no-visitor' | 'targeting-device' | 'targeting-visitor-type' | 'namespace' | 'hash-error' | 'coverage' | 'assigned' | 'unknown-test';
41
+ type PlaybookAssignReason = 'preview'
42
+ /** Another test is being previewed on this request: this one serves control. */
43
+ | 'preview-isolated' | 'override' | 'winner' | 'not-running' | 'no-visitor' | 'targeting-device' | 'targeting-visitor-type' | 'namespace' | 'hash-error' | 'coverage' | 'assigned' | 'unknown-test';
42
44
  interface PlaybookAssignment {
43
45
  arm: string;
44
46
  status: PlaybookTestStatus;
@@ -74,7 +76,7 @@ interface PlaybookState {
74
76
  now: string;
75
77
  rulesetVersion: string | null;
76
78
  /** Where this render's ruleset came from; null when disabled. */
77
- rulesetSource: 'memory' | 'stale' | 'fetched' | 'last-good' | 'cold-fallback' | null;
79
+ rulesetSource: 'memory' | 'stale' | 'fetched' | 'last-good' | 'cold-fallback' | 'backoff' | null;
78
80
  /**
79
81
  * The verified `pb_preview` token, or null. Only present for a merchant's own
80
82
  * verified preview link; lets the client carry `?pb_preview=` across in-app
@@ -123,6 +125,7 @@ interface PlaybookServerResult {
123
125
  /** Serializable; pass to the client through loader data. */
124
126
  state: PlaybookState;
125
127
  assignments: Record<string, PlaybookAssignment>;
128
+ /** Null when disabled, and during a verified preview (no visitor is tracked). */
126
129
  visitorId: string | null;
127
130
  preview: PlaybookPreview | null;
128
131
  /** Where the verified preview came from (this request's URL or the cookie). */
@@ -146,10 +149,15 @@ declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetch
146
149
  *
147
150
  * - Fresh for 60s; served stale for a further 300s while one background
148
151
  * refresh runs (stale-while-revalidate).
149
- * - Past that, a render waits at most RENDER_BUDGET_MS for a fresh copy, then
150
- * falls back to the last good ruleset; with none, the caller gets `null`
151
- * and everyone sees control.
152
+ * - Past that, a render waits at most RENDER_BUDGET_MS (COLD_RENDER_BUDGET_MS
153
+ * with nothing cached) for a fresh copy, then falls back to the last good
154
+ * ruleset; with none, the caller gets `null` and everyone sees control.
152
155
  * - A failed or malformed fetch never replaces a good cached copy.
156
+ * - A failure (timeout, network error, non-2xx, malformed body) — or a render
157
+ * that gave up waiting on its budget — opens a FAILURE_BACKOFF_MS window per
158
+ * shop. Inside it no render touches the network or waits: each one gets the
159
+ * last good copy, or control. The first render after the window retries.
160
+ * This keeps a hanging platform from costing every page request its budget.
153
161
  */
154
162
 
155
163
  /**
@@ -160,8 +168,10 @@ declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetch
160
168
  * - `last-good`: network missed the budget; served the last good copy.
161
169
  * - `cold-fallback`: nothing in memory and the network missed even the
162
170
  * cold budget (or failed) — everyone gets control for this render.
171
+ * - `backoff`: a recent fetch failed, so this render skipped the network and
172
+ * got the last good copy (or `null` — control — with none).
163
173
  */
164
- type RulesetSource = 'memory' | 'stale' | 'fetched' | 'last-good' | 'cold-fallback';
174
+ type RulesetSource = 'memory' | 'stale' | 'fetched' | 'last-good' | 'cold-fallback' | 'backoff';
165
175
  declare function getRulesetWithSource({ platformUrl, shopId, waitUntil, fetchImpl, }: {
166
176
  platformUrl: string;
167
177
  shopId: string;
package/dist/index.js CHANGED
@@ -57,6 +57,9 @@ function getBucketRanges(numVariations, coverage, weights) {
57
57
 
58
58
  // src/assign.ts
59
59
  var CONTROL_ARM = "control";
60
+ function controlArmOf(test) {
61
+ return controlKey(test);
62
+ }
60
63
  function controlKey(test) {
61
64
  return test.arms.find((a) => a.key === CONTROL_ARM)?.key ?? test.arms[0]?.key ?? CONTROL_ARM;
62
65
  }
@@ -408,6 +411,7 @@ async function verifyPreviewToken({
408
411
  var FRESH_MS = 6e4;
409
412
  var STALE_MS = 3e5;
410
413
  var RENDER_BUDGET_MS = 300;
414
+ var FAILURE_BACKOFF_MS = 3e4;
411
415
  var FETCH_TIMEOUT_MS = 5e3;
412
416
  var memory = /* @__PURE__ */ new Map();
413
417
  function rulesUrl(platformUrl, shopId) {
@@ -421,6 +425,9 @@ function isRuleset(value) {
421
425
  (t) => t && typeof t.key === "string" && typeof t.status === "string" && Array.isArray(t.arms) && t.arms.every((a) => a && typeof a.key === "string")
422
426
  );
423
427
  }
428
+ function inBackoff(entry, now) {
429
+ return entry.failedAt > 0 && now - entry.failedAt < FAILURE_BACKOFF_MS;
430
+ }
424
431
  function refresh(key, url, entry, fetchImpl) {
425
432
  if (entry.inflight) return entry.inflight;
426
433
  const controller = new AbortController();
@@ -434,8 +441,10 @@ function refresh(key, url, entry, fetchImpl) {
434
441
  if (!isRuleset(json)) throw new Error("ruleset malformed");
435
442
  entry.ruleset = json;
436
443
  entry.fetchedAt = Date.now();
444
+ entry.failedAt = 0;
437
445
  return json;
438
446
  }).catch((error) => {
447
+ entry.failedAt = Date.now();
439
448
  console.warn("[playbook] ruleset fetch failed", String(error));
440
449
  return entry.ruleset;
441
450
  }).finally(() => {
@@ -446,6 +455,7 @@ function refresh(key, url, entry, fetchImpl) {
446
455
  return entry.inflight;
447
456
  }
448
457
  var COLD_RENDER_BUDGET_MS = 1500;
458
+ var BUDGET_MISSED = /* @__PURE__ */ Symbol("budget-missed");
449
459
  async function getRulesetWithSource({
450
460
  platformUrl,
451
461
  shopId,
@@ -457,12 +467,17 @@ async function getRulesetWithSource({
457
467
  const entry = memory.get(key) ?? {
458
468
  ruleset: null,
459
469
  fetchedAt: 0,
470
+ failedAt: 0,
460
471
  inflight: null
461
472
  };
462
- const age = Date.now() - entry.fetchedAt;
473
+ const now = Date.now();
474
+ const age = now - entry.fetchedAt;
463
475
  if (entry.ruleset && age < FRESH_MS) {
464
476
  return { ruleset: entry.ruleset, source: "memory" };
465
477
  }
478
+ if (inBackoff(entry, now)) {
479
+ return { ruleset: entry.ruleset, source: "backoff" };
480
+ }
466
481
  if (entry.ruleset && age < FRESH_MS + STALE_MS) {
467
482
  const p2 = refresh(key, url, entry, fetchImpl);
468
483
  waitUntil?.(p2);
@@ -474,14 +489,17 @@ async function getRulesetWithSource({
474
489
  let timer;
475
490
  const budget = new Promise((resolve) => {
476
491
  timer = setTimeout(
477
- () => resolve(null),
492
+ () => resolve(BUDGET_MISSED),
478
493
  lastGood ? RENDER_BUDGET_MS : COLD_RENDER_BUDGET_MS
479
494
  );
480
495
  });
481
496
  const result = await Promise.race([p, budget]);
482
497
  clearTimeout(timer);
483
- if (result && result !== lastGood)
498
+ if (result === BUDGET_MISSED) {
499
+ if (entry.inflight && entry.failedAt === 0) entry.failedAt = Date.now();
500
+ } else if (result && result !== lastGood) {
484
501
  return { ruleset: result, source: "fetched" };
502
+ }
485
503
  if (lastGood) return { ruleset: lastGood, source: "last-good" };
486
504
  return { ruleset: null, source: "cold-fallback" };
487
505
  }
@@ -568,56 +586,59 @@ async function createPlaybook({
568
586
  ].find((v) => isValidVisitorId(v));
569
587
  const visitorId = existing ?? randomUuid();
570
588
  let visitorType = existing ? "returning" : "new";
571
- if (!existing) {
572
- setCookieHeaders.push(serializeCookie(NEW_SESSION_COOKIE, "1", { secure }));
573
- } else if (cookies[NEW_SESSION_COOKIE] === "1") {
574
- visitorType = "new";
575
- }
576
- if (persistentAllowed) {
577
- const refreshed = cookies[VISITOR_REFRESHED_COOKIE] === "1";
578
- if (cookies[VISITOR_COOKIE] !== visitorId || !refreshed) {
579
- setCookieHeaders.push(
580
- serializeCookie(VISITOR_COOKIE, visitorId, {
581
- maxAge: VISITOR_MAX_AGE,
582
- secure
583
- })
584
- );
585
- }
586
- if (!refreshed) {
587
- setCookieHeaders.push(
588
- serializeCookie(VISITOR_REFRESHED_COOKIE, "1", {
589
- secure,
590
- httpOnly: true
591
- })
592
- );
589
+ if (existing && cookies[NEW_SESSION_COOKIE] === "1") visitorType = "new";
590
+ const writeVisitorCookies = () => {
591
+ if (!existing) {
592
+ setCookieHeaders.push(serializeCookie(NEW_SESSION_COOKIE, "1", { secure }));
593
593
  }
594
- } else {
595
- if (cookies[SESSION_VISITOR_COOKIE] !== visitorId) {
596
- setCookieHeaders.push(
597
- serializeCookie(SESSION_VISITOR_COOKIE, visitorId, {
598
- secure,
599
- httpOnly: true
600
- })
601
- );
602
- }
603
- if (cookies[VISITOR_COOKIE]) {
604
- setCookieHeaders.push(
605
- serializeCookie(VISITOR_COOKIE, "", { maxAge: 0, secure })
606
- );
594
+ if (persistentAllowed) {
595
+ const refreshed = cookies[VISITOR_REFRESHED_COOKIE] === "1";
596
+ if (cookies[VISITOR_COOKIE] !== visitorId || !refreshed) {
597
+ setCookieHeaders.push(
598
+ serializeCookie(VISITOR_COOKIE, visitorId, {
599
+ maxAge: VISITOR_MAX_AGE,
600
+ secure
601
+ })
602
+ );
603
+ }
604
+ if (!refreshed) {
605
+ setCookieHeaders.push(
606
+ serializeCookie(VISITOR_REFRESHED_COOKIE, "1", {
607
+ secure,
608
+ httpOnly: true
609
+ })
610
+ );
611
+ }
612
+ } else {
613
+ if (cookies[SESSION_VISITOR_COOKIE] !== visitorId) {
614
+ setCookieHeaders.push(
615
+ serializeCookie(SESSION_VISITOR_COOKIE, visitorId, {
616
+ secure,
617
+ httpOnly: true
618
+ })
619
+ );
620
+ }
621
+ if (cookies[VISITOR_COOKIE]) {
622
+ setCookieHeaders.push(
623
+ serializeCookie(VISITOR_COOKIE, "", { maxAge: 0, secure })
624
+ );
625
+ }
607
626
  }
608
- }
609
- if (cookies[LEGACY_VISITOR_COOKIE]) {
610
- setCookieHeaders.push(
611
- serializeCookie(LEGACY_VISITOR_COOKIE, "", { maxAge: 0, secure })
612
- );
613
- if (domain) {
627
+ if (cookies[LEGACY_VISITOR_COOKIE]) {
614
628
  setCookieHeaders.push(
615
- serializeCookie(LEGACY_VISITOR_COOKIE, "", { maxAge: 0, domain, secure })
629
+ serializeCookie(LEGACY_VISITOR_COOKIE, "", { maxAge: 0, secure })
616
630
  );
631
+ if (domain) {
632
+ setCookieHeaders.push(
633
+ serializeCookie(LEGACY_VISITOR_COOKIE, "", { maxAge: 0, domain, secure })
634
+ );
635
+ }
617
636
  }
618
- }
637
+ };
619
638
  const paramToken = url.searchParams.get(PREVIEW_PARAM);
620
- const cookieToken = cookies[PREVIEW_COOKIE];
639
+ const framed = request.headers.get("sec-fetch-dest") === "iframe";
640
+ const rawCookieToken = cookies[PREVIEW_COOKIE];
641
+ const cookieToken = framed ? rawCookieToken : void 0;
621
642
  const PREVIEW_COOKIE_OPTS = { httpOnly: true, sameSite: "None" };
622
643
  const clearPreview = () => setCookieHeaders.push(
623
644
  serializeCookie(PREVIEW_COOKIE, "", { maxAge: 0, ...PREVIEW_COOKIE_OPTS })
@@ -626,7 +647,9 @@ async function createPlaybook({
626
647
  let previewSource = null;
627
648
  let previewPromise = Promise.resolve(null);
628
649
  if (paramToken === "off" || paramToken === "") {
629
- if (cookieToken) clearPreview();
650
+ if (rawCookieToken) clearPreview();
651
+ } else if (!paramToken && rawCookieToken && !framed) {
652
+ clearPreview();
630
653
  } else if (paramToken || cookieToken) {
631
654
  const token = paramToken || cookieToken;
632
655
  previewPromise = verifyPreviewToken({
@@ -653,16 +676,21 @@ async function createPlaybook({
653
676
  getRulesetWithSource({ platformUrl: base, shopId, waitUntil, fetchImpl }),
654
677
  previewPromise
655
678
  ]);
679
+ const isolated = !!preview;
680
+ if (!isolated) writeVisitorCookies();
681
+ const stateVisitorId = isolated ? null : visitorId;
656
682
  const assignments = {};
657
683
  for (const test of ruleset?.tests ?? []) {
658
- assignments[test.key] = assignTest(test, {
659
- visitorId,
684
+ const a = assignTest(test, {
685
+ visitorId: stateVisitorId,
660
686
  device,
661
687
  visitorType,
662
688
  preview
663
689
  });
690
+ assignments[test.key] = isolated && preview?.testKey !== test.key ? { ...a, arm: controlArmOf(test), inTest: false, forced: false, reason: "preview-isolated" } : a;
664
691
  }
665
692
  for (const o of overrides ?? []) {
693
+ if (isolated && preview?.testKey !== o.testKey) continue;
666
694
  if (preview?.testKey === o.testKey && !(previewSource === "session" && o.source === "request")) {
667
695
  continue;
668
696
  }
@@ -681,7 +709,7 @@ async function createPlaybook({
681
709
  state: {
682
710
  enabled: true,
683
711
  shopId,
684
- visitorId,
712
+ visitorId: stateVisitorId,
685
713
  visitorType,
686
714
  device,
687
715
  now,
@@ -694,7 +722,7 @@ async function createPlaybook({
694
722
  previewToken
695
723
  },
696
724
  assignments,
697
- visitorId,
725
+ visitorId: stateVisitorId,
698
726
  preview,
699
727
  previewSource,
700
728
  setCookieHeaders
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@heyplaybook/hydrogen",
3
- "version": "0.1.0",
3
+ "version": "0.2.1",
4
4
  "description": "Playbook store-edit tests for Shopify Hydrogen storefronts: server-side assignment, consent-gated visitor cookie, in-view exposures and cart attribution.",
5
5
  "license": "MIT",
6
6
  "author": "Pack Digital Inc.",
@@ -39,12 +39,6 @@
39
39
  "publishConfig": {
40
40
  "access": "public"
41
41
  },
42
- "scripts": {
43
- "build": "tsup",
44
- "type-check": "tsc --noEmit",
45
- "test": "vitest run",
46
- "prepublishOnly": "pnpm run test && pnpm run build"
47
- },
48
42
  "peerDependencies": {
49
43
  "react": ">=18"
50
44
  },
@@ -54,5 +48,10 @@
54
48
  "tsup": "^8.5.1",
55
49
  "typescript": "^5.3.0",
56
50
  "vitest": "^2.0.0"
51
+ },
52
+ "scripts": {
53
+ "build": "tsup",
54
+ "type-check": "tsc --noEmit",
55
+ "test": "vitest run"
57
56
  }
58
- }
57
+ }