@heyplaybook/hydrogen 0.2.1 → 0.6.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/dist/index.d.ts CHANGED
@@ -1,5 +1,139 @@
1
1
  import * as react_jsx_runtime from 'react/jsx-runtime';
2
- import { ReactNode } from 'react';
2
+ import * as react from 'react';
3
+ import { ReactNode, Component } from 'react';
4
+
5
+ /**
6
+ * Analytics consent — vendored from the Playbook platform's shared consent module (the
7
+ * storefront SDKs' single source; see Playbook's
8
+ * `.ai/docs/STOREFRONT-CONSENT-GATING.md`, which is binding). Keep the logic
9
+ * identical; this copy exists only because the store can't import the
10
+ * Playbook monorepo.
11
+ *
12
+ * Contract:
13
+ * - Read Shopify's Customer Privacy API (`analytics` purpose only, matching
14
+ * the checkout Web Pixel). Never integrate with a CMP directly — any CMP that
15
+ * feeds the API (e.g. TrueVault Polaris) works with no code here.
16
+ * - RENDERING is functional and never gated. The persistent visitor cookie,
17
+ * exposures, events and the cart attribute are ANALYTICS and are gated.
18
+ * - FAIL OPEN only when the API is genuinely absent; CLOSED when it exists and
19
+ * denies, or while a known-present API is still resolving.
20
+ *
21
+ * Client: `window`/`document` touched at CALL time only (safe to import on the
22
+ * server). Server: `analyticsConsentFromCookie` reads Shopify's own
23
+ * `_tracking_consent` cookie, the same signal the checkout pixel trusts.
24
+ *
25
+ * 0.5.0: a present API whose `consentStatus` is a string other than
26
+ * `'loaded'` is still resolving (pending). Before it loads, the API answers
27
+ * with a no-data fallback (every `*Allowed()` true, no banner owed) that
28
+ * would otherwise read as granted in a region that requires a banner. An
29
+ * API with no `consentStatus` field at all (older script versions) is read
30
+ * as before. The decision carried by `visitorConsentCollected`'s
31
+ * `event.detail` is remembered and used until the API itself has loaded.
32
+ */
33
+ type ConsentState = 'granted' | 'denied' | 'pending' | 'absent';
34
+ /**
35
+ * Force the "a CMP is present" branch: a headless store whose CMP injects
36
+ * `Shopify.customerPrivacy` after we boot (e.g. TrueVault Polaris). Without it a
37
+ * first-time visitor with no `_tracking_consent` cookie would fail open.
38
+ */
39
+ declare function declareConsentRequired(): void;
40
+ /** Wait for the API: already loaded → `loadFeatures()` → bounded poll → give up. */
41
+ declare function waitForConsentAPI(): Promise<void>;
42
+ /** Granted right now? Closed while resolving a known-present API; open if absent. */
43
+ declare function isAnalyticsConsentGranted(): boolean;
44
+ declare function getConsentState(): ConsentState;
45
+ /**
46
+ * Events after which a present API may have finished loading the visitor's
47
+ * consent (`consentStatus` → 'loaded'): Shopify's consent data loaded, or
48
+ * Hydrogen loaded the Customer Privacy script. `visitorConsentCollected` is
49
+ * handled by `onConsentChange` (decision read from `event.detail`).
50
+ */
51
+ declare const CONSENT_LOADED_EVENTS: readonly ["consentTrackingApiLoaded", "shopifyCustomerPrivacyApiLoaded"];
52
+ /** Call `cb` after each "consent loaded" event (document and window). */
53
+ declare function onConsentLoaded(cb: () => void): () => void;
54
+ /** Subscribe to `visitorConsentCollected` (decision read from event.detail). */
55
+ declare function onConsentChange(cb: (granted: boolean) => void): () => void;
56
+ /**
57
+ * SERVER: analytics consent from Shopify's `_tracking_consent` cookie.
58
+ * Returns `granted` / `denied`, `pending` when the cookie exists but analytics
59
+ * is undecided, and `absent` when there is no cookie at all. Tolerates both
60
+ * known payload shapes (`con.CMP.a` = "1"/"0"/"" and `purposes.a` boolean);
61
+ * anything unparseable is `pending` (closed), never granted.
62
+ */
63
+ declare function analyticsConsentFromCookie(raw: string | undefined): ConsentState;
64
+
65
+ /** SERVER half: the decision for one request. */
66
+ interface PlaybookServerConsent {
67
+ /** Stable name, for debug output. */
68
+ readonly id: string;
69
+ /** SERVER: the decision for this request. Never throws. */
70
+ fromRequest(request: Request): ConsentState;
71
+ }
72
+ /** CLIENT half: the live decision in the browser. */
73
+ interface PlaybookClientConsent {
74
+ /** Stable name, for debug output. */
75
+ readonly id: string;
76
+ /** CLIENT: the decision right now. `window`/`document` read at call time. */
77
+ read(): ConsentState;
78
+ /** CLIENT: call `onChange` whenever the decision may have changed. */
79
+ subscribe(onChange: () => void): () => void;
80
+ }
81
+ /** Both halves from one decision function (unchanged since 0.3.0). */
82
+ interface PlaybookConsentAdapter extends PlaybookServerConsent, PlaybookClientConsent {
83
+ }
84
+ /**
85
+ * Map a store's own analytics answer to a `ConsentState`, so a store adapter
86
+ * doesn't hand-roll tri-state logic:
87
+ * `true` / `'granted'` / `'yes'` → granted, `false` / `'denied'` / `'no'` →
88
+ * denied, anything else (null, undefined, `'unknown'`, `''`) → pending
89
+ * (closed). Never `absent`: a store that wires an adapter has a consent
90
+ * system, so "no answer" must not fail open.
91
+ */
92
+ declare function consentFromAnalytics(value: boolean | string | null | undefined): ConsentState;
93
+ /**
94
+ * The built-in browser source: Shopify's Customer Privacy API (what
95
+ * `<PlaybookRoot>` uses when no client consent is passed).
96
+ *
97
+ * - Pending while the API is resolving, and while it reports a
98
+ * `consentStatus` other than `'loaded'` (its pre-load fallback answers
99
+ * "everything allowed").
100
+ * - Re-read when the consent data or the privacy script loads
101
+ * (`consentTrackingApiLoaded`, `shopifyCustomerPrivacyApiLoaded`).
102
+ * - On `visitorConsentCollected`, the decision comes from `event.detail`
103
+ * (the API's methods may not exist yet when it fires).
104
+ * - Fails OPEN (`absent`) only when no consent system is present at all.
105
+ *
106
+ * Module-level state (one listener, one wait) is shared by every subscriber.
107
+ */
108
+ declare const shopifyCustomerPrivacyConsent: PlaybookClientConsent;
109
+ /** TrueVault Polaris's banner cookie (the one Sand Cloud's Blotout/analytics read). */
110
+ declare const TRUEVAULT_CONSENT_COOKIE = "polaris_consent_settings";
111
+ interface TrueVaultConsentOptions {
112
+ /**
113
+ * Decision while the visitor has no `polaris_consent_settings` cookie yet.
114
+ * Default `pending` (closed): nothing analytics runs until Polaris records a
115
+ * decision. `granted` matches an opt-out regime where the absence of a
116
+ * decision means "allowed" (Sand Cloud's own `getPolarisCanTrack`).
117
+ */
118
+ whenMissing?: Extract<ConsentState, 'pending' | 'granted'>;
119
+ /**
120
+ * Global Privacy Control. Default `follow-banner`: GPC is a sale/sharing
121
+ * opt-out, Playbook doesn't sell data, so GPC alone doesn't deny analytics —
122
+ * only the banner's `analyticsPermitted` decides (Polaris itself keeps
123
+ * `analyticsPermitted` and only flips `notOptedOut` on GPC). `deny`: a store
124
+ * that wants GPC to switch analytics off too.
125
+ */
126
+ gpc?: 'follow-banner' | 'deny';
127
+ }
128
+ /**
129
+ * Pure decision shared by server and client. `raw` is the cookie value exactly
130
+ * as stored (URI-encoded JSON or plain JSON); `gpc` is the GPC signal.
131
+ */
132
+ declare function trueVaultDecision(raw: string | null | undefined, gpc: boolean, { whenMissing, gpc: gpcMode }?: TrueVaultConsentOptions): ConsentState;
133
+ /** TrueVault Polaris: `polaris_consent_settings.analyticsPermitted`, GPC-aware. */
134
+ declare function createTrueVaultConsent(options?: TrueVaultConsentOptions): PlaybookConsentAdapter;
135
+ /** TrueVault with the defaults (closed until a decision; GPC follows the banner). */
136
+ declare const truevaultConsent: PlaybookConsentAdapter;
3
137
 
