@heyplaybook/hydrogen 0.2.1 → 0.3.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,106 @@
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
+ type ConsentState = 'granted' | 'denied' | 'pending' | 'absent';
26
+ /**
27
+ * Force the "a CMP is present" branch: a headless store whose CMP injects
28
+ * `Shopify.customerPrivacy` after we boot (e.g. TrueVault Polaris). Without it a
29
+ * first-time visitor with no `_tracking_consent` cookie would fail open.
30
+ */
31
+ declare function declareConsentRequired(): void;
32
+ /** Wait for the API: already loaded → `loadFeatures()` → bounded poll → give up. */
33
+ declare function waitForConsentAPI(): Promise<void>;
34
+ /** Granted right now? Closed while resolving a known-present API; open if absent. */
35
+ declare function isAnalyticsConsentGranted(): boolean;
36
+ declare function getConsentState(): ConsentState;
37
+ /** Subscribe to `visitorConsentCollected` (decision read from event.detail). */
38
+ declare function onConsentChange(cb: (granted: boolean) => void): () => void;
39
+ /**
40
+ * SERVER: analytics consent from Shopify's `_tracking_consent` cookie.
41
+ * Returns `granted` / `denied`, `pending` when the cookie exists but analytics
42
+ * is undecided, and `absent` when there is no cookie at all. Tolerates both
43
+ * known payload shapes (`con.CMP.a` = "1"/"0"/"" and `purposes.a` boolean);
44
+ * anything unparseable is `pending` (closed), never granted.
45
+ */
46
+ declare function analyticsConsentFromCookie(raw: string | undefined): ConsentState;
47
+
48
+ /**
49
+ * Pluggable analytics-consent sources. ONE decision function per adapter is
50
+ * used on BOTH sides — the server reads it from the request (cookie + GPC
51
+ * header), the client from `document.cookie` + `navigator` — so the server's
52
+ * `serverConsent` and the client's live consent can never disagree on the same
53
+ * inputs (0.2.1 resolved a TrueVault store to `pending` on the server and to
54
+ * `absent`/open on the client).
55
+ *
56
+ * Without an adapter the package keeps 0.2.1 behaviour: Shopify's Customer
57
+ * Privacy API on the client and its `_tracking_consent` cookie on the server.
58
+ * Use an adapter when the store's CMP does NOT feed that API (TrueVault
59
+ * Polaris on Sand Cloud never sets `window.Shopify.customerPrivacy` or
60
+ * `_tracking_consent`).
61
+ *
62
+ * Pass the SAME adapter to `createPlaybookContext({consent})` and
63
+ * `<PlaybookRoot consent>`.
64
+ */
65
+
66
+ interface PlaybookConsentAdapter {
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
+ /** CLIENT: the decision right now. `window`/`document` read at call time. */
72
+ read(): ConsentState;
73
+ /** CLIENT: call `onChange` whenever the decision may have changed. */
74
+ subscribe(onChange: () => void): () => void;
75
+ }
76
+ /** TrueVault Polaris's banner cookie (the one Sand Cloud's Blotout/analytics read). */
77
+ declare const TRUEVAULT_CONSENT_COOKIE = "polaris_consent_settings";
78
+ interface TrueVaultConsentOptions {
79
+ /**
80
+ * Decision while the visitor has no `polaris_consent_settings` cookie yet.
81
+ * Default `pending` (closed): nothing analytics runs until Polaris records a
82
+ * decision. `granted` matches an opt-out regime where the absence of a
83
+ * decision means "allowed" (Sand Cloud's own `getPolarisCanTrack`).
84
+ */
85
+ whenMissing?: Extract<ConsentState, 'pending' | 'granted'>;
86
+ /**
87
+ * Global Privacy Control. Default `follow-banner`: GPC is a sale/sharing
88
+ * opt-out, Playbook doesn't sell data, so GPC alone doesn't deny analytics —
89
+ * only the banner's `analyticsPermitted` decides (Polaris itself keeps
90
+ * `analyticsPermitted` and only flips `notOptedOut` on GPC). `deny`: a store
91
+ * that wants GPC to switch analytics off too.
92
+ */
93
+ gpc?: 'follow-banner' | 'deny';
94
+ }
95
+ /**
96
+ * Pure decision shared by server and client. `raw` is the cookie value exactly
97
+ * as stored (URI-encoded JSON or plain JSON); `gpc` is the GPC signal.
98
+ */
99
+ declare function trueVaultDecision(raw: string | null | undefined, gpc: boolean, { whenMissing, gpc: gpcMode }?: TrueVaultConsentOptions): ConsentState;
100
+ /** TrueVault Polaris: `polaris_consent_settings.analyticsPermitted`, GPC-aware. */
101
+ declare function createTrueVaultConsent(options?: TrueVaultConsentOptions): PlaybookConsentAdapter;
102
+ /** TrueVault with the defaults (closed until a decision; GPC follows the banner). */
103
+ declare const truevaultConsent: PlaybookConsentAdapter;
3
104
 
