@refraction-ui/astro 0.5.1 → 0.6.0

package/dist/logger/telemetry-manager.ts

@@ -0,0 +1,229 @@
+import { createConsoleSink } from './console-sink.js'
+import { createNoopTelemetry } from './noop.js'
+import { resolvePreset, type TelemetryPreset } from './presets.js'
+import { redact } from './redact.js'
+import {
+  LEVEL_ORDER,
+  type LogContext,
+  type LogLevel,
+  type LogRecord,
+  type Span,
+  type SpanRecord,
+  type Telemetry,
+  type TelemetryConfig,
+  type TelemetrySink,
+} from './types.js'
+
+/**
+ * createTelemetry — creates a telemetry manager that fans records out to
+ * registered sinks. Manager/provider pattern, mirroring `createAI`.
+ *
+ * - `enabled: false` -> tree-shakeable noop (zero emissions, no engines).
+ * - no `endpoint` -> console-only transport.
+ * - `endpoint` set -> async Faro engine is registered when the optional
+ *   peers exist; console stays as a safe fallback until then.
+ *
+ * The returned object IS a logger (root context = `{}`); `child()` derives
+ * loggers with bound context (sessionId / interviewId / turnId / ...).
+ */
+export function createTelemetry(config: TelemetryConfig): Telemetry {
+  if (config.enabled === false) {
+    return createNoopTelemetry()
+  }
+
+  const preset = resolvePreset(config.env)
+  const sampleRate = config.sampleRate ?? preset.sampleRate
+  const redactKeys = config.redactKeys ?? []
+
+  const sinks = new Map<string, TelemetrySink>()
+  /** Insertion-ordered sink names. */
+  const sinkOrder: string[] = []
+  /** Batch buffer (production preset only). */
+  const buffer: Array<{ kind: 'log'; record: LogRecord } | { kind: 'span'; record: SpanRecord }> = []
+
+  function addSinkInternal(sink: TelemetrySink): void {
+    if (sinks.has(sink.name)) {
+      sinks.set(sink.name, sink)
+    } else {
+      sinks.set(sink.name, sink)
+      sinkOrder.push(sink.name)
+    }
+  }
+
+  // Console transport is always present as the zero-dependency baseline.
+  addSinkInternal(createConsoleSink({ pretty: preset.pretty }))
+
+  // When an endpoint is configured, attempt to attach the Faro engine. The
+  // import is lazy + dynamic so the optional peers never become required and
+  // Faro names stay out of the public API.
+  if (config.endpoint) {
+    const endpoint = config.endpoint
+    void import('./faro-engine.js')
+      .then(({ createFaroSink }) => createFaroSink({ app: config.app, endpoint }))
+      .then((faro) => {
+        if (faro) addSinkInternal(faro)
+      })
+      .catch(() => {
+        /* peers absent or init failed — console remains */
+      })
+  }
+
+  function shouldSample(): boolean {
+    if (sampleRate >= 1) return true
+    if (sampleRate <= 0) return false
+    return Math.random() < sampleRate
+  }
+
+  function dispatch(
+    entry: { kind: 'log'; record: LogRecord } | { kind: 'span'; record: SpanRecord },
+  ): void {
+    if (preset.batch) {
+      buffer.push(entry)
+      if (buffer.length >= preset.batchSize) {
+        void flushBuffer()
+      }
+      return
+    }
+    deliver(entry)
+  }
+
+  function deliver(
+    entry: { kind: 'log'; record: LogRecord } | { kind: 'span'; record: SpanRecord },
+  ): void {
+    for (const name of sinkOrder) {
+      const sink = sinks.get(name)
+      if (!sink) continue
+      if (entry.kind === 'log') sink.log(entry.record)
+      else sink.span(entry.record)
+    }
+  }
+
+  async function flushBuffer(): Promise<void> {
+    if (buffer.length > 0) {
+      const pending = buffer.splice(0, buffer.length)
+      for (const entry of pending) deliver(entry)
+    }
+    await Promise.all(
+      sinkOrder.map((name) => sinks.get(name)?.flush() ?? Promise.resolve()),
+    )
+  }
+
+  // ---- page-exit beacon flush (production preset) -------------------------
+  // Browser only — `navigator.sendBeacon` is used by the underlying engine
+  // transport; here we just trigger a flush on the page-exit signals.
+  const root = globalThis as {
+    addEventListener?: (type: string, listener: () => void) => void
+    document?: { visibilityState?: string }
+    navigator?: { sendBeacon?: unknown }
+  }
+  if (preset.beaconFlush && typeof root.addEventListener === 'function') {
+    const onExit = (): void => {
+      void flushBuffer()
+    }
+    root.addEventListener('pagehide', onExit)
+    root.addEventListener('visibilitychange', () => {
+      if (root.document?.visibilityState === 'hidden') onExit()
+    })
+  }
+
+  function makeLogger(boundContext: LogContext): Telemetry {
+    function emit(level: LogLevel, message: string, context?: LogContext): void {
+      if (LEVEL_ORDER[level] < LEVEL_ORDER[preset.minLevel]) return
+      if (!shouldSample()) return
+      const merged = redact({ ...boundContext, ...context }, redactKeys)
+      const record: LogRecord = {
+        level,
+        message,
+        timestamp: Date.now(),
+        app: config.app,
+        env: config.env,
+        context: merged,
+      }
+      dispatch({ kind: 'log', record })
+    }
+
+    const logger: Telemetry = {
+      debug(message, context?) {
+        emit('debug', message, context)
+      },
+      info(message, context?) {
+        emit('info', message, context)
+      },
+      warn(message, context?) {
+        emit('warn', message, context)
+      },
+      error(message, context?) {
+        emit('error', message, context)
+      },
+      fatal(message, context?) {
+        emit('fatal', message, context)
+      },
+
+      child(context: LogContext): Telemetry {
+        return makeLogger({ ...boundContext, ...context })
+      },
+
+      startSpan(name: string, attributes?: LogContext): Span {
+        const startTime = Date.now()
+        let ended = false
+        return {
+          end(opts?: { error?: unknown; attributes?: LogContext }): void {
+            if (ended) return
+            ended = true
+            const endTime = Date.now()
+            const merged = redact(
+              { ...boundContext, ...attributes, ...opts?.attributes },
+              redactKeys,
+            )
+            const err = opts?.error
+            const record: SpanRecord = {
+              name,
+              startTime,
+              endTime,
+              durationMs: endTime - startTime,
+              app: config.app,
+              env: config.env,
+              context: merged,
+              status: err ? 'error' : 'ok',
+              ...(err
+                ? {
+                    error: {
+                      name: err instanceof Error ? err.name : 'Error',
+                      message: err instanceof Error ? err.message : String(err),
+                    },
+                  }
+                : {}),
+            }
+            dispatch({ kind: 'span', record })
+          },
+        }
+      },
+
+      flush(): Promise<void> {
+        return flushBuffer()
+      },
+
+      get sinks(): string[] {
+        return [...sinkOrder]
+      },
+
+      addSink(sink: TelemetrySink): void {
+        addSinkInternal(sink)
+      },
+
+      removeSink(name: string): void {
+        if (sinks.has(name)) {
+          sinks.delete(name)
+          const idx = sinkOrder.indexOf(name)
+          if (idx !== -1) sinkOrder.splice(idx, 1)
+        }
+      },
+    }
+
+    return logger
+  }
+
+  return makeLogger({})
+}
+
+export type { TelemetryPreset }

