@fire-spark/analytics 0.21.1 → 0.23.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 (3) hide show
  1. package/dist/index.d.ts +453 -8
  2. package/dist/index.js +2939 -1375
  3. package/package.json +3 -2
package/dist/index.d.ts CHANGED
@@ -34,6 +34,39 @@ type BuiltinDestinationId = (typeof BUILTIN_DESTINATION_IDS)[number];
34
34
  */
35
35
  type DestinationProviderId = BuiltinDestinationId | (string & {});
36
36
  type AnalyticsRuntime = "web" | "react-native";
37
+ /**
38
+ * Where ads events are delivered. `client` only loads the browser pixels
39
+ * (today's behavior). `server` relays to `serverSide.endpoint` and never
40
+ * loads the pixel scripts. `hybrid` does both with the same `eventId`.
41
+ */
42
+ type AnalyticsDeliveryMode = "client" | "server" | "hybrid";
43
+ /** Routes `meta`, `tiktok` and `google-ads` through a server relay. */
44
+ interface AnalyticsServerSideOptions {
45
+ /** `"/api/track"` (same-origin path) or an `https:` URL. */
46
+ endpoint?: string;
47
+ /**
48
+ * Ads providers routed through the server. Default: the configured ads
49
+ * adapters among `["meta","tiktok","google-ads"]`.
50
+ */
51
+ providers?: ServerProviderId[];
52
+ /** Events per relay request, 1 to 20. Default 10. */
53
+ batchSize?: number;
54
+ /** Batch delay in ms. Default 0. A purchase always flushes at once. */
55
+ flushIntervalMs?: number;
56
+ /** Extra non-secret request headers (for example a CSRF token). */
57
+ headers?: Record<string, string>;
58
+ }
59
+ type AnalyticsConfigErrorCode = "ANALYTICS_SERVER_ENDPOINT_REQUIRED" | "ANALYTICS_SERVER_MODE_UNSUPPORTED_RUNTIME" | "ANALYTICS_INVALID_ENDPOINT" | "ANALYTICS_INVALID_MODE";
60
+ /**
61
+ * Thrown by `resolveDeliveryMode()` for an invalid `mode` / `serverSide`.
62
+ * In development `configure()` lets it throw; in production (`env:
63
+ * "production"`) it is caught, reported through `onWarning` and the client
64
+ * falls back to `mode: "client"` so the storefront never crashes.
65
+ */
66
+ declare class AnalyticsConfigError extends Error {
67
+ readonly code: AnalyticsConfigErrorCode;
68
+ constructor(code: AnalyticsConfigErrorCode, message: string);
69
+ }
37
70
  /** Gate declared by a custom destination. */
38
71
  type AnalyticsConsentCategory = "analytics" | "ads";
39
72
  /**
@@ -50,7 +83,7 @@ type AnalyticsUser = {
50
83
  id?: string | null;
51
84
  properties?: Record<string, string | number | boolean | null>;
52
85
  };
53
- type AnalyticsIssueSource = "configure" | "destination" | "ingest" | "sample" | "track" | "hash";
86
+ type AnalyticsIssueSource = "configure" | "destination" | "ingest" | "relay" | "sample" | "track" | "hash";
54
87
  /** Problem the SDK hit without throwing to the caller. */