4
105
  /**
5
106
  * Playbook code-test types. Mirrors the ruleset contract served by
@@ -116,6 +217,12 @@ interface CreatePlaybookOptions {
116
217
  * `data-pb-consent="required"`.
117
218
  */
118
219
  consentRequired?: boolean;
220
+ /**
221
+ * Consent source when the store's CMP doesn't feed Shopify's Customer Privacy
222
+ * API (e.g. `truevaultConsent`). Replaces the `_tracking_consent` read; pass
223
+ * the SAME adapter to the client (`PlaybookRoot consent`).
224
+ */
225
+ consent?: PlaybookConsentAdapter;
119
226
  }
120
227
  interface PlaybookOverride extends PlaybookPreview {
121
228
  /** `request`: set by this request's URL; `session`: replayed from a cookie. */
@@ -142,7 +249,7 @@ declare function detectGeo(headers: Headers): {
142
249
  region: string | null;
143
250
  };
144
251
  declare function detectDevice(userAgent: string | null): PlaybookDevice;
145
- declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetchImpl, overrides, consentRequired, }: CreatePlaybookOptions): Promise<PlaybookServerResult>;
252
+ declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetchImpl, overrides, consentRequired, consent: consentAdapter, }: CreatePlaybookOptions): Promise<PlaybookServerResult>;
146
253
 
147
254
  /**
148
255
  * Ruleset fetch with an in-memory (per-isolate) cache.
@@ -160,6 +267,12 @@ declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetch
160
267
  * This keeps a hanging platform from costing every page request its budget.
161
268
  */
162
269
 
270
+ /**
271
+ * The ruleset with only its valid rules, or null when the envelope itself is
272
+ * malformed. A single bad rule is DROPPED (its test serves control) rather
273
+ * than discarding every other test; a bad envelope keeps the last good copy.
274
+ */
275
+ declare function sanitizeRuleset(value: unknown): PlaybookRuleset | null;
163
276
  /**
164
277
  * Where the ruleset for this render came from (debug/QA):
165
278
  * - `memory`: fresh in-memory copy (< 60s).
@@ -187,48 +300,181 @@ declare function getRulesetWithSource({ platformUrl, shopId, waitUntil, fetchImp
187
300
  */
188
301
  declare function prefetchRuleset(args: Parameters<typeof getRulesetWithSource>[0]): void;
189
302
 
303
+ interface CartAttribute {
304
+ key: string;
305
+ value?: string | null;
306
+ }
307
+ interface CartWriteResult {
308
+ ok: boolean;
309
+ /** The cart's attributes after the write, when the response carried them. */
310
+ attributes?: ReadonlyArray<CartAttribute> | null;
311
+ }
312
+ /** Merge `add` into `current` by key (an empty value removes the key). */
313
+ declare function mergeAttributes(current: ReadonlyArray<CartAttribute> | null | undefined, add: ReadonlyArray<CartAttribute>): {
314
+ key: string;
315
+ value: string;
316
+ }[];
317
+ interface CartEndpointOptions {
318
+ /** The store's cart action route. Default `/api/cart` (Pack Hydrogen). */
319
+ endpoint?: string;
320
+ /**
321
+ * The endpoint reads the cart and merges attributes itself (Pack's
322
+ * `/api/cart`): send only the keys being written. Default false: send the
323
+ * full merged list, because Hydrogen's `cart.updateAttributes` REPLACES the
324
+ * whole list and a lone `_pb_vid` would wipe every other attribute.
325
+ */
326
+ serverMerges?: boolean;
327
+ fetchImpl?: typeof fetch;
328
+ }
190
329
  /**
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.
196
- *
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.
205
- *
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.
330
+ * Default writer: POSTs to the store's cart endpoint in both shapes Hydrogen
331
+ * stores use (`action` + `attributes` fields, and CartForm's
332
+ * `cartFormInput`). Never throws.
209
333
  */
