@alumbwe/anvil 1.0.20 → 1.0.21

package/vendor/@anvil/common/src/util/lazy-response-ads.ts

@@ -0,0 +1,92 @@
+export type LazyResponseAdQueue<T extends { impUrl: string }> = {
+  targetCounts: Map<string, number>
+  attemptedCounts: Map<string, number>
+  inFlight: Map<string, Promise<void>>
+  usedImpUrls: Set<string>
+}
+
+/** Maximum number of unique ads auctioned for one assistant response. */
+export const MAX_RESPONSE_AD_POOL_SIZE = 4
+
+/**
+ * Before the pool is full, only render ads that have actually loaded. Once all
+ * four are available, fill every eligible slot by cycling that stable pool.
+ */
+export function responseAdDisplayCount(params: {
+  eligibleCount: number
+  poolSize: number
+}): number {
+  const eligibleCount = Math.max(0, Math.floor(params.eligibleCount))
+  const poolSize = Math.max(0, Math.floor(params.poolSize))
+  return poolSize >= MAX_RESPONSE_AD_POOL_SIZE
+    ? eligibleCount
+    : Math.min(eligibleCount, poolSize)
+}
+
+/** Return the exact pooled ad for a slot, repeating the pool in order. */
+export function getResponseAdForSlot<T>(
+  ads: readonly T[],
+  slotIndex: number,
+): T | undefined {
+  if (ads.length === 0) return undefined
+  return ads[Math.max(0, Math.floor(slotIndex)) % ads.length]
+}
+
+export function createLazyResponseAdQueue<
+  T extends { impUrl: string },
+>(): LazyResponseAdQueue<T> {
+  return {
+    targetCounts: new Map(),
+    attemptedCounts: new Map(),
+    inFlight: new Map(),
+    usedImpUrls: new Set(),
+  }
+}
+
+/**
+ * Raise one response's target ad count and fetch exactly once for each newly
+ * eligible slot, up to {@link MAX_RESPONSE_AD_POOL_SIZE}. Calls are serialized
+ * per response so resolved ads retain their placement order. No-fill and
+ * duplicate results still consume an attempt, preventing render-driven retry
+ * loops.
+ */
+export function requestLazyResponseAds<T extends { impUrl: string }>(params: {
+  queue: LazyResponseAdQueue<T>
+  messageId: string
+  count: number
+  fetchOne: () => Promise<T | null>
+  onAd: (ad: T) => void
+}): Promise<void> | null {
+  const { queue, messageId, fetchOne, onAd } = params
+  const count = Number.isFinite(params.count)
+    ? Math.min(MAX_RESPONSE_AD_POOL_SIZE, Math.max(0, Math.floor(params.count)))
+    : 0
+  const previousTarget = queue.targetCounts.get(messageId) ?? 0
+  if (count <= previousTarget) return queue.inFlight.get(messageId) ?? null
+
+  queue.targetCounts.set(messageId, count)
+  const existing = queue.inFlight.get(messageId)
+  if (existing) return existing
+
+  const task = (async () => {
+    try {
+      for (;;) {
+        const target = queue.targetCounts.get(messageId) ?? 0
+        const attempted = queue.attemptedCounts.get(messageId) ?? 0
+        if (attempted >= target) break
+        queue.attemptedCounts.set(messageId, attempted + 1)
+
+        const ad = await fetchOne()
+        if (!ad || queue.usedImpUrls.has(ad.impUrl)) continue
+
+        queue.usedImpUrls.add(ad.impUrl)
+        onAd(ad)
+      }
+    } finally {
+      queue.inFlight.delete(messageId)
+    }
+  })()
+
+  queue.inFlight.set(messageId, task)
+  return task
+}

package/vendor/@anvil/common/src/util/log-data.ts

@@ -0,0 +1,57 @@
+import { MAX_LOG_DATA_BYTES } from '../schemas/logs'
+
+import type { LogLevel } from '../types/contracts/logs'
+
+/**
+ * Shared pieces of the Axiom log-row pipeline used by every producer that
+ * ingests rows — the long-lived sink (packages/logging/src/sink.ts) and the
+ * Convex direct-ingest helper (anvil/web/convex/lib/axiom_log.ts). Living
+ * here keeps the serialized `data` contract and level ordering identical
+ * across producers, so APL queries behave the same regardless of which
+ * service emitted a row. Deliberately light on imports (the schemas module
+ * pulls only zod) so it stays safe for the Convex bundle.
+ */
+
+/** Numeric severity order for LogLevel, used for min-level gating. */
+export const LOG_LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  fatal: 50,
+}
+
+/**
+ * Serialize a log payload to a single string field, tolerating circular refs
+ * and capping size. The cap applies to ALL sources so a large `data` payload
+ * can't inflate Axiom ingest cost. The truncated form is still valid JSON so
+ * query scripts can `parse_json(data)`.
+ */
+export function serializeLogData(data: unknown): string | null {
+  if (data == null) return null
+  let serialized: string
+  if (typeof data === 'string') {
+    serialized = data
+  } else {
+    try {
+      const seen = new WeakSet()
+      serialized = JSON.stringify(data, (_k, v) => {
+        if (typeof v === 'object' && v !== null) {
+          if (seen.has(v)) return '[Circular]'
+          seen.add(v)
+        }
+        return v
+      })
+    } catch {
+      return null
+    }
+  }
+  if (serialized.length > MAX_LOG_DATA_BYTES) {
+    return JSON.stringify({
+      _truncated: true,
+      original_bytes: serialized.length,
+      preview: serialized.slice(0, MAX_LOG_DATA_BYTES),
+    })
+  }
+  return serialized
+}

package/vendor/@anvil/common/src/util/log-ingest.ts

