@refraction-ui/astro 0.7.0 → 0.8.0

package/dist/analytics-sink-ga4/client-sdk-sink.ts

@@ -0,0 +1,191 @@
+/**
+ * GA4 `client-sdk` adapter — lazy gtag.js.
+ *
+ * The vendor library is NEVER a hard dependency and is NEVER bundled. On the
+ * first delivery the adapter:
+ *   1. installs the gtag stub + dataLayer,
+ *   2. pushes the Consent Mode default (if a bridge is configured),
+ *   3. lazily injects `https://www.googletagmanager.com/gtag/js?id=<id>`
+ *      via a `<script>` tag (or an injected loader for tests/SSR),
+ *   4. runs `gtag('js', Date)` + `gtag('config', <id>, { send_page_view:false })`.
+ *
+ * Subsequent deliveries map each canonical envelope through the shared mapper
+ * and call `gtag('set', 'user_properties', …)` / `gtag('set', { user_id })` /
+ * `gtag('event', name, params)`.
+ *
+ * Consent Mode bridge: `init` pushes `consent: default`; `deliver` is only
+ * reached when the router's consent gate already allows this sink, at which
+ * point `consent: update` is pushed for the mapped GA4 consent types.
+ */
+
+import type {
+  AnalyticsEvent,
+  AnalyticsSink,
+  SinkInitContext,
+} from '../analytics/index.ts'
+import type { GA4ClientSdkOptions, GtagFn } from './types.js'
+import { mapEvent } from './mapping.js'
+
+const DEFAULT_SRC_BASE = 'https://www.googletagmanager.com/gtag/js'
+
+interface GtagGlobal {
+  dataLayer?: unknown[]
+  gtag?: GtagFn
+  document?: {
+    createElement(tag: string): {
+      async: boolean
+      src: string
+      onload: (() => void) | null
+      onerror: (() => void) | null
+    }
+    head?: { appendChild(node: unknown): void }
+    getElementsByTagName(tag: string): ArrayLike<{
+      parentNode?: { insertBefore(a: unknown, b: unknown): void }
+    }>
+  }
+}
+
+/** DOM `<script>` injector (browser only). */
+function defaultScriptLoader(src: string): Promise<void> {
+  const g = globalThis as unknown as GtagGlobal
+  const doc = g.document
+  if (!doc || typeof doc.createElement !== 'function') {
+    return Promise.reject(
+      new Error('GA4 client-sdk sink: no DOM to inject gtag.js'),
+    )
+  }
+  return new Promise<void>((resolve, reject) => {
+    const el = doc.createElement('script')
+    el.async = true
+    el.src = src
+    el.onload = () => resolve()
+    el.onerror = () => reject(new Error('GA4 client-sdk: gtag.js failed'))
+    if (doc.head?.appendChild) {
+      doc.head.appendChild(el)
+    } else {
+      const first = doc.getElementsByTagName('script')[0]
+      first?.parentNode?.insertBefore(el, first)
+    }
+  })
+}
+
+/**
+ * Create the GA4 gtag.js (`client-sdk`) sink. The vendor script is dynamically
+ * loaded on first delivery only — there is no static import of any GA4/gtag
+ * library, so `http`-mode consumers never pull this code path.
+ */
+export function createGA4ClientSdkSink(
+  options: GA4ClientSdkOptions,
+): AnalyticsSink {
+  const {
+    measurementId,
+    consentCategories = ['analytics'],
+    name = 'ga4',
+    consentMode,
+  } = options
+
+  const g = globalThis as unknown as GtagGlobal
+
+  let gtag: GtagFn | undefined = options.gtag
+  let loaded = false
+  let loadPromise: Promise<void> | undefined
+
+  function ensureGtagStub(): GtagFn {
+    if (gtag) return gtag
+    // Standard gtag bootstrap: dataLayer-backed shim available synchronously.
+    g.dataLayer = g.dataLayer ?? []
+    const dl = g.dataLayer
+    const fn: GtagFn = (...args: unknown[]) => {
+      dl.push(args)
+    }
+    g.gtag = g.gtag ?? fn
+    gtag = g.gtag
+    return gtag
+  }
+
+  function pushConsentDefault(): void {
+    if (!consentMode?.default || !gtag) return
+    gtag('consent', 'default', { ...consentMode.default })
+  }
+
+  function pushConsentUpdate(): void {
+    if (!consentMode?.map || !gtag) return
+    const update: Record<string, 'granted'> = {}
+    // deliver() only runs when the router's consent gate already permits this
+    // sink (all consentCategories granted) → reflect that to GA4.
+    for (const cat of consentCategories) {
+      for (const ga4Type of consentMode.map[cat] ?? []) {
+        update[ga4Type] = 'granted'
+      }
+    }
+    if (Object.keys(update).length > 0) {
+      gtag('consent', 'update', update)
+    }
+  }
+
+  function ensureLoaded(): Promise<void> {
+    if (loaded) return Promise.resolve()
+    if (loadPromise) return loadPromise
+
+    ensureGtagStub()
+    pushConsentDefault()
+
+    // App/test supplied its own gtag → never inject a vendor script.
+    if (options.gtag) {
+      gtag!('js', new Date())
+      gtag!('config', measurementId, { send_page_view: false })
+      loaded = true
+      return Promise.resolve()
+    }
+
+    const base = options.gtagSrcBase ?? DEFAULT_SRC_BASE
+    const src = `${base}?id=${encodeURIComponent(measurementId)}`
+    const load = options.scriptLoader ?? defaultScriptLoader
+
+    loadPromise = load(src).then(() => {
+      gtag!('js', new Date())
+      gtag!('config', measurementId, { send_page_view: false })
+      loaded = true
+    })
+    return loadPromise
+  }
+
+  return {
+    name,
+    consentCategories,
+
+    init(_ctx: SinkInitContext): void {
+      // Install the stub + Consent Mode default eagerly so a `consent:
+      // default` is in dataLayer before the tag loads. The vendor script
+      // itself is still deferred to the first delivery.
+      ensureGtagStub()
+      pushConsentDefault()
+      void _ctx
+    },
+
+    async deliver(batch: AnalyticsEvent[]): Promise<void> {
+      if (batch.length === 0) return
+      await ensureLoaded()
+      const send = gtag!
+      pushConsentUpdate()
+
+      for (const ev of batch) {
+        const m = mapEvent(ev)
+
+        if (m.userId) {
+          send('set', { user_id: m.userId })
+        }
+        if (m.userProperties) {
+          const flat: Record<string, unknown> = {}
+          for (const [k, v] of Object.entries(m.userProperties)) {
+            flat[k] = v.value
+          }
+          send('set', 'user_properties', flat)
+        }
+        if (m.event) {
+          send('event', m.event.name, m.event.params)
+        }
+      }
+    },
+  }
+}