4
138
  /**
5
139
  * Playbook code-test types. Mirrors the ruleset contract served by
@@ -40,14 +174,14 @@ interface PlaybookRuleset {
40
174
  /** Why a visitor got this arm (debug/QA; mirrors the platform core's AssignReason). */
41
175
  type PlaybookAssignReason = 'preview'
42
176
  /** 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';
177
+ | 'preview-isolated' | 'winner' | 'not-running' | 'no-visitor' | 'targeting-device' | 'targeting-visitor-type' | 'namespace' | 'hash-error' | 'coverage' | 'assigned' | 'unknown-test';
44
178
  interface PlaybookAssignment {
45
179
  arm: string;
46
180
  status: PlaybookTestStatus;
47
181
  reason: PlaybookAssignReason;
48
182
  /** True only when the visitor was bucketed into a RUNNING test. */
49
183
  inTest: boolean;
50
- /** True when the arm comes from a verified `pb_preview` token or a QA override. */
184
+ /** True when the arm comes from a verified `pb_preview` token. */
51
185
  forced: boolean;
52
186
  config: Record<string, unknown>;
53
187
  /** Evaluated on the client against the current route (SPA navigation). */
@@ -61,8 +195,9 @@ interface PlaybookState {
61
195
  visitorType: PlaybookVisitorType;
62
196
  device: PlaybookDevice;
63
197
  /**
64
- * Analytics consent as the server saw it (`_tracking_consent` cookie). The
65
- * client re-reads the live Customer Privacy API before any beacon.
198
+ * Analytics consent as the server saw it (the server consent source, default
199
+ * `_tracking_consent`). The client re-reads its own live source before any
200
+ * beacon.
66
201
  */
67
202
  serverConsent: 'granted' | 'denied' | 'pending' | 'absent';
68
203
  /** The store declared a late-loading CMP (closed until it answers). */
@@ -99,16 +234,6 @@ interface CreatePlaybookOptions {
99
234
  /** Keeps a background ruleset refresh alive after the response (Workers). */
100
235
  waitUntil?: (p: Promise<unknown>) => void;
101
236
  fetchImpl?: typeof fetch;
102
- /**
103
- * Arms to force regardless of status/targeting (QA). Forced views never
104
- * expose. The CALLER decides when overrides are trusted (e.g. preview hosts
105
- * only) — this module applies whatever it is given.
106
- *
107
- * Precedence per test: a `pb_preview` token on THIS request > an override
108
- * from this request (`source: 'request'`) > a `pb_preview` carried by the
109
- * session cookie > a session override > natural assignment.
110
- */
111
- overrides?: PlaybookOverride[];
112
237
  /**
113
238
  * The store's CMP may load after first paint (headless, e.g. TrueVault
114
239
  * Polaris): with no `_tracking_consent` cookie yet, treat consent as pending
@@ -116,10 +241,12 @@ interface CreatePlaybookOptions {
116
241
  * `data-pb-consent="required"`.
117
242
  */
118
243
  consentRequired?: boolean;
119
- }
120
- interface PlaybookOverride extends PlaybookPreview {
121
- /** `request`: set by this request's URL; `session`: replayed from a cookie. */
122
- source?: 'request' | 'session';
244
+ /**
245
+ * Server consent source when the store's CMP doesn't feed Shopify's
246
+ * `_tracking_consent` cookie (e.g. `truevaultConsent`, or a store's own
247
+ * `PlaybookServerConsent`). Replaces the `_tracking_consent` read.
248
+ */
249
+ consent?: PlaybookServerConsent;
123
250
  }
124
251
  interface PlaybookServerResult {
125
252
  /** Serializable; pass to the client through loader data. */
@@ -142,7 +269,7 @@ declare function detectGeo(headers: Headers): {
142
269
  region: string | null;
143
270
  };
144
271
  declare function detectDevice(userAgent: string | null): PlaybookDevice;
145
- declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetchImpl, overrides, consentRequired, }: CreatePlaybookOptions): Promise<PlaybookServerResult>;
272
+ declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetchImpl, consentRequired, consent: consentAdapter, }: CreatePlaybookOptions): Promise<PlaybookServerResult>;
146
273
 
147
274
  /**
148
275
  * Ruleset fetch with an in-memory (per-isolate) cache.
@@ -158,8 +285,19 @@ declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetch
158
285
  * shop. Inside it no render touches the network or waits: each one gets the
159
286
  * last good copy, or control. The first render after the window retries.
160
287
  * This keeps a hanging platform from costing every page request its budget.
288
+ *
289
+ * 0.6.0: the cache itself is `createCachedJsonFetcher`, generic over the
290
+ * payload, so the targeting manifest (`./targeting`) shares the exact same
291
+ * fresh / stale / budget / backoff / warn-once behaviour. The ruleset is its
292
+ * first user; nothing about the ruleset path changed.
161
293
  */
162
294
 
295
+ /**
296
+ * The ruleset with only its valid rules, or null when the envelope itself is
297
+ * malformed. A single bad rule is DROPPED (its test serves control) rather
298
+ * than discarding every other test; a bad envelope keeps the last good copy.
299
+ */
300
+ declare function sanitizeRuleset(value: unknown): PlaybookRuleset | null;
163
301
  /**
164
302
  * Where the ruleset for this render came from (debug/QA):
165
303
  * - `memory`: fresh in-memory copy (< 60s).
@@ -187,48 +325,368 @@ declare function getRulesetWithSource({ platformUrl, shopId, waitUntil, fetchImp
187
325
  */
188
326
  declare function prefetchRuleset(args: Parameters<typeof getRulesetWithSource>[0]): void;
189
327
 
