@flamingo-stack/openframe-frontend-core 0.0.212 → 0.0.213-snapshot.20260528174436

package/src/types/.navigation.md

@@ -1,44 +1,52 @@
-<!-- source-hash: a9d24e616587f58e415e36d9160a88ba -->
-A comprehensive type definition file that provides TypeScript interfaces for all navigation-related components in the OpenFrame UI system, including headers, mobile navigation, sidebars, and user configurations.
+<!-- source-hash: 4697d9aedf1aceab0cdd55dfb68dfa62 -->
+Defines shared TypeScript interfaces for all navigation-related components, providing a unified type contract for headers, sidebars, and mobile navigation panels.
 
 ## Key Components
 
-- **`NavigationItem`** - Base interface for navigation items with support for icons, badges, dropdowns, and custom elements
-- **`HeaderConfig`** - Configuration for header components including logo, navigation positioning, and mobile behavior
-- **`MobileNavConfig`** - Configuration for mobile navigation panels with sectioned items and footer support
-- **`SlidingSidebarConfig`** - Configuration for sliding sidebar overlays with position control
-- **`NavigationSidebarConfig`** - Configuration for persistent navigation sidebars with minimization support
-- **`NavigationSidebarItem`** - Specialized navigation item for sidebar components with section grouping
-- **`UnifiedSidebarUser`** - User profile information interface for authenticated navigation states
+| Interface | Purpose |
+|-----------|---------|
+| `NavigationItem` | Base interface for any nav item — supports links, dropdowns, badges, icons, and custom elements |
+| `HeaderConfig` | Full configuration for the top header including logo, nav items, actions, and mobile behavior |
+| `MobileNavConfig` | Configuration for grouped mobile navigation panels with optional footer |
+| `SlidingSidebarConfig` | Configuration for animated slide-in sidebars (left or right) |
+| `NavigationSidebarConfig` | Configuration for collapsible vertical sidebars with minimize support |
+| `NavigationSidebarItem` | Sidebar-specific nav item with section placement (`primary` / `secondary`) |
+| `UnifiedSidebarUser` | User identity shape (name, email, avatar, role) consumed by unified sidebar components |
 
 ## Usage Example
 
 ```typescript
 import { NavigationItem, HeaderConfig } from './navigation'
 
-const navigationItems: NavigationItem[] = [
+const navItems: NavigationItem[] = [
   {
-    id: 'home',
-    label: 'Home',
-    href: '/',
-    icon: <HomeIcon />,
-    isActive: true
+    id: 'dashboard',
+    label: 'Dashboard',
+    href: '/dashboard',
+    type: 'single',
+    isActive: true,
   },
   {
-    id: 'products',
-    label: 'Products',
+    id: 'tools',
+    label: 'Tools',
     type: 'dropdown',
     children: [
-      { id: 'web', label: 'Web Apps', href: '/web' },
-      { id: 'mobile', label: 'Mobile Apps', href: '/mobile' }
-    ]
-  }
+      { id: 'tickets', label: 'Tickets', href: '/tickets' },
+      { id: 'assets', label: 'Assets', href: '/assets' },
+    ],
+  },
 ]
 
 const headerConfig: HeaderConfig = {
-  logo: { element: <Logo />, href: '/' },
-  navigation: { items: navigationItems, position: 'center' },
-  mobile: { enabled: true },
-  backgroundColor: 'bg-ods-card'
+  logo: {
+    element: <FlamingoLogo />,
+    href: '/',
+  },
+  navigation: {
+    items: navItems,
+    position: 'center',
+  },
+  autoHide: true,
+  backgroundColor: 'bg-ods-card',
 }
 ```

package/src/types/.os.types.md

@@ -1,38 +1,43 @@
-<!-- source-hash: c01f816451c4b77f3aba2dc0969faf19 -->
-Centralized operating system type definitions and normalization utilities for the Flamingo platform. Provides a single source of truth for OS information across Fleet MDM, Tactical RMM, and GraphQL integrations.
+<!-- source-hash: 6581d93b3edee981ded786a177e99959 -->
+Defines the centralized source of truth for operating system type metadata across the Flamingo platform, normalizing OS values from Fleet MDM, Tactical RMM, and GraphQL into a unified structure.
 
 ## Key Components
 