package/dist/analytics-sink-ga4/ga4-sink.ts

@@ -0,0 +1,27 @@
+/**
+ * `createGA4Sink` — the single entry point. Dispatches on `mode`:
+ *   - `mode: 'client-sdk'` → lazy gtag.js adapter
+ *   - `mode: 'http'` (default) → Measurement Protocol adapter, no vendor lib
+ *
+ * Default is `http` to honour the epic's "default = protocol adapters (no
+ * vendor libs in the browser)" stance. GA4 is just a sink — register it via
+ * `createAnalytics({ sinks: [createGA4Sink(...)] })` or `analytics.addSink`.
+ *
+ * Both factories are independent modules. The `http` factory has ZERO
+ * references to gtag.js / DOM-script code, and the `client-sdk` factory only
+ * touches the vendor script lazily (first delivery). Selecting one mode never
+ * executes the other's load path; consumers that only ever construct an
+ * `http` sink never run any vendor code.
+ */
+
+import type { AnalyticsSink } from '../analytics/index.ts'
+import type { GA4SinkOptions } from './types.js'
+import { createGA4HttpSink } from './http-sink.js'
+import { createGA4ClientSdkSink } from './client-sdk-sink.js'
+
+export function createGA4Sink(options: GA4SinkOptions): AnalyticsSink {
+  if (options.mode === 'client-sdk') {
+    return createGA4ClientSdkSink(options)
+  }
+  return createGA4HttpSink(options)
+}

