@refraction-ui/astro 0.5.1 → 0.6.0

package/dist/astro-logger/library-error-capture.ts

@@ -0,0 +1,121 @@
+import {
+  captureLibraryOriginError,
+  type DevFeedbackRecord,
+  type DevFeedbackSink,
+  type LibraryOriginIdentity,
+} from '../shared/index.ts'
+
+/**
+ * library-error-capture — the Astro capture seam for epic #247 / issue #249.
+ *
+ * A `defineMiddleware`-compatible runtime hook that tags ONLY errors whose
+ * stack originates in a `@refraction-ui/*` package and routes them to an
+ * optional, consumer-wired telemetry sink. The filter → tag → route flow
+ * lives entirely in `@refraction-ui/shared`'s `captureLibraryOriginError`;
+ * this is the thin Astro middleware around it.
+ *
+ * The error is ALWAYS rethrown so Astro's normal error handling (and the
+ * app's own error pages) are untouched. App-origin errors are never tagged
+ * or forwarded to the diagnostics sink — they pass straight through.
+ *
+ * Zero hard dependency on the telemetry lib — the sink is the structural
+ * `DevFeedbackSink` from shared (the real `@refraction-ui/logger`
+ * `TelemetrySink` satisfies it). Nothing phones home unless a sink is wired.
+ */
+
+/**
+ * Subset of Astro's middleware context we depend on. Kept structural so the
+ * adapter never needs Astro's types at build time (Astro is a peer dep and
+ * its middleware types vary across versions).
+ */
+export interface LibraryErrorCaptureContext {
+  request: Request
+  locals: Record<string, unknown>
+}
+
+/** A `MiddlewareNext`-compatible continuation. */
+export type LibraryErrorCaptureNext = () => Promise<Response> | Response
+
+/** Options for {@link createLibraryErrorCapture}. */
+export interface LibraryErrorCaptureOptions {
+  /**
+   * Fixed package/component identity tagged onto a captured library-origin
+   * error. Carries NO app data — the fingerprint is derived from the stack.
+   */
+  identity: LibraryOriginIdentity
+  /**
+   * Optional, consumer-wired telemetry sink. Library-origin errors are
+   * forwarded here when present; absent / `null` ⇒ no-op (nothing phones
+   * home). The real `@refraction-ui/logger` `TelemetrySink` satisfies this.
+   */
+  sink?: DevFeedbackSink | null
+  /**
+   * Invoked when a library-origin error is captured, with the tagged
+   * diagnostics record (after it has been forwarded to the sink). Optional;
+   * never called for app-origin errors.
+   */
+  onCapture?: (record: DevFeedbackRecord) => void
+}
+
+/**
+ * createLibraryErrorCapture — the Astro-idiomatic server-side capture hook.
+ *
+ * Returns a `defineMiddleware`-compatible `onRequest` handler that runs the
+ * downstream chain and, if it throws, captures the error iff it is
+ * `@refraction-ui/*`-origin (filter + tag + optional forward) and then
+ * ALWAYS rethrows so Astro's error handling is unchanged.
+ *
+ * ```ts
+ * // src/middleware.ts
+ * import { defineMiddleware } from 'astro:middleware'
+ * import { createLibraryErrorCapture } from '../astro-logger/index.ts'
+ *
+ * export const onRequest = defineMiddleware(
+ *   createLibraryErrorCapture({
+ *     identity: { package: '@refraction-ui/astro', componentName: 'app',
+ *                 version: '0.1.0', framework: 'astro' },
+ *     sink: mySink, // omit ⇒ nothing phones home
+ *   }),
+ * )
+ * ```
+ */
+export function createLibraryErrorCapture(
+  options: LibraryErrorCaptureOptions,
+): (
+  context: LibraryErrorCaptureContext,
+  next: LibraryErrorCaptureNext,
+) => Promise<Response> {
+  const { identity, sink = null, onCapture } = options
+
+  return async function onRequest(
+    _context: LibraryErrorCaptureContext,
+    next: LibraryErrorCaptureNext,
+  ): Promise<Response> {
+    try {
+      return await next()
+    } catch (error) {
+      // Filter + tag + route happens entirely in shared. Returns the tagged
+      // record for a library-origin error, or null for an app-origin error
+      // (left completely untouched — not forwarded anywhere).
+      const record = captureLibraryOriginError(error, identity, sink)
+      if (record) onCapture?.(record)
+      // Always rethrow: Astro's normal error handling / error page is
+      // unchanged for both library- and app-origin errors.
+      throw error
+    }
+  }
+}
+
+/**
+ * captureAstroLibraryError — the non-middleware Astro seam. Use from an
+ * endpoint / server island `try/catch` where the middleware cannot reach.
+ * Same contract: library-origin only, optional sink, app-origin returns
+ * `null` untouched. Never throws.
+ */
+export function captureAstroLibraryError(
+  error: unknown,
+  identity: LibraryOriginIdentity,
+  sink?: DevFeedbackSink | null,
+): DevFeedbackRecord | null {
+  return captureLibraryOriginError(error, identity, sink)
+}

