@wippy-fe/log 0.0.19

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@wippy-fe/log",
+  "version": "0.0.19",
+  "description": "Logging layer for Wippy micro-frontend platform",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    },
+    "./default-receiver": {
+      "import": "./dist/default-receiver.mjs",
+      "types": "./dist/default-receiver.d.mts"
+    },
+    "./logger": {
+      "import": "./dist/logger.mjs",
+      "types": "./dist/logger.d.mts"
+    },
+    "./sentry-transport": {
+      "import": "./dist/sentry-transport.mjs",
+      "types": "./dist/sentry-transport.d.mts"
+    },
+    "./console-transport": {
+      "import": "./dist/console-transport.mjs",
+      "types": "./dist/console-transport.d.mts"
+    },
+    "./gelf-transport": {
+      "import": "./dist/gelf-transport.mjs",
+      "types": "./dist/gelf-transport.d.mts"
+    }
+  },
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "scripts": {
+    "build:types": "tsup"
+  },
+  "peerDependencies": {
+    "@sentry/browser": ">=8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@sentry/browser": {
+      "optional": true
+    }
+  }
+}

package/src/console-transport.ts

@@ -0,0 +1,68 @@
+/* eslint-disable no-console -- this IS the console transport */
+import type { LogTransport, NormalizedLogEntry } from './types'
+import { LogLevel, reconstructError } from './types'
+
+export interface ConsoleTransportOptions {
+  collapsed?: boolean
+}
+
+function formatPrefix(entry: NormalizedLogEntry): string {
+  const { source } = entry
+  if (source.resourceId)
+    return `[${source.layer}:${source.resourceType ?? 'unknown'}:${source.resourceId}]`
+  return `[${source.layer}]`
+}
+
+function collectMetadata(entry: NormalizedLogEntry): Record<string, unknown> | null {
+  const meta: Record<string, unknown> = {}
+  if (entry.callerStack)
+    meta.callerStack = entry.callerStack
+  if (entry.extra)
+    meta.extra = entry.extra
+  if (Object.keys(entry.tags).length > 0)
+    meta.tags = entry.tags
+  if (Object.keys(entry.contexts).length > 0)
+    meta.contexts = entry.contexts
+  if (Object.keys(meta).length === 0)
+    return null
+  return meta
+}
+
+export function consoleTransport(options?: ConsoleTransportOptions): LogTransport {
+  return {
+    name: 'console',
+    handle(entry: NormalizedLogEntry) {
+      const prefix = formatPrefix(entry)
+      const message = `${prefix} ${entry.message}`
+      const meta = collectMetadata(entry)
+
+      if (entry.subAction === 'captureException' && entry.error) {
+        const err = reconstructError(entry.error)
+
+        if (options?.collapsed && entry.breadcrumbs.length > 0) {
+          console.groupCollapsed(message)
+          console.error(err)
+          if (meta)
+            console.log(meta)
+          console.log('Breadcrumbs:', entry.breadcrumbs)
+          console.groupEnd()
+        }
+        else {
+          console.error(message, err, ...(meta ? [meta] : []))
+        }
+        return
+      }
+
+      const args: unknown[] = meta ? [message, meta] : [message]
+
+      if (entry.level <= LogLevel.Error)
+        console.error(...args)
+      else if (entry.level <= LogLevel.Warning)
+        console.warn(...args)
+      else if (entry.level <= LogLevel.Info)
+        console.info(...args)
+      else
+        console.debug(...args)
+    },
+  }
+}

package/src/default-receiver.ts