package/dist/analytics-sink-ga4/http-sink.ts

@@ -0,0 +1,141 @@
+/**
+ * GA4 `http` adapter — Measurement Protocol (`/mp/collect`).
+ *
+ * Server-relay friendly: this path NEVER loads gtag.js or any browser
+ * library. It only POSTs JSON to the Measurement Protocol endpoint:
+ *
+ *   POST {endpoint}/mp/collect?measurement_id={id}&api_secret={secret}
+ *   Content-Type: application/json
+ *   { client_id, user_id?, user_properties?, events: [{ name, params }] }
+ *
+ * GA4 Measurement Protocol constraints honoured here:
+ *   - up to 25 events per request → batches are chunked.
+ *   - `identify` envelopes carry no event; they still POST so user_id /
+ *     user_properties propagate (events array may be empty for a user-props
+ *     only ping, which GA4 accepts).
+ *   - 2xx (incl. 204) = accepted. The MP endpoint always returns 2xx for
+ *     well-formed requests; the `debug` endpoint returns validation messages.
+ */
+
+import type {
+  AnalyticsEvent,
+  AnalyticsSink,
+  SinkInitContext,
+} from '../analytics/index.ts'
+import type { GA4HttpOptions } from './types.js'
+import { mapEvent } from './mapping.js'
+
+const DEFAULT_ENDPOINT = 'https://www.google-analytics.com'
+const MAX_EVENTS_PER_REQUEST = 25
+
+interface MPPayload {
+  client_id: string
+  user_id?: string
+  user_properties?: Record<string, { value: unknown }>
+  events: Array<{ name: string; params: Record<string, unknown> }>
+}
+
+function resolveFetch(opts: GA4HttpOptions): typeof fetch {
+  if (opts.fetchImpl) return opts.fetchImpl
+  const f = (globalThis as unknown as { fetch?: typeof fetch }).fetch
+  if (!f) throw new Error('GA4 http sink: no fetch implementation available')
+  return f
+}
+
+/**
+ * Group consecutive envelopes by GA4 identity (client_id + user_id) so each
+ * Measurement Protocol request carries a single identity, then chunk to the
+ * 25-event limit.
+ */
+function buildPayloads(batch: AnalyticsEvent[]): MPPayload[] {
+  const payloads: MPPayload[] = []
+
+  for (const ev of batch) {
+    const m = mapEvent(ev)
+    const last = payloads[payloads.length - 1]
+    const sameIdentity =
+      last &&
+      last.client_id === m.clientId &&
+      last.user_id === m.userId &&
+      last.events.length < MAX_EVENTS_PER_REQUEST &&
+      // user_properties must not silently differ within one request
+      JSON.stringify(last.user_properties) ===
+        JSON.stringify(m.userProperties)
+
+    const target: MPPayload = sameIdentity
+      ? last
+      : (() => {
+          const p: MPPayload = { client_id: m.clientId, events: [] }
+          if (m.userId) p.user_id = m.userId
+          if (m.userProperties) p.user_properties = m.userProperties
+          payloads.push(p)
+          return p
+        })()
+
+    if (m.event) {
+      target.events.push(m.event)
+    }
+  }
+
+  // Drop empty payloads that carry neither an event nor user identity
+  // signal (nothing to send to GA4).
+  return payloads.filter(
+    (p) =>
+      p.events.length > 0 ||
+      p.user_id !== undefined ||
+      p.user_properties !== undefined,
+  )
+}
+
+/**
+ * Create the GA4 Measurement-Protocol (`http`) sink.
+ *
+ * No vendor library is loaded on this path under any circumstance.
+ */
+export function createGA4HttpSink(options: GA4HttpOptions): AnalyticsSink {
+  const {
+    measurementId,
+    apiSecret,
+    consentCategories = ['analytics'],
+    name = 'ga4',
+    debug = false,
+  } = options
+  const base = (options.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, '')
+  const path = debug ? '/debug/mp/collect' : '/mp/collect'
+  const url =
+    `${base}${path}?measurement_id=${encodeURIComponent(measurementId)}` +
+    `&api_secret=${encodeURIComponent(apiSecret)}`
+
+  return {
+    name,
+    consentCategories,
+
+    init(_ctx: SinkInitContext): void {
+      // No-op: the Measurement Protocol is stateless and credential-driven.
+      // Explicitly NO vendor script / SDK is loaded here.
+      void _ctx
+    },
+
+    async deliver(batch: AnalyticsEvent[]): Promise<void> {
+      if (batch.length === 0) return
+      const payloads = buildPayloads(batch)
+      if (payloads.length === 0) return
+      const doFetch = resolveFetch(options)
+
+      for (const payload of payloads) {
+        try {
+          await doFetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+            keepalive: true,
+          })
+          // GA4 MP returns 2xx (204) for well-formed requests and never
+          // asks for client-side retries; transient failures are dropped.
+        } catch {
+          // Network failure — GA4 MP is fire-and-forget; drop silently.
+        }
+      }
+    },
+  }
+}