328
+ interface CartAttribute {
329
+ key: string;
330
+ value?: string | null;
331
+ }
332
+ interface CartWriteResult {
333
+ ok: boolean;
334
+ /** The cart's attributes after the write, when the response carried them. */
335
+ attributes?: ReadonlyArray<CartAttribute> | null;
336
+ }
337
+ /** Merge `add` into `current` by key (an empty value removes the key). */
338
+ declare function mergeAttributes(current: ReadonlyArray<CartAttribute> | null | undefined, add: ReadonlyArray<CartAttribute>): {
339
+ key: string;
340
+ value: string;
341
+ }[];
342
+ interface CartEndpointOptions {
343
+ /** The store's cart action route. Default `/api/cart` (Pack Hydrogen). */
344
+ endpoint?: string;
345
+ /**
346
+ * The endpoint reads the cart and merges attributes itself (Pack's
347
+ * `/api/cart`): send only the keys being written. Default false: send the
348
+ * full merged list, because Hydrogen's `cart.updateAttributes` REPLACES the
349
+ * whole list and a lone `_pb_vid` would wipe every other attribute.
350
+ */
351
+ serverMerges?: boolean;
352
+ fetchImpl?: typeof fetch;
353
+ }
190
354
  /**
191
- * Analytics consent — vendored from the Playbook platform's shared consent module (the
192
- * storefront SDKs' single source; see Playbook's
193
- * `.ai/docs/STOREFRONT-CONSENT-GATING.md`, which is binding). Keep the logic
194
- * identical; this copy exists only because the store can't import the
195
- * Playbook monorepo.
355
+ * Default writer: POSTs to the store's cart endpoint in both shapes Hydrogen
356
+ * stores use (`action` + `attributes` fields, and CartForm's
357
+ * `cartFormInput`). Never throws.
358
+ */
359
+ declare function createCartAttributeWriter({ endpoint, serverMerges, fetchImpl, }?: CartEndpointOptions): (add: ReadonlyArray<CartAttribute>, current: ReadonlyArray<CartAttribute> | null | undefined) => Promise<CartWriteResult>;
360
+ /** Default re-read: `GET endpoint` → `{cart: {attributes}}`. Null on failure. */
361
+ declare function createCartAttributeReader({ endpoint, fetchImpl, }?: CartEndpointOptions): () => Promise<CartAttribute[] | null>;
362
+ type CartAttributeWriter = ReturnType<typeof createCartAttributeWriter>;
363
+ type CartAttributeReader = ReturnType<typeof createCartAttributeReader>;
364
+ interface CartSyncSnapshot {
365
+ cartId: string | null | undefined;
366
+ attributes: ReadonlyArray<CartAttribute> | null | undefined;
367
+ /** The store's cart status, READ only. Writes wait for `idle` (or none). */
368
+ status?: string | null;
369
+ visitorId: string | null | undefined;
370
+ /** Consent allows it AND the visitor is in at least one running test. */
371
+ eligible: boolean;
372
+ }
373
+ type CartSyncEvent = {
374
+ type: 'scheduled';
375
+ cartId: string;
376
+ } | {
377
+ type: 'written';
378
+ cartId: string;
379
+ ok: boolean;
380
+ } | {
381
+ type: 'restored';
382
+ cartId: string;
383
+ keys: string[];
384
+ ok: boolean;
385
+ } | {
386
+ type: 'capped';
387
+ cartId: string;
388
+ };
389
+ interface CartSyncOptions {
390
+ write: CartAttributeWriter;
391
+ read?: CartAttributeReader;
392
+ maxWritesPerCart?: number;
393
+ idleMs?: number;
394
+ /** Keys another writer owns; restored if a write loses them. */
395
+ protectedKeyPrefixes?: string[];
396
+ onEvent?: (event: CartSyncEvent) => void;
397
+ }
398
+ declare const CART_SYNC_IDLE_MS = 3000;
399
+ declare const MAX_WRITES_PER_CART = 3;
400
+ /**
401
+ * The client write path as a small state machine (no React), so every rule
402
+ * above is unit-testable. Call `update()` with each new cart snapshot.
403
+ */
404
+ declare function createCartAttributeSync({ write, read, maxWritesPerCart, idleMs, protectedKeyPrefixes, onEvent, }: CartSyncOptions): {
405
+ update(s: CartSyncSnapshot): void;
406
+ dispose(): void;
407
+ /** Test/debug: writes made for the current cart. */
408
+ writesForCart(cartId: string): number;
409
+ };
410
+ /**
411
+ * Returns the cart-create input with `_pb_vid` in its attributes (other
412
+ * attributes kept; an existing `_pb_vid` replaced). `attribute` null → the
413
+ * input unchanged. Use in the store's cart action for `Create`, and for a
414
+ * `LinesAdd` that will create the cart (no cart id yet).
415
+ */
416
+ declare function withPlaybookCartAttribute<T extends object>(input: T | null | undefined, attribute: CartAttribute | null): T & {
417
+ attributes?: {
418
+ key: string;
419
+ value: string;
420
+ }[];
421
+ };
422
+
423
+ /** Hard ceiling on the hide, in ms. The cloak can be shorter, never longer. */
424
+ declare const CLOAK_MAX_MS = 1500;
425
+ /** The bundle `playbook.js` injects on Hydrogen (CDN sibling of the loader). */
426
+ declare const DEFAULT_EXPERIENCE_SDK_URL = "https://cdn.heyplaybook.com/experience-sdk.js";
427
+ declare const CLOAK_STYLE_ID = "pb-cloak";
428
+ declare const EXPERIENCE_SDK_SCRIPT_ID = "pb-experience-sdk";
429
+ /** What the server decided for this request (`loaderData().cloak`). */
430
+ interface PlaybookCloakConfig {
431
+ /** This path's manifest page key (`product:<handle>`, `home:`, …). */
432
+ targetedPage: string;
433
+ /** `data-pb-shop`: the storefront domain the manifest was read for. */
434
+ shopDomain: string;
435
+ /** `data-pb-api-base`: where the SDK calls the resolver (app proxy). */
436
+ apiBase: string;
437
+ }
438
+ interface PlaybookHeadSnippetOptions {
439
+ /** The store's CSP nonce, put on all three nodes. */
440
+ nonce?: string;
441
+ /** Override the bundle URL (absolute https). Default: the CDN. */
442
+ sdkUrl?: string;
443
+ /** Adds `data-pb-consent="required"` (see the module comment). */
444
+ consentRequired?: boolean;
445
+ /** Shorter hide than 1.5s. Clamped to 100…`CLOAK_MAX_MS`. */
446
+ maxHideMs?: number;
447
+ }
448
+ interface HeadSnippetParts {
449
+ css: string;
450
+ script: string;
451
+ sdk: {
452
+ src: string;
453
+ attrs: Record<string, string>;
454
+ };
455
+ nonce?: string;
456
+ }
457
+ /**
458
+ * Pure: the snippet's parts, or null when nothing should render (no targeted
459
+ * page, or a config missing its shop / api base).
460
+ */
461
+ declare function buildHeadSnippet(cloak: PlaybookCloakConfig | null | undefined, options?: PlaybookHeadSnippetOptions): HeadSnippetParts | null;
462
+ /**
463
+ * The head nodes as React elements. Renders ONCE: later prop changes (a
464
+ * client-side navigation revalidating the root loader) are ignored, so the
465
+ * hydrated nodes stay exactly as the server sent them.
466
+ */
467
+ declare const PlaybookCloakHead: react.NamedExoticComponent<PlaybookHeadSnippetOptions & {
468
+ cloak: PlaybookCloakConfig | null | undefined;
469
+ }>;
470
+ /**
471
+ * The cloak + early inject for `<head>`. Place it EARLY in <head> (before the
472
+ * stylesheets and before any `playbook.js` tag):
196
473
  *
197
- * Contract:
198
- * - Read Shopify's Customer Privacy API (`analytics` purpose only, matching
199
- * the checkout Web Pixel). Never integrate with a CMP directly — any CMP that
200
- * feeds the API (e.g. TrueVault Polaris) works with no code here.
201
- * - RENDERING is functional and never gated. The persistent visitor cookie,
202
- * exposures, events and the cart attribute are ANALYTICS and are gated.
203
- * - FAIL OPEN only when the API is genuinely absent; CLOSED when it exists and
204
- * denies, or while a known-present API is still resolving.
474
+ * {playbookHeadSnippet(data.cloak, {nonce})}
205
475
  *
206
- * Client: `window`/`document` touched at CALL time only (safe to import on the
207
- * server). Server: `analyticsConsentFromCookie` reads Shopify's own
208
- * `_tracking_consent` cookie, the same signal the checkout pixel trusts.
476
+ * Returns null when the page isn't targeted.
209
477
  */
