@refraction-ui/astro 0.5.1 → 0.6.0

package/dist/analytics/types.ts

@@ -0,0 +1,273 @@
+/**
+ * @refraction-ui/analytics — type contracts.
+ *
+ * The library is a neutral Segment-spec collector/router. The app instruments
+ * once via the canonical API; the router fans the canonical envelope out to
+ * N pluggable sinks. There is NO privileged engine — every vendor is a sink.
+ */
+
+/** Canonical Segment event types. */
+export type AnalyticsEventType =
+  | 'track'
+  | 'identify'
+  | 'page'
+  | 'screen'
+  | 'group'
+  | 'alias'
+
+/** Schema version stamped onto every envelope and the wire contract path. */
+export const SCHEMA_VERSION = 1
+
+/** Arbitrary, JSON-serialisable bag of values. */
+export type AnalyticsProperties = Record<string, unknown>
+
+/**
+ * The context block attached to every event. `library` identifies the
+ * collector; `app`/`env` identify the product instance.
+ */
+export interface AnalyticsContext {
+  app: string
+  env: string
+  page?: {
+    path?: string
+    url?: string
+    referrer?: string
+    title?: string
+    search?: string
+  }
+  library: {
+    name: string
+    version: string
+  }
+  /** Free-form additions contributed by `with(context)` children. */
+  [key: string]: unknown
+}
+
+/**
+ * The canonical Segment envelope. Every sink receives events in exactly this
+ * shape; the built-in HTTP sink ships it verbatim over the wire contract.
+ */
+export interface AnalyticsEvent {
+  /** Segment call type. */
+  type: AnalyticsEventType
+  /** Event name (track/screen) or page name (page). */
+  event?: string
+  /** Idempotency key — backends MUST dedupe on this. */
+  messageId: string
+  /** Persistent, non-PII, resettable client id. */
+  anonymousId: string
+  /** Opaque app-supplied id (set after identify). */
+  userId?: string
+  /** Group id (group calls). */
+  groupId?: string
+  /** Previous id (alias calls). */
+  previousId?: string
+  /** Analytics session id (UUIDv4, minted at session start). */
+  sessionId: string
+  /** track/page/screen/group payload. */
+  properties?: AnalyticsProperties
+  /** identify/group trait payload. */
+  traits?: AnalyticsProperties
+  /** Collector + product context. */
+  context: AnalyticsContext
+  /** ISO-8601 client timestamp. */
+  timestamp: string
+  /** Envelope schema version. */
+  schemaVersion: number
+}
+
+/**
+ * Sink SPI — implemented by adapter packages (GA4, Azure, PostHog) and by the
+ * built-in HTTP sink. A sink declares the consent categories it requires; the
+ * router will not deliver to a sink whose categories are not all granted.
+ */
+export interface AnalyticsSink {
+  /** Stable sink identifier. */
+  name: string
+  /** Consent categories this sink requires (e.g. ['analytics']). */
+  consentCategories?: string[]
+  /** Called once before the first delivery. */
+  init?(ctx: SinkInitContext): void | Promise<void>
+  /** Deliver a batch of canonical events. */
+  deliver(batch: AnalyticsEvent[], ctx: SinkDeliverContext): void | Promise<void>
+  /** Flush any buffered state (best-effort). */
+  flush?(): void | Promise<void>
+  /** Release resources on reset()/shutdown. */
+  shutdown?(): void | Promise<void>
+}
+
+/** Context handed to `sink.init`. */
+export interface SinkInitContext {
+  app: string
+  env: string
+  endpoint?: string
+}
+
+/** Context handed to every `sink.deliver`. */
+export interface SinkDeliverContext {
+  /** True on the unload path — sinks should prefer sendBeacon. */
+  unload: boolean
+}
+
+/** Cross-tab persistence SPI. Defaults pick localStorage/cookie/memory. */
+export interface AnalyticsStorage {
+  get(key: string): string | null
+  set(key: string, value: string): void
+  remove(key: string): void
+}
+
+/** Session engine configuration. */
+export interface SessionConfig {
+  /** Inactivity timeout in ms before a new session is minted. GA4 = 30min. */
+  timeoutMs?: number
+  /** Reset the session when a campaign/utm change is detected. */
+  resetOnCampaign?: boolean
+  /** Persistence backend; defaults to localStorage→cookie→memory. */
+  storage?: AnalyticsStorage
+  /** Storage key namespace. */
+  storageKey?: string
+}
+
+/** Identity engine configuration. */
+export interface IdentityConfig {
+  /** Persistence backend; defaults to localStorage→cookie→memory. */
+  storage?: AnalyticsStorage
+  /** Storage key namespace. */
+  storageKey?: string
+}
+
+/** Consent gate configuration. */
+export interface ConsentConfig {
+  /** Categories granted at boot. */
+  granted?: string[]
+  /**
+   * If true, an event is dropped entirely when NO sink can receive it.
+   * If false (default), events are still buffered until consent is granted.
+   */
+  strict?: boolean
+}
+
+/** Consent gate runtime API. */
+export interface ConsentAPI {
+  grant(...categories: string[]): void
+  revoke(...categories: string[]): void
+  granted(): string[]
+  isGranted(category: string): boolean
+}
+
+/** Session runtime API. */
+export interface SessionAPI {
+  /** Current session id (mints one lazily if none active). */
+  id(): string
+  /** Force-start a new session, returning the new id. */
+  start(): string
+  /** End the current session. */
+  end(): void
+  /** Attach arbitrary session-scoped properties. */
+  set(props: AnalyticsProperties): void
+}
+
+/** Built-in HTTP sink options (Segment HTTP Tracking API wire contract). */
+export interface HttpSinkOptions {
+  /** Base endpoint; events POST to `{endpoint}/v{schemaVersion}/batch`. */
+  endpoint: string
+  /** Write key — sent as `Authorization: Basic base64(writeKey:)`. */
+  writeKey: 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
+  /** Consent categories this sink requires. Default ['analytics']. */
+  consentCategories?: string[]
+  /** Soft per-batch byte cap (Segment ≈ 500KB). Default 500_000. */
+  maxBatchBytes?: number
+  /** Soft per-event byte cap (Segment ≈ 32KB). Default 32_000. */
+  maxEventBytes?: number
+}
+
+/** `createAnalytics` configuration. */
+export interface AnalyticsConfig {
+  /** Product/app identifier (stamped into context.app). */
+  app: string
+  /** Environment, e.g. 'development' | 'production'. Drives presets. */
+  env: string
+  /** When set, a built-in HTTP sink is auto-registered to this endpoint. */
+  endpoint?: string
+  /** Write key for the auto-registered HTTP sink. */
+  writeKey?: string
+  /** Kill switch — when false, a tree-shakeable noop is returned. Default true. */
+  enabled?: boolean
+  /** 0..1 sampling rate applied per top-level call. Default 1. */
+  sampleRate?: number
+  /** Extra property/trait keys to redact (in addition to the PII deny-list). */
+  redactKeys?: string[]
+  /** Explicit sinks (in addition to / instead of the auto HTTP sink). */
+  sinks?: AnalyticsSink[]
+  /** Session engine config. */
+  session?: SessionConfig
+  /** Identity engine config. */
+  identity?: IdentityConfig
+  /** Consent gate config. */
+  consent?: ConsentConfig
+  /**
+   * Force a preset. Defaults: env==='production' → 'prod', else 'dev'.
+   * dev = sync + console; prod = batch + sample + beacon flush on unload.
+   */
+  preset?: 'dev' | 'prod'
+  /** Batch size before an automatic flush (prod). Default 20. */
+  batchSize?: number
+  /** Auto-flush interval in ms (prod). Default 10_000. */
+  flushIntervalMs?: number
+}
+
+/** Options accepted by every top-level call. */
+export interface CallOptions {
+  /** Per-call timestamp override (ISO-8601). */
+  timestamp?: string
+  /** Per-call context overrides (shallow-merged). */
+  context?: Partial<AnalyticsContext>
+}
+
+/** The public analytics surface returned by `createAnalytics`. */
+export interface Analytics {
+  track(event: string, properties?: AnalyticsProperties, opts?: CallOptions): void
+  identify(userId: string, traits?: AnalyticsProperties, opts?: CallOptions): void
+  page(name?: string, properties?: AnalyticsProperties, opts?: CallOptions): void
+  screen(name?: string, properties?: AnalyticsProperties, opts?: CallOptions): void
+  group(groupId: string, traits?: AnalyticsProperties, opts?: CallOptions): void
+  alias(userId: string, previousId?: string, opts?: CallOptions): void
+
+  /** Analytics-session API (NOT replay). */
+  session: SessionAPI
+  /** Consent gate API. */
+  consent: ConsentAPI
+
+  /** Persistent, non-PII anonymous id. */
+  anonymousId(): string
+  /** Current opaque user id (if identified). */
+  userId(): string | undefined
+
+  /** Derive a child that merges extra context into every event. */
+  with(context: Partial<AnalyticsContext>): Analytics
+
+  /** Register an additional sink at runtime. */
+  addSink(sink: AnalyticsSink): void
+  /** Remove a sink by name. */
+  removeSink(name: string): void
+  /** Registered sink names. */
+  readonly sinks: string[]
+
+  /** Flush all sinks (and the internal batch). */
+  flush(): Promise<void>
+  /**
+   * Reset identity + session (privacy-safe logout). Mints a fresh
+   * anonymousId and ends the session.
+   */
+  reset(): void
+  /** Whether this is a live collector (false for the noop). */
+  readonly enabled: boolean
+}