210
- type ConsentState = 'granted' | 'denied' | 'pending' | 'absent';
334
+ declare function createCartAttributeWriter({ endpoint, serverMerges, fetchImpl, }?: CartEndpointOptions): (add: ReadonlyArray<CartAttribute>, current: ReadonlyArray<CartAttribute> | null | undefined) => Promise<CartWriteResult>;
335
+ /** Default re-read: `GET endpoint` → `{cart: {attributes}}`. Null on failure. */
336
+ declare function createCartAttributeReader({ endpoint, fetchImpl, }?: CartEndpointOptions): () => Promise<CartAttribute[] | null>;
337
+ type CartAttributeWriter = ReturnType<typeof createCartAttributeWriter>;
338
+ type CartAttributeReader = ReturnType<typeof createCartAttributeReader>;
339
+ interface CartSyncSnapshot {
340
+ cartId: string | null | undefined;
341
+ attributes: ReadonlyArray<CartAttribute> | null | undefined;
342
+ /** The store's cart status, READ only. Writes wait for `idle` (or none). */
343
+ status?: string | null;
344
+ visitorId: string | null | undefined;
345
+ /** Consent allows it AND the visitor is in at least one running test. */
346
+ eligible: boolean;
347
+ }
348
+ type CartSyncEvent = {
349
+ type: 'scheduled';
350
+ cartId: string;
351
+ } | {
352
+ type: 'written';
353
+ cartId: string;
354
+ ok: boolean;
355
+ } | {
356
+ type: 'restored';
357
+ cartId: string;
358
+ keys: string[];
359
+ ok: boolean;
360
+ } | {
361
+ type: 'capped';
362
+ cartId: string;
363
+ };
364
+ interface CartSyncOptions {
365
+ write: CartAttributeWriter;
366
+ read?: CartAttributeReader;
367
+ maxWritesPerCart?: number;
368
+ idleMs?: number;
369
+ /** Keys another writer owns; restored if a write loses them. */
370
+ protectedKeyPrefixes?: string[];
371
+ onEvent?: (event: CartSyncEvent) => void;
372
+ }
373
+ declare const CART_SYNC_IDLE_MS = 3000;
374
+ declare const MAX_WRITES_PER_CART = 3;
211
375
  /**
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.
376
+ * The client write path as a small state machine (no React), so every rule
377
+ * above is unit-testable. Call `update()` with each new cart snapshot.
215
378
  */
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;
379
+ declare function createCartAttributeSync({ write, read, maxWritesPerCart, idleMs, protectedKeyPrefixes, onEvent, }: CartSyncOptions): {
380
+ update(s: CartSyncSnapshot): void;
381
+ dispose(): void;
382
+ /** Test/debug: writes made for the current cart. */
383
+ writesForCart(cartId: string): number;
384
+ };
224
385
  /**
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.
386
+ * Returns the cart-create input with `_pb_vid` in its attributes (other
387
+ * attributes kept; an existing `_pb_vid` replaced). `attribute` null → the
388
+ * input unchanged. Use in the store's cart action for `Create`, and for a
389
+ * `LinesAdd` that will create the cart (no cart id yet).
230
390
  */