210
- type ConsentState = 'granted' | 'denied' | 'pending' | 'absent';
478
+ declare function playbookHeadSnippet(cloak: PlaybookCloakConfig | null | undefined, options?: PlaybookHeadSnippetOptions): react_jsx_runtime.JSX.Element | null;
479
+ /** The same nodes as an HTML string, for a non-React head. '' when untargeted. */
480
+ declare function playbookHeadSnippetHtml(cloak: PlaybookCloakConfig | null | undefined, options?: PlaybookHeadSnippetOptions): string;
481
+
482
+ /** The env keys the kit reads (all optional). */
483
+ interface PlaybookEnv {
484
+ PUBLIC_PLAYBOOK_SHOP_ID?: string;
485
+ PLAYBOOK_PLATFORM_URL?: string;
486
+ PLAYBOOK_TESTS_DISABLED?: string;
487
+ /** 0.6.0: storefront domain for the targeting manifest (see `shopDomain`). */
488
+ PUBLIC_PLAYBOOK_SHOP_DOMAIN?: string;
489
+ }
490
+ interface CreatePlaybookContextOptions {
491
+ request: Request;
492
+ /** The worker env; any object carrying the keys above. */
493
+ env?: PlaybookEnv | Record<string, unknown> | null;
494
+ waitUntil?: (p: Promise<unknown>) => void;
495
+ /** Overrides `env.PUBLIC_PLAYBOOK_SHOP_ID`. */
496
+ shopId?: string | null;
497
+ /** Overrides `env.PLAYBOOK_PLATFORM_URL`. */
498
+ platformUrl?: string | null;
499
+ /** Overrides `env.PLAYBOOK_TESTS_DISABLED`. */
500
+ disabled?: boolean;
501
+ /** See `createPlaybook({consentRequired})` (Shopify consent path only). */
502
+ consentRequired?: boolean;
503
+ /**
504
+ * Server consent source: a `PlaybookServerConsent` (e.g. a store's CMS
505
+ * session record) or a full adapter (e.g. `truevaultConsent`, then pass the
506
+ * same one to the client). Default: Shopify's `_tracking_consent` cookie.
507
+ */
508
+ consent?: PlaybookServerConsent;
509
+ /**
510
+ * 0.6.0: `reconcileCartAttributes` also puts back the EXPERIENCE-test cart
511
+ * attributes (`pb_exp__`, `pb_vid__`) when another script wiped them, for a
512
+ * visitor the browser SDK has shown an experience test. Fill-only; see
513
+ * `./experience-attribution`. Default `true`; `false` restores 0.5.0.
514
+ */
515
+ experienceAttribution?: boolean;
516
+ /**
517
+ * 0.6.0: read the platform's targeting manifest in `loaderData()` so the
518
+ * head can cloak + early-inject on a page an all-traffic experience test
519
+ * targets (`loaderData().cloak`, `playbookHeadSnippet`). Default `true`.
520
+ */
521
+ cloak?: boolean;
522
+ /**
523
+ * 0.6.0: the storefront DOMAIN the targeting manifest is keyed by (its
524
+ * `?shop=`; the Playbook UUID doesn't work there). Overrides
525
+ * `env.PUBLIC_PLAYBOOK_SHOP_DOMAIN`; default the request's hostname, the
526
+ * same fallback `playbook.js` uses on a headless store.
527
+ */
528
+ shopDomain?: string | null;
529
+ /**
530
+ * 0.6.0: the experience SDK's `data-pb-api-base`. Default
531
+ * `<request origin>/apps/playbook` (the store's app-proxy route), which is
532
+ * what `playbook.js` passes when it's loaded from `/apps/playbook/sdk`.
533
+ */
534
+ apiBase?: string | null;
535
+ fetchImpl?: typeof fetch;
536
+ }
537
+ interface PlaybookLoaderData {
538
+ /** Store-test state for `<PlaybookRoot state>` / `<PlaybookHead state>`. */
539
+ playbook: PlaybookState | null;
540
+ /** For `<PlaybookHead hasPlaybookParams>` (anti-flicker). */
541
+ hasPlaybookParams: boolean;
542
+ /**
543
+ * 0.6.0: this path's manifest page key (`product:<handle>`, `home:`, …)
544
+ * when an all-traffic experience test targets it, else null. Null on any
545
+ * manifest failure or timeout, on `pbk`/`_pv`/preview visits, and never
546
+ * set by utm params alone.
547
+ */
548
+ targetedPage: string | null;
549
+ /** 0.6.0: pass to `playbookHeadSnippet(cloak, {nonce})`. Null = no cloak. */
550
+ cloak: PlaybookCloakConfig | null;
551
+ }
552
+ interface PlaybookRequestContext {
553
+ readonly shopId: string | null;
554
+ readonly platformUrl: string;
555
+ /** True when the kill switch is on (or there is no shop id). */
556
+ readonly disabled: boolean;
557
+ get(): Promise<PlaybookServerResult | null>;
558
+ loaderData(): Promise<PlaybookLoaderData>;
559
+ cartAttribute(): CartAttribute | null;
560
+ /**
561
+ * The visitor id this request may stamp on the cart as `_pb_vid`: analytics
562
+ * consent granted (or no consent system and `consentRequired` off), read
563
+ * from `_pb_visitor_id` then `_pb_session_vid`. Never minted; null when
564
+ * disabled, without consent, or without an id. No ruleset fetch.
565
+ */
566
+ cartVisitorId(): string | null;
567
+ /**
568
+ * The cart's full attribute list with `_pb_vid` added, corrected or removed
569
+ * (consent withdrawn / no id), every other attribute kept; `null` when the
570
+ * cart is already right, or when Playbook is disabled (the cart is left
571
+ * untouched). Call after EVERY cart action with the cart as it now stands.
572
+ *
573
+ * 0.6.0: also fills a missing `pb_exp__` / `pb_vid__` (experience tests) for
574
+ * a visitor with an experience exposure, and removes them on an explicit
575
+ * denial. Still one list, so still at most one write.
576
+ */
577
+ reconcileCartAttributes(current: ReadonlyArray<{
578
+ key: string;
579
+ value?: string | null;
580
+ }> | null | undefined): {
581
+ key: string;
582
+ value: string;
583
+ }[] | null;
584
+ /** APPEND this request's Playbook cookies to `headers`. Never throws. */
585
+ appendCookies(headers: Headers): Promise<void>;
586
+ /**
587
+ * Returns the response with this request's Playbook cookies appended
588
+ * (re-wrapping it when its headers are immutable, e.g. `Response.redirect`).
589
+ * A redirect never waits on a still-pending resolution: its cookies are
590
+ * skipped and the next request sets them.
591
+ */
592
+ finalize(response: Response): Promise<Response>;
593
+ }
594
+ declare function createPlaybookContext({ request, env, waitUntil, shopId: shopIdOption, platformUrl: platformUrlOption, disabled: disabledOption, consentRequired, consent, experienceAttribution, cloak: cloakOption, shopDomain: shopDomainOption, apiBase: apiBaseOption, fetchImpl, }: CreatePlaybookContextOptions): PlaybookRequestContext;
211
595
  /**
212
- * Force the "a CMP is present" branch: a headless store whose CMP injects
213
- * `Shopify.customerPrivacy` after we boot (e.g. TrueVault Polaris). Without it a
214
- * first-time visitor with no `_tracking_consent` cookie would fail open.
596
+ * Wrapper form: creates the context, runs the store's handler with it, then
597
+ * finalizes whatever response the handler returns (incl. a redirect built
598
+ * from a 404). The handler must still put `playbook` on its load context.
215
599
  */
