@refraction-ui/astro 0.5.1 → 0.6.0

package/dist/analytics/identity.ts

@@ -0,0 +1,64 @@
+import type { AnalyticsStorage, IdentityConfig } from './types.js'
+import { resolveStorage } from './storage.js'
+import { uuidv4, isUuidV4 } from './uuid.js'
+
+const DEFAULT_KEY = 'rfx:analytics:anon'
+
+/**
+ * Identity engine.
+ *
+ * - `anonymousId`: persistent, non-PII, resettable UUIDv4 stored cross-tab.
+ * - `userId`: opaque, app-supplied; never persisted by the library (the app
+ *   owns the user record) — kept only in memory for the active page.
+ * - `alias`: records a previous→current stitch for the wire envelope.
+ */
+export function createIdentity(config?: IdentityConfig) {
+  const storage: AnalyticsStorage = resolveStorage(config?.storage)
+  const key = config?.storageKey ?? DEFAULT_KEY
+
+  let userId: string | undefined
+
+  function loadOrMintAnon(): string {
+    const existing = storage.get(key)
+    if (isUuidV4(existing)) return existing as string
+    const fresh = uuidv4()
+    storage.set(key, fresh)
+    return fresh
+  }
+
+  let anonymousId = loadOrMintAnon()
+
+  return {
+    anonymousId(): string {
+      return anonymousId
+    },
+    userId(): string | undefined {
+      return userId
+    },
+    /** identify(): bind an opaque app user id (no validation, no persistence). */
+    setUserId(id: string): void {
+      userId = id
+    },
+    /**
+     * alias(): returns the stitch pair for the envelope. `previousId`
+     * defaults to the current user or anonymous id.
+     */
+    alias(nextUserId: string, previousId?: string): { userId: string; previousId: string } {
+      const prev = previousId ?? userId ?? anonymousId
+      userId = nextUserId
+      return { userId: nextUserId, previousId: prev }
+    },
+    /**
+     * reset(): privacy-safe logout. Drops the user binding and mints a brand
+     * new anonymousId so the next visitor is not stitched to the old one.
+     */
+    reset(): string {
+      userId = undefined
+      anonymousId = uuidv4()
+      storage.set(key, anonymousId)
+      return anonymousId
+    },
+  }
+}
+
+export type Identity = ReturnType<typeof createIdentity>

package/dist/analytics/index.ts

@@ -0,0 +1,60 @@
+// Types
+export type {
+  Analytics,
+  AnalyticsConfig,
+  AnalyticsEvent,
+  AnalyticsEventType,
+  AnalyticsProperties,
+  AnalyticsContext,
+  AnalyticsSink,
+  AnalyticsStorage,
+  SinkInitContext,
+  SinkDeliverContext,
+  SessionConfig,
+  SessionAPI,
+  IdentityConfig,
+  ConsentConfig,
+  ConsentAPI,
+  HttpSinkOptions,
+  CallOptions,
+} from './types.js'
+export { SCHEMA_VERSION } from './types.js'
+
+// Manager
+export { createAnalytics } from './analytics-manager.js'
+
+// Built-in sinks
+export { createHttpSink } from './http-sink.js'
+export { createConsoleSink } from './console-sink.js'
+export type { ConsoleSinkOptions } from './console-sink.js'
+
+// Mock sink (for testing)
+export { createMockSink } from './mock-sink.js'
+export type { MockSink, CreateMockSinkOptions } from './mock-sink.js'
+
+// Engines (advanced / standalone use)
+export {
+  createSession,
+  campaignFingerprint,
+  DEFAULT_SESSION_TIMEOUT_MS,
+} from './session.js'
+export { createIdentity } from './identity.js'
+export { createConsent } from './consent.js'
+export {
+  createRedactor,
+  PII_DENY_LIST,
+  PII_EXACT_KEYS,
+  REDACTED,
+} from './redaction.js'
+export type { Redactor } from './redaction.js'
+
+// Storage adapters
+export {
+  createMemoryStorage,
+  createLocalStorageAdapter,
+  createCookieAdapter,
+  resolveStorage,
+} from './storage.js'
+
+// Utilities
+export { uuidv4, isUuidV4, UUID_V4_RE } from './uuid.js'

package/dist/analytics/mock-sink.ts

