@lucida-analytics/browser 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.
Files changed (108) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +228 -2
  3. package/dist/autocapture.d.ts +78 -0
  4. package/dist/autocapture.js +1 -0
  5. package/dist/banner-CGEWCIGP.js +1 -0
  6. package/dist/chunk-3PWTJFHH.js +1 -0
  7. package/dist/chunk-AWIQCFGN.js +1 -0
  8. package/dist/chunk-GVYMMTQM.js +1 -0
  9. package/dist/chunk-MCWQHOEV.js +1 -0
  10. package/dist/chunk-MI35SSIT.js +1 -0
  11. package/dist/client-ts5YMCoB.d.ts +8 -0
  12. package/dist/consent.d.ts +84 -0
  13. package/dist/consent.js +1 -0
  14. package/dist/core.d.ts +9 -0
  15. package/dist/core.js +3 -0
  16. package/dist/correlate.d.ts +15 -0
  17. package/dist/correlate.js +1 -0
  18. package/dist/early-access.d.ts +12 -0
  19. package/dist/early-access.js +1 -0
  20. package/dist/experiments.d.ts +199 -0
  21. package/dist/experiments.js +1 -0
  22. package/dist/flags.d.ts +13 -0
  23. package/dist/flags.js +3 -0
  24. package/dist/forms.d.ts +13 -0
  25. package/dist/forms.js +1 -0
  26. package/dist/guides.d.ts +1158 -0
  27. package/dist/guides.js +1 -0
  28. package/dist/heatmaps.d.ts +17 -0
  29. package/dist/heatmaps.js +1 -0
  30. package/dist/host-headers.d.ts +16 -0
  31. package/dist/host-headers.js +1 -0
  32. package/dist/index.d.ts +89 -0
  33. package/dist/index.js +3 -0
  34. package/dist/inspector.d.ts +13 -0
  35. package/dist/inspector.js +1 -0
  36. package/dist/lucida.js +3 -0
  37. package/dist/modules-FANMZRDJ.js +1 -0
  38. package/dist/persistent-XLGNSZQR.js +1 -0
  39. package/dist/recommendations.d.ts +2 -0
  40. package/dist/recommendations.js +1 -0
  41. package/dist/recorder-LFUTDRP4.js +78 -0
  42. package/dist/replay.d.ts +18 -0
  43. package/dist/replay.js +1 -0
  44. package/dist/static/v0/autocapture.js +1 -0
  45. package/dist/static/v0/banner-CGEWCIGP.js +1 -0
  46. package/dist/static/v0/chunk-3PWTJFHH.js +1 -0
  47. package/dist/static/v0/chunk-AWIQCFGN.js +1 -0
  48. package/dist/static/v0/chunk-GVYMMTQM.js +1 -0
  49. package/dist/static/v0/chunk-MCWQHOEV.js +1 -0
  50. package/dist/static/v0/chunk-MI35SSIT.js +1 -0
  51. package/dist/static/v0/consent.js +1 -0
  52. package/dist/static/v0/core.js +3 -0
  53. package/dist/static/v0/correlate.js +1 -0
  54. package/dist/static/v0/early-access.js +1 -0
  55. package/dist/static/v0/experiments.js +1 -0
  56. package/dist/static/v0/flags.js +3 -0
  57. package/dist/static/v0/forms.js +1 -0
  58. package/dist/static/v0/guides.js +1 -0
  59. package/dist/static/v0/heatmaps.js +1 -0
  60. package/dist/static/v0/host-headers.js +1 -0
  61. package/dist/static/v0/index.js +3 -0
  62. package/dist/static/v0/inspector.js +1 -0
  63. package/dist/static/v0/lucida.js +3 -0
  64. package/dist/static/v0/modules-FANMZRDJ.js +1 -0
  65. package/dist/static/v0/persistent-XLGNSZQR.js +1 -0
  66. package/dist/static/v0/recommendations.js +1 -0
  67. package/dist/static/v0/recorder-LFUTDRP4.js +78 -0
  68. package/dist/static/v0/replay.js +1 -0
  69. package/dist/static/v0/toolbar.js +4 -0
  70. package/dist/static/v0/validation-ENITEP6V.js +1 -0
  71. package/dist/static/v0/webmcp.js +1 -0
  72. package/dist/static/v0.1.0/autocapture.js +1 -0
  73. package/dist/static/v0.1.0/banner-CGEWCIGP.js +1 -0
  74. package/dist/static/v0.1.0/chunk-3PWTJFHH.js +1 -0
  75. package/dist/static/v0.1.0/chunk-AWIQCFGN.js +1 -0
  76. package/dist/static/v0.1.0/chunk-GVYMMTQM.js +1 -0
  77. package/dist/static/v0.1.0/chunk-MCWQHOEV.js +1 -0
  78. package/dist/static/v0.1.0/chunk-MI35SSIT.js +1 -0
  79. package/dist/static/v0.1.0/consent.js +1 -0
  80. package/dist/static/v0.1.0/core.js +3 -0
  81. package/dist/static/v0.1.0/correlate.js +1 -0
  82. package/dist/static/v0.1.0/early-access.js +1 -0
  83. package/dist/static/v0.1.0/experiments.js +1 -0
  84. package/dist/static/v0.1.0/flags.js +3 -0
  85. package/dist/static/v0.1.0/forms.js +1 -0
  86. package/dist/static/v0.1.0/guides.js +1 -0
  87. package/dist/static/v0.1.0/heatmaps.js +1 -0
  88. package/dist/static/v0.1.0/host-headers.js +1 -0
  89. package/dist/static/v0.1.0/index.js +3 -0
  90. package/dist/static/v0.1.0/inspector.js +1 -0
  91. package/dist/static/v0.1.0/integrity.json +30 -0
  92. package/dist/static/v0.1.0/lucida.js +3 -0
  93. package/dist/static/v0.1.0/modules-FANMZRDJ.js +1 -0
  94. package/dist/static/v0.1.0/persistent-XLGNSZQR.js +1 -0
  95. package/dist/static/v0.1.0/recommendations.js +1 -0
  96. package/dist/static/v0.1.0/recorder-LFUTDRP4.js +78 -0
  97. package/dist/static/v0.1.0/replay.js +1 -0
  98. package/dist/static/v0.1.0/toolbar.js +4 -0
  99. package/dist/static/v0.1.0/validation-ENITEP6V.js +1 -0
  100. package/dist/static/v0.1.0/webmcp.js +1 -0
  101. package/dist/toolbar.d.ts +193 -0
  102. package/dist/toolbar.js +4 -0
  103. package/dist/types-BWd9sbCh.d.ts +1071 -0
  104. package/dist/types-Cv4pBbPu.d.ts +898 -0
  105. package/dist/validation-ENITEP6V.js +1 -0
  106. package/dist/webmcp.d.ts +21 -0
  107. package/dist/webmcp.js +1 -0
  108. package/package.json +104 -3
