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

package/src/components/chat/types/entities/program-types.ts

@@ -0,0 +1,433 @@
+/**
+ * Unified Program System Types
+ *
+ * Base interfaces and types for the Unified Program System that handles
+ * events, podcasts, and webinars through a single set of generic components.
+ *
+ * Design Goals:
+ *   1. Maximum Reuse: Single set of components works for all program types
+ *   2. Type Safety: TypeScript generics ensure correct data shapes
+ *   3. Configuration-Driven: Program types defined via configuration objects
+ *   4. Admin Consistency: Same patterns work for public pages and admin CRUD
+ *
+ * Lifted from `lib/types/program-types.ts` in the hub. The pure transform
+ * helpers (`transformEventToProgram`, `transformPodcastToProgram`,
+ * `transformWebinarToProgram`) also move here — they're pure shape
+ * mappers with no DB / state access.
+ */
+
+import type { ReactNode } from 'react';
+
+// ============================================================================
+// HOST TYPES
+// ============================================================================
+
+/**
+ * Host/Speaker information for programs
+ */
+export interface ProgramHost {
+  id?: string;
+  name: string;
+  email?: string;
+  avatar_url?: string;
+  bio?: string;
+  role?: string; // e.g., "Host", "Speaker", "Guest"
+}
+
+// ============================================================================
+// DATABASE ROW TYPES
+// ============================================================================
+
+/**
+ * Raw database row from luma_events table
+ * Note: Many fields are optional to support partial queries
+ * where not all columns are selected. The hosts field uses
+ * unknown to accommodate JSON parsing from the database.
+ */
+export interface LumaEventRow {
+  id: string;
+  name: string;
+  description?: string | null;
+  cover_url?: string | null;
+  start_at: string;
+  end_at: string;
+  timezone?: string | null;
+  location_name?: string | null;
+  location_full_address?: string | null;
+  geo_latitude?: number | null;
+  geo_longitude?: number | null;
+  meeting_url?: string | null;
+  event_url?: string | null;
+  guest_count?: number | null;
+  visibility?: string | null;
+  hosts?: ProgramHost[] | null;
+  platform_id: string;
+  luma_api_id: string;
+  is_deleted?: boolean;
+}
+
+/**
+ * Raw database row from podcast_episodes table
+ * Note: Many fields are optional to support partial queries
+ * where not all columns are selected.
+ */
+export interface PodcastEpisodeRow {
+  id: string;
+  title: string;
+  description?: string | null;
+  cover_url?: string | null;
+  published_at?: string | null;
+  created_at: string;
+  external_url?: string | null;
+  hosts?: ProgramHost[] | null;
+  platform_id: string;
+  podbean_episode_id: string;
+  podbean_podcast_id: string;
+  audio_url?: string | null;
+  /** Podbean-supplied source video URL (was `video_url` pre-rename). */
+  main_video_url?: string | null;
+  media_type?: 'audio' | 'video' | null;
+  duration_seconds?: number | null;
+  status?: string | null;
+  is_deleted?: boolean;
+  // Override fields (not synced by job)
+  cover_image_override?: string | null;
+  custom_video_url?: string | null;
+}
+
+/**
+ * Raw database row from webinars table
+ * Note: Many fields are optional to support partial queries
+ * where not all columns are selected.
+ */
+export interface WebinarRow {
+  id: string;
+  title: string;
+  description?: string | null;
+  cover_url?: string | null;
+  start_at: string;
+  end_at?: string | null;
+  timezone?: string | null;
+  registration_url?: string | null;
+  hosts?: ProgramHost[] | null;
+  platform_id: string;
+  livestorm_event_id: string;
+  is_deleted?: boolean;
+  /** Livestorm-supplied recording URL (was `recording_url` pre-rename). */
+  main_video_url?: string | null;
+  // Override fields (not synced by job)
+  custom_video_url?: string | null;
+  display_date_override?: string | null;
+  cover_image_override?: string | null;
+}
+
+// ============================================================================
+// BASE PROGRAM ITEM
+// ============================================================================
+
+/**
+ * Base interface that all program items must implement
+ * This enables the generic components to work across events, podcasts, and webinars
+ */
+export interface BaseProgramItem {
+  id: string;
+  title: string; // Maps to: name (events), title (podcasts/webinars)
+  description: string | null;
+  cover_url: string | null; // Primary image
+  date: string; // ISO date string - maps to: start_at, published_at
+  external_url?: string | null; // Registration/play link
+  hosts?: ProgramHost[] | null; // Speakers/hosts
+  platform_id: string;
+}
+
+// ============================================================================
+// PROGRAM-SPECIFIC INTERFACES
+// ============================================================================
+
+/**
+ * Event-specific fields (from luma_events table)
+ */
+export interface EventItem extends BaseProgramItem {
+  luma_api_id: string;
+  end_at: string;
+  timezone?: string | null;
+  location_name?: string | null;
+  location_full_address?: string | null;
+  geo_latitude?: number | null;
+  geo_longitude?: number | null;
+  meeting_url?: string | null;
+  event_url?: string | null;
+  guest_count?: number | null;
+  visibility?: string | null;
+  is_deleted: boolean;
+}
+
+/**
+ * Podcast episode fields (from podcast_episodes table)
+ * Updated for Podbean video podcast support
+ */
+export interface PodcastItem extends BaseProgramItem {
+  author_id?: string | null;
+  podbean_episode_id: string;
+  podbean_podcast_id: string;
+  audio_url?: string | null;
+  /** Podbean-supplied source video URL (was `video_url` pre-rename). */
+  main_video_url?: string | null;
+  media_type: 'audio' | 'video';
+  duration_seconds?: number | null;
+  status: string;
+  published_at: string | null;
+  is_deleted: boolean;
+  podcast_url?: string | null; // Main podcast page URL from Podbean
+  // Override fields (not synced by job)
+  cover_image_override?: string | null;
+  custom_video_url?: string | null;
+  // Video processing fields
+  transcript?: string | null;
+  transcript_words_data?: unknown;
+  srt_content?: string | null;
+  video_summary?: string | null;
+  video_bites?: unknown[];
+  highlight_video_url?: string | null;
+  highlight_video_source?: string | null;
+  highlight_video_thumbnail?: string | null;
+  highlight_video_duration_ms?: number | null;
+  main_video_thumbnail?: string | null;
+  config?: Record<string, unknown>;
+  custom_instructions?: string | null;
+  seo_title?: string | null;
+  seo_description?: string | null;
+  seo_keywords?: string | null;
+  ai_confidence_video_summary?: number | null;
+  ai_confidence_transcript?: number | null;
+}
+
+/**
+ * Webinar fields (from webinars table)
+ */
+export interface WebinarItem extends BaseProgramItem {
+  author_id?: string | null;
+  livestorm_event_id: string;
+  start_at: string;
+  end_at?: string | null;
+  timezone?: string | null;
+  registration_url?: string | null;
+  is_deleted: boolean;
+  /** Livestorm-supplied recording URL (was `recording_url` pre-rename). */
+  main_video_url?: string | null;
+  // Override fields (not synced by job)
+  custom_video_url?: string | null;
+  display_date_override?: string | null;
+  cover_image_override?: string | null;
+  // Video processing fields
+  transcript?: string | null;
+  transcript_words_data?: unknown;
+  srt_content?: string | null;
+  video_summary?: string | null;
+  video_bites?: unknown[];
+  highlight_video_url?: string | null;
+  highlight_video_source?: string | null;
+  highlight_video_thumbnail?: string | null;
+  highlight_video_duration_ms?: number | null;
+  main_video_thumbnail?: string | null;
+  config?: Record<string, unknown>;
+  custom_instructions?: string | null;
+  seo_title?: string | null;
+  seo_description?: string | null;
+  seo_keywords?: string | null;
+  ai_confidence_video_summary?: number | null;
+  ai_confidence_transcript?: number | null;
+}
+
+// ============================================================================
+// PROGRAM CONFIGURATION
+// ============================================================================
+
+/**
+ * Program type identifier
+ */
+export type ProgramType = 'event' | 'podcast' | 'webinar';
+
+/**
+ * Labels configuration for a program type
+ */
+export interface ProgramLabels {
+  singular: string; // "Event", "Episode", "Webinar"
+  plural: string; // "Events", "Episodes", "Webinars"
+  upcoming: string; // "Next Event", "Latest Episode", "Upcoming Webinar"
+  upcomingSection: string; // "Upcoming Events", "Upcoming Episodes", "Upcoming Webinars"
+  archive: string; // "Past Events", "All Episodes", "Past Webinars"
+  empty: string; // "No events yet", "No episodes yet", "No webinars yet"
+}
+
+/**
+ * Configuration object that defines how a program type behaves
+ * This is the core abstraction that enables generic components
+ */
+export interface ProgramConfig<T extends BaseProgramItem = BaseProgramItem> {
+  type: ProgramType;
+  labels: ProgramLabels;
+  dateField: keyof T; // Which field to sort/filter by
+  table: string; // Database table name
+  apiEndpoint: string; // Base API path
+  icon: ReactNode; // Section icon (CalendarDays, Mic, Video)
+  platformIcon?: ReactNode; // External platform icon (optional)
+  externalLinkLabel: string; // "View on Luma", "Listen on Podbean", "Watch on Livestorm"
+  detailRoute: string; // "/events", "/podcasts", "/webinars"
+
+  // Optional customization
+  sortOrder?: 'asc' | 'desc'; // Default sort order for archive
+  showInNav?: boolean; // Whether to show in navigation
+  platformUrl?: string; // Fallback URL to external platform (e.g., Podbean main page)
+  heroCoverAspect?: 'landscape' | 'square'; // Hero cover image aspect ratio (default: 'landscape')
+}
+
+// ============================================================================
+// GENERIC DATA TYPES
+// ============================================================================
+
+/**
+ * Generic response for program list queries
+ */
+export interface ProgramListResponse<T extends BaseProgramItem> {
+  items: T[];
+  count: number;
+  hasMore?: boolean;
+}
+
+/**
+ * Generic response for single program queries
+ */
+export interface ProgramItemResponse<T extends BaseProgramItem> {
+  item: T;
+  media?: ProgramMedia[];
+}
+
+/**
+ * Program media (photos, videos, etc.)
+ */
+export interface ProgramMedia {
+  id: string;
+  program_id: string;
+  media_type: 'image' | 'video' | 'audio';
+  media_url: string;
+  title?: string | null;
+  description?: string | null;
+  display_order: number;
+  created_at: string;
+}
+
+// ============================================================================
+// FILTER AND QUERY TYPES
+// ============================================================================
+
+/**
+ * Filter options for program queries
+ */
+export interface ProgramFilter {
+  filter: 'upcoming' | 'past' | 'all';
+  limit?: number;
+  offset?: number;
+  search?: string;
+}
+
+/**
+ * Admin query options
+ */
+export interface AdminProgramFilter extends ProgramFilter {
+  includeDeleted?: boolean;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+// ============================================================================
+// TRANSFORM UTILITIES
+// ============================================================================
+
+/**
+ * Transform a database event row to EventItem
+ */
+export function transformEventToProgram(event: LumaEventRow): EventItem {
+  return {
+    id: event.id,
+    title: event.name,
+    description: event.description ?? null,
+    cover_url: event.cover_url ?? null,
+    date: event.start_at,
+    external_url: event.event_url ?? null,
+    hosts: event.hosts ?? null,
+    platform_id: event.platform_id,
+    luma_api_id: event.luma_api_id,
+    end_at: event.end_at,
+    timezone: event.timezone ?? null,
+    location_name: event.location_name ?? null,
+    location_full_address: event.location_full_address ?? null,
+    geo_latitude: event.geo_latitude ?? null,
+    geo_longitude: event.geo_longitude ?? null,
+    meeting_url: event.meeting_url ?? null,
+    event_url: event.event_url ?? null,
+    guest_count: event.guest_count ?? null,
+    visibility: event.visibility ?? null,
+    is_deleted: event.is_deleted ?? false,
+  };
+}
+
+/**
+ * Transform a database podcast row to PodcastItem
+ */
+export function transformPodcastToProgram(episode: PodcastEpisodeRow): PodcastItem {
+  return {
+    id: episode.id,
+    title: episode.title,
+    description: episode.description ?? null,
+    // Use cover_image_override if set, otherwise use cover_url
+    cover_url: episode.cover_image_override ?? episode.cover_url ?? null,
+    date: episode.published_at ?? episode.created_at,
+    external_url: episode.external_url ?? null,
+    hosts: episode.hosts ?? null,
+    platform_id: episode.platform_id,
+    podbean_episode_id: episode.podbean_episode_id,
+    podbean_podcast_id: episode.podbean_podcast_id,
+    audio_url: episode.audio_url ?? null,
+    main_video_url: episode.main_video_url ?? null,
+    media_type: episode.media_type ?? 'audio',
+    duration_seconds: episode.duration_seconds ?? null,
+    status: episode.status ?? 'published',
+    published_at: episode.published_at ?? null,
+    is_deleted: episode.is_deleted ?? false,
+    // Override fields
+    cover_image_override: episode.cover_image_override ?? null,
+    custom_video_url: episode.custom_video_url ?? null,
+  };
+}
+
+/**
+ * Transform a database webinar row to WebinarItem
+ * Uses display_date_override for date field when available (for backdating)
+ * Uses cover_image_override for cover_url when available
+ */
+export function transformWebinarToProgram(webinar: WebinarRow): WebinarItem {
+  return {
+    id: webinar.id,
+    title: webinar.title,
+    description: webinar.description ?? null,
+    // Use cover_image_override if set, otherwise use cover_url
+    cover_url: webinar.cover_image_override ?? webinar.cover_url ?? null,
+    // Use display_date_override if set, otherwise use start_at
+    date: webinar.display_date_override ?? webinar.start_at,
+    external_url: webinar.registration_url ?? null,
+    hosts: webinar.hosts ?? null,
+    platform_id: webinar.platform_id,
+    livestorm_event_id: webinar.livestorm_event_id,
+    start_at: webinar.start_at,
+    end_at: webinar.end_at ?? null,
+    timezone: webinar.timezone ?? null,
+    registration_url: webinar.registration_url ?? null,
+    is_deleted: webinar.is_deleted ?? false,
+    main_video_url: webinar.main_video_url ?? null,
+    // Override fields
+    custom_video_url: webinar.custom_video_url ?? null,
+    display_date_override: webinar.display_date_override ?? null,
+    cover_image_override: webinar.cover_image_override ?? null,
+  };
+}

package/src/components/chat/types/entities/roadmap-item.ts

@@ -0,0 +1,42 @@
+/**
+ * Roadmap Item entity — wire shape for the chat roadmap card and the
+ * public `/api/roadmap` reads.
+ *
+ * Lifted from `lib/data/clickup-query-utils.ts` in the hub. Mirrors the
+ * `roadmap_items` projection produced by `transformTask()` in
+ * `clickup-sync-utils.ts`.
+ *
+ * Naming note: a `RoadmapItem` stub already exists in
+ * `src/components/shared/product-release/release-detail-page.tsx` as
+ * `{ id: string; [key: string]: unknown }` — that placeholder predates this
+ * canonical shape and lives in a different module, so the two don't
+ * collide. Callers that want the strongly-typed wire shape import from
+ * `@/components/chat/types/entities/roadmap-item`; the product-release
+ * placeholder will be reconciled in a follow-up.
+ */
+
+export interface RoadmapItem {
+  id: string;
+  title: string;
+  description: string;
+  status: string;
+  statusColor: string;
+  icon: string | null;
+  figmaUrl: string | null;
+  screenshots: string[];
+  targetVersion: string | null;
+  upvotes: number;
+  downvotes: number;
+  quarter: string;
+  clickupUrl: string;
+  /** ClickUp canonical task-type taxonomy ID (1008=Bug, 1009=Request,
+   *  1010=Feature, …). Drives the type-specific icon rendered in the
+   *  chat's compact card for the internal-tasks variant — see
+   *  `getTaskTypeIcon` in `lib/utils/clickup-task-type-utils.ts`. */
+  customItemId: number | null;
+}
+
+export interface RoadmapStaleness {
+  lastSyncedAt: string | null;
+  staleSinceMs: number;
+}

package/src/components/chat/types/entities/slack-message.ts

@@ -0,0 +1,28 @@
+/**
+ * Slack Message entity — wire shape for the chat slack-message card.
+ *
+ * Lifted from `components/shared/slack/slack-message-card.tsx`. The card
+ * consumes this shape; the row shape coming out of the `slack_messages`
+ * RAG table is reduced to this minimal projection at render time.
+ *
+ * Naming note: this is intentionally `SlackMessageItem` (not the broader
+ * `SlackMessage` in `src/types/slack.ts`, which describes the Slack
+ * Community feature's message structure including reactions / threading /
+ * user objects). The chat card needs only the post-RAG projection: id,
+ * title, preview, channel, date, permalink — no reactions / threads.
+ */
+
+export interface SlackMessageItem {
+  /** Slack message ID (ts or url-derived) */
+  id: string;
+  /** Display title — typically "author · channel" or message subject */
+  title: string;
+  /** Message body preview (PII-sanitized server-side) */
+  preview?: string;
+  /** Channel name parsed from URL or stored on the row, when available */
+  channel?: string;
+  /** ISO timestamp or millisecond epoch */
+  dateUpdated?: string | number | null;
+  /** Slack permalink (https://*.slack.com/archives/<channel>/p<ts>) */
+  url?: string | null;
+}

package/src/components/chat/types/index.ts

@@ -4,3 +4,4 @@ export * from './component.types'
 export * from './network.types'
 export * from './processing.types'
 export * from './api.types'
+export * from './entities'

package/src/components/chat/utils/agent-status-message.ts

@@ -0,0 +1,52 @@
+/**
+ * Status color-scheme resolver used by chat-adjacent badges (StatusBadge
+ * components rendering job, ClickUp task, and log-level statuses).
+ *
+ * Lib-side subset of the hub's `lib/utils/agent-status-message.ts`. The
+ * hub file also carries CSS-class resolvers + an `AgentStatusMessage`
+ * builder for the SSE-status surface; those live hub-side because they
+ * reference hub-only ODS class names. This function returns the abstract
+ * color scheme name only — the consuming `StatusBadge` (in this lib)
+ * maps it to concrete colors.
+ */
+
+export type ColorScheme = 'success' | 'error' | 'warning' | 'cyan' | 'default'
+
+/**
+ * Map a status to a color scheme name for StatusBadge components.
+ * Supports job/processing statuses, ClickUp task statuses, and log levels.
+ */
+export function getStatusColorScheme(status: string): ColorScheme {
+  const s = status?.toLowerCase() || ''
+
+  // Exact matches first (most common)
+  switch (status) {
+    case 'completed':
+    case 'success':
+    case 'active':          // review cycles, feature flags, etc.
+      return 'success'
+    case 'failed':
+    case 'failure':
+    case 'cancelled':
+    case 'error':
+      return 'error'
+    case 'running':
+    case 'processing':
+    case 'closed':          // review cycles past their active window
+      return 'cyan'
+    case 'pending':
+    case 'warning':
+      return 'warning'
+    case 'draft':           // review cycles not yet opened to reviewers
+    case 'info':
+      return 'default'
+  }
+
+  // Partial matches for ClickUp-style statuses (Complete, Done, Working, etc.)
+  if (s.includes('complete') || s.includes('done')) return 'success'
+  if (s.includes('review')) return 'cyan'
+  if (s.includes('working') || s.includes('progress')) return 'warning'
+  if (s.includes('blocked') || s.includes('failed')) return 'error'
+
+  return 'default'
+}

package/src/components/chat/utils/auto-continuation-directive.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared cross-process contract for the post-approval auto-continuation
+ * directive. The client emits a hidden synthetic user message starting
+ * with `AUTO_CONTINUATION_DIRECTIVE_PREFIX`; the server's `decideRoute`
+ * matches that exact prefix on the RAW user query (pre-rewriter) and
+ * hard-disables tools for the directive turn, forcing the LLM to
+ * respond with prose follow-up questions instead of duplicating the
+ * just-approved tool call.
+ *
+ * Single source of truth — both server-side `decideRoute` AND
+ * client-side `autoContinueRef` import from here. Drifting the literal
+ * on either side would silently break the duplicate-ticket guard
+ * (server would route normally with tools wired; LLM would propose the
+ * same tool again).
+ *
+ * `toolName` is typed as `string` (not a const-union) so the lib stays
+ * generic across hub deployments — host code that has a sharper
+ * `KnownWriteToolName` type can pass that through; this builder only
+ * cares about a handful of string-equal branches.
+ */
+
+export const AUTO_CONTINUATION_DIRECTIVE_PREFIX = '[internal-auto-continuation]'
+
+export interface BuildAutoContinuationOptions {
+  ticketId?: string
+  /** Reading of `args.status` on the just-approved tool call. Used to
+   *  branch the directive between "post-create diagnostic Qs",
+   *  "post-close resolution ask", and "post-update acknowledgement". */
+  status?: string
+}
+
+/**
+ * Build the directive text the client sends as a HIDDEN user message
+ * after every successful Approve. The LLM treats it as the user
+ * speaking; the chat shell filters it out at render time.
+ *
+ * Branch logic mirrors `TICKET_TOOL_PROTOCOL` §1a/§1b — keep them in
+ * sync: the directive tells the model WHICH section to follow.
+ */
+export function buildAutoContinuationDirective(
+  toolName: string,
+  opts: BuildAutoContinuationOptions = {},
+): string {
+  const ticketRef = opts.ticketId ? ` (ticket #${opts.ticketId})` : ''
+  const ticketHash = opts.ticketId ? ` #${opts.ticketId}` : ''
+  const isClose = toolName === 'update_ticket' && opts.status?.toUpperCase() === 'CLOSED'
+  if (toolName === 'create_ticket') {
+    return (
+      `${AUTO_CONTINUATION_DIRECTIVE_PREFIX} The user just approved create_ticket${ticketRef}. ` +
+      `Per ticket-protocol §1a, ask 2-4 SHORT, issue-specific diagnostic follow-up questions ` +
+      `tailored to the symptom they reported in their original message. When they answer, ` +
+      `propose an update_ticket with content_addendum carrying a clean Q&A digest. ` +
+      `Do NOT call any tool in this turn — just write the questions as prose.`
+    )
+  }
+  if (isClose) {
+    return (
+      `${AUTO_CONTINUATION_DIRECTIVE_PREFIX} The user just approved closing ticket${ticketHash}. ` +
+      `Per ticket-protocol §1b, ask ONE short question: "How was this resolved? I'll add it ` +
+      `to the ticket as a closing note." Phrase kindly even if the user was curt. When they ` +
+      `answer, propose an update_ticket with content_addendum="[Resolution] <their words>". ` +
+      `Do NOT call any tool in this turn — just write the prose ask.`
+    )
+  }
+  return (
+    `${AUTO_CONTINUATION_DIRECTIVE_PREFIX} The user just approved update_ticket${ticketHash}. ` +
+    `Acknowledge the change in ONE short sentence; if anything else looks like it needs ` +
+    `attention, ask. Do NOT call any tool in this turn.`
+  )
+}