@refraction-ui/astro 0.5.0 → 0.6.0

package/dist/analytics/analytics-manager.ts

@@ -0,0 +1,361 @@
+import type {
+  Analytics,
+  AnalyticsConfig,
+  AnalyticsContext,
+  AnalyticsEvent,
+  AnalyticsEventType,
+  AnalyticsSink,
+  CallOptions,
+  SinkDeliverContext,
+} from './types.js'
+import { SCHEMA_VERSION } from './types.js'
+import { uuidv4 } from './uuid.js'
+import { createSession, campaignFingerprint } from './session.js'
+import { createIdentity } from './identity.js'
+import { createConsent } from './consent.js'
+import { createRedactor } from './redaction.js'
+import { createHttpSink } from './http-sink.js'
+import { createConsoleSink } from './console-sink.js'
+import { createNoopAnalytics } from './noop.js'
+
+const LIBRARY = {
+  name: '@refraction-ui/analytics',
+  version: '0.1.0',
+}
+
+/** Read the current page block from the DOM, if any (browser-only). */
+function readPage(): AnalyticsContext['page'] | undefined {
+  const g = globalThis as unknown as {
+    location?: { pathname?: string; href?: string; search?: string }
+    document?: { title?: string; referrer?: string }
+  }
+  if (!g.location && !g.document) return undefined
+  return {
+    path: g.location?.pathname,
+    url: g.location?.href,
+    search: g.location?.search,
+    title: g.document?.title,
+    referrer: g.document?.referrer,
+  }
+}
+
+/**
+ * createAnalytics — the neutral Segment-spec collector/router.
+ *
+ * Mirrors `createAI`: a single factory returns the entire public surface and
+ * fans the canonical envelope out to registered sinks. There is NO privileged
+ * engine — the built-in HTTP sink and every vendor adapter are equal sinks.
+ *
+ * Presets:
+ *   dev  — synchronous delivery + a console sink (see exactly what ships).
+ *   prod — batching + sampling + beacon flush on pagehide/visibilitychange.
+ *
+ * When `enabled: false`, a tree-shakeable noop is returned and none of the
+ * live collector / sink code is reachable.
+ */
+export function createAnalytics(config: AnalyticsConfig): Analytics {
+  if (config.enabled === false) {
+    return createNoopAnalytics()
+  }
+
+  const { app, env } = config
+  const preset =
+    config.preset ?? (env === 'production' ? 'prod' : 'dev')
+  const sampleRate = config.sampleRate ?? 1
+  const batchSize = config.batchSize ?? 20
+  const flushIntervalMs = config.flushIntervalMs ?? 10_000
+
+  const session = createSession(config.session)
+  const identity = createIdentity(config.identity)
+  const consent = createConsent(config.consent)
+  const redactor = createRedactor(config.redactKeys)
+
+  // --- Sink registry ------------------------------------------------------
+  const sinks = new Map<string, AnalyticsSink>()
+  const sinkOrder: string[] = []
+  const initialized = new Set<string>()
+
+  function registerSink(sink: AnalyticsSink): void {
+    if (!sinks.has(sink.name)) sinkOrder.push(sink.name)
+    sinks.set(sink.name, sink)
+  }
+
+  // Auto HTTP sink when an endpoint is supplied.
+  if (config.endpoint) {
+    registerSink(
+      createHttpSink({
+        endpoint: config.endpoint,
+        writeKey: config.writeKey ?? '',
+      }),
+    )
+  }
+  // dev preset → add a console sink for visibility.
+  if (preset === 'dev') {
+    registerSink(createConsoleSink())
+  }
+  // Explicit sinks (override same-named built-ins).
+  for (const s of config.sinks ?? []) registerSink(s)
+
+  /**
+   * Initialise a sink at most once. Returns a promise only when the sink's
+   * own `init` is async — synchronous sinks stay on the synchronous path so
+   * the dev preset delivers without a microtask hop.
+   */
+  function ensureInit(sink: AnalyticsSink): void | Promise<void> {
+    if (initialized.has(sink.name)) return
+    initialized.add(sink.name)
+    if (sink.init) {
+      return sink.init({ app, env, endpoint: config.endpoint })
+    }
+  }
+
+  // --- Batch buffer -------------------------------------------------------
+  const buffer: AnalyticsEvent[] = []
+  let timer: ReturnType<typeof setInterval> | undefined
+
+  function startTimer(): void {
+    if (preset !== 'prod' || timer) return
+    timer = setInterval(() => {
+      void flush(false)
+    }, flushIntervalMs)
+    // Do not keep a Node process alive purely for the flush timer.
+    ;(timer as unknown as { unref?: () => void }).unref?.()
+  }
+
+  /**
+   * Fan a batch out to every consented sink. Stays fully synchronous when all
+   * sinks are synchronous (dev preset visibility); returns a promise only if a
+   * sink's init/deliver is async.
+   */
+  function deliverToSinks(
+    batch: AnalyticsEvent[],
+    unload: boolean,
+  ): void | Promise<void> {
+    if (batch.length === 0) return
+    const ctx: SinkDeliverContext = { unload }
+    const pending: Array<Promise<unknown>> = []
+    for (const name of sinkOrder) {
+      const sink = sinks.get(name)
+      if (!sink) continue
+      if (!consent.allows(sink.consentCategories)) continue
+      const inited = ensureInit(sink)
+      if (inited && typeof (inited as Promise<void>).then === 'function') {
+        pending.push(
+          (inited as Promise<void>).then(() => sink.deliver(batch, ctx)),
+        )
+      } else {
+        const r = sink.deliver(batch, ctx)
+        if (r && typeof (r as Promise<void>).then === 'function') {
+          pending.push(r as Promise<void>)
+        }
+      }
+    }
+    if (pending.length) return Promise.all(pending).then(() => undefined)
+  }
+
+  async function flush(unload = false): Promise<void> {
+    const batch = buffer.splice(0, buffer.length)
+    await deliverToSinks(batch, unload)
+    for (const name of sinkOrder) {
+      const sink = sinks.get(name)
+      if (sink?.flush && consent.allows(sink.consentCategories)) {
+        await sink.flush()
+      }
+    }
+  }
+
+  // --- Unload flush (prod) ------------------------------------------------
+  function bindUnload(): void {
+    if (preset !== 'prod') return
+    const g = globalThis as unknown as {
+      addEventListener?: (t: string, h: () => void) => void
+      document?: { visibilityState?: string }
+    }
+    if (typeof g.addEventListener !== 'function') return
+    const onUnload = (): void => {
+      void deliverToSinks(buffer.splice(0, buffer.length), true)
+    }
+    g.addEventListener('pagehide', onUnload)
+    g.addEventListener('visibilitychange', () => {
+      if (g.document?.visibilityState === 'hidden') onUnload()
+    })
+  }
+
+  startTimer()
+  bindUnload()
+
+  // --- Envelope construction ---------------------------------------------
+  function buildContext(
+    extra?: Partial<AnalyticsContext>,
+    childCtx?: Partial<AnalyticsContext>,
+  ): AnalyticsContext {
+    const page = readPage()
+    return {
+      app,
+      env,
+      ...(page ? { page } : {}),
+      ...childCtx,
+      ...extra,
+      library: LIBRARY,
+    }
+  }
+
+  function sampled(): boolean {
+    if (sampleRate >= 1) return true
+    if (sampleRate <= 0) return false
+    return Math.random() < sampleRate
+  }
+
+  function enqueue(ev: AnalyticsEvent): void {
+    if (preset === 'dev') {
+      // Synchronous, unbatched — immediate visibility.
+      void deliverToSinks([ev], false)
+      return
+    }
+    buffer.push(ev)
+    if (buffer.length >= batchSize) {
+      void flush(false)
+    }
+  }
+
+  function emit(
+    type: AnalyticsEventType,
+    fields: Partial<AnalyticsEvent>,
+    childCtx: Partial<AnalyticsContext> | undefined,
+    opts?: CallOptions,
+  ): void {
+    if (!sampled()) return
+
+    const page = readPage()
+    const campaign = campaignFingerprint(page?.search)
+    const sessionId = session.touch(campaign)
+    const sessionProps = session.props()
+
+    const ev: AnalyticsEvent = {
+      type,
+      messageId: uuidv4(),
+      anonymousId: identity.anonymousId(),
+      userId: identity.userId(),
+      sessionId,
+      context: buildContext(opts?.context, childCtx),
+      timestamp: opts?.timestamp ?? new Date().toISOString(),
+      schemaVersion: SCHEMA_VERSION,
+      ...fields,
+    }
+
+    // Merge session-scoped props beneath call props.
+    if (sessionProps && (ev.properties || type === 'track' || type === 'page' || type === 'screen')) {
+      ev.properties = { ...sessionProps, ...(ev.properties ?? {}) }
+    }
+
+    enqueue(ev)
+  }
+
+  function makeApi(childCtx?: Partial<AnalyticsContext>): Analytics {
+    const api: Analytics = {
+      track(event, properties, opts) {
+        emit(
+          'track',
+          { event, properties: redactor.redact(properties) },
+          childCtx,
+          opts,
+        )
+      },
+
+      identify(userId, traits, opts) {
+        identity.setUserId(userId)
+        emit('identify', { traits: redactor.redact(traits) }, childCtx, opts)
+      },
+
+      page(name, properties, opts) {
+        emit(
+          'page',
+          { event: name, properties: redactor.redact(properties) },
+          childCtx,
+          opts,
+        )
+      },
+
+      screen(name, properties, opts) {
+        emit(
+          'screen',
+          { event: name, properties: redactor.redact(properties) },
+          childCtx,
+          opts,
+        )
+      },
+
+      group(groupId, traits, opts) {
+        emit(
+          'group',
+          { groupId, traits: redactor.redact(traits) },
+          childCtx,
+          opts,
+        )
+      },
+
+      alias(userId, previousId, opts) {
+        const stitch = identity.alias(userId, previousId)
+        emit(
+          'alias',
+          { userId: stitch.userId, previousId: stitch.previousId },
+          childCtx,
+          opts,
+        )
+      },
+
+      session: {
+        id: () => session.id(),
+        start: () => session.start(),
+        end: () => session.end(),
+        set: (props) => session.set(props),
+      },
+
+      consent: {
+        grant: (...c) => consent.grant(...c),
+        revoke: (...c) => consent.revoke(...c),
+        granted: () => consent.granted(),
+        isGranted: (c) => consent.isGranted(c),
+      },
+
+      anonymousId: () => identity.anonymousId(),
+      userId: () => identity.userId(),
+
+      with(extra: Partial<AnalyticsContext>): Analytics {
+        return makeApi({ ...childCtx, ...extra })
+      },
+
+      addSink(sink: AnalyticsSink): void {
+        registerSink(sink)
+      },
+
+      removeSink(name: string): void {
+        if (sinks.has(name)) {
+          sinks.delete(name)
+          const i = sinkOrder.indexOf(name)
+          if (i !== -1) sinkOrder.splice(i, 1)
+          initialized.delete(name)
+        }
+      },
+
+      get sinks(): string[] {
+        return [...sinkOrder]
+      },
+
+      async flush(): Promise<void> {
+        await flush(false)
+      },
+
+      reset(): void {
+        identity.reset()
+        session.end()
+      },
+
+      enabled: true,
+    }
+
+    return api
+  }
+
+  return makeApi()
+}

