@shware/analytics 7.4.0 → 7.5.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { ALL_ENVIRONMENTS, ALL_PLATFORMS, CreateFeedbackDTO, CreateLinkDTO, createFeedbackSchema, createLinkSchema, createTrackEventSchema, createVisitorSchema, updateVisitorSchema } from "./schema/index.cjs";
 import { sendFeedback } from "./feedback/index.cjs";
-import { AllowedPropertyValues, Environment, Platform, TrackProperties, TrackTags, UTMParams, UserProvidedData } from "./track/types.cjs";
+import { AllowedPropertyValues, CustomEventProperties, Environment, Platform, TrackProperties, TrackTags, UTMParams, UserProvidedData } from "./track/types.cjs";
 import { useTrackImpression } from "./hooks/use-track-impression.cjs";
 import { VisitorProperties } from "./visitor/types.cjs";
 import { setupAnalytics } from "./setup/index.cjs";
@@ -8,4 +8,4 @@ import { sendBeacon, track, trackAsync } from "./track/index.cjs";
 import { getVisitor, setVisitor } from "./visitor/index.cjs";
 import { Link, createLink, getLink } from "./link/index.cjs";
 import { stripeMinorUnits } from "./utils/stripe.cjs";
-export { ALL_ENVIRONMENTS, ALL_PLATFORMS, type AllowedPropertyValues, type CreateFeedbackDTO, type CreateLinkDTO, type Environment, type Link, type Platform, type TrackProperties, type TrackTags, type UTMParams, type UserProvidedData, type VisitorProperties, createFeedbackSchema, createLink, createLinkSchema, createTrackEventSchema, createVisitorSchema, getLink, getVisitor, sendBeacon, sendFeedback, setVisitor, setupAnalytics, stripeMinorUnits, track, trackAsync, updateVisitorSchema, useTrackImpression };
+export { ALL_ENVIRONMENTS, ALL_PLATFORMS, type AllowedPropertyValues, type CreateFeedbackDTO, type CreateLinkDTO, type CustomEventProperties, type Environment, type Link, type Platform, type TrackProperties, type TrackTags, type UTMParams, type UserProvidedData, type VisitorProperties, createFeedbackSchema, createLink, createLinkSchema, createTrackEventSchema, createVisitorSchema, getLink, getVisitor, sendBeacon, sendFeedback, setVisitor, setupAnalytics, stripeMinorUnits, track, trackAsync, updateVisitorSchema, useTrackImpression };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { ALL_ENVIRONMENTS, ALL_PLATFORMS, CreateFeedbackDTO, CreateLinkDTO, createFeedbackSchema, createLinkSchema, createTrackEventSchema, createVisitorSchema, updateVisitorSchema } from "./schema/index.mjs";
 import { sendFeedback } from "./feedback/index.mjs";
-import { AllowedPropertyValues, Environment, Platform, TrackProperties, TrackTags, UTMParams, UserProvidedData } from "./track/types.mjs";
+import { AllowedPropertyValues, CustomEventProperties, Environment, Platform, TrackProperties, TrackTags, UTMParams, UserProvidedData } from "./track/types.mjs";
 import { useTrackImpression } from "./hooks/use-track-impression.mjs";
 import { VisitorProperties } from "./visitor/types.mjs";
 import { setupAnalytics } from "./setup/index.mjs";
@@ -8,4 +8,4 @@ import { sendBeacon, track, trackAsync } from "./track/index.mjs";
 import { getVisitor, setVisitor } from "./visitor/index.mjs";
 import { Link, createLink, getLink } from "./link/index.mjs";
 import { stripeMinorUnits } from "./utils/stripe.mjs";
-export { ALL_ENVIRONMENTS, ALL_PLATFORMS, type AllowedPropertyValues, type CreateFeedbackDTO, type CreateLinkDTO, type Environment, type Link, type Platform, type TrackProperties, type TrackTags, type UTMParams, type UserProvidedData, type VisitorProperties, createFeedbackSchema, createLink, createLinkSchema, createTrackEventSchema, createVisitorSchema, getLink, getVisitor, sendBeacon, sendFeedback, setVisitor, setupAnalytics, stripeMinorUnits, track, trackAsync, updateVisitorSchema, useTrackImpression };
+export { ALL_ENVIRONMENTS, ALL_PLATFORMS, type AllowedPropertyValues, type CreateFeedbackDTO, type CreateLinkDTO, type CustomEventProperties, type Environment, type Link, type Platform, type TrackProperties, type TrackTags, type UTMParams, type UserProvidedData, type VisitorProperties, createFeedbackSchema, createLink, createLinkSchema, createTrackEventSchema, createVisitorSchema, getLink, getVisitor, sendBeacon, sendFeedback, setVisitor, setupAnalytics, stripeMinorUnits, track, trackAsync, updateVisitorSchema, useTrackImpression };