package/dist/logger/types.ts

@@ -0,0 +1,121 @@
+/** Severity levels, ordered low -> high. */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+
+/** Numeric ordering used for level threshold comparisons. */
+export const LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  fatal: 50,
+}
+
+/** Bound key/value pairs attached to every record emitted by a logger. */
+export type LogContext = Record<string, unknown>
+
+/** A single structured log record handed to a sink. */
+export interface LogRecord {
+  level: LogLevel
+  message: string
+  timestamp: number
+  app: string
+  env: TelemetryEnv
+  /** Merged bound context (child loggers) + per-call context, post-redaction. */
+  context: LogContext
+}
+
+/** A span record handed to a sink when a span ends. */
+export interface SpanRecord {
+  name: string
+  startTime: number
+  endTime: number
+  durationMs: number
+  app: string
+  env: TelemetryEnv
+  /** Merged bound context + span attributes, post-redaction. */
+  context: LogContext
+  /** 'ok' unless ended with an error. */
+  status: 'ok' | 'error'
+  error?: { name: string; message: string }
+}
+
+/**
+ * Vendor-neutral telemetry sink. Engines (console, Faro, custom) implement
+ * this — no vendor type ever leaks across this boundary.
+ */
+export interface TelemetrySink {
+  /** Engine name, for diagnostics. */
+  name: string
+  /** Receive a log record. May buffer; honor flush(). */
+  log(record: LogRecord): void
+  /** Receive a finished span. May buffer; honor flush(). */
+  span(record: SpanRecord): void
+  /** Force-deliver any buffered records. Resolves once delivery is attempted. */
+  flush(): Promise<void>
+}
+
+/** Telemetry environment — selects a behavior preset. */
+export type TelemetryEnv = 'development' | 'production'
+
+/** Config for {@link createTelemetry} — mirrors `createAI`'s config shape. */
+export interface TelemetryConfig {
+  /** Logical app/service name attached to every record. */
+  app: string
+  /** Environment preset selector. */
+  env: TelemetryEnv
+  /**
+   * Remote collector endpoint. When omitted, telemetry stays console-only
+   * (no network engine is constructed).
+   */
+  endpoint?: string
+  /**
+   * Master kill switch. When `false`, a tree-shakeable noop logger is
+   * returned and zero records are ever produced. Defaults to `true`.
+   */
+  enabled?: boolean
+  /**
+   * Fraction of records kept, 0..1. Defaults to the preset value
+   * (1 in development, 0.25 in production). Records below the sample
+   * are dropped before reaching any sink.
+   */
+  sampleRate?: number
+  /**
+   * Context keys to strip (deep) before a record is emitted. Use for
+   * PII / secrets, e.g. `['password', 'token', 'authorization']`.
+   */
+  redactKeys?: string[]
+}
+
+/** A logger bound to a context. Child loggers inherit + extend that context. */
+export interface Logger {
+  debug(message: string, context?: LogContext): void
+  info(message: string, context?: LogContext): void
+  warn(message: string, context?: LogContext): void
+  error(message: string, context?: LogContext): void
+  fatal(message: string, context?: LogContext): void
+  /**
+   * Derive a logger with additional bound context (e.g.
+   * `{ sessionId, interviewId, turnId }`). Merges over the parent's context.
+   */
+  child(context: LogContext): Logger
+  /** Begin a span. Call {@link Span.end} to record its duration. */
+  startSpan(name: string, attributes?: LogContext): Span
+  /** Force-deliver buffered records on every sink. */
+  flush(): Promise<void>
+}
+
+/** An in-flight span returned by {@link Logger.startSpan}. */
+export interface Span {
+  /** End the span and emit a {@link SpanRecord}. Optionally attach error/attrs. */
+  end(opts?: { error?: unknown; attributes?: LogContext }): void
+}
+
+/** Return type of {@link createTelemetry}. */
+export interface Telemetry extends Logger {
+  /** Registered sink names, in insertion order. */
+  readonly sinks: string[]
+  /** Register an additional sink (e.g. a custom collector). */
+  addSink(sink: TelemetrySink): void
+  /** Remove a sink by name. */
+  removeSink(name: string): void
+}

