@fire-spark/analytics 0.18.0 → 0.19.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,34 @@
1
+ # @fire-spark/analytics
2
+
3
+ Sends events to Fire Spark and to the GA4, Meta, TikTok and Masivo adapters.
4
+
5
+ ```typescript
6
+ import { analytics } from "@fire-spark/analytics";
7
+ import { ga4 } from "@fire-spark/analytics-ga4";
8
+
9
+ await analytics.configure({
10
+ channel_id: "web",
11
+ platform: "web",
12
+ storage: window.localStorage,
13
+ getCustomer: () => session.customer,
14
+ adapters: [ga4({ measurementId: "G-XXXXXXX" })],
15
+ onError: issue => console.error(issue)
16
+ });
17
+
18
+ await analytics.track("add_to_cart", { product_id: "p1", quantity: 1 });
19
+ ```
20
+
21
+ Behavior to know before you integrate:
22
+
23
+ - Calls to `track()` before `configure()` are kept and sent once it runs.
24
+ - Fire Spark stores funnel and interaction events and any event sent as
25
+ `track({ name, properties })`. `track("name", params)` with another name
26
+ only reaches the destinations (by design).
27
+ - Fire Spark keeps one event per funnel step per session; destinations
28
+ receive every occurrence.
29
+ - The queue is sent on its own (`flushAt`, `flushIntervalMs`, page hide on
30
+ web, `appState` in React Native).
31
+ - Destination failures go to `onError`; `track()` never rejects for them.
32
+ - `setUser()` and `setConsent()` reach every destination.
33
+
34
+ Guide: https://firespark.cloud/docs/guides/analytics/use-analytics-in-the-sdk
package/dist/index.d.ts CHANGED
@@ -28,26 +28,69 @@ type AnalyticsScope = {
28
28
  };
29
29
  type DestinationProviderId = "ga4" | "meta" | "masivo" | "tiktok";
30
30
  type AnalyticsRuntime = "web" | "react-native";
31
+ /**
32
+ * `analytics` gates GA4 and Masivo; `ads` gates Meta and TikTok. Fire Spark
33
+ * ingest is first-party and is not gated.
34
+ */
31
35
  type AnalyticsConsent = {
32
36
  analytics: boolean;
33
37
  ads: boolean;
34
38
  };
39
+ /** User identity forwarded to destinations. `id: null` clears it. */
40
+ type AnalyticsUser = {
41
+ id?: string | null;
42
+ properties?: Record<string, string | number | boolean | null>;
43
+ };
44
+ type AnalyticsIssueSource = "configure" | "destination" | "ingest" | "sample" | "track" | "hash";
45
+ /** Problem the SDK hit without throwing to the caller. */
46
+ type AnalyticsIssue = {
47
+ level: "error" | "warning";
48
+ source: AnalyticsIssueSource;
49
+ message: string;
50
+ error?: unknown;
51
+ provider?: DestinationProviderId;
52
+ event?: string;
53
+ };
54
+ /** Host hash for PII. Must return the lowercase hex SHA-256 of `value`. */
55
+ type AnalyticsHash = (value: string) => string | Promise<string>;
56
+ /** Subset of React Native `AppState`. */
57
+ type AnalyticsAppState = {
58
+ addEventListener: (type: "change", listener: (state: string) => void) => {
59
+ remove: () => void;
60
+ } | undefined | void;
61
+ };
35
62
  type AnalyticsSampleOptions = {
36
63
  firstPerEvent?: boolean;
37
64
  rate?: number;
38
65
  };
39
66
  type NormalizedEvent = {
67
+ /** Destination event name (catalog binding, or the tracked name). */
40
68
  name: string;
69
+ /** Destination payload: catalog params merged with the provider fields. */
41
70
  params: Record<string, unknown>;
42
71
  items?: Array<Record<string, unknown>>;
43
72
  userProperties?: Record<string, unknown>;
44
73
  context: Record<string, unknown>;
45
74
  runtime: AnalyticsRuntime;
46
75
  consent: AnalyticsConsent;
76
+ /** Same id for every destination of one `track()`, for deduplication. */
77
+ eventId?: string;
78
+ /** Hashed advanced-matching fields (Meta and TikTok). */
79
+ userData?: Record<string, string>;
80
+ /** Meta app events `valueToSum` (react-native). */
81
+ valueToSum?: number;
82
+ /**
83
+ * Current user. Ads providers (Meta, TikTok) receive the SHA-256 of `id`.
84
+ */
85
+ user?: AnalyticsUser;
47
86
  };
