@codefast/tracking 0.0.0 → 0.5.0-canary.4

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 (71) hide show
  1. package/CHANGELOG.md +38 -0
  2. package/README.md +46 -8
  3. package/dist/client/consent-storage.d.mts +11 -3
  4. package/dist/client/consent-storage.mjs +45 -9
  5. package/dist/client/create-client-tracker.d.mts +10 -0
  6. package/dist/client/create-client-tracker.mjs +14 -1
  7. package/dist/client/gpc.d.mts +2 -0
  8. package/dist/client/gpc.mjs +2 -0
  9. package/dist/client/lifecycle.d.mts +5 -0
  10. package/dist/client/lifecycle.mjs +2 -0
  11. package/dist/client/local-storage.d.mts +5 -2
  12. package/dist/client/local-storage.mjs +12 -5
  13. package/dist/client/queue.d.mts +7 -0
  14. package/dist/client/queue.mjs +2 -0
  15. package/dist/client/router.d.mts +4 -0
  16. package/dist/client/router.mjs +2 -0
  17. package/dist/core/consent.d.mts +61 -9
  18. package/dist/core/consent.mjs +39 -7
  19. package/dist/core/destination.d.mts +10 -0
  20. package/dist/core/event-catalog.d.mts +8 -0
  21. package/dist/core/event-catalog.mjs +2 -0
  22. package/dist/core/event-id.d.mts +2 -0
  23. package/dist/core/event-id.mjs +2 -0
  24. package/dist/core/index.d.mts +2 -2
  25. package/dist/core/index.mjs +2 -2
  26. package/dist/core/tracked-event.d.mts +2 -0
  27. package/dist/destinations/ga4-measurement-protocol.d.mts +54 -0
  28. package/dist/destinations/ga4-measurement-protocol.mjs +89 -0
  29. package/dist/destinations/google-analytics.d.mts +98 -0
  30. package/dist/destinations/google-analytics.mjs +126 -0
  31. package/dist/destinations/http-destination.d.mts +5 -0
  32. package/dist/destinations/http-destination.mjs +2 -0
  33. package/dist/destinations/index.d.mts +3 -1
  34. package/dist/destinations/index.mjs +3 -1
  35. package/dist/destinations/vercel-analytics.d.mts +4 -2
  36. package/dist/destinations/vercel-analytics.mjs +5 -2
  37. package/dist/index.d.mts +2 -2
  38. package/dist/index.mjs +2 -2
  39. package/dist/react/consent-banner.d.mts +48 -14
  40. package/dist/react/consent-banner.mjs +94 -22
  41. package/dist/react/index.d.mts +2 -2
  42. package/dist/react/use-consent.d.mts +30 -5
  43. package/dist/react/use-consent.mjs +38 -15
  44. package/dist/server/create-server-tracker.d.mts +14 -0
  45. package/dist/server/create-server-tracker.mjs +24 -5
  46. package/dist/server/region.d.mts +4 -0
  47. package/dist/server/region.mjs +4 -0
  48. package/package.json +12 -2
  49. package/src/client/consent-storage.ts +75 -10
  50. package/src/client/create-client-tracker.ts +30 -1
  51. package/src/client/gpc.ts +2 -0
  52. package/src/client/lifecycle.ts +5 -0
  53. package/src/client/local-storage.ts +21 -6
  54. package/src/client/queue.ts +7 -0
  55. package/src/client/router.ts +4 -0
  56. package/src/core/consent.ts +85 -11
  57. package/src/core/destination.ts +10 -0
  58. package/src/core/event-catalog.ts +8 -0
  59. package/src/core/event-id.ts +2 -0
  60. package/src/core/index.ts +15 -2
  61. package/src/core/tracked-event.ts +2 -0
  62. package/src/destinations/ga4-measurement-protocol.ts +166 -0
  63. package/src/destinations/google-analytics.ts +233 -0
  64. package/src/destinations/http-destination.ts +5 -0
  65. package/src/destinations/index.ts +16 -0
  66. package/src/destinations/vercel-analytics.ts +5 -2
  67. package/src/react/consent-banner.tsx +121 -22
  68. package/src/react/index.ts +1 -1
  69. package/src/react/use-consent.ts +81 -23
  70. package/src/server/create-server-tracker.ts +39 -16
  71. package/src/server/region.ts +4 -0
@@ -5,11 +5,17 @@ import type { EventCatalog, EventsOf } from "#/core/event-catalog";
5
5
  import { generateEventId } from "#/core/event-id";
6
6
  import type { TrackedEvent } from "#/core/tracked-event";
7
7
 
8
+ /**
9
+ * @since 0.5.0-canary.4
10
+ */
8
11
  export interface ServerTrackContext {
9
12
  anonymousId: string;
10
13
  userId?: string | undefined;
11
14
  }
12
15
 