package/dist/shared/dev-feedback.ts

@@ -0,0 +1,154 @@
+/**
+ * dev-feedback — zero-dependency `devWarn` / `devError` primitives.
+ *
+ * Design constraints (epic #247, issue #248):
+ * - Guarded by `process.env.NODE_ENV !== 'production'` so production bundlers
+ *   dead-code-strip every call (the guard is a static string compare that
+ *   minifiers fold to `false` in prod builds).
+ * - Warn-once dedupe per `code` — a footgun is reported once, not on every
+ *   render.
+ * - NO import of `@refraction-ui/logger` (no hard dependency on the telemetry
+ *   lib). Forwarding to a telemetry sink happens ONLY if the consumer
+ *   explicitly injects one (dependency inversion, never an import).
+ */
+
+/**
+ * Minimal structural shape of the record a telemetry sink consumes. This is a
+ * deliberate structural mirror of `@refraction-ui/logger`'s `LogRecord` — it is
+ * NOT imported, so `@refraction-ui/shared` keeps zero dependency on the
+ * telemetry lib. A consumer that wires the real logger sink satisfies this
+ * shape structurally.
+ */
+export interface DevFeedbackRecord {
+  level: 'warn' | 'error'
+  message: string
+  timestamp: number
+  /** Structured detail — the library-origin envelope lives here. */
+  context: Record<string, unknown>
+}
+
+/**
+ * The narrow contract a consumer-injected telemetry sink must satisfy. Kept
+ * intentionally minimal and structural so the real `TelemetrySink` from
+ * `@refraction-ui/logger` is assignable WITHOUT shared importing the logger.
+ */
+export interface DevFeedbackSink {
+  /** Receive a single dev-feedback record. Must never throw to the caller. */
+  log(record: DevFeedbackRecord): void
+}
+
+/**
+ * Minimal ambient view of `process.env` so we can read `NODE_ENV` WITHOUT
+ * pulling `@types/node` into this zero-dependency package. Accessed defensively
+ * (the `typeof process === 'undefined'` guard) so this is safe in browsers too.
+ */
+declare const process:
+  | { env?: { NODE_ENV?: string } }
+  | undefined
+
+/** Per-code dedupe set — module-scoped so it survives across calls. */
+const seen = new Set<string>()
+
+/**
+ * Optional, consumer-injected sink. `null` until a consumer explicitly wires
+ * one via {@link setDevFeedbackSink}. Nothing phones home implicitly.
+ */
+let injectedSink: DevFeedbackSink | null = null
+
+/**
+ * Wire an optional telemetry sink that {@link devWarn} / {@link devError}
+ * forward to (in addition to the console). Inversion of control: the consumer
+ * owns the sink; this package never imports it. Pass `null` to unwire.
+ *
+ * Forwarding still only happens in non-production (the calls themselves are
+ * stripped in prod), and still respects warn-once dedupe.
+ */
+export function setDevFeedbackSink(sink: DevFeedbackSink | null): void {
+  injectedSink = sink
+}
+
+/** Test-only / consumer-only escape hatch to reset warn-once dedupe state. */
+export function resetDevFeedback(): void {
+  seen.clear()
+}
+
+function isDev(): boolean {
+  // String compare (not a negated truthiness) so bundlers can statically fold
+  // `process.env.NODE_ENV` and strip the whole branch in production builds.
+  return (
+    typeof process === 'undefined' ||
+    process.env?.NODE_ENV !== 'production'
+  )
+}
+
+function emit(
+  level: 'warn' | 'error',
+  code: string,
+  message: string,
+  detail?: Record<string, unknown>,
+): void {
+  if (!isDev()) return
+
+  // Warn-once dedupe, keyed by (level, code) so an error and a warning sharing
+  // a code are not collapsed into one.
+  const key = `${level}:${code}`
+  if (seen.has(key)) return
+  seen.add(key)
+
+  const text = `[refraction-ui] ${code}: ${message}`
+
+  if (level === 'error') {
+    console.error(text, detail ?? '')
+  } else {
+    console.warn(text, detail ?? '')
+  }
+
+  // Forward to the consumer-injected sink ONLY if one was explicitly wired.
+  if (injectedSink) {
+    const record: DevFeedbackRecord = {
+      level,
+      message: `${code}: ${message}`,
+      timestamp: Date.now(),
+      context: { code, ...(detail ?? {}) },
+    }
+    try {
+      injectedSink.log(record)
+    } catch {
+      // A broken sink must never break the consumer app.
+    }
+  }
+}
+
+/**
+ * Emit a development-only warning for a refraction-ui footgun.
+ *
+ * @param code    Stable, greppable identifier (e.g. `'react/no-controlled-prop'`).
+ * @param message Human-readable explanation.
+ * @param detail  Optional structured detail (forwarded to an injected sink).
+ *
+ * Stripped entirely in production. Warned at most once per `code`.
+ */
+export function devWarn(
+  code: string,
+  message: string,
+  detail?: Record<string, unknown>,
+): void {
+  emit('warn', code, message, detail)
+}
+
+/**
+ * Emit a development-only error for a refraction-ui misuse / invariant break.
+ *
+ * @param code    Stable, greppable identifier.
+ * @param message Human-readable explanation.
+ * @param detail  Optional structured detail (forwarded to an injected sink).
+ *
+ * Stripped entirely in production. Reported at most once per `code`.
+ */
+export function devError(
+  code: string,
+  message: string,
+  detail?: Record<string, unknown>,
+): void {
+  emit('error', code, message, detail)
+}

