@flamingo-stack/openframe-frontend-core 0.0.204 → 0.0.205

package/src/utils/index.ts

@@ -1,5 +1,9 @@
 // Utils exports - client-side only
-export { cn, formatDate, formatNumber, formatPrice, formatBytes, getAllPlatformBaseDomains } from './cn'
+export { cn, getAllPlatformBaseDomains } from './cn'
+// Number / currency / byte / date formatters live in `./format` (single
+// source of truth). Re-exported here so existing callers that pull from
+// the barrel keep working without changing imports.
+export { formatDate, formatNumber, formatPrice, formatBytes } from './format'
 // SVG path constants — re-exported here (server-safe) because icons-v2 has "use client"
 export { PLAY_ICON_PATH } from '../components/icons-v2-generated/media-playback/play-icon'
 export { getPlatformAccentColor, getCurrentPlatform, type ColorCategory } from './ods-color-utils'
@@ -16,9 +20,18 @@ export * from './validation-utils'
 export * from './confidence-helpers'
 // Release date formatting utilities
 export * from './date-formatters'
-export * from './format-relative-time'
-// Dynamic icon registry
-export * from './dynamic-icons'
+// Dynamic icon registry — single source of truth lives at
+// components/chat/utils/icon-registry. Re-exported here so existing
+// `@flamingo-stack/openframe-frontend-core/utils` callers (hub admin
+// social-account screens) keep working without changing their import path.
+export {
+  getDynamicIcon,
+  type DynamicIconSize,
+  ICON_REGISTRY,
+  getIconComponent,
+  normalizeIconKey,
+} from '../components/chat/utils/icon-registry'
+export { getPlatformIconComponent as getPlatformLogo } from './platform-config'
 // Tool type utilities
 export * from './tool-utils'
 // Shell type utilities
@@ -28,4 +41,131 @@ export * from './os-utils'
 // Phone utilities
 export * from './country-phone-utils'
 // Generic domain detection
