@refraction-ui/astro 0.6.0 → 0.8.0

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

@@ -0,0 +1,160 @@
+import type {
+  AnalyticsEvent,
+  AnalyticsSink,
+  SinkInitContext,
+} from '../analytics/index.ts'
+import { distinctId } from './mapping.js'
+
+/**
+ * PostHog `client-sdk` sink — OPTIONAL, opt-in mode.
+ *
+ * For client-exclusive PostHog features (autocapture, feature flags,
+ * surveys, web experiments) that the protocol API alone cannot drive.
+ * `posthog-js` is loaded **lazily via dynamic `import()`** the first time the
+ * sink delivers, so a consumer who only uses the default `http` sink never
+ * pays the browser-library cost and `posthog-js` stays a fully optional peer.
+ *
+ * Session replay is deliberately NOT touched here — it lives in the separate
+ * `@refraction-ui/analytics-sink-posthog/replay` module so it is never on the
+ * event path and tree-shakes out unless explicitly enabled.
+ */
+
+/** Minimal structural type for the bits of `posthog-js` we use. */
+interface PostHogJs {
+  init(apiKey: string, options: Record<string, unknown>): void
+  capture(event: string, properties?: Record<string, unknown>): void
+  identify(distinctId: string, set?: Record<string, unknown>): void
+  alias(alias: string, original?: string): void
+  group(
+    groupType: string,
+    groupKey: string,
+    properties?: Record<string, unknown>,
+  ): void
+  reset(): void
+}
+
+export interface PostHogClientSdkSinkOptions {
+  /** PostHog project API key. */
+  apiKey: string
+  /** PostHog API host. Default `https://us.i.posthog.com`. */
+  host?: string
+  /** Sink name. Default `posthog`. */
+  name?: string
+  /** Consent categories this sink requires. Default `['analytics']`. */
+  consentCategories?: string[]
+  /**
+   * Extra `posthog-js` init options. `autocapture`, `capture_pageview`, and
+   * `session_recording` default to OFF — the canonical router owns the event
+   * path; replay is opt-in via the separate module.
+   */
+  posthogOptions?: Record<string, unknown>
+  /**
+   * Injected loader (testing / custom bundling). Defaults to a lazy
+   * `import('posthog-js')`.
+   */
+  loadPostHog?: () => Promise<{ default: PostHogJs } | PostHogJs>
+}
+
+async function defaultLoad(): Promise<PostHogJs> {
+  // Dynamic import keeps `posthog-js` out of the graph until first delivery.
+  const mod = (await import('posthog-js')) as unknown as
+    | { default: PostHogJs }
+    | PostHogJs
+  return 'default' in mod ? mod.default : mod
+}
+
+/**
+ * Create the OPTIONAL PostHog `client-sdk`-mode sink. `posthog-js` is
+ * dynamically imported on first use, never at module load.
+ */
+export function createPostHogClientSdkSink(
+  options: PostHogClientSdkSinkOptions,
+): AnalyticsSink {
+  const {
+    apiKey,
+    host = 'https://us.i.posthog.com',
+    name = 'posthog',
+    consentCategories = ['analytics'],
+    posthogOptions = {},
+  } = options
+
+  let ph: PostHogJs | undefined
+  let loading: Promise<PostHogJs> | undefined
+
+  async function ensure(): Promise<PostHogJs> {
+    if (ph) return ph
+    if (!loading) {
+      const load = options.loadPostHog
+        ? async () => {
+            const m = await options.loadPostHog!()
+            return ('default' in m ? m.default : m) as PostHogJs
+          }
+        : defaultLoad
+      loading = load().then((instance) => {
+        instance.init(apiKey, {
+          api_host: host,
+          // The canonical router owns the event path — disable PostHog's
+          // own auto-capture and pageview, and never start replay here.
+          autocapture: false,
+          capture_pageview: false,
+          disable_session_recording: true,
+          ...posthogOptions,
+        })
+        ph = instance
+        return instance
+      })
+    }
+    return loading
+  }
+
+  return {
+    name,
+    consentCategories,
+
+    async init(_ctx: SinkInitContext): Promise<void> {
+      // Eagerly warm the SDK so the first event is not delayed. Still lazy
+      // relative to module load — only runs once the sink is registered.
+      await ensure()
+    },
+
+    async deliver(batch: AnalyticsEvent[]): Promise<void> {
+      if (batch.length === 0) return
+      const client = await ensure()
+      for (const ev of batch) {
+        const did = distinctId(ev)
+        switch (ev.type) {
+          case 'identify':
+            client.identify(did, { ...(ev.traits ?? {}) })
+            break
+          case 'alias':
+            if (ev.previousId) client.alias(ev.previousId, did)
+            break
+          case 'group':
+            client.group(
+              (ev.properties?.groupType as string) ?? 'company',
+              ev.groupId ?? '',
+              { ...(ev.traits ?? {}) },
+            )
+            break
+          case 'page':
+            client.capture('$pageview', { ...(ev.properties ?? {}) })
+            break
+          case 'screen':
+            client.capture('$screen', {
+              $screen_name: ev.event,
+              ...(ev.properties ?? {}),
+            })
+            break
+          case 'track':
+          default:
+            client.capture(ev.event ?? 'track', { ...(ev.properties ?? {}) })
+            break
+        }
+      }
+    },
+
+    shutdown(): void {
+      ph?.reset()
+    },
+  }
+}

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