48
87
  type AnalyticsAdapter = {
49
88
  provider: DestinationProviderId;
50
89
  send: (event: NormalizedEvent) => Promise<void> | void;
90
+ /** Called by `setUser()`. Ads providers receive the SHA-256 of `id`. */
91
+ setUser?: (user: AnalyticsUser, runtime: AnalyticsRuntime) => Promise<void> | void;
92
+ /** Called by `setConsent()`, also when consent is revoked. */
93
+ setConsent?: (consent: AnalyticsConsent, runtime: AnalyticsRuntime) => Promise<void> | void;
51
94
  };
52
95
  type TrackOptions = {
53
96
  only?: DestinationProviderId[];
@@ -114,6 +157,8 @@ type AnalyticsLimits = {
114
157
  type AnalyticsMerchantContext = () => Record<string, unknown>;
115
158
  type AnalyticsConfigureOptions = {
116
159
  baseUrl?: string;
160
+ /** Storage key prefix. Use a different one per `Analytics` instance. */
161
+ storagePrefix?: string;
117
162
  getAccessToken?: () => Promise<string>;
118
163
  storage: AnalyticsStorage;
119
164
  getCustomer: () => AnalyticsCustomer | null;
@@ -126,13 +171,38 @@ type AnalyticsConfigureOptions = {
126
171
  limits?: AnalyticsLimits;
127
172
  fetchImpl?: typeof fetch;
128
173
  sessionMs?: number;
174
+ /**
175
+ * ISO 4217 code. An invalid code is reported and ignored; the merchant
176
+ * currency from preferences is used instead.
177
+ */
129
178
  currency?: string;
130
179
  adapters?: AnalyticsAdapter[];
131
180
  env?: "production" | "staging";
132
181
  planVersionId?: string;
182
+ /** Read on every event unless `setConsent()` was called. */
133
183
  consent?: () => AnalyticsConsent;
134
184
  sample?: AnalyticsSampleOptions;
135
185
  runtime?: AnalyticsRuntime;
186
+ /** Errors (destination failures, dropped events). Default `console.error`. */
187
+ onError?: (issue: AnalyticsIssue) => void;
188
+ /** Recoverable problems. Default `console.warn`. */
189
+ onWarning?: (issue: AnalyticsIssue) => void;
190
+ /**
191
+ * SHA-256 for PII sent to Meta and TikTok. Defaults to `crypto.subtle`,
192
+ * or a built-in implementation when it is missing (Hermes, insecure web).
193
+ */
194
+ hash?: AnalyticsHash;
195
+ /** Send the queue once it holds this many events. Default 20. */
196
+ flushAt?: number;
197
+ /** Send the queue this long after an event is queued. 0 disables. */
198
+ flushIntervalMs?: number;
199
+ /**
200
+ * Send the queue when the page is hidden (`visibilitychange`,
201
+ * `pagehide`, with `keepalive`). Default true on web.
202
+ */
203
+ flushOnHide?: boolean;
204
+ /** React Native `AppState`: the queue is sent when the app backgrounds. */
205
+ appState?: AnalyticsAppState;
136
206
  };
137
207
  type AnalyticsConfig = {
138
208
  session: {
@@ -145,24 +215,65 @@ declare const isFunnelEventName: (name: string) => name is FunnelEventName;
145
215
  declare const isInteractionEventName: (name: string) => name is InteractionEventName;
146
216
  //#endregion
147
217
  //#region src/flush.d.ts
218
+ /** Sends the default instance queue to Fire Spark. */
148
219
  declare const flush: () => Promise<void>;
149
220
  //#endregion
221
+ //#region src/version.d.ts
222
+ /** Kept equal to package.json by `pnpm sdk:release` (see version.test.ts). */
223
+ declare const SDK_VERSION = "0.19.1";
224
+ //#endregion
225
+ //#region src/compact.d.ts
226
+ /** Drops `undefined`, `null`, non-finite numbers and functions, deeply. */
227
+ declare const compactPayload: (value: Record<string, unknown>) => Record<string, unknown>;
228
+ //#endregion
229
+ //#region src/script.d.ts
230
+ /**
231
+ * True when the page has a `<script>` whose `src` starts with `prefix`,
232
+ * ignoring the one with id `exceptId` (the adapter's own).
233
+ */
234
+ declare const hasScript: (prefix: string, exceptId?: string) => boolean;
235
+ /**
236
+ * Injects `src` once per page. A failed script is removed and forgotten, so
237
+ * the next call retries. Returns null outside a browser.
238
+ */
239
+ declare const loadScript: (src: string, id: string) => Promise<void> | null;
240
+ //#endregion
150
241
  //#region src/index.d.ts
151
- declare const configure: (options: AnalyticsConfigureOptions) => Promise<void>;
152
242
  type TrackName = (name: string, params?: Record<string, unknown>, opts?: TrackOptions) => Promise<void>;
153
243
  type TrackAlias = (event: TrackEvent) => Promise<void>;
154
244
  type TrackEither = (nameOrEvent: string | TrackEvent, params?: Record<string, unknown>, opts?: TrackOptions) => Promise<void>;
245
+ /**
246
+ * Both forms reach the destinations. Fire Spark stores funnel and
247
+ * interaction events, and any event sent with the object form
248
+ * `track({ name, properties })`; `track("name", params)` with another name
249
+ * is not stored (by design). Calls before `configure()` are kept and sent
250
+ * once it runs.
251
+ */
155
252
  type TrackFn = TrackName & TrackAlias & TrackEither;
253
+ declare const configure: (options: AnalyticsConfigureOptions) => Promise<void>;
156
254
  declare const track: TrackFn;
157
255
  declare const endSession: () => Promise<void>;
158
256
  declare const reset: () => Promise<void>;
257
+ /** User for destinations (GA4 user_id, Meta/TikTok external_id). */
258
+ declare const setUser: (user: AnalyticsUser | null) => Promise<void>;
259
+ /** Updates consent and propagates it to every destination. */
260
+ declare const setConsent: (consent: AnalyticsConsent) => Promise<void>;
261
+ /**
262
+ * Independent analytics client: its own queue, session, timers and
263
+ * adapters. The module-level functions use a shared default instance.
264
+ */
159
265
  declare class Analytics {
266
+ #private;
267
+ /** Settles when the constructor `configure()` finishes. */
268
+ readonly ready: Promise<void>;
160
269
  constructor(options?: AnalyticsConfigureOptions);
161
- configure: typeof configure;
270
+ configure: (options: AnalyticsConfigureOptions) => Promise<void>;
162
271
  track: TrackFn;
163
- flush: typeof flush;
164
- endSession: typeof endSession;
165
- reset: typeof reset;
272
+ flush: () => Promise<void>;
273
+ endSession: () => Promise<void>;
274
+ reset: () => Promise<void>;
275
+ setUser: (user: AnalyticsUser | null) => Promise<void>;
276
+ setConsent: (consent: AnalyticsConsent) => Promise<void>;
166
277
  }
167
278
  declare const analytics: {
168
279
  configure: typeof configure;
@@ -170,6 +281,8 @@ declare const analytics: {
170
281
  flush: typeof flush;
171
282
  endSession: typeof endSession;
172
283
  reset: typeof reset;
284
+ setUser: typeof setUser;
285
+ setConsent: typeof setConsent;
173
286
  };
174
287
  //#endregion
175
- export { Analytics, type AnalyticsAdapter, type AnalyticsConfig, type AnalyticsConfigureOptions, type AnalyticsConsent, type AnalyticsContext, type AnalyticsCustomer, type AnalyticsPlatform, type AnalyticsRuntime, type AnalyticsSampleOptions, type AnalyticsScope, type AnalyticsStorage, type DestinationProviderId, FUNNEL_EVENTS, type FunnelEventName, INTERACTION_EVENTS, type InteractionEventName, type NormalizedEvent, type TrackOptions as TrackCallOptions, type TrackOptions, type TrackEvent, analytics, configure, endSession, flush, isFunnelEventName, isInteractionEventName, reset, track };
288
+ export { Analytics, type AnalyticsAdapter, type AnalyticsAppState, type AnalyticsConfig, type AnalyticsConfigureOptions, type AnalyticsConsent, type AnalyticsContext, type AnalyticsCustomer, type AnalyticsHash, type AnalyticsIssue, type AnalyticsIssueSource, type AnalyticsPlatform, type AnalyticsRuntime, type AnalyticsSampleOptions, type AnalyticsScope, type AnalyticsStorage, type AnalyticsUser, type DestinationProviderId, FUNNEL_EVENTS, type FunnelEventName, INTERACTION_EVENTS, type InteractionEventName, type NormalizedEvent, SDK_VERSION, type TrackOptions as TrackCallOptions, type TrackOptions, type TrackEvent, analytics, compactPayload, configure, endSession, flush, hasScript, isFunnelEventName, isInteractionEventName, loadScript, reset, setConsent, setUser, track };