package/dist/analytics/uuid.ts

@@ -0,0 +1,63 @@
+/**
+ * uuidv4 — RFC 4122 version 4 UUID.
+ *
+ * Prefers `crypto.randomUUID` / `crypto.getRandomValues` when available
+ * (browser, modern Node) and degrades to `Math.random` only as a last
+ * resort. No external dependency by design (this is the neutral router).
+ */
+export function uuidv4(): string {
+  const c: Crypto | undefined =
+    typeof globalThis !== 'undefined'
+      ? (globalThis.crypto as Crypto | undefined)
+      : undefined
+
+  if (c && typeof c.randomUUID === 'function') {
+    return c.randomUUID()
+  }
+
+  const bytes = new Uint8Array(16)
+  if (c && typeof c.getRandomValues === 'function') {
+    c.getRandomValues(bytes)
+  } else {
+    for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256)
+  }
+
+  // Per RFC 4122 §4.4: set version (4) and variant (10xx) bits.
+  bytes[6] = (bytes[6] & 0x0f) | 0x40
+  bytes[8] = (bytes[8] & 0x3f) | 0x80
+
+  const hex: string[] = []
+  for (let i = 0; i < 256; i++) hex.push((i + 0x100).toString(16).slice(1))
+
+  return (
+    hex[bytes[0]] +
+    hex[bytes[1]] +
+    hex[bytes[2]] +
+    hex[bytes[3]] +
+    '-' +
+    hex[bytes[4]] +
+    hex[bytes[5]] +
+    '-' +
+    hex[bytes[6]] +
+    hex[bytes[7]] +
+    '-' +
+    hex[bytes[8]] +
+    hex[bytes[9]] +
+    '-' +
+    hex[bytes[10]] +
+    hex[bytes[11]] +
+    hex[bytes[12]] +
+    hex[bytes[13]] +
+    hex[bytes[14]] +
+    hex[bytes[15]]
+  )
+}
+
+/** RFC 4122 v4 shape matcher (case-insensitive). */
+export const UUID_V4_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+/** True when `value` is a well-formed v4 UUID. */
+export function isUuidV4(value: unknown): value is string {
+  return typeof value === 'string' && UUID_V4_RE.test(value)
+}