@@ -0,0 +1,62 @@
+import type {
+  AnalyticsEvent,
+  AnalyticsSink,
+  SinkDeliverContext,
+  SinkInitContext,
+} from './types.js'
+
+/** A mock sink that records every call — used for testing the router. */
+export interface MockSink extends AnalyticsSink {
+  /** All events received across all deliver() calls (flattened). */
+  events: AnalyticsEvent[]
+  /** Each deliver() call's batch + context. */
+  deliveries: Array<{ batch: AnalyticsEvent[]; ctx: SinkDeliverContext }>
+  /** init() call contexts. */
+  initCalls: SinkInitContext[]
+  /** flush() invocation count. */
+  flushCalls: number
+  /** shutdown() invocation count. */
+  shutdownCalls: number
+}
+
+export interface CreateMockSinkOptions {
+  name?: string
+  consentCategories?: string[]
+}
+
+/**
+ * createMockSink — an `AnalyticsSink` that captures everything for assertion.
+ * Mirrors the testing ergonomics of `@refraction-ui/ai`'s mock providers.
+ */
+export function createMockSink(
+  options: CreateMockSinkOptions = {},
+): MockSink {
+  const sink: MockSink = {
+    name: options.name ?? 'mock',
+    consentCategories: options.consentCategories,
+    events: [],
+    deliveries: [],
+    initCalls: [],
+    flushCalls: 0,
+    shutdownCalls: 0,
+
+    init(ctx: SinkInitContext): void {
+      sink.initCalls.push(ctx)
+    },
+
+    deliver(batch: AnalyticsEvent[], ctx: SinkDeliverContext): void {
+      sink.deliveries.push({ batch, ctx })
+      for (const ev of batch) sink.events.push(ev)
+    },
+
+    flush(): void {
+      sink.flushCalls++
+    },
+
+    shutdown(): void {
+      sink.shutdownCalls++
+    },
+  }
+
+  return sink
+}

package/dist/analytics/noop.ts

@@ -0,0 +1,48 @@
+import type { Analytics } from './types.js'
+
+/**
+ * The noop collector returned when `enabled: false`.
+ *
+ * Every method is an empty function so calls are free and the surrounding
+ * vendor/sink code can be tree-shaken out of a production bundle when
+ * analytics is compiled off. Kept in its own module so bundlers can drop the
+ * live collector entirely on the `enabled:false` path.
+ */
+export function createNoopAnalytics(): Analytics {
+  const sessionId = '00000000-0000-4000-8000-000000000000'
+  const noop = (): void => {}
+
+  const api: Analytics = {
+    track: noop,
+    identify: noop,
+    page: noop,
+    screen: noop,
+    group: noop,
+    alias: noop,
+    session: {
+      id: () => sessionId,
+      start: () => sessionId,
+      end: noop,
+      set: noop,
+    },
+    consent: {
+      grant: noop,
+      revoke: noop,
+      granted: () => [],
+      isGranted: () => false,
+    },
+    anonymousId: () => sessionId,
+    userId: () => undefined,
+    with: () => api,
+    addSink: noop,
+    removeSink: noop,
+    get sinks() {
+      return []
+    },
+    flush: async () => {},
+    reset: noop,
+    enabled: false,
+  }
+
+  return api
+}

package/dist/analytics/redaction.ts

@@ -0,0 +1,93 @@
+import type { AnalyticsProperties } from './types.js'
+
+/**
+ * PII redaction.
+ *
+ * A built-in deny-list of well-known PII key names (email/phone/name and
+ * common variants) plus any caller-supplied `redactKeys`. Matching is
+ * case-insensitive and substring-based so `userEmail`, `email_address`,
+ * `phoneNumber`, `fullName`, etc. are all caught. Redaction recurses into
+ * nested objects and arrays so PII cannot hide one level down.
+ */
+
+/**
+ * Built-in PII deny-list (substring, case-insensitive, separator-insensitive).
+ * These match anywhere in a key, so `userEmail`, `email_address`,
+ * `phoneNumber`, `firstName`, etc. are all caught.
+ */
+export const PII_DENY_LIST: readonly string[] = [
+  'email',
+  'phone',
+  'mobile',
+  'firstname',
+  'lastname',
+  'fullname',
+  'givenname',
+  'surname',
+  'password',
+  'passwd',
+  'ssn',
+  'creditcard',
+  'cardnumber',
+  'cvv',
+  'dob',
+  'dateofbirth',
+  'address',
+]
+
+/**
+ * Keys that are PII only as an *exact* (normalised) match. `name` belongs
+ * here so genuine name fields redact while `username`, `eventName`,
+ * `fileName`, `firstName`-style compounds (handled by the deny-list) do not
+ * over-redact every key that merely contains "name".
+ */
+export const PII_EXACT_KEYS: readonly string[] = ['name']
+
+/** Replacement token written in place of a redacted value. */
+export const REDACTED = '[REDACTED]'
+
+function normalize(key: string): string {
+  return key.toLowerCase().replace(/[_\-\s]/g, '')
+}
+
+/**
+ * Build a key matcher from the deny-list + extra keys. `extra` entries match
+ * exactly (case-insensitive, normalised); deny-list entries match as
+ * substrings.
+ */
+export function createRedactor(extraKeys: string[] = []) {
+  const exact = new Set([
+    ...extraKeys.map(normalize),
+    ...PII_EXACT_KEYS.map(normalize),
+  ])
+  const deny = PII_DENY_LIST.map(normalize)
+
+  const shouldRedact = (key: string): boolean => {
+    const n = normalize(key)
+    if (exact.has(n)) return true
+    return deny.some((d) => n.includes(d))
+  }
+
+  const walk = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(walk)
+    if (value && typeof value === 'object') {
+      const out: Record<string, unknown> = {}
+      for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+        out[k] = shouldRedact(k) ? REDACTED : walk(v)
+      }
+      return out
+    }
+    return value
+  }
+
+  return {
+    shouldRedact,
+    /** Redact a properties/traits bag (returns a new object). */
+    redact(props?: AnalyticsProperties): AnalyticsProperties | undefined {
+      if (!props) return props
+      return walk(props) as AnalyticsProperties
+    },
+  }
+}
+
+export type Redactor = ReturnType<typeof createRedactor>