55
88
  type AnalyticsIssue = {
56
89
  level: "error" | "warning";
@@ -62,6 +95,47 @@ type AnalyticsIssue = {
62
95
  };
63
96
  /** Host hash for PII. Must return the lowercase hex SHA-256 of `value`. */
64
97
  type AnalyticsHash = (value: string) => string | Promise<string>;
98
+ /** How a hashed `phone` param is written before hashing. */
99
+ type PhoneHashFormat = "e164" | "digits";
100
+ /** Raw personal data for `hashUserData()`. Every field is optional. */
101
+ interface UserDataInput {
102
+ email?: string;
103
+ phone?: string;
104
+ firstName?: string;
105
+ lastName?: string;
106
+ /** Your user id. Hashed the same way as the `external_id` of the pixels. */
107
+ externalId?: string;
108
+ /** ISO 3166-1 alpha-2 of the user. Returned uppercase, never hashed. */
109
+ countryCode?: string;
110
+ }
111
+ interface HashUserDataOptions {
112
+ /** ISO 3166-1 alpha-2 for phones typed without a country code. */
113
+ defaultCountry?: string;
114
+ /** Defaults to `sha256Hex`. */
115
+ hash?: AnalyticsHash;
116
+ }
117
+ /**
118
+ * SHA-256 (lowercase hex) of each normalized field. A field that is missing
119
+ * or invalid (for example a phone that is not a real number) is omitted.
120
+ */
121
+ interface HashedUserData {
122
+ /** `normalizeEmail`: Meta `em`, TikTok `email`. */
123
+ emailSha256?: string;
124
+ /** `normalizeEmailForGoogle`: Google `emailAddress`. */
125
+ emailGoogleSha256?: string;
126
+ /** E.164 with `+`: TikTok `phone`, Google `phoneNumber`. */
127
+ phoneE164Sha256?: string;
128
+ /** E.164 digits without `+`: Meta `ph`. */
129
+ phoneDigitsSha256?: string;
130
+ /** `normalizeExternalId`: Meta and TikTok `external_id`. */
131
+ externalIdSha256?: string;
132
+ /** `normalizeName`: Meta `fn`. */
133
+ firstNameSha256?: string;
134
+ /** `normalizeName`: Meta `ln`. */
135
+ lastNameSha256?: string;
136
+ /** ISO 3166-1 alpha-2, uppercase, not hashed. */
137
+ countryCode?: string;
138
+ }
65
139
  /** Subset of React Native `AppState`. */
66
140
  type AnalyticsAppState = {
67
141
  addEventListener: (type: "change", listener: (state: string) => void) => {
@@ -82,9 +156,16 @@ type NormalizedEvent = {
82
156
  context: Record<string, unknown>;
83
157
  runtime: AnalyticsRuntime;
84
158
  consent: AnalyticsConsent;
85
- /** Same id for every destination of one `track()`, for deduplication. */
159
+ /**
160
+ * Same id for every destination of one `track()`, for deduplication. A
161
+ * `purchase` with an `order_id` uses `purchase:<order_id>`.
162
+ */
86
163
  eventId?: string;
87
- /** Hashed advanced-matching fields (Meta and TikTok). */
164
+ /**
165
+ * Hashed advanced-matching fields. Meta: `em`, `ph` (E.164 digits without
166
+ * `+`), `external_id`. TikTok: `email`, `phone_number` (E.164 with `+`),
167
+ * `external_id`.
168
+ */
88
169
  userData?: Record<string, string>;
89
170
  /** Meta app events `valueToSum` (react-native). */
90
171
  valueToSum?: number;
@@ -114,8 +195,9 @@ interface CustomDestinationIdentity {
114
195
  }
115
196
  /**
116
197
  * Raw tracked event passed to a custom `map`. Catalog renames are not
117
- * applied. `properties` and `items` are already hashed when `consent` is
118
- * `"ads"`.
198
+ * applied. With `consent: "ads"`, `email` and `phone` (E.164 with `+`) in
199
+ * `properties` and `items` are already hashed, an invalid one is omitted,
200
+ * and `device_ip` and `ttclid` stay raw.
119
201
  */
120
202
  interface CustomDestinationInput {
121
203
  name: string;
@@ -123,6 +205,7 @@ interface CustomDestinationInput {
123
205
  items?: Array<Record<string, unknown>>;
124
206
  /** ISO 4217 for this event, or the merchant currency. */
125
207
  currency?: string;
208
+ /** `purchase:<order_id>` for a purchase with an `order_id`. */
126
209
  eventId: string;
127
210
  /** Unix seconds. */
128
211
  eventTime: number;
@@ -268,9 +351,15 @@ type AnalyticsConfigureOptions = {
268
351
  /**
269
352
  * SHA-256 for PII sent to Meta, TikTok and custom `ads` destinations.
270
353
  * Defaults to `crypto.subtle`, or a built-in implementation when it is
271
- * missing (Hermes, insecure web).
354
+ * missing (Hermes, insecure web). It receives the normalized value.
272
355
  */
273
356
  hash?: AnalyticsHash;
357
+ /**
358
+ * ISO 3166-1 alpha-2 used to read a `phone` typed without a country code
359
+ * (for example `"EC"`). Without it, the merchant country from preferences
360
+ * is used. An invalid code is reported and ignored.
361
+ */
362
+ defaultCountry?: string;
274
363
  /** Send the queue once it holds this many events. Default 20. */
275
364
  flushAt?: number;
276
365
  /** Send the queue this long after an event is queued. 0 disables. */
@@ -282,6 +371,14 @@ type AnalyticsConfigureOptions = {
282
371
  flushOnHide?: boolean;
283
372
  /** React Native `AppState`: the queue is sent when the app backgrounds. */
284
373
  appState?: AnalyticsAppState;
374
+ /**
375
+ * Delivery mode for the ads providers. Omitted resolves automatically: an
376
+ * endpoint ⇒ `hybrid` on web, no endpoint ⇒ `client`. See
377
+ * `resolveDeliveryMode`.
378
+ */
379
+ mode?: AnalyticsDeliveryMode;
380
+ /** Server relay for `meta`, `tiktok` and `google-ads`. */
381
+ serverSide?: AnalyticsServerSideOptions;
285
382
  };
286
383
  type AnalyticsConfig = {
287
384
  session: {
@@ -293,6 +390,208 @@ type AnalyticsConfig = {
293
390
  declare const isFunnelEventName: (name: string) => name is FunnelEventName;
294
391
  declare const isInteractionEventName: (name: string) => name is InteractionEventName;
295
392
  //#endregion
393
+ //#region src/contract.types.d.ts
394
+ /** `"12.50"`: matches `/^-?\d+(\.\d+)?$/`, read with Big.js, never rounded. */
395
+ type DecimalString = string;
396
+ /** Lowercase hex SHA-256 (64 characters). */
397
+ type Sha256Hex = string;
398
+ /** Ads platforms the server relays to. Other destinations stay client-side. */
399
+ type ServerProviderId = "meta" | "tiktok" | "google-ads";
400
+ interface TrackingSdkV1 {
401
+ name: string;
402
+ version: string;
403
+ }
404
+ /**
405
+ * Body of `POST {serverSide.endpoint}`, contract version 1. Every wire
406
+ * field is snake_case; the builder maps the camelCase inputs to it.
407
+ */
408
+ interface TrackingEnvelopeV1 {
409
+ v: 1;
410
+ sdk: TrackingSdkV1;
411
+ /** ISO 8601 time the envelope was built. */
412
+ sent_at: string;
413
+ /** 1 to 20 events. */
414
+ events: TrackingEventV1[];
415
+ }
416
+ interface TrackingContextV1 {
417
+ runtime: "web";
418
+ /** BCP 47, for example `es-EC`. */
419
+ locale?: string;
420
+ channel_id: string;
421
+ store_id?: string;
422
+ brand_id?: string;
423
+ fulfillment_id?: string;
424
+ }
425
+ /** Input of `buildTrackingEvent()`; sent as `TrackingContextV1`. */
426
+ interface TrackingContext {
427
+ runtime: "web";
428
+ locale?: string;
429
+ channelId: string;
430
+ storeId?: string;
431
+ brandId?: string;
432
+ fulfillmentId?: string;
433
+ }
434
+ interface TrackingEventV1 {
435
+ /** 1 to 64 of `[A-Za-z0-9:_.-]`. The same id the browser pixels get. */
436
+ event_id: string;
437
+ /** Fire Spark tracked name, for example `purchase`. */
438
+ name: string;
439
+ /** Epoch milliseconds when `track()` was called. */
440
+ timestamp: number;
441
+ /** Page URL (`https:`). */
442
+ source_url: string;
443
+ referrer_url?: string;
444
+ /** Tracked params without personal data, `items`, `value` and `currency`. */
445
+ properties: Record<string, unknown>;
446
+ /** ISO 4217, uppercase. */
447
+ currency?: string;
448
+ value?: DecimalString;
449
+ items?: TrackingItemV1[];
450
+ order_id?: string;
451
+ user: HashedUserDataV1;
452
+ click_ids: ClickIdsV1;
453
+ consent: ConsentV1;
454
+ providers: ServerProviderId[];
455
+ context: TrackingContextV1;
456
+ }
457
+ interface TrackingItemV1 {
458
+ id: string;
459
+ name?: string;
460
+ category?: string;
461
+ brand?: string;
462
+ /** Unit price. */
463
+ price?: DecimalString;
464
+ quantity?: DecimalString;
465
+ }
466
+ /** `hashUserData()` output on the wire: lowercase hex SHA-256 values. */
467
+ interface HashedUserDataV1 {
468
+ email_sha256?: Sha256Hex;
469
+ email_google_sha256?: Sha256Hex;
470
+ phone_e164_sha256?: Sha256Hex;
471
+ phone_digits_sha256?: Sha256Hex;
472
+ external_id_sha256?: Sha256Hex;
473
+ first_name_sha256?: Sha256Hex;
474
+ last_name_sha256?: Sha256Hex;
475
+ /** ISO 3166-1 alpha-2, uppercase. Not hashed. */
476
+ country_code?: string;
477
+ }
478
+ /** Ad click identifiers on the wire, raw (the ads APIs reject hashes). */
479
+ interface ClickIdsV1 {
480
+ fbp?: string;
481
+ fbc?: string;
482
+ ttclid?: string;
483
+ ttp?: string;
484
+ gclid?: string;
485
+ gbraid?: string;
486
+ wbraid?: string;
487
+ google_session_attributes?: string;
488
+ }
489
+ /** What `captureClickIds()` returns; sent as `ClickIdsV1`. */
490
+ interface ClickIds {
491
+ /** Meta `_fbp`: `fb.<subdomainIndex>.<creationTimeMs>.<random>`. */
492
+ fbp?: string;
493
+ /** Meta `_fbc`: `fb.<subdomainIndex>.<creationTimeMs>.<fbclid>`. */
494
+ fbc?: string;
495
+ ttclid?: string;
496
+ /** TikTok `_ttp` cookie. */
497
+ ttp?: string;
498
+ gclid?: string;
499
+ gbraid?: string;
500
+ wbraid?: string;
501
+ /** Google session attributes (base64), passed in by the merchant. */
502
+ googleSessionAttributes?: string;
503
+ }
504
+ interface ConsentV1 {
505
+ ads: boolean;
506
+ /** Google `ad_user_data`. Defaults to `ads`. */
507
+ ad_user_data?: boolean;
508
+ /** Google `ad_personalization`. Defaults to `ads`. */
509
+ ad_personalization?: boolean;
510
+ }
511
+ /** Input of `buildTrackingEvent()`; sent as `ConsentV1`. */
512
+ interface TrackingConsent {
513
+ ads: boolean;
514
+ /** Google `adUserData`. Defaults to `ads`. */
515
+ adUserData?: boolean;
516
+ /** Google `adPersonalization`. Defaults to `ads`. */
517
+ adPersonalization?: boolean;
518
+ }
519
+ type EnvelopeError = "invalid_json" | "invalid_envelope" | "unsupported_contract_version";
520
+ type RejectReason = "invalid_event" | "invalid_event_id" | "invalid_name" | "event_too_old" | "event_in_future" | "invalid_source_url" | "origin_not_allowed" | "invalid_hash" | "invalid_decimal" | "invalid_currency" | "unknown_provider";
521
+ /** One entry of the relay's `rejected` list. */
522
+ interface RejectedEvent {
523
+ event_id?: string;
524
+ reason: RejectReason;
525
+ }
526
+ type EnvelopeValidation = {
527
+ ok: true;
528
+ envelope: TrackingEnvelopeV1;
529
+ rejected: RejectedEvent[];
530
+ } | {
531
+ ok: false;
532
+ error: EnvelopeError;
533
+ };
534
+ interface ValidateEnvelopeOptions {
535
+ /** Epoch ms used for the timestamp window. Defaults to `Date.now()`. */
536
+ now?: number;
537
+ /**
538
+ * Origins (`https://shop.example.com`) a `source_url` may come from.
539
+ * Omitted: any `https:` origin is accepted.
540
+ */
541
+ allowedOrigins?: readonly string[];
542
+ /** Providers the server has configured. Defaults to all of them. */
543
+ providers?: readonly ServerProviderId[];
544
+ /** Accept `http://localhost` source URLs (local development only). */
545
+ allowLocalhost?: boolean;
546
+ }
547
+ /** Input of `buildTrackingEvent()`. */
548
+ interface TrackingEventInput {
549
+ eventId: string;
550
+ name: string;
551
+ /** Epoch ms when `track()` was called. */
552
+ timestamp: number;
553
+ sourceUrl: string;
554
+ referrerUrl?: string;
555
+ /** Raw tracked params. Personal data is removed, never copied. */
556
+ properties?: Record<string, unknown>;
557
+ /** Merchant ISO 4217 code. A valid `properties.currency` wins. */
558
+ currency?: string;
559
+ /** From `hashUserData()`. */
560
+ user?: HashedUserData;
561
+ /** From `captureClickIds()`. */
562
+ clickIds?: ClickIds;
563
+ consent: TrackingConsent;
564
+ providers: ServerProviderId[];
565
+ context: TrackingContext;
566
+ }
567
+ interface ClickIdCaptureOptions {
568
+ /** Nothing is read or stored without ads consent. */
569
+ consent: {
570
+ ads: boolean;
571
+ };
572
+ /** Page URL. Defaults to `location.href`. */
573
+ url?: string;
574
+ /** Cookie string. Defaults to `document.cookie`. */
575
+ cookie?: string;
576
+ /**
577
+ * Keeps click ids from the landing URL for 90 days under `fs_ck_*` keys
578
+ * (for example `localStorage`). Omitted: nothing is stored.
579
+ */
580
+ storage?: AnalyticsStorage;
581
+ /** Epoch ms. Defaults to `Date.now()`. */
582
+ now?: number;
583
+ /** Google session attributes from Google's capture snippet. */
584
+ googleSessionAttributes?: string;
585
+ }
586
+ interface BuildEnvelopeOptions {
587
+ /** Epoch ms for `sent_at`. Defaults to `Date.now()`. */
588
+ now?: number;
589
+ }
590
+ //#endregion
591
+ //#region src/mode.d.ts
592
+ /** The resolved delivery mode. Throws `AnalyticsConfigError` when invalid. */
593
+ declare const resolveDeliveryMode: (options: AnalyticsConfigureOptions) => AnalyticsDeliveryMode;
594
+ //#endregion
296
595
  //#region src/flush.d.ts
297
596
  /** Sends the default instance queue to Fire Spark. */
298
597
  declare const flush: () => Promise<void>;
@@ -382,7 +681,7 @@ declare const customAdapter: (options: CustomAdapterOptions) => CustomAnalyticsA
382
681
  //#endregion
383
682
  //#region src/version.d.ts
384
683
  /** Kept equal to package.json by `pnpm sdk:release` (see version.test.ts). */
385
- declare const SDK_VERSION = "0.21.1";
684
+ declare const SDK_VERSION = "0.23.0";
386
685
  //#endregion
387
686
  //#region src/compact.d.ts
388
687
  /** Drops `undefined`, `null`, non-finite numbers and functions, deeply. */
@@ -400,6 +699,152 @@ declare const hasScript: (prefix: string, exceptId?: string) => boolean;
400
699
  */
401
700
  declare const loadScript: (src: string, id: string) => Promise<void> | null;
402
701
  //#endregion
702
+ //#region src/normalize.d.ts
703
+ /**
704
+ * Lowercase hex SHA-256 of the UTF-8 bytes of `value`: `crypto.subtle`
705
+ * when available, else a built-in implementation (Hermes, insecure web).
706
+ */
707
+ declare const sha256Hex: AnalyticsHash;
708
+ /** Meta and TikTok: trim and lowercase. Not an email → `undefined`. */
709
+ declare const normalizeEmail: (value: string) => string | undefined;
710
+ /**
711
+ * Google only: removes every whitespace and lowercases. For `gmail.com`
712
+ * and `googlemail.com` it also drops the dots and any `+tag` of the local
713
+ * part. Never use it for Meta or TikTok.
714
+ */
715
+ declare const normalizeEmailForGoogle: (value: string) => string | undefined;
716
+ /** ISO 3166-1 alpha-2, uppercase. Anything else → `undefined`. */
717
+ declare const normalizeCountryCode: (value: unknown) => string | undefined;
718
+ /**
719
+ * E.164 with `+` (`+593991234567`). A number without a country code is
720
+ * read in `defaultCountry`. A value that is not a valid phone number →
721
+ * `undefined`: omit it, never hash it.
722
+ */
723
+ declare const normalizePhoneE164: (value: string, defaultCountry?: string) => Promise<string | undefined>;
724
+ /** Meta `ph`: the E.164 digits without `+`. Not E.164 → `undefined`. */
725
+ declare const phoneDigits: (e164: string) => string | undefined;
726
+ /**
727
+ * Meta `fn` / `ln`: lowercase, without punctuation, digits or symbols.
728
+ * Letters keep their accents (UTF-8); inner spaces collapse to one.
729
+ */
730
+ declare const normalizeName: (value: string) => string | undefined;
731
+ /** `external_id`: trim and lowercase, as the user id always was. */
732
+ declare const normalizeExternalId: (value: string) => string | undefined;
733
+ /**
734
+ * Normalizes and hashes each field the way each ads platform expects. One
735
+ * email gives two hashes: `emailSha256` (Meta, TikTok) and
736
+ * `emailGoogleSha256` (Google). One phone gives `phoneE164Sha256` (TikTok,
737
+ * Google) and `phoneDigitsSha256` (Meta).
738
+ */
739
+ declare const hashUserData: (input: UserDataInput, options?: HashUserDataOptions) => Promise<HashedUserData>;
740
+ //#endregion
741
+ //#region src/contract.d.ts
742
+ declare const TRACKING_CONTRACT_VERSION: 1;
743
+ /** Versions a server accepts: the current one and the one before. */
744
+ declare const SUPPORTED_CONTRACT_VERSIONS: readonly [1];
745
+ declare const SERVER_PROVIDER_IDS: readonly ["meta", "tiktok", "google-ads"];
746
+ declare const TRACKING_SDK_NAME = "@fire-spark/analytics";
747
+ declare const MAX_ENVELOPE_EVENTS = 20;
748
+ /** Params never copied into a contract event (raw personal data). */
749
+ declare const CONTRACT_PII_KEYS: readonly ["email", "phone", "first_name", "last_name", "device_ip", "ttclid"];
750
+ /** `hashUserData()` field → its snake_case wire name. */
751
+ declare const HASHED_USER_WIRE_KEYS: {
752
+ readonly emailSha256: "email_sha256";
753
+ readonly emailGoogleSha256: "email_google_sha256";
754
+ readonly phoneE164Sha256: "phone_e164_sha256";
755
+ readonly phoneDigitsSha256: "phone_digits_sha256";
756
+ readonly externalIdSha256: "external_id_sha256";
757
+ readonly firstNameSha256: "first_name_sha256";
758
+ readonly lastNameSha256: "last_name_sha256";
759
+ };
760
+ /** `captureClickIds()` field → its snake_case wire name. */
761
+ declare const CLICK_ID_WIRE_KEYS: {
762
+ readonly fbp: "fbp";
763
+ readonly fbc: "fbc";
764
+ readonly ttclid: "ttclid";
765
+ readonly ttp: "ttp";
766
+ readonly gclid: "gclid";
767
+ readonly gbraid: "gbraid";
768
+ readonly wbraid: "wbraid";
769
+ readonly googleSessionAttributes: "google_session_attributes";
770
+ };
771
+ /** 1 to 64 of `[A-Za-z0-9:_.-]`. */
772
+ declare const isValidEventId: (value: unknown) => value is string;
773
+ /**
774
+ * `purchase:<order_id>`: the event id every destination (Meta pixel,
775
+ * TikTok pixel, the server relay) gets for a purchase, so a reloaded
776
+ * confirmation page is deduplicated instead of counted twice. Returns
777
+ * `undefined` when there is no order id or the result is not a valid
778
+ * event id (longer than 64 characters or with other characters).
779
+ */
780
+ declare const purchaseEventId: (orderId: unknown) => string | undefined;
781
+ declare const isDecimalString: (value: unknown) => value is DecimalString;
782
+ /**
783
+ * Money as a decimal string, never rounded. A decimal string is kept as
784
+ * written (`"25.90"` stays `"25.90"`); a finite number keeps every digit
785
+ * of its shortest representation (`25.9` → `"25.9"`).
786
+ */
787
+ declare const toDecimalString: (value: unknown) => string | undefined;
788
+ /**
789
+ * One contract v1 event from a tracked event. Personal params are
790
+ * dropped (pass hashed user data in `user`), money becomes decimal
791
+ * strings without rounding, and `items` / `value` / `currency` follow the
792
+ * same rules as the browser pixels.
793
+ */
794
+ declare const buildTrackingEvent: (input: TrackingEventInput) => TrackingEventV1;
795
+ /** Wraps 1 to 20 events in a contract v1 envelope. */
796
+ declare const buildTrackingEnvelope: (events: TrackingEventV1[], options?: BuildEnvelopeOptions) => TrackingEnvelopeV1;
797
+ //#endregion
798
+ //#region src/contract.validate.d.ts
799
+ /**
800
+ * Brings an envelope of a supported older version to the current one.
801
+ * Version 1 is current, so it is returned as is.
802
+ */
803
+ declare const upgradeEnvelope: (envelope: Record<string, unknown>) => Record<string, unknown>;
804
+ /**
805
+ * Validates a relay body (a JSON string or a parsed value). A malformed
806
+ * body or an unsupported `v` fails as a whole; otherwise every event is
807
+ * checked on its own and the invalid ones are listed in `rejected`. The
808
+ * returned envelope is a clean copy: unknown fields and personal params
809
+ * (`email`, `phone`, `first_name`, `last_name`, `device_ip`, `ttclid`) are
810
+ * dropped, and `consent.ad_user_data` / `ad_personalization` default to
811
+ * `ads`. Field names are snake_case, as on the wire.
812
+ */
813
+ declare const validateEnvelope: (input: unknown, options?: ValidateEnvelopeOptions) => EnvelopeValidation;
814
+ //#endregion
815
+ //#region src/click-ids.d.ts
816
+ declare const CLICK_ID_STORAGE_PREFIX = "fs_ck_";
817
+ /** Click ids from a landing URL are kept for 90 days. */
818
+ declare const CLICK_ID_TTL_MS: number;
819
+ /** Value of cookie `name` in a `document.cookie` string. */
820
+ declare const readCookie: (cookie: string, name: string) => string | undefined;
821
+ /**
822
+ * Meta `fbc` from a `fbclid` URL param:
823
+ * `fb.<subdomainIndex>.<creationTimeMs>.<fbclid>`. The fbclid keeps its
824
+ * case.
825
+ */
826
+ declare const fbcFromFbclid: (fbclid: string, creationTimeMs: number, subdomainIndex?: number) => string;
827
+ /** The gclid inside a Google `_gcl_aw` cookie (`GCL.<time>.<gclid>`). */
828
+ declare const gclidFromGclAw: (value: string) => string | undefined;
829
+ /** `fbclid`, `ttclid`, `gclid`, `gbraid` and `wbraid` of a URL. */
830
+ declare const parseClickIdParams: (url: string) => Partial<Record<"fbclid" | "gbraid" | "gclid" | "ttclid" | "wbraid", string>>;
831
+ /**
832
+ * Reads ad click ids for the server relay. Without ads consent it returns
833
+ * `{}` and reads or writes nothing.
834
+ *
835
+ * - `fbc`: a `fbclid` in the URL, else the `_fbc` cookie, else storage.
836
+ * - `fbp`: the `_fbp` cookie set by the Meta pixel.
837
+ * - `ttclid`, `gbraid`, `wbraid`: the URL, else storage.
838
+ * - `ttp`: the `_ttp` cookie set by the TikTok pixel (read only).
839
+ * - `gclid`: the URL, else the `_gcl_aw` cookie, else storage.
840
+ *
841
+ * With `storage`, ids found in the URL are kept for 90 days under
842
+ * `fs_ck_*` keys so a later page (the checkout) still has them.
843
+ */
844
+ declare const captureClickIds: (options: ClickIdCaptureOptions) => Promise<ClickIds>;
845
+ /** Removes the `fs_ck_*` entries, for example when ads consent is revoked. */
846
+ declare const clearClickIds: (storage: AnalyticsStorage) => Promise<void>;
847
+ //#endregion
403
848
  //#region src/index.d.ts
404
849
  type TrackName = (name: string, params?: Record<string, unknown>, opts?: TrackOptions) => Promise<void>;
405
850
  type TrackAlias = (event: TrackEvent) => Promise<void>;
@@ -447,4 +892,4 @@ declare const analytics: {
447
892
  setConsent: typeof setConsent;
448
893
  };
449
894
  //#endregion
450
- export { Analytics, type AnalyticsAdapter, type AnalyticsAppState, type AnalyticsConfig, type AnalyticsConfigureOptions, type AnalyticsConsent, type AnalyticsConsentCategory, type AnalyticsContext, type AnalyticsCustomer, type AnalyticsDestination, type AnalyticsHash, type AnalyticsIssue, type AnalyticsIssueSource, type AnalyticsPlatform, type AnalyticsRuntime, type AnalyticsSampleOptions, type AnalyticsScope, type AnalyticsStorage, type AnalyticsUser, BUILTIN_DESTINATION_IDS, type BuiltinDestinationId, type CustomAdapterOptions, type CustomAnalyticsAdapter, type CustomDestinationEvent, type CustomDestinationIdentity, type CustomDestinationInput, type CustomDestinationMap, type CustomRevenue, 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, customAdapter, endSession, flush, hasScript, isFunnelEventName, isInteractionEventName, loadScript, reset, setConsent, setUser, track };
895
+ export { Analytics, type AnalyticsAdapter, type AnalyticsAppState, type AnalyticsConfig, AnalyticsConfigError, type AnalyticsConfigErrorCode, type AnalyticsConfigureOptions, type AnalyticsConsent, type AnalyticsConsentCategory, type AnalyticsContext, type AnalyticsCustomer, type AnalyticsDeliveryMode, type AnalyticsDestination, type AnalyticsHash, type AnalyticsIssue, type AnalyticsIssueSource, type AnalyticsPlatform, type AnalyticsRuntime, type AnalyticsSampleOptions, type AnalyticsScope, type AnalyticsServerSideOptions, type AnalyticsStorage, type AnalyticsUser, BUILTIN_DESTINATION_IDS, type BuildEnvelopeOptions, type BuiltinDestinationId, CLICK_ID_STORAGE_PREFIX, CLICK_ID_TTL_MS, CLICK_ID_WIRE_KEYS, CONTRACT_PII_KEYS, type ClickIdCaptureOptions, type ClickIds, type ClickIdsV1, type ConsentV1, type CustomAdapterOptions, type CustomAnalyticsAdapter, type CustomDestinationEvent, type CustomDestinationIdentity, type CustomDestinationInput, type CustomDestinationMap, type CustomRevenue, type DecimalString, type DestinationProviderId, type EnvelopeError, type EnvelopeValidation, FUNNEL_EVENTS, type FunnelEventName, HASHED_USER_WIRE_KEYS, type HashUserDataOptions, type HashedUserData, type HashedUserDataV1, INTERACTION_EVENTS, type InteractionEventName, MAX_ENVELOPE_EVENTS, type NormalizedEvent, type PhoneHashFormat, type RejectReason, type RejectedEvent, SDK_VERSION, SERVER_PROVIDER_IDS, SUPPORTED_CONTRACT_VERSIONS, type ServerProviderId, type Sha256Hex, TRACKING_CONTRACT_VERSION, TRACKING_SDK_NAME, type TrackOptions as TrackCallOptions, type TrackOptions, type TrackEvent, type TrackingConsent, type TrackingContext, type TrackingContextV1, type TrackingEnvelopeV1, type TrackingEventInput, type TrackingEventV1, type TrackingItemV1, type TrackingSdkV1, type UserDataInput, type ValidateEnvelopeOptions, analytics, buildTrackingEnvelope, buildTrackingEvent, captureClickIds, clearClickIds, compactPayload, configure, customAdapter, endSession, fbcFromFbclid, flush, gclidFromGclAw, hasScript, hashUserData, isDecimalString, isFunnelEventName, isInteractionEventName, isValidEventId, loadScript, normalizeCountryCode, normalizeEmail, normalizeEmailForGoogle, normalizeExternalId, normalizeName, normalizePhoneE164, parseClickIdParams, phoneDigits, purchaseEventId, readCookie, reset, resolveDeliveryMode, setConsent, setUser, sha256Hex, toDecimalString, track, upgradeEnvelope, validateEnvelope };