-export * from './generic-domain-utils'
+export * from './generic-domain-utils'
+
+// Color analysis (canvas-based image color extraction)
+export * from './color-analysis'
+
+// Image-proxy URL builder (pure, runtime-configurable)
+export {
+  type GetProxiedImageUrlOptions,
+  getProxiedImageUrl,
+  urlPathLooksLikeSvg,
+  shouldProxyImage,
+  generateImageSizes,
+} from './image-proxy'
+
+// Number / byte / duration / time / UTC date / initials / metric /
+// trend / range / text helpers — single canonical home for every
+// generic formatter consumed across the lib AND the hub. Hub keeps
+// only vendor-specific helpers (formatClassification / formatPricingModel
+// in `lib/utils/vendor-text.ts`).
+export {
+  formatLargeNumber,
+  formatAbbreviatedNumber,
+  nameInitials,
+  getFirstLastInitials,
+  formatDurationMMSS,
+  formatDurationCompact,
+  formatTimeWithTimezone,
+  formatDurationFromRange,
+  type FormatDateUTCOptions,
+  formatDateUTC,
+  formatCurrency,
+  formatPercent,
+  formatWholeDollars,
+  formatLegalDate,
+  formatBytesShort,
+  formatDateTimeAt,
+  formatDurationFromMs,
+  type MetricFormat,
+  type TrendPolarity,
+  formatCompactMetric,
+  getTrendColors,
+  formatDateRange,
+  formatDuration,
+  formatUnderscoreText,
+  stripHtml,
+  formatBioText,
+  formatClassification,
+  formatPricingModel,
+} from './format'
+
+// Date / time helpers (relative, absolute, range checks, UTC timestamp)
+export {
+  formatRelativeTime,
+  formatAbsoluteDate,
+  formatDateTime,
+  getDetailedTimeDifference,
+  isToday,
+  isWithinMinutes,
+  createUTCTimestamp,
+} from './date-utils'
+
+// Chat source-icons + labels (server-safe — lives here in src/utils/
+// instead of src/components/chat/utils/ so server-side hub callers like
+// doc-chat-utils can use them without tripping the 'use client' boundary)
+export {
+  SOURCE_ICON_NAMES,
+  getSourceIconName,
+  SOURCE_LABELS_BY_TABLE,
+  getSourceLabel,
+} from './source-icons'
+
+// Pure text/wire helpers that originated under components/chat/utils/
+// but are needed by SERVER-SIDE hub callers (doc-chat-utils,
+// hubspot-files-utils, rag-mappers). Re-exporting through utils/ keeps
+// them out of the 'use client' bundle. The chat-side re-export chain
+// stays intact for client consumers via components/chat barrel.
+export {
+  escapeMarkdownInline,
+  type ChatAttachment,
+  buildChatAttachmentViewUrl,
+  formatChatAttachmentMarkdownForBubble,
+  CHAT_ATTACHMENT_VIEW_URL_PREFIX,
+  CHAT_ATTACHMENT_VIEW_TOKEN_QUERY_PARAM,
+  ANTHROPIC_SUPPORTED_IMAGE_MIME,
+  CHAT_ATTACHMENT_VIEW_URL_PREFIX_REGEX_ESCAPED,
+  CHAT_ATTACHMENT_MARKDOWN_PATTERN,
+  stripChatAttachmentMarkdown,
+} from '../components/chat/utils/chat-attachment-markdown'
+export {
+  AUTO_CONTINUATION_DIRECTIVE_PREFIX,
+  buildAutoContinuationDirective,
+  type BuildAutoContinuationOptions,
+} from '../components/chat/utils/auto-continuation-directive'
+export { flattenAssistantContent } from '../components/chat/utils/flatten-assistant-content'
+export {
+  SCROLL_ANCHOR,
+  type ScrollAnchor,
+  SCROLL_ANCHOR_WIRE_KEY,
+  parseScrollAnchor,
+} from '../components/chat/utils/scroll-anchor'
+export {
+  type WireCommandOverride,
+  parseWireCommandOverride,
+  sanitizeTitleForChat,
+  formatSingularLookupInvocation,
+  type CommandOverride,
+  extractEntityIdFilter,
+  buildDiscussAddendum,
+} from '../components/chat/utils/slash-dispatch-utils'
+
+// ClickUp taxonomy constants + label resolver — server-safe so the
+// delivery aggregator + sync engine can read CUSTOM_ITEM_ID.BUG/.REQUEST
+// without going through the 'use client' chat barrel (which erases the
+// values to undefined when imported from server code).
+export { CUSTOM_ITEM_ID, getTaskTypeLabel } from '../components/chat/utils/clickup-task-type-utils'
+
+// Status color scheme + clickup URL helpers (pure, server-safe)
+export { type ColorScheme, getStatusColorScheme } from '../components/chat/utils/agent-status-message'
+export { clickupTaskUrl } from '../components/chat/utils/external-app-urls'
+
+// Cross-origin URL detection (pure — used by server-side rag-mappers
+// + content-url-builder for cross-origin same-tab decisions)
+export { isCrossOriginUrl } from '../components/chat/utils/is-cross-origin-url'
+
+// React-version-aware `fetchpriority` prop builder — spread into `<img>`
+// / `<iframe>` so the rendered DOM attribute is correct under React 18
+// (lowercase) AND React 19 (camelCase) without console warnings.
+export { fetchPriorityProp, type FetchPriorityValue } from './fetch-priority'

package/src/utils/local-storage-adapter.ts