231
- declare function analyticsConsentFromCookie(raw: string | undefined): ConsentState;
391
+ declare function withPlaybookCartAttribute<T extends object>(input: T | null | undefined, attribute: CartAttribute | null): T & {
392
+ attributes?: {
393
+ key: string;
394
+ value: string;
395
+ }[];
396
+ };
397
+
398
+ /** The env keys the kit reads (all optional). */
399
+ interface PlaybookEnv {
400
+ PUBLIC_PLAYBOOK_SHOP_ID?: string;
401
+ PLAYBOOK_PLATFORM_URL?: string;
402
+ PLAYBOOK_TESTS_DISABLED?: string;
403
+ }
404
+ interface CreatePlaybookContextOptions {
405
+ request: Request;
406
+ /** The worker env; any object carrying the keys above. */
407
+ env?: PlaybookEnv | Record<string, unknown> | null;
408
+ waitUntil?: (p: Promise<unknown>) => void;
409
+ /** Overrides `env.PUBLIC_PLAYBOOK_SHOP_ID`. */
410
+ shopId?: string | null;
411
+ /** Overrides `env.PLAYBOOK_PLATFORM_URL`. */
412
+ platformUrl?: string | null;
413
+ /** Overrides `env.PLAYBOOK_TESTS_DISABLED`. */
414
+ disabled?: boolean;
415
+ /** See `createPlaybook({consentRequired})` (Shopify consent path only). */
416
+ consentRequired?: boolean;
417
+ /** Consent adapter (e.g. `truevaultConsent`); same one as the client. */
418
+ consent?: PlaybookConsentAdapter;
419
+ overrides?: PlaybookOverride[];
420
+ fetchImpl?: typeof fetch;
421
+ }
422
+ interface PlaybookLoaderData {
423
+ /** Store-test state for `<PlaybookRoot state>` / `<PlaybookHead state>`. */
424
+ playbook: PlaybookState | null;
425
+ /** For `<PlaybookHead hasPlaybookParams>` (anti-flicker). */
426
+ hasPlaybookParams: boolean;
427
+ }
428
+ interface PlaybookRequestContext {
429
+ readonly shopId: string | null;
430
+ readonly platformUrl: string;
431
+ /** True when the kill switch is on (or there is no shop id). */
432
+ readonly disabled: boolean;
433
+ get(): Promise<PlaybookServerResult | null>;
434
+ loaderData(): Promise<PlaybookLoaderData>;
435
+ cartAttribute(): CartAttribute | null;
436
+ /** APPEND this request's Playbook cookies to `headers`. Never throws. */
437
+ appendCookies(headers: Headers): Promise<void>;
438
+ /**
439
+ * Returns the response with this request's Playbook cookies appended
440
+ * (re-wrapping it when its headers are immutable, e.g. `Response.redirect`).
441
+ * A redirect never waits on a still-pending resolution: its cookies are
442
+ * skipped and the next request sets them.
443
+ */
444
+ finalize(response: Response): Promise<Response>;
445
+ }
446
+ declare function createPlaybookContext({ request, env, waitUntil, shopId: shopIdOption, platformUrl: platformUrlOption, disabled: disabledOption, consentRequired, consent, overrides, fetchImpl, }: CreatePlaybookContextOptions): PlaybookRequestContext;
447
+ /**
448
+ * Wrapper form: creates the context, runs the store's handler with it, then
449
+ * finalizes whatever response the handler returns (incl. a redirect built
450
+ * from a 404). The handler must still put `playbook` on its load context.
451
+ */
452
+ declare function withPlaybook(options: CreatePlaybookContextOptions, handler: (playbook: PlaybookRequestContext) => Promise<Response>): Promise<Response>;
453
+
454
+ declare const DEFAULT_SDK_URL = "https://cdn.heyplaybook.com/playbook.js";
455
+ /** First-party proxy prefix (the `/apps/playbook/*` route). */
456
+ declare const DEFAULT_PROXY_ENDPOINT = "/apps/playbook";
457
+ /** The reveal script, byte-compatible with the hand-wired integrations. */
458
+ declare function revealScript(hasPlaybookParams: boolean): string;
459
+ interface PlaybookHeadProps {
460
+ /** Playbook shop UUID (`PUBLIC_PLAYBOOK_SHOP_ID`). Falsy → renders nothing. */
461
+ shopId: string | null | undefined;
462
+ /**
463
+ * Where `playbook.js` sends API calls. Default `/apps/playbook` (first-party
464
+ * proxy); pass `https://www.heyplaybook.com` to go direct.
465
+ */
466
+ apiEndpoint?: string;
467
+ sdkUrl?: string;
468
+ /** From `context.playbook.loaderData()` (or `hasPlaybookParams(request.url)`). */
469
+ hasPlaybookParams?: boolean;
470
+ /** Store-test state from the root loader; its visitor id is seeded. */
471
+ state?: PlaybookState | null;
472
+ /** Explicit visitor id (overrides `state`). Non-UUID values are ignored. */
473
+ visitorId?: string | null;
474
+ /** CSP nonce for the inline scripts/style, when the store sets a CSP. */
475
+ nonce?: string;
476
+ }
477
+ declare function PlaybookHead({ shopId, apiEndpoint, sdkUrl, hasPlaybookParams, state, visitorId, nonce, }: PlaybookHeadProps): react_jsx_runtime.JSX.Element | null;
232
478
 
