@guidelytech/sdk-core 0.8.0 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/chunk-544KSOC3.js +214 -0
- package/dist/chunk-544KSOC3.js.map +1 -0
- package/dist/headless.cjs +6 -0
- package/dist/headless.cjs.map +1 -1
- package/dist/headless.d.cts +1 -1
- package/dist/headless.d.ts +1 -1
- package/dist/headless.js +3 -1
- package/dist/index.cjs +39 -5
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +8 -3
- package/dist/index.d.ts +8 -3
- package/dist/index.js +37 -6
- package/dist/index.js.map +1 -1
- package/dist/types-DnJW_4ck.d.ts +253 -0
- package/dist/types-zM5e3loY.d.cts +253 -0
- package/package.json +7 -7
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
import { SdkEvent, PublishedGuide, FrequencyConfig, AutocaptureSettings, NetworkRequest, ProjectTheme, SdkConfigResponse, ChecklistTask, MessengerMessage, MessengerConversation } from '@guidelytech/shared';
|
|
2
|
+
import { b as KeyValueStore, S as StorageKind } from './http-47tiAlOM.js';
|
|
3
|
+
import { FlagsClientOptions } from '@guidelytech/flags';
|
|
4
|
+
|
|
5
|
+
interface EventQueueOptions {
|
|
6
|
+
store: KeyValueStore;
|
|
7
|
+
storageKey: string;
|
|
8
|
+
/** Sends one batch. Resolve `{ ok: true }` on success, `{ ok: false, retry }` otherwise. */
|
|
9
|
+
send: (events: SdkEvent[]) => Promise<{
|
|
10
|
+
ok: boolean;
|
|
11
|
+
retry?: boolean;
|
|
12
|
+
}>;
|
|
13
|
+
/** Synchronous best-effort send used on page hide. */
|
|
14
|
+
beacon?: (events: SdkEvent[]) => boolean;
|
|
15
|
+
/** Should events be flushed right now? (analytics enabled + consent granted). */
|
|
16
|
+
enabled: () => boolean;
|
|
17
|
+
flushIntervalMs?: number;
|
|
18
|
+
maxQueue?: number;
|
|
19
|
+
batchSize?: number;
|
|
20
|
+
maxAttempts?: number;
|
|
21
|
+
onError?: (err: unknown) => void;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Bounded, persisted event queue. Batches ≤50 events every 2s (or on demand), dedupes by
|
|
25
|
+
* `eventId`, retries with exponential backoff (1s→30s, 5 attempts) and keeps failed events for
|
|
26
|
+
* the next flush. Drops the oldest events once the queue exceeds 200.
|
|
27
|
+
*/
|
|
28
|
+
declare class EventQueue {
|
|
29
|
+
private readonly opts;
|
|
30
|
+
private events;
|
|
31
|
+
private timer;
|
|
32
|
+
private retryTimer;
|
|
33
|
+
private inflight;
|
|
34
|
+
private inflightIds;
|
|
35
|
+
private attempt;
|
|
36
|
+
private destroyed;
|
|
37
|
+
private readonly flushIntervalMs;
|
|
38
|
+
private readonly maxQueue;
|
|
39
|
+
private readonly batchSize;
|
|
40
|
+
private readonly maxAttempts;
|
|
41
|
+
constructor(opts: EventQueueOptions);
|
|
42
|
+
get size(): number;
|
|
43
|
+
/** Pending events (read-only copy, for debugging). */
|
|
44
|
+
peek(): SdkEvent[];
|
|
45
|
+
enqueue(event: SdkEvent): void;
|
|
46
|
+
private persist;
|
|
47
|
+
private schedule;
|
|
48
|
+
/** Sends queued events now (one batch at a time). Safe to call at any time. */
|
|
49
|
+
flush(): Promise<void>;
|
|
50
|
+
/** Best-effort synchronous flush on unload using `sendBeacon`. */
|
|
51
|
+
flushSync(): void;
|
|
52
|
+
clear(): void;
|
|
53
|
+
destroy(): void;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** Per-guide state kept locally and merged with the server's `IdentifyResponse.guideState`. */
|
|
57
|
+
interface GuideLocalState {
|
|
58
|
+
impressions: number;
|
|
59
|
+
completedAt?: string | null;
|
|
60
|
+
dismissedAt?: string | null;
|
|
61
|
+
lastShownAt?: string | null;
|
|
62
|
+
/** Last step reached in a multi-step flow (local only), so the messenger can offer to resume it. */
|
|
63
|
+
lastStepId?: string | null;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Pure frequency evaluation. `shownThisSession` comes from session storage.
|
|
67
|
+
* - `once`: a single impression ever (unless `reshowAfterDismiss` and it was only dismissed).
|
|
68
|
+
* - `once_per_session`: at most once per browser session.
|
|
69
|
+
* - `every_time`: on every trigger (still blocked by completion/dismissal rules below).
|
|
70
|
+
* - `interval`: at most once every `intervalHours`.
|
|
71
|
+
* `maxImpressions` caps total impressions; dismissal blocks re-showing unless `reshowAfterDismiss`
|
|
72
|
+
* (then `cooldownHours` must have elapsed); completion blocks unless mode is `every_time`.
|
|
73
|
+
*/
|
|
74
|
+
declare function isFrequencyEligible(freq: FrequencyConfig, state: GuideLocalState | undefined, shownThisSession: boolean, now?: number): boolean;
|
|
75
|
+
/**
|
|
76
|
+
* Exclusive guides (flows, modals, tooltips, announcements, surveys) run one at a time.
|
|
77
|
+
* Banners, checklists and hotspot-only tooltips can coexist with an active flow.
|
|
78
|
+
*/
|
|
79
|
+
declare function isExclusiveGuide(guide: PublishedGuide): boolean;
|
|
80
|
+
/** Is `a` mutually exclusive with `b` (by id or key, in either direction)? */
|
|
81
|
+
declare function areMutuallyExclusive(a: PublishedGuide, b: PublishedGuide): boolean;
|
|
82
|
+
/** Survey scheduling window. */
|
|
83
|
+
declare function isWithinSchedule(guide: PublishedGuide, now?: number): boolean;
|
|
84
|
+
/**
|
|
85
|
+
* A checklist's dismissal after merging server state. A local dismissal normally wins (it may not have
|
|
86
|
+
* synced yet), but when the server reports a reset this device hasn't applied, the server's value wins:
|
|
87
|
+
* null, or a dismissal made on another device after the reset. Compared as tokens, not times, so a
|
|
88
|
+
* skewed device clock can't keep a reset dismissal.
|
|
89
|
+
*/
|
|
90
|
+
declare function dismissedAfterMerge(local: {
|
|
91
|
+
dismissedAt?: string | null;
|
|
92
|
+
dismissResetAt?: string | null;
|
|
93
|
+
} | undefined, server: {
|
|
94
|
+
dismissedAt?: string | null;
|
|
95
|
+
dismissResetAt?: string | null;
|
|
96
|
+
}): string | null;
|
|
97
|
+
|
|
98
|
+
type GuidelyEnvironment = "development" | "staging" | "production";
|
|
99
|
+
type ConsentState = "granted" | "denied" | "pending";
|
|
100
|
+
interface GuidelyAccount {
|
|
101
|
+
id: string;
|
|
102
|
+
traits?: Record<string, unknown>;
|
|
103
|
+
}
|
|
104
|
+
interface GuidelyUser {
|
|
105
|
+
id: string;
|
|
106
|
+
traits?: Record<string, unknown>;
|
|
107
|
+
account?: GuidelyAccount;
|
|
108
|
+
}
|
|
109
|
+
interface GuidelyOptions {
|
|
110
|
+
/** Environment public key, e.g. `pk_dev_…`. Not a secret. */
|
|
111
|
+
projectId: string;
|
|
112
|
+
environment?: GuidelyEnvironment;
|
|
113
|
+
/** Base URL of the Guidely API (default `https://api.guidely.app`; use `http://localhost:3000` locally). */
|
|
114
|
+
apiUrl?: string;
|
|
115
|
+
/** Log trigger decisions and requests to the console. */
|
|
116
|
+
debug?: boolean;
|
|
117
|
+
/** Send analytics events (default `true`). Guides still render when disabled. */
|
|
118
|
+
analytics?: boolean;
|
|
119
|
+
/** `pending` buffers events until `setConsent("granted")`; `denied` disables analytics. */
|
|
120
|
+
consent?: ConsentState;
|
|
121
|
+
/** Where to persist identity, cached config and the event queue (default `local`). */
|
|
122
|
+
storage?: StorageKind;
|
|
123
|
+
/** Interval for re-checking element-visibility triggers while the page is idle (default 1000ms). */
|
|
124
|
+
pollIntervalMs?: number;
|
|
125
|
+
/** How often to refresh the published config (default 5 minutes). */
|
|
126
|
+
configRefreshMs?: number;
|
|
127
|
+
/** Elements whose text must never be captured (authoring snapshots, click text, session replays). Merged with the project setting. */
|
|
128
|
+
maskSelectors?: string[];
|
|
129
|
+
/**
|
|
130
|
+
* Page views, page leave, clicks and rage clicks are captured when the project enables them.
|
|
131
|
+
* `false` turns all of them off for this installation; an object turns individual ones off
|
|
132
|
+
* (`{ clicks: false }`). Options can only switch capture off, never on.
|
|
133
|
+
*/
|
|
134
|
+
autocapture?: boolean | Partial<AutocaptureSettings>;
|
|
135
|
+
/** App version or commit SHA (≤100 chars), sent with every `exception` to pick the matching uploaded source maps. */
|
|
136
|
+
release?: string;
|
|
137
|
+
/** `false` stops uncaught errors / unhandled rejections from being reported (`captureException` still works). */
|
|
138
|
+
captureErrors?: boolean;
|
|
139
|
+
/**
|
|
140
|
+
* `false` never records sessions on this installation. An object can only make masking stricter:
|
|
141
|
+
* `maskAllText` masks every text node, `blockSelectors` replaces matching elements with a placeholder.
|
|
142
|
+
*/
|
|
143
|
+
sessionReplay?: boolean | {
|
|
144
|
+
maskAllText?: boolean;
|
|
145
|
+
blockSelectors?: string[];
|
|
146
|
+
/** `false`: never record network requests / WebSockets in replays. */
|
|
147
|
+
recordNetwork?: false;
|
|
148
|
+
/** `false`: never record request/response headers, bodies or WebSocket frame data. */
|
|
149
|
+
recordNetworkPayloads?: false;
|
|
150
|
+
/** Last say over each recorded request (applied after redaction): return a modified copy, or null to drop it. */
|
|
151
|
+
maskNetworkRequest?: (request: NetworkRequest) => NetworkRequest | null;
|
|
152
|
+
};
|
|
153
|
+
onError?: (error: Error) => void;
|
|
154
|
+
/** Overrides for the project theme (colors, radius, font). */
|
|
155
|
+
theme?: Partial<ProjectTheme>;
|
|
156
|
+
/** Identify this user as soon as the client initialises. */
|
|
157
|
+
user?: GuidelyUser;
|
|
158
|
+
/** Custom fetch (tests / polyfills). */
|
|
159
|
+
fetch?: typeof fetch;
|
|
160
|
+
/** Disable the authoring-mode and how-to capture URL parameter detection. */
|
|
161
|
+
disableAuthoring?: boolean;
|
|
162
|
+
/**
|
|
163
|
+
* Feature flags (on by default, same key and API URL). `false` turns them off (getters return
|
|
164
|
+
* fallbacks, nothing is fetched); an object passes options to the flags client, e.g.
|
|
165
|
+
* `{ payload }` to bootstrap from server rendering, `{ attributes }`, `{ remoteEval: true }`,
|
|
166
|
+
* `{ pollingMode: "stream" }`. Identity, page and device attributes are maintained for you.
|
|
167
|
+
*/
|
|
168
|
+
flags?: false | Partial<FlagsClientOptions>;
|
|
169
|
+
}
|
|
170
|
+
interface ChecklistProgressState {
|
|
171
|
+
completedTaskIds: string[];
|
|
172
|
+
completedAt?: string | null;
|
|
173
|
+
dismissedAt?: string | null;
|
|
174
|
+
/** The server's last dismissal reset this device applied (see `dismissedAfterMerge`). */
|
|
175
|
+
dismissResetAt?: string | null;
|
|
176
|
+
}
|
|
177
|
+
/** Everything the client persists per project key (`guidely:state:<key>`). */
|
|
178
|
+
interface PersistedState {
|
|
179
|
+
guides: Record<string, GuideLocalState>;
|
|
180
|
+
checklists: Record<string, ChecklistProgressState>;
|
|
181
|
+
surveysSubmitted: string[];
|
|
182
|
+
audienceIds: string[];
|
|
183
|
+
firstSeenAt?: string;
|
|
184
|
+
}
|
|
185
|
+
interface SessionState {
|
|
186
|
+
id: string;
|
|
187
|
+
startedAt: string;
|
|
188
|
+
shownGuides: string[];
|
|
189
|
+
events: string[];
|
|
190
|
+
/** Epoch ms of the last tracked activity; the session rotates after `sessionTimeoutMinutes` of inactivity. */
|
|
191
|
+
lastActivityAt?: number;
|
|
192
|
+
/** Page views sent in this session (the first one carries the referrer). */
|
|
193
|
+
pageViews?: number;
|
|
194
|
+
/** Exceptions reported in this session (capped at 100). */
|
|
195
|
+
exceptions?: number;
|
|
196
|
+
/** Replay decision for this session: sampled in / forced (`true`), sampled out or disabled by the server (`false`). */
|
|
197
|
+
replay?: boolean;
|
|
198
|
+
}
|
|
199
|
+
interface GuideStepInfo {
|
|
200
|
+
guide: PublishedGuide;
|
|
201
|
+
stepId: string;
|
|
202
|
+
stepIndex: number;
|
|
203
|
+
}
|
|
204
|
+
interface GuidelyEvents {
|
|
205
|
+
/** Config loaded (from network or cache) and triggers evaluated. */
|
|
206
|
+
ready: (config: SdkConfigResponse) => void;
|
|
207
|
+
/** Config (re)loaded. */
|
|
208
|
+
config: (config: SdkConfigResponse) => void;
|
|
209
|
+
"guide:start": (guide: PublishedGuide) => void;
|
|
210
|
+
"guide:step": (info: GuideStepInfo) => void;
|
|
211
|
+
"guide:complete": (guide: PublishedGuide) => void;
|
|
212
|
+
"guide:dismiss": (guide: PublishedGuide) => void;
|
|
213
|
+
"guide:skip": (guide: PublishedGuide) => void;
|
|
214
|
+
"checklist:task": (info: {
|
|
215
|
+
guide: PublishedGuide;
|
|
216
|
+
task: ChecklistTask;
|
|
217
|
+
progress: ChecklistProgressState;
|
|
218
|
+
}) => void;
|
|
219
|
+
"checklist:complete": (guide: PublishedGuide) => void;
|
|
220
|
+
"survey:submit": (info: {
|
|
221
|
+
guide: PublishedGuide;
|
|
222
|
+
answers: Record<string, unknown>;
|
|
223
|
+
responseId: string;
|
|
224
|
+
}) => void;
|
|
225
|
+
"resource-center:open": () => void;
|
|
226
|
+
"messenger:open": () => void;
|
|
227
|
+
/** A Scout or teammate message arrived in the messenger. */
|
|
228
|
+
"conversation:message": (info: {
|
|
229
|
+
message: MessengerMessage;
|
|
230
|
+
conversation: MessengerConversation;
|
|
231
|
+
}) => void;
|
|
232
|
+
error: (error: Error) => void;
|
|
233
|
+
/** Every tracked event (custom and lifecycle). */
|
|
234
|
+
track: (event: SdkEvent) => void;
|
|
235
|
+
identify: (info: {
|
|
236
|
+
userId: string | null;
|
|
237
|
+
anonymousId: string;
|
|
238
|
+
}) => void;
|
|
239
|
+
authoring: (info: {
|
|
240
|
+
active: boolean;
|
|
241
|
+
}) => void;
|
|
242
|
+
/** How-to capture (recording steps for a how-to guide) started or ended in this tab. */
|
|
243
|
+
capture: (info: {
|
|
244
|
+
active: boolean;
|
|
245
|
+
}) => void;
|
|
246
|
+
/** Feature flags loaded (bootstrap, cache or network) — or failed to and serve fallbacks. */
|
|
247
|
+
"flags:ready": () => void;
|
|
248
|
+
/** New flag rules arrived (attribute changes notify `onFlagsChange` subscribers instead). */
|
|
249
|
+
"flags:change": () => void;
|
|
250
|
+
}
|
|
251
|
+
type GuidelyEventName = keyof GuidelyEvents;
|
|
252
|
+
|
|
253
|
+
export { type ChecklistProgressState as C, EventQueue as E, type GuideLocalState as G, type PersistedState as P, type SessionState as S, type ConsentState as a, type EventQueueOptions as b, type GuidelyAccount as c, type GuidelyEnvironment as d, type GuidelyUser as e, areMutuallyExclusive as f, dismissedAfterMerge as g, isFrequencyEligible as h, isExclusiveGuide as i, isWithinSchedule as j, type GuidelyOptions as k, type GuidelyEvents as l, type GuideStepInfo as m, type GuidelyEventName as n };
|
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
import { SdkEvent, PublishedGuide, FrequencyConfig, AutocaptureSettings, NetworkRequest, ProjectTheme, SdkConfigResponse, ChecklistTask, MessengerMessage, MessengerConversation } from '@guidelytech/shared';
|
|
2
|
+
import { b as KeyValueStore, S as StorageKind } from './http-47tiAlOM.cjs';
|
|
3
|
+
import { FlagsClientOptions } from '@guidelytech/flags';
|
|
4
|
+
|
|
5
|
+
interface EventQueueOptions {
|
|
6
|
+
store: KeyValueStore;
|
|
7
|
+
storageKey: string;
|
|
8
|
+
/** Sends one batch. Resolve `{ ok: true }` on success, `{ ok: false, retry }` otherwise. */
|
|
9
|
+
send: (events: SdkEvent[]) => Promise<{
|
|
10
|
+
ok: boolean;
|
|
11
|
+
retry?: boolean;
|
|
12
|
+
}>;
|
|
13
|
+
/** Synchronous best-effort send used on page hide. */
|
|
14
|
+
beacon?: (events: SdkEvent[]) => boolean;
|
|
15
|
+
/** Should events be flushed right now? (analytics enabled + consent granted). */
|
|
16
|
+
enabled: () => boolean;
|
|
17
|
+
flushIntervalMs?: number;
|
|
18
|
+
maxQueue?: number;
|
|
19
|
+
batchSize?: number;
|
|
20
|
+
maxAttempts?: number;
|
|
21
|
+
onError?: (err: unknown) => void;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Bounded, persisted event queue. Batches ≤50 events every 2s (or on demand), dedupes by
|
|
25
|
+
* `eventId`, retries with exponential backoff (1s→30s, 5 attempts) and keeps failed events for
|
|
26
|
+
* the next flush. Drops the oldest events once the queue exceeds 200.
|
|
27
|
+
*/
|
|
28
|
+
declare class EventQueue {
|
|
29
|
+
private readonly opts;
|
|
30
|
+
private events;
|
|
31
|
+
private timer;
|
|
32
|
+
private retryTimer;
|
|
33
|
+
private inflight;
|
|
34
|
+
private inflightIds;
|
|
35
|
+
private attempt;
|
|
36
|
+
private destroyed;
|
|
37
|
+
private readonly flushIntervalMs;
|
|
38
|
+
private readonly maxQueue;
|
|
39
|
+
private readonly batchSize;
|
|
40
|
+
private readonly maxAttempts;
|
|
41
|
+
constructor(opts: EventQueueOptions);
|
|
42
|
+
get size(): number;
|
|
43
|
+
/** Pending events (read-only copy, for debugging). */
|
|
44
|
+
peek(): SdkEvent[];
|
|
45
|
+
enqueue(event: SdkEvent): void;
|
|
46
|
+
private persist;
|
|
47
|
+
private schedule;
|
|
48
|
+
/** Sends queued events now (one batch at a time). Safe to call at any time. */
|
|
49
|
+
flush(): Promise<void>;
|
|
50
|
+
/** Best-effort synchronous flush on unload using `sendBeacon`. */
|
|
51
|
+
flushSync(): void;
|
|
52
|
+
clear(): void;
|
|
53
|
+
destroy(): void;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** Per-guide state kept locally and merged with the server's `IdentifyResponse.guideState`. */
|
|
57
|
+
interface GuideLocalState {
|
|
58
|
+
impressions: number;
|
|
59
|
+
completedAt?: string | null;
|
|
60
|
+
dismissedAt?: string | null;
|
|
61
|
+
lastShownAt?: string | null;
|
|
62
|
+
/** Last step reached in a multi-step flow (local only), so the messenger can offer to resume it. */
|
|
63
|
+
lastStepId?: string | null;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Pure frequency evaluation. `shownThisSession` comes from session storage.
|
|
67
|
+
* - `once`: a single impression ever (unless `reshowAfterDismiss` and it was only dismissed).
|
|
68
|
+
* - `once_per_session`: at most once per browser session.
|
|
69
|
+
* - `every_time`: on every trigger (still blocked by completion/dismissal rules below).
|
|
70
|
+
* - `interval`: at most once every `intervalHours`.
|
|
71
|
+
* `maxImpressions` caps total impressions; dismissal blocks re-showing unless `reshowAfterDismiss`
|
|
72
|
+
* (then `cooldownHours` must have elapsed); completion blocks unless mode is `every_time`.
|
|
73
|
+
*/
|
|
74
|
+
declare function isFrequencyEligible(freq: FrequencyConfig, state: GuideLocalState | undefined, shownThisSession: boolean, now?: number): boolean;
|
|
75
|
+
/**
|
|
76
|
+
* Exclusive guides (flows, modals, tooltips, announcements, surveys) run one at a time.
|
|
77
|
+
* Banners, checklists and hotspot-only tooltips can coexist with an active flow.
|
|
78
|
+
*/
|
|
79
|
+
declare function isExclusiveGuide(guide: PublishedGuide): boolean;
|
|
80
|
+
/** Is `a` mutually exclusive with `b` (by id or key, in either direction)? */
|
|
81
|
+
declare function areMutuallyExclusive(a: PublishedGuide, b: PublishedGuide): boolean;
|
|
82
|
+
/** Survey scheduling window. */
|
|
83
|
+
declare function isWithinSchedule(guide: PublishedGuide, now?: number): boolean;
|
|
84
|
+
/**
|
|
85
|
+
* A checklist's dismissal after merging server state. A local dismissal normally wins (it may not have
|
|
86
|
+
* synced yet), but when the server reports a reset this device hasn't applied, the server's value wins:
|
|
87
|
+
* null, or a dismissal made on another device after the reset. Compared as tokens, not times, so a
|
|
88
|
+
* skewed device clock can't keep a reset dismissal.
|
|
89
|
+
*/
|
|
90
|
+
declare function dismissedAfterMerge(local: {
|
|
91
|
+
dismissedAt?: string | null;
|
|
92
|
+
dismissResetAt?: string | null;
|
|
93
|
+
} | undefined, server: {
|
|
94
|
+
dismissedAt?: string | null;
|
|
95
|
+
dismissResetAt?: string | null;
|
|
96
|
+
}): string | null;
|
|
97
|
+
|
|
98
|
+
type GuidelyEnvironment = "development" | "staging" | "production";
|
|
99
|
+
type ConsentState = "granted" | "denied" | "pending";
|
|
100
|
+
interface GuidelyAccount {
|
|
101
|
+
id: string;
|
|
102
|
+
traits?: Record<string, unknown>;
|
|
103
|
+
}
|
|
104
|
+
interface GuidelyUser {
|
|
105
|
+
id: string;
|
|
106
|
+
traits?: Record<string, unknown>;
|
|
107
|
+
account?: GuidelyAccount;
|
|
108
|
+
}
|
|
109
|
+
interface GuidelyOptions {
|
|
110
|
+
/** Environment public key, e.g. `pk_dev_…`. Not a secret. */
|
|
111
|
+
projectId: string;
|
|
112
|
+
environment?: GuidelyEnvironment;
|
|
113
|
+
/** Base URL of the Guidely API (default `https://api.guidely.app`; use `http://localhost:3000` locally). */
|
|
114
|
+
apiUrl?: string;
|
|
115
|
+
/** Log trigger decisions and requests to the console. */
|
|
116
|
+
debug?: boolean;
|
|
117
|
+
/** Send analytics events (default `true`). Guides still render when disabled. */
|
|
118
|
+
analytics?: boolean;
|
|
119
|
+
/** `pending` buffers events until `setConsent("granted")`; `denied` disables analytics. */
|
|
120
|
+
consent?: ConsentState;
|
|
121
|
+
/** Where to persist identity, cached config and the event queue (default `local`). */
|
|
122
|
+
storage?: StorageKind;
|
|
123
|
+
/** Interval for re-checking element-visibility triggers while the page is idle (default 1000ms). */
|
|
124
|
+
pollIntervalMs?: number;
|
|
125
|
+
/** How often to refresh the published config (default 5 minutes). */
|
|
126
|
+
configRefreshMs?: number;
|
|
127
|
+
/** Elements whose text must never be captured (authoring snapshots, click text, session replays). Merged with the project setting. */
|
|
128
|
+
maskSelectors?: string[];
|
|
129
|
+
/**
|
|
130
|
+
* Page views, page leave, clicks and rage clicks are captured when the project enables them.
|
|
131
|
+
* `false` turns all of them off for this installation; an object turns individual ones off
|
|
132
|
+
* (`{ clicks: false }`). Options can only switch capture off, never on.
|
|
133
|
+
*/
|
|
134
|
+
autocapture?: boolean | Partial<AutocaptureSettings>;
|
|
135
|
+
/** App version or commit SHA (≤100 chars), sent with every `exception` to pick the matching uploaded source maps. */
|
|
136
|
+
release?: string;
|
|
137
|
+
/** `false` stops uncaught errors / unhandled rejections from being reported (`captureException` still works). */
|
|
138
|
+
captureErrors?: boolean;
|
|
139
|
+
/**
|
|
140
|
+
* `false` never records sessions on this installation. An object can only make masking stricter:
|
|
141
|
+
* `maskAllText` masks every text node, `blockSelectors` replaces matching elements with a placeholder.
|
|
142
|
+
*/
|
|
143
|
+
sessionReplay?: boolean | {
|
|
144
|
+
maskAllText?: boolean;
|
|
145
|
+
blockSelectors?: string[];
|
|
146
|
+
/** `false`: never record network requests / WebSockets in replays. */
|
|
147
|
+
recordNetwork?: false;
|
|
148
|
+
/** `false`: never record request/response headers, bodies or WebSocket frame data. */
|
|
149
|
+
recordNetworkPayloads?: false;
|
|
150
|
+
/** Last say over each recorded request (applied after redaction): return a modified copy, or null to drop it. */
|
|
151
|
+
maskNetworkRequest?: (request: NetworkRequest) => NetworkRequest | null;
|
|
152
|
+
};
|
|
153
|
+
onError?: (error: Error) => void;
|
|
154
|
+
/** Overrides for the project theme (colors, radius, font). */
|
|
155
|
+
theme?: Partial<ProjectTheme>;
|
|
156
|
+
/** Identify this user as soon as the client initialises. */
|
|
157
|
+
user?: GuidelyUser;
|
|
158
|
+
/** Custom fetch (tests / polyfills). */
|
|
159
|
+
fetch?: typeof fetch;
|
|
160
|
+
/** Disable the authoring-mode and how-to capture URL parameter detection. */
|
|
161
|
+
disableAuthoring?: boolean;
|
|
162
|
+
/**
|
|
163
|
+
* Feature flags (on by default, same key and API URL). `false` turns them off (getters return
|
|
164
|
+
* fallbacks, nothing is fetched); an object passes options to the flags client, e.g.
|
|
165
|
+
* `{ payload }` to bootstrap from server rendering, `{ attributes }`, `{ remoteEval: true }`,
|
|
166
|
+
* `{ pollingMode: "stream" }`. Identity, page and device attributes are maintained for you.
|
|
167
|
+
*/
|
|
168
|
+
flags?: false | Partial<FlagsClientOptions>;
|
|
169
|
+
}
|
|
170
|
+
interface ChecklistProgressState {
|
|
171
|
+
completedTaskIds: string[];
|
|
172
|
+
completedAt?: string | null;
|
|
173
|
+
dismissedAt?: string | null;
|
|
174
|
+
/** The server's last dismissal reset this device applied (see `dismissedAfterMerge`). */
|
|
175
|
+
dismissResetAt?: string | null;
|
|
176
|
+
}
|
|
177
|
+
/** Everything the client persists per project key (`guidely:state:<key>`). */
|
|
178
|
+
interface PersistedState {
|
|
179
|
+
guides: Record<string, GuideLocalState>;
|
|
180
|
+
checklists: Record<string, ChecklistProgressState>;
|
|
181
|
+
surveysSubmitted: string[];
|
|
182
|
+
audienceIds: string[];
|
|
183
|
+
firstSeenAt?: string;
|
|
184
|
+
}
|
|
185
|
+
interface SessionState {
|
|
186
|
+
id: string;
|
|
187
|
+
startedAt: string;
|
|
188
|
+
shownGuides: string[];
|
|
189
|
+
events: string[];
|
|
190
|
+
/** Epoch ms of the last tracked activity; the session rotates after `sessionTimeoutMinutes` of inactivity. */
|
|
191
|
+
lastActivityAt?: number;
|
|
192
|
+
/** Page views sent in this session (the first one carries the referrer). */
|
|
193
|
+
pageViews?: number;
|
|
194
|
+
/** Exceptions reported in this session (capped at 100). */
|
|
195
|
+
exceptions?: number;
|
|
196
|
+
/** Replay decision for this session: sampled in / forced (`true`), sampled out or disabled by the server (`false`). */
|
|
197
|
+
replay?: boolean;
|
|
198
|
+
}
|
|
199
|
+
interface GuideStepInfo {
|
|
200
|
+
guide: PublishedGuide;
|
|
201
|
+
stepId: string;
|
|
202
|
+
stepIndex: number;
|
|
203
|
+
}
|
|
204
|
+
interface GuidelyEvents {
|
|
205
|
+
/** Config loaded (from network or cache) and triggers evaluated. */
|
|
206
|
+
ready: (config: SdkConfigResponse) => void;
|
|
207
|
+
/** Config (re)loaded. */
|
|
208
|
+
config: (config: SdkConfigResponse) => void;
|
|
209
|
+
"guide:start": (guide: PublishedGuide) => void;
|
|
210
|
+
"guide:step": (info: GuideStepInfo) => void;
|
|
211
|
+
"guide:complete": (guide: PublishedGuide) => void;
|
|
212
|
+
"guide:dismiss": (guide: PublishedGuide) => void;
|
|
213
|
+
"guide:skip": (guide: PublishedGuide) => void;
|
|
214
|
+
"checklist:task": (info: {
|
|
215
|
+
guide: PublishedGuide;
|
|
216
|
+
task: ChecklistTask;
|
|
217
|
+
progress: ChecklistProgressState;
|
|
218
|
+
}) => void;
|
|
219
|
+
"checklist:complete": (guide: PublishedGuide) => void;
|
|
220
|
+
"survey:submit": (info: {
|
|
221
|
+
guide: PublishedGuide;
|
|
222
|
+
answers: Record<string, unknown>;
|
|
223
|
+
responseId: string;
|
|
224
|
+
}) => void;
|
|
225
|
+
"resource-center:open": () => void;
|
|
226
|
+
"messenger:open": () => void;
|
|
227
|
+
/** A Scout or teammate message arrived in the messenger. */
|
|
228
|
+
"conversation:message": (info: {
|
|
229
|
+
message: MessengerMessage;
|
|
230
|
+
conversation: MessengerConversation;
|
|
231
|
+
}) => void;
|
|
232
|
+
error: (error: Error) => void;
|
|
233
|
+
/** Every tracked event (custom and lifecycle). */
|
|
234
|
+
track: (event: SdkEvent) => void;
|
|
235
|
+
identify: (info: {
|
|
236
|
+
userId: string | null;
|
|
237
|
+
anonymousId: string;
|
|
238
|
+
}) => void;
|
|
239
|
+
authoring: (info: {
|
|
240
|
+
active: boolean;
|
|
241
|
+
}) => void;
|
|
242
|
+
/** How-to capture (recording steps for a how-to guide) started or ended in this tab. */
|
|
243
|
+
capture: (info: {
|
|
244
|
+
active: boolean;
|
|
245
|
+
}) => void;
|
|
246
|
+
/** Feature flags loaded (bootstrap, cache or network) — or failed to and serve fallbacks. */
|
|
247
|
+
"flags:ready": () => void;
|
|
248
|
+
/** New flag rules arrived (attribute changes notify `onFlagsChange` subscribers instead). */
|
|
249
|
+
"flags:change": () => void;
|
|
250
|
+
}
|
|
251
|
+
type GuidelyEventName = keyof GuidelyEvents;
|
|
252
|
+
|
|
253
|
+
export { type ChecklistProgressState as C, EventQueue as E, type GuideLocalState as G, type PersistedState as P, type SessionState as S, type ConsentState as a, type EventQueueOptions as b, type GuidelyAccount as c, type GuidelyEnvironment as d, type GuidelyUser as e, areMutuallyExclusive as f, dismissedAfterMerge as g, isFrequencyEligible as h, isExclusiveGuide as i, isWithinSchedule as j, type GuidelyOptions as k, type GuidelyEvents as l, type GuideStepInfo as m, type GuidelyEventName as n };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@guidelytech/sdk-core",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"description": "Framework-independent Guidely browser SDK",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -38,9 +38,9 @@
|
|
|
38
38
|
"@rrweb/record": "^2.1.7",
|
|
39
39
|
"@rrweb/rrweb-plugin-console-record": "^2.1.7",
|
|
40
40
|
"@rrweb/types": "^2.1.7",
|
|
41
|
-
"@guidelytech/guide-runtime": "0.
|
|
42
|
-
"@guidelytech/flags": "0.
|
|
43
|
-
"@guidelytech/shared": "0.
|
|
41
|
+
"@guidelytech/guide-runtime": "0.9.0",
|
|
42
|
+
"@guidelytech/flags": "0.9.0",
|
|
43
|
+
"@guidelytech/shared": "0.9.0"
|
|
44
44
|
},
|
|
45
45
|
"devDependencies": {
|
|
46
46
|
"@eslint/js": "^9.39.5",
|
|
@@ -56,12 +56,12 @@
|
|
|
56
56
|
},
|
|
57
57
|
"repository": {
|
|
58
58
|
"type": "git",
|
|
59
|
-
"url": "git+https://github.com/
|
|
59
|
+
"url": "git+https://github.com/GuidelyTech/Guidely.git",
|
|
60
60
|
"directory": "packages/sdk-core"
|
|
61
61
|
},
|
|
62
|
-
"homepage": "https://github.com/
|
|
62
|
+
"homepage": "https://github.com/GuidelyTech/Guidely/tree/main/packages/sdk-core#readme",
|
|
63
63
|
"bugs": {
|
|
64
|
-
"url": "https://github.com/
|
|
64
|
+
"url": "https://github.com/GuidelyTech/Guidely/issues"
|
|
65
65
|
},
|
|
66
66
|
"keywords": [
|
|
67
67
|
"guidely",
|