package/dist/analytics-sink-ga4/index.ts

@@ -0,0 +1,20 @@
+// Unified factory (dispatches on `mode`).
+export { createGA4Sink } from './ga4-sink.js'
+
+// Direct mode factories (for explicit selection / tree-shaking).
+export { createGA4HttpSink } from './http-sink.js'
+export { createGA4ClientSdkSink } from './client-sdk-sink.js'
+
+// Pure mapping (canonical envelope → GA4) — reusable / testable in isolation.
+export { mapEvent, ga4EventName, toGa4Name } from './mapping.js'
+export type { GA4Event, GA4Mapped } from './mapping.js'
+
+// Option contracts.
+export type {
+  GA4SinkOptions,
+  GA4HttpOptions,
+  GA4ClientSdkOptions,
+  GA4ConsentBridge,
+  ConsentState,
+  GtagFn,
+} from './types.js'

package/dist/analytics-sink-ga4/mapping.ts

@@ -0,0 +1,172 @@
+/**
+ * Canonical envelope → GA4 mapping.
+ *
+ * One mapper, two consumers: the `client-sdk` adapter feeds the result into
+ * `gtag('event', name, params)` / `gtag('set', ...)`, and the `http` adapter
+ * serialises it into a Measurement Protocol `/mp/collect` payload. Keeping the
+ * mapping in one place guarantees the two modes stay behaviourally identical.
+ *
+ * Identity / param mapping (issue #216, epic #213):
+ *   anonymousId  → client_id           (GA4 device/browser id)
+ *   userId       → user_id             (GA4 User-ID, cross-device)
+ *   properties   → event params        (track/page/screen/group payload)
+ *   identify     → user_properties     (traits become GA4 user properties)
+ *   sessionId    → session_id param    (so GA4 sessionisation can align)
+ *
+ * GA4 event-name normalisation: GA4 recommends snake_case event names and
+ * forbids spaces. `page` → `page_view`, `screen` → `screen_view` (GA4
+ * Enhanced-Measurement parity); everything else is lower_snake_cased.
+ */
+
+import type { AnalyticsEvent, AnalyticsProperties } from '../analytics/index.ts'
+
+/** A GA4 event ready for gtag.js or the Measurement Protocol. */
+export interface GA4Event {
+  /** GA4 event name (snake_case, no spaces). */
+  name: string
+  /** Event params (GA4 caps these; we pass them through verbatim). */
+  params: Record<string, unknown>
+}
+
+/** The fully-mapped result for a single canonical envelope. */
+export interface GA4Mapped {
+  /** GA4 client_id (from anonymousId). Always present. */
+  clientId: string
+  /** GA4 user_id (from userId). Present only after identify. */
+  userId?: string
+  /**
+   * GA4 user_properties (from identify/group traits). Each value is wrapped
+   * in `{ value }` as the Measurement Protocol requires; the gtag adapter
+   * unwraps when it calls `gtag('set', 'user_properties', ...)`.
+   */
+  userProperties?: Record<string, { value: unknown }>
+  /**
+   * The GA4 event to send. `identify` calls carry no event (they only set
+   * user_id / user_properties), so this is optional.
+   */
+  event?: GA4Event
+}
+
+const GA4_RESERVED_PREFIXES = ['google_', 'ga_', 'firebase_']
+
+/** Lower_snake_case an arbitrary event/trait name for GA4. */
+export function toGa4Name(name: string): string {
+  const snake = name
+    .trim()
+    .replace(/['"]/g, '')
+    .replace(/[^a-zA-Z0-9]+/g, '_')
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/_+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .toLowerCase()
+  // GA4 names must start with a letter and avoid reserved prefixes.
+  const safe = /^[a-z]/.test(snake) ? snake : `e_${snake}`
+  return GA4_RESERVED_PREFIXES.some((p) => safe.startsWith(p))
+    ? `x_${safe}`
+    : safe
+}
+
+/** Map a Segment call type + name to its GA4 event name. */
+export function ga4EventName(ev: AnalyticsEvent): string | undefined {
+  switch (ev.type) {
+    case 'identify':
+      // identify only sets identity/user_properties — no event is emitted.
+      return undefined
+    case 'page':
+      return 'page_view'
+    case 'screen':
+      return 'screen_view'
+    case 'group':
+      return 'group'
+    case 'alias':
+      return 'alias'
+    case 'track':
+      return ev.event ? toGa4Name(ev.event) : 'track'
+    default:
+      return undefined
+  }
+}
+
+/** Wrap traits as GA4 user_properties (`{ name: { value } }`). */
+function toUserProperties(
+  traits: AnalyticsProperties | undefined,
+): Record<string, { value: unknown }> | undefined {
+  if (!traits) return undefined
+  const out: Record<string, { value: unknown }> = {}
+  let any = false
+  for (const [k, v] of Object.entries(traits)) {
+    if (v === undefined) continue
+    out[toGa4Name(k)] = { value: v }
+    any = true
+  }
+  return any ? out : undefined
+}
+
+/** Build the GA4 event params from a canonical envelope. */
+function toParams(ev: AnalyticsEvent): Record<string, unknown> {
+  const params: Record<string, unknown> = {}
+
+  // Pass through the canonical payload as GA4 params.
+  for (const [k, v] of Object.entries(ev.properties ?? {})) {
+    if (v === undefined) continue
+    params[toGa4Name(k)] = v
+  }
+
+  // Align GA4 sessionisation with our analytics session.
+  params.session_id = ev.sessionId
+  // Stable client-supplied de-dupe / debugging aid.
+  params.engagement_time_msec = params.engagement_time_msec ?? 1
+
+  // page/screen context → GA4 page_* params (Enhanced-Measurement parity).
+  const page = ev.context.page
+  if (ev.type === 'page' || ev.type === 'screen') {
+    if (ev.event) {
+      if (ev.type === 'screen') params.screen_name = ev.event
+      else params.page_title = params.page_title ?? ev.event
+    }
+    if (page?.url && params.page_location === undefined) {
+      params.page_location = page.url
+    }
+    if (page?.path && params.page_path === undefined) {
+      params.page_path = page.path
+    }
+    if (page?.referrer && params.page_referrer === undefined) {
+      params.page_referrer = page.referrer
+    }
+    if (page?.title && params.page_title === undefined) {
+      params.page_title = page.title
+    }
+  }
+
+  if (ev.type === 'group' && ev.groupId) {
+    params.group_id = ev.groupId
+  }
+  if (ev.type === 'alias') {
+    if (ev.userId) params.user_id = ev.userId
+    if (ev.previousId) params.previous_id = ev.previousId
+  }
+
+  return params
+}
+
+/**
+ * Map one canonical envelope to its GA4 representation. Pure — no transport,
+ * no vendor lib; both the gtag and Measurement-Protocol adapters consume this.
+ */
+export function mapEvent(ev: AnalyticsEvent): GA4Mapped {
+  const name = ga4EventName(ev)
+  const mapped: GA4Mapped = {
+    clientId: ev.anonymousId,
+  }
+  if (ev.userId) mapped.userId = ev.userId
+
+  if (ev.type === 'identify' || ev.type === 'group') {
+    const up = toUserProperties(ev.traits)
+    if (up) mapped.userProperties = up
+  }
+
+  if (name) {
+    mapped.event = { name, params: toParams(ev) }
+  }
+  return mapped
+}

package/dist/analytics-sink-ga4/types.ts

@@ -0,0 +1,94 @@
+/**
+ * @refraction-ui/analytics-sink-ga4 — option contracts.
+ *
+ * GA4 is "just a sink" in the epic's model (no privileged engine). This
+ * adapter implements the `AnalyticsSink` SPI from `@refraction-ui/analytics`
+ * in two interchangeable modes:
+ *
+ *   - `client-sdk` — lazy-loads gtag.js in the browser (no hard vendor dep;
+ *     the script is injected on first delivery only). Bridges Consent Mode.
+ *   - `http`       — GA4 Measurement Protocol (`/mp/collect`). No browser
+ *     library is ever loaded — server-relay friendly.
+ *
+ * Default = `http` (protocol adapter, no vendor lib in the browser), matching
+ * the epic's "default = protocol adapters" stance.
+ */
+
+/** Minimal gtag.js function signature (we never import the real types). */
+export type GtagFn = (...args: unknown[]) => void
+
+/** GA4 Consent Mode signal values. */
+export type ConsentState = 'granted' | 'denied'
+
+/**
+ * GA4 Consent Mode bridge — maps our consent categories to the gtag
+ * `consent` command. Only used in `client-sdk` mode.
+ */
+export interface GA4ConsentBridge {
+  /**
+   * Default consent state pushed via `gtag('consent', 'default', …)` before
+   * the GA4 tag loads. Keys are GA4 consent types
+   * (`analytics_storage`, `ad_storage`, `ad_user_data`,
+   * `ad_personalization`, `functionality_storage`, …).
+   */
+  default?: Record<string, ConsentState>
+  /**
+   * Maps a refraction consent category → the GA4 consent types it controls.
+   * When the router reports the sink may deliver (category granted) the
+   * adapter pushes `gtag('consent', 'update', { <types>: 'granted' })`.
+   * Example: `{ analytics: ['analytics_storage'] }`.
+   */
+  map?: Record<string, string[]>
+}
+
+interface GA4CommonOptions {
+  /** GA4 Measurement ID, e.g. `G-XXXXXXXXXX`. */
+  measurementId: string
+  /**
+   * Consent categories this sink requires. The router will not deliver until
+   * all are granted. Default: `['analytics']`.
+   */
+  consentCategories?: string[]
+  /** Stable sink name. Default `'ga4'`. */
+  name?: string
+}
+
+/** `client-sdk` mode — runs gtag.js in the browser. */
+export interface GA4ClientSdkOptions extends GA4CommonOptions {
+  mode: 'client-sdk'
+  /**
+   * Inject the GA4 Consent Mode bridge. The default state (if any) is pushed
+   * before the tag loads; category grants drive `consent: update`.
+   */
+  consentMode?: GA4ConsentBridge
+  /**
+   * Inject an existing gtag function (tests / apps that manage the tag
+   * themselves). When provided, the script loader is NOT used and **no**
+   * vendor script is injected.
+   */
+  gtag?: GtagFn
+  /**
+   * Inject the script loader (tests / SSR-safe apps). Receives the gtag.js
+   * src URL; must resolve once the script has executed. Defaults to a DOM
+   * `<script>` injector (browser only).
+   */
+  scriptLoader?: (src: string) => Promise<void>
+  /** Override the gtag.js base URL (testing). */
+  gtagSrcBase?: string
+}
+
+/** `http` mode — GA4 Measurement Protocol. No browser library. */
+export interface GA4HttpOptions extends GA4CommonOptions {
+  mode?: 'http'
+  /** GA4 Measurement Protocol API secret (server-side credential). */
+  apiSecret: string
+  /** Override the `/mp/collect` base URL (testing / EU endpoint). */
+  endpoint?: string
+  /** Use the Measurement Protocol `/debug/mp/collect` validation endpoint. */
+  debug?: boolean
+  /** Injected fetch (defaults to global fetch). Never loads a vendor lib. */
+  fetchImpl?: typeof fetch
+}
+
+/** Discriminated union of the two modes. */
+export type GA4SinkOptions = GA4ClientSdkOptions | GA4HttpOptions