@shware/analytics 12.0.0 → 12.2.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 (76) hide show
  1. package/README.md +63 -1
  2. package/dist/index.d.cts +2 -2
  3. package/dist/index.d.mts +2 -2
  4. package/dist/native/firebase.cjs +7 -1
  5. package/dist/native/firebase.cjs.map +1 -1
  6. package/dist/native/firebase.d.cts +7 -1
  7. package/dist/native/firebase.d.cts.map +1 -1
  8. package/dist/native/firebase.d.mts +7 -1
  9. package/dist/native/firebase.d.mts.map +1 -1
  10. package/dist/native/firebase.mjs +7 -1
  11. package/dist/native/firebase.mjs.map +1 -1
  12. package/dist/schema/index.cjs +10 -2
  13. package/dist/schema/index.cjs.map +1 -1
  14. package/dist/schema/index.d.cts +3 -0
  15. package/dist/schema/index.d.cts.map +1 -1
  16. package/dist/schema/index.d.mts +3 -0
  17. package/dist/schema/index.d.mts.map +1 -1
  18. package/dist/schema/index.mjs +10 -2
  19. package/dist/schema/index.mjs.map +1 -1
  20. package/dist/third-parties/google-analytics.cjs +1 -1
  21. package/dist/third-parties/google-analytics.cjs.map +1 -1
  22. package/dist/third-parties/google-analytics.d.cts +1 -1
  23. package/dist/third-parties/google-analytics.d.mts +1 -1
  24. package/dist/third-parties/google-analytics.mjs +1 -1
  25. package/dist/third-parties/google-analytics.mjs.map +1 -1
  26. package/dist/third-parties/linkedin-insight-tag.cjs +1 -1
  27. package/dist/third-parties/linkedin-insight-tag.cjs.map +1 -1
  28. package/dist/third-parties/linkedin-insight-tag.d.cts +1 -1
  29. package/dist/third-parties/linkedin-insight-tag.d.mts +1 -1
  30. package/dist/third-parties/linkedin-insight-tag.mjs +1 -1
  31. package/dist/third-parties/linkedin-insight-tag.mjs.map +1 -1
  32. package/dist/third-parties/meta-pixel.cjs +1 -1
  33. package/dist/third-parties/meta-pixel.cjs.map +1 -1
  34. package/dist/third-parties/meta-pixel.d.cts +1 -1
  35. package/dist/third-parties/meta-pixel.d.mts +1 -1
  36. package/dist/third-parties/meta-pixel.mjs +1 -1
  37. package/dist/third-parties/meta-pixel.mjs.map +1 -1
  38. package/dist/third-parties/microsoft-uet.cjs +1 -1
  39. package/dist/third-parties/microsoft-uet.cjs.map +1 -1
  40. package/dist/third-parties/microsoft-uet.d.cts +1 -1
  41. package/dist/third-parties/microsoft-uet.d.mts +1 -1
  42. package/dist/third-parties/microsoft-uet.mjs +1 -1
  43. package/dist/third-parties/microsoft-uet.mjs.map +1 -1
  44. package/dist/third-parties/openai-pixel.cjs +1 -1
  45. package/dist/third-parties/openai-pixel.cjs.map +1 -1
  46. package/dist/third-parties/openai-pixel.d.cts +1 -1
  47. package/dist/third-parties/openai-pixel.d.mts +1 -1
  48. package/dist/third-parties/openai-pixel.mjs +1 -1
  49. package/dist/third-parties/openai-pixel.mjs.map +1 -1
  50. package/dist/third-parties/reddit-pixel.cjs +1 -1
  51. package/dist/third-parties/reddit-pixel.cjs.map +1 -1
  52. package/dist/third-parties/reddit-pixel.d.cts +1 -1
  53. package/dist/third-parties/reddit-pixel.d.mts +1 -1
  54. package/dist/third-parties/reddit-pixel.mjs +1 -1
  55. package/dist/third-parties/reddit-pixel.mjs.map +1 -1
  56. package/dist/track/index.cjs +77 -42
  57. package/dist/track/index.cjs.map +1 -1
  58. package/dist/track/index.d.cts +28 -4
  59. package/dist/track/index.d.cts.map +1 -1
  60. package/dist/track/index.d.mts +28 -4
  61. package/dist/track/index.d.mts.map +1 -1
  62. package/dist/track/index.mjs +77 -43
  63. package/dist/track/index.mjs.map +1 -1
  64. package/dist/track/once.cjs +65 -17
  65. package/dist/track/once.cjs.map +1 -1
  66. package/dist/track/once.d.cts +5 -4
  67. package/dist/track/once.d.cts.map +1 -1
  68. package/dist/track/once.d.mts +5 -4
  69. package/dist/track/once.d.mts.map +1 -1
  70. package/dist/track/once.mjs +66 -18
  71. package/dist/track/once.mjs.map +1 -1
  72. package/dist/track/types.d.cts +58 -5
  73. package/dist/track/types.d.cts.map +1 -1
  74. package/dist/track/types.d.mts +58 -5
  75. package/dist/track/types.d.mts.map +1 -1
  76. package/package.json +2 -2