package/dist/astro-logger/telemetry-middleware.ts

@@ -0,0 +1,92 @@
+import {
+  createTelemetry,
+  type Telemetry,
+  type TelemetryConfig,
+} from '../logger/index.ts'
+
+/**
+ * Subset of Astro's middleware context we depend on. Kept structural so the
+ * adapter never needs Astro's types at build time (Astro is a peer dep and
+ * its middleware types vary across versions).
+ */
+export interface TelemetryMiddlewareContext {
+  request: Request
+  locals: Record<string, unknown>
+}
+
+/** A `MiddlewareNext`-compatible continuation. */
+export type TelemetryMiddlewareNext = () => Promise<Response> | Response
+
+/** Options for {@link createTelemetryMiddleware}. */
+export interface TelemetryMiddlewareOptions extends TelemetryConfig {
+  /**
+   * Key under `context.locals` where the per-request logger is exposed.
+   * Defaults to `telemetry`.
+   */
+  localsKey?: string
+  /**
+   * Pre-built telemetry instance to reuse instead of constructing one from
+   * the config. Useful for sharing a single manager across requests.
+   */
+  telemetry?: Telemetry
+}
+
+/**
+ * createTelemetryMiddleware — the Astro-idiomatic server-side telemetry hook.
+ *
+ * Returns a `defineMiddleware`-compatible `onRequest` handler that:
+ *   - builds (or reuses) a `@refraction-ui/logger` telemetry manager,
+ *   - exposes a per-request child logger on `context.locals[localsKey]`
+ *     (bound with method + path), so SSR pages/endpoints can log,
+ *   - wraps the downstream chain in a span recording duration + status,
+ *   - flushes buffered records once the response is produced.
+ *
+ * ```ts
+ * // src/middleware.ts
+ * import { defineMiddleware } from 'astro:middleware'
+ * import { createTelemetryMiddleware } from '../astro-logger/index.ts'
+ *
+ * export const onRequest = defineMiddleware(
+ *   createTelemetryMiddleware({ app: 'web', env: 'production', endpoint: '/collect' }),
+ * )
+ * ```
+ */
+export function createTelemetryMiddleware(
+  options: TelemetryMiddlewareOptions,
+): (
+  context: TelemetryMiddlewareContext,
+  next: TelemetryMiddlewareNext,
+) => Promise<Response> {
+  const { localsKey = 'telemetry', telemetry, ...config } = options
+  const root: Telemetry = telemetry ?? createTelemetry(config)
+
+  return async function onRequest(
+    context: TelemetryMiddlewareContext,
+    next: TelemetryMiddlewareNext,
+  ): Promise<Response> {
+    const url = new URL(context.request.url)
+    const method = context.request.method
+    const path = url.pathname
+
+    const requestLogger = root.child({ method, path })
+    context.locals[localsKey] = requestLogger
+
+    const span = requestLogger.startSpan('astro.request', { method, path })
+    try {
+      const response = await next()
+      span.end({ attributes: { status: response.status } })
+      return response
+    } catch (error) {
+      span.end({ error })
+      requestLogger.error('astro.request.error', {
+        method,
+        path,
+        message: error instanceof Error ? error.message : String(error),
+      })
+      throw error
+    } finally {
+      // Best-effort delivery of any buffered records for this request.
+      void root.flush()
+    }
+  }
+}

package/dist/index.ts

@@ -77,3 +77,5 @@ export * from './astro-link-card/index.ts';
 export * from './astro-card-grid/index.ts';
 export * from './astro-payment/index.ts';
 export * from './astro-command-input/index.ts';
+export * from './astro-logger/index.ts';
+export * from './astro-analytics/index.ts';

package/dist/logger/console-sink.ts