-- **`OSTypeValues`** - Constant enum defining the three supported OS types (WINDOWS, MACOS, LINUX)
-- **`OSType`** - TypeScript type derived from OSTypeValues for type safety
-- **`OSTypeDefinition`** - Interface defining OS metadata including label, icon, platform ID, and aliases
-- **`OS_TYPES`** - Array of complete OS definitions with React icons and normalization aliases
-- **`osLabels`** - Simple mapping from OS type to display label
+- **`OSTypeValues`** — Const enum-like object with `WINDOWS`, `MACOS`, and `LINUX` string literals
+- **`OSType`** — Union type derived from `OSTypeValues`
+- **`OSTypeDefinition`** — Interface describing a full OS entry: `id`, `label`, `value`, `icon`, `platformId`, and `aliases`
+- **`OS_TYPES`** — Primary export; array of `OSTypeDefinition` objects for all three platforms, including brand icons and alias lists for fuzzy matching
+- **`osLabels`** — Convenience record mapping each `OSType` to its display label
 
 ## Usage Example
 
 ```typescript
-import { OS_TYPES, OSTypeValues, type OSType } from './os.types'
-
-// Find OS by alias (handles normalization)
-const normalizeOS = (rawOS: string): OSType | null => {
-  const osDefinition = OS_TYPES.find(os => 
-    os.aliases.some(alias => 
-      alias.toLowerCase() === rawOS.toLowerCase()
-    )
+import { OS_TYPES, OSTypeValues, osLabels } from './os.types'
+
+// Resolve an OS from an arbitrary string (e.g. from Fleet MDM)
+function resolveOS(raw: string) {
+  const normalized = raw.toLowerCase()
+  return OS_TYPES.find(os =>
+    os.aliases.includes(normalized)
   )
-  return osDefinition?.id || null
 }
 
-// Use in components
-const DeviceIcon = ({ osType }: { osType: OSType }) => {
-  const osDefinition = OS_TYPES.find(os => os.id === osType)
-  const IconComponent = osDefinition?.icon
-  return IconComponent ? <IconComponent /> : null
-}
+const match = resolveOS('darwin')
+// match.id    → 'MACOS'
+// match.label → 'macOS'
+// match.platformId → 'darwin'
 
-// Type-safe OS checking
-if (device.os === OSTypeValues.MACOS) {
-  // Handle macOS-specific logic
-}
-```
+// Render display label from known type
+const label = osLabels[OSTypeValues.WINDOWS]
+// → 'Windows'
+
+// Render the OS icon in a React component
+const OsIcon = match?.icon
+// <OsIcon className="w-4 h-4" />
+```
+
+## Notes
+
+- Aliases are **order-sensitive** — more specific strings (e.g. `'darwin'`) precede shorter ones (e.g. `'mac'`) to prevent false-positive matches
+- Linux aliases cover major distros (`ubuntu`, `debian`, `centos`, `fedora`, `arch`, etc.)
+- Icons are pulled from the internal `icons-v2-generated` brand logo set

package/src/types/.platform.md

@@ -1,39 +1,42 @@
-<!-- source-hash: a3020519ab0287c823f82ee567c03d4d -->
-TypeScript definitions for unified platform types used across the Flamingo ecosystem, including OpenMSP, TMCG, and various hub configurations.
+<!-- source-hash: a990391bb43e6e44b547ca32debddb41 -->
+Defines unified platform types used across announcements, blog posts, and platform configuration throughout the Flamingo/OpenFrame stack.
 
 ## Key Components
 
-- **PlatformName**: Union type defining all supported platform identifiers including `openmsp`, `tmcg`, `flamingo`, and various hub platforms
-- **PlatformRecord**: Database model interface representing platform entries with metadata like display names, descriptions, and status flags
-- **PlatformConfig**: API configuration interface extending platform records with UI-specific properties like colors and icons
-- **PlatformOption**: Simplified interface for dropdown/filter components requiring only value-label pairs
-- **PlatformStats**: Analytics interface tracking announcement and blog post counts per platform
+| Export | Type | Description |
+|--------|------|-------------|
+| `PlatformName` | `type` | Union of all valid platform identifiers (e.g. `'flamingo'`, `'openframe'`, `'openmsp'`) |
+| `PlatformRecord` | `interface` | Full database model from the `platforms` table, including chat/RAG wiring fields |
+| `PlatformConfig` | `interface` | API-facing configuration shape with display metadata (color, icon, description) |
+| `PlatformOption` | `interface` | Minimal `value`/`label` pair for dropdowns and filter UIs |
+| `PlatformFilter` | `type` | Extends `PlatformName` with an `'all'` wildcard for filter contexts |
+| `LegacyPlatform` | `type` | Backward-compatible alias scoped to the original three platforms |
+| `PlatformStats` | `interface` | Aggregate counts of announcements and blog posts per platform |
 
 ## Usage Example
 
 ```typescript