package/dist/astro-analytics/AnalyticsScript.astro

@@ -0,0 +1,130 @@
+---
+/**
+ * AnalyticsScript — injects a <script> that initializes the analytics
+ * router on the page. Exposes `window.__rfr_analytics` so other scripts
+ * can call track / identify / page / screen / group / alias.
+ *
+ * Props mirror the consumer-facing slice of `AnalyticsConfig` from
+ * `@refraction-ui/analytics`. The app instruments once and never names a
+ * vendor — `endpoint` points at your server relay (recommended prod
+ * topology: client → your endpoint → server-side fan-out), so the browser
+ * ships only our neutral router and stays ad-blocker-proof.
+ *
+ * Because inline scripts cannot import ES modules, this island stashes the
+ * config and a deferred `init(createAnalytics, sinks)` helper. The consumer
+ * calls it from their own module script with the real core:
+ *
+ * ```astro
+ * ---
+ * import { AnalyticsScript } from '../astro-analytics/index.ts'
+ * ---
+ * <AnalyticsScript app="my-app" env="production" endpoint="/relay" />
+ * <script>
+ *   import { createAnalytics } from '../analytics/index.ts'
+ *   window.__rfr_analytics.init(createAnalytics)
+ * </script>
+ * ```
+ */
+
+interface Props extends astroHTML.JSX.HTMLAttributes {
+  /** Product/app identifier (stamped into context.app). */
+  app: string
+  /** Environment, e.g. 'development' | 'production'. Drives presets. */
+  env: string
+  /** Server-relay endpoint; an HTTP sink auto-registers here. */
+  endpoint?: string
+  /** Write key for the auto-registered HTTP sink. */
+  writeKey?: string
+  /** Kill switch — when false, a tree-shakeable noop is returned. */
+  enabled?: boolean
+  /** 0..1 sampling rate applied per top-level call. */
+  sampleRate?: number
+  /** Extra property/trait keys to redact (in addition to PII deny-list). */
+  redactKeys?: string[]
+  /** Force a preset (defaults from env). */
+  preset?: 'dev' | 'prod'
+}
+
+const {
+  app,
+  env,
+  endpoint,
+  writeKey,
+  enabled,
+  sampleRate,
+  redactKeys,
+  preset,
+  ...props
+} = Astro.props
+
+const configJSON = JSON.stringify({
+  app,
+  env,
+  endpoint,
+  writeKey,
+  enabled,
+  sampleRate,
+  redactKeys,
+  preset,
+})
+---
+
+<script
+  data-rfr-analytics-config={configJSON}
+  {...props}
+  is:inline
+>
+  ;(function () {
+    // Only initialize once
+    if (window.__rfr_analytics) return
+
+    // We cannot import ES modules from an inline script, so we stash the
+    // config and let the consumer call init() from their own module script.
+    var configEl = document.querySelector('[data-rfr-analytics-config]')
+    var config = {}
+    if (configEl) {
+      try { config = JSON.parse(configEl.getAttribute('data-rfr-analytics-config') || '{}') } catch (_) { /* */ }
+    }
+
+    function notReady() {
+      throw new Error('Analytics not initialized. Call window.__rfr_analytics.init(createAnalytics, sinks) first.')
+    }
+
+    // Placeholder that will be replaced once createAnalytics is called
+    window.__rfr_analytics = {
+      _config: config,
+      _api: null,
+      _ready: false,
+      init: function (createAnalytics, sinks) {
+        var api = createAnalytics(
+          sinks && sinks.length
+            ? Object.assign({}, config, { sinks: sinks })
+            : config
+        )
+        window.__rfr_analytics._api = api
+        window.__rfr_analytics._ready = true
+        window.__rfr_analytics.track = api.track.bind(api)
+        window.__rfr_analytics.identify = api.identify.bind(api)
+        window.__rfr_analytics.page = api.page.bind(api)
+        window.__rfr_analytics.screen = api.screen.bind(api)
+        window.__rfr_analytics.group = api.group.bind(api)
+        window.__rfr_analytics.alias = api.alias.bind(api)
+        window.__rfr_analytics.flush = api.flush.bind(api)
+        window.__rfr_analytics.reset = api.reset.bind(api)
+        window.__rfr_analytics.session = api.session
+        window.__rfr_analytics.consent = api.consent
+        return api
+      },
+      track: notReady,
+      identify: notReady,
+      page: notReady,
+      screen: notReady,
+      group: notReady,
+      alias: notReady,
+      flush: notReady,
+      reset: notReady,
+      session: null,
+      consent: null,
+    }
+  })()
+</script>