16
+ /**
17
+ * @since 0.5.0-canary.4
18
+ */
13
19
  export interface ServerTrackerOptions<Catalog extends EventCatalog> {
14
20
  catalog: Catalog;
15
21
  destinations: Array<Destination>;
@@ -19,7 +25,13 @@ export interface ServerTrackerOptions<Catalog extends EventCatalog> {
19
25
  retryDelayMs?: number;
20
26
  }
21
27
 
28
+ /**
29
+ * @since 0.5.0-canary.4
30
+ */
22
31
  export interface ServerTracker<Catalog extends EventCatalog> {
32
+ /** Explicit anonymous → known-user merge, for when `identify` timing can't do it. */
33
+ alias: (previousId: string, userId: string, context: ServerTrackContext) => Promise<void>;
34
+ group: (groupId: string, traits: Record<string, unknown> | undefined, context: ServerTrackContext) => Promise<void>;
23
35
  track: <Name extends keyof EventsOf<Catalog, "server">>(
24
36
  name: Name,
25
37
  props: z.infer<EventsOf<Catalog, "server">[Name]["schema"]>,
@@ -60,6 +72,8 @@ async function sendWithRetry(
60
72
  /**
61
73
  * No dead-letter queue yet (self-host storage is Phase 2) — a destination that keeps
62
74
  * failing after retries is only logged via `onDestinationError`, never re-queued.
75
+ *
76
+ * @since 0.5.0-canary.4
63
77
  */
64
78
  export function createServerTracker<Catalog extends EventCatalog>(
65
79
  options: ServerTrackerOptions<Catalog>,
@@ -73,7 +87,31 @@ export function createServerTracker<Catalog extends EventCatalog>(
73
87
  console.error(`[tracking] destination "${destination.name}" failed for event "${event.name}"`, error);
74
88
  });
75
89
 
90
+ async function sendEvent(name: string, props: Record<string, unknown>, context: ServerTrackContext): Promise<void> {
91
+ const event: TrackedEvent = {
92
+ anonymousId: context.anonymousId,
93
+ eventId: createId(),
94
+ name,
95
+ owner: "server",
96
+ props,
97
+ timestamp: Date.now(),
98
+ ...(context.userId === undefined ? {} : { userId: context.userId }),
99
+ };
100
+
101
+ await Promise.all(
102
+ options.destinations.map(async (destination) =>
103
+ sendWithRetry(destination, event, maxRetries, retryDelayMs, onError),
104
+ ),
105
+ );
106
+ }
107
+
76
108
  return {
109
+ async alias(previousId, userId, context) {
110
+ await sendEvent("$alias", { previousId, userId }, context);
111
+ },
112
+ async group(groupId, traits, context) {
113
+ await sendEvent("$group", { groupId, ...traits }, context);
114
+ },
77
115
  async track(name, props, context) {
78
116
  // noUncheckedIndexedAccess types this as possibly undefined; the owner check also
79
117
  // guards callers who bypass the EventsOf filter with an `as` cast.
@@ -84,22 +122,7 @@ export function createServerTracker<Catalog extends EventCatalog>(
84
122
  }
85
123
 
86
124
  definition.schema.parse(props);
87
-
88
- const event: TrackedEvent = {
89
- anonymousId: context.anonymousId,
90
- eventId: createId(),
91
- name: name as string,
92
- owner: "server",
93
- props: props as Record<string, unknown>,
94
- timestamp: Date.now(),
95
- ...(context.userId === undefined ? {} : { userId: context.userId }),
96
- };
97
-
98
- await Promise.all(
99
- options.destinations.map(async (destination) =>
100
- sendWithRetry(destination, event, maxRetries, retryDelayMs, onError),
101
- ),
102
- );
125
+ await sendEvent(name as string, props as Record<string, unknown>, context);
103
126
  },
104
127
  };
105
128
  }
@@ -34,6 +34,8 @@ const EU_COUNTRY_CODES = new Set([
34
34
  * Missing/unrecognized codes fall back to "other", which `resolveConsentMode` treats
35
35
  * as opt-out — the least restrictive default, safe only because opt-in regions (EU/VN)
36
36
  * are matched explicitly above it.
37
+ *
38
+ * @since 0.5.0-canary.4
37
39
  */
38
40
  export function resolveRegionFromCountryCode(countryCode: string | undefined): ConsentRegion {
39
41
  if (!countryCode) {
@@ -60,6 +62,8 @@ export function resolveRegionFromCountryCode(countryCode: string | undefined): C
60
62
  /**
61
63
  * Reads the hosting platform's geo header (e.g. Vercel's `x-vercel-ip-country`) — pass
62
64
  * the incoming request's `Headers` from server-function/middleware context.
65
+ *
66
+ * @since 0.5.0-canary.4
63
67
  */
64
68
  export function resolveRegion(headers: Headers, headerName = "x-vercel-ip-country"): ConsentRegion {
65
69
  return resolveRegionFromCountryCode(headers.get(headerName) ?? undefined);