-import { PlatformName, PlatformRecord, PlatformConfig } from './platform';
+import type { PlatformName, PlatformRecord, PlatformFilter } from './platform';
 
-// Define platform configuration
-const flamingoConfig: PlatformConfig = {
-  id: 'uuid-here',
-  value: 'flamingo',
-  label: 'Flamingo Platform',
+// Type-safe platform reference
+const platform: PlatformName = 'openframe';
+
+// Filter selection (includes 'all' wildcard)
+const filter: PlatformFilter = 'all';
+
+// Working with a database record
+const record: PlatformRecord = {
+  id: 'uuid-123',
   name: 'flamingo',
-  display_name: 'Flamingo Platform',
-  default_color: '#FFC008',
-  default_icon: 'flamingo-icon',
-  description: 'AI-powered MSP platform'
+  display_name: 'Flamingo',
+  is_active: true,
+  is_internal: false,
+  chat_source_id: 'src-abc',
+  chat_source_rag_tables_version: 3,
+  chat_enabled: true,
+  created_at: '2024-01-01T00:00:00Z',
+  updated_at: '2024-01-01T00:00:00Z',
 };
+```
 
-// Filter content by platform
-function filterByPlatform(platform: PlatformName) {
-  // Implementation for filtering announcements/blog posts
-}
-
-// Create dropdown options
-const platformOptions: PlatformOption[] = [
-  { value: 'openmsp', label: 'OpenMSP' },
-  { value: 'flamingo', label: 'Flamingo Platform' }
-];
-```
+> `chat_source_rag_tables_version` is bumped by the `replace_chat_source_rag_tables` RPC and drives cross-Lambda cache invalidation — do not modify this field manually.

package/src/types/.product-release.md

@@ -1,55 +1,82 @@
-<!-- source-hash: bf24b901b66514f0ec5d636b0b37536a -->
-TypeScript definitions for product release management system with comprehensive change tracking and external integrations.
+<!-- source-hash: 5a845a31a46ea7c6d1945d44c5a712fa -->
+Defines the complete TypeScript type system for the Flamingo product release module, including data shapes for releases, changelog entries, media assets, and external integrations (GitHub, ClickUp, Knowledge Base).
 
 ## Key Components
 
-- **ProductRelease**: Main interface defining release structure with changelog categories, metadata, and external links
-- **ChangelogEntry**: Individual changelog item with title and optional description
-- **ReleaseMedia**: Media attachments (images, videos, screenshots, demos) with ordering
-- **External Link Interfaces**: GitHub releases, knowledge base articles, ClickUp tasks for roadmap/delivery tracking
-- **CreateProductReleaseData**: Data transfer object for creating new releases with platform and tag associations
-- **ProductReleaseFilters**: Query parameters for filtering releases by various criteria
-- **Configuration Objects**: Pre-defined options for release types, statuses, and changelog labels
+### Core Interfaces
+
+| Interface | Purpose |
+|-----------|---------|
+| `ProductRelease` | Primary entity — full release record with video, SEO, AI, analytics, and relation fields |
+| `ChangelogEntry` | Single changelog item with optional per-entry `visibility` (supports investor update use case) |
+| `ReleaseMedia` | Attached media assets (`image`, `video`, `screenshot`, `demo`) |
+| `CreateProductReleaseData` | Input shape for creating a new release |
+| `UpdateProductReleaseData` | Partial version of create data for updates |
+| `ProductReleaseFilters` | Query filter bag for list endpoints (pagination, tags, type, status, search) |
+| `ProductReleaseListResponse` | Paginated list response wrapper |
+
+### External Link Interfaces
+
+| Interface | Links To |
+|-----------|---------|
+| `ProductReleaseGitHubLink` | GitHub release URLs |
+| `KnowledgeBaseLink` | Internal KB article paths |
+| `ClickUpRoadmapTask` | ClickUp roadmap task IDs |
+| `ClickUpDeliveryTask` | ClickUp delivery list task IDs |
+| `GitHubRelease` | GitHub API release shape (wizard import) |
+
+### Constants & Utilities
+
+- `releaseTypeOptions` — dropdown metadata for `major`, `minor`, `patch`, `beta`, `alpha`
+- `releaseStatusOptions` — dropdown metadata for `alpha`, `beta`, `stable`, `deprecated`
+- `changelogLabels` — human-readable labels for changelog categories
+- `SEMVER_REGEX` — validates semantic versioning strings including pre-release and build metadata
 
 ## Usage Example
 
 ```typescript
-import { 
-  ProductRelease, 
-  CreateProductReleaseData, 
-  releaseTypeOptions,
-  SEMVER_REGEX 
+import type {
+  ProductRelease,
+  CreateProductReleaseData,
+  ProductReleaseFilters,
+  ChangelogEntry,
 } from './product-release'
+import { releaseTypeOptions, SEMVER_REGEX } from './product-release'
 
-// Create a new product release
+// Validate version before submission
+const version = '2.1.0-beta.1'
+if (!SEMVER_REGEX.test(version)) {
+  throw new Error(`Invalid semver: ${version}`)
+}
+
+// Build a new release payload
 const newRelease: CreateProductReleaseData = {
-  title: "API Gateway v2.1.0",
-  slug: "api-gateway-v2-1-0",
-  version: "2.1.0",
-  summary: "Enhanced authentication and rate limiting",
-  release_type: "minor",
-  release_status: "stable",
-  release_date: "2024-03-15",
+  title: 'OpenFrame 2.1 Beta',
+  slug: 'openframe-2-1-beta',
+  version,
+  release_type: 'beta',
+  release_status: 'beta',
+  release_date: '2025-07-01',
+  status: 'draft',
+  author_id: 'user-uuid',
+  platforms: ['platform-uuid-1'],
+  tags: [1, 4],
   features_added: [
-    { title: "JWT token validation", description: "Improved security" }
-  ],
-  bugs_fixed: [
-    { title: "Memory leak in connection pool" }
-  ],
-  platforms: ["platform-uuid"],
-  tags: [1, 2, 3],
-  status: "published",
-  author_id: "user-123"
+    { title: 'Mingo AI ticket routing', visibility: 'public' },
+    { title: 'Internal billing dashboard', visibility: 'internal' },
+  ] satisfies ChangelogEntry[],
 }
 
-// Validate semantic version
-const isValidVersion = SEMVER_REGEX.test("2.1.0") // true
-
-// Filter releases
+// Filter releases for a public changelog page
 const filters: ProductReleaseFilters = {
-  platform: "web",
-  release_type: ["major", "minor"],
+  release_status: ['stable', 'beta'],
   has_breaking_changes: false,
-  search: "authentication"
+  status: 'published',
+  limit: 20,
+  offset: 0,
 }
+
+// Access dropdown labels for a form
+const typeLabel = releaseTypeOptions.find(o => o.value === 'beta')?.label
+// → 'Beta Release'
 ```

package/src/types/.supabase.md

@@ -1,44 +1,52 @@
-<!-- source-hash: c853fb77c6260c957115dec1c3f34fae -->
-TypeScript type definitions for a Supabase database schema, providing comprehensive type safety for database operations across multiple data models including announcements, Slack integration, and file assets.
+<!-- source-hash: e5e5528221514a1a868f47ffbc324b0c -->
+Auto-generated type definitions for the Flamingo/OpenFrame Supabase database schema, providing fully-typed `Row`, `Insert`, and `Update` interfaces for all public tables along with their foreign key relationships.
 
 ## Key Components
 
-- **`Json`** - Recursive JSON type definition for flexible data structures
-- **`Database`** - Complete database schema with tables for announcements, Slack data, and assets
-- **`Tables<T>`** - Generic utility type for extracting row types from any table
-- **`TablesInsert<T>`** - Generic utility type for insert operations with optional fields
-- **`TablesUpdate<T>`** - Generic utility type for update operations with all optional fields
+### `Json` Type
+A recursive union type representing any valid JSON value — `string`, `number`, `boolean`, `null`, nested objects, or arrays.
 
-### Database Tables
+### `Database` Type
+The root type exported for use with the Supabase client. Contains a `public` schema with the following tables:
 
-- **`announcements`** - Platform announcements with styling and metadata
-- **`announcement_assets`** - File attachments linked to announcements
-- **`slack_channels`** - Slack channel information and metadata
-- **`slack_messages`** - Slack message data with threading support
-- **`slack_users`** - Slack user profiles and permissions
+| Table | Description |
+|---|---|
+| `announcement_assets` | File attachments (images, docs) linked to announcements |
+| `announcements` | Platform announcements with icon, color, and active state |
+| `slack_channels` | Synced Slack workspace channels |
+| `slack_messages` | Slack messages with threading and reply support |
+| `slack_users` | Slack workspace user profiles |
+| `podcast_episodes` | Podbean podcast episodes linked to platforms |
+| `webinars` | Livestorm webinar events linked to platforms |
+
+Each table exposes three operation shapes:
+- **`Row`** — full record shape returned by `SELECT`
+- **`Insert`** — shape for `INSERT` (required fields enforced, optional fields use `?`)
+- **`Update`** — shape for `UPDATE` (all fields optional)
 
 ## Usage Example
 
 ```typescript
-import { Database, Tables, TablesInsert } from './supabase'
 import { createClient } from '@supabase/supabase-js'
+import type { Database } from './supabase'
 
-const supabase = createClient<Database>(url, key)
-
-// Type-safe row access
-type Announcement = Tables<'announcements'>
-type SlackMessage = Tables<'slack_messages'>
+const supabase = createClient<Database>(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_ANON_KEY!
+)
 
-// Type-safe insert operations
-const newAnnouncement: TablesInsert<'announcements'> = {
-  title: 'System Maintenance',
-  description: 'Scheduled downtime tonight',
-  background_color: '#ff6b6b'
-}
+// Fully typed query — row shape inferred automatically
+const { data: episodes } = await supabase
+  .from('podcast_episodes')
+  .select('id, title, audio_url, published_at')
+  .eq('platform_id', 'abc-123')
 
-// Type-safe database operations
-const { data, error } = await supabase
+// Typed insert
+const { error } = await supabase
   .from('announcements')
-  .insert(newAnnouncement)
-  .select()
+  .insert({
+    title: 'New Feature',
+    description: 'Check out what is new!',
+    platform_id: 'abc-123',
+  })
 ```

package/src/types/.team.md

@@ -1,46 +1,54 @@
-<!-- source-hash: bc9c5011cbf51c60413cd0caed57e9e1 -->
-Defines TypeScript interfaces for team member management and organizational structure within an application.
+<!-- source-hash: d36360a6eca29b3fb1beb45b84046f49 -->
+Defines TypeScript interfaces for team roster data structures, supporting organized display of team members grouped by department sections.
 
 ## Key Components
 
-- **`TeamMember`** - Complete interface for individual team member data including personal info, employment details, and profile metadata
-- **`TeamSection`** - Groups team members by department or functional area with title and description
-- **`TeamData`** - Top-level structure containing a founder reference and organized team sections
-- **`GetTeamOptions`** - Configuration interface for team data retrieval with filtering options
+| Interface | Description |
+|-----------|-------------|
+| `TeamMember` | Full profile of an individual employee including personal info, employment details, skills, and social links |
+| `TeamSection` | Groups team members by department with a title and description |
+| `TeamData` | Top-level container holding an optional founder and an array of department sections |
+| `GetTeamOptions` | Query options for filtering team data by active status or department |
 
 ## Usage Example
 
 ```typescript
-// Creating a team member
-const teamMember: TeamMember = {
-  id: "tm_123",
-  employee_id: "EMP001",
-  first_name: "John",
-  last_name: "Doe",
-  email: "john.doe@company.com",
-  role: "Senior Developer",
-  department: "Engineering",
-  employment_status: "active",
+import type { TeamData, TeamMember, GetTeamOptions } from './team';
+
+const options: GetTeamOptions = {
+  includeInactive: false,
+  department: 'Engineering',
+};
+
+const member: TeamMember = {
+  id: 'usr_01',
+  employee_id: 'EMP-001',
+  first_name: 'Jane',
+  last_name: 'Doe',
+  employment_status: 'active',
   is_public: true,
-  is_manager: false,
-  created_at: "2024-01-15T10:00:00Z",
-  updated_at: "2024-01-15T10:00:00Z"
+  is_manager: true,
+  created_at: '2024-01-01T00:00:00Z',
+  updated_at: '2024-06-01T00:00:00Z',
+  skills: ['TypeScript', 'Node.js'],
+  social_links: { linkedin: 'https://linkedin.com/in/janedoe' },
 };
 
-// Organizing team data
 const teamData: TeamData = {
-  founder: teamMember,
-  sections: [{
-    title: "Engineering Team",
-    department: "Engineering",
-    description: "Our technical development team",
-    members: [teamMember]
-  }]
+  founder: member,
+  sections: [
+    {
+      title: 'Engineering',
+      department: 'engineering',
+      description: 'Builds and maintains the platform',
+      members: [member],
+    },
+  ],
 };
+```
 
-// Fetching team with options
-const options: GetTeamOptions = {
-  includeInactive: false,
-  department: "Engineering"
-};
-```
+## Notes
+
+- `full_name` is optional and may be derived from `first_name` + `last_name`
+- `work_email` and `email` are both optional to support personal vs. corporate email separation
+- `social_links` uses a flexible `Record<string, string>` map to accommodate any platform

package/src/types/.video-processing.md

@@ -0,0 +1,54 @@
+<!-- source-hash: d2e79259f53d9d688fe3d007c1eb382a -->
+Shared type definitions for video processing functionality used across multiple entities (CustomerInterview, ProductRelease, and other video-enabled features).
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `VideoTeaser` | Interface | Short video clip for previews; tracks URL, thumbnail, visibility, and origin (`manual` \| `ai_generated`) |
+| `Speaker` | Interface | Speaker identification metadata from transcription |
+| `VideoClip` | Interface | AI-identified video segment with time range, confidence, and optional Twelve Labs ID |
+| `TranscriptWord` | Interface | Word-level transcript entry with millisecond timestamps and speaker attribution |
+| `SpeakerMapping` | Interface | Maps AssemblyAI speaker labels (e.g., `"A"`, `"B"`) to names and roles |
+| `ExcludedRange` | Interface | Time range exclusion (e.g., incentive mentions) in seconds |
+| `VideoProcessingFields` | Interface | Base fields shared across all video-enabled entities (transcript, highlight video, thumbnails, AI confidence scores) |
+| `VideoProcessingEntityType` | Union Type | Supported entity types for agent processing pipelines |
+
+## Usage Example
+
+```typescript
+import type {
+  VideoProcessingFields,
+  SpeakerMapping,
+  VideoTeaser,
+  VideoProcessingEntityType
+} from './video-processing'
+
+const speakerMapping: SpeakerMapping = {
+  A: { name: 'Jane Smith', role: 'interviewer' },
+  B: { name: 'John Doe',  role: 'interviewee', userId: 'usr_123' },
+}
+
+const videoFields: VideoProcessingFields = {
+  main_video_url: 'https://cdn.example.com/interviews/abc.mp4',
+  transcript: 'Full transcript text...',
+  transcript_words_data: [
+    { text: 'Hello', start: 0, end: 450, confidence: 0.98, speaker: 'A' },
+  ],
+  speaker_mapping: speakerMapping,
+  ai_confidence_transcript: 0.95,
+  ai_confidence_summary: 0.88,
+}
+
+const teaser: VideoTeaser = {
+  url: 'https://cdn.example.com/teasers/clip1.mp4',
+  title: 'Key insight on onboarding',
+  published: true,
+  source: 'ai_generated',
+  created_at: new Date().toISOString(),
+}
+
+const entityType: VideoProcessingEntityType = 'customer_interview'
+```
+
+> **Note:** `VideoProcessingFields` is intended as a base — extend it per entity rather than using it directly. `published` on `VideoTeaser` defaults to `false`; an admin must explicitly set it to `true` for public visibility.