package/dist/astro-analytics/index.ts

@@ -0,0 +1,49 @@
+export { default as AnalyticsScript } from './AnalyticsScript.astro'
+
+// Re-export core factories and types for convenience. The Astro adapter is a
+// thin island over the neutral router — no privileged engine, every vendor is
+// a sink, and the recommended prod topology routes through your server relay.
+export {
+  createAnalytics,
+  createHttpSink,
+  createConsoleSink,
+  createMockSink,
+  createSession,
+  createIdentity,
+  createConsent,
+  createRedactor,
+  createMemoryStorage,
+  createLocalStorageAdapter,
+  createCookieAdapter,
+  resolveStorage,
+  campaignFingerprint,
+  uuidv4,
+  isUuidV4,
+  UUID_V4_RE,
+  PII_DENY_LIST,
+  PII_EXACT_KEYS,
+  REDACTED,
+  SCHEMA_VERSION,
+  DEFAULT_SESSION_TIMEOUT_MS,
+  type Analytics,
+  type AnalyticsConfig,
+  type AnalyticsEvent,
+  type AnalyticsEventType,
+  type AnalyticsProperties,
+  type AnalyticsContext,
+  type AnalyticsSink,
+  type AnalyticsStorage,
+  type SinkInitContext,
+  type SinkDeliverContext,
+  type SessionConfig,
+  type SessionAPI,
+  type IdentityConfig,
+  type ConsentConfig,
+  type ConsentAPI,
+  type HttpSinkOptions,
+  type CallOptions,
+  type ConsoleSinkOptions,
+  type MockSink,
+  type CreateMockSinkOptions,
+  type Redactor,
+} from '../analytics/index.ts'

