@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 +11 -2
- package/dist/index.d.ts +16 -6
- package/dist/index.js +80 -52
- package/package.json +7 -8
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.
|
|
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'
|
|
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
|
|
150
|
-
*
|
|
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
|
|
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(
|
|
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
|
|
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 (
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
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
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
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,
|
|
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
|
|
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 (
|
|
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
|
-
|
|
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
|
|
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
|
+
}
|