@heyplaybook/hydrogen 0.0.0-stage → 0.1.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/LICENSE +49 -0
- package/README.md +185 -2
- package/dist/index.d.ts +474 -0
- package/dist/index.js +1320 -0
- package/package.json +56 -4
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,474 @@
|
|
|
1
|
+
import * as react_jsx_runtime from 'react/jsx-runtime';
|
|
2
|
+
import { ReactNode } from 'react';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Playbook code-test types. Mirrors the ruleset contract served by
|
|
6
|
+
* `GET {PLAYBOOK_PLATFORM_URL}/api/storefront/tests/rules?shop={shopId}`.
|
|
7
|
+
*/
|
|
8
|
+
type PlaybookTestStatus = 'running' | 'paused' | 'completed';
|
|
9
|
+
type PlaybookDevice = 'mobile' | 'desktop';
|
|
10
|
+
type PlaybookVisitorType = 'new' | 'returning';
|
|
11
|
+
interface PlaybookArm {
|
|
12
|
+
key: string;
|
|
13
|
+
weight: number;
|
|
14
|
+
}
|
|
15
|
+
interface PlaybookTestRule {
|
|
16
|
+
key: string;
|
|
17
|
+
seed?: string;
|
|
18
|
+
hashVersion?: number;
|
|
19
|
+
status: PlaybookTestStatus;
|
|
20
|
+
coverage?: number;
|
|
21
|
+
arms: PlaybookArm[];
|
|
22
|
+
namespace?: {
|
|
23
|
+
id: string;
|
|
24
|
+
range: [number, number];
|
|
25
|
+
} | null;
|
|
26
|
+
targeting?: {
|
|
27
|
+
device?: PlaybookDevice;
|
|
28
|
+
pathPrefix?: string[];
|
|
29
|
+
visitorType?: PlaybookVisitorType;
|
|
30
|
+
} | null;
|
|
31
|
+
winner?: string | null;
|
|
32
|
+
config?: Record<string, unknown> | null;
|
|
33
|
+
}
|
|
34
|
+
interface PlaybookRuleset {
|
|
35
|
+
version: string;
|
|
36
|
+
generatedAt: string;
|
|
37
|
+
tests: PlaybookTestRule[];
|
|
38
|
+
}
|
|
39
|
+
/** One test's resolved outcome for the current visitor (ships to the client). */
|
|
40
|
+
/** Why a visitor got this arm (debug/QA; mirrors the platform core's AssignReason). */
|
|
41
|
+
type PlaybookAssignReason = 'preview' | 'override' | 'winner' | 'not-running' | 'no-visitor' | 'targeting-device' | 'targeting-visitor-type' | 'namespace' | 'hash-error' | 'coverage' | 'assigned' | 'unknown-test';
|
|
42
|
+
interface PlaybookAssignment {
|
|
43
|
+
arm: string;
|
|
44
|
+
status: PlaybookTestStatus;
|
|
45
|
+
reason: PlaybookAssignReason;
|
|
46
|
+
/** True only when the visitor was bucketed into a RUNNING test. */
|
|
47
|
+
inTest: boolean;
|
|
48
|
+
/** True when the arm comes from a verified `pb_preview` token or a QA override. */
|
|
49
|
+
forced: boolean;
|
|
50
|
+
config: Record<string, unknown>;
|
|
51
|
+
/** Evaluated on the client against the current route (SPA navigation). */
|
|
52
|
+
pathPrefix?: string[];
|
|
53
|
+
}
|
|
54
|
+
/** Serializable state the root loader hands to the client. */
|
|
55
|
+
interface PlaybookState {
|
|
56
|
+
enabled: boolean;
|
|
57
|
+
shopId: string | null;
|
|
58
|
+
visitorId: string | null;
|
|
59
|
+
visitorType: PlaybookVisitorType;
|
|
60
|
+
device: PlaybookDevice;
|
|
61
|
+
/**
|
|
62
|
+
* Analytics consent as the server saw it (`_tracking_consent` cookie). The
|
|
63
|
+
* client re-reads the live Customer Privacy API before any beacon.
|
|
64
|
+
*/
|
|
65
|
+
serverConsent: 'granted' | 'denied' | 'pending' | 'absent';
|
|
66
|
+
/** The store declared a late-loading CMP (closed until it answers). */
|
|
67
|
+
consentRequired: boolean;
|
|
68
|
+
/** Coarse geo from the edge (Oxygen `oxygen-buyer-*`), for exposure context. */
|
|
69
|
+
geo?: {
|
|
70
|
+
country: string | null;
|
|
71
|
+
region: string | null;
|
|
72
|
+
};
|
|
73
|
+
/** Server time (ISO) so date-windowed variants render identically on SSR + hydration. */
|
|
74
|
+
now: string;
|
|
75
|
+
rulesetVersion: string | null;
|
|
76
|
+
/** Where this render's ruleset came from; null when disabled. */
|
|
77
|
+
rulesetSource: 'memory' | 'stale' | 'fetched' | 'last-good' | 'cold-fallback' | null;
|
|
78
|
+
/**
|
|
79
|
+
* The verified `pb_preview` token, or null. Only present for a merchant's own
|
|
80
|
+
* verified preview link; lets the client carry `?pb_preview=` across in-app
|
|
81
|
+
* navigation inside a cross-site frame where third-party cookies may be blocked.
|
|
82
|
+
*/
|
|
83
|
+
previewToken: string | null;
|
|
84
|
+
tests: Record<string, PlaybookAssignment>;
|
|
85
|
+
}
|
|
86
|
+
interface PlaybookPreview {
|
|
87
|
+
testKey: string;
|
|
88
|
+
arm: string;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
declare const DEFAULT_PLATFORM_URL = "https://www.heyplaybook.com";
|
|
92
|
+
interface CreatePlaybookOptions {
|
|
93
|
+
/** Playbook shop UUID. Falsy → disabled: everyone gets control, no cookies. */
|
|
94
|
+
shopId: string | null | undefined;
|
|
95
|
+
platformUrl?: string | null;
|
|
96
|
+
request: Request;
|
|
97
|
+
/** Keeps a background ruleset refresh alive after the response (Workers). */
|
|
98
|
+
waitUntil?: (p: Promise<unknown>) => void;
|
|
99
|
+
fetchImpl?: typeof fetch;
|
|
100
|
+
/**
|
|
101
|
+
* Arms to force regardless of status/targeting (QA). Forced views never
|
|
102
|
+
* expose. The CALLER decides when overrides are trusted (e.g. preview hosts
|
|
103
|
+
* only) — this module applies whatever it is given.
|
|
104
|
+
*
|
|
105
|
+
* Precedence per test: a `pb_preview` token on THIS request > an override
|
|
106
|
+
* from this request (`source: 'request'`) > a `pb_preview` carried by the
|
|
107
|
+
* session cookie > a session override > natural assignment.
|
|
108
|
+
*/
|
|
109
|
+
overrides?: PlaybookOverride[];
|
|
110
|
+
/**
|
|
111
|
+
* The store's CMP may load after first paint (headless, e.g. TrueVault
|
|
112
|
+
* Polaris): with no `_tracking_consent` cookie yet, treat consent as pending
|
|
113
|
+
* (closed) instead of absent (open). Mirrors the SDK's
|
|
114
|
+
* `data-pb-consent="required"`.
|
|
115
|
+
*/
|
|
116
|
+
consentRequired?: boolean;
|
|
117
|
+
}
|
|
118
|
+
interface PlaybookOverride extends PlaybookPreview {
|
|
119
|
+
/** `request`: set by this request's URL; `session`: replayed from a cookie. */
|
|
120
|
+
source?: 'request' | 'session';
|
|
121
|
+
}
|
|
122
|
+
interface PlaybookServerResult {
|
|
123
|
+
/** Serializable; pass to the client through loader data. */
|
|
124
|
+
state: PlaybookState;
|
|
125
|
+
assignments: Record<string, PlaybookAssignment>;
|
|
126
|
+
visitorId: string | null;
|
|
127
|
+
preview: PlaybookPreview | null;
|
|
128
|
+
/** Where the verified preview came from (this request's URL or the cookie). */
|
|
129
|
+
previewSource: 'request' | 'session' | null;
|
|
130
|
+
/** Set-Cookie values to APPEND (never `set`) on the document response. */
|
|
131
|
+
setCookieHeaders: string[];
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Coarse geo from edge headers: Oxygen (`oxygen-buyer-country`,
|
|
135
|
+
* `oxygen-buyer-region-code`), falling back to Cloudflare / Vercel names.
|
|
136
|
+
*/
|
|
137
|
+
declare function detectGeo(headers: Headers): {
|
|
138
|
+
country: string | null;
|
|
139
|
+
region: string | null;
|
|
140
|
+
};
|
|
141
|
+
declare function detectDevice(userAgent: string | null): PlaybookDevice;
|
|
142
|
+
declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetchImpl, overrides, consentRequired, }: CreatePlaybookOptions): Promise<PlaybookServerResult>;
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* Ruleset fetch with an in-memory (per-isolate) cache.
|
|
146
|
+
*
|
|
147
|
+
* - Fresh for 60s; served stale for a further 300s while one background
|
|
148
|
+
* refresh runs (stale-while-revalidate).
|
|
149
|
+
* - Past that, a render waits at most RENDER_BUDGET_MS for a fresh copy, then
|
|
150
|
+
* falls back to the last good ruleset; with none, the caller gets `null`
|
|
151
|
+
* and everyone sees control.
|
|
152
|
+
* - A failed or malformed fetch never replaces a good cached copy.
|
|
153
|
+
*/
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* Where the ruleset for this render came from (debug/QA):
|
|
157
|
+
* - `memory`: fresh in-memory copy (< 60s).
|
|
158
|
+
* - `stale`: stale copy served while a background refresh runs.
|
|
159
|
+
* - `fetched`: waited for the network and got it within budget.
|
|
160
|
+
* - `last-good`: network missed the budget; served the last good copy.
|
|
161
|
+
* - `cold-fallback`: nothing in memory and the network missed even the
|
|
162
|
+
* cold budget (or failed) — everyone gets control for this render.
|
|
163
|
+
*/
|
|
164
|
+
type RulesetSource = 'memory' | 'stale' | 'fetched' | 'last-good' | 'cold-fallback';
|
|
165
|
+
declare function getRulesetWithSource({ platformUrl, shopId, waitUntil, fetchImpl, }: {
|
|
166
|
+
platformUrl: string;
|
|
167
|
+
shopId: string;
|
|
168
|
+
waitUntil?: (p: Promise<unknown>) => void;
|
|
169
|
+
fetchImpl?: typeof fetch;
|
|
170
|
+
}): Promise<{
|
|
171
|
+
ruleset: PlaybookRuleset | null;
|
|
172
|
+
source: RulesetSource;
|
|
173
|
+
}>;
|
|
174
|
+
/**
|
|
175
|
+
* Start (or join) the ruleset fetch as early as possible in a request, before
|
|
176
|
+
* routing/rendering; the render then joins the in-flight promise. Never throws.
|
|
177
|
+
*/
|
|
178
|
+
declare function prefetchRuleset(args: Parameters<typeof getRulesetWithSource>[0]): void;
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* Analytics consent — vendored from the Playbook platform's shared consent module (the
|
|
182
|
+
* storefront SDKs' single source; see Playbook's
|
|
183
|
+
* `.ai/docs/STOREFRONT-CONSENT-GATING.md`, which is binding). Keep the logic
|
|
184
|
+
* identical; this copy exists only because the store can't import the
|
|
185
|
+
* Playbook monorepo.
|
|
186
|
+
*
|
|
187
|
+
* Contract:
|
|
188
|
+
* - Read Shopify's Customer Privacy API (`analytics` purpose only, matching
|
|
189
|
+
* the checkout Web Pixel). Never integrate with a CMP directly — any CMP that
|
|
190
|
+
* feeds the API (e.g. TrueVault Polaris) works with no code here.
|
|
191
|
+
* - RENDERING is functional and never gated. The persistent visitor cookie,
|
|
192
|
+
* exposures, events and the cart attribute are ANALYTICS and are gated.
|
|
193
|
+
* - FAIL OPEN only when the API is genuinely absent; CLOSED when it exists and
|
|
194
|
+
* denies, or while a known-present API is still resolving.
|
|
195
|
+
*
|
|
196
|
+
* Client: `window`/`document` touched at CALL time only (safe to import on the
|
|
197
|
+
* server). Server: `analyticsConsentFromCookie` reads Shopify's own
|
|
198
|
+
* `_tracking_consent` cookie, the same signal the checkout pixel trusts.
|
|
199
|
+
*/
|
|
200
|
+
type ConsentState = 'granted' | 'denied' | 'pending' | 'absent';
|
|
201
|
+
/**
|
|
202
|
+
* Force the "a CMP is present" branch: a headless store whose CMP injects
|
|
203
|
+
* `Shopify.customerPrivacy` after we boot (e.g. TrueVault Polaris). Without it a
|
|
204
|
+
* first-time visitor with no `_tracking_consent` cookie would fail open.
|
|
205
|
+
*/
|
|
206
|
+
declare function declareConsentRequired(): void;
|
|
207
|
+
/** Wait for the API: already loaded → `loadFeatures()` → bounded poll → give up. */
|
|
208
|
+
declare function waitForConsentAPI(): Promise<void>;
|
|
209
|
+
/** Granted right now? Closed while resolving a known-present API; open if absent. */
|
|
210
|
+
declare function isAnalyticsConsentGranted(): boolean;
|
|
211
|
+
declare function getConsentState(): ConsentState;
|
|
212
|
+
/** Subscribe to `visitorConsentCollected` (decision read from event.detail). */
|
|
213
|
+
declare function onConsentChange(cb: (granted: boolean) => void): () => void;
|
|
214
|
+
/**
|
|
215
|
+
* SERVER: analytics consent from Shopify's `_tracking_consent` cookie.
|
|
216
|
+
* Returns `granted` / `denied`, `pending` when the cookie exists but analytics
|
|
217
|
+
* is undecided, and `absent` when there is no cookie at all. Tolerates both
|
|
218
|
+
* known payload shapes (`con.CMP.a` = "1"/"0"/"" and `purposes.a` boolean);
|
|
219
|
+
* anything unparseable is `pending` (closed), never granted.
|
|
220
|
+
*/
|
|
221
|
+
declare function analyticsConsentFromCookie(raw: string | undefined): ConsentState;
|
|
222
|
+
|
|
223
|
+
/**
|
|
224
|
+
* The standard events — ONE taxonomy for every store (GROWTH-TESTS.md "The
|
|
225
|
+
* standard events"). Store-specific interactions are `variant_interaction`
|
|
226
|
+
* with a `name` slug, never a new event.
|
|
227
|
+
*/
|
|
228
|
+
declare const STANDARD_EVENTS: readonly ["add_to_cart", "checkout_started", "scroll_depth", "engaged_time", "variant_interaction"];
|
|
229
|
+
type StandardEvent = (typeof STANDARD_EVENTS)[number];
|
|
230
|
+
declare const DEFAULT_SUPPORTED_EVENTS: string[];
|
|
231
|
+
/** Store-supplied context the module can't derive (market, locale, login). */
|
|
232
|
+
interface PlaybookStoreContext {
|
|
233
|
+
market?: string | null;
|
|
234
|
+
locale?: string | null;
|
|
235
|
+
isLoggedIn?: boolean | null;
|
|
236
|
+
}
|
|
237
|
+
interface TrackedEntry {
|
|
238
|
+
at: string;
|
|
239
|
+
kind: 'exposure' | 'event';
|
|
240
|
+
name: string;
|
|
241
|
+
testKey: string;
|
|
242
|
+
arm: string;
|
|
243
|
+
status: 'sent' | 'held' | 'blocked';
|
|
244
|
+
props?: Record<string, unknown>;
|
|
245
|
+
}
|
|
246
|
+
declare function getTrackedLog(): readonly TrackedEntry[];
|
|
247
|
+
declare function getServerTrackedLog(): readonly TrackedEntry[];
|
|
248
|
+
declare function subscribeTrackedLog(fn: () => void): () => void;
|
|
249
|
+
interface SessionContext {
|
|
250
|
+
utm: Record<string, string>;
|
|
251
|
+
referrerHost: string | null;
|
|
252
|
+
landingPath: string;
|
|
253
|
+
/** Which ad network's click id was on the landing URL — never the value. */
|
|
254
|
+
clickIdType: string | null;
|
|
255
|
+
}
|
|
256
|
+
/** Captured once per session on its first page, then reused. */
|
|
257
|
+
declare function getSessionContext(): SessionContext | null;
|
|
258
|
+
/** Whether this browser session already sent an exposure for the test. */
|
|
259
|
+
declare function hasSentExposure(visitorId: string, testKey: string): boolean;
|
|
260
|
+
/** Which tests an event is attributed to. */
|
|
261
|
+
type TrackScope =
|
|
262
|
+
/** every running test this visitor was exposed to this session */
|
|
263
|
+
'visitor'
|
|
264
|
+
/** running tests whose slot was on screen during this page view */
|
|
265
|
+
| 'page'
|
|
266
|
+
/** explicit test keys */
|
|
267
|
+
| {
|
|
268
|
+
testKeys: string[];
|
|
269
|
+
};
|
|
270
|
+
interface TrackOptions {
|
|
271
|
+
/** Once per visitor per test per session under this suffix (e.g. the event). */
|
|
272
|
+
oncePerSession?: string;
|
|
273
|
+
/** Use sendBeacon (pagehide). */
|
|
274
|
+
beacon?: boolean;
|
|
275
|
+
}
|
|
276
|
+
/**
|
|
277
|
+
* Track an event for every test in `scope`. No-op without consent, outside a
|
|
278
|
+
* running test, or for forced previews. Unsupported event names are held.
|
|
279
|
+
*/
|
|
280
|
+
declare function playbookTrack(event: StandardEvent, rawProps?: Record<string, unknown>, scope?: TrackScope, { oncePerSession, beacon }?: TrackOptions): number;
|
|
281
|
+
|
|
282
|
+
declare const DEFAULT_EXPOSURE_URL = "/apps/playbook/api/storefront/tests/exposure";
|
|
283
|
+
declare const DEFAULT_EVENT_URL = "/apps/playbook/api/storefront/tests/event";
|
|
284
|
+
/** Live analytics consent: granted / denied / pending / absent (API absent). */
|
|
285
|
+
declare function usePlaybookConsent(): ConsentState;
|
|
286
|
+
/**
|
|
287
|
+
* May analytics (exposures, events, the persistent visitor cookie, the cart
|
|
288
|
+
* attribute) run? Open only when granted or the API is genuinely absent.
|
|
289
|
+
*/
|
|
290
|
+
declare function useAnalyticsAllowed(): boolean;
|
|
291
|
+
declare function usePlaybookState(): PlaybookState | null;
|
|
292
|
+
interface PlaybookVariant {
|
|
293
|
+
arm: string;
|
|
294
|
+
inTest: boolean;
|
|
295
|
+
forced: boolean;
|
|
296
|
+
config: Record<string, unknown>;
|
|
297
|
+
}
|
|
298
|
+
/**
|
|
299
|
+
* The visitor's arm for a test. Resolved on the server and read from loader
|
|
300
|
+
* state, so SSR and hydration render the same arm (no flicker).
|
|
301
|
+
*
|
|
302
|
+
* `eligible: false` (e.g. "not a towel product") → control, not in test.
|
|
303
|
+
* A forced arm (QA `pb_force` or a `pb_preview` link) skips status and traffic
|
|
304
|
+
* split but still respects targeting: a towel arm forced on a towel page must
|
|
305
|
+
* not follow the session onto a bedding page.
|
|
306
|
+
*/
|
|
307
|
+
declare function usePlaybookVariant(testKey: string, { eligible }?: {
|
|
308
|
+
eligible?: boolean;
|
|
309
|
+
}): PlaybookVariant;
|
|
310
|
+
|
|
311
|
+
/**
|
|
312
|
+
* Returns `(name, target?)` that logs a `variant_interaction` for this test —
|
|
313
|
+
* anything the variant itself offers (`copy_code`, `open_review_quote`) —
|
|
314
|
+
* once per name+target per session. No-op without consent, outside the test,
|
|
315
|
+
* or for forced previews.
|
|
316
|
+
*/
|
|
317
|
+
declare function usePlaybookInteraction(testKey: string, variant: PlaybookVariant): (name: string, target?: string) => void;
|
|
318
|
+
/**
|
|
319
|
+
* Logs an exposure when the attached element is actually on screen, once per
|
|
320
|
+
* visitor per test per session. Attach the returned ref to an element that
|
|
321
|
+
* renders in BOTH arms (e.g. the price) so control and variant are exposed by
|
|
322
|
+
* the same trigger. No-op for forced previews and visitors not in the test.
|
|
323
|
+
*/
|
|
324
|
+
declare function usePlaybookExposure(testKey: string, variant: PlaybookVariant, { enabled }?: {
|
|
325
|
+
enabled?: boolean;
|
|
326
|
+
}): (el: Element | null) => void;
|
|
327
|
+
/**
|
|
328
|
+
* Preview-only: after an in-app navigation drops `?pb_preview=`, returns the
|
|
329
|
+
* URL (path + search + hash) that puts it back, or null when nothing to do.
|
|
330
|
+
* Needed inside a cross-site frame, where the SameSite=None preview cookie can
|
|
331
|
+
* still be blocked as a third-party cookie. Normal shoppers have no token, so
|
|
332
|
+
* this is always null for them.
|
|
333
|
+
*/
|
|
334
|
+
declare function usePreviewParamRedirect(location: {
|
|
335
|
+
pathname: string;
|
|
336
|
+
search: string;
|
|
337
|
+
hash: string;
|
|
338
|
+
}): string | null;
|
|
339
|
+
|
|
340
|
+
declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supportedEvents, storeContext, children, }: {
|
|
341
|
+
state: PlaybookState | null | undefined;
|
|
342
|
+
/** Current route pathname (re-render on navigation so path targeting updates). */
|
|
343
|
+
pathname: string;
|
|
344
|
+
exposureUrl?: string;
|
|
345
|
+
eventUrl?: string;
|
|
346
|
+
/** Event names the platform endpoint accepts; others are held, not sent. */
|
|
347
|
+
supportedEvents?: string[];
|
|
348
|
+
/** Market / locale / login state, for the exposure context. */
|
|
349
|
+
storeContext?: PlaybookStoreContext;
|
|
350
|
+
children: ReactNode;
|
|
351
|
+
}): react_jsx_runtime.JSX.Element;
|
|
352
|
+
/** Component form of `usePlaybookExposure` for wrapping an existing element. */
|
|
353
|
+
declare function PlaybookExposure({ testKey, variant, enabled, children, }: {
|
|
354
|
+
testKey: string;
|
|
355
|
+
variant: PlaybookVariant;
|
|
356
|
+
enabled?: boolean;
|
|
357
|
+
children: (ref: (el: Element | null) => void) => ReactNode;
|
|
358
|
+
}): react_jsx_runtime.JSX.Element;
|
|
359
|
+
|
|
360
|
+
/**
|
|
361
|
+
* CLIENT: keep the browser's copies of the ONE visitor id in line with the
|
|
362
|
+
* consent decision, exactly as the platform's shared visitor-id module
|
|
363
|
+
* does for the SDK (so both write the same keys the same way):
|
|
364
|
+
*
|
|
365
|
+
* granted / no CMP → `_pb_visitor_id` cookie, 365d (promotes a session id)
|
|
366
|
+
* denied / pending → sessionStorage only; any cookie is EXPIRED
|
|
367
|
+
*
|
|
368
|
+
* sessionStorage `_pb_visitor_id` is always seeded with the server's id so the
|
|
369
|
+
* SDK's helper (which reads sessionStorage under denial) uses the same value.
|
|
370
|
+
*/
|
|
371
|
+
|
|
372
|
+
declare function syncVisitorId(visitorId: string, consent: ConsentState): void;
|
|
373
|
+
/**
|
|
374
|
+
* Inline script for the document <head>, BEFORE the SDK script: seeds
|
|
375
|
+
* sessionStorage so `playbook.js` resolves the same visitor id even when it
|
|
376
|
+
* runs before hydration. `visitorId` is a validated UUID (no escaping needed
|
|
377
|
+
* beyond JSON).
|
|
378
|
+
*/
|
|
379
|
+
declare function visitorSeedScript(visitorId: string): string;
|
|
380
|
+
|
|
381
|
+
declare function usePageEngagement(pathname: string, enabled: boolean): void;
|
|
382
|
+
|
|
383
|
+
/** Minimal cookie helpers (web-standard, no dependencies). */
|
|
384
|
+
/**
|
|
385
|
+
* The ONE Playbook visitor id, shared with the existing SDK (`playbook.js`,
|
|
386
|
+
* the platform's shared visitor-id module): persistent (365d, host-only,
|
|
387
|
+
* readable by JS) only with analytics consent or no consent system.
|
|
388
|
+
*/
|
|
389
|
+
declare const VISITOR_COOKIE = "_pb_visitor_id";
|
|
390
|
+
/**
|
|
391
|
+
* Session-scoped carrier of the same id while consent is denied or pending, so
|
|
392
|
+
* the server can render the same arm on every page of the session (the SDK's
|
|
393
|
+
* equivalent is sessionStorage, which the server can't read). Functional:
|
|
394
|
+
* expires with the browser session, never written once the persistent cookie
|
|
395
|
+
* is allowed.
|
|
396
|
+
*/
|
|
397
|
+
declare const SESSION_VISITOR_COOKIE = "_pb_session_vid";
|
|
398
|
+
/** Retired pilot cookie; migrated on first read, then expired. */
|
|
399
|
+
declare const LEGACY_VISITOR_COOKIE = "pb_vid";
|
|
400
|
+
|
|
401
|
+
type AddToCartSource = 'pdp' | 'quick_add' | 'cart_upsell' | 'other';
|
|
402
|
+
declare function setNextAddSource(source: AddToCartSource): void;
|
|
403
|
+
declare function takeAddSource(): AddToCartSource;
|
|
404
|
+
interface AddedLineInput {
|
|
405
|
+
merchandiseId?: string;
|
|
406
|
+
quantity?: number;
|
|
407
|
+
}
|
|
408
|
+
interface CartLineSnapshot {
|
|
409
|
+
merchandise?: {
|
|
410
|
+
id?: string;
|
|
411
|
+
price?: {
|
|
412
|
+
amount?: string;
|
|
413
|
+
};
|
|
414
|
+
product?: {
|
|
415
|
+
id?: string;
|
|
416
|
+
};
|
|
417
|
+
};
|
|
418
|
+
}
|
|
419
|
+
/** One `add_to_cart` per added line. Never throws. */
|
|
420
|
+
declare function trackAddToCartLines(lines: AddedLineInput[], cartLines: CartLineSnapshot[], source: AddToCartSource): void;
|
|
421
|
+
|
|
422
|
+
/** Cart attribute that ties an order back to the visitor's assignments. */
|
|
423
|
+
declare const CART_VISITOR_ATTRIBUTE = "_pb_vid";
|
|
424
|
+
declare function playbookCartAttribute(visitorId: string): {
|
|
425
|
+
key: string;
|
|
426
|
+
value: string;
|
|
427
|
+
};
|
|
428
|
+
/** True when the cart already carries this visitor's id. */
|
|
429
|
+
declare function cartHasPlaybookAttribute(attributes: ReadonlyArray<{
|
|
430
|
+
key: string;
|
|
431
|
+
value?: string | null;
|
|
432
|
+
}> | null | undefined, visitorId: string): boolean;
|
|
433
|
+
|
|
434
|
+
declare const CONTROL_ARM = "control";
|
|
435
|
+
interface AssignInput {
|
|
436
|
+
visitorId: string | null;
|
|
437
|
+
device: PlaybookDevice;
|
|
438
|
+
visitorType: PlaybookVisitorType;
|
|
439
|
+
preview?: PlaybookPreview | null;
|
|
440
|
+
}
|
|
441
|
+
declare function assignTest(test: PlaybookTestRule, { visitorId, device, visitorType, preview }: AssignInput): PlaybookAssignment;
|
|
442
|
+
/**
|
|
443
|
+
* Path targeting is evaluated against the CURRENT route on the client, so a
|
|
444
|
+
* root loader that doesn't revalidate on SPA navigation stays correct. A
|
|
445
|
+
* leading locale segment (`/en-ca/products/…`) is ignored.
|
|
446
|
+
*/
|
|
447
|
+
declare function matchesPathPrefix(pathname: string, prefixes: string[] | undefined): boolean;
|
|
448
|
+
|
|
449
|
+
/**
|
|
450
|
+
* GrowthBook assignment primitives, vendored for Playbook code tests.
|
|
451
|
+
*
|
|
452
|
+
* Ported from GrowthBook's JavaScript SDK
|
|
453
|
+
* (https://github.com/growthbook/growthbook, packages/sdk-js/src/util.ts),
|
|
454
|
+
* MIT License, Copyright (c) 2021 GrowthBook, Inc.
|
|
455
|
+
*
|
|
456
|
+
* The canonical copy lives in the Playbook platform's shared core (unit-tested against
|
|
457
|
+
* GrowthBook's published `cases.json` vectors). This file must stay
|
|
458
|
+
* behaviour-identical to it: the platform's readout re-derives assignment from
|
|
459
|
+
* the same inputs, so any drift here silently corrupts a test.
|
|
460
|
+
*
|
|
461
|
+
* Pure and isomorphic: no Node, DOM or Worker globals.
|
|
462
|
+
*/
|
|
463
|
+
type VariationRange = [number, number];
|
|
464
|
+
/**
|
|
465
|
+
* Deterministic hash → n in [0, 1). Version 2 is GrowthBook's unbiased
|
|
466
|
+
* algorithm; version 1 is the original (still used for namespaces).
|
|
467
|
+
*/
|
|
468
|
+
declare function hash(seed: string, value: string, version: number): number | null;
|
|
469
|
+
declare function getEqualWeights(n: number): number[];
|
|
470
|
+
declare function inNamespace(hashValue: string, namespace: [string, number, number]): boolean;
|
|
471
|
+
declare function chooseVariation(n: number, ranges: VariationRange[]): number;
|
|
472
|
+
declare function getBucketRanges(numVariations: number, coverage: number | undefined, weights?: number[]): VariationRange[];
|
|
473
|
+
|
|
474
|
+
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 };
|