package/dist/analytics/session.ts

@@ -0,0 +1,162 @@
+import type {
+  AnalyticsProperties,
+  AnalyticsStorage,
+  SessionConfig,
+} from './types.js'
+import { resolveStorage } from './storage.js'
+import { uuidv4 } from './uuid.js'
+
+/** GA4 parity: 30 minutes of inactivity ends a session. */
+export const DEFAULT_SESSION_TIMEOUT_MS = 30 * 60 * 1000
+
+const DEFAULT_KEY = 'rfx:analytics:session'
+
+interface PersistedSession {
+  id: string
+  /** Last activity epoch ms. */
+  lastActivity: number
+  /** Campaign fingerprint at session start (for campaign-reset). */
+  campaign?: string
+  /** Session-scoped properties (set via session.set). */
+  props?: AnalyticsProperties
+}
+
+/** Recognised campaign params (UTM + common click ids). GA4 parity. */
+const CAMPAIGN_PARAMS = [
+  'utm_source',
+  'utm_medium',
+  'utm_campaign',
+  'utm_term',
+  'utm_content',
+  'gclid',
+  'fbclid',
+  'msclkid',
+]
+
+/**
+ * Derive a stable campaign fingerprint from a URL's query string. A change in
+ * this fingerprint (a *new* campaign, not its absence) forces a new session,
+ * matching GA4's "campaign change resets the session" behaviour.
+ */
+export function campaignFingerprint(search?: string): string | undefined {
+  if (!search) return undefined
+  let qs = search
+  const q = qs.indexOf('?')
+  if (q !== -1) qs = qs.slice(q + 1)
+  let params: URLSearchParams
+  try {
+    params = new URLSearchParams(qs)
+  } catch {
+    return undefined
+  }
+  const pairs: string[] = []
+  for (const p of CAMPAIGN_PARAMS) {
+    const v = params.get(p)
+    if (v) pairs.push(`${p}=${v}`)
+  }
+  return pairs.length ? pairs.join('&') : undefined
+}
+
+/**
+ * Session engine.
+ *
+ * A session is a span of continuous activity. It ends after `timeoutMs` of
+ * inactivity (GA4 parity, default 30 min) or when a *new* campaign is
+ * detected. State is persisted cross-tab so multiple tabs share one session.
+ */
+export function createSession(
+  config?: SessionConfig,
+  now: () => number = () => Date.now(),
+) {
+  const storage: AnalyticsStorage = resolveStorage(config?.storage)
+  const key = config?.storageKey ?? DEFAULT_KEY
+  const timeoutMs = config?.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS
+  const resetOnCampaign = config?.resetOnCampaign ?? true
+
+  function read(): PersistedSession | null {
+    const raw = storage.get(key)
+    if (!raw) return null
+    try {
+      const parsed = JSON.parse(raw) as PersistedSession
+      if (parsed && typeof parsed.id === 'string') return parsed
+    } catch {
+      /* corrupt — treat as none */
+    }
+    return null
+  }
+
+  function write(s: PersistedSession): void {
+    storage.set(key, JSON.stringify(s))
+  }
+
+  function mint(campaign?: string): PersistedSession {
+    const s: PersistedSession = {
+      id: uuidv4(),
+      lastActivity: now(),
+      campaign,
+    }
+    write(s)
+    return s
+  }
+
+  /**
+   * Return the live session, creating/rotating it as required by the
+   * inactivity timeout and (optionally) a campaign change.
+   */
+  function ensure(campaign?: string): PersistedSession {
+    const existing = read()
+    const t = now()
+
+    if (!existing) return mint(campaign)
+
+    // Inactivity timeout.
+    if (t - existing.lastActivity > timeoutMs) {
+      return mint(campaign)
+    }
+
+    // Campaign reset — only when a *new* campaign appears.
+    if (
+      resetOnCampaign &&
+      campaign !== undefined &&
+      existing.campaign !== campaign
+    ) {
+      return mint(campaign)
+    }
+
+    return existing
+  }
+
+  return {
+    /** Get the current session id, rotating if expired. */
+    id(campaign?: string): string {
+      return ensure(campaign).id
+    },
+    /** Force a brand-new session. */
+    start(campaign?: string): string {
+      return mint(campaign).id
+    },
+    /** End the current session (next id() mints a fresh one). */
+    end(): void {
+      storage.remove(key)
+    },
+    /** Touch activity so the inactivity window slides forward. */
+    touch(campaign?: string): string {
+      const s = ensure(campaign)
+      s.lastActivity = now()
+      write(s)
+      return s.id
+    },
+    /** Attach/merge session-scoped properties. */
+    set(props: AnalyticsProperties): void {
+      const s = ensure()
+      s.props = { ...(s.props ?? {}), ...props }
+      write(s)
+    },
+    /** Read session-scoped properties (undefined when none). */
+    props(): AnalyticsProperties | undefined {
+      return read()?.props
+    },
+  }
+}
+
+export type Session = ReturnType<typeof createSession>