233
479
  /**
234
480
  * The standard events — ONE taxonomy for every store (GROWTH-TESTS.md "The
@@ -244,6 +490,14 @@ interface PlaybookStoreContext {
244
490
  locale?: string | null;
245
491
  isLoggedIn?: boolean | null;
246
492
  }
493
+ /**
494
+ * GA4 / GTM forwarding of exposures. `false` turns it off; `eventName`
495
+ * renames the event (default `view_experiment`).
496
+ */
497
+ type PlaybookDataLayerOption = false | {
498
+ eventName?: string;
499
+ };
500
+ declare const DEFAULT_DATALAYER_EVENT = "view_experiment";
247
501
  interface TrackedEntry {
248
502
  at: string;
249
503
  kind: 'exposure' | 'event';
@@ -289,6 +543,142 @@ interface TrackOptions {
289
543
  */
290
544
  declare function playbookTrack(event: StandardEvent, rawProps?: Record<string, unknown>, scope?: TrackScope, { oncePerSession, beacon }?: TrackOptions): number;
291
545
 
546
+ /** The sitewide A/A test key the sentinel exposes for. */
547
+ declare const AA_SITEWIDE_TEST = "aa-sitewide";
548
+ /** What the kit needs from the store's cart. READ-only: no setters. */
549
+ interface PlaybookCartAdapter {
550
+ cartId: string | null | undefined;
551
+ attributes: ReadonlyArray<CartAttribute> | null | undefined;
552
+ /** The store's cart status (writes wait for `idle`). Never written. */
553
+ status?: string | null;
554
+ /** Cart action route for the default writer/reader. Default `/api/cart`. */
555
+ endpoint?: string;
556
+ /** The endpoint merges attributes server-side (Pack `/api/cart`). */
557
+ serverMerges?: boolean;
558
+ /** Replace the default writer (must not touch the store's cart state). */
559
+ write?: CartAttributeWriter;
560
+ /** Replace the default re-read (used to confirm `_ig*` keys survived). */
561
+ read?: CartAttributeReader;
562
+ }
563
+ interface PlaybookRootProps {
564
+ state: PlaybookState | null | undefined;
565
+ location: {
566
+ pathname: string;
567
+ search?: string;
568
+ hash?: string;
569
+ };
570
+ /** Router navigate; used only to restore `?pb_preview=` inside Playbook's frame. */
571
+ navigate?: (to: string, options: {
572
+ replace: true;
573
+ preventScrollReset: true;
574
+ }) => void;
575
+ cart?: PlaybookCartAdapter | null;
576
+ consent?: PlaybookConsentAdapter;
577
+ storeContext?: PlaybookStoreContext;
578
+ /**
579
+ * The store's own CMS/editor preview (e.g. Pack customizer): no cart write,
580
+ * no A/A exposure.
581
+ */
582
+ editorPreview?: boolean;
583
+ /** Render the `aa-sitewide` sentinel (default true; inert without that test). */
584
+ aaSentinel?: boolean;
585
+ /** QA panel: force allow/deny, and the test keys this store has code for. */
586
+ debug?: {
587
+ allowed?: boolean;
588
+ implementedTests?: string[];
589
+ };
590
+ /** GA4 `view_experiment` dataLayer push per exposure (default on). */
591
+ dataLayer?: PlaybookDataLayerOption;
592
+ /** Observe cart-sync decisions (debug/logging). */
593
+ onCartSyncEvent?: (event: CartSyncEvent) => void;
594
+ exposureUrl?: string;
595
+ eventUrl?: string;
596
+ supportedEvents?: string[];
597
+ children: ReactNode;
598
+ }
599
+ /** Any running (non-forced) test the visitor is bucketed into. */
600
+ declare function visitorInRunningTest(state: PlaybookState | null | undefined): boolean;
601
+ /**
602
+ * A/A sentinel: invisible and IDENTICAL in both arms, so `aa-sitewide` can only
603
+ * measure the pipeline itself. Always in the viewport, out of layout flow.
604
+ * With no such rule (or not running) nothing is sent.
605
+ */
606
+ declare function PlaybookAAExposure({ testKey }: {
607
+ testKey?: string;
608
+ }): react_jsx_runtime.JSX.Element;
609
+ declare function PlaybookRoot({ state, location, navigate, cart, consent, storeContext, editorPreview, aaSentinel, debug, dataLayer, onCartSyncEvent, exposureUrl, eventUrl, supportedEvents, children, }: PlaybookRootProps): react_jsx_runtime.JSX.Element;
610
+
611
+ /** May the panel open on this page? */
612
+ declare function debugPanelAllowed(state: PlaybookState | null | undefined, hostname: string, allowed?: boolean): boolean;
613
+ declare function PlaybookDebugPanel({ state, location, allowed, implementedTests, }: {
614
+ state: PlaybookState | null | undefined;
615
+ location: {
616
+ pathname: string;
617
+ search?: string;
618
+ };
619
+ /** Force allow/deny; default: preview hosts or a verified preview token. */
620
+ allowed?: boolean;
621
+ /** Test keys this storefront has code for (others are labelled as such). */
622
+ implementedTests?: string[];
623
+ }): react_jsx_runtime.JSX.Element | null;
624
+
625
+ interface Props {
626
+ /** For the console warning only. */
627
+ name: string;
628
+ children?: ReactNode;
629
+ }
630
+ declare class PlaybookBoundary extends Component<Props, {
631
+ failed: boolean;
632
+ }> {
633
+ state: {
634
+ failed: boolean;
635
+ };
636
+ static getDerivedStateFromError(): {
637
+ failed: boolean;
638
+ };
639
+ componentDidCatch(error: unknown): void;
640
+ 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;
641
+ }
642
+
643
+ type PlatformUrlOption = string | null | undefined | ((args: ProxyArgs) => string | null | undefined);
644
+ interface ProxyArgs {
645
+ request: Request;
646
+ /** The route's load context; `context.env.PLAYBOOK_PLATFORM_URL` is read by default. */
647
+ context?: unknown;
648
+ }
649
+ interface PlaybookProxyOptions {
650
+ /** Default: `context.env.PLAYBOOK_PLATFORM_URL`, else heyplaybook.com. */
651
+ platformUrl?: PlatformUrlOption;
652
+ timeoutMs?: number;
653
+ maxBodyBytes?: number;
654
+ fetchImpl?: typeof fetch;
655
+ }
656
+ /** `/apps/playbook/api/x?y` → `{platform}/api/x?y`; other paths → `/api/<path>`. */
657
+ declare function playbookBackendUrl(requestUrl: string, platformUrl: string): string;
658
+ declare function createPlaybookProxyHandler({ platformUrl, timeoutMs, maxBodyBytes, fetchImpl, }?: PlaybookProxyOptions): {
659
+ loader: (args: ProxyArgs) => Promise<Response>;
660
+ action: (args: ProxyArgs) => Promise<Response>;
661
+ };
662
+
663
+ /** Small isomorphic predicates shared by the server helper and the client. */
664
+ /**
665
+ * The legacy `playbook.js` loader is about to swap content in (landing
666
+ * experiences, editor/brand previews): hide the page until it reveals it.
667
+ * Same four markers the hand-wired integrations checked.
668
+ */
669
+ declare function hasPlaybookParams(url: string | URL): boolean;
670
+ /**
671
+ * Kill switch: `PLAYBOOK_TESTS_DISABLED=1` (or `true`) turns off ONLY the
672
+ * store-test kit — assignment, visitor cookies, the cart attribute, exposures
673
+ * and events. The legacy `playbook.js` loader keeps running.
674
+ */
675
+ declare function isKillSwitchOn(value: string | null | undefined): boolean;
676
+ /**
677
+ * Non-production hosts where the QA panel may open from `?pb_debug=1`:
678
+ * Oxygen previews (`*.myshopify.dev`), Shopify previews, workers.dev and local.
679
+ */
680
+ declare function isPreviewHost(hostname: string): boolean;
681
+
292
682
  declare const DEFAULT_EXPOSURE_URL = "/apps/playbook/api/storefront/tests/exposure";
293
683
  declare const DEFAULT_EVENT_URL = "/apps/playbook/api/storefront/tests/event";
294
684
  /** Live analytics consent: granted / denied / pending / absent (API absent). */
@@ -347,7 +737,7 @@ declare function usePreviewParamRedirect(location: {
347
737
  hash: string;
348
738
  }): string | null;
349
739
 
350
- declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supportedEvents, storeContext, children, }: {
740
+ declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supportedEvents, storeContext, consent: consentAdapter, dataLayer, children, }: {
351
741
  state: PlaybookState | null | undefined;
352
742
  /** Current route pathname (re-render on navigation so path targeting updates). */
353
743
  pathname: string;
@@ -357,6 +747,16 @@ declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supp
357
747
  supportedEvents?: string[];
358
748
  /** Market / locale / login state, for the exposure context. */
359
749
  storeContext?: PlaybookStoreContext;
750
+ /**
751
+ * Consent source for stores whose CMP doesn't feed Shopify's Customer
752
+ * Privacy API. Must be the SAME adapter the server used.
753
+ */
754
+ consent?: PlaybookConsentAdapter;
755
+ /**
756
+ * Forward each exposure to `window.dataLayer` as GA4 `view_experiment`
757
+ * (default on). `false` disables; `{eventName}` renames.
758
+ */
759
+ dataLayer?: PlaybookDataLayerOption;
360
760
  children: ReactNode;
361
761
  }): react_jsx_runtime.JSX.Element;