package/dist/analytics/consent.ts

@@ -0,0 +1,40 @@
+import type { ConsentAPI, ConsentConfig } from './types.js'
+
+/**
+ * Consent gate.
+ *
+ * Holds the set of granted consent categories. The router asks the gate, per
+ * sink, whether *all* of that sink's required categories are granted before
+ * delivering. A sink with no declared categories is always allowed (it is the
+ * sink author's responsibility to declare what it needs).
+ */
+export function createConsent(config?: ConsentConfig): ConsentAPI & {
+  /** True when every required category is granted (empty list ⇒ allowed). */
+  allows(required?: string[]): boolean
+  /** True when at least one sink could receive (used by strict mode). */
+  strict: boolean
+} {
+  const granted = new Set<string>(config?.granted ?? [])
+
+  return {
+    strict: config?.strict ?? false,
+    grant(...categories: string[]): void {
+      for (const c of categories) granted.add(c)
+    },
+    revoke(...categories: string[]): void {
+      for (const c of categories) granted.delete(c)
+    },
+    granted(): string[] {
+      return [...granted]
+    },
+    isGranted(category: string): boolean {
+      return granted.has(category)
+    },
+    allows(required?: string[]): boolean {
+      if (!required || required.length === 0) return true
+      return required.every((c) => granted.has(c))
+    },
+  }
+}
+
+export type Consent = ReturnType<typeof createConsent>