@@ -0,0 +1,214 @@
+import type {
+  AnalyticsEvent,
+  AnalyticsSink,
+  SinkDeliverContext,
+} from '../analytics/index.ts'
+import { toPostHogBatch } from './mapping.js'
+
+/**
+ * PostHog `http` sink — the DEFAULT mode.
+ *
+ * Talks to PostHog's ingestion API directly over `fetch`; it never loads
+ * `posthog-js` or any browser library, so it is server-relay friendly and
+ * ad-blocker-proof when fronted by your own endpoint.
+ *
+ *   single event  → POST {host}/capture/   { api_key, event, ... }
+ *   batch         → POST {host}/batch/     { api_key, batch: [...] }
+ *
+ * PostHog accept-and-queue semantics mirror the canonical wire contract:
+ *   2xx        accepted (queued, not processed) → done
+ *   400        malformed       → DROP, never retry
+ *   401 / 403  bad project key → DROP, never retry
+ *   413        payload too big → DROP (we also pre-split under the size caps)
+ *   429 / 5xx  transient       → exponential backoff retry
+ *   network    —               → treated as transient → retry
+ *
+ * No `Authorization` header is used: PostHog authenticates with the public
+ * project API key carried in the JSON body, so the `sendBeacon` unload path
+ * works without any header juggling.
+ */
+
+const NO_RETRY = new Set([400, 401, 403, 413])
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
+
+function byteLength(s: string): number {
+  const g = globalThis as unknown as {
+    TextEncoder?: new () => { encode(s: string): { length: number } }
+  }
+  if (g.TextEncoder) return new g.TextEncoder().encode(s).length
+  return unescape(encodeURIComponent(s)).length
+}
+
+export interface PostHogHttpSinkOptions {
+  /** PostHog project API key (the public, write-only key). */
+  apiKey: string
+  /**
+   * Ingestion host. Default `https://us.i.posthog.com`. Use
+   * `https://eu.i.posthog.com`, a self-hosted host, or — recommended for
+   * production — your own reverse-proxy/relay path.
+   */
+  host?: string
+  /** Sink name. Default `posthog`. */
+  name?: string
+  /** Consent categories this sink requires. Default `['analytics']`. */
+  consentCategories?: string[]
+  /** Max retries for 429/5xx (exponential backoff). Default 3. */
+  maxRetries?: number
+  /** Base backoff delay in ms. Default 500. */
+  backoffBaseMs?: number
+  /** Injected fetch (defaults to global fetch). */
+  fetchImpl?: typeof fetch
+  /** Injected sendBeacon (defaults to navigator.sendBeacon). */
+  beaconImpl?: (url: string, body: string) => boolean
+  /** Soft per-batch byte cap. PostHog limit ≈ 20MB; default 1MB. */
+  maxBatchBytes?: number
+  /** Soft per-event byte cap. Default 32KB. */
+  maxEventBytes?: number
+}
+
+type PostHogBatchItem = ReturnType<typeof toPostHogBatch>[number]
+
+/** Split so neither per-event nor per-batch byte caps are exceeded. */
+function splitBatch(
+  items: PostHogBatchItem[],
+  maxBatchBytes: number,
+  maxEventBytes: number,
+): PostHogBatchItem[][] {
+  const batches: PostHogBatchItem[][] = []
+  let current: PostHogBatchItem[] = []
+  let currentBytes = 2
+
+  for (const item of items) {
+    const itemBytes = byteLength(JSON.stringify(item))
+    // Oversized single events can never be sent — drop them.
+    if (itemBytes > maxEventBytes) continue
+    if (current.length && currentBytes + itemBytes + 1 > maxBatchBytes) {
+      batches.push(current)
+      current = []
+      currentBytes = 2
+    }
+    current.push(item)
+    currentBytes += itemBytes + 1
+  }
+  if (current.length) batches.push(current)
+  return batches
+}
+
+/**
+ * Create the PostHog `http`-mode sink (default). Pure protocol adapter —
+ * no `posthog-js`, safe in Node and the browser.
+ */
+export function createPostHogHttpSink(
+  options: PostHogHttpSinkOptions,
+): AnalyticsSink {
+  const {
+    apiKey,
+    host = 'https://us.i.posthog.com',
+    name = 'posthog',
+    consentCategories = ['analytics'],
+    maxRetries = 3,
+    backoffBaseMs = 500,
+    maxBatchBytes = 1_000_000,
+    maxEventBytes = 32_000,
+  } = options
+
+  const base = host.replace(/\/+$/, '')
+  const captureUrl = `${base}/capture/`
+  const batchUrl = `${base}/batch/`
+
+  const resolveFetch = (): typeof fetch => {
+    if (options.fetchImpl) return options.fetchImpl
+    const f = (globalThis as unknown as { fetch?: typeof fetch }).fetch
+    if (!f) throw new Error('No fetch implementation available')
+    return f
+  }
+
+  const resolveBeacon = ():
+    | ((u: string, body: string) => boolean)
+    | undefined => {
+    if (options.beaconImpl) return options.beaconImpl
+    const nav = (
+      globalThis as unknown as {
+        navigator?: { sendBeacon?: (u: string, data: BodyInit) => boolean }
+      }
+    ).navigator
+    if (nav && typeof nav.sendBeacon === 'function') {
+      return (u, body) => nav.sendBeacon!(u, body)
+    }
+    return undefined
+  }
+
+  function payload(part: PostHogBatchItem[]): {
+    url: string
+    body: string
+  } {
+    if (part.length === 1) {
+      return {
+        url: captureUrl,
+        body: JSON.stringify({ api_key: apiKey, ...part[0] }),
+      }
+    }
+    return {
+      url: batchUrl,
+      body: JSON.stringify({ api_key: apiKey, batch: part }),
+    }
+  }
+
+  async function sendViaFetch(part: PostHogBatchItem[]): Promise<void> {
+    const doFetch = resolveFetch()
+    const { url, body } = payload(part)
+
+    for (let attempt = 0; ; attempt++) {
+      let status: number
+      try {
+        const res = await doFetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body,
+          keepalive: true,
+        })
+        status = res.status
+      } catch {
+        status = 0 // network error → transient
+      }
+
+      if (status >= 200 && status < 300) return
+      if (NO_RETRY.has(status)) return
+
+      if (attempt >= maxRetries) return
+      await sleep(backoffBaseMs * 2 ** attempt)
+    }
+  }
+
+  function sendViaBeacon(part: PostHogBatchItem[]): boolean {
+    const beacon = resolveBeacon()
+    if (!beacon) return false
+    const { url, body } = payload(part)
+    return beacon(url, body)
+  }
+
+  return {
+    name,
+    consentCategories,
+
+    async deliver(
+      batch: AnalyticsEvent[],
+      ctx: SinkDeliverContext,
+    ): Promise<void> {
+      if (batch.length === 0) return
+      const items = toPostHogBatch(batch)
+      const parts = splitBatch(items, maxBatchBytes, maxEventBytes)
+
+      for (const part of parts) {
+        if (part.length === 0) continue
+        if (ctx.unload) {
+          if (sendViaBeacon(part)) continue
+          void sendViaFetch(part)
+        } else {
+          await sendViaFetch(part)
+        }
+      }
+    },
+  }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * @refraction-ui/analytics-sink-posthog
+ *
+ * A PostHog `AnalyticsSink` for `@refraction-ui/analytics`. PostHog is *just
+ * a sink* — register it via `config.sinks` or `analytics.addSink(...)`.
+ *
+ * - `http` mode (DEFAULT): pure protocol adapter against PostHog's
+ *   `/capture` + `/batch` API. No `posthog-js`. Server-relay friendly.
+ * - `client-sdk` mode (OPTIONAL): lazily dynamic-imports `posthog-js`.
+ *
+ * Session replay is intentionally NOT exported here. Import the separate
+ * `@refraction-ui/analytics-sink-posthog/replay` module to opt in — it is
+ * never on the event path and tree-shakes away when unused.
+ */
+
+export { createPostHogSink } from './sink.js'
+export type { PostHogSinkMode, PostHogSinkOptions } from './sink.js'
+
+export { createPostHogHttpSink } from './http-sink.js'
+export type { PostHogHttpSinkOptions } from './http-sink.js'
+
+export { createPostHogClientSdkSink } from './client-sdk-sink.js'
+export type { PostHogClientSdkSinkOptions } from './client-sdk-sink.js'
+
+export { toPostHogEvent, toPostHogBatch, distinctId } from './mapping.js'
+export type { PostHogEvent } from './mapping.js'

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