@@ -0,0 +1,58 @@
+import { MAX_LOG_DATA_BYTES } from '../schemas/logs'
+
+import type { LogRecordInput } from '../schemas/logs'
+import type { LogRow, LogSource } from '../types/contracts/logs'
+
+/**
+ * Truncate an oversized payload so a single client cannot bloat ingest volume.
+ * Returns the original value when small.
+ */
+function truncateData(data: unknown): unknown {
+  if (data === undefined) return null
+  let serialized: string
+  try {
+    serialized = JSON.stringify(data)
+  } catch {
+    return { _unserializable: true }
+  }
+  if (serialized.length <= MAX_LOG_DATA_BYTES) return data
+  return {
+    _truncated: true,
+    original_bytes: serialized.length,
+    preview: serialized.slice(0, MAX_LOG_DATA_BYTES),
+  }
+}
+
+/**
+ * Map validated client ingest records onto `LogRow`s. The server is the source
+ * of truth for identity/environment: it stamps `source`, `service`, `env`, the
+ * authenticated `user_id`, and a received-at fallback timestamp.
+ */
+export function buildLogRows(params: {
+  records: LogRecordInput[]
+  source: LogSource
+  service: string
+  env: string
+  userId?: string | null
+  now: Date
+}): LogRow[] {
+  const { records, source, service, env, userId = null, now } = params
+  return records.map((record) => {
+    const ts = record.timestamp ? new Date(record.timestamp) : now
+    return {
+      id: crypto.randomUUID(),
+      timestamp: isNaN(ts.getTime()) ? now : ts,
+      level: record.level,
+      source,
+      service,
+      env,
+      event: record.event ?? null,
+      message: record.message ?? null,
+      user_id: userId,
+      client_session_id: record.client_session_id ?? null,
+      client_request_id: record.client_request_id ?? null,
+      fingerprint_id: record.fingerprint_id ?? null,
+      data: truncateData(record.data),
+    }
+  })
+}

package/vendor/@anvil/common/src/util/log-mirror.ts

@@ -0,0 +1,34 @@
+/**
+ * Which analytics events get mirrored into the Axiom logs dataset.
+ *
+ * PostHog stays the product-analytics system of record (it keeps EVERY event).
+ * Axiom is the SQL-queryable copy for debugging/ops, where a handful of
+ * extremely high-volume, low-query-value PostHog auto-events would otherwise
+ * dominate ingest cost and bury the events we actually query (named product
+ * events, signups, logins, errors). We drop those from the Axiom mirror only.
+ *
+ * `$snapshot` (session replay) alone is the bulk of ingest. Autocapture,
+ * heatmaps and web-vitals are similar: useful in PostHog's product UI, noise in
+ * APL. Everything else — `$pageview`, `$identify`, `$exception`, `$rageclick`,
+ * and all non-`$` named events — is kept.
+ */
+export const AXIOM_MIRROR_DENYLIST: ReadonlySet<string> = new Set([
+  '$snapshot',
+  '$autocapture',
+  '$heatmap',
+  '$$heatmap',
+  '$web_vitals',
+  '$pageleave',
+  // Engaged-time heartbeat: one event per user per minute across every surface.
+  // High volume, low debug value, and PostHog is the system of record for the
+  // metric — keep it out of the Axiom mirror to control ingest cost.
+  'product_active_minute',
+])
+
+/** True if this analytics event should be copied into the Axiom logs dataset. */
+export function shouldMirrorAnalyticsEvent(
+  eventName: string | null | undefined,
+): boolean {
+  if (!eventName) return true
+  return !AXIOM_MIRROR_DENYLIST.has(eventName)
+}

package/vendor/@anvil/common/src/util/lru-cache.ts

@@ -0,0 +1,67 @@
+/**
+ * A simple Least Recently Used (LRU) cache implementation using a Map.
+ * It leverages the fact that Map objects maintain insertion order.
+ */
+export class LRUCache<K, V> {
+  private cache = new Map<K, V>()
+
+  constructor(private maxSize: number) {
+    if (maxSize <= 0) {
+      throw new Error('LRUCache maxSize must be a positive number.')
+    }
+  }
+
+  /**
+   * Retrieves an item from the cache. If found, marks it as recently used.
+   * @param key The key of the item to retrieve.
+   * @returns The value associated with the key, or undefined if not found.
+   */
+  get(key: K): V | undefined {
+    const value = this.cache.get(key)
+    if (value !== undefined) {
+      // Mark as recently used by deleting and re-setting
+      this.cache.delete(key)
+      this.cache.set(key, value)
+      return value
+    }
+    return undefined
+  }
+
+  /**
+   * Adds or updates an item in the cache. If the cache exceeds maxSize,
+   * the least recently used item is evicted.
+   * @param key The key of the item to set.
+   * @param value The value to associate with the key.
+   */
+  set(key: K, value: V): void {
+    // If key already exists, delete it first to update its position
+    if (this.cache.has(key)) {
+      this.cache.delete(key)
+    }
+    // Check if cache is full before adding the new item
+    else if (this.cache.size >= this.maxSize) {
+      // Evict the least recently used item (the first item in the Map's iteration order)
+      const oldestKey = this.cache.keys().next().value
+      if (oldestKey !== undefined) {
+        // Should always be defined if size >= maxSize > 0
+        this.cache.delete(oldestKey)
+      }
+    }
+    // Add the new item (or re-add the updated item)
+    this.cache.set(key, value)
+  }
+
+  /**
+   * Returns the current number of items in the cache.
+   */
+  get size(): number {
+    return this.cache.size
+  }
+
+  /**
+   * Clears all items from the cache.
+   */
+  clear(): void {
+    this.cache.clear()
+  }
+}