@heyplaybook/hydrogen 0.2.0 → 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
@@ -76,7 +177,7 @@ interface PlaybookState {
76
177
  now: string;
77
178
  rulesetVersion: string | null;
78
179
  /** Where this render's ruleset came from; null when disabled. */
79
- rulesetSource: 'memory' | 'stale' | 'fetched' | 'last-good' | 'cold-fallback' | null;
180
+ rulesetSource: 'memory' | 'stale' | 'fetched' | 'last-good' | 'cold-fallback' | 'backoff' | null;
80
181
  /**
81
182
  * The verified `pb_preview` token, or null. Only present for a merchant's own
82
183
  * verified preview link; lets the client carry `?pb_preview=` across in-app
@@ -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,19 +249,30 @@ 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.
149
256
  *
150
257
  * - Fresh for 60s; served stale for a further 300s while one background
151
258
  * refresh runs (stale-while-revalidate).
152
- * - Past that, a render waits at most RENDER_BUDGET_MS for a fresh copy, then
153
- * falls back to the last good ruleset; with none, the caller gets `null`
154
- * and everyone sees control.
259
+ * - Past that, a render waits at most RENDER_BUDGET_MS (COLD_RENDER_BUDGET_MS
260
+ * with nothing cached) for a fresh copy, then falls back to the last good
261
+ * ruleset; with none, the caller gets `null` and everyone sees control.
155
262
  * - A failed or malformed fetch never replaces a good cached copy.
263
+ * - A failure (timeout, network error, non-2xx, malformed body) — or a render
264
+ * that gave up waiting on its budget — opens a FAILURE_BACKOFF_MS window per
265
+ * shop. Inside it no render touches the network or waits: each one gets the
266
+ * last good copy, or control. The first render after the window retries.
267
+ * This keeps a hanging platform from costing every page request its budget.
156
268
  */
157
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;
158
276
  /**
159
277
  * Where the ruleset for this render came from (debug/QA):
160
278
  * - `memory`: fresh in-memory copy (< 60s).
@@ -163,8 +281,10 @@ declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetch
163
281
  * - `last-good`: network missed the budget; served the last good copy.
164
282
  * - `cold-fallback`: nothing in memory and the network missed even the
165
283
  * cold budget (or failed) — everyone gets control for this render.
284
+ * - `backoff`: a recent fetch failed, so this render skipped the network and
285
+ * got the last good copy (or `null` — control — with none).
166
286
  */
167
- type RulesetSource = 'memory' | 'stale' | 'fetched' | 'last-good' | 'cold-fallback';
287
+ type RulesetSource = 'memory' | 'stale' | 'fetched' | 'last-good' | 'cold-fallback' | 'backoff';
168
288
  declare function getRulesetWithSource({ platformUrl, shopId, waitUntil, fetchImpl, }: {
169
289
  platformUrl: string;
170
290
  shopId: string;
@@ -180,48 +300,181 @@ declare function getRulesetWithSource({ platformUrl, shopId, waitUntil, fetchImp
180
300
  */
181
301
  declare function prefetchRuleset(args: Parameters<typeof getRulesetWithSource>[0]): void;
182
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
+ }
183
329
  /**
184
- * Analytics consent — vendored from the Playbook platform's shared consent module (the
185
- * storefront SDKs' single source; see Playbook's
186
- * `.ai/docs/STOREFRONT-CONSENT-GATING.md`, which is binding). Keep the logic
187
- * identical; this copy exists only because the store can't import the
188
- * Playbook monorepo.
189
- *
190
- * Contract:
191
- * - Read Shopify's Customer Privacy API (`analytics` purpose only, matching
192
- * the checkout Web Pixel). Never integrate with a CMP directly — any CMP that
193
- * feeds the API (e.g. TrueVault Polaris) works with no code here.
194
- * - RENDERING is functional and never gated. The persistent visitor cookie,
195
- * exposures, events and the cart attribute are ANALYTICS and are gated.
196
- * - FAIL OPEN only when the API is genuinely absent; CLOSED when it exists and
197
- * denies, or while a known-present API is still resolving.
198
- *
199
- * Client: `window`/`document` touched at CALL time only (safe to import on the
200
- * server). Server: `analyticsConsentFromCookie` reads Shopify's own
201
- * `_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.
202
333
  */
203
- 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;
204
375
  /**
205
- * Force the "a CMP is present" branch: a headless store whose CMP injects
206
- * `Shopify.customerPrivacy` after we boot (e.g. TrueVault Polaris). Without it a
207
- * 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.
208
378
  */
209
- declare function declareConsentRequired(): void;
210
- /** Wait for the API: already loaded → `loadFeatures()` → bounded poll → give up. */
211
- declare function waitForConsentAPI(): Promise<void>;
212
- /** Granted right now? Closed while resolving a known-present API; open if absent. */
213
- declare function isAnalyticsConsentGranted(): boolean;
214
- declare function getConsentState(): ConsentState;
215
- /** Subscribe to `visitorConsentCollected` (decision read from event.detail). */
216
- 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
+ };
217
385
  /**
218
- * SERVER: analytics consent from Shopify's `_tracking_consent` cookie.
219
- * Returns `granted` / `denied`, `pending` when the cookie exists but analytics
220
- * is undecided, and `absent` when there is no cookie at all. Tolerates both
221
- * known payload shapes (`con.CMP.a` = "1"/"0"/"" and `purposes.a` boolean);
222
- * 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).
223
390
  */
224
- 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;
225
478
 
226
479
  /**
227
480
  * The standard events — ONE taxonomy for every store (GROWTH-TESTS.md "The
@@ -237,6 +490,14 @@ interface PlaybookStoreContext {
237
490
  locale?: string | null;
238
491
  isLoggedIn?: boolean | null;
239
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";
240
501
  interface TrackedEntry {
241
502
  at: string;
242
503
  kind: 'exposure' | 'event';
@@ -282,6 +543,142 @@ interface TrackOptions {
282
543
  */
283
544
  declare function playbookTrack(event: StandardEvent, rawProps?: Record<string, unknown>, scope?: TrackScope, { oncePerSession, beacon }?: TrackOptions): number;
284
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
+
285
682
  declare const DEFAULT_EXPOSURE_URL = "/apps/playbook/api/storefront/tests/exposure";
286
683
  declare const DEFAULT_EVENT_URL = "/apps/playbook/api/storefront/tests/event";
287
684
  /** Live analytics consent: granted / denied / pending / absent (API absent). */
@@ -340,7 +737,7 @@ declare function usePreviewParamRedirect(location: {
340
737
  hash: string;
341
738
  }): string | null;
342
739
 
343
- declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supportedEvents, storeContext, children, }: {
740
+ declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supportedEvents, storeContext, consent: consentAdapter, dataLayer, children, }: {
344
741
  state: PlaybookState | null | undefined;
345
742
  /** Current route pathname (re-render on navigation so path targeting updates). */
346
743
  pathname: string;
@@ -350,6 +747,16 @@ declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supp
350
747
  supportedEvents?: string[];
351
748
  /** Market / locale / login state, for the exposure context. */
352
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;
353
760
  children: ReactNode;
354
761
  }): react_jsx_runtime.JSX.Element;
355
762
  /** Component form of `usePlaybookExposure` for wrapping an existing element. */
@@ -366,7 +773,8 @@ declare function PlaybookExposure({ testKey, variant, enabled, children, }: {
366
773
  * does for the SDK (so both write the same keys the same way):
367
774
  *
368
775
  * granted / no CMP → `_pb_visitor_id` cookie, 365d (promotes a session id)
369
- * 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
370
778
  *
371
779
  * sessionStorage `_pb_visitor_id` is always seeded with the server's id so the
372
780
  * SDK's helper (which reads sessionStorage under denial) uses the same value.
@@ -376,10 +784,14 @@ declare function syncVisitorId(visitorId: string, consent: ConsentState): void;
376
784
  /**
377
785
  * Inline script for the document <head>, BEFORE the SDK script: seeds
378
786
  * sessionStorage so `playbook.js` resolves the same visitor id even when it
379
- * runs before hydration. `visitorId` is a validated UUID (no escaping needed
380
- * 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.
381
793
  */
382
- declare function visitorSeedScript(visitorId: string): string;
794
+ declare function visitorSeedScript(visitorId: string | null | undefined): string;
383
795
 
384
796
  declare function usePageEngagement(pathname: string, enabled: boolean): void;
385
797
 
@@ -401,7 +813,7 @@ declare const SESSION_VISITOR_COOKIE = "_pb_session_vid";
401
813
  /** Retired pilot cookie; migrated on first read, then expired. */
402
814
  declare const LEGACY_VISITOR_COOKIE = "pb_vid";
403
815
 
404
- type AddToCartSource = 'pdp' | 'quick_add' | 'cart_upsell' | 'other';
816
+ type AddToCartSource = 'pdp' | 'quick_add' | 'cart_upsell' | 'cross_sell' | 'other';
405
817
  declare function setNextAddSource(source: AddToCartSource): void;
406
818
  declare function takeAddSource(): AddToCartSource;
407
819
  interface AddedLineInput {
@@ -419,6 +831,31 @@ interface CartLineSnapshot {
419
831
  };
420
832
  };
421
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;
422
859
  /** One `add_to_cart` per added line. Never throws. */
423
860
  declare function trackAddToCartLines(lines: AddedLineInput[], cartLines: CartLineSnapshot[], source: AddToCartSource): void;
424
861
 
@@ -474,4 +911,4 @@ declare function inNamespace(hashValue: string, namespace: [string, number, numb
474
911
  declare function chooseVariation(n: number, ranges: VariationRange[]): number;
475
912
  declare function getBucketRanges(numVariations: number, coverage: number | undefined, weights?: number[]): VariationRange[];
476
913
 
477
- 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 };