@@ -0,0 +1,1158 @@
1
+ import { ConsentCategory, ConsentState, WireEvent, Core, Props, ConsentMode, FlagDefinition, EvalContext, Transport, ConsentStatus, FlagResult, Intervention, AgentConversationOptions, AgentConversation, EarlyAccessService, Storage } from '@lucida-analytics/sdk-core';
2
+
3
+ type BannerPosition = "bottom" | "top" | "center" | "bottom-left" | "bottom-right";
4
+ interface BannerTexts {
5
+ title: string;
6
+ body: string;
7
+ acceptAll: string;
8
+ rejectAll: string;
9
+ /** Saves the per-category choices (shown when more than one category is offered). */
10
+ save: string;
11
+ /** Label per category checkbox. */
12
+ categories: Record<ConsentCategory, string>;
13
+ }
14
+ interface BannerOptions {
15
+ /** Categories the visitor can choose. Default: analytics, replay, marketing. */
16
+ categories?: ConsentCategory[];
17
+ texts?: Partial<Omit<BannerTexts, "categories">> & {
18
+ categories?: Partial<BannerTexts["categories"]>;
19
+ };
20
+ position?: BannerPosition;
21
+ /** Policy/text version written to the `$consent_updated` record. Default `consent.policyVersion` or "1". */
22
+ version?: string;
23
+ /**
24
+ * Fill copy, categories and position from the project's `consent_banner` (settings.sdk, served by `GET /v1/config`).
25
+ * Options given here win. This is one request carrying only the public key, made before consent; off by default.
26
+ */
27
+ remote?: boolean;
28
+ }
29
+ /** Optional first-party banner (lazy chunk). */
30
+ interface ConsentUi {
31
+ /** Resolves with the stored decision, or null when dismissed with Escape (nothing is stored). */
32
+ showBanner(opts?: BannerOptions): Promise<ConsentState | null>;
33
+ hideBanner(): void;
34
+ }
35
+
36
+ /**
37
+ * Recording rules as trigger groups (remote `replay_trigger_groups`, local `trigger_groups`). Groups are
38
+ * OR-ed; inside one group the URL, event and flag conditions combine by `match`; a group without
39
+ * conditions always matches. A matched group still has to be sampled in (per group, deterministic per
40
+ * session), and its `min_duration_ms` then applies. Same semantics in every SDK (testdata/replay/sampling.json).
41
+ */
42
+ interface TriggerGroup {
43
+ id: string;
44
+ name?: string;
45
+ match?: "any" | "all";
46
+ /** Regex sources tested against the page URL; once matched it stays matched for the session. */
47
+ url_patterns?: string[];
48
+ events?: string[];
49
+ /** Truthy flag, or exactly `variant` when given. */
50
+ flag?: {
51
+ key: string;
52
+ variant?: string;
53
+ };
54
+ /** 0..1. Default 1. */
55
+ sample_rate?: number;
56
+ min_duration_ms?: number;
57
+ }
58
+
59
+ /** Opt-in asset capture (LC-EXP-64). Off by default; local config only. */
60
+ interface AssetCapture {
61
+ /** Inline same-origin / CORS-readable images into the recording as data URLs (rrweb `inlineImages`). Refused under mask-all-text. */
62
+ inlineImages?: boolean;
63
+ /** Inlined images larger than this (data URL characters, default 256 KB) are dropped; the element keeps its URL. */
64
+ maxInlineBytes?: number;
65
+ /** Record web fonts loaded with the FontFace API (rrweb `collectFonts`). */
66
+ collectFonts?: boolean;
67
+ /**
68
+ * Rewrites asset URLs (img/source/video src and srcset, poster, stylesheet links, CSS `url()` incl. fonts) from
69
+ * `origins` to `${url}?url=<encoded original>`, so the player loads CORS-blocked or expiring assets through your
70
+ * proxy. `url` must be on the page's origin or the Lucida host; any other proxy is ignored.
71
+ */
72
+ proxy?: {
73
+ url: string;
74
+ origins: string[];
75
+ };
76
+ }
77
+
78
+ /** A rectangle in canvas pixel coordinates (the canvas `width`/`height` space, not CSS pixels). */
79
+ interface CanvasRegion {
80
+ x: number;
81
+ y: number;
82
+ width: number;
83
+ height: number;
84
+ }
85
+ /** Remote rule: canvases matching `selector` get `regions` painted over, or the whole canvas when `regions` is absent. */
86
+ interface CanvasMaskRule {
87
+ selector: string;
88
+ regions?: CanvasRegion[];
89
+ }
90
+
91
+ interface MutationThrottle {
92
+ /** Attribute changes one element may make in a burst (default 100). */
93
+ burst?: number;
94
+ /** Sustained attribute changes per element per second after the burst (default 10). */
95
+ perSecond?: number;
96
+ }
97
+
98
+ /** Support widgets that get this session's replay link (LC-EXP-28). Opt-in, local config only. */
99
+ interface SupportWidgets {
100
+ /** `Intercom("update", { lucida_replay_url })` once Intercom is on the page. */
101
+ intercom?: boolean;
102
+ /** `$crisp.push(["set", "session:data", [[["lucida_replay_url", url]]]])` once Crisp is on the page. */
103
+ crisp?: boolean;
104
+ }
105
+
106
+ interface UrlPrivacyRule {
107
+ /** Substring with `*` wildcards, or `re:` + regular expression (case-insensitive), like the URL blocklist. */
108
+ url: string;
109
+ mask_all_text?: boolean;
110
+ mask_selectors?: string[];
111
+ block_selectors?: string[];
112
+ }
113
+
114
+ type ReplayOwner = "lucida" | "watchtower" | "both";
115
+ type ReplayTrigger = {
116
+ mode: "always";
117
+ } | {
118
+ mode: "on_event";
119
+ events: string[];
120
+ } | {
121
+ mode: "on_flag";
122
+ flag: string;
123
+ } | {
124
+ mode: "on_url";
125
+ pattern: string;
126
+ } | {
127
+ mode: "on_frustration";
128
+ };
129
+ interface ReplayConfig {
130
+ /** Set false to switch the module off. */
131
+ enabled?: boolean;
132
+ /** 0..1, decided once per session. Default 1. */
133
+ sample_rate?: number;
134
+ /** Sessions shorter than this are never sent. Default 0. */
135
+ min_duration_ms?: number;
136
+ trigger?: ReplayTrigger;
137
+ /** Recording rules (groups OR-ed, each with URL/event/flag conditions, sample rate, min duration). Replace `trigger` and `sample_rate` when non-empty. */
138
+ trigger_groups?: TriggerGroup[];
139
+ /** `buffer` (default, strict): this page's recorded data must reach the minimum. `session`: the session's age counts. */
140
+ min_duration_mode?: "buffer" | "session";
141
+ /** Regex source strings. Empty include = every URL. Exclude always wins. */
142
+ include_urls?: string[];
143
+ exclude_urls?: string[];
144
+ /** Extra CSS selectors blocked (placeholder box) / text-masked, on top of [data-lc-block] / [data-lc-mask]. */
145
+ block_selectors?: string[];
146
+ mask_selectors?: string[];
147
+ /** Default true. Only a local `false` loosens it; remote config can only tighten. */
148
+ mask_all_inputs?: boolean;
149
+ /** Mask every text node and text attribute (LC-EXP-40). Remote `replay_mask_all_text: true` forces it on. */
150
+ mask_all_text?: boolean;
151
+ /** Extra masking on pages matching a URL pattern (P-M16), added to the remote `replay_url_privacy_rules`; only tightens. */
152
+ url_privacy_rules?: UrlPrivacyRule[];
153
+ /** With mask_all_text: CSS selectors whose text stays visible, on top of [data-lc-unmask]. Local config only. */
154
+ unmask_selectors?: string[];
155
+ /** Ring buffer length before a trigger fires. Default 60 000. */
156
+ buffer_ms?: number;
157
+ flush_interval_ms?: number;
158
+ /** Flush a chunk at this many (uncompressed) bytes. Default 256 KB. */
159
+ chunk_bytes?: number;
160
+ owner?: ReplayOwner;
161
+ /** Opt-in canvas/WebGL capture (LC-EXP-23). Off unless set here or by the remote `replay_capture_canvas` toggle; `false` refuses the toggle. Canvases inside [data-lc-block] are never captured. */
162
+ captureCanvas?: CanvasCapture | false;
163
+ /** With mask_all_inputs false: input types that stay masked (password is always masked). */
164
+ maskInputOptions?: Partial<Record<MaskableInput, boolean>>;
165
+ /** Rewrites an input value before it is recorded (runs on inputs the rules mask; returning the text unmasks it). */
166
+ maskInputFn?: (text: string, element: HTMLElement) => string;
167
+ /** Rewrites the text of masked elements (e.g. hide only e-mail addresses). Ignored under mask_all_text. */
168
+ maskTextFn?: (text: string, element: HTMLElement | null) => string;
169
+ /** Rewrites page URLs before they leave the browser (meta events and pageview markers in the recording). */
170
+ maskUrlFn?: (url: string) => string;
171
+ /** Opt-in cross-origin iframe capture (LC-EXP-24). Local config only; both sides must list the other's origin. */
172
+ crossOriginIframes?: CrossOriginIframes;
173
+ /** Canvas areas painted black before a frame is encoded (LC-EXP-59), added to the remote `replay_canvas_mask` rules (which local config cannot remove). */
174
+ canvasMaskRegions?: (canvas: HTMLCanvasElement) => CanvasRegion[];
175
+ /** Per-element attribute-mutation guard (LC-EXP-65). On by default (burst 100, 10/s per element); `false` turns it off. */
176
+ mutationThrottle?: MutationThrottle | false;
177
+ /** Opt-in asset inlining / proxying (LC-EXP-64). Local config only. */
178
+ assets?: AssetCapture;
179
+ /** Opt-in: hand this session's replay link to Intercom / Crisp while recording (LC-EXP-28). Local config only. */
180
+ supportWidgets?: SupportWidgets;
181
+ }
182
+ type MaskableInput = "color" | "date" | "datetime-local" | "email" | "month" | "number" | "range" | "search" | "tel" | "text" | "time" | "url" | "week" | "textarea" | "select";
183
+ interface CanvasCapture {
184
+ /** Frames per second sampled per canvas. Default 2, max 15. */
185
+ fps?: number;
186
+ /** 0..1 JPEG quality. Default 0.4. */
187
+ quality?: number;
188
+ }
189
+ interface CrossOriginIframes {
190
+ /** Parent page: iframe origins whose events are merged. Iframe: parent origins it may post to. Exact `scheme://host[:port]`. */
191
+ allowedOrigins: string[];
192
+ }
193
+
194
+ interface RateLimitConfig {
195
+ /** Sustained events per second (default 10). */
196
+ eventsPerSecond?: number;
197
+ /** Bucket size: the burst allowed before throttling (default 100). */
198
+ burst?: number;
199
+ }
200
+
201
+ /** A `beforeSend` hook: return the (possibly amended) event, or null to drop it. */
202
+ type BeforeSend = (event: WireEvent) => WireEvent | null;
203
+ type PersonProfiles = "always" | "identified_only" | "never";
204
+
205
+ interface CookieOptions {
206
+ /** Force the Secure attribute on/off (default: on when the page is https). */
207
+ secure?: boolean;
208
+ /** Lifetime in days (default 365). */
209
+ expiryDays?: number;
210
+ /** Share the cookie across subdomains: the broadest registrable domain the browser accepts is used. */
211
+ crossSubdomain?: boolean;
212
+ /** Explicit cookie Domain (wins over crossSubdomain). */
213
+ domain?: string;
214
+ }
215
+
216
+ /**
217
+ * Where SDK state lives. "cookie" (default), "localStorage", "sessionStorage" (gone when the tab closes),
218
+ * "localStorage+cookie" (identity in a cookie and localStorage, everything else in localStorage), "memory"
219
+ * (this page only) and "none" (cookie-free: no storage writes at all, no distinct_id until identify() so the
220
+ * gateway derives its daily cookieless id, and no offline queue).
221
+ */
222
+ type Persistence = "cookie" | "localStorage" | "sessionStorage" | "localStorage+cookie" | "memory" | "none";
223
+ /** Modules the classic script (`lucida.js`) can load from `assetHost` (see docs/guides/sdk-pinning.md). */
224
+ type LazyModuleName = "replay" | "heatmaps" | "forms" | "toolbar" | "guides" | "inspector" | "experiments" | "early-access" | "consent";
225
+ interface StorageConfig {
226
+ persistence?: Persistence;
227
+ /** Cookie attributes for "cookie" and "localStorage+cookie". */
228
+ cookie?: CookieOptions;
229
+ /**
230
+ * "always" is `persistence: "none"`. "on_reject" is `consent.cookielessOnReject`: after a decline keep counting
231
+ * anonymously, with nothing stored. Both need cookieless mode on in the project.
232
+ */
233
+ cookieless?: "always" | "on_reject";
234
+ /** Only these super properties (`register` / `registerOnce`) are persisted; the rest last for this page. Default: all. */
235
+ persistedProperties?: string[];
236
+ /** Coalesce storage writes for this long (ms); reads see them at once, page hide writes them out. Default 0 (write through). */
237
+ storageWriteDelayMs?: number;
238
+ /** Separate store for the flag cache and persisted flag overrides (e.g. keep big payloads out of cookies). Default: `persistence`. */
239
+ flagPersistence?: Persistence;
240
+ /** Store for the consent decision itself (e.g. "cookie" so the server can read it). Default: `persistence`. */
241
+ consentPersistence?: Persistence;
242
+ }
243
+ interface DeliveryConfig {
244
+ /** Origin that serves the SDK's versioned static files (`/static/v<version>/...`). Default `apiHost`. */
245
+ assetHost?: string;
246
+ /** Classic script only: modules to load from `assetHost` before the client starts. Refused in extension mode. */
247
+ modules?: LazyModuleName[];
248
+ /** Rewrite the path of every request to `apiHost` / `flagsApiHost` (e.g. `/v1/batch` -> `/a/e`) for proxies that rename routes. */
249
+ rewritePath?: (path: string) => string;
250
+ /** CSP nonce put on every `<style>` the SDK injects (guides, experiment anti-flicker veil). */
251
+ nonce?: string;
252
+ /**
253
+ * Browser-extension (Manifest V3) mode: no cookies (localStorage instead), no remote code (`modules` refused).
254
+ * Default: on when the page runs on a `chrome-extension:`, `moz-extension:` or `safari-web-extension:` URL.
255
+ */
256
+ extension?: boolean;
257
+ /**
258
+ * Extension mode only: where state lives instead of cookies. "localStorage" (default) is the extension's own origin
259
+ * on a popup, options or side-panel page; use "memory" in a content script so nothing is written to the host page's storage.
260
+ */
261
+ extensionPersistence?: Persistence;
262
+ /**
263
+ * `$csp_violation` events from the page's `securitypolicyviolation` events (default off): directive, blocked URL and
264
+ * source file as origin + path, line and disposition. `{ maxPerPage }` caps the volume (default 20).
265
+ */
266
+ captureCspViolations?: boolean | {
267
+ maxPerPage?: number;
268
+ };
269
+ }
270
+ interface AutocaptureConfig {
271
+ /** Capture element text (default true). Text of form controls is never captured. */
272
+ captureText?: boolean;
273
+ /** Only capture events whose target is inside one of these selectors. */
274
+ allowSelectors?: string[];
275
+ /** Never capture events inside these selectors. */
276
+ denySelectors?: string[];
277
+ /** Only capture on pages whose URL matches one of these. */
278
+ urlAllowlist?: Array<string | RegExp>;
279
+ /** Autocapture is off on pages whose URL matches one of these (substring or RegExp); wins over `urlAllowlist`. */
280
+ urlIgnorelist?: Array<string | RegExp>;
281
+ /** Default: click, change, submit. */
282
+ events?: Array<"click" | "change" | "submit">;
283
+ /** `$autocapture` change events for edited `contenteditable` regions: element chain only, never the content (default true). */
284
+ contentEditable?: boolean;
285
+ /** `$copy_autocapture` on copy / cut with `$copy_type` (default false). */
286
+ copyCut?: boolean;
287
+ /** With `copyCut`: also send the selected text as `$selected_content`, digit runs masked and cut to 255 chars (default false). */
288
+ captureCopiedText?: boolean;
289
+ /** `$outbound_click` on links to other hosts (default true). */
290
+ outboundLinks?: boolean;
291
+ /** `$file_download` on download links: true = built-in extension list, string[] = your list, false = off (default true). */
292
+ fileDownloads?: boolean | string[];
293
+ /** `$site_search` when the URL carries a search param: true = q/s/search/query, `{params}` = yours, false = off (default true). */
294
+ siteSearch?: boolean | {
295
+ params?: string[];
296
+ };
297
+ /** `$content_impression` / `$content_interaction` for elements marked `data-lc-content` (default true; nothing is sent without the attribute). */
298
+ contentBlocks?: boolean;
299
+ /** `$article_read` read-through for the article region (`data-lc-region="article"` or `articleSelector`), default true; nothing is sent on pages without one. */
300
+ articles?: boolean;
301
+ /** CSS selector of the article region; wins over remote config `article_selector` and the `data-lc-region` attribute. */
302
+ articleSelector?: string;
303
+ /** `$media_play` / `$media_progress` (25, 50, 75%) / `$media_complete` for `<video>` and `<audio>` (default true). */
304
+ media?: boolean;
305
+ /** Only capture events whose target is inside one of these tags (e.g. ["a", "button"]). */
306
+ elementAllowlist?: string[];
307
+ /** Attribute names kept out of `$elements` (exact, or a trailing `*` prefix such as `data-*`; "href", "id" and "class" work too). */
308
+ attributeIgnore?: string[];
309
+ /** Replace every attribute value in `$elements` (id, href and kept attributes) with `***`, except `attributeAllowlist`. Default false. */
310
+ maskAllAttributes?: boolean;
311
+ /** With `maskAllAttributes`: names whose values stay readable (same matching as `attributeIgnore`). */
312
+ attributeAllowlist?: string[];
313
+ /** Rage-click hint thresholds; false = never add `$rageclick`. Defaults: 3 clicks within 1000 ms and 30 px. */
314
+ rageClicks?: false | FrustrationConfig;
315
+ /** Dead-click hint (`$deadclick_hint`): waitMs of DOM silence after a click on a non-interactive element (default 700). false = off. */
316
+ deadClicks?: false | {
317
+ waitMs?: number;
318
+ ignoreSelectors?: string[];
319
+ };
320
+ }
321
+ interface FrustrationConfig {
322
+ count?: number;
323
+ radiusPx?: number;
324
+ windowMs?: number;
325
+ /** Clicks inside these selectors never count (`.lc-no-rageclick` and `[data-lc-no-rageclick]` always opt out). */
326
+ ignoreSelectors?: string[];
327
+ /** Do not count clicks while text is selected (default true). */
328
+ ignoreTextSelection?: boolean;
329
+ /**
330
+ * Repeated clicks on steppers are intended, not rage: number inputs, +/- and arrow buttons, quantity and carousel
331
+ * controls (default true). `stepperSelectors` adds your own.
332
+ */
333
+ suppressSteppers?: boolean;
334
+ stepperSelectors?: string[];
335
+ }
336
+
337
+ /** One recommended item (from the project's catalog). */
338
+ interface RecommendationItem {
339
+ item_id: string;
340
+ name: string;
341
+ url?: string | null;
342
+ image_url?: string | null;
343
+ price?: number | null;
344
+ category?: string | null;
345
+ score: number;
346
+ }
347
+ interface RecommendationOptions {
348
+ /** The item on screen (product page): its neighbours are recommended and it is left out. */
349
+ itemId?: string;
350
+ limit?: number;
351
+ /** Item ids never to show (e.g. the cart). */
352
+ exclude?: string[];
353
+ /** Flag whose payload `lc_recs` configures this placement; default: any flag payload naming the placement. */
354
+ flag?: string;
355
+ /** Capture `$recommendation_shown` when the result arrives (default true); false = call `shown()` yourself on render. */
356
+ autoShown?: boolean;
357
+ }
358
+ interface Recommendations {
359
+ placement: string;
360
+ strategy: string;
361
+ items: RecommendationItem[];
362
+ /** The flag and value that chose the strategy, when one did. */
363
+ flag?: string;
364
+ variant?: FlagValue;
365
+ /** Capture `$recommendation_shown` (once). */
366
+ shown(): void;
367
+ /** Capture `$recommendation_clicked` for one item. */
368
+ clicked(itemId: string): void;
369
+ }
370
+ interface RecsService {
371
+ get(placement: string, opts?: RecommendationOptions): Promise<Recommendations>;
372
+ /** Record a viewed item for "recently viewed" (done automatically for the configured view event). */
373
+ viewed(itemId: string): void;
374
+ }
375
+
376
+ interface BootstrapConfig {
377
+ distinctId?: string;
378
+ /** distinctId belongs to a signed-in user (identified), not an anonymous visitor. */
379
+ isIdentified?: boolean;
380
+ /** Session id to continue (server-rendered pages). Ignored when a session is already stored. */
381
+ sessionId?: string;
382
+ flags?: Record<string, boolean | string>;
383
+ payloads?: Record<string, unknown>;
384
+ }
385
+ /** Flag request tuning (the `flags` module). */
386
+ interface FlagOptions {
387
+ /** Abort a /v1/flags request after this long (default 10000). */
388
+ timeoutMs?: number;
389
+ /** Refetch on this interval while the page is visible (0/unset = off). */
390
+ refreshMs?: number;
391
+ /** Evaluate and expose only these flag keys. */
392
+ keys?: string[];
393
+ /** Evaluation-context tags sent with the request for server-side scoping. */
394
+ evaluationContexts?: string[];
395
+ /** Never call /v1/flags: values come from bootstrap, localFlags and `updateFlags()` only. */
396
+ disableRemote?: boolean;
397
+ /**
398
+ * Skip the automatic flag requests (page load, `refreshMs`) while the last response for this visitor is younger than
399
+ * this many ms. `reloadFlags()`, identify/reset/group and property or context changes always fetch. Default off.
400
+ */
401
+ cacheTtlMs?: number;
402
+ /** false: do not add the landing URL's campaign params, `$os`, `$browser` and `$device_type` to flag requests as person properties. Default true. */
403
+ autoProperties?: boolean;
404
+ }
405
+ /** Per-call capture options. */
406
+ interface CaptureOptions {
407
+ /** Event time (epoch ms, ISO string or Date) instead of now. Invalid values are ignored. */
408
+ timestamp?: number | string | Date;
409
+ /** Flush the queue right after this event. */
410
+ sendInstantly?: boolean;
411
+ /** "beacon" flushes with sendBeacon (survives unload; falls back to fetch keepalive when `disableBeacon`). */
412
+ transport?: "beacon" | "fetch";
413
+ }
414
+ interface BrowserConfig extends StorageConfig, DeliveryConfig {
415
+ apiHost?: string;
416
+ /** Lucida app/API host for the toolbar and deep links (`getReplayUrl`) when `apiHost` is a reverse proxy that only forwards capture (default `apiHost`). */
417
+ uiHost?: string;
418
+ /** Toolbar: data attributes preferred when it builds an element selector (default data-lc-id, data-testid, data-test, data-cy, data-qa). */
419
+ toolbar?: {
420
+ dataAttributes?: string[];
421
+ };
422
+ autocapture?: boolean | AutocaptureConfig;
423
+ /** 'history' = initial + SPA route changes, 'hash' = history plus hash routes (`$pathname` includes the `#/route` fragment, fires on `hashchange`), true = initial only, false = none. Default 'history'. */
424
+ capturePageview?: "history" | "hash" | boolean;
425
+ consent?: {
426
+ mode?: ConsentMode;
427
+ queueBeforeConsent?: boolean;
428
+ respectDnt?: boolean;
429
+ /** Storage key of the stored decision (default `lc_consent`, suffixed per project like every SDK key). */
430
+ storageKey?: string;
431
+ /** Version of your consent text/policy, written to every `$consent_updated` record. Default "1". */
432
+ policyVersion?: string;
433
+ /** Send the consent-log record for a visitor who declines analytics as one anonymous beacon (no id, session, URL or storage). Default false: such a decision is not logged. */
434
+ logBeacon?: boolean;
435
+ /**
436
+ * Cookieless "on reject": after a visitor declines, keep counting pageviews and events anonymously (no storage,
437
+ * no distinct_id, no person properties; the gateway derives its daily cookieless id, so the project needs
438
+ * cookieless mode on). Granting later switches to normal identity. Default false: a decline drops events.
439
+ */
440
+ cookielessOnReject?: boolean;
441
+ /**
442
+ * Geo consent defaults (N-ANA-17): before anything is stored or sent, ask `GET /v1/config` which mode the
443
+ * project's rules give this visitor's country / US state (opt-in, opt-out or cookieless). Events wait in memory
444
+ * meanwhile (at most 3 s; then the local `mode` applies). A stored decision skips the wait. Default false.
445
+ */
446
+ geo?: boolean;
447
+ };
448
+ /** Treat Do Not Track as a consent denial in opt_out mode (default false; falls back to consent.respectDnt). */
449
+ respectDnt?: boolean;
450
+ /** Treat Global Privacy Control (`navigator.globalPrivacyControl`) as opt-out of non-essential storage (default false). */
451
+ respectGpc?: boolean;
452
+ /** Capture ad click ids (gclid, gad_source, gclsrc, dclid, gbraid, wbraid, fbclid, igshid, msclkid, ttclid, li_fat_id, twclid, mc_cid) from landing URLs into `$click_ids` on every event and `$initial_*` / `$last_*` person properties on `$pageview`. Remembered 90 days (`expiryDays`); stored only after consent. false = off. */
453
+ clickIds?: false | {
454
+ expiryDays?: number;
455
+ };
456
+ /** Hostnames to carry the visitor across with an `_lcid` link param (and accept it from). Match is exact or a subdomain. */
457
+ crossDomains?: string[];
458
+ debug?: boolean;
459
+ /** No events, no storage, no network (tests). */
460
+ disabled?: boolean;
461
+ /** Send nothing from known crawler / headless user agents (default true; the server still classifies anything that gets through). */
462
+ blockBots?: boolean;
463
+ /** Guides module: render=false leaves display to the host app. */
464
+ guides?: {
465
+ render?: boolean; /** Keep progress and dismissals on the server so they follow a person across devices (default true; needs consent and a distinct id). */
466
+ syncState?: boolean; /** Preferred guide language (BCP 47); default: person property `locale`, then the browser's. */
467
+ locale?: string; /** In a child frame: draw guides in the top window at this exact origin (its SDK must list this frame's origin in `frameOrigins`). */
468
+ renderInTop?: string; /** Top window: child-frame origins allowed to forward guides here. */
469
+ frameOrigins?: string[];
470
+ };
471
+ /** Visual-editor / personalization changes (the `experiments` module). antiFlickerMs hides the page until flags load (0 = off). */
472
+ visualChanges?: {
473
+ antiFlickerMs?: number;
474
+ /** Run per-variant custom JS that the project approved (`experiment.custom_code`); default false, so no experiment code runs unless the site opts in. */
475
+ allowCustomJs?: boolean;
476
+ };
477
+ /** Split-URL tests (the `splitUrl` experiments module): see experiments/split-url.ts. */
478
+ splitUrl?: {
479
+ antiFlickerMs?: number;
480
+ allowedOrigins?: string[];
481
+ navigate?: (url: string) => void;
482
+ };
483
+ /** Product recommendations (the `recommendations` module): the event and property that mark an item view (default `$product_viewed` / `item_id`). */
484
+ recommendations?: {
485
+ viewEvent?: string;
486
+ itemIdProperty?: string;
487
+ };
488
+ /** Skip the flags request at init; flags load on reloadFlags(), identify(), group() or reset(). */
489
+ disableFlagsOnFirstLoad?: boolean;
490
+ /** Attach `$feature/<key>` and `$active_feature_flags` to captured events (default true). */
491
+ sendFeatureFlags?: boolean;
492
+ bootstrap?: BootstrapConfig;
493
+ /**
494
+ * Hooks run in order on every event right before it is queued: return the (amended) event, or null to drop it.
495
+ * A hook that throws is logged and skipped. Events from sdk-internal modules go through them too.
496
+ */
497
+ beforeSend?: BeforeSend | BeforeSend[];
498
+ /** Keep this share (0..1) of events, stamping `$sample_rate`. Runs before `beforeSend`. */
499
+ sampleRate?: number;
500
+ /** Property names never sent (event properties, `$set`, `$set_once`). Runs before `beforeSend`. */
501
+ propertyDenylist?: string[];
502
+ /**
503
+ * "always" (default): normal person processing. "identified_only": events carry `$process_person_profile:false`
504
+ * until identify/alias/group/setPersonProperties. "never": always personless; identify/alias/setPersonProperties no-op.
505
+ */
506
+ personProfiles?: PersonProfiles;
507
+ /** reset() keeps this device's first anonymous id instead of minting a new one. */
508
+ reuseAnonymousId?: boolean;
509
+ /** Client token bucket (off by default): drops events beyond eventsPerSecond (10) with a burst of 100. */
510
+ rateLimit?: RateLimitConfig;
511
+ /** Session rotation limits in ms (defaults 30 min idle, 24 h total). */
512
+ /** Session rotation; unset values follow the project's session definition in the remote config (N-ANA-6). */
513
+ session?: {
514
+ idleMs?: number;
515
+ maxMs?: number;
516
+ newOnEvents?: string[];
517
+ };
518
+ /**
519
+ * Hostnames (`api.example.com`, or `.example.com` for the domain and subdomains) whose fetch/XHR requests carry
520
+ * `X-Lucida-Distinct-Id` and `X-Lucida-Session-Id`. Opt-in, consent-gated, never sent to the ingest host.
521
+ */
522
+ tracingHeaders?: string[];
523
+ /** Never use sendBeacon. */
524
+ disableBeacon?: boolean;
525
+ /** Extra headers on ingest requests (adds a CORS preflight to the ingest host). */
526
+ requestHeaders?: Record<string, string>;
527
+ /** Called when an ingest request fails (status 0) or returns an error status. */
528
+ onRequestError?: (e: {
529
+ url: string;
530
+ status: number;
531
+ }) => void;
532
+ /** Extra query parameters treated as campaign params (stored as `$<name>` on `$pageview`). */
533
+ customCampaignParams?: string[];
534
+ /** `$pageleave`: true = also without pageview capture, false = never, "if_capture_pageview" (default) = with pageviews. */
535
+ capturePageleave?: boolean | "if_capture_pageview";
536
+ /** Origin for /v1/flags when flags are proxied separately. Default apiHost. */
537
+ flagsApiHost?: string;
538
+ flagOptions?: FlagOptions;
539
+ flushAt?: number;
540
+ flushIntervalMs?: number;
541
+ /** Persist undeliverable batches in localStorage and replay them when online (default true). */
542
+ offlineQueue?: boolean;
543
+ /** Session replay (the `replay` module). */
544
+ replay?: ReplayConfig;
545
+ /** Who records the DOM when Watchtower is also on the page. Default 'lucida'. */
546
+ replayOwner?: ReplayOwner;
547
+ /** Watchtower seam: correlate fetch/XHR with the Lucida session via W3C baggage. */
548
+ watchtower?: {
549
+ correlate?: boolean;
550
+ origins?: Array<string | RegExp>;
551
+ };
552
+ /** Heatmap capture options (the `heatmaps` module). `attention` batches visible time per scroll band and element. */
553
+ heatmaps?: {
554
+ moves?: boolean;
555
+ moveIntervalMs?: number;
556
+ attention?: boolean;
557
+ };
558
+ /** Subscribe to GET /v1/flags/stream (public key; change notices only) and refetch flags on a notice. `pollMs` = fallback poll while the stream is down (default 60s, 0 = off). Default off. */
559
+ flagStream?: boolean | {
560
+ pollMs?: number;
561
+ };
562
+ /** Flag definitions bootstrapped from the server; evaluated in the browser with the sdk-core evaluator. */
563
+ localFlags?: FlagDefinition[];
564
+ /** Person/group/device properties the local evaluator may use (it knows nothing else about the user). */
565
+ localFlagsContext?: Partial<EvalContext>;
566
+ /** Agent analytics (`client.ai`). `captureText` sends message text and feedback comments, redacted (cards, emails, phones); default false (length, hash and sentiment only). */
567
+ ai?: {
568
+ captureText?: boolean;
569
+ };
570
+ /** Test/advanced overrides. */
571
+ transport?: Transport;
572
+ fetch?: typeof fetch;
573
+ }
574
+ /** `client.ai`: agent / chatbot conversation analytics (product side; LLM traces stay in Watchtower). */
575
+ interface AgentAnalytics {
576
+ /** Emits `$ai_conversation_started` and returns the handle for `message`, `feedback`, `end` and `outcome`. */
577
+ startConversation(opts?: AgentConversationOptions): AgentConversation;
578
+ }
579
+ interface RemoteConfig {
580
+ autocapture?: boolean;
581
+ /** Mirrors go/gateway ProjectConfig. */
582
+ session_recording?: boolean;
583
+ replay_sample_rate?: number;
584
+ mask_all_inputs?: boolean;
585
+ heatmaps?: boolean;
586
+ /** Replay privacy policy (settings.sdk): selectors masked / blocked; URL patterns (substring, `*` wildcard) not recorded; pages where a session start is never recorded. */
587
+ replay_mask_selectors?: string[];
588
+ /** Mask all replay text in the browser (LC-EXP-40); only tightens. */
589
+ replay_mask_all_text?: boolean;
590
+ replay_block_selectors?: string[];
591
+ replay_url_blocklist?: string[];
592
+ replay_never_record?: string[];
593
+ /** Recording rules (settings.sdk); see replay/groups.ts. */
594
+ replay_trigger_groups?: TriggerGroup[];
595
+ replay_min_duration_ms?: number;
596
+ replay_min_duration_mode?: "buffer" | "session";
597
+ /** Project toggle that turns canvas capture on with default fps/quality (a local `captureCanvas: false` refuses it). */
598
+ replay_capture_canvas?: boolean;
599
+ /** Canvas mask rules (LC-EXP-59): canvases matching `selector` get `regions` (or the whole canvas) painted over; only adds masking. */
600
+ replay_canvas_mask?: CanvasMaskRule[];
601
+ /** Optional extended replay settings (same names as ReplayConfig). */
602
+ replay?: Partial<ReplayConfig>;
603
+ /** Project session definition (N-ANA-6): idle minutes, longest session in minutes, events that start a session. */
604
+ session_idle_minutes?: number;
605
+ session_max_minutes?: number;
606
+ session_new_on_events?: string[];
607
+ /** Geo consent default resolved for this visitor (N-ANA-17), and the location it was resolved from. */
608
+ consent_default?: "opt_in" | "opt_out" | "cookieless";
609
+ consent_country?: string;
610
+ consent_region?: string;
611
+ [k: string]: unknown;
612
+ }
613
+ type FlagValue = boolean | string;
614
+ /** Flags module surface the client delegates to. */
615
+ interface FlagsService {
616
+ get(key: string): FlagValue | undefined;
617
+ payload(key: string): unknown;
618
+ /** Value, variant, payload and reason of one flag; records the exposure unless `sendExposure` is false. */
619
+ result(key: string, opts?: {
620
+ sendExposure?: boolean;
621
+ }): FlagResult;
622
+ /** A layer parameter (LC-EXT-36) from the layer experiment this person is in (records its exposure); undefined when in none. */
623
+ layerParam(layer: string, param: string): unknown;
624
+ onChange(cb: (flags: Record<string, FlagValue>) => void): () => void;
625
+ reload(): Promise<void>;
626
+ /** Every known flag value (overrides applied) without recording exposures. */
627
+ all(): Record<string, FlagValue>;
628
+ /** Local overrides that win over server values; false clears them. */
629
+ override(map: Record<string, FlagValue> | false, opts?: {
630
+ persist?: boolean;
631
+ }): void;
632
+ setPersonProperties(props: Props, reload?: boolean): void;
633
+ resetPersonProperties(): void;
634
+ setGroupProperties(props: Record<string, Props>, reload?: boolean): void;
635
+ resetGroupProperties(): void;
636
+ /** Sets the context of one kind for flag evaluation (kept in memory only; sent with the next flags request). */
637
+ setContext(kind: FlagContextKind, key: string, properties?: Props): void;
638
+ clearContext(kind: FlagContextKind): void;
639
+ /** Push flags evaluated elsewhere (your backend). merge=false replaces the current set. */
640
+ update(flags: Record<string, FlagValue>, payloads?: Record<string, unknown>, merge?: boolean): void;
641
+ }
642
+ /** The context kinds flags can target and bucket on (LC-FLG-18). */
643
+ type FlagContextKind = "user" | "device" | "org";
644
+ /** A person / group property test (`value` is compared as text). */
645
+ interface PropFilter {
646
+ key: string;
647
+ op: "eq" | "neq" | "contains" | "exists";
648
+ value?: unknown;
649
+ /** group_filters only: the group type (e.g. "org"). */
650
+ group_type?: string;
651
+ }
652
+ /** Client-side targeting keys for guides (cohort_ids / exclude_cohort_ids are resolved by the gateway). */
653
+ interface TargetConditions {
654
+ url?: string;
655
+ url_match?: "exact" | "contains" | "regex";
656
+ event_trigger?: string;
657
+ flag_key?: string;
658
+ /** With `flag_key`: only people served this variant (multivariate flags). */
659
+ flag_variant?: string;
660
+ delay_seconds?: number;
661
+ sample_pct?: number;
662
+ wait_days?: number;
663
+ devices?: Array<"desktop" | "mobile" | "tablet">;
664
+ person_filters?: PropFilter[];
665
+ /** Group (account) attributes, from `group(type, key, props)` calls. */
666
+ group_filters?: PropFilter[];
667
+ /** Guide ids this person must have / must not have seen in this browser. */
668
+ seen_guides?: string[];
669
+ not_seen_guides?: string[];
670
+ /** Window (RFC 3339), weekdays 0=Sunday and local hours [from, to) the guide may show in. */
671
+ schedule?: {
672
+ start?: string;
673
+ end?: string;
674
+ days?: number[];
675
+ hours?: {
676
+ from?: number;
677
+ to?: number;
678
+ };
679
+ timezone?: string;
680
+ };
681
+ /** At most `max_views` shows per rolling `per_days` (omitted: lifetime). Lifts the default show-once. */
682
+ frequency?: {
683
+ max_views?: number;
684
+ per_days?: number;
685
+ };
686
+ /** Share of eligible people held back as the control group (`$guide_holdout`). */
687
+ holdout_pct?: number;
688
+ /** `variant`: each A/B variant holds back its own control group (default: pooled across the group). */
689
+ holdout_scope?: "group" | "variant";
690
+ /** Guides sharing a group are A/B variants: one is picked per person, by `ab_weight`. */
691
+ ab_group?: string;
692
+ ab_weight?: number;
693
+ goal?: {
694
+ event: string;
695
+ window_days?: number;
696
+ };
697
+ /** Project-wide exclusions (served by the gateway): never on a URL matching any glob (`*`); a pattern starting with `/` matches the path. */
698
+ exclude_url_patterns?: string[];
699
+ }
700
+ /** Announcements: published banner guides. */
701
+ interface GuidesService {
702
+ /** Open the changelog panel listing announcement (banner) guides. Returns the entry count (0 = nothing shown). */
703
+ showChangelog(): number;
704
+ /**
705
+ * Show a published guide now (manual / API trigger), skipping its targeting but never consent, a guide already on
706
+ * screen, or the one-at-a-time rule. False when the guide is unknown (not published to this person) or blocked.
707
+ */
708
+ show(id: string): boolean;
709
+ /** Forget that this browser saw / dismissed / progressed through the guide, so its targeting can show it again. */
710
+ reset(id: string): void;
711
+ }
712
+ interface GuideButton {
713
+ label: string;
714
+ action: "next" | "back" | "dismiss" | "link" | "event" | "start_tour" | "snooze";
715
+ url?: string;
716
+ /** With `snooze`: hide the guide and show it again after this many hours (1..720). */
717
+ snooze_hours?: number;
718
+ event?: string;
719
+ /** With `next`: jump to a LATER step id, or "end". */
720
+ goto?: string;
721
+ }
722
+ interface GuideStep {
723
+ id: string;
724
+ title?: string;
725
+ body?: string;
726
+ selector?: string;
727
+ /** Tried in order when `selector` matches nothing (e.g. a stable data attribute, then a class path). */
728
+ fallback_selectors?: string[];
729
+ /** Tooltip / tour: wait up to this long (ms, default 3000, max 15000) for the target to appear before showing the step unanchored. */
730
+ wait_ms?: number;
731
+ /** How the step moves on: its buttons (default), a click on the target, or a `change` of the target field (value never read). */
732
+ advance?: "button" | "click" | "input";
733
+ /** Close the step (as dismissed, reason `auto_close`) after this many seconds (1..600). */
734
+ auto_close_s?: number;
735
+ /** Last step: a short confetti burst on completion (skipped under prefers-reduced-motion). */
736
+ confetti?: boolean;
737
+ /** Act on the page when the step shows. Never on password / masked / card fields; values are never read. */
738
+ automation?: GuideAutomation;
739
+ /** Mobile anchor (accessibility identifier / view tag / Flutter key / RN testID); the web ignores it. */
740
+ native_id?: string;
741
+ /** `form_validation` guides: the field and its format rules. */
742
+ validation?: {
743
+ selector: string;
744
+ rules: GuideRule[];
745
+ };
746
+ placement?: "top" | "bottom" | "left" | "right";
747
+ /** Page (URL substring) this step lives on; a tour waits for it across navigations. */
748
+ url?: string;
749
+ buttons?: GuideButton[];
750
+ /** First matching rule wins when Next is pressed on a step with no `goto`. Keys are person properties. */
751
+ branch?: Array<{
752
+ key: string;
753
+ op: PropFilter["op"] | "element_present" | "element_absent" | "flag_on" | "flag_off";
754
+ value?: unknown;
755
+ goto: string;
756
+ }>;
757
+ /** Checklist item: completes itself when this event is captured (all `props` equal). */
758
+ complete_on?: {
759
+ event: string;
760
+ props?: Record<string, string | number | boolean>;
761
+ };
762
+ /** Per-locale text; `buttons` are labels by position. */
763
+ i18n?: Record<string, {
764
+ title?: string;
765
+ body?: string;
766
+ buttons?: string[];
767
+ }>;
768
+ /** Rich media under the text (https only; embeds are sandboxed iframes of known video hosts). */
769
+ media?: GuideMedia[];
770
+ /** Resource-center module this item renders: other guides, announcements, or help-doc search. */
771
+ module?: "guides" | "announcements" | "search";
772
+ /** `guides` module: which guides to list (default: every tour, checklist and modal). */
773
+ guide_ids?: string[];
774
+ /** `search` module: help-doc search URL with `{q}`, opened in a new tab. */
775
+ search_url?: string;
776
+ }
777
+ interface GuideAutomation {
778
+ action: "click" | "focus" | "fill";
779
+ selector: string;
780
+ /** `fill` only: a builder-set constant. */
781
+ value?: string;
782
+ }
783
+ /** One format rule of a `form_validation` step (checked in the page; the value never leaves it). */
784
+ interface GuideRule {
785
+ type: "required" | "email" | "url" | "phone" | "regex" | "min_length" | "max_length" | "number";
786
+ value?: string | number;
787
+ message: string;
788
+ }
789
+ /** Colors (#hex), radius and font applied to the rendered guide. */
790
+ interface GuideTokens {
791
+ background?: string;
792
+ text?: string;
793
+ accent?: string;
794
+ radius?: number;
795
+ /** CSS font-family list (letters, digits, spaces, commas, quotes, hyphens). */
796
+ font?: string;
797
+ shadow?: "none" | "sm" | "lg";
798
+ button_radius?: number;
799
+ /** Secondary (non-first) buttons. */
800
+ secondary?: string;
801
+ secondary_text?: string;
802
+ }
803
+ interface GuideMedia {
804
+ type: "image" | "video" | "embed";
805
+ url: string;
806
+ alt?: string;
807
+ }
808
+ type GuideKind = "tooltip" | "modal" | "banner" | "tour" | "checklist" | "resource_center" | "announcement" | "hotspot" | "beacon" | "badge" | "launcher" | "slideout" | "inline" | "carousel" | "form_validation";
809
+ /** Shape of go/gateway GET /v1/guides; conditions are the client targeting keys. */
810
+ interface Guide {
811
+ id: string;
812
+ name: string;
813
+ kind: GuideKind;
814
+ steps: GuideStep[];
815
+ conditions: TargetConditions;
816
+ appearance?: {
817
+ i18n?: Record<string, {
818
+ name?: string;
819
+ }>;
820
+ launcher_label?: string;
821
+ tokens?: GuideTokens;
822
+ /** Dark variant, used when `theme_mode` is dark, or auto and the visitor prefers dark. */
823
+ dark?: {
824
+ tokens?: GuideTokens;
825
+ };
826
+ theme_mode?: "auto" | "light" | "dark";
827
+ /** Theme font (resolved by the gateway from `theme_id`); `tokens.font` wins. */
828
+ font_family?: string;
829
+ /** Dim the page behind the guide (default: modal only). */
830
+ overlay?: boolean;
831
+ /** Close (as dismissed) on a click outside the guide (default: modal only). */
832
+ dismiss_on_outside_click?: boolean;
833
+ /** Slideout edge. */
834
+ side?: "left" | "right";
835
+ [k: string]: unknown;
836
+ };
837
+ version?: number;
838
+ /** When the guide first went live (announcements list newest first). */
839
+ published_at?: string;
840
+ /** A draft served to one of its QA users (gateway): targeting is skipped, events carry `$guide_preview`. */
841
+ preview?: boolean;
842
+ /** This person is in the guide's holdout (decided by the gateway); the guide carries no steps. */
843
+ held_out?: boolean;
844
+ /** A workflow queued this guide for this person (gateway): it shows on the next eligible page view, skipping delay, sampling and wait_days. */
845
+ queued?: boolean;
846
+ }
847
+ /** What a manual `replay.start()` may bypass (default: sampling only). */
848
+ interface ReplayStartOverride {
849
+ sampling?: boolean;
850
+ url_trigger?: boolean;
851
+ event_trigger?: boolean;
852
+ linked_flag?: boolean;
853
+ }
854
+ /** Recording control (the `replay` module registers it; every call is a no-op without the module). */
855
+ interface ReplayControl {
856
+ /**
857
+ * Start now. No argument bypasses sampling only; `true` also bypasses every trigger; an object picks what to bypass.
858
+ * Never bypasses consent, replayOwner, the project kill-switch or never-record pages. Resolves once the attempt settled.
859
+ */
860
+ start(override?: true | ReplayStartOverride): Promise<void>;
861
+ /** Stop and discard unsent data; auto-start stays off until start(). */
862
+ stop(): void;
863
+ pause(): void;
864
+ resume(): void;
865
+ /** Emits `$replay_tag` { name, session_id } so the replay timeline can be searched. */
866
+ tag(name: string): void;
867
+ isRecording(): boolean;
868
+ }
869
+ /** What modules receive: the shared core plus platform helpers. */
870
+ interface Host {
871
+ core: Core;
872
+ client: Client;
873
+ config: BrowserConfig & {
874
+ apiHost: string;
875
+ };
876
+ apiKey: string;
877
+ log: (...a: unknown[]) => void;
878
+ fetch: typeof fetch;
879
+ /** Consent-gated store for the flag cache and persisted overrides (`flagPersistence`, else the core storage). */
880
+ flagStorage: Storage;
881
+ /** Runs on pagehide, before the final beacon flush. */
882
+ onUnload(fn: () => void): void;
883
+ /** Remote config; in opt_in mode resolves only after consent (no network before). */
884
+ loadConfig(): Promise<RemoteConfig | null>;
885
+ /** Run fn now if analytics consent is held, else when granted. */
886
+ whenConsented(fn: () => void): void;
887
+ /** Observe every captured event (after the consent gate). */
888
+ onCapture(fn: (e: WireEvent) => void): void;
889
+ /** Extra props for every event, contributed by modules (replay diagnostics). Read at event time with the event's session id. */
890
+ eventExtras: Array<(sessionId: string) => Props>;
891
+ /** Extra props for click events, contributed by modules (heatmaps). Read at event time. */
892
+ clickExtras: Array<(ev: MouseEvent, el: Element) => Props>;
893
+ /** Person properties modules add to flag requests and local evaluation (early-access enrolment). */
894
+ flagPersonProps: Array<() => Props>;
895
+ /** Set by autocapture when it already captures interactive clicks (heatmaps then adds only the rest). */
896
+ autocaptureClicks?: boolean;
897
+ /** A module registers the flags service here. */
898
+ flags?: FlagsService;
899
+ /** The earlyAccess module registers its service here. */
900
+ earlyAccess?: EarlyAccessService;
901
+ /** The guides module registers its service here. */
902
+ guides?: GuidesService;
903
+ /** The consentBanner module registers the lazy banner here. */
904
+ consentUi?: ConsentUi;
905
+ /** The replay module registers its control here. */
906
+ replay?: ReplayControl;
907
+ /** The toolbar module registers its manual loader here. */
908
+ toolbar?: {
909
+ load(token: string): Promise<boolean>;
910
+ };
911
+ /** The visualChanges module registers manual experiment activation here. */
912
+ experiments?: {
913
+ activate(flagKey: string): void;
914
+ };
915
+ /** The recommendations module registers its service here. */
916
+ recs?: RecsService;
917
+ }
918
+ /** A module is a function; it may return a teardown. Unused modules are tree-shaken. */
919
+ type Module = (host: Host) => void | (() => void);
920
+ interface Client {
921
+ readonly distinctId: string;
922
+ capture(event: string, props?: Props, options?: CaptureOptions): void;
923
+ identify(id: string, set?: Props, setOnce?: Props): void;
924
+ alias(alias: string, original?: string): void;
925
+ /** Forget the user. `resetDeviceId` also mints a new stable device id (flag device stickiness). */
926
+ reset(resetDeviceId?: boolean): void;
927
+ /** `$set` / `$set_once` on the current person (no-op with personProfiles "never"; turns a personless visitor into a person). */
928
+ setPersonProperties(set?: Props, setOnce?: Props): void;
929
+ unsetPersonProperties(keys: string[]): void;
930
+ /**
931
+ * personProfiles "identified_only": start processing a person for this visitor without identify() (the
932
+ * `$set_once` initial values kept while personless are sent along). No-op in "always" and "never".
933
+ */
934
+ createPersonProfile(): void;
935
+ /**
936
+ * Change options at runtime. Object options (autocapture, rateLimit, ...) merge one level deep. Takes effect at once
937
+ * for what is read per event: debug, autocapture options, beforeSend, sampleRate, propertyDenylist, rateLimit,
938
+ * persistedProperties, sendFeatureFlags, customCampaignParams, requestHeaders. Start-up options (apiHost,
939
+ * persistence, personProfiles, modules) keep their initial value.
940
+ */
941
+ setConfig(partial: Partial<BrowserConfig>): void;
942
+ getSessionId(): string;
943
+ /** Called with the session id now and on every rotation; returns the unsubscribe. */
944
+ onSessionId(cb: (sessionId: string) => void): () => void;
945
+ /** A registered super property (`register`). */
946
+ getProperty(key: string): unknown;
947
+ /** True while analytics capture is not allowed (opted out, or an opt_in project not yet opted in). */
948
+ hasOptedOut(): boolean;
949
+ /** Link to this session's replay in the Lucida app (uiHost, else apiHost). */
950
+ getReplayUrl(o?: {
951
+ withTimestamp?: boolean;
952
+ timestampLookBackSeconds?: number;
953
+ }): string;
954
+ /** Flip debug logging at runtime (also enabled by `?__lucida_debug=1`). */
955
+ debug(on?: boolean): void;
956
+ /** `$feature_view`: this person was shown the feature behind `flagKey`; marks the person `$feature_view/<key>`. */
957
+ featureView(flagKey: string, props?: Props): void;
958
+ /** `$feature_interaction`: this person used the feature behind `flagKey`; marks the person `$feature_interaction/<key>`. */
959
+ featureInteraction(flagKey: string, props?: Props): void;
960
+ /** Push flags evaluated by your own backend; merge=true (default) keeps the rest. */
961
+ updateFlags(flags: Record<string, FlagValue>, payloads?: Record<string, unknown>, o?: {
962
+ merge?: boolean;
963
+ }): void;
964
+ register(props: Props): void;
965
+ registerOnce(props: Props): void;
966
+ unregister(key: string): void;
967
+ group(type: string, key: string, props?: Props): void;
968
+ optIn(): void;
969
+ optOut(): void;
970
+ /** Tag every event from this browser `$internal: true` (staff / test traffic). Persists after consent; pass false to undo. */
971
+ optOutInternal(on?: boolean): void;
972
+ readonly isInternal: boolean;
973
+ setConsent(update: {
974
+ analytics?: boolean;
975
+ replay?: boolean;
976
+ marketing?: boolean;
977
+ }): void;
978
+ /** Current decision per category (the mode's default until the visitor chose). */
979
+ getConsent(): ConsentState;
980
+ /** `pending` until the visitor made an explicit choice, then `granted` or `denied` (default category analytics). */
981
+ getConsentStatus(category?: ConsentCategory): ConsentStatus;
982
+ /** The explicit analytics decision: "pending" until the visitor answers (show your banner then). */
983
+ consentStatus(): ConsentStatus;
984
+ getFlag(key: string): FlagValue | undefined;
985
+ getFlagPayload(key: string): unknown;
986
+ /** Value, variant, payload and reason (evaluator/server reason, or `override`, `preview`, `bootstrap`, `cached`, `pushed`, `not_found`) in one read. */
987
+ getFlagResult(key: string, opts?: {
988
+ sendExposure?: boolean;
989
+ }): FlagResult;
990
+ isFeatureEnabled(key: string): boolean;
991
+ /**
992
+ * A parameter of an experiment layer (LC-EXT-36): the value set by whichever experiment of the layer this
993
+ * person is allocated to (their exposure is recorded), else `fallback` (outside every experiment, or no flags module).
994
+ */
995
+ getLayerParam<T = unknown>(layer: string, param: string, fallback: T): T;
996
+ onFlags(cb: (flags: Record<string, FlagValue>) => void): () => void;
997
+ /** In-session interventions (N-ANA-2) fired for this person: opens GET /v1/interventions/stream on the first listener (after analytics consent). Returns unsubscribe. */
998
+ onIntervention(cb: (i: Intervention) => void): () => void;
999
+ reloadFlags(): Promise<void>;
1000
+ /** Every known flag value, without recording exposures. */
1001
+ getAllFlags(): Record<string, FlagValue>;
1002
+ /** Force flag values in this browser (QA, tests); `false` clears. persist keeps them across reloads (after consent). */
1003
+ overrideFlags(map: Record<string, FlagValue> | false, opts?: {
1004
+ persist?: boolean;
1005
+ }): void;
1006
+ /** Extra person properties for flag targeting only (additive); reloads flags unless reload=false. */
1007
+ setPersonPropertiesForFlags(props: Props, reload?: boolean): void;
1008
+ resetPersonPropertiesForFlags(): void;
1009
+ /** Extra group properties for flag targeting, by group type. */
1010
+ setGroupPropertiesForFlags(props: Record<string, Props>, reload?: boolean): void;
1011
+ resetGroupPropertiesForFlags(): void;
1012
+ /**
1013
+ * Describes the user, device or organisation to flag targeting (`context` filters and `context:<kind>` stickiness).
1014
+ * Held in memory only, never stored or captured as an event; it is sent to /v1/flags once analytics consent allows
1015
+ * the flags request, and cleared by reset(). Needs the `flags` module (no-op otherwise).
1016
+ */
1017
+ setContext(kind: FlagContextKind, key: string, properties?: Props): void;
1018
+ clearContext(kind: FlagContextKind): void;
1019
+ /** Agent analytics: `$ai_*` conversation events through the normal capture path (consent, opt-out, beforeSend apply). */
1020
+ readonly ai: AgentAnalytics;
1021
+ /** Early-access opt-in (no-ops until the `earlyAccess` module is installed). */
1022
+ readonly earlyAccess: EarlyAccessService;
1023
+ /** Changelog widget (no-ops until the `guides` module is installed). */
1024
+ readonly guides: GuidesService;
1025
+ readonly replay: ReplayControl;
1026
+ /** First-party consent banner (no-ops until the `consentBanner` module from "@lucida-analytics/browser/consent" is installed). */
1027
+ readonly consent: ConsentUi;
1028
+ /**
1029
+ * Start the toolbar from a launch token you carried yourself (frameworks that rewrite the URL before the SDK reads
1030
+ * `?__lc_toolbar=`). Pass the token or the `{token}` object; resolves false when rejected or the `toolbar` module is absent.
1031
+ */
1032
+ loadToolbar(params: string | {
1033
+ token: string;
1034
+ }): Promise<boolean>;
1035
+ /**
1036
+ * Activate a web experiment whose `lc_trigger` waits (SPAs: call it when the view the experiment targets renders);
1037
+ * also re-applies an active experiment's changes after a re-render. Needs the `visualChanges` module.
1038
+ */
1039
+ activateExperiment(flagKey: string): void;
1040
+ /** Recommended items for a placement (empty without the `recommendations` module or on any failure). */
1041
+ recommendations(placement: string, opts?: RecommendationOptions): Promise<Recommendations>;
1042
+ flush(): Promise<void>;
1043
+ shutdown(): Promise<void>;
1044
+ }
1045
+
1046
+ /** `POST /v1/guides/answer` response. */
1047
+ interface AnswerResult {
1048
+ answer: string;
1049
+ citations: Array<{
1050
+ title: string;
1051
+ url: string;
1052
+ }>;
1053
+ guide_ids: string[];
1054
+ }
1055
+ /** The resource center's AI help: the guides module wires it to the gateway and to `$guide_search`. */
1056
+ interface Assist {
1057
+ /** "unavailable" = no LLM configured (503): the answer box hides and plain search stays. null = failed this time. */
1058
+ ask(query: string): Promise<AnswerResult | "unavailable" | null>;
1059
+ /** One search, and later its answer feedback. The query text is passed for the opt-in project setting only. */
1060
+ searched(p: {
1061
+ query: string;
1062
+ results: number;
1063
+ answered: boolean;
1064
+ feedback?: "up" | "down";
1065
+ }): void;
1066
+ }
1067
+
1068
+ type Branch = NonNullable<GuideStep["branch"]>[number];
1069
+ interface BranchCtx {
1070
+ person?: Record<string, unknown>;
1071
+ /** The SDK's evaluated flag: on when served and not false. */
1072
+ flag?: (key: string) => boolean;
1073
+ }
1074
+ /** One branch rule: element presence (checked now), flag state, else a person-property test. */
1075
+ declare function branchOk(r: Branch, ctx: BranchCtx): boolean;
1076
+ /** Fields an automation never touches: passwords, masked fields and card data. */
1077
+ declare function sensitive(el: Element): boolean;
1078
+ type AutomationResult = "done" | "missing" | "refused" | "invalid";
1079
+ /**
1080
+ * Click, focus or fill the automation target. `fill` writes the builder's constant through the native value
1081
+ * setter (so frameworks see it) and fires input + change; the current value is never read.
1082
+ */
1083
+ declare function runAutomation(a: GuideAutomation, doc?: Document): AutomationResult;
1084
+
1085
+ /** What the renderer reports; the module turns these into $guide_* events. */
1086
+ interface GuideHooks {
1087
+ shown(): void;
1088
+ step(index: number, id: string): void;
1089
+ completed(): void;
1090
+ /** `reason`: "auto_close" (the step timed out) or "snooze"; omitted for a person's dismissal. */
1091
+ dismissed(index: number, id: string, reason?: "auto_close" | "snooze"): void;
1092
+ event(name: string): void;
1093
+ /** A `snooze` button: hide the guide for `hours`, then let it show again. */
1094
+ snoozed?(stepId: string, hours: number): void;
1095
+ /** An anchored step's target did not appear within its wait (the step then shows unanchored). */
1096
+ targetMissing?(stepId: string, selector: string): void;
1097
+ /** A `form_validation` field broke a rule (only the rule type is reported, never the value). */
1098
+ validationFailed?(stepId: string, rule: string): void;
1099
+ /** A step's automation ran, or was refused / missed its target. */
1100
+ automated?(stepId: string, result: AutomationResult): void;
1101
+ /** The step the person moved to (also when a tour waits for another page): persisted so the tour resumes. */
1102
+ progress?(stepId: string): void;
1103
+ }
1104
+ interface RenderOpts {
1105
+ /** Step index to open at (a resumed tour). */
1106
+ start?: number;
1107
+ /** Checklist item ids already done. */
1108
+ checked?: string[];
1109
+ /** Person properties, for step `branch` rules. */
1110
+ person?: Record<string, unknown>;
1111
+ /** Resource-center modules: the project's guides, and how to open one (closes this panel first). */
1112
+ library?: Guide[];
1113
+ launch?: (guideId: string) => void;
1114
+ /** CSP nonce for the injected `<style>`. */
1115
+ nonce?: string;
1116
+ /** Evaluated flags, for `flag_on` / `flag_off` branch rules. */
1117
+ flag?: (key: string) => boolean;
1118
+ /** Where a step's target is (default `findTarget`); a child frame forwarding to the top window maps it here. */
1119
+ resolveTarget?: (s: GuideStep) => Element | null;
1120
+ /** Resource-center AI answers and search reporting. */
1121
+ assist?: Assist;
1122
+ /** Run step automations (default true; off when the guide is drawn for another frame). */
1123
+ automate?: boolean;
1124
+ }
1125
+ /** What renderGuide returns: the teardown, plus a way to tick a checklist item from outside. */
1126
+ type GuideHandle = (() => void) & {
1127
+ markDone(stepId: string): void;
1128
+ };
1129
+ /**
1130
+ * Render a guide in a shadow root. Returns a teardown. Keyboard: Escape dismisses, Tab is trapped in
1131
+ * modals; other kinds move focus to their first control. URL buttons open with noopener.
1132
+ */
1133
+ declare function renderGuide(g: Guide, hooks: GuideHooks, done: () => void, opts?: RenderOpts): GuideHandle;
1134
+
1135
+ type Appearance = NonNullable<Guide["appearance"]>;
1136
+ /** The tokens to paint: base tokens, the theme font, then the dark variant on top when it applies. */
1137
+ declare function resolveTokens(a: Appearance | undefined, prefersDark?: boolean): GuideTokens;
1138
+
1139
+ declare const PERMALINK_PARAM = "lc_guide";
1140
+
1141
+ /**
1142
+ * Guides module (LC-ENG-4, 10-14, 16-20): GET /v1/guides after consent (the gateway applies cohort
1143
+ * targeting for ?distinct_id), client targeting (url, flag, sampling, wait_days, devices, person and
1144
+ * group attributes, seen guides, schedule, frequency), A/B variant and holdout, at most one modal-style
1145
+ * guide on screen (arbiter) plus any persistent hotspot/beacon/badge/launcher, then a shadow-DOM render
1146
+ * in the visitor's locale. Tours and checklists resume on the next page; checklist items tick
1147
+ * themselves from `complete_on` events. Inline guides wait for their element; resource-center
1148
+ * modules can open other guides. A `preview` guide (a draft served to one of its QA users) skips
1149
+ * targeting, shows once per page load and sends no events, so QA never reaches the results. config.guides.render === false leaves display to the host app.
1150
+ * Events: $guide_shown, $guide_step ($guide_step_id/_index: step reached; checklist item done),
1151
+ * $guide_completed, $guide_dismissed (`reason` auto_close / snooze), $guide_holdout (control group),
1152
+ * $guide_target_missing, $guide_validation_failed (rule type only), $guide_search (query length only by default),
1153
+ * all carrying $guide_id. Also: `?lc_guide=<id>` permalinks, snooze, form validation, carousels, and drawing in
1154
+ * the top window for a child frame (`renderInTop` / `frameOrigins`).
1155
+ */
1156
+ declare const guides: Module;
1157
+
1158
+ export { PERMALINK_PARAM, branchOk, guides, renderGuide, resolveTokens, runAutomation, sensitive };