@@ -0,0 +1,64 @@
+import type { LogLevel, LogRecord, SpanRecord, TelemetrySink } from './types.js'
+
+/** Console method used for each level. */
+const METHOD: Record<LogLevel, 'debug' | 'info' | 'warn' | 'error'> = {
+  debug: 'debug',
+  info: 'info',
+  warn: 'warn',
+  error: 'error',
+  fatal: 'error',
+}
+
+export interface ConsoleSinkOptions {
+  /** Single-line pretty output (vs. structured JSON). */
+  pretty?: boolean
+  /** Console to write to (injectable for tests). Defaults to global console. */
+  console?: Pick<Console, 'debug' | 'info' | 'warn' | 'error'>
+}
+
+/**
+ * Default zero-dependency transport. Used whenever no `endpoint` is set.
+ * Synchronous; `flush()` is a resolved no-op (nothing is buffered).
+ */
+export function createConsoleSink(opts?: ConsoleSinkOptions): TelemetrySink {
+  const pretty = opts?.pretty ?? true
+  const out = opts?.console ?? console
+
+  function emit(level: LogLevel, line: string, payload: unknown): void {
+    out[METHOD[level]](line, payload)
+  }
+
+  return {
+    name: 'console',
+
+    log(record: LogRecord): void {
+      if (pretty) {
+        const ts = new Date(record.timestamp).toISOString()
+        emit(
+          record.level,
+          `${ts} ${record.level.toUpperCase()} [${record.app}] ${record.message}`,
+          record.context,
+        )
+      } else {
+        emit(record.level, JSON.stringify({ type: 'log', ...record }), record.context)
+      }
+    },
+
+    span(record: SpanRecord): void {
+      const level: LogLevel = record.status === 'error' ? 'error' : 'debug'
+      if (pretty) {
+        emit(
+          level,
+          `[span] ${record.name} ${record.durationMs.toFixed(2)}ms (${record.status})`,
+          record.context,
+        )
+      } else {
+        emit(level, JSON.stringify({ type: 'span', ...record }), record.context)
+      }
+    },
+
+    async flush(): Promise<void> {
+      // Console is synchronous — nothing buffered.
+    },
+  }
+}

package/dist/logger/faro-engine.ts

@@ -0,0 +1,130 @@
+import type { LogLevel, LogRecord, SpanRecord, TelemetrySink } from './types.js'
+
+/**
+ * Faro-backed engine. `@grafana/faro-web-sdk` + `@grafana/faro-web-tracing`
+ * are **optional peerDependencies** — they are loaded dynamically and never
+ * referenced in this module's public types. If the peers are absent the
+ * factory resolves to `null` so the caller can fall back to console.
+ *
+ * For tests, a `transport` may be injected: an object with a `push(payload)`
+ * method. This bypasses Faro entirely (no network, no peer required).
+ */
+
+/** Minimal structural shape of a Faro-ish transport. Not exported. */
+interface FaroTransport {
+  push(payload: { kind: 'log' | 'span'; record: LogRecord | SpanRecord }): void
+}
+
+export interface FaroEngineOptions {
+  app: string
+  endpoint: string
+  /**
+   * Test/override transport. When provided, the Faro peers are NOT loaded
+   * and records are forwarded straight to `transport.push`.
+   */
+  transport?: FaroTransport
+}
+
+/** Map our levels onto Faro's log-level strings. */
+const FARO_LEVEL: Record<LogLevel, string> = {
+  debug: 'debug',
+  info: 'info',
+  warn: 'warn',
+  error: 'error',
+  fatal: 'error',
+}
+
+/**
+ * Construct the Faro engine. Returns `null` when the optional peers are not
+ * installed and no override transport was supplied — callers treat `null` as
+ * "fall back to console".
+ */
+export async function createFaroSink(
+  opts: FaroEngineOptions,
+): Promise<TelemetrySink | null> {
+  const transport = opts.transport ?? (await loadFaroTransport(opts))
+  if (!transport) return null
+
+  return {
+    name: 'faro',
+
+    log(record: LogRecord): void {
+      transport.push({ kind: 'log', record })
+    },
+
+    span(record: SpanRecord): void {
+      transport.push({ kind: 'span', record })
+    },
+
+    async flush(): Promise<void> {
+      // Faro's own transports flush on their schedule / on beacon; the
+      // manager drives page-exit beacon flushing. Nothing buffered here.
+    },
+  }
+}
+
+/**
+ * Dynamically import the Faro peers and adapt them to {@link FaroTransport}.
+ * Returns `null` if either peer is missing (optional peerDependency absent).
+ */
+async function loadFaroTransport(
+  opts: FaroEngineOptions,
+): Promise<FaroTransport | null> {
+  try {
+    // Indirected so bundlers keep these as runtime-optional dynamic imports.
+    const sdkName = '@grafana/faro-web-sdk'
+    const tracingName = '@grafana/faro-web-tracing'
+    const sdk = (await import(/* @vite-ignore */ sdkName)) as {
+      initializeFaro: (cfg: unknown) => unknown
+      getWebInstrumentations: () => unknown[]
+    }
+    const tracing = (await import(/* @vite-ignore */ tracingName)) as {
+      TracingInstrumentation: new () => unknown
+    }
+
+    const faro = sdk.initializeFaro({
+      url: opts.endpoint,
+      app: { name: opts.app },
+      instrumentations: [
+        ...sdk.getWebInstrumentations(),
+        new tracing.TracingInstrumentation(),
+      ],
+    }) as {
+      api: {
+        pushLog: (msgs: unknown[], opts?: unknown) => void
+        pushEvent: (name: string, attrs?: Record<string, unknown>) => void
+      }
+    }
+
+    return {
+      push({ kind, record }): void {
+        if (kind === 'log') {
+          const r = record as LogRecord
+          faro.api.pushLog([r.message], {
+            level: FARO_LEVEL[r.level],
+            context: flatten(r.context),
+          })
+        } else {
+          const r = record as SpanRecord
+          faro.api.pushEvent(`span:${r.name}`, {
+            durationMs: String(r.durationMs),
+            status: r.status,
+            ...flatten(r.context),
+          })
+        }
+      },
+    }
+  } catch {
+    // Peer not installed (optional) or init failed — caller falls back.
+    return null
+  }
+}
+
+/** Faro context attributes are flat string maps; coerce ours to match. */
+function flatten(ctx: Record<string, unknown>): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(ctx)) {
+    out[k] = typeof v === 'string' ? v : JSON.stringify(v)
+  }
+  return out
+}

