@heyplaybook/hydrogen 0.1.0 → 0.2.0

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
@@ -162,7 +162,13 @@ banner that feeds it works with no extra code.
162
162
  - `?pb_preview=<token>`: a signed preview link from Playbook. The package verifies it with
163
163
  the platform, forces that arm, and keeps it in an HttpOnly session cookie
164
164
  (`SameSite=None; Secure`, because Playbook frames the store cross-site).
165
- `?pb_preview=off` clears it.
165
+ `?pb_preview=off` clears it. The cookie is only honoured on a framed request
166
+ (`Sec-Fetch-Dest: iframe`); a normal top-level visit clears it, so a reviewer never
167
+ carries a preview out of Playbook.
168
+ - A preview is **isolated** (0.2.0+): only the previewed test renders, every other test
169
+ serves its control (`reason: 'preview-isolated'`), overrides for other tests are ignored,
170
+ and the visit writes no visitor cookies and has no visitor id (`visitorId: null`), so it
171
+ sends no exposures or events and leaves no assignment behind.
166
172
  - `createPlaybook({overrides})`: force arms for QA from your own code, for example on
167
173
  preview hosts only. Forced arms ignore status and traffic split, still respect page
168
174
  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;
@@ -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). */
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
  }
@@ -568,56 +571,59 @@ async function createPlaybook({
568
571
  ].find((v) => isValidVisitorId(v));
569
572
  const visitorId = existing ?? randomUuid();
570
573
  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
- );
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
- );
574
+ if (existing && cookies[NEW_SESSION_COOKIE] === "1") visitorType = "new";
575
+ const writeVisitorCookies = () => {
576
+ if (!existing) {
577
+ setCookieHeaders.push(serializeCookie(NEW_SESSION_COOKIE, "1", { secure }));
602
578
  }
603
- if (cookies[VISITOR_COOKIE]) {
604
- setCookieHeaders.push(
605
- serializeCookie(VISITOR_COOKIE, "", { maxAge: 0, secure })
606
- );
579
+ if (persistentAllowed) {
580
+ const refreshed = cookies[VISITOR_REFRESHED_COOKIE] === "1";
581
+ if (cookies[VISITOR_COOKIE] !== visitorId || !refreshed) {
582
+ setCookieHeaders.push(
583
+ serializeCookie(VISITOR_COOKIE, visitorId, {
584
+ maxAge: VISITOR_MAX_AGE,
585
+ secure
586
+ })
587
+ );
588
+ }
589
+ if (!refreshed) {
590
+ setCookieHeaders.push(
591
+ serializeCookie(VISITOR_REFRESHED_COOKIE, "1", {
592
+ secure,
593
+ httpOnly: true
594
+ })
595
+ );
596
+ }
597
+ } else {
598
+ if (cookies[SESSION_VISITOR_COOKIE] !== visitorId) {
599
+ setCookieHeaders.push(
600
+ serializeCookie(SESSION_VISITOR_COOKIE, visitorId, {
601
+ secure,
602
+ httpOnly: true
603
+ })
604
+ );
605
+ }
606
+ if (cookies[VISITOR_COOKIE]) {
607
+ setCookieHeaders.push(
608
+ serializeCookie(VISITOR_COOKIE, "", { maxAge: 0, secure })
609
+ );
610
+ }
607
611
  }
608
- }
609
- if (cookies[LEGACY_VISITOR_COOKIE]) {
610
- setCookieHeaders.push(
611
- serializeCookie(LEGACY_VISITOR_COOKIE, "", { maxAge: 0, secure })
612
- );
613
- if (domain) {
612
+ if (cookies[LEGACY_VISITOR_COOKIE]) {
614
613
  setCookieHeaders.push(
615
- serializeCookie(LEGACY_VISITOR_COOKIE, "", { maxAge: 0, domain, secure })
614
+ serializeCookie(LEGACY_VISITOR_COOKIE, "", { maxAge: 0, secure })
616
615
  );
616
+ if (domain) {
617
+ setCookieHeaders.push(
618
+ serializeCookie(LEGACY_VISITOR_COOKIE, "", { maxAge: 0, domain, secure })
619
+ );
620
+ }
617
621
  }
618
- }
622
+ };
619
623
  const paramToken = url.searchParams.get(PREVIEW_PARAM);
620
- const cookieToken = cookies[PREVIEW_COOKIE];
624
+ const framed = request.headers.get("sec-fetch-dest") === "iframe";
625
+ const rawCookieToken = cookies[PREVIEW_COOKIE];
626
+ const cookieToken = framed ? rawCookieToken : void 0;
621
627
  const PREVIEW_COOKIE_OPTS = { httpOnly: true, sameSite: "None" };
622
628
  const clearPreview = () => setCookieHeaders.push(
623
629
  serializeCookie(PREVIEW_COOKIE, "", { maxAge: 0, ...PREVIEW_COOKIE_OPTS })
@@ -626,7 +632,9 @@ async function createPlaybook({
626
632
  let previewSource = null;
627
633
  let previewPromise = Promise.resolve(null);
628
634
  if (paramToken === "off" || paramToken === "") {
629
- if (cookieToken) clearPreview();
635
+ if (rawCookieToken) clearPreview();
636
+ } else if (!paramToken && rawCookieToken && !framed) {
637
+ clearPreview();
630
638
  } else if (paramToken || cookieToken) {
631
639
  const token = paramToken || cookieToken;
632
640
  previewPromise = verifyPreviewToken({
@@ -653,16 +661,21 @@ async function createPlaybook({
653
661
  getRulesetWithSource({ platformUrl: base, shopId, waitUntil, fetchImpl }),
654
662
  previewPromise
655
663
  ]);
664
+ const isolated = !!preview;
665
+ if (!isolated) writeVisitorCookies();
666
+ const stateVisitorId = isolated ? null : visitorId;
656
667
  const assignments = {};
657
668
  for (const test of ruleset?.tests ?? []) {
658
- assignments[test.key] = assignTest(test, {
659
- visitorId,
669
+ const a = assignTest(test, {
670
+ visitorId: stateVisitorId,
660
671
  device,
661
672
  visitorType,
662
673
  preview
663
674
  });
675
+ assignments[test.key] = isolated && preview?.testKey !== test.key ? { ...a, arm: controlArmOf(test), inTest: false, forced: false, reason: "preview-isolated" } : a;
664
676
  }
665
677
  for (const o of overrides ?? []) {
678
+ if (isolated && preview?.testKey !== o.testKey) continue;
666
679
  if (preview?.testKey === o.testKey && !(previewSource === "session" && o.source === "request")) {
667
680
  continue;
668
681
  }
@@ -681,7 +694,7 @@ async function createPlaybook({
681
694
  state: {
682
695
  enabled: true,
683
696
  shopId,
684
- visitorId,
697
+ visitorId: stateVisitorId,
685
698
  visitorType,
686
699
  device,
687
700
  now,
@@ -694,7 +707,7 @@ async function createPlaybook({
694
707
  previewToken
695
708
  },
696
709
  assignments,
697
- visitorId,
710
+ visitorId: stateVisitorId,
698
711
  preview,
699
712
  previewSource,
700
713
  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.0",
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
+ }