@@ -0,0 +1,27 @@
+import type { LogReceiverHandle, LogTransport } from './types'
+import { consoleTransport } from './console-transport'
+import { createReceiverCore } from './receiver-core'
+
+export function createDefaultLogReceiver(env: Record<string, string>): LogReceiverHandle {
+  const transports: LogTransport[] = [consoleTransport()]
+
+  if (env.PUBLIC_SENTRY_DSN) {
+    const dsn = env.PUBLIC_SENTRY_DSN
+    import('./sentry-transport').then(({ sentryTransport }) => {
+      transports.push(sentryTransport({ dsn }))
+    }).catch((e) => {
+      console.warn('[@wippy-fe/log] Sentry transport unavailable:', e)
+    })
+  }
+
+  if (env.PUBLIC_GELF_URL) {
+    const url = env.PUBLIC_GELF_URL
+    import('./gelf-transport').then(({ gelfTransport }) => {
+      transports.push(gelfTransport({ url }))
+    }).catch((e) => {
+      console.warn('[@wippy-fe/log] GELF transport unavailable:', e)
+    })
+  }
+
+  return createReceiverCore(transports)
+}

package/src/gelf-transport.ts

@@ -0,0 +1,93 @@
+import type { LogTransport, NormalizedLogEntry } from './types'
+
+export interface GelfTransportOptions {
+  url: string
+  host?: string
+  facility?: string
+}
+
+const BATCH_INTERVAL = 1000
+const MAX_BATCH_SIZE = 20
+
+export function gelfTransport(options: GelfTransportOptions): LogTransport {
+  const { url, host = 'wippy', facility } = options
+  let batch: object[] = []
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  function sendBatch(): void {
+    if (batch.length === 0)
+      return
+    const entries = batch
+    batch = []
+    timer = null
+
+    for (const entry of entries) {
+      fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(entry),
+      }).catch(() => {})
+    }
+  }
+
+  function scheduleSend(): void {
+    if (!timer)
+      timer = setTimeout(sendBatch, BATCH_INTERVAL)
+  }
+
+  function toGelf(entry: NormalizedLogEntry): object {
+    const gelf: Record<string, unknown> = {
+      version: '1.1',
+      host,
+      short_message: entry.message,
+      timestamp: entry.timestamp / 1000,
+      level: entry.level,
+      _wippy_layer: entry.source.layer,
+    }
+
+    if (facility)
+      gelf.facility = facility
+    if (entry.source.resourceId)
+      gelf._wippy_resourceId = entry.source.resourceId
+    if (entry.source.resourceType)
+      gelf._wippy_resourceType = entry.source.resourceType
+    if (entry.source.nestingDepth != null)
+      gelf._wippy_nestingDepth = entry.source.nestingDepth
+
+    if (entry.error?.stack)
+      gelf.full_message = entry.error.stack
+
+    for (const [key, value] of Object.entries(entry.tags))
+      gelf[`_tag_${key}`] = value
+
+    if (entry.extra) {
+      for (const [key, value] of Object.entries(entry.extra))
+        gelf[`_extra_${key}`] = typeof value === 'string' ? value : JSON.stringify(value)
+    }
+
+    return gelf
+  }
+
+  return {
+    name: 'gelf',
+    handle(entry: NormalizedLogEntry) {
+      batch.push(toGelf(entry))
+      if (batch.length >= MAX_BATCH_SIZE)
+        sendBatch()
+      else
+        scheduleSend()
+    },
+    async flush() {
+      if (timer) {
+        clearTimeout(timer)
+        timer = null
+      }
+      sendBatch()
+    },
+    destroy() {
+      if (timer)
+        clearTimeout(timer)
+      batch = []
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+import type { LogReceiverHandle, LogReceiverOptions } from './types'
+import { createReceiverCore } from './receiver-core'
+
+export type {
+  Breadcrumb,
+  CmdLogPayload,
+  CmdLogSubAction,
+  CreateLoggerOptions,
+  LoggerApi,
+  LogLevelValue,
+  LogReceiverHandle,
+  LogReceiverOptions,
+  LogSource,
+  LogTransport,
+  NormalizedLogEntry,
+} from './types'
+
+export { LogLevel } from './types'
+
+export function createLogReceiver(options: LogReceiverOptions): LogReceiverHandle {
+  return createReceiverCore(options.transports, options.context)
+}

package/src/logger.ts

@@ -0,0 +1,69 @@
+import type { CmdLogSubAction, CreateLoggerOptions, LoggerApi, LogLevelValue, LogSource } from './types'
+import { captureCallerStack, LogLevel, serializeError } from './types'
+
+const DEFAULT_MESSAGE_TYPE = '@gen2-chat'
+
+// Frames: caller → info/warn/error → logWithStack → send
+const LOG_FRAMES_TO_SKIP = 3
+// Frames: caller → captureException/captureMessage → send
+const CAPTURE_FRAMES_TO_SKIP = 2
+
+export function createLogger(options: CreateLoggerOptions): LoggerApi {
+  const { source, messageType = DEFAULT_MESSAGE_TYPE } = options
+  const target = options.target ?? window.parent
+
+  function send(subAction: CmdLogSubAction, data: Record<string, unknown>, callerStack?: string): void {
+    target?.postMessage(JSON.stringify({
+      type: messageType,
+      action: 'cmd-log',
+      subAction,
+      data,
+      source,
+      timestamp: Date.now(),
+      callerStack,
+    }), '*')
+  }
+
+  function log(level: LogLevelValue, message: string, data?: Record<string, unknown>): void {
+    send('log', { message, level, extra: data })
+  }
+
+  function logWithStack(level: LogLevelValue, message: string, data?: Record<string, unknown>): void {
+    send('log', { message, level, extra: data }, captureCallerStack(LOG_FRAMES_TO_SKIP))
+  }
+
+  return {
+    debug: (message, data) => log(LogLevel.Debug, message, data),
+    info: (message, data) => logWithStack(LogLevel.Info, message, data),
+    warn: (message, data) => logWithStack(LogLevel.Warning, message, data),
+    error: (message, data) => logWithStack(LogLevel.Error, message, data),
+
+    captureException(error, extra) {
+      send('captureException', { ...serializeError(error), extra }, captureCallerStack(CAPTURE_FRAMES_TO_SKIP))
+    },
+
+    captureMessage(message, level, extra) {
+      send('captureMessage', { message, level: level ?? LogLevel.Info, extra }, captureCallerStack(CAPTURE_FRAMES_TO_SKIP))
+    },
+
+    addBreadcrumb(breadcrumb) {
+      send('addBreadcrumb', { ...breadcrumb, timestamp: breadcrumb.timestamp ?? Date.now() })
+    },
+
+    setContext(name, data) {
+      send('setContext', { name, data })
+    },
+
+    setTag(key, value) {
+      send('setTag', { key, value })
+    },
+  }
+}
+
+export function createChildLogger(source: Omit<LogSource, 'layer'>): LoggerApi {
+  return createLogger({ source: { layer: 'child', ...source } })
+}
+
+export function createHostLogger(): LoggerApi {
+  return createLogger({ source: { layer: 'host' } })
+}

package/src/receiver-core.ts

@@ -0,0 +1,150 @@
+import type { Breadcrumb, LogReceiverHandle, LogSource, LogTransport, NormalizedLogEntry } from './types'
+import { LogLevel } from './types'
+
+interface SourceState {
+  breadcrumbs: Breadcrumb[]
+  contexts: Record<string, Record<string, unknown>>
+  tags: Record<string, string>
+}
+
+const MAX_BREADCRUMBS = 100
+const DEFAULT_MESSAGE_TYPE = '@gen2-chat'
+
+function getSourceKey(source: LogSource): string {
+  return `${source.layer}:${source.resourceId ?? 'unknown'}`
+}
+
+function isValidSource(source: unknown): source is LogSource {
+  return source != null
+    && typeof source === 'object'
+    && 'layer' in source
+    && (source.layer === 'child' || source.layer === 'host')
+}
+
+export function createReceiverCore(
+  transports: LogTransport[],
+  globalContext?: Record<string, unknown>,
+  messageType: string = DEFAULT_MESSAGE_TYPE,
+): LogReceiverHandle {
+  const sourceStates = new Map<string, SourceState>()
+
+  function getState(sourceKey: string): SourceState {
+    let state = sourceStates.get(sourceKey)
+    if (!state) {
+      state = { breadcrumbs: [], contexts: {}, tags: {} }
+      sourceStates.set(sourceKey, state)
+    }
+    return state
+  }
+
+  function dispatch(entry: NormalizedLogEntry): void {
+    for (const transport of transports)
+      transport.handle(entry)
+  }
+
+  function handleMessage(event: MessageEvent): void {
+    if (typeof event.data !== 'string')
+      return
+
+    let msg: any
+    try {
+      msg = JSON.parse(event.data)
+    }
+    catch {
+      return
+    }
+
+    if (msg.type !== messageType || msg.action !== 'cmd-log')
+      return
+
+    const { subAction, data, source, timestamp, callerStack } = msg
+    if (!data || typeof data !== 'object')
+      return
+
+    const resolvedSource: LogSource = isValidSource(source)
+      ? source
+      : { layer: 'child' }
+    const sourceKey = getSourceKey(resolvedSource)
+    const state = getState(sourceKey)
+
+    switch (subAction) {
+      case 'addBreadcrumb': {
+        state.breadcrumbs.push(data as Breadcrumb)
+        if (state.breadcrumbs.length > MAX_BREADCRUMBS)
+          state.breadcrumbs.shift()
+        break
+      }
+      case 'setContext': {
+        const name = data.name as string | undefined
+        if (!name)
+          break
+        if (data.data === null)
+          delete state.contexts[name]
+        else
+          state.contexts[name] = data.data as Record<string, unknown>
+        break
+      }
+      case 'setTag': {
+        const key = data.key as string | undefined
+        if (!key)
+          break
+        if (data.value === null)
+          delete state.tags[key]
+        else
+          state.tags[key] = data.value as string
+        break
+      }
+      case 'log':
+      case 'captureException':
+      case 'captureMessage': {
+        const entry: NormalizedLogEntry = {
+          subAction,
+          level: data.level ?? LogLevel.Info,
+          message: data.message ?? '',
+          timestamp: timestamp ?? Date.now(),
+          source: resolvedSource,
+          breadcrumbs: [...state.breadcrumbs],
+          contexts: {
+            ...(globalContext ? { global: globalContext } : {}),
+            ...state.contexts,
+          },
+          tags: { ...state.tags },
+        }
+        if (callerStack)
+          entry.callerStack = callerStack
+        if (data.extra)
+          entry.extra = data.extra as Record<string, unknown>
+        if (subAction === 'captureException') {
+          entry.error = {
+            name: (data.name as string) ?? 'Error',
+            message: (data.message as string) ?? '',
+            stack: data.stack as string | undefined,
+          }
+          entry.level = data.level ?? LogLevel.Error
+        }
+        dispatch(entry)
+        break
+      }
+    }
+  }
+
+  window.addEventListener('message', handleMessage)
+
+  function onUnload(): void {
+    for (const transport of transports)
+      transport.flush?.()
+  }
+  window.addEventListener('beforeunload', onUnload)
+
+  return {
+    destroy() {
+      window.removeEventListener('message', handleMessage)
+      window.removeEventListener('beforeunload', onUnload)
+      for (const transport of transports) {
+        transport.flush?.()
+        transport.destroy?.()
+      }
+      sourceStates.clear()
+    },
+  }
+}

package/src/sentry-transport.ts

@@ -0,0 +1,112 @@
+import type { LogTransport, NormalizedLogEntry } from './types'
+import { LogLevel, reconstructError } from './types'
+
+export interface SentryTransportOptions {
+  dsn: string
+  environment?: string
+  release?: string
+  tracesSampleRate?: number
+}
+
+type SentryModule = typeof import('@sentry/browser')
+
+let sentryInitialized = false
+let Sentry: SentryModule | null = null
+
+async function ensureSentry(options: SentryTransportOptions): Promise<SentryModule | null> {
+  if (sentryInitialized)
+    return Sentry
+  try {
+    Sentry = await import('@sentry/browser')
+    Sentry.init({
+      dsn: options.dsn,
+      environment: options.environment,
+      release: options.release,
+      tracesSampleRate: options.tracesSampleRate ?? 0,
+    })
+    sentryInitialized = true
+  }
+  catch (e) {
+    console.warn('[@wippy-fe/log] Failed to load @sentry/browser:', e)
+  }
+  return Sentry
+}
+
+function toSentryLevel(level: number): 'fatal' | 'error' | 'warning' | 'info' | 'debug' {
+  if (level <= LogLevel.Alert)
+    return 'fatal'
+  if (level <= LogLevel.Error)
+    return 'error'
+  if (level <= LogLevel.Warning)
+    return 'warning'
+  if (level <= LogLevel.Info)
+    return 'info'
+  return 'debug'
+}
+
+export function sentryTransport(options: SentryTransportOptions): LogTransport {
+  const ready = ensureSentry(options)
+
+  return {
+    name: 'sentry',
+    handle(entry: NormalizedLogEntry) {
+      ready.then((sentry) => {
+        if (!sentry)
+          return
+
+        sentry.withScope((scope) => {
+          scope.setTag('wippy.layer', entry.source.layer)
+          if (entry.source.resourceId)
+            scope.setTag('wippy.resourceId', entry.source.resourceId)
+          if (entry.source.resourceType)
+            scope.setTag('wippy.resourceType', entry.source.resourceType)
+          if (entry.source.nestingDepth != null)
+            scope.setTag('wippy.nestingDepth', String(entry.source.nestingDepth))
+
+          for (const [key, value] of Object.entries(entry.tags))
+            scope.setTag(key, value)
+
+          scope.setContext('wippy', { ...entry.source })
+          for (const [name, data] of Object.entries(entry.contexts))
+            scope.setContext(name, data)
+
+          for (const bc of entry.breadcrumbs) {
+            sentry.addBreadcrumb({
+              category: bc.category,
+              message: bc.message,
+              data: bc.data,
+              level: toSentryLevel(bc.level ?? LogLevel.Info),
+              type: bc.type,
+              timestamp: bc.timestamp ? bc.timestamp / 1000 : undefined,
+            })
+          }
+
+          if (entry.extra)
+            scope.setExtras(entry.extra)
+
+          if (entry.callerStack)
+            scope.setExtra('callerStack', entry.callerStack)
+
+          if (entry.subAction === 'captureException' && entry.error) {
+            const err = reconstructError(entry.error)
+            if (!err.stack && entry.callerStack)
+              err.stack = entry.callerStack
+            sentry.captureException(err)
+          }
+          else {
+            sentry.captureMessage(entry.message, toSentryLevel(entry.level))
+          }
+        })
+      })
+    },
+    async flush() {
+      const sentry = await ready
+      if (sentry)
+        await sentry.flush(2000)
+    },
+    destroy() {
+      if (Sentry)
+        Sentry.close()
+    },
+  }
+}

package/src/types.ts

@@ -0,0 +1,17 @@
+export {
+  type Breadcrumb,
+  captureCallerStack,
+  type CmdLogPayload,
+  type CmdLogSubAction,
+  type CreateLoggerOptions,
+  type LoggerApi,
+  LogLevel,
+  type LogLevelValue,
+  type LogReceiverHandle,
+  type LogReceiverOptions,
+  type LogSource,
+  type LogTransport,
+  type NormalizedLogEntry,
+  reconstructError,
+  serializeError,
+} from '../../../src/shared/logging/types'