@@ -0,0 +1,105 @@
+/**
+ * Thin JSON-typed Web-Storage adapter (localStorage or sessionStorage).
+ *
+ * Centralizes the SSR-guard + try/catch + silent quota-failure pattern
+ * that every per-feature storage util would otherwise re-implement.
+ *
+ * Optional `namespace` prefix supports platform / user partitioning —
+ * the resolver runs lazily at call time so the namespace can vary across
+ * the lifetime of the page (e.g. proxy-auth switches user, which switches
+ * the key suffix).
+ *
+ * Backend selection (`backend: 'local' | 'session'`):
+ *   - `'local'` (default): persists across browser sessions. Use for
+ *     UI state, chat history metadata, feature-flag opt-ins.
+ *   - `'session'`: cleared when the tab closes. Use for ANY auth-adjacent
+ *     value (bearer tokens, act-as identity, proxy credentials). Reduces
+ *     the XSS-exfiltration attack window from "indefinite" to "until tab
+ *     close" without losing per-session ergonomics.
+ */
+
+export type WebStorageBackend = 'local' | 'session'
+
+export interface LocalStorageAdapter<T> {
+  load(): T | null
+  save(value: T): void
+  clear(): void
+  /** Resolved storage key for the current call. Useful for tests. */
+  resolveKey(): string
+}
+
+export interface LocalStorageAdapterOptions<T> {
+  /** Base storage key. Combined with `namespace()` when provided. */
+  key: string
+  /** Optional dynamic namespace prefix appended via `.` separator.
+   *  Called on EVERY read/write so the key can vary across the page
+   *  lifetime (e.g. when the platform or user identity changes). */
+  namespace?: () => string | null | undefined
+  /** Runtime shape check. Falsey return → `load()` yields null. */
+  validate?: (parsed: unknown) => parsed is T
+  /** Diagnostic prefix written to `console.warn` on parse / write
+   *  failures. Defaults to `'[local-storage]'`. */
+  logTag?: string
+  /** Which Web-Storage backend to use. Defaults to `'local'`. Pass
+   *  `'session'` for anything auth-adjacent so the value evaporates
+   *  when the tab closes. */
+  backend?: WebStorageBackend
+}
+
+function getStorage(backend: WebStorageBackend): Storage | null {
+  if (typeof window === 'undefined') return null
+  try {
+    return backend === 'session' ? window.sessionStorage : window.localStorage
+  } catch {
+    // Some sandboxed contexts (Safari private mode older versions,
+    // strict CSP) throw on storage access — treat as unavailable.
+    return null
+  }
+}
+
+export function createLocalStorageAdapter<T>(
+  options: LocalStorageAdapterOptions<T>,
+): LocalStorageAdapter<T> {
+  const tag = options.logTag ?? '[local-storage]'
+  const backend: WebStorageBackend = options.backend ?? 'local'
+  const resolveKey = (): string => {
+    const ns = options.namespace?.()
+    return ns ? `${ns}.${options.key}` : options.key
+  }
+
+  return {
+    resolveKey,
+    load() {
+      const storage = getStorage(backend)
+      if (!storage) return null
+      try {
+        const raw = storage.getItem(resolveKey())
+        if (!raw) return null
+        const parsed = JSON.parse(raw) as unknown
+        if (options.validate && !options.validate(parsed)) return null
+        return parsed as T
+      } catch (err) {
+        console.warn(`${tag} parse failed for key ${resolveKey()}:`, err)
+        return null
+      }
+    },
+    save(value: T) {
+      const storage = getStorage(backend)
+      if (!storage) return
+      try {
+        storage.setItem(resolveKey(), JSON.stringify(value))
+      } catch (err) {
+        console.warn(`${tag} write failed for key ${resolveKey()}:`, err)
+      }
+    },
+    clear() {
+      const storage = getStorage(backend)
+      if (!storage) return
+      try {
+        storage.removeItem(resolveKey())
+      } catch (err) {
+        console.warn(`${tag} clear failed for key ${resolveKey()}:`, err)
+      }
+    },
+  }
+}

package/src/utils/source-icons.ts