216
- declare function declareConsentRequired(): void;
217
- /** Wait for the API: already loaded → `loadFeatures()` → bounded poll → give up. */
218
- declare function waitForConsentAPI(): Promise<void>;
219
- /** Granted right now? Closed while resolving a known-present API; open if absent. */
220
- declare function isAnalyticsConsentGranted(): boolean;
221
- declare function getConsentState(): ConsentState;
222
- /** Subscribe to `visitorConsentCollected` (decision read from event.detail). */
223
- declare function onConsentChange(cb: (granted: boolean) => void): () => void;
600
+ declare function withPlaybook(options: CreatePlaybookContextOptions, handler: (playbook: PlaybookRequestContext) => Promise<Response>): Promise<Response>;
601
+
602
+ declare const DEFAULT_SDK_URL = "https://cdn.heyplaybook.com/playbook.js";
603
+ /** First-party proxy prefix (the `/apps/playbook/*` route). */
604
+ declare const DEFAULT_PROXY_ENDPOINT = "/apps/playbook";
605
+ /** The reveal script, byte-compatible with the hand-wired integrations. */
606
+ declare function revealScript(hasPlaybookParams: boolean): string;
607
+ interface PlaybookHeadProps {
608
+ /** Playbook shop UUID (`PUBLIC_PLAYBOOK_SHOP_ID`). Falsy → renders nothing. */
609
+ shopId: string | null | undefined;
610
+ /**
611
+ * Where `playbook.js` sends API calls. Default `/apps/playbook` (first-party
612
+ * proxy); pass `https://www.heyplaybook.com` to go direct.
613
+ */
614
+ apiEndpoint?: string;
615
+ sdkUrl?: string;
616
+ /** From `context.playbook.loaderData()` (or `hasPlaybookParams(request.url)`). */
617
+ hasPlaybookParams?: boolean;
618
+ /** Store-test state from the root loader; its visitor id is seeded. */
619
+ state?: PlaybookState | null;
620
+ /** Explicit visitor id (overrides `state`). Non-UUID values are ignored. */
621
+ visitorId?: string | null;
622
+ /** CSP nonce for the inline scripts/style, when the store sets a CSP. */
623
+ nonce?: string;
624
+ }
625
+ declare function PlaybookHead({ shopId, apiEndpoint, sdkUrl, hasPlaybookParams, state, visitorId, nonce, }: PlaybookHeadProps): react_jsx_runtime.JSX.Element | null;
626
+
627
+ declare function manifestUrl(platformUrl: string, shopDomain: string): string;
224
628
  /**
225
- * SERVER: analytics consent from Shopify's `_tracking_consent` cookie.
226
- * Returns `granted` / `denied`, `pending` when the cookie exists but analytics
227
- * is undecided, and `absent` when there is no cookie at all. Tolerates both
228
- * known payload shapes (`con.CMP.a` = "1"/"0"/"" and `purposes.a` boolean);
229
- * anything unparseable is `pending` (closed), never granted.
629
+ * The manifest's `pages` as clean strings, or null when the envelope is not
630
+ * a manifest. A manifest without `pages` (an older platform) is `[]` — valid,
631
+ * nothing targeted. Non-string entries are dropped.
230
632
  */
231
- declare function analyticsConsentFromCookie(raw: string | undefined): ConsentState;
633
+ declare function sanitizeManifestPages(value: unknown): string[] | null;
634
+ /**
635
+ * The shop's all-traffic page keys, or `null` when the read is not healthy
636
+ * (failure, timeout, backoff, last-good during an outage) — the caller must
637
+ * then NOT hide. Never throws.
638
+ */
639
+ declare function getTargetedPages({ platformUrl, shopDomain, waitUntil, fetchImpl, }: {
640
+ platformUrl: string;
641
+ shopDomain: string;
642
+ waitUntil?: (p: Promise<unknown>) => void;
643
+ fetchImpl?: typeof fetch;
644
+ }): Promise<{
645
+ pages: string[] | null;
646
+ source: RulesetSource;
647
+ }>;
648
+ /**
649
+ * The manifest page key for a storefront path — a byte-for-byte port of
650
+ * `targetPageKey` in shared/src/targeting/index.ts (the same function the
651
+ * `playbook.js` loader and the experience SDK use):
652
+ * `product:<handle>` (also under `/collections/<c>/products/<p>`),
653
+ * `collection:<handle>`, `home:`, `page:<handle>` for `/pages/<handle>`,
654
+ * `page:cart`, `page:<path>` for any other storefront path; null for an
655
+ * untargetable path. A leading locale segment (`/en-us`, `/fr`) and a
656
+ * trailing slash are stripped; handles are URI-decoded and lowercased.
657
+ */
658
+ declare function targetPageKey(pathname: string): string | null;
659
+ /**
660
+ * This path's page key when the manifest serves it to all traffic, else null.
661
+ * Same matching as `manifestMatchesPage` (shared): exact key, or a key ending
662
+ * in `*` by prefix (`"*"`, `"product:*"`, `"product:the-weekender-in-*"`).
663
+ */
664
+ declare function matchTargetedPage(pages: readonly string[] | null | undefined, pathname: string): string | null;
665
+
666
+ /**
667
+ * Store-specific "why not in test" text for the QA panel. Return a string to
668
+ * show it (it wins over the generic reason), or null to fall back to the
669
+ * generic reason. Runs in the browser; must not throw (errors are ignored).
670
+ */
671
+ type PlaybookDebugExplain = (testKey: string, assignment: PlaybookAssignment, pathname: string) => string | null | undefined;
672
+ /** `<PlaybookRoot debug>` options. */
673
+ interface PlaybookDebugOptions {
674
+ /** Force allow/deny; default: preview hosts or a verified preview token. */
675
+ allowed?: boolean;
676
+ /** Test keys this storefront has code for (others are labelled as such). */
677
+ implementedTests?: string[];
678
+ /** Store-specific eligibility text (e.g. "not a towel product"). */
679
+ explain?: PlaybookDebugExplain;
680
+ }
681
+ /** May the panel open on this page? */
682
+ declare function debugPanelAllowed(state: PlaybookState | null | undefined, hostname: string, allowed?: boolean): boolean;
683
+ declare function PlaybookDebugPanel({ state, location, allowed, implementedTests, explain, }: {
684
+ state: PlaybookState | null | undefined;
685
+ location: {
686
+ pathname: string;
687
+ search?: string;
688
+ };
689
+ } & PlaybookDebugOptions): react_jsx_runtime.JSX.Element | null;
232
690
 