package/dist/astro-logger/TelemetryScript.astro

@@ -0,0 +1,108 @@
+---
+/**
+ * TelemetryScript — injects a <script> that initializes the telemetry client
+ * on the page. Exposes `window.__rfr_telemetry` for other scripts to call
+ * debug / info / warn / error / fatal / child / startSpan / flush.
+ *
+ * Props mirror TelemetryConfig from @refraction-ui/logger. Faro stays fully
+ * hidden — the only wiring a consumer supplies is the backend `endpoint`.
+ */
+
+interface Props extends astroHTML.JSX.HTMLAttributes {
+  /** Logical app/service name attached to every record. */
+  app: string
+  /** Environment preset selector. */
+  env: 'development' | 'production'
+  /** Remote collector endpoint. Omit for console-only (zero-config dev). */
+  endpoint?: string
+  /** Master kill switch. `false` -> tree-shakeable noop. Defaults to true. */
+  enabled?: boolean
+  /** Fraction of records kept, 0..1. Defaults to the preset value. */
+  sampleRate?: number
+  /** Context keys to strip (deep) before a record is emitted. */
+  redactKeys?: string[]
+}
+
+const {
+  app,
+  env,
+  endpoint,
+  enabled,
+  sampleRate,
+  redactKeys,
+  ...props
+} = Astro.props
+
+const configJSON = JSON.stringify({
+  app,
+  env,
+  endpoint,
+  enabled,
+  sampleRate,
+  redactKeys,
+})
+---
+
+<script
+  data-rfr-telemetry-config={configJSON}
+  {...props}
+  is:inline
+>
+  ;(function () {
+    // Only initialize once
+    if (window.__rfr_telemetry) return
+
+    // We cannot import ES modules from an inline script, so we stash the config
+    // and let the consumer call the init function from their own module script.
+    // This inline script sets up the namespace and a deferred init helper.
+    var configEl = document.querySelector('[data-rfr-telemetry-config]')
+    var config = {}
+    if (configEl) {
+      try { config = JSON.parse(configEl.getAttribute('data-rfr-telemetry-config') || '{}') } catch (_) { /* */ }
+    }
+
+    function notReady() {
+      throw new Error('Telemetry not initialized. Call window.__rfr_telemetry.init(createTelemetry) first.')
+    }
+
+    // Placeholder that will be replaced once createTelemetry is called
+    window.__rfr_telemetry = {
+      _config: config,
+      _api: null,
+      _ready: false,
+      init: function (createTelemetry, sinks) {
+        var api = createTelemetry(config)
+        if (sinks) {
+          sinks.forEach(function (sink) {
+            api.addSink(sink)
+          })
+        }
+        window.__rfr_telemetry._api = api
+        window.__rfr_telemetry._ready = true
+        window.__rfr_telemetry.debug = api.debug.bind(api)
+        window.__rfr_telemetry.info = api.info.bind(api)
+        window.__rfr_telemetry.warn = api.warn.bind(api)
+        window.__rfr_telemetry.error = api.error.bind(api)
+        window.__rfr_telemetry.fatal = api.fatal.bind(api)
+        window.__rfr_telemetry.child = api.child.bind(api)
+        window.__rfr_telemetry.startSpan = api.startSpan.bind(api)
+        window.__rfr_telemetry.flush = api.flush.bind(api)
+        window.__rfr_telemetry.addSink = api.addSink.bind(api)
+        window.__rfr_telemetry.removeSink = api.removeSink.bind(api)
+        window.__rfr_telemetry.sinks = api.sinks
+        return api
+      },
+      debug: notReady,
+      info: notReady,
+      warn: notReady,
+      error: notReady,
+      fatal: notReady,
+      child: notReady,
+      startSpan: notReady,
+      flush: function () { return Promise.resolve() },
+      addSink: notReady,
+      removeSink: notReady,
+      sinks: [],
+    }
+  })()
+</script>