@@ -2,14 +2,50 @@ import { StandardEvents, UserProvidedData as UserProvidedData$1 } from "./gtag.m
2
2
  //#region src/track/types.d.ts
3
3
  export type AllowedPropertyValues = string | number | boolean | null;
4
4
  export type EventName = Lowercase<string> | 'CLS' | 'FCP' | 'INP' | 'LCP' | 'TTFB';
5
- export type TrackName<T extends EventName = EventName> = T extends keyof StandardEvents ? T : EventName;
5
+ /**
6
+ * Type-level switches an application turns on by declaration merging, the way it fills
7
+ * `CustomEventProperties` — usually in the same file:
8
+ *
9
+ * ```ts
10
+ * declare module '@shware/analytics' {
11
+ * interface AnalyticsOptions {
12
+ * strict: true;
13
+ * }
14
+ * }
15
+ * ```
16
+ *
17
+ * - `strict: true` — strict events: every function that takes an event name (`track`, `trackOnce`,
18
+ * `trackAsync`, `sendBeacon`, `useTrackImpression`, the third-party senders) accepts only
19
+ * GA4's standard events and the events declared in `CustomEventProperties`: a misspelled or
20
+ * undeclared name (`'purchse'`, `'begin_checkout '`) is a compile error instead of a new event.
21
+ *
22
+ * Empty by default, so nothing changes for an application that never merges into it.
23
+ */
24
+ export interface AnalyticsOptions {}
25
+ /** Whether the application turned on `AnalyticsOptions['strict']`. */
26
+ type Strict = AnalyticsOptions extends {
27
+ strict: true;
28
+ } ? true : false;
29
+ /**
30
+ * The names `track` accepts with `strict` on: GA4's standard events and the events
31
+ * the application declared. Only declared keys that are themselves valid event names, so the
32
+ * set stays within `EventName`.
33
+ */
34
+ export type DeclaredEventName = keyof StandardEvents | Extract<keyof CustomEventProperties, EventName>;
35
+ /**
36
+ * The type of an event-name parameter. `T` is inferred from the argument through both branches;
37
+ * the false branch is what the argument is checked against when it is not a known event — any
38
+ * event name by default, only a declared one with `strict` on.
39
+ */
40
+ export type TrackName<T extends EventName = EventName> = Strict extends true ? T extends DeclaredEventName ? T : DeclaredEventName : T extends keyof StandardEvents ? T : EventName;
6
41
  /**
7
42
  * Properties an application defines for its own events, keyed by event name.
8
43
  *
9
44
  * Empty here on purpose. Applications fill it by declaration merging, and it does two jobs:
10
45
  * it adds custom properties to GA4's standard events, which are otherwise closed shapes and
11
46
  * would need a cast; and it gives an application's own events a real type instead of the
12
- * open record they fall back to.
47
+ * open record they fall back to. With `AnalyticsOptions['strict']` on, it is also the
48
+ * list of the custom event names `track` accepts.
13
49
  *
14
50
  * ```ts
15
51
  * declare module '@shware/analytics' {
@@ -37,7 +73,7 @@ export interface CustomEventProperties {}
37
73
  * no declaration intersects to exactly the type it had before.
38
74
  */
39
75
  type CustomPropertiesFor<T> = T extends keyof CustomEventProperties ? CustomEventProperties[T] : unknown;