package/dist/analytics/console-sink.ts

@@ -0,0 +1,37 @@
+import type { AnalyticsEvent, AnalyticsSink } from './types.js'
+
+export interface ConsoleSinkOptions {
+  /** Injected logger (defaults to globalThis.console). */
+  logger?: Pick<Console, 'log' | 'groupCollapsed' | 'groupEnd'>
+  /** Consent categories this sink requires. Default: none (always allowed). */
+  consentCategories?: string[]
+}
+
+/**
+ * Built-in `console` sink — the dev preset's default. Prints each canonical
+ * envelope so engineers can see exactly what would ship over the wire.
+ */
+export function createConsoleSink(
+  options: ConsoleSinkOptions = {},
+): AnalyticsSink {
+  const logger =
+    options.logger ??
+    (globalThis as unknown as { console: Console }).console
+
+  return {
+    name: 'console',
+    consentCategories: options.consentCategories,
+    deliver(batch: AnalyticsEvent[]): void {
+      for (const ev of batch) {
+        const label = `[analytics] ${ev.type}${ev.event ? ` ${ev.event}` : ''}`
+        if (typeof logger.groupCollapsed === 'function') {
+          logger.groupCollapsed(label)
+          logger.log(ev)
+          logger.groupEnd?.()
+        } else {
+          logger.log(label, ev)
+        }
+      }
+    },
+  }
+}