package/dist/analytics/storage.ts

@@ -0,0 +1,119 @@
+import type { AnalyticsStorage } from './types.js'
+
+/**
+ * Storage adapters.
+ *
+ * Order of preference for the cross-tab default: localStorage → cookie →
+ * in-memory. The package is environment-agnostic; consumers can inject any
+ * `AnalyticsStorage` (e.g. an RN AsyncStorage shim) via config.
+ */
+
+/** Volatile per-process store (SSR / Node / no-DOM fallback). */
+export function createMemoryStorage(): AnalyticsStorage {
+  const map = new Map<string, string>()
+  return {
+    get: (k) => (map.has(k) ? (map.get(k) as string) : null),
+    set: (k, v) => {
+      map.set(k, v)
+    },
+    remove: (k) => {
+      map.delete(k)
+    },
+  }
+}
+
+/** `window.localStorage` adapter (cross-tab via the storage event). */
+export function createLocalStorageAdapter(
+  ls: Storage,
+): AnalyticsStorage {
+  return {
+    get: (k) => {
+      try {
+        return ls.getItem(k)
+      } catch {
+        return null
+      }
+    },
+    set: (k, v) => {
+      try {
+        ls.setItem(k, v)
+      } catch {
+        /* quota / disabled — degrade silently */
+      }
+    },
+    remove: (k) => {
+      try {
+        ls.removeItem(k)
+      } catch {
+        /* ignore */
+      }
+    },
+  }
+}
+
+interface CookieDoc {
+  cookie: string
+}
+
+/** `document.cookie` adapter (cross-tab + cross-subdomain capable). */
+export function createCookieAdapter(
+  doc: CookieDoc,
+  maxAgeSeconds = 60 * 60 * 24 * 365,
+): AnalyticsStorage {
+  const read = (k: string): string | null => {
+    const target = encodeURIComponent(k) + '='
+    const parts = doc.cookie ? doc.cookie.split(';') : []
+    for (const part of parts) {
+      const c = part.trim()
+      if (c.startsWith(target)) {
+        return decodeURIComponent(c.slice(target.length))
+      }
+    }
+    return null
+  }
+  return {
+    get: read,
+    set: (k, v) => {
+      doc.cookie = `${encodeURIComponent(k)}=${encodeURIComponent(
+        v,
+      )}; path=/; max-age=${maxAgeSeconds}; SameSite=Lax`
+    },
+    remove: (k) => {
+      doc.cookie = `${encodeURIComponent(k)}=; path=/; max-age=0; SameSite=Lax`
+    },
+  }
+}
+
+/**
+ * Resolve the default storage for the current environment. A caller-supplied
+ * storage always wins. Browser → localStorage (falls back to cookie if
+ * localStorage throws), otherwise in-memory.
+ */
+export function resolveStorage(
+  override?: AnalyticsStorage,
+): AnalyticsStorage {
+  if (override) return override
+
+  const g = globalThis as unknown as {
+    localStorage?: Storage
+    document?: CookieDoc
+  }
+
+  if (g.localStorage) {
+    try {
+      // Probe — Safari private mode throws on setItem.
+      const probe = '__rfx_a_probe__'
+      g.localStorage.setItem(probe, '1')
+      g.localStorage.removeItem(probe)
+      return createLocalStorageAdapter(g.localStorage)
+    } catch {
+      /* fall through to cookie */
+    }
+  }
+
+  if (g.document && typeof g.document.cookie === 'string') {
+    return createCookieAdapter(g.document)
+  }
+
+  return createMemoryStorage()
+}