@shware/analytics 12.1.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.
package/README.md CHANGED
@@ -154,6 +154,31 @@ function Button() {
154
154
  }
155
155
  ```
156
156
 
157
+ ### Typed events and strict event names
158
+
159
+ An application types its own events, and adds properties to GA4's standard ones, by declaration merging into `CustomEventProperties` (see its doc comment). By default an event declared nowhere still compiles, with open properties, so `track('purchse', …)` or `track('begin_checkout ', …)` (a trailing space) quietly becomes a new event.
160
+
161
+ Turn on `strict` to make that a compile error. Merge it into `AnalyticsOptions`, preferably in the same file that declares `CustomEventProperties`, so the list of events and the rule that only they can be tracked live together:
162
+
163
+ ```ts
164
+ declare module '@shware/analytics' {
165
+ interface AnalyticsOptions {
166
+ strict: true;
167
+ }
168
+ interface CustomEventProperties {
169
+ plan_changed: { direction: 'upgrade' | 'downgrade' };
170
+ account_deleted: undefined; // an event with no properties
171
+ }
172
+ }
173
+ ```
174
+
175
+ With it on:
176
+
177
+ - Every function that takes an event name — `track`, `trackOnce`, `trackAsync`, `sendBeacon`, `useTrackImpression` and the third-party senders — accepts only GA4's standard events (`purchase`, `login`, `page_view`, …) and the keys of `CustomEventProperties`. Anything else is an error at the call site, so a new event has to be declared before it can be tracked.
178
+ - `TrackProperties` no longer falls back to the open `Record` for an undeclared event (there is none left to track); declared and standard events are typed exactly as before.
179
+
180
+ It is type-only: nothing changes at runtime, and without the merge the SDK behaves exactly as it always has.
181
+
157
182
  ### When events reach the pixels and the server
158
183
 
159
184
  Every event gets its id on the client, a uuidv7 generated by `track()` (and `trackOnce()`, `trackAsync()`) at the moment it is tracked. The same id goes to both places:
package/dist/index.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { AllowedPropertyValues, CustomEventProperties, Environment, Platform, TrackProperties, TrackTags, UTMParams, UserProvidedData } from "./track/types.cjs";
1
+ import { AllowedPropertyValues, AnalyticsOptions, CustomEventProperties, Environment, Platform, TrackProperties, TrackTags, UTMParams, UserProvidedData } from "./track/types.cjs";
2
2
  import { BOT_CATEGORIES, Bot, BotCategory, NOT_A_BOT, botOf } from "./bot/index.cjs";
3
3
  import { ALL_ENVIRONMENTS, ALL_PLATFORMS, CreateFeedbackDTO, CreateLinkDTO, CreateTrackEventDTO, CreateVisitorDTO, UpdateVisitorDTO, createFeedbackSchema, createLinkSchema, createTrackEventSchema, createVisitorSchema, updateVisitorSchema } from "./schema/index.cjs";
4
4
  import { sendFeedback } from "./feedback/index.cjs";
@@ -11,4 +11,4 @@ import { visitorId } from "./visitor/id.cjs";
11
11
  import { IDENTIFY_EVENT, setVisitor } from "./visitor/index.cjs";
12
12
  import { Link, createLink, getLink } from "./link/index.cjs";
13
13
  import { stripeMinorUnits } from "./utils/stripe.cjs";
14
- export { ALL_ENVIRONMENTS, ALL_PLATFORMS, type AllowedPropertyValues, BOT_CATEGORIES, type Bot, type BotCategory, type CreateFeedbackDTO, type CreateLinkDTO, type CreateTrackEventDTO, type CreateVisitorDTO, type CustomEventProperties, type Environment, IDENTIFY_EVENT, type Link, NOT_A_BOT, type Platform, type TrackOnceOptions, type TrackProperties, type TrackTags, type UTMParams, type UpdateVisitorDTO, type UserProvidedData, type VisitorProperties, botOf, createFeedbackSchema, createLink, createLinkSchema, createTrackEventSchema, createVisitorSchema, getLink, sendBeacon, sendFeedback, sendPendingEvents, setVisitor, setupAnalytics, stripeMinorUnits, track, trackAsync, trackOnce, updateVisitorSchema, useTrackImpression, visitorId };
14
+ export { ALL_ENVIRONMENTS, ALL_PLATFORMS, type AllowedPropertyValues, type AnalyticsOptions, BOT_CATEGORIES, type Bot, type BotCategory, type CreateFeedbackDTO, type CreateLinkDTO, type CreateTrackEventDTO, type CreateVisitorDTO, type CustomEventProperties, type Environment, IDENTIFY_EVENT, type Link, NOT_A_BOT, type Platform, type TrackOnceOptions, type TrackProperties, type TrackTags, type UTMParams, type UpdateVisitorDTO, type UserProvidedData, type VisitorProperties, botOf, createFeedbackSchema, createLink, createLinkSchema, createTrackEventSchema, createVisitorSchema, getLink, sendBeacon, sendFeedback, sendPendingEvents, setVisitor, setupAnalytics, stripeMinorUnits, track, trackAsync, trackOnce, updateVisitorSchema, useTrackImpression, visitorId };
package/dist/index.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { AllowedPropertyValues, CustomEventProperties, Environment, Platform, TrackProperties, TrackTags, UTMParams, UserProvidedData } from "./track/types.mjs";
1
+ import { AllowedPropertyValues, AnalyticsOptions, CustomEventProperties, Environment, Platform, TrackProperties, TrackTags, UTMParams, UserProvidedData } from "./track/types.mjs";
2
2
  import { BOT_CATEGORIES, Bot, BotCategory, NOT_A_BOT, botOf } from "./bot/index.mjs";
3
3
  import { ALL_ENVIRONMENTS, ALL_PLATFORMS, CreateFeedbackDTO, CreateLinkDTO, CreateTrackEventDTO, CreateVisitorDTO, UpdateVisitorDTO, createFeedbackSchema, createLinkSchema, createTrackEventSchema, createVisitorSchema, updateVisitorSchema } from "./schema/index.mjs";
4
4
  import { sendFeedback } from "./feedback/index.mjs";
@@ -11,4 +11,4 @@ import { visitorId } from "./visitor/id.mjs";
11
11
  import { IDENTIFY_EVENT, setVisitor } from "./visitor/index.mjs";
12
12
  import { Link, createLink, getLink } from "./link/index.mjs";
13
13
  import { stripeMinorUnits } from "./utils/stripe.mjs";
14
- export { ALL_ENVIRONMENTS, ALL_PLATFORMS, type AllowedPropertyValues, BOT_CATEGORIES, type Bot, type BotCategory, type CreateFeedbackDTO, type CreateLinkDTO, type CreateTrackEventDTO, type CreateVisitorDTO, type CustomEventProperties, type Environment, IDENTIFY_EVENT, type Link, NOT_A_BOT, type Platform, type TrackOnceOptions, type TrackProperties, type TrackTags, type UTMParams, type UpdateVisitorDTO, type UserProvidedData, type VisitorProperties, botOf, createFeedbackSchema, createLink, createLinkSchema, createTrackEventSchema, createVisitorSchema, getLink, sendBeacon, sendFeedback, sendPendingEvents, setVisitor, setupAnalytics, stripeMinorUnits, track, trackAsync, trackOnce, updateVisitorSchema, useTrackImpression, visitorId };
14
+ export { ALL_ENVIRONMENTS, ALL_PLATFORMS, type AllowedPropertyValues, type AnalyticsOptions, BOT_CATEGORIES, type Bot, type BotCategory, type CreateFeedbackDTO, type CreateLinkDTO, type CreateTrackEventDTO, type CreateVisitorDTO, type CustomEventProperties, type Environment, IDENTIFY_EVENT, type Link, NOT_A_BOT, type Platform, type TrackOnceOptions, type TrackProperties, type TrackTags, type UTMParams, type UpdateVisitorDTO, type UserProvidedData, type VisitorProperties, botOf, createFeedbackSchema, createLink, createLinkSchema, createTrackEventSchema, createVisitorSchema, getLink, sendBeacon, sendFeedback, sendPendingEvents, setVisitor, setupAnalytics, stripeMinorUnits, track, trackAsync, trackOnce, updateVisitorSchema, useTrackImpression, visitorId };
@@ -2,7 +2,13 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
2
  let _react_native_firebase_analytics = require("@react-native-firebase/analytics");
3
3
  //#region src/native/firebase.ts
4
4
  const analytics = (0, _react_native_firebase_analytics.getAnalytics)();
5
- async function sendFirebaseEvent(name, properties) {
5
+ /**
6
+ * A `ThirdPartyTracker` for Firebase Analytics. Synchronous: @react-native-firebase/analytics 26
7
+ * made the modular `logEvent` fire-and-forget (void), and a tracker's return is `void | boolean`
8
+ * (`false` meaning "not ready"), which an `async` function's promise would not satisfy. Callers
9
+ * that still `await` it keep compiling.
10
+ */
11
+ function sendFirebaseEvent(name, properties) {
6
12
  if (name === "screen_view") (0, _react_native_firebase_analytics.logEvent)(analytics, "screen_view", {
7
13
  firebase_screen: properties?.screen_name,
8
14
  firebase_screen_class: properties?.screen_class
@@ -1 +1 @@
1
- {"version":3,"file":"firebase.cjs","names":["getAnalytics"],"sources":["../../src/native/firebase.ts"],"sourcesContent":["import { getAnalytics, logEvent } from '@react-native-firebase/analytics';\nimport type { StandardEvents } from '../track/gtag';\nimport type { EventName, TrackName, TrackProperties } from '../track/types';\n\nconst analytics = getAnalytics();\n\nexport async function sendFirebaseEvent<T extends EventName>(\n name: TrackName<T>,\n properties?: TrackProperties<T>\n) {\n // @react-native-firebase/analytics 26 made the modular logEvent fire-and-forget (void).\n // sendFirebaseEvent stays async so callers that await it keep compiling.\n if (name === 'screen_view') {\n logEvent(analytics, 'screen_view', {\n firebase_screen: (properties as StandardEvents['screen_view'] | undefined)?.screen_name,\n firebase_screen_class: (properties as StandardEvents['screen_view'] | undefined)\n ?.screen_class,\n });\n } else {\n logEvent(analytics, name, properties);\n }\n}\n"],"mappings":";;;AAIA,MAAM,aAAA,GAAYA,iCAAAA,aAAAA,CAAa;AAE/B,eAAsB,kBACpB,MACA,YACA;CAGA,IAAI,SAAS,eACX,CAAA,GAAA,iCAAA,SAAA,CAAS,WAAW,eAAe;EACjC,iBAAkB,YAA0D;EAC5E,uBAAwB,YACpB;CACN,CAAC;MAED,CAAA,GAAA,iCAAA,SAAA,CAAS,WAAW,MAAM,UAAU;AAExC"}
1
+ {"version":3,"file":"firebase.cjs","names":["getAnalytics"],"sources":["../../src/native/firebase.ts"],"sourcesContent":["import { getAnalytics, logEvent } from '@react-native-firebase/analytics';\nimport type { StandardEvents } from '../track/gtag';\nimport type { EventName, TrackName, TrackProperties } from '../track/types';\n\nconst analytics = getAnalytics();\n\n/**\n * A `ThirdPartyTracker` for Firebase Analytics. Synchronous: @react-native-firebase/analytics 26\n * made the modular `logEvent` fire-and-forget (void), and a tracker's return is `void | boolean`\n * (`false` meaning \"not ready\"), which an `async` function's promise would not satisfy. Callers\n * that still `await` it keep compiling.\n */\nexport function sendFirebaseEvent<T extends EventName>(\n name: TrackName<T>,\n properties?: TrackProperties<T>\n) {\n if (name === 'screen_view') {\n logEvent(analytics, 'screen_view', {\n firebase_screen: (properties as StandardEvents['screen_view'] | undefined)?.screen_name,\n firebase_screen_class: (properties as StandardEvents['screen_view'] | undefined)\n ?.screen_class,\n });\n } else {\n logEvent(analytics, name, properties);\n }\n}\n"],"mappings":";;;AAIA,MAAM,aAAA,GAAYA,iCAAAA,aAAAA,CAAa;;;;;;;AAQ/B,SAAgB,kBACd,MACA,YACA;CACA,IAAI,SAAS,eACX,CAAA,GAAA,iCAAA,SAAA,CAAS,WAAW,eAAe;EACjC,iBAAkB,YAA0D;EAC5E,uBAAwB,YACpB;CACN,CAAC;MAED,CAAA,GAAA,iCAAA,SAAA,CAAS,WAAW,MAAM,UAAU;AAExC"}
@@ -1,5 +1,11 @@
1
1
  import { EventName, TrackName, TrackProperties } from "../track/types.cjs";
2
2
  //#region src/native/firebase.d.ts
3
- export declare function sendFirebaseEvent<T extends EventName>(name: TrackName<T>, properties?: TrackProperties<T>): Promise<void>;
3
+ /**
4
+ * A `ThirdPartyTracker` for Firebase Analytics. Synchronous: @react-native-firebase/analytics 26
5
+ * made the modular `logEvent` fire-and-forget (void), and a tracker's return is `void | boolean`
6
+ * (`false` meaning "not ready"), which an `async` function's promise would not satisfy. Callers
7
+ * that still `await` it keep compiling.
8
+ */
9
+ export declare function sendFirebaseEvent<T extends EventName>(name: TrackName<T>, properties?: TrackProperties<T>): void;
4
10
  //#endregion
5
11
  //# sourceMappingURL=firebase.d.cts.map
@@ -1 +1 @@
1
- {"version":3,"file":"firebase.d.cts","names":[],"sources":["../../src/native/firebase.ts"],"mappings":";;wBAMsB,kBAAkB,UAAU,WAChD,MAAM,UAAU,IAChB,aAAa,gBAAgB,KAAE"}
1
+ {"version":3,"file":"firebase.d.cts","names":[],"sources":["../../src/native/firebase.ts"],"mappings":";;;;;;;;wBAYgB,kBAAkB,UAAU,WAC1C,MAAM,UAAU,IAChB,aAAa,gBAAgB"}
@@ -1,5 +1,11 @@
1
1
  import { EventName, TrackName, TrackProperties } from "../track/types.mjs";
2
2
  //#region src/native/firebase.d.ts
3
- export declare function sendFirebaseEvent<T extends EventName>(name: TrackName<T>, properties?: TrackProperties<T>): Promise<void>;
3
+ /**
4
+ * A `ThirdPartyTracker` for Firebase Analytics. Synchronous: @react-native-firebase/analytics 26
5
+ * made the modular `logEvent` fire-and-forget (void), and a tracker's return is `void | boolean`
6
+ * (`false` meaning "not ready"), which an `async` function's promise would not satisfy. Callers
7
+ * that still `await` it keep compiling.
8
+ */
9
+ export declare function sendFirebaseEvent<T extends EventName>(name: TrackName<T>, properties?: TrackProperties<T>): void;
4
10
  //#endregion
5
11
  //# sourceMappingURL=firebase.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"firebase.d.mts","names":[],"sources":["../../src/native/firebase.ts"],"mappings":";;wBAMsB,kBAAkB,UAAU,WAChD,MAAM,UAAU,IAChB,aAAa,gBAAgB,KAAE"}
1
+ {"version":3,"file":"firebase.d.mts","names":[],"sources":["../../src/native/firebase.ts"],"mappings":";;;;;;;;wBAYgB,kBAAkB,UAAU,WAC1C,MAAM,UAAU,IAChB,aAAa,gBAAgB"}
@@ -1,7 +1,13 @@
1
1
  import { getAnalytics, logEvent } from "@react-native-firebase/analytics";
2
2
  //#region src/native/firebase.ts
3
3
  const analytics = getAnalytics();
4
- async function sendFirebaseEvent(name, properties) {
4
+ /**
5
+ * A `ThirdPartyTracker` for Firebase Analytics. Synchronous: @react-native-firebase/analytics 26
6
+ * made the modular `logEvent` fire-and-forget (void), and a tracker's return is `void | boolean`
7
+ * (`false` meaning "not ready"), which an `async` function's promise would not satisfy. Callers
8
+ * that still `await` it keep compiling.
9
+ */
10
+ function sendFirebaseEvent(name, properties) {
5
11
  if (name === "screen_view") logEvent(analytics, "screen_view", {
6
12
  firebase_screen: properties?.screen_name,
7
13
  firebase_screen_class: properties?.screen_class
@@ -1 +1 @@
1
- {"version":3,"file":"firebase.mjs","names":[],"sources":["../../src/native/firebase.ts"],"sourcesContent":["import { getAnalytics, logEvent } from '@react-native-firebase/analytics';\nimport type { StandardEvents } from '../track/gtag';\nimport type { EventName, TrackName, TrackProperties } from '../track/types';\n\nconst analytics = getAnalytics();\n\nexport async function sendFirebaseEvent<T extends EventName>(\n name: TrackName<T>,\n properties?: TrackProperties<T>\n) {\n // @react-native-firebase/analytics 26 made the modular logEvent fire-and-forget (void).\n // sendFirebaseEvent stays async so callers that await it keep compiling.\n if (name === 'screen_view') {\n logEvent(analytics, 'screen_view', {\n firebase_screen: (properties as StandardEvents['screen_view'] | undefined)?.screen_name,\n firebase_screen_class: (properties as StandardEvents['screen_view'] | undefined)\n ?.screen_class,\n });\n } else {\n logEvent(analytics, name, properties);\n }\n}\n"],"mappings":";;AAIA,MAAM,YAAY,aAAa;AAE/B,eAAsB,kBACpB,MACA,YACA;CAGA,IAAI,SAAS,eACX,SAAS,WAAW,eAAe;EACjC,iBAAkB,YAA0D;EAC5E,uBAAwB,YACpB;CACN,CAAC;MAED,SAAS,WAAW,MAAM,UAAU;AAExC"}
1
+ {"version":3,"file":"firebase.mjs","names":[],"sources":["../../src/native/firebase.ts"],"sourcesContent":["import { getAnalytics, logEvent } from '@react-native-firebase/analytics';\nimport type { StandardEvents } from '../track/gtag';\nimport type { EventName, TrackName, TrackProperties } from '../track/types';\n\nconst analytics = getAnalytics();\n\n/**\n * A `ThirdPartyTracker` for Firebase Analytics. Synchronous: @react-native-firebase/analytics 26\n * made the modular `logEvent` fire-and-forget (void), and a tracker's return is `void | boolean`\n * (`false` meaning \"not ready\"), which an `async` function's promise would not satisfy. Callers\n * that still `await` it keep compiling.\n */\nexport function sendFirebaseEvent<T extends EventName>(\n name: TrackName<T>,\n properties?: TrackProperties<T>\n) {\n if (name === 'screen_view') {\n logEvent(analytics, 'screen_view', {\n firebase_screen: (properties as StandardEvents['screen_view'] | undefined)?.screen_name,\n firebase_screen_class: (properties as StandardEvents['screen_view'] | undefined)\n ?.screen_class,\n });\n } else {\n logEvent(analytics, name, properties);\n }\n}\n"],"mappings":";;AAIA,MAAM,YAAY,aAAa;;;;;;;AAQ/B,SAAgB,kBACd,MACA,YACA;CACA,IAAI,SAAS,eACX,SAAS,WAAW,eAAe;EACjC,iBAAkB,YAA0D;EAC5E,uBAAwB,YACpB;CACN,CAAC;MAED,SAAS,WAAW,MAAM,UAAU;AAExC"}
@@ -2,14 +2,50 @@ import { StandardEvents, UserProvidedData as UserProvidedData$1 } from "./gtag.c
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 {
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.cts","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;;;;;;;;;;;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"}
1
+ {"version":3,"file":"types.d.cts","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"}
@@ -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 {
@@ -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;;;;;;;;;;;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"}
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.1.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"