40
- export type TrackProperties<T extends EventName = EventName> = T extends keyof StandardEvents ? StandardEvents[T] & CustomPropertiesFor<T> : T extends keyof CustomEventProperties ? CustomEventProperties[T] : Record<Lowercase<string>, AllowedPropertyValues>;
76
+ export type TrackProperties<T extends EventName = EventName> = T extends keyof StandardEvents ? StandardEvents[T] & CustomPropertiesFor<T> : T extends keyof CustomEventProperties ? CustomEventProperties[T] : Strict extends true ? never : Record<Lowercase<string>, AllowedPropertyValues>;
41
77
  export type Platform = 'ios' | 'android' | 'web' | 'macos' | 'windows' | 'linux' | 'unknown';
42
78
  export type Environment = 'development' | 'production';
43
79
  export interface UserData {
@@ -66,7 +102,16 @@ export interface UserProvidedData extends UserProvidedData$1 {
66
102
  fb_login_id?: string;
67
103
  fb_page_id?: string;
68
104
  }
69
- export type ThirdPartyTracker = <T extends EventName>(name: TrackName<T>, properties?: TrackProperties<T>, event_id?: string) => void;
105
+ /**
106
+ * A browser pixel or app SDK an event is forwarded to. Called synchronously when the event is
107
+ * tracked, before it is sent, with `event_id` — the client-generated id the event is stored and
108
+ * sent to the conversions APIs under — as the platform's deduplication id.
109
+ *
110
+ * Returning `false` means "not ready": the pixel's global (`fbq`, `rdt`, `gtag`, …) is not on the
111
+ * page yet, its snippet still loading. The SDK then calls the tracker once more, with the same
112
+ * event and id, on the next macrotask. Any other return value (`void` included) is a handled call.
113
+ */
114
+ export type ThirdPartyTracker = <T extends EventName>(name: TrackName<T>, properties?: TrackProperties<T>, event_id?: string) => void | boolean;
70
115
  export interface PlatformInfo {
71
116
  os?: string;
72
117
  os_name?: string;
@@ -263,8 +308,16 @@ export interface TrackEvent<T extends EventName = EventName> {
263
308
  properties?: TrackProperties<T>;
264
309
  created_at: string;
265
310
  }
311
+ /**
312
+ * What `POST /events` answers: one `{ id }` per event, in the order sent.
313
+ *
314
+ * Since 12.1 the client generates each event's id and sends it in the DTO; the SDK no longer
315
+ * reads this answer, and `onSucceed` reports the client's id. Servers keep answering it for
316
+ * clients before 12.1, which fire their pixels with the id found here. To be removed in the next
317
+ * major.
318
+ */
266
319
  export type TrackEventResponse = {
267
- /** track event id: Meta Pixel will use event_id and event_name for deduplication */
320
+ /** The event's id, the one the pixels and the conversions APIs deduplicate on. */
268
321
  id: string;
269
322
  }[];
270
323
  //#endregion
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.mts","names":["GAUserProvidedData"],"sources":["../../src/track/types.ts"],"mappings":";;YAEY;YACA,YAAY;YAEZ,UAAU,UAAU,YAAY,aAAa,gBAAgB,iBACrE,IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+Ba;;;;;;;KAQZ,oBAAoB,KAAK,gBAAgB,wBAC1C,sBAAsB;YAGd,gBAAgB,UAAU,YAAY,aAAa,gBAAgB,iBAC3E,eAAe,KAAK,oBAAoB,KACxC,gBAAgB,wBACd,sBAAsB,KACtB,OAAO,mBAAmB;YAEpB;YACA;iBAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;iBAGe,yBAAyBA;EACxC;EACA;EACA;EACA;EACA;IAAa;IAAc;IAAe;;EAE1C;EACA;;YAGU,qBAAqB,UAAU,WACzC,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;iBAGe;;EAEf;EACA;;iBAGe;EACf;EACA;EACA;;;;;;;;;;iBAWe;EACf;EACA;EACA;;;;;;;EAOA;;;;;;EAMA;;;;;;;;;;;;;iBAce;EAEf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;EAMA;;EAEA;;EAEA;;EAEA;EAEA;EACA;EACA;EACA;;;;;;;;EAQA;;;;;;EAMA;EACA;EACA;EACA;;EAEA;;EAEA;EAEA;;EAEA;EAEA;;EAEA;;EAEA;;EAEA;EAEA;;;;;EAKA;EAEA;;EAEA;;EAEA;EAEA;EACA;EACA;EACA;EACA;EACA;;;;;;;iBAQe;;EAEf;;;;;;;;;;;;EAqCA;;;;;;EAuDA;;EAMA;;EAEA;;EAEA;;EAEA;;EAUA;;EAEA;;iBAGe,kBACP,cAAc,YAAY,SAAS,iBAAiB,UAAU,iBAAiB;EACvF;GACC;;iBAGc,WAAW,UAAU,YAAY;EAChD;EACA,MAAM,UAAU;EAChB,MAAM;EACN;EACA;EACA,UAAU;EACV,aAAa;EACb,aAAa,gBAAgB;EAC7B;;YAGU;;EAEV"}
1
+ {"version":3,"file":"types.d.mts","names":["GAUserProvidedData"],"sources":["../../src/track/types.ts"],"mappings":";;YAEY;YACA,YAAY;;;;;;;;;;;;;;;;;;;;iBAsBP;;KAGZ,SAAS;EAA2B;;;;;;;YAO7B,0BACF,iBACN,cAAc,uBAAuB;;;;;;YAO7B,UAAU,UAAU,YAAY,aAAa,sBACrD,UAAU,oBACR,IACA,oBACF,gBAAgB,iBACd,IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgCW;;;;;;;KAQZ,oBAAoB,KAAK,gBAAgB,wBAC1C,sBAAsB;YAGd,gBAAgB,UAAU,YAAY,aAAa,gBAAgB,iBAC3E,eAAe,KAAK,oBAAoB,KACxC,gBAAgB,wBACd,sBAAsB,KAGtB,8BAEE,OAAO,mBAAmB;YAEtB;YACA;iBAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;iBAGe,yBAAyBA;EACxC;EACA;EACA;EACA;EACA;IAAa;IAAc;IAAe;;EAE1C;EACA;;;;;;;;;;;YAYU,qBAAqB,UAAU,WACzC,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;iBAGe;;EAEf;EACA;;iBAGe;EACf;EACA;EACA;;;;;;;;;;iBAWe;EACf;EACA;EACA;;;;;;;EAOA;;;;;;EAMA;;;;;;;;;;;;;iBAce;EAEf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;EAMA;;EAEA;;EAEA;;EAEA;EAEA;EACA;EACA;EACA;;;;;;;;EAQA;;;;;;EAMA;EACA;EACA;EACA;;EAEA;;EAEA;EAEA;;EAEA;EAEA;;EAEA;;EAEA;;EAEA;EAEA;;;;;EAKA;EAEA;;EAEA;;EAEA;EAEA;EACA;EACA;EACA;EACA;EACA;;;;;;;iBAQe;;EAEf;;;;;;;;;;;;EAqCA;;;;;;EAuDA;;EAMA;;EAEA;;EAEA;;EAEA;;EAUA;;EAEA;;iBAGe,kBACP,cAAc,YAAY,SAAS,iBAAiB,UAAU,iBAAiB;EACvF;GACC;;iBAGc,WAAW,UAAU,YAAY;EAChD;EACA,MAAM,UAAU;EAChB,MAAM;EACN;EACA;EACA,UAAU;EACV,aAAa;EACb,aAAa,gBAAgB;EAC7B;;;;;;;;;;YAWU;;EAEV"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@shware/analytics",
3
- "version": "12.0.0",
3
+ "version": "12.2.0",
4
4
  "private": false,
5
5
  "repository": {
6
6
  "type": "git",
@@ -254,7 +254,7 @@
254
254
  },
255
255
  "scripts": {
256
256
  "dev": "tsc --watch",
257
- "check-types": "tsc --noEmit",
257
+ "check-types": "tsc --noEmit && tsc --noEmit -p src/track/strict-event-names",
258
258
  "test": "vitest run --passWithNoTests",
259
259
  "lint": "oxlint --type-aware . --fix",
260
260
  "build": "tsdown"