@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/README.md +172 -2
- package/dist/index.d.ts +475 -45
- package/dist/index.js +1212 -119
- package/package.json +2 -1
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,106 @@
|
|
|
1
1
|
import * as react_jsx_runtime from 'react/jsx-runtime';
|
|
2
|
-
import
|
|
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
|
-
*
|
|
192
|
-
*
|
|
193
|
-
*
|
|
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
|
-
|
|
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
|
-
*
|
|
213
|
-
*
|
|
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
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
/**
|
|
220
|
-
|
|
221
|
-
|
|
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
|
-
*
|
|
226
|
-
*
|
|
227
|
-
*
|
|
228
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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.
|
|
387
|
-
*
|
|
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 };
|