package/dist/track/types.d.cts

@@ -3,7 +3,41 @@ import { StandardEvents, UserProvidedData as UserProvidedData$1 } from "./gtag.c
 type AllowedPropertyValues = string | number | boolean | null;
 type EventName = Lowercase<string> | 'CLS' | 'FCP' | 'INP' | 'LCP' | 'TTFB';
 type TrackName<T extends EventName = EventName> = T extends keyof StandardEvents ? T : EventName;
-type TrackProperties<T extends EventName = EventName> = T extends keyof StandardEvents ? StandardEvents[T] : Record<Lowercase<string>, AllowedPropertyValues>;
+/**
+ * Properties an application defines for its own events, keyed by event name.
+ *
+ * Empty here on purpose. Applications fill it by declaration merging, and it does two jobs:
+ * it adds custom properties to GA4's standard events, which are otherwise closed shapes and
+ * would need a cast; and it gives an application's own events a real type instead of the
+ * open record they fall back to.
+ *
+ * ```ts
+ * declare module '@shware/analytics' {
+ *   interface CustomEventProperties {
+ *     // Extra properties on a standard event.
+ *     begin_checkout: { type?: 'new_purchase' | 'upgrade' };
+ *     // The whole shape of an event this app defines itself.
+ *     schedule_plan_change: { direction: 'upgrade' | 'downgrade'; effective_at: string };
+ *   }
+ * }
+ * ```
+ *
+ * Keyed by event rather than a single flat set of properties, so a dimension cannot leak
+ * onto events it means nothing on. An event nobody declares keeps its previous type exactly,
+ * which is what makes adopting this optional and incremental.
+ *
+ * Note what "custom" attaches to: the *properties*, not the event. `begin_checkout` is one
+ * of GA4's recommended events and stays one — only the properties added here are custom.
+ */
+interface CustomEventProperties {}
+/**
+ * An application's declared properties for one event, or nothing if it declared none.
+ *
+ * `unknown` rather than `{}` for the empty case: it is the identity of `&`, so an event with
+ * no declaration intersects to exactly the type it had before.
+ */
+type CustomPropertiesFor<T> = T extends keyof CustomEventProperties ? CustomEventProperties[T] : unknown;
+type TrackProperties<T extends EventName = EventName> = T extends keyof StandardEvents ? StandardEvents[T] & CustomPropertiesFor<T> : T extends keyof CustomEventProperties ? CustomEventProperties[T] : Record<Lowercase<string>, AllowedPropertyValues>;
 type Platform = 'ios' | 'android' | 'web' | 'macos' | 'windows' | 'linux' | 'unknown';
 type Environment = 'development' | 'production';
 interface UserData {
@@ -172,5 +206,5 @@ type TrackEventResponse = {
   id: string;
 }[];
 //#endregion
-export { AdvertisingInfo, AllowedPropertyValues, AppInfo, DeviceInfo, Environment, EnvironmentInfo, EventName, PageInfo, Platform, PlatformInfo, ThirdPartyTracker, TrackEvent, TrackEventResponse, TrackName, TrackProperties, TrackTags, UTMParams, UserData, UserProvidedData };
+export { AdvertisingInfo, AllowedPropertyValues, AppInfo, CustomEventProperties, DeviceInfo, Environment, EnvironmentInfo, EventName, PageInfo, Platform, PlatformInfo, ThirdPartyTracker, TrackEvent, TrackEventResponse, TrackName, TrackProperties, TrackTags, UTMParams, UserData, UserProvidedData };
 //# sourceMappingURL=types.d.cts.map

package/dist/track/types.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.cts","names":[],"sources":["../../src/track/types.ts"],"mappings":";;KAEY;KACA,YAAY;KAEZ,UAAU,UAAU,YAAY,aAAa,gBAAgB,iBACrE,IACA;KACQ,gBAAgB,UAAU,YAAY,aAAa,gBAAgB,iBAC3E,eAAe,KACf,OAAO,mBAAmB;KAElB;KACA;UAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGe,yBAAyB;EACxC;EACA;EACA;EACA;EACA;IAAa;IAAc;IAAe;;EAE1C;EACA;;KAGU,qBAAqB,UAAU,WACzC,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B;UAGe;EACf;EACA;EACA;EACA;EACA;EACA;;UAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGe;;EAEf;EACA;;UAGe;EACf;EACA;EACA;;;;;;;;;;UAWe;EACf;EACA;EACA;;UAGe;;;;;;;EAOf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;EACA;EACA;EACA;;EAEA;EACA;;EAEA;EAEA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;UAQe;;EAEf;;;;;;;;;;;;EAqCA;;;;;;EAuDA;;EAMA;;EAEA;;EAEA;;EAEA;;EAUA;;EAEA;;UAGe,kBACP,cAAc,YAAY,SAAS,iBAAiB,UAAU,iBAAiB;EACvF;GACC;;UAGc,WAAW,UAAU,YAAY;EAChD;EACA,MAAM,UAAU;EAChB,MAAM;EACN;EACA;EACA,UAAU;EACV,aAAa;EACb,aAAa,gBAAgB;EAC7B;;KAGU;;EAEV"}
+{"version":3,"file":"types.d.cts","names":[],"sources":["../../src/track/types.ts"],"mappings":";;KAEY;KACA,YAAY;KAEZ,UAAU,UAAU,YAAY,aAAa,gBAAgB,iBACrE,IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;UA+Ba;;;;;;;KAQZ,oBAAoB,KAAK,gBAAgB,wBAC1C,sBAAsB;KAGd,gBAAgB,UAAU,YAAY,aAAa,gBAAgB,iBAC3E,eAAe,KAAK,oBAAoB,KACxC,gBAAgB,wBACd,sBAAsB,KACtB,OAAO,mBAAmB;KAEpB;KACA;UAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGe,yBAAyB;EACxC;EACA;EACA;EACA;EACA;IAAa;IAAc;IAAe;;EAE1C;EACA;;KAGU,qBAAqB,UAAU,WACzC,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B;UAGe;EACf;EACA;EACA;EACA;EACA;EACA;;UAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGe;;EAEf;EACA;;UAGe;EACf;EACA;EACA;;;;;;;;;;UAWe;EACf;EACA;EACA;;UAGe;;;;;;;EAOf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;EACA;EACA;EACA;;EAEA;EACA;;EAEA;EAEA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;UAQe;;EAEf;;;;;;;;;;;;EAqCA;;;;;;EAuDA;;EAMA;;EAEA;;EAEA;;EAEA;;EAUA;;EAEA;;UAGe,kBACP,cAAc,YAAY,SAAS,iBAAiB,UAAU,iBAAiB;EACvF;GACC;;UAGc,WAAW,UAAU,YAAY;EAChD;EACA,MAAM,UAAU;EAChB,MAAM;EACN;EACA;EACA,UAAU;EACV,aAAa;EACb,aAAa,gBAAgB;EAC7B;;KAGU;;EAEV"}

package/dist/track/types.d.mts

@@ -3,7 +3,41 @@ import { StandardEvents, UserProvidedData as UserProvidedData$1 } from "./gtag.m
 type AllowedPropertyValues = string | number | boolean | null;
 type EventName = Lowercase<string> | 'CLS' | 'FCP' | 'INP' | 'LCP' | 'TTFB';
 type TrackName<T extends EventName = EventName> = T extends keyof StandardEvents ? T : EventName;
-type TrackProperties<T extends EventName = EventName> = T extends keyof StandardEvents ? StandardEvents[T] : Record<Lowercase<string>, AllowedPropertyValues>;
+/**
+ * Properties an application defines for its own events, keyed by event name.
+ *
+ * Empty here on purpose. Applications fill it by declaration merging, and it does two jobs:
+ * it adds custom properties to GA4's standard events, which are otherwise closed shapes and
+ * would need a cast; and it gives an application's own events a real type instead of the
+ * open record they fall back to.
+ *
+ * ```ts
+ * declare module '@shware/analytics' {
+ *   interface CustomEventProperties {
+ *     // Extra properties on a standard event.
+ *     begin_checkout: { type?: 'new_purchase' | 'upgrade' };
+ *     // The whole shape of an event this app defines itself.
+ *     schedule_plan_change: { direction: 'upgrade' | 'downgrade'; effective_at: string };
+ *   }
+ * }
+ * ```
+ *
+ * Keyed by event rather than a single flat set of properties, so a dimension cannot leak
+ * onto events it means nothing on. An event nobody declares keeps its previous type exactly,
+ * which is what makes adopting this optional and incremental.
+ *
+ * Note what "custom" attaches to: the *properties*, not the event. `begin_checkout` is one
+ * of GA4's recommended events and stays one — only the properties added here are custom.
+ */
+interface CustomEventProperties {}
+/**
+ * An application's declared properties for one event, or nothing if it declared none.
+ *
+ * `unknown` rather than `{}` for the empty case: it is the identity of `&`, so an event with
+ * no declaration intersects to exactly the type it had before.
+ */
+type CustomPropertiesFor<T> = T extends keyof CustomEventProperties ? CustomEventProperties[T] : unknown;
+type TrackProperties<T extends EventName = EventName> = T extends keyof StandardEvents ? StandardEvents[T] & CustomPropertiesFor<T> : T extends keyof CustomEventProperties ? CustomEventProperties[T] : Record<Lowercase<string>, AllowedPropertyValues>;
 type Platform = 'ios' | 'android' | 'web' | 'macos' | 'windows' | 'linux' | 'unknown';
 type Environment = 'development' | 'production';
 interface UserData {
@@ -172,5 +206,5 @@ type TrackEventResponse = {
   id: string;
 }[];
 //#endregion
-export { AdvertisingInfo, AllowedPropertyValues, AppInfo, DeviceInfo, Environment, EnvironmentInfo, EventName, PageInfo, Platform, PlatformInfo, ThirdPartyTracker, TrackEvent, TrackEventResponse, TrackName, TrackProperties, TrackTags, UTMParams, UserData, UserProvidedData };
+export { AdvertisingInfo, AllowedPropertyValues, AppInfo, CustomEventProperties, DeviceInfo, Environment, EnvironmentInfo, EventName, PageInfo, Platform, PlatformInfo, ThirdPartyTracker, TrackEvent, TrackEventResponse, TrackName, TrackProperties, TrackTags, UTMParams, UserData, UserProvidedData };
 //# sourceMappingURL=types.d.mts.map

package/dist/track/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/track/types.ts"],"mappings":";;KAEY;KACA,YAAY;KAEZ,UAAU,UAAU,YAAY,aAAa,gBAAgB,iBACrE,IACA;KACQ,gBAAgB,UAAU,YAAY,aAAa,gBAAgB,iBAC3E,eAAe,KACf,OAAO,mBAAmB;KAElB;KACA;UAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGe,yBAAyB;EACxC;EACA;EACA;EACA;EACA;IAAa;IAAc;IAAe;;EAE1C;EACA;;KAGU,qBAAqB,UAAU,WACzC,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B;UAGe;EACf;EACA;EACA;EACA;EACA;EACA;;UAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGe;;EAEf;EACA;;UAGe;EACf;EACA;EACA;;;;;;;;;;UAWe;EACf;EACA;EACA;;UAGe;;;;;;;EAOf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;EACA;EACA;EACA;;EAEA;EACA;;EAEA;EAEA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;UAQe;;EAEf;;;;;;;;;;;;EAqCA;;;;;;EAuDA;;EAMA;;EAEA;;EAEA;;EAEA;;EAUA;;EAEA;;UAGe,kBACP,cAAc,YAAY,SAAS,iBAAiB,UAAU,iBAAiB;EACvF;GACC;;UAGc,WAAW,UAAU,YAAY;EAChD;EACA,MAAM,UAAU;EAChB,MAAM;EACN;EACA;EACA,UAAU;EACV,aAAa;EACb,aAAa,gBAAgB;EAC7B;;KAGU;;EAEV"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/track/types.ts"],"mappings":";;KAEY;KACA,YAAY;KAEZ,UAAU,UAAU,YAAY,aAAa,gBAAgB,iBACrE,IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;UA+Ba;;;;;;;KAQZ,oBAAoB,KAAK,gBAAgB,wBAC1C,sBAAsB;KAGd,gBAAgB,UAAU,YAAY,aAAa,gBAAgB,iBAC3E,eAAe,KAAK,oBAAoB,KACxC,gBAAgB,wBACd,sBAAsB,KACtB,OAAO,mBAAmB;KAEpB;KACA;UAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGe,yBAAyB;EACxC;EACA;EACA;EACA;EACA;IAAa;IAAc;IAAe;;EAE1C;EACA;;KAGU,qBAAqB,UAAU,WACzC,MAAM,UAAU,IAChB,aAAa,gBAAgB,IAC7B;UAGe;EACf;EACA;EACA;EACA;EACA;EACA;;UAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGe;;EAEf;EACA;;UAGe;EACf;EACA;EACA;;;;;;;;;;UAWe;EACf;EACA;EACA;;UAGe;;;;;;;EAOf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;EACA;EACA;EACA;;EAEA;EACA;;EAEA;EAEA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;UAQe;;EAEf;;;;;;;;;;;;EAqCA;;;;;;EAuDA;;EAMA;;EAEA;;EAEA;;EAEA;;EAUA;;EAEA;;UAGe,kBACP,cAAc,YAAY,SAAS,iBAAiB,UAAU,iBAAiB;EACvF;GACC;;UAGc,WAAW,UAAU,YAAY;EAChD;EACA,MAAM,UAAU;EAChB,MAAM;EACN;EACA;EACA,UAAU;EACV,aAAa;EACb,aAAa,gBAAgB;EAC7B;;KAGU;;EAEV"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shware/analytics",
-  "version": "7.4.0",
+  "version": "7.5.0",
   "private": false,
   "repository": {
     "type": "git",