@@ -0,0 +1,155 @@
+import type { AnalyticsEvent } from '../analytics/index.ts'
+
+/**
+ * Canonical envelope → PostHog event mapping.
+ *
+ * This module is pure (no I/O, no transport) so the http sink and the
+ * client-sdk sink share exactly one mapping definition and it can be unit
+ * tested in isolation against a mock transport.
+ *
+ * PostHog identity model:
+ *   - `distinct_id` is the single id PostHog buckets a person under.
+ *   - Before `identify`, the anonymous visitor is keyed by `anonymousId`.
+ *   - `identify` upgrades the person to the opaque app `userId`, sending
+ *     `$set` traits and an `$anon_distinct_id` so PostHog stitches the
+ *     pre-identify anonymous history onto the identified person.
+ *   - `alias` emits PostHog's `$create_alias` linking `previousId` (alias)
+ *     to the canonical `userId`/`anonymousId` (distinct_id).
+ *   - `group` emits a `$groupidentify` event with `$group_set` traits.
+ *
+ * See https://posthog.com/docs/api/capture for the event shape.
+ */
+
+/** A single PostHog capture event (the `/capture` and `/batch` item shape). */
+export interface PostHogEvent {
+  /** PostHog event name (Segment names map to `$pageview`/`$screen`/etc.). */
+  event: string
+  /** The person bucket id. */
+  distinct_id: string
+  /** Event + person/group properties. */
+  properties: Record<string, unknown>
+  /** ISO-8601 client timestamp (PostHog corrects for skew server-side). */
+  timestamp: string
+  /** Idempotency key — PostHog dedupes on this. Mirrors `messageId`. */
+  uuid: string
+}
+
+/** Resolve the PostHog `distinct_id` for an envelope. */
+export function distinctId(ev: AnalyticsEvent): string {
+  return ev.userId ?? ev.anonymousId
+}
+
+/**
+ * Properties that PostHog reads off `context` for every event so its UI
+ * shows app/library/page/session metadata without the consumer wiring it.
+ */
+function contextProperties(ev: AnalyticsEvent): Record<string, unknown> {
+  const ctx = ev.context
+  const props: Record<string, unknown> = {
+    $lib: ctx.library?.name,
+    $lib_version: ctx.library?.version,
+    app: ctx.app,
+    env: ctx.env,
+    $session_id: ev.sessionId,
+    // Keep the canonical anonymous id addressable in PostHog too.
+    anonymousId: ev.anonymousId,
+  }
+  const page = ctx.page
+  if (page) {
+    if (page.url !== undefined) props.$current_url = page.url
+    if (page.path !== undefined) props.$pathname = page.path
+    if (page.referrer !== undefined) props.$referrer = page.referrer
+    if (page.title !== undefined) props.title = page.title
+    if (page.search !== undefined) props.$search = page.search
+  }
+  return props
+}
+
+/**
+ * Map one canonical envelope to one PostHog event.
+ *
+ * `track`    → the event name verbatim, `properties` passed through.
+ * `page`     → `$pageview` (PostHog's built-in pageview).
+ * `screen`   → `$screen` with `$screen_name`.
+ * `identify` → `$identify` with `$set` traits + `$anon_distinct_id` stitch.
+ * `group`    → `$groupidentify` with `$group_set` traits.
+ * `alias`    → `$create_alias` linking `previousId` → distinct id.
+ */
+export function toPostHogEvent(ev: AnalyticsEvent): PostHogEvent {
+  const base = {
+    distinct_id: distinctId(ev),
+    timestamp: ev.timestamp,
+    uuid: ev.messageId,
+  }
+  const props = contextProperties(ev)
+
+  switch (ev.type) {
+    case 'identify': {
+      return {
+        ...base,
+        event: '$identify',
+        properties: {
+          ...props,
+          $set: { ...(ev.traits ?? {}) },
+          // Stitch the pre-identify anonymous history onto this person.
+          $anon_distinct_id: ev.anonymousId,
+        },
+      }
+    }
+    case 'group': {
+      const groupType = (ev.properties?.groupType as string) ?? 'company'
+      return {
+        ...base,
+        event: '$groupidentify',
+        properties: {
+          ...props,
+          $group_type: groupType,
+          $group_key: ev.groupId,
+          $group_set: { ...(ev.traits ?? {}) },
+        },
+      }
+    }
+    case 'alias': {
+      return {
+        ...base,
+        event: '$create_alias',
+        properties: {
+          ...props,
+          // PostHog links `alias` to the current `distinct_id`.
+          alias: ev.previousId,
+        },
+      }
+    }
+    case 'page': {
+      return {
+        ...base,
+        event: '$pageview',
+        properties: { ...props, ...(ev.properties ?? {}) },
+      }
+    }
+    case 'screen': {
+      return {
+        ...base,
+        event: '$screen',
+        properties: {
+          ...props,
+          $screen_name: ev.event,
+          ...(ev.properties ?? {}),
+        },
+      }
+    }
+    case 'track':
+    default: {
+      return {
+        ...base,
+        event: ev.event ?? 'track',
+        properties: { ...props, ...(ev.properties ?? {}) },
+      }
+    }
+  }
+}
+
+/** Map a batch of canonical envelopes to PostHog events. */
+export function toPostHogBatch(batch: AnalyticsEvent[]): PostHogEvent[] {
+  return batch.map(toPostHogEvent)
+}