package/dist/shared/index.ts

@@ -48,6 +48,18 @@ export type {
   SkipLinkProps,
 } from './skip-link.js'
 
+export type {
+  DevFeedbackRecord,
+  DevFeedbackSink,
+} from './dev-feedback.js'
+
+export type {
+  LibraryFramework,
+  LibraryOriginErrorInput,
+  LibraryOriginEnvelope,
+  LibraryOriginIdentity,
+} from './library-origin-error.js'
+
 // Functions
 export { mergeAriaProps, generateId, resetIdCounter } from './aria.js'
 export { Keys, createKeyboardHandler } from './keyboard.js'
@@ -58,3 +70,16 @@ export { FOCUSABLE_SELECTOR, getFocusableElements, createFocusTrap } from './foc
 export { createLiveRegion } from './live-region.js'
 export { prefersReducedMotion, getAnimationDuration } from './motion.js'
 export { createSkipLink } from './skip-link.js'
+export {
+  devWarn,
+  devError,
+  setDevFeedbackSink,
+  resetDevFeedback,
+} from './dev-feedback.js'
+export {
+  libraryOriginError,
+  libraryOriginEnvelope,
+  stackFingerprint,
+  isLibraryOriginError,
+  captureLibraryOriginError,
+} from './library-origin-error.js'