package/dist/astro-logger/index.ts

@@ -0,0 +1,48 @@
+export { default as TelemetryScript } from './TelemetryScript.astro'
+
+// Astro-idiomatic server-side hook
+export {
+  createTelemetryMiddleware,
+  type TelemetryMiddlewareContext,
+  type TelemetryMiddlewareNext,
+  type TelemetryMiddlewareOptions,
+} from './telemetry-middleware.js'
+
+// Library-origin error capture seam (epic #247 / issue #249)
+export {
+  createLibraryErrorCapture,
+  captureAstroLibraryError,
+  type LibraryErrorCaptureContext,
+  type LibraryErrorCaptureNext,
+  type LibraryErrorCaptureOptions,
+} from './library-error-capture.js'
+export type {
+  LibraryOriginIdentity,
+  DevFeedbackRecord,
+  DevFeedbackSink,
+} from '../shared/index.ts'
+
+// Re-export core types and factories for convenience (Faro stays hidden)
+export {
+  createTelemetry,
+  createConsoleSink,
+  createNoopTelemetry,
+  createMockSink,
+  redact,
+  PRESETS,
+  resolvePreset,
+  LEVEL_ORDER,
+  type Telemetry,
+  type TelemetryConfig,
+  type TelemetryEnv,
+  type TelemetryPreset,
+  type Logger,
+  type Span,
+  type LogLevel,
+  type LogContext,
+  type LogRecord,
+  type SpanRecord,
+  type TelemetrySink,
+  type ConsoleSinkOptions,
+  type MockSinkExtended,
+} from '../logger/index.ts'