package/dist/logger/index.ts

@@ -0,0 +1,39 @@
+// Types (vendor-neutral — no Faro/Grafana types are exported)
+export type {
+  LogLevel,
+  LogContext,
+  LogRecord,
+  SpanRecord,
+  TelemetrySink,
+  TelemetryEnv,
+  TelemetryConfig,
+  Logger,
+  Span,
+  Telemetry,
+} from './types.js'
+export { LEVEL_ORDER } from './types.js'
+
+// Manager
+export { createTelemetry } from './telemetry-manager.js'
+export type { TelemetryPreset } from './telemetry-manager.js'
+
+// Presets
+export { PRESETS, resolvePreset } from './presets.js'
+
+// Built-in transports
+export { createConsoleSink } from './console-sink.js'
+export type { ConsoleSinkOptions } from './console-sink.js'
+
+// Faro engine (optional peers loaded dynamically; types stay vendor-neutral)
+export { createFaroSink } from './faro-engine.js'
+export type { FaroEngineOptions } from './faro-engine.js'
+
+// Kill switch
+export { createNoopTelemetry } from './noop.js'
+
+// Utilities
+export { redact } from './redact.js'
+
+// Mock sink (for testing)
+export { createMockSink } from './mock-sink.js'
+export type { MockSinkExtended } from './mock-sink.js'

package/dist/logger/mock-sink.ts

@@ -0,0 +1,38 @@
+import type { LogRecord, SpanRecord, TelemetrySink } from './types.js'
+
+export interface MockSinkExtended extends TelemetrySink {
+  /** Every log record received, in order. */
+  logs: LogRecord[]
+  /** Every span record received, in order. */
+  spans: SpanRecord[]
+  /** Number of times {@link TelemetrySink.flush} was called. */
+  flushCalls: number
+}
+
+/**
+ * createMockSink — a {@link TelemetrySink} that records everything for
+ * assertions instead of doing I/O. Used to test the manager and the Faro
+ * engine without any network. Mirrors `createMockAIProvider` in `packages/ai`.
+ */
+export function createMockSink(name: string = 'mock'): MockSinkExtended {
+  const sink: MockSinkExtended = {
+    name,
+    logs: [],
+    spans: [],
+    flushCalls: 0,
+
+    log(record: LogRecord): void {
+      sink.logs.push(record)
+    },
+
+    span(record: SpanRecord): void {
+      sink.spans.push(record)
+    },
+
+    async flush(): Promise<void> {
+      sink.flushCalls++
+    },
+  }
+
+  return sink
+}