362
762
  /** Component form of `usePlaybookExposure` for wrapping an existing element. */
@@ -373,7 +773,8 @@ declare function PlaybookExposure({ testKey, variant, enabled, children, }: {
373
773
  * does for the SDK (so both write the same keys the same way):
374
774
  *
375
775
  * granted / no CMP → `_pb_visitor_id` cookie, 365d (promotes a session id)
376
- * denied / pending → sessionStorage only; any cookie is EXPIRED
776
+ * pending → sessionStorage only; an existing cookie is left alone
777
+ * denied → sessionStorage only; any cookie is EXPIRED
377
778
  *
378
779
  * sessionStorage `_pb_visitor_id` is always seeded with the server's id so the
379
780
  * SDK's helper (which reads sessionStorage under denial) uses the same value.
@@ -383,10 +784,14 @@ declare function syncVisitorId(visitorId: string, consent: ConsentState): void;
383
784
  /**
384
785
  * Inline script for the document <head>, BEFORE the SDK script: seeds
385
786
  * 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).
787
+ * runs before hydration.
788
+ *
789
+ * The id comes from a request cookie the browser controls and is interpolated
790
+ * into an inline <script>, so ONLY the UUID shape Playbook mints is accepted;
791
+ * anything else returns '' (render no script) and a tampered cookie can never
792
+ * break out of the tag.
388
793
  */
389
- declare function visitorSeedScript(visitorId: string): string;
794
+ declare function visitorSeedScript(visitorId: string | null | undefined): string;
390
795
 
391
796
  declare function usePageEngagement(pathname: string, enabled: boolean): void;
392
797
 
@@ -408,7 +813,7 @@ declare const SESSION_VISITOR_COOKIE = "_pb_session_vid";
408
813
  /** Retired pilot cookie; migrated on first read, then expired. */
409
814
  declare const LEGACY_VISITOR_COOKIE = "pb_vid";
410
815
 
411
- type AddToCartSource = 'pdp' | 'quick_add' | 'cart_upsell' | 'other';
816
+ type AddToCartSource = 'pdp' | 'quick_add' | 'cart_upsell' | 'cross_sell' | 'other';
412
817
  declare function setNextAddSource(source: AddToCartSource): void;
413
818
  declare function takeAddSource(): AddToCartSource;
414
819
  interface AddedLineInput {
@@ -426,6 +831,31 @@ interface CartLineSnapshot {
426
831
  };
427
832
  };
428
833
  }
834
+ type CartLinesLike = CartLineSnapshot[] | {
835
+ nodes?: CartLineSnapshot[];
836
+ edges?: {
837
+ node: CartLineSnapshot;
838
+ }[];
839
+ } | null | undefined;
840
+ /**
841
+ * The lines an add request carried. Accepts the lines array itself, or the
842
+ * cart request's FormData in either Hydrogen shape: `action` + `lines` /
843
+ * `cart` fields (Pack's `/api/cart`), or CartForm's `cartFormInput`.
844
+ */
845
+ declare function addedLinesFrom(input: AddedLineInput[] | FormData | null | undefined): AddedLineInput[];
846
+ /**
847
+ * The store's ONE add-to-cart touchpoint. Call it after a SUCCESSFUL add
848
+ * (no user errors), with the lines that were added (array or the request's
849
+ * FormData) and the cart the mutation returned. `source` omitted → the one set
850
+ * by `setNextAddSource` (taken now), else `other`. No-op without consent or
851
+ * outside a running test. Never throws.
852
+ */
853
+ declare function trackAddToCart(source: AddToCartSource | null | undefined, { lines, cart, }: {
854
+ lines: AddedLineInput[] | FormData | null | undefined;
855
+ cart: {
856
+ lines?: CartLinesLike;
857
+ } | null | undefined | unknown;
858
+ }): void;
429
859
  /** One `add_to_cart` per added line. Never throws. */
430
860
  declare function trackAddToCartLines(lines: AddedLineInput[], cartLines: CartLineSnapshot[], source: AddToCartSource): void;
431
861
 
@@ -481,4 +911,4 @@ declare function inNamespace(hashValue: string, namespace: [string, number, numb
481
911
  declare function chooseVariation(n: number, ranges: VariationRange[]): number;
482
912
  declare function getBucketRanges(numVariations: number, coverage: number | undefined, weights?: number[]): VariationRange[];
483
913
 
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 };
914
+ export { AA_SITEWIDE_TEST, type AddToCartSource, type AddedLineInput, CART_SYNC_IDLE_MS, CART_VISITOR_ATTRIBUTE, 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_EXPOSURE_URL, DEFAULT_PLATFORM_URL, DEFAULT_PROXY_ENDPOINT, DEFAULT_SDK_URL, DEFAULT_SUPPORTED_EVENTS, LEGACY_VISITOR_COOKIE, MAX_WRITES_PER_CART, PlaybookAAExposure, type PlaybookArm, type PlaybookAssignReason, type PlaybookAssignment, PlaybookBoundary, type PlaybookCartAdapter, type PlaybookConsentAdapter, type PlaybookDataLayerOption, PlaybookDebugPanel, type PlaybookDevice, type PlaybookEnv, PlaybookExposure, PlaybookHead, type PlaybookHeadProps, type PlaybookLoaderData, type PlaybookOverride, type PlaybookPreview, PlaybookProvider, type PlaybookProxyOptions, type PlaybookRequestContext, PlaybookRoot, type PlaybookRootProps, 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, TRUEVAULT_CONSENT_COOKIE, type TrackScope, type TrackedEntry, type TrueVaultConsentOptions, VISITOR_COOKIE, addedLinesFrom, analyticsConsentFromCookie, assignTest, cartHasPlaybookAttribute, chooseVariation, createCartAttributeReader, createCartAttributeSync, createCartAttributeWriter, createPlaybook, createPlaybookContext, createPlaybookProxyHandler, createTrueVaultConsent, debugPanelAllowed, declareConsentRequired, detectDevice, detectGeo, getBucketRanges, getConsentState, getEqualWeights, getServerTrackedLog, getSessionContext, getTrackedLog, hasPlaybookParams, hasSentExposure, hash, inNamespace, isAnalyticsConsentGranted, isKillSwitchOn, isPreviewHost, matchesPathPrefix, mergeAttributes, onConsentChange, playbookBackendUrl, playbookCartAttribute, playbookTrack, prefetchRuleset, revealScript, sanitizeRuleset, setNextAddSource, subscribeTrackedLog, syncVisitorId, takeAddSource, trackAddToCart, trackAddToCartLines, trueVaultDecision, truevaultConsent, useAnalyticsAllowed, usePageEngagement, usePlaybookConsent, usePlaybookExposure, usePlaybookInteraction, usePlaybookState, usePlaybookVariant, usePreviewParamRedirect, visitorInRunningTest, visitorSeedScript, waitForConsentAPI, withPlaybook, withPlaybookCartAttribute };