package/dist/analytics/http-sink.ts

@@ -0,0 +1,213 @@
+import type {
+  AnalyticsEvent,
+  AnalyticsSink,
+  HttpSinkOptions,
+  SinkDeliverContext,
+} from './types.js'
+import { SCHEMA_VERSION } from './types.js'
+import { uuidv4 } from './uuid.js'
+
+/**
+ * Built-in `http` sink — Segment HTTP Tracking API wire contract.
+ *
+ * Wire contract (adopt, do not invent — RudderStack/Jitsu/Segment conform):
+ *
+ *   POST {endpoint}/v{schemaVersion}/batch
+ *   Content-Type: application/json
+ *   Authorization: Basic base64(writeKey:)         (note the trailing colon)
+ *   Body: { batch: AnalyticsEvent[], sentAt, batchId }
+ *
+ * Each event carries `messageId` (idempotency — backends MUST dedupe),
+ * `anonymousId`, `userId?`, `sessionId`, `type`, `event?`,
+ * `properties`/`traits`, `context`, `timestamp`, `schemaVersion`.
+ *
+ * Response handling (accept-and-queue semantics):
+ *   200       accepted (the backend has only queued it, not processed it)
+ *   400       malformed       → DROP, never retry
+ *   401       bad write key   → DROP, never retry
+ *   413       payload too big → DROP (we also pre-split under the size caps)
+ *   429 / 5xx transient       → exponential backoff retry
+ *
+ * Clock skew: the backend corrects with
+ *   corrected = timestamp + (receivedAt − sentAt)
+ * so we always stamp an honest client `sentAt`.
+ *
+ * sendBeacon caveat: the unload path (`pagehide`/`visibilitychange`) uses
+ * `navigator.sendBeacon`, which cannot set an `Authorization` header. On that
+ * path we fall back to `?writeKey=` in the query string with a
+ * `text/plain` body (the wire contract requires the backend to accept this).
+ */
+
+const NO_RETRY = new Set([400, 401, 413])
+
+function base64(input: string): string {
+  const g = globalThis as unknown as {
+    btoa?: (s: string) => string
+    Buffer?: { from(s: string, enc: string): { toString(enc: string): string } }
+  }
+  if (typeof g.btoa === 'function') {
+    return g.btoa(input)
+  }
+  if (g.Buffer) {
+    return g.Buffer.from(input, 'utf-8').toString('base64')
+  }
+  throw new Error('No base64 implementation available (btoa/Buffer)')
+}
+
+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
+  // Conservative fallback (UTF-8 worst case is 4 bytes/char; use 3 as typical).
+  return unescape(encodeURIComponent(s)).length
+}
+
+const sleep = (ms: number) =>
+  new Promise<void>((r) => setTimeout(r, ms))
+
+/**
+ * Split a batch so neither the per-event nor per-batch byte caps are
+ * exceeded. Over-sized single events are dropped (they can never be sent).
+ */
+function splitBatch(
+  batch: AnalyticsEvent[],
+  maxBatchBytes: number,
+  maxEventBytes: number,
+): { batches: AnalyticsEvent[][]; dropped: AnalyticsEvent[] } {
+  const batches: AnalyticsEvent[][] = []
+  const dropped: AnalyticsEvent[] = []
+  let current: AnalyticsEvent[] = []
+  let currentBytes = 2 // "[]"
+
+  for (const ev of batch) {
+    const evBytes = byteLength(JSON.stringify(ev))
+    if (evBytes > maxEventBytes) {
+      dropped.push(ev)
+      continue
+    }
+    if (current.length && currentBytes + evBytes + 1 > maxBatchBytes) {
+      batches.push(current)
+      current = []
+      currentBytes = 2
+    }
+    current.push(ev)
+    currentBytes += evBytes + 1
+  }
+  if (current.length) batches.push(current)
+  return { batches, dropped }
+}
+
+/** Create the built-in Segment-spec HTTP sink. */
+export function createHttpSink(options: HttpSinkOptions): AnalyticsSink {
+  const {
+    endpoint,
+    writeKey,
+    maxRetries = 3,
+    backoffBaseMs = 500,
+    consentCategories = ['analytics'],
+    maxBatchBytes = 500_000,
+    maxEventBytes = 32_000,
+  } = options
+
+  const base = endpoint.replace(/\/+$/, '')
+  const url = `${base}/v${SCHEMA_VERSION}/batch`
+  const authHeader = `Basic ${base64(`${writeKey}:`)}`
+
+  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 envelope(batch: AnalyticsEvent[]) {
+    return {
+      batch,
+      sentAt: new Date().toISOString(),
+      batchId: uuidv4(),
+    }
+  }
+
+  /** Beacon path: writeKey via query string, text/plain body. */
+  function sendViaBeacon(batch: AnalyticsEvent[]): boolean {
+    const beacon = resolveBeacon()
+    if (!beacon) return false
+    const beaconUrl = `${url}?writeKey=${encodeURIComponent(writeKey)}`
+    return beacon(beaconUrl, JSON.stringify(envelope(batch)))
+  }
+
+  /** Standard path: fetch + Authorization header, with backoff retries. */
+  async function sendViaFetch(batch: AnalyticsEvent[]): Promise<void> {
+    const doFetch = resolveFetch()
+    const body = JSON.stringify(envelope(batch))
+
+    for (let attempt = 0; ; attempt++) {
+      let status: number
+      try {
+        const res = await doFetch(url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: authHeader,
+          },
+          body,
+          keepalive: true,
+        })
+        status = res.status
+      } catch {
+        // Network error — treat as transient.
+        status = 0
+      }
+
+      if (status >= 200 && status < 300) return // accepted-and-queued
+      if (NO_RETRY.has(status)) return // 400/401/413 — drop, never retry
+
+      // 429 / 5xx / network (0) → backoff retry.
+      if (attempt >= maxRetries) return
+      const delay = backoffBaseMs * 2 ** attempt
+      await sleep(delay)
+    }
+  }
+
+  return {
+    name: 'http',
+    consentCategories,
+
+    async deliver(
+      batch: AnalyticsEvent[],
+      ctx: SinkDeliverContext,
+    ): Promise<void> {
+      if (batch.length === 0) return
+      const { batches, dropped } = splitBatch(
+        batch,
+        maxBatchBytes,
+        maxEventBytes,
+      )
+      void dropped // oversized events are unsendable by contract — silently dropped
+
+      for (const part of batches) {
+        if (ctx.unload) {
+          // Unload path: try beacon first; fall back to keepalive fetch.
+          if (sendViaBeacon(part)) continue
+          void sendViaFetch(part)
+        } else {
+          await sendViaFetch(part)
+        }
+      }
+    },
+  }
+}