233
691
  /**
234
692
  * The standard events — ONE taxonomy for every store (GROWTH-TESTS.md "The
@@ -244,6 +702,17 @@ interface PlaybookStoreContext {
244
702
  locale?: string | null;
245
703
  isLoggedIn?: boolean | null;
246
704
  }
705
+ /**
706
+ * GA4 / GTM forwarding of exposures. OFF by default since 0.5.0 (a store that
707
+ * also runs another testing tool's `view_experiment` — e.g. Pack tests — would
708
+ * get two tools' experiments mixed in GA4). `true` or `{}` turns it on;
709
+ * `{eventName}` turns it on under another event name (default
710
+ * `view_experiment`); `false` keeps it off.
711
+ */
712
+ type PlaybookDataLayerOption = boolean | {
713
+ eventName?: string;
714
+ };
715
+ declare const DEFAULT_DATALAYER_EVENT = "view_experiment";
247
716
  interface TrackedEntry {
248
717
  at: string;
249
718
  kind: 'exposure' | 'event';
@@ -289,6 +758,141 @@ interface TrackOptions {
289
758
  */
290
759
  declare function playbookTrack(event: StandardEvent, rawProps?: Record<string, unknown>, scope?: TrackScope, { oncePerSession, beacon }?: TrackOptions): number;
291
760
 
761
+ /** The sitewide A/A test key the sentinel exposes for. */
762
+ declare const AA_SITEWIDE_TEST = "aa-sitewide";
763
+ /** What the kit needs from the store's cart. READ-only: no setters. */
764
+ interface PlaybookCartAdapter {
765
+ cartId: string | null | undefined;
766
+ attributes: ReadonlyArray<CartAttribute> | null | undefined;
767
+ /** The store's cart status (writes wait for `idle`). Never written. */
768
+ status?: string | null;
769
+ /** Cart action route for the default writer/reader. Default `/api/cart`. */
770
+ endpoint?: string;
771
+ /** The endpoint merges attributes server-side (Pack `/api/cart`). */
772
+ serverMerges?: boolean;
773
+ /** Replace the default writer (must not touch the store's cart state). */
774
+ write?: CartAttributeWriter;
775
+ /** Replace the default re-read (used to confirm `_ig*` keys survived). */
776
+ read?: CartAttributeReader;
777
+ }
778
+ interface PlaybookRootProps {
779
+ state: PlaybookState | null | undefined;
780
+ location: {
781
+ pathname: string;
782
+ search?: string;
783
+ hash?: string;
784
+ };
785
+ /** Router navigate; used only to restore `?pb_preview=` inside Playbook's frame. */
786
+ navigate?: (to: string, options: {
787
+ replace: true;
788
+ preventScrollReset: true;
789
+ }) => void;
790
+ /**
791
+ * Client `_pb_vid` sync. `null` turns it off — do that when the server owns
792
+ * `_pb_vid` (`context.playbook.reconcileCartAttributes` in the cart action).
793
+ */
794
+ cart?: PlaybookCartAdapter | null;
795
+ /**
796
+ * Browser consent: a `PlaybookClientConsent` or a full adapter. Default:
797
+ * Shopify's Customer Privacy API (`shopifyCustomerPrivacyConsent`).
798
+ */
799
+ consent?: PlaybookClientConsent;
800
+ storeContext?: PlaybookStoreContext;
801
+ /**
802
+ * The store's own CMS/editor preview (e.g. Pack customizer): no cart write,
803
+ * no A/A exposure.
804
+ */
805
+ editorPreview?: boolean;
806
+ /** Render the `aa-sitewide` sentinel (default true; inert without that test). */
807
+ aaSentinel?: boolean;
808
+ /**
809
+ * QA panel: force allow/deny, the test keys this store has code for, and
810
+ * `explain` for store-specific "why not in test" text.
811
+ */
812
+ debug?: PlaybookDebugOptions;
813
+ /**
814
+ * GA4 `view_experiment` dataLayer push per exposure. OFF by default since
815
+ * 0.5.0; `true` / `{eventName}` turns it on.
816
+ */
817
+ dataLayer?: PlaybookDataLayerOption;
818
+ /** A verified preview shows its arm even off-target (default false). */
819
+ previewIgnoresTargeting?: boolean;
820
+ /** Observe cart-sync decisions (debug/logging). */
821
+ onCartSyncEvent?: (event: CartSyncEvent) => void;
822
+ exposureUrl?: string;
823
+ eventUrl?: string;
824
+ supportedEvents?: string[];
825
+ children: ReactNode;
826
+ }
827
+ /** Any running (non-forced) test the visitor is bucketed into. */
828
+ declare function visitorInRunningTest(state: PlaybookState | null | undefined): boolean;
829
+ /**
830
+ * A/A sentinel: invisible and IDENTICAL in both arms, so `aa-sitewide` can only
831
+ * measure the pipeline itself. Always in the viewport, out of layout flow.
832
+ * With no such rule (or not running) nothing is sent.
833
+ */
834
+ declare function PlaybookAAExposure({ testKey }: {
835
+ testKey?: string;
836
+ }): react_jsx_runtime.JSX.Element;
837
+ declare function PlaybookRoot({ state, location, navigate, cart, consent, storeContext, editorPreview, aaSentinel, debug, dataLayer, previewIgnoresTargeting, onCartSyncEvent, exposureUrl, eventUrl, supportedEvents, children, }: PlaybookRootProps): react_jsx_runtime.JSX.Element;
838
+
839
+ interface Props {
840
+ /** For the console warning only. */
841
+ name: string;
842
+ children?: ReactNode;
843
+ }
844
+ declare class PlaybookBoundary extends Component<Props, {
845
+ failed: boolean;
846
+ }> {
847
+ state: {
848
+ failed: boolean;
849
+ };
850
+ static getDerivedStateFromError(): {
851
+ failed: boolean;
852
+ };
853
+ componentDidCatch(error: unknown): void;
854
+ render(): string | number | bigint | boolean | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null;
855
+ }
856
+
857
+ type PlatformUrlOption = string | null | undefined | ((args: ProxyArgs) => string | null | undefined);
858
+ interface ProxyArgs {
859
+ request: Request;
860
+ /** The route's load context; `context.env.PLAYBOOK_PLATFORM_URL` is read by default. */
861
+ context?: unknown;
862
+ }
863
+ interface PlaybookProxyOptions {
864
+ /** Default: `context.env.PLAYBOOK_PLATFORM_URL`, else heyplaybook.com. */
865
+ platformUrl?: PlatformUrlOption;
866
+ timeoutMs?: number;
867
+ maxBodyBytes?: number;
868
+ fetchImpl?: typeof fetch;
869
+ }
870
+ /** `/apps/playbook/api/x?y` → `{platform}/api/x?y`; other paths → `/api/<path>`. */
871
+ declare function playbookBackendUrl(requestUrl: string, platformUrl: string): string;
872
+ declare function createPlaybookProxyHandler({ platformUrl, timeoutMs, maxBodyBytes, fetchImpl, }?: PlaybookProxyOptions): {
873
+ loader: (args: ProxyArgs) => Promise<Response>;
874
+ action: (args: ProxyArgs) => Promise<Response>;
875
+ };
876
+
877
+ /** Small isomorphic predicates shared by the server helper and the client. */
878
+ /**
879
+ * The legacy `playbook.js` loader is about to swap content in (landing
880
+ * experiences, editor/brand previews): hide the page until it reveals it.
881
+ * Same four markers the hand-wired integrations checked.
882
+ */
883
+ declare function hasPlaybookParams(url: string | URL): boolean;
884
+ /**
885
+ * Kill switch: `PLAYBOOK_TESTS_DISABLED=1` (or `true`) turns off ONLY the
886
+ * store-test kit — assignment, visitor cookies, the cart attribute, exposures
887
+ * and events. The legacy `playbook.js` loader keeps running.
888
+ */
889
+ declare function isKillSwitchOn(value: string | null | undefined): boolean;
890
+ /**
891
+ * Non-production hosts where the QA panel may open from `?pb_debug=1`:
892
+ * Oxygen previews (`*.myshopify.dev`), Shopify previews, workers.dev and local.
893
+ */
894
+ declare function isPreviewHost(hostname: string): boolean;
895
+
292
896
  declare const DEFAULT_EXPOSURE_URL = "/apps/playbook/api/storefront/tests/exposure";
293
897
  declare const DEFAULT_EVENT_URL = "/apps/playbook/api/storefront/tests/event";
294
898
  /** Live analytics consent: granted / denied / pending / absent (API absent). */
@@ -310,9 +914,10 @@ interface PlaybookVariant {
310
914
  * state, so SSR and hydration render the same arm (no flicker).
311
915
  *
312
916
  * `eligible: false` (e.g. "not a towel product") → control, not in test.
313
- * A forced arm (QA `pb_force` or a `pb_preview` link) skips status and traffic
314
- * split but still respects targeting: a towel arm forced on a towel page must
315
- * not follow the session onto a bedding page.
917
+ * A forced arm (a verified `pb_preview` link) skips status and traffic split
918
+ * but still respects targeting: a towel arm forced on a towel page must not
919
+ * follow the session onto a bedding page. A store that wants previews to show
920
+ * the arm everywhere passes `<PlaybookRoot previewIgnoresTargeting>`.
316
921
  */
317
922
  declare function usePlaybookVariant(testKey: string, { eligible }?: {
318
923
  eligible?: boolean;
@@ -347,7 +952,7 @@ declare function usePreviewParamRedirect(location: {
347
952
  hash: string;
348
953
  }): string | null;
349
954
 
350
- declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supportedEvents, storeContext, children, }: {
955
+ declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supportedEvents, storeContext, consent: consentAdapter, dataLayer, previewIgnoresTargeting, children, }: {
351
956
  state: PlaybookState | null | undefined;
352
957
  /** Current route pathname (re-render on navigation so path targeting updates). */
353
958
  pathname: string;
@@ -357,6 +962,25 @@ declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supp
357
962
  supportedEvents?: string[];
358
963
  /** Market / locale / login state, for the exposure context. */
359
964
  storeContext?: PlaybookStoreContext;
965
+ /**
966
+ * Browser consent source (a `PlaybookClientConsent`, or a full adapter).
967
+ * Default: Shopify's Customer Privacy API (`shopifyCustomerPrivacyConsent`).
968
+ * Keep it closed on the same "unknown" states as the server source.
969
+ */
970
+ consent?: PlaybookClientConsent;
971
+ /**
972
+ * Forward each exposure to `window.dataLayer` as GA4 `view_experiment`.
973
+ * OFF by default since 0.5.0; `true` / `{}` turns it on, `{eventName}`
974
+ * renames it.
975
+ */
976
+ dataLayer?: PlaybookDataLayerOption;
977
+ /**
978
+ * A verified preview (`pb_preview`) shows the forced arm even where the
979
+ * test doesn't apply (`eligible: false` or an off-target path). Default
980
+ * false: the forced arm respects targeting, so an arm previewed on a towel
981
+ * page doesn't follow the reviewer onto a bedding page.
982
+ */
983
+ previewIgnoresTargeting?: boolean;
360
984
  children: ReactNode;
361
985
  }): react_jsx_runtime.JSX.Element;
362
986
  /** Component form of `usePlaybookExposure` for wrapping an existing element. */
@@ -373,7 +997,8 @@ declare function PlaybookExposure({ testKey, variant, enabled, children, }: {
373
997
  * does for the SDK (so both write the same keys the same way):
374
998
  *
375
999
  * granted / no CMP → `_pb_visitor_id` cookie, 365d (promotes a session id)
376
- * denied / pending → sessionStorage only; any cookie is EXPIRED
1000
+ * pending → sessionStorage only; an existing cookie is left alone
1001
+ * denied → sessionStorage only; any cookie is EXPIRED
377
1002
  *
378
1003
  * sessionStorage `_pb_visitor_id` is always seeded with the server's id so the
379
1004
  * SDK's helper (which reads sessionStorage under denial) uses the same value.
@@ -383,10 +1008,14 @@ declare function syncVisitorId(visitorId: string, consent: ConsentState): void;
383
1008
  /**
384
1009
  * Inline script for the document <head>, BEFORE the SDK script: seeds
385
1010
  * sessionStorage so `playbook.js` resolves the same visitor id even when it
386
- * runs before hydration. `visitorId` is a validated UUID (no escaping needed
387
- * beyond JSON).
1011
+ * runs before hydration.
1012
+ *
1013
+ * The id comes from a request cookie the browser controls and is interpolated
1014
+ * into an inline <script>, so ONLY the UUID shape Playbook mints is accepted;
1015
+ * anything else returns '' (render no script) and a tampered cookie can never
1016
+ * break out of the tag.
388
1017
  */
389
- declare function visitorSeedScript(visitorId: string): string;
1018
+ declare function visitorSeedScript(visitorId: string | null | undefined): string;
390
1019
 
391
1020
  declare function usePageEngagement(pathname: string, enabled: boolean): void;
392
1021
 
@@ -408,7 +1037,7 @@ declare const SESSION_VISITOR_COOKIE = "_pb_session_vid";
408
1037
  /** Retired pilot cookie; migrated on first read, then expired. */
409
1038
  declare const LEGACY_VISITOR_COOKIE = "pb_vid";
410
1039
 
411
- type AddToCartSource = 'pdp' | 'quick_add' | 'cart_upsell' | 'other';
1040
+ type AddToCartSource = 'pdp' | 'quick_add' | 'cart_upsell' | 'cross_sell' | 'other';
412
1041
  declare function setNextAddSource(source: AddToCartSource): void;
413
1042
  declare function takeAddSource(): AddToCartSource;
414
1043
  interface AddedLineInput {
@@ -426,6 +1055,31 @@ interface CartLineSnapshot {
426
1055
  };
427
1056
  };
428
1057
  }
1058
+ type CartLinesLike = CartLineSnapshot[] | {
1059
+ nodes?: CartLineSnapshot[];
1060
+ edges?: {
1061
+ node: CartLineSnapshot;
1062
+ }[];
1063
+ } | null | undefined;
1064
+ /**
1065
+ * The lines an add request carried. Accepts the lines array itself, or the
1066
+ * cart request's FormData in either Hydrogen shape: `action` + `lines` /
1067
+ * `cart` fields (Pack's `/api/cart`), or CartForm's `cartFormInput`.
1068
+ */
1069
+ declare function addedLinesFrom(input: AddedLineInput[] | FormData | null | undefined): AddedLineInput[];
1070
+ /**
1071
+ * The store's ONE add-to-cart touchpoint. Call it after a SUCCESSFUL add
1072
+ * (no user errors), with the lines that were added (array or the request's
1073
+ * FormData) and the cart the mutation returned. `source` omitted → the one set
1074
+ * by `setNextAddSource` (taken now), else `other`. No-op without consent or
1075
+ * outside a running test. Never throws.
1076
+ */
1077
+ declare function trackAddToCart(source: AddToCartSource | null | undefined, { lines, cart, }: {
1078
+ lines: AddedLineInput[] | FormData | null | undefined;
1079
+ cart: {
1080
+ lines?: CartLinesLike;
1081
+ } | null | undefined | unknown;
1082
+ }): void;
429
1083
  /** One `add_to_cart` per added line. Never throws. */
430
1084
  declare function trackAddToCartLines(lines: AddedLineInput[], cartLines: CartLineSnapshot[], source: AddToCartSource): void;
431
1085
 
@@ -440,6 +1094,74 @@ declare function cartHasPlaybookAttribute(attributes: ReadonlyArray<{
440
1094
  key: string;
441
1095
  value?: string | null;
442
1096
  }> | null | undefined, visitorId: string): boolean;
1097
+ /**
1098
+ * The cart's FULL attribute list with `_pb_vid` reconciled to `visitorId`:
1099
+ * added when missing, corrected when stale (or duplicated), removed when
1100
+ * `visitorId` is null (no id, or consent withdrawn). Every other attribute is
1101
+ * kept as-is, in order. Returns `null` when the cart is already right, so the
1102
+ * caller skips the mutation.
1103
+ *
1104
+ * Pure: it never mints an id. Pass the result to a REPLACE-style write
1105
+ * (Hydrogen's `cart.updateAttributes`), which is why the whole list comes
1106
+ * back rather than just `_pb_vid`. A null/empty value on another key is
1107
+ * written back as `''`.
1108
+ */
1109
+ declare function reconcilePlaybookCartAttribute(current: ReadonlyArray<{
1110
+ key: string;
1111
+ value?: string | null;
1112
+ }> | null | undefined, visitorId: string | null | undefined): {
1113
+ key: string;
1114
+ value: string;
1115
+ }[] | null;
1116
+
1117
+ /** The SDK's exposure-list cookie (30 days). */
1118
+ declare const EXPOSURE_COOKIE = "_pb_exp";
1119
+ /** Cart attribute the `orders/paid` webhook decodes as the exposure list. */
1120
+ declare const EXPOSURE_CART_ATTRIBUTE = "pb_exp__";
1121
+ /** Cart attribute carrying the long-lived visitor id the impressions use. */
1122
+ declare const EXPERIENCE_VISITOR_CART_ATTRIBUTE = "pb_vid__";
1123
+ /**
1124
+ * The exposure list from a raw cookie value, re-encoded in the platform's wire
1125
+ * format (malformed and expired entries dropped), or `null` when nothing valid
1126
+ * is left. Pure; `now` is epoch SECONDS.
1127
+ */
1128
+ declare function normalizeExposureList(raw: string | null | undefined, now?: number): string | null;
1129
+ /**
1130
+ * The long-lived visitor id the browser SDK records impressions under, read
1131
+ * from the request's cookies in the SDK's own order (`readBucketingId`):
1132
+ * Shopify's `_y` (the SDK reads it from Server-Timing; the server sees the
1133
+ * cookie itself), then a Shopify client-id cookie (`shopify_client_id`, then
1134
+ * the legacy `_shopify_y`), then Playbook's `_pb_visitor_id`. `null` when none
1135
+ * is present. Call it only with analytics consent.
1136
+ *
1137
+ * Never the session-only `_pb_session_vid`: the SDK can't read it (HttpOnly),
1138
+ * so no impression is ever recorded under it.
1139
+ */
1140
+ declare function experienceVisitorIdFromCookies(cookies: Record<string, string | undefined>): string | null;
1141
+ type ExperienceAttributionConsent = 'allowed' | 'denied' | 'unknown';
1142
+ interface ExperienceAttributionInput {
1143
+ consent: ExperienceAttributionConsent;
1144
+ /** The request's `_pb_exp` cookie, raw. */
1145
+ exposureCookie: string | null | undefined;
1146
+ /** From `experienceVisitorIdFromCookies`. */
1147
+ visitorId: string | null | undefined;
1148
+ /** Epoch seconds (tests). */
1149
+ now?: number;
1150
+ }
1151
+ type Attr = {
1152
+ key: string;
1153
+ value?: string | null;
1154
+ };
1155
+ /**
1156
+ * The cart's FULL attribute list with `pb_exp__` / `pb_vid__` filled in or
1157
+ * removed per the policy above; `null` when the cart should be left as it is.
1158
+ * Every other attribute is kept, in order (a null value becomes `''`, as in
1159
+ * `reconcilePlaybookCartAttribute`). Pure.
1160
+ */
1161
+ declare function reconcileExperienceCartAttributes(current: readonly Attr[] | null | undefined, { consent, exposureCookie, visitorId, now }: ExperienceAttributionInput): {
1162
+ key: string;
1163
+ value: string;
1164
+ }[] | null;
443
1165
 
444
1166
  declare const CONTROL_ARM = "control";
445
1167
  interface AssignInput {
@@ -481,4 +1203,4 @@ declare function inNamespace(hashValue: string, namespace: [string, number, numb
481
1203
  declare function chooseVariation(n: number, ranges: VariationRange[]): number;
482
1204
  declare function getBucketRanges(numVariations: number, coverage: number | undefined, weights?: number[]): VariationRange[];
483
1205
 
484
- export { type AddToCartSource, type AddedLineInput, CART_VISITOR_ATTRIBUTE, CONTROL_ARM, type CartLineSnapshot, type ConsentState, type CreatePlaybookOptions, DEFAULT_EVENT_URL, DEFAULT_EXPOSURE_URL, DEFAULT_PLATFORM_URL, DEFAULT_SUPPORTED_EVENTS, LEGACY_VISITOR_COOKIE, type PlaybookArm, type PlaybookAssignReason, type PlaybookAssignment, type PlaybookDevice, PlaybookExposure, type PlaybookOverride, type PlaybookPreview, PlaybookProvider, type PlaybookRuleset, type PlaybookServerResult, type PlaybookState, type PlaybookStoreContext, type PlaybookTestRule, type PlaybookTestStatus, type PlaybookVariant, type PlaybookVisitorType, type RulesetSource, SESSION_VISITOR_COOKIE, STANDARD_EVENTS, type StandardEvent, type TrackScope, type TrackedEntry, VISITOR_COOKIE, analyticsConsentFromCookie, assignTest, cartHasPlaybookAttribute, chooseVariation, createPlaybook, declareConsentRequired, detectDevice, detectGeo, getBucketRanges, getConsentState, getEqualWeights, getServerTrackedLog, getSessionContext, getTrackedLog, hasSentExposure, hash, inNamespace, isAnalyticsConsentGranted, matchesPathPrefix, onConsentChange, playbookCartAttribute, playbookTrack, prefetchRuleset, setNextAddSource, subscribeTrackedLog, syncVisitorId, takeAddSource, trackAddToCartLines, useAnalyticsAllowed, usePageEngagement, usePlaybookConsent, usePlaybookExposure, usePlaybookInteraction, usePlaybookState, usePlaybookVariant, usePreviewParamRedirect, visitorSeedScript, waitForConsentAPI };
1206
+ export { AA_SITEWIDE_TEST, type AddToCartSource, type AddedLineInput, CART_SYNC_IDLE_MS, CART_VISITOR_ATTRIBUTE, CLOAK_MAX_MS, CLOAK_STYLE_ID, CONSENT_LOADED_EVENTS, CONTROL_ARM, type CartAttribute, type CartAttributeReader, type CartAttributeWriter, type CartLineSnapshot, type CartSyncEvent, type CartSyncSnapshot, type CartWriteResult, type ConsentState, type CreatePlaybookContextOptions, type CreatePlaybookOptions, DEFAULT_DATALAYER_EVENT, DEFAULT_EVENT_URL, DEFAULT_EXPERIENCE_SDK_URL, DEFAULT_EXPOSURE_URL, DEFAULT_PLATFORM_URL, DEFAULT_PROXY_ENDPOINT, DEFAULT_SDK_URL, DEFAULT_SUPPORTED_EVENTS, EXPERIENCE_SDK_SCRIPT_ID, EXPERIENCE_VISITOR_CART_ATTRIBUTE, EXPOSURE_CART_ATTRIBUTE, EXPOSURE_COOKIE, type ExperienceAttributionConsent, type ExperienceAttributionInput, type HeadSnippetParts, LEGACY_VISITOR_COOKIE, MAX_WRITES_PER_CART, PlaybookAAExposure, type PlaybookArm, type PlaybookAssignReason, type PlaybookAssignment, PlaybookBoundary, type PlaybookCartAdapter, type PlaybookClientConsent, type PlaybookCloakConfig, PlaybookCloakHead, type PlaybookConsentAdapter, type PlaybookDataLayerOption, type PlaybookDebugExplain, type PlaybookDebugOptions, PlaybookDebugPanel, type PlaybookDevice, type PlaybookEnv, PlaybookExposure, PlaybookHead, type PlaybookHeadProps, type PlaybookHeadSnippetOptions, type PlaybookLoaderData, type PlaybookPreview, PlaybookProvider, type PlaybookProxyOptions, type PlaybookRequestContext, PlaybookRoot, type PlaybookRootProps, type PlaybookRuleset, type PlaybookServerConsent, type PlaybookServerResult, type PlaybookState, type PlaybookStoreContext, type PlaybookTestRule, type PlaybookTestStatus, type PlaybookVariant, type PlaybookVisitorType, type RulesetSource, SESSION_VISITOR_COOKIE, STANDARD_EVENTS, type StandardEvent, TRUEVAULT_CONSENT_COOKIE, type TrackScope, type TrackedEntry, type TrueVaultConsentOptions, VISITOR_COOKIE, addedLinesFrom, analyticsConsentFromCookie, assignTest, buildHeadSnippet, cartHasPlaybookAttribute, chooseVariation, consentFromAnalytics, createCartAttributeReader, createCartAttributeSync, createCartAttributeWriter, createPlaybook, createPlaybookContext, createPlaybookProxyHandler, createTrueVaultConsent, debugPanelAllowed, declareConsentRequired, detectDevice, detectGeo, experienceVisitorIdFromCookies, getBucketRanges, getConsentState, getEqualWeights, getServerTrackedLog, getSessionContext, getTargetedPages, getTrackedLog, hasPlaybookParams, hasSentExposure, hash, inNamespace, isAnalyticsConsentGranted, isKillSwitchOn, isPreviewHost, manifestUrl, matchTargetedPage, matchesPathPrefix, mergeAttributes, normalizeExposureList, onConsentChange, onConsentLoaded, playbookBackendUrl, playbookCartAttribute, playbookHeadSnippet, playbookHeadSnippetHtml, playbookTrack, prefetchRuleset, reconcileExperienceCartAttributes, reconcilePlaybookCartAttribute, revealScript, sanitizeManifestPages, sanitizeRuleset, setNextAddSource, shopifyCustomerPrivacyConsent, subscribeTrackedLog, syncVisitorId, takeAddSource, targetPageKey, trackAddToCart, trackAddToCartLines, trueVaultDecision, truevaultConsent, useAnalyticsAllowed, usePageEngagement, usePlaybookConsent, usePlaybookExposure, usePlaybookInteraction, usePlaybookState, usePlaybookVariant, usePreviewParamRedirect, visitorInRunningTest, visitorSeedScript, waitForConsentAPI, withPlaybook, withPlaybookCartAttribute };