package/dist/logger/noop.ts

@@ -0,0 +1,52 @@
+import type { Span, Telemetry } from './types.js'
+
+/** Shared no-op span — emits nothing, allocates nothing per call. */
+const NOOP_SPAN: Span = {
+  end(): void {
+    /* no-op */
+  },
+}
+
+/**
+ * Returned by {@link createTelemetry} when `enabled: false`. Every method is
+ * an empty stub, so a bundler can dead-code-eliminate call sites and the
+ * engines (console/Faro) are never imported at runtime. Zero emissions.
+ */
+export function createNoopTelemetry(): Telemetry {
+  const noop: Telemetry = {
+    debug(): void {
+      /* no-op */
+    },
+    info(): void {
+      /* no-op */
+    },
+    warn(): void {
+      /* no-op */
+    },
+    error(): void {
+      /* no-op */
+    },
+    fatal(): void {
+      /* no-op */
+    },
+    child(): Telemetry {
+      return noop
+    },
+    startSpan(): Span {
+      return NOOP_SPAN
+    },
+    async flush(): Promise<void> {
+      /* no-op */
+    },
+    get sinks(): string[] {
+      return []
+    },
+    addSink(): void {
+      /* no-op */
+    },
+    removeSink(): void {
+      /* no-op */
+    },
+  }
+  return noop
+}

package/dist/logger/presets.ts

@@ -0,0 +1,51 @@
+import type { LogLevel, TelemetryEnv } from './types.js'
+
+/**
+ * Behavior derived from {@link TelemetryConfig.env}. The manager reads these
+ * fields to decide level filtering, batching, sampling, and flush triggers.
+ */
+export interface TelemetryPreset {
+  /** Records strictly below this level are dropped. */
+  minLevel: LogLevel
+  /** Buffer records and deliver in batches instead of synchronously. */
+  batch: boolean
+  /** Batch size before an automatic flush (only when `batch`). */
+  batchSize: number
+  /** Default sample rate when config omits `sampleRate`. */
+  sampleRate: number
+  /** Pretty, single-line console output (vs. structured JSON). */
+  pretty: boolean
+  /**
+   * Flush buffered records on `pagehide` + `visibilitychange` (hidden),
+   * using `navigator.sendBeacon` when available.
+   */
+  beaconFlush: boolean
+}
+
+/**
+ * - development: sync, pretty, level=debug, no batching, sample everything.
+ * - production: batched + sampled, level>=warn, beacon flush on page exit.
+ */
+export const PRESETS: Record<TelemetryEnv, TelemetryPreset> = {
+  development: {
+    minLevel: 'debug',
+    batch: false,
+    batchSize: 1,
+    sampleRate: 1,
+    pretty: true,
+    beaconFlush: false,
+  },
+  production: {
+    minLevel: 'warn',
+    batch: true,
+    batchSize: 20,
+    sampleRate: 0.25,
+    pretty: false,
+    beaconFlush: true,
+  },
+}
+
+/** Resolve the preset for an env (defensive copy so callers can't mutate it). */
+export function resolvePreset(env: TelemetryEnv): TelemetryPreset {
+  return { ...PRESETS[env] }
+}

package/dist/logger/redact.ts

@@ -0,0 +1,33 @@
+import type { LogContext } from './types.js'
+
+/**
+ * Deep-strip any object key whose name (case-insensitive) is in `keys`.
+ * Arrays are walked; cycles are guarded; non-matching values pass through
+ * unchanged. Returns a new structure — the input is never mutated.
+ */
+export function redact(value: LogContext, keys: string[]): LogContext {
+  if (keys.length === 0) return value
+  const lookup = new Set(keys.map((k) => k.toLowerCase()))
+  return walk(value, lookup, new WeakSet()) as LogContext
+}
+
+function walk(value: unknown, keys: Set<string>, seen: WeakSet<object>): unknown {
+  if (value === null || typeof value !== 'object') return value
+
+  if (seen.has(value as object)) return '[Circular]'
+  seen.add(value as object)
+
+  if (Array.isArray(value)) {
+    return value.map((item) => walk(item, keys, seen))
+  }
+
+  const out: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    if (keys.has(k.toLowerCase())) {
+      out[k] = '[REDACTED]'
+      continue
+    }
+    out[k] = walk(v, keys, seen)
+  }
+  return out
+}