@@ -0,0 +1,219 @@
+/**
+ * Per-source icon-name + label lookup. Keyed by `RagTableConfig.id` (the same
+ * id used in `chat_source_rag_tables.rag_table_id` and on each
+ * `ChatRef.sourceRepo`).
+ *
+ * Server-safe — lives in `src/utils/` (no `'use client'` banner) so
+ * hub server-side rag-mappers + chat route handlers can call
+ * `getSourceLabel()` / `getSourceIconName()` directly. The client-side
+ * chat barrel re-exports from here for ergonomic client imports.
+ *
+ * Used by SOURCE-LEVEL chip surfaces:
+ *   - The chip strip below an assistant message.
+ *   - The tracking-row source glyph on inline entity cards.
+ *
+ * Why a small map here instead of a column on RAG_TABLE_CONFIGS:
+ *   - The icon NAME is a small string; the resolver (icon-name → React
+ *     component) lives in `src/components/chat/utils/icon-registry.ts`
+ *     where it can stay client-only. Server-side consumers stay
+ *     icon-component-free.
+ *   - The mapping is intrinsic to the TABLE, not per-platform — same
+ *     entry serves every (platform, source) binding.
+ *
+ * Per-table admin-UI bucket id (`SOURCE_CATEGORIES_BY_TABLE`) stays
+ * hub-side because it depends on the hub's `RagSourceCategoryId` enum.
+ */
+
+/** Map RagTableConfig.id → icon_name (resolvable via `getIconComponent`). */
+export const SOURCE_ICON_NAMES: Record<string, string> = {
+  // Doc tables
+  'openframe-docs':              'openframe',
+  'data-room-docs':              'shield',
+
+  // CMS / programs
+  'blog-posts':                  'newspaper',
+  'product-releases':            'rocket',
+  'case-studies':                'briefcase',
+  'onboarding-guides':           'graduation-cap',
+  webinars:                      'video',
+  events:                        'calendar',
+  podcasts:                      'headphones',
+  'customer-interviews':         'users',
+
+  // Financials
+  'investor-updates':            'mail',
+  'financial-kpis':              'activity',
+  'financial-cap-table':         'table',
+  'financial-pnl':               'trending-up',
+  'financial-balance-sheet':     'dollar-sign',
+  'financial-cash-flow':         'banknote',
+
+  // ClickUp
+  'clickup-roadmap':             'clickup',
+  'clickup-delivery':            'clickup',
+  'clickup-tasks-internal':      'clickup',
+
+  // GitHub
+  'github-commits':              'github',
+  'github-pull-requests':        'github',
+  'github-pr-reviews':           'github',
+  'github-commits-public':       'github',
+  'github-pull-requests-public': 'github',
+  'github-pr-reviews-public':    'github',
+
+  // HubSpot
+  'hubspot-tickets':             'hubspot',
+  'hubspot-tickets-anon':        'hubspot',
+  'hubspot-tickets-self':        'hubspot',
+
+  // Communications
+  'slack-messages':              'slack',
+}
+
+/** Lookup an icon name by RagTableConfig.id. Returns undefined when
+ *  unknown so callers can decide whether to fall back to documentType
+ *  or to the generic FileText glyph in the icon registry. */
+export function getSourceIconName(tableId: string | null | undefined): string | undefined {
+  if (!tableId) return undefined
+  return SOURCE_ICON_NAMES[tableId]
+}
+
+/**
+ * Per-table display LABEL — used by SERVER-SIDE chip-strip rendering
+ * (the row's "Customer Interviews (8 records)" chip below an assistant
+ * message).
+ *
+ * The chip GRID + autocomplete DROPDOWN read their command label
+ * from the DB (per-source `chat_admin_slash_commands.label`) — those
+ * surfaces can carry per-source labels (e.g. "OpenFrame Commits" vs
+ * "GitHub Commits" for the same table). This map is the TABLE-LEVEL
+ * label used by sub-message chips where a SINGLE label per table is
+ * sufficient regardless of which source's chat is rendering.
+ */
+export const SOURCE_LABELS_BY_TABLE: Record<string, string> = {
+  // Doc tables
+  'openframe-docs':              'OpenFrame Docs',
+  'data-room-docs':              'Data Room',
+
+  // CMS / programs
+  'blog-posts':                  'Blog Posts',
+  'product-releases':            'Product Releases',
+  'case-studies':                'Case Studies',
+  'onboarding-guides':           'Onboarding Guides',
+  webinars:                      'Webinars',
+  events:                        'Events',
+  podcasts:                      'Podcasts',
+  'customer-interviews':         'Customer Interviews',
+
+  // Financials
+  'investor-updates':            'Investor Updates',
+  'financial-kpis':              'Financial KPIs',
+  'financial-cap-table':         'Cap Table',
+  'financial-pnl':               'Profit & Loss',
+  'financial-balance-sheet':     'Balance Sheet',
+  'financial-cash-flow':         'Cash Flow',
+
+  // ClickUp
+  'clickup-roadmap':             'ClickUp Roadmap',
+  'clickup-delivery':            'ClickUp Delivery',
+  'clickup-tasks-internal':      'ClickUp Tasks',
+
+  // GitHub
+  'github-commits':              'GitHub Commits',
+  'github-pull-requests':        'GitHub Pull Requests',
+  'github-pr-reviews':           'GitHub PR Reviews',
+  'github-commits-public':       'OpenFrame Commits',
+  'github-pull-requests-public': 'OpenFrame Pull Requests',
+  'github-pr-reviews-public':    'OpenFrame PR Reviews',
+
+  // HubSpot
+  'hubspot-tickets':             'HubSpot Tickets',
+  'hubspot-tickets-anon':        'Known Issues',
+  'hubspot-tickets-self':        'My Tickets',
+
+  // Communications
+  'slack-messages':              'OpenMSP Community',
+}
+
+/** Lookup a human-readable label by RagTableConfig.id. Falls back
+ *  to the raw id (chip text becomes the table slug — visible bug
+ *  that prompts an entry to land in `SOURCE_LABELS_BY_TABLE`). */
+export function getSourceLabel(tableId: string): string {
+  return SOURCE_LABELS_BY_TABLE[tableId] ?? tableId
+}
+
+/**
+ * Default `documentType → RagTableConfig.id` reverse map.
+ *
+ * Mirrors the canonical lookup the hub registers via
+ * `lib/config/rag-table-config.ts:tableIdForDocumentType()` — same vocabulary
+ * the LLM emits inside `[card://<type>:<id>]` markers, same tableIds the
+ * retrieval layer routes by, and same set of keys covered by
+ * `SOURCE_ICON_NAMES` / `SOURCE_LABELS_BY_TABLE` above.
+ *
+ * Server-safe (no `'use client'` banner), keyed by string for forward
+ * compatibility — adding a new RAG table is a single-line edit here so
+ * lib-based embedders pick it up without re-publishing.
+ *
+ * Embedders that need a CUSTOM mapping (e.g. polymorphic types whose
+ * tableId depends on per-tenant config) still pass their own
+ * `tableIdForDocumentType` callback to `useEmbeddedChat`; this default
+ * only applies when no callback is supplied.
+ *
+ * Inverse mapping audited 2026-05-24 against the hub registry — every
+ * entry in `RAG_TABLE_CONFIGS` with a `documentType` is represented.
+ */
+export const DEFAULT_DOCUMENT_TYPE_TO_TABLE_ID: Record<string, string> = {
+  // Doc tables
+  markdown:                       'openframe-docs',
+  data_room_doc:                  'data-room-docs',
+
+  // CMS / programs
+  blog_post:                      'blog-posts',
+  product_release:                'product-releases',
+  case_study:                     'case-studies',
+  onboarding_guide:               'onboarding-guides',
+  webinar:                        'webinars',
+  event:                          'events',
+  podcast:                        'podcasts',
+  customer_interview:             'customer-interviews',
+
+  // Financials
+  investor_update:                'investor-updates',
+  financial_kpi:                  'financial-kpis',
+  cap_table:                      'financial-cap-table',
+  profit_loss:                    'financial-pnl',
+  balance_sheet:                  'financial-balance-sheet',
+  cash_flow:                      'financial-cash-flow',
+
+  // ClickUp
+  roadmap_item:                   'clickup-roadmap',
+  delivery_item:                  'clickup-delivery',
+  internal_task:                  'clickup-tasks-internal',
+
+  // GitHub
+  github_commit:                  'github-commits',
+  github_pull_request:            'github-pull-requests',
+  github_pr_review:               'github-pr-reviews',
+  github_commit_public:           'github-commits-public',
+  github_pull_request_public:     'github-pull-requests-public',
+  github_pr_review_public:        'github-pr-reviews-public',
+
+  // HubSpot
+  hubspot_ticket:                 'hubspot-tickets',
+  hubspot_ticket_anon:            'hubspot-tickets-anon',
+  hubspot_ticket_self:            'hubspot-tickets-self',
+
+  // Communications
+  slack_message:                  'slack-messages',
+}
+
+/**
+ * Default `tableIdForDocumentType` resolver used by `useEmbeddedChat` when
+ * the caller didn't pass an explicit callback. Returns `null` for
+ * unrecognized document types so downstream `discussRef` / `displayRef`
+ * still short-circuits gracefully on stale or custom types.
+ */
+export function defaultTableIdForDocumentType(documentType: string): string | null {
+  return DEFAULT_DOCUMENT_TYPE_TO_TABLE_ID[documentType] ?? null
+}