package/dist/analytics-sink-posthog/replay.ts

@@ -0,0 +1,152 @@
+/**
+ * @refraction-ui/analytics-sink-posthog/replay
+ *
+ * OPTIONAL, lazy session-replay (rrweb, via `posthog-js`).
+ *
+ * Hard guarantees this module exists to enforce:
+ *
+ *  1. **Off by default.** Nothing in the main `@refraction-ui/analytics-sink-posthog`
+ *     entry imports this file, so it (and `posthog-js`, and rrweb) are fully
+ *     tree-shaken out of any bundle that does not explicitly import it.
+ *  2. **Never on the event path.** Replay is not an `AnalyticsSink`. It does
+ *     not see, transform, or block canonical envelopes. `track`/`identify`/…
+ *     keep flowing through the sink even if replay never starts or fails.
+ *  3. **Privacy/consent gated.** `startSessionReplay` refuses to start unless
+ *     a consent predicate returns true, and re-checks it; `stop()` tears the
+ *     recorder down. Masking defaults are maximally private.
+ *  4. **Lazy.** `posthog-js` is `import()`-ed only when `startSessionReplay`
+ *     is actually called.
+ *
+ * This is a thin controller around `posthog-js`'s built-in rrweb session
+ * recording — we do not bundle rrweb ourselves.
+ */
+
+/** Minimal structural view of the `posthog-js` replay surface. */
+interface PostHogReplay {
+  init(apiKey: string, options: Record<string, unknown>): void
+  startSessionRecording(): void
+  stopSessionRecording(): void
+  sessionRecordingStarted?(): boolean
+}
+
+export interface SessionReplayOptions {
+  /** PostHog project API key. */
+  apiKey: string
+  /** PostHog API host. Default `https://us.i.posthog.com`. */
+  host?: string
+  /**
+   * Consent predicate. Replay starts ONLY when this returns `true`, and is
+   * re-checked by `enforceConsent()`. There is no default-allow: if omitted,
+   * replay is treated as NOT consented and will not start.
+   */
+  hasConsent?: () => boolean
+  /**
+   * rrweb masking. Defaults are maximally private: all text + all inputs
+   * masked. Override deliberately and document the privacy review.
+   */
+  maskAllText?: boolean
+  maskAllInputs?: boolean
+  /** Extra `posthog-js` session_recording options (advanced). */
+  recordingOptions?: Record<string, unknown>
+  /**
+   * Injected loader (testing / custom bundling). Defaults to a lazy
+   * `import('posthog-js')`.
+   */
+  loadPostHog?: () => Promise<{ default: PostHogReplay } | PostHogReplay>
+}
+
+/** Handle returned by {@link startSessionReplay}. */
+export interface SessionReplayHandle {
+  /** True if the rrweb recorder is currently running. */
+  readonly recording: boolean
+  /**
+   * Re-evaluate the consent predicate. If consent was revoked, recording is
+   * stopped. Call this from your consent-change handler.
+   */
+  enforceConsent(): void
+  /** Stop recording and release the recorder. Idempotent. */
+  stop(): void
+}
+
+async function defaultLoad(): Promise<PostHogReplay> {
+  const mod = (await import('posthog-js')) as unknown as
+    | { default: PostHogReplay }
+    | PostHogReplay
+  return 'default' in mod ? mod.default : mod
+}
+
+/**
+ * Start PostHog/rrweb session replay. Resolves to a handle, or to a
+ * non-recording handle if consent is not granted (it never throws on the
+ * consent path — replay simply does not start).
+ *
+ * `posthog-js` is dynamically imported here and nowhere else.
+ */
+export async function startSessionReplay(
+  options: SessionReplayOptions,
+): Promise<SessionReplayHandle> {
+  const {
+    apiKey,
+    host = 'https://us.i.posthog.com',
+    hasConsent,
+    maskAllText = true,
+    maskAllInputs = true,
+    recordingOptions = {},
+  } = options
+
+  const consented = (): boolean =>
+    typeof hasConsent === 'function' ? hasConsent() === true : false
+
+  // Single-slot holder so the closure can observe the lazily-loaded
+  // instance without an outer `let` rebind.
+  const slot: { ph?: PostHogReplay } = {}
+  let recording = false
+
+  const stop = (): void => {
+    if (slot.ph && recording) {
+      slot.ph.stopSessionRecording()
+    }
+    recording = false
+  }
+
+  const handle: SessionReplayHandle = {
+    get recording() {
+      return recording
+    },
+    enforceConsent(): void {
+      if (!consented()) stop()
+    },
+    stop,
+  }
+
+  // Privacy gate: do not even load posthog-js if consent is absent.
+  if (!consented()) return handle
+
+  const load = options.loadPostHog
+    ? async () => {
+        const m = await options.loadPostHog!()
+        return ('default' in m ? m.default : m) as PostHogReplay
+      }
+    : defaultLoad
+
+  slot.ph = await load()
+  slot.ph.init(apiKey, {
+    api_host: host,
+    autocapture: false,
+    capture_pageview: false,
+    // Start with replay disabled, then opt in explicitly below.
+    disable_session_recording: true,
+    session_recording: {
+      maskAllInputs,
+      maskTextSelector: maskAllText ? '*' : undefined,
+      ...recordingOptions,
+    },
+  })
+
+  // Re-check consent after the (async) load in case it was revoked meanwhile.
+  if (!consented()) return handle
+
+  slot.ph.startSessionRecording()
+  recording = slot.ph.sessionRecordingStarted?.() ?? true
+  return handle
+}