@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/types/.case-study.md

@@ -1,16 +1,25 @@
-<!-- source-hash: 347abba356d14a3c4bf7cf70892add4e -->
-Defines TypeScript interfaces and types for the Case Study content entity within the Flamingo/OpenMSP platform, following the same structural pattern as `blog.ts`.
+<!-- source-hash: 214619bf625ae18d6ede7c3a67ec6b5b -->
+Defines TypeScript interfaces for case study content entities in the OpenFrame platform, covering the full lifecycle from creation to publishing with video processing, SEO, and relational data support.
 
 ## Key Components
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `CaseStudy` | `interface` | Full case study record with all fields, relations, and metadata |
+| `CaseStudy` | `interface` | Full case study record with all fields, relations, and video pipeline data |
 | `CreateCaseStudyData` | `interface` | Payload shape for creating a new case study |
-| `UpdateCaseStudyData` | `type` | Partial version of `CreateCaseStudyData` for updates |
+| `UpdateCaseStudyData` | `type` | Partial version of `CreateCaseStudyData` for PATCH operations |
 | `CaseStudyFilters` | `interface` | Query filter options for listing/searching case studies |
 | `CaseStudyListResponse` | `interface` | Paginated response wrapper for case study arrays |
 
+## Field Groups (CaseStudy)
+
+- **Story structure** — `challenge`, `solution`, `results`
+- **Video** — `testimonial_video_url` (YouTube preferred), `main_video_url` (uploaded fallback), `video_bites`, `main_video_thumbnail`
+- **Video processing pipeline** — `transcript`, `srt_content`, `video_summary`, `highlight_video_url`, `config` (full parity with `customer_interviews`)
+- **SEO** — `seo_title`, `seo_description`, `seo_keywords`, `og_image_url`
+- **Publishing** — `status` (`draft` | `ai_drafted` | `published` | `scheduled` | `archived`), `published_at`
+- **Relations** — `msp`, `user`, `platforms`, `tags`, `customer_interview`
+
 ## Usage Example
 
 ```typescript
@@ -23,33 +32,38 @@ import type {
 
 // Create a new case study
 const payload: CreateCaseStudyData = {
-  title: 'How Acme IT Reduced Ticket Volume by 40%',
-  slug: 'acme-it-ticket-reduction',
+  title: 'How Acme MSP Cut Ticket Resolution by 40%',
+  slug: 'acme-msp-ticket-resolution',
   status: 'draft',
   author_id: 'uuid-author',
   platforms: ['uuid-platform-1'],
-  tags: [1, 2],
+  tags: [12, 34],
   challenge: 'High volume of repetitive L1 tickets...',
-  solution: 'Deployed Mingo AI with automated triage...',
-  results: '40% reduction in ticket volume in 30 days.',
-  testimonial_video_url: 'https://www.youtube.com/watch?v=EXAMPLE',
+  solution: 'Deployed Mingo AI triage automation...',
+  results: '40% reduction in mean time to resolve...',
+  testimonial_video_url: 'https://www.youtube.com/watch?v=example',
 }
 
-// Filter published case studies by industry
+// Filter for published case studies by industry
 const filters: CaseStudyFilters = {
-  industry: 'healthcare',
   status: 'published',
+  industry: 'healthcare',
   limit: 10,
   offset: 0,
 }
 
-// Typed paginated response
+// Typed response
 const response: CaseStudyListResponse = await fetchCaseStudies(filters)
-console.log(response.count, response.data)
+response.data.forEach((cs: CaseStudy) => console.log(cs.title))
 ```
 
 ## Notes
 
-- **Video fields**: `testimonial_video_url` (YouTube, preferred) and `main_video_url` (uploaded fallback) follow the same `ENTITY_FIELD_CONFIG` convention used across `customer_interviews`, `webinars`, `podcasts`, and `investor_updates`.
-- **MSP relation**: Company, industry, and testimonial data are resolved indirectly via `user.msp_id`, not stored directly on the case study.
-- `video_source_type` is deprecated — consumers should detect source from URL presence instead.
+- `video_source_type` is **deprecated**; prefer URL-based detection via `testimonial_video_url` vs `main_video_url`
+- `transcript_words_data` is intentionally omitted — server-only field
+- `main_video_thumbnail` is optional for backward compatibility with existing consumers
+- MSP company/industry/testimonial data is accessed through the `msp` relation, resolved via `user.msp_id`
+
+## Source
+
+[`case-study.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/case-study.ts)

package/src/types/.content-ref.md

@@ -0,0 +1,37 @@
+<!-- source-hash: 134dd81f40b3ecbbabb4fde92ba7a6a4 -->
+Defines the canonical `ContentRef` interface — the unified shape for link/embed metadata stored in JSONB columns across investor updates, performance baselines, and other entities that surface "related content" rails. This is the single package-wide definition; all other paths (including chat components) re-export from here.
+
+## Key Components
+
+- **`ContentRef`** — Core interface describing a linked or embedded content item, including identity fields (`type`, `id`, `slug`, `url`), display metadata (`title`, `summary`, `image_url`, `image_bg_color`), visibility scope (`'public' | 'internal'`), and optional `targetPlatform`.
+- **`ContentRefWithReason`** — Extension of `ContentRef` that appends a `reason: string` field, representing the placement rationale returned by the suggestion service (`/api/related-content`). Used for data transport only; never rendered by the rail.
+
+## Usage Example
+
+```typescript
+import type { ContentRef, ContentRefWithReason } from '@openframe-oss-lib/content-ref';
+
+// Persisting a content reference in a JSONB column
+const ref: ContentRef = {
+  type: 'article',
+  id: 'abc-123',
+  slug: 'q1-performance-review',
+  url: 'https://example.com/q1-performance-review',
+  title: 'Q1 Performance Review',
+  summary: 'A breakdown of Q1 metrics.',
+  visibility: 'internal',
+  display_order: 1,
+};
+
+// Consuming a suggestion-service response
+const suggested: ContentRefWithReason = {
+  ...ref,
+  reason: 'top_performer',
+};
+```
+
+## Notes
+
+- `ContentRef` is safe for server-side use; it carries no rendering dependencies.
+- `reason` on `ContentRefWithReason` is typed as `string` (not a narrow union) intentionally — the narrow vocabulary is hub-server only.
+- Source: [`content-ref.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/content-ref.ts)

package/src/types/.customer-interview.md

@@ -1,17 +1,26 @@
-<!-- source-hash: 110781f95cc87ef6269255e1ff54d089 -->
-Brief description: Defines TypeScript types and interfaces for the Customer Interview content module, covering the full lifecycle from creation and AI processing to publishing and analytics within the Flamingo/OpenFrame platform.
+<!-- source-hash: 95f69519f0878413e2b796e8c36607d2 -->
+Customer interview domain types defining the full data model for video-based customer testimonial interviews, including AI processing pipelines, video content management, and publishing workflows.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `CustomerInterview` | Interface | Core entity representing a recorded customer interview with all fields including video, AI processing state, SEO, and relations |
-| `CustomerInterviewConfig` | Interface | Per-interview configuration options (highlight video duration, subtitle burning) |
-| `CreateCustomerInterviewData` | Interface | Input shape for creating a new interview record |
-| `UpdateCustomerInterviewData` | Type alias | Partial version of `CreateCustomerInterviewData` for patch updates |
-| `CustomerInterviewFilters` | Interface | Query filter options for listing interviews (platform, industry, search, pagination) |
-| `CustomerInterviewListResponse` | Interface | Paginated response wrapper for interview list queries |
-| Re-exports | Types | `VideoTeaser`, `Speaker`, `VideoClip`, `TranscriptWord`, `SpeakerMapping`, `ExcludedRange` from `./video-processing` for backwards compatibility |
+### Interfaces
+
+- **`CustomerInterview`** — Core entity with fields for video content, AI processing status/results, SEO metadata, speaker identification, and relational joins to users, MSPs, platforms, and case studies
+- **`CustomerInterviewConfig`** — Per-interview configuration for AI highlight video generation (target duration, subtitle burning)
+- **`CreateCustomerInterviewData`** — Input shape for creating new interviews; requires `title`, `slug`, `status`, `author_id`, and `platforms`
+- **`UpdateCustomerInterviewData`** — Partial of `CreateCustomerInterviewData` for patch operations
+- **`CustomerInterviewFilters`** — Query filter parameters including platform, industry, company size, search, status, and pagination
+- **`CustomerInterviewListResponse`** — Paginated list wrapper with `data` array and `count`
+
+### Re-exports
+
+Re-exports `VideoTeaser`, `Speaker`, `VideoClip`, `TranscriptWord`, `SpeakerMapping`, and `ExcludedRange` from `./video-processing` for backwards compatibility.
+
+### Status Enums
+
+- **Publishing:** `'draft' | 'completed'`
+- **AI pipeline stages** (`ai_transcript_status`, `ai_summary_status`, `ai_clips_status`): `'pending' | 'processing' | 'completed' | 'failed'`
+- **Highlight video source:** `'manual' | 'ai_generated'`
 
 ## Usage Example
 
@@ -20,43 +29,31 @@ import type {
   CustomerInterview,
   CreateCustomerInterviewData,
   CustomerInterviewFilters,
-  CustomerInterviewListResponse
 } from './customer-interview'
 
-// Creating a new interview
+// Create a new interview record
 const payload: CreateCustomerInterviewData = {
-  title: 'How Acme IT Scaled Support with Flamingo',
-  slug: 'acme-it-flamingo-interview',
+  title: 'How Acme IT Reduced Ticket Volume by 40%',
+  slug: 'acme-it-ticket-reduction',
   status: 'draft',
-  author_id: 'user-uuid-123',
-  platforms: ['platform-uuid-abc'],
-  user_id: 'customer-uuid-456',
+  author_id: 'usr_abc123',
+  platforms: ['plt_uuid_1', 'plt_uuid_2'],
   main_video_url: 'https://cdn.example.com/interviews/acme.mp4',
   config: {
     highlight_target_duration_seconds: 120,
-    skipSubtitleBurning: false
+    skipSubtitleBurning: false,
   },
-  custom_instructions: 'Focus on ROI and ticket volume reduction metrics.'
 }
 
-// Filtering interviews for a listing page
+// Filter published interviews by platform
 const filters: CustomerInterviewFilters = {
-  platform: 'all',
+  platform: 'plt_uuid_1',
   status: 'completed',
-  search: 'managed services',
-  limit: 12,
-  offset: 0
+  limit: 10,
+  offset: 0,
 }
 
-// Consuming a list response
-async function fetchInterviews(
-  filters: CustomerInterviewFilters
-): Promise<CustomerInterviewListResponse> {
-  const response = await api.get('/interviews', { params: filters })
-  return response.data
-}
-
-// Checking AI processing state
+// Access AI pipeline status on a fetched record
 function isReadyToPublish(interview: CustomerInterview): boolean {
   return (
     interview.ai_transcript_status === 'completed' &&
@@ -68,7 +65,10 @@ function isReadyToPublish(interview: CustomerInterview): boolean {
 
 ## Notes
 
-- AI processing fields (`ai_transcript_status`, `ai_summary_status`, `ai_clips_status`) follow a `pending → processing → completed | failed` lifecycle driven by **AssemblyAI** (transcription) and **TwelveLabs** (video understanding).
-- `speaker_mapping` maps AssemblyAI speaker labels (e.g. `"A"`, `"B"`) to real `UserProfile` identities resolved during transcription.
-- `incentive_excluded_ranges` stores timestamp ranges where promotional/incentive language was detected and should be excluded from highlight clip generation.
-- Relations (`user`, `msp`, `author`, `case_study`, `platforms`) are populated only when explicitly joined — treat them as optional at the call site.
+- External transcript/video APIs are tracked via `assemblyai_transcript_id` and `twelvelabs_video_id`
+- `incentive_excluded_ranges` and `speaker_mapping` are computed during transcription and stored as JSONB
+- `custom_instructions` steers AI prompts for both case study generation and video processing
+
+---
+
+**Source:** [`customer-interview.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/customer-interview.ts)

package/src/types/.doc-source.md

@@ -0,0 +1,87 @@
+<!-- source-hash: 37a4c2cdf765511c217fb40ef3c7ec1e -->
+Canonical type definitions for the doc-source system, providing a unified tree structure, content payload, and data-access contract for all doc-viewer consumers (knowledge base, data room, and future sources).
+
+## Key Components
+
+| Export | Kind | Description |
+|---|---|---|
+| `DocNode` | `interface` | Single node in a doc-source tree; discriminates folders vs. files and supports rich content types via `documentType` |
+| `DocumentType` | `type` | Non-nullable alias for `DocNode['documentType']`; use as renderer-map key |
+| `DocContent` | `interface` | Content payload from a DAL's `getContent` call; covers both markdown and rich-content (PDF, Google Sheet, Figma) fields |
+| `DocSourceDal<Client>` | `interface` | Generic DAL contract each doc source must satisfy; `Client` defaults to `unknown` to avoid pulling in `@supabase/supabase-js` |
+| `DocSourceId` | `type` | Registry discriminator union (`'openframe-docs' \| 'data-room-docs'`); type-narrowing handle only — no runtime registry |
+| `ResolveLinkResult` | `interface` | Discriminator-style result from the resolve-link endpoint; drives navigate / expand-folder / broken-link behaviour |
+| `DocRenderHandlers` | `interface` | Callbacks and context passed into a consumer's `renderContent`; includes optional async link resolver |
+
+## Usage Example
+
+```typescript
+import type {
+  DocNode,
+  DocContent,
+  DocSourceDal,
+  DocSourceId,
+  DocRenderHandlers,
+  DocumentType,
+} from '@openframe-oss-lib/doc-source'
+
+// Implement a DAL for a new doc source
+class MyDocsDal implements DocSourceDal<SupabaseClient> {
+  async getStructure(client: SupabaseClient): Promise<DocNode[]> {
+    // Return the full nav tree
+    return [
+      {
+        id: 'intro',
+        name: 'Introduction',
+        slug: 'introduction',
+        path: 'docs/introduction',
+        type: 'file',
+        documentType: 'markdown',
+      },
+    ]
+  }
+
+  async getContent(
+    client: SupabaseClient,
+    path: string,
+  ): Promise<DocContent | null> {
+    return {
+      content: '# Hello world',
+      sections: [{ id: 'hello-world', title: 'Hello world', level: 1 }],
+      path,
+      documentType: 'markdown',
+    }
+  }
+}
+
+// Build a renderer map keyed by DocumentType
+const renderers: Record<DocumentType, React.FC<{ content: DocContent }>> = {
+  markdown: MarkdownRenderer,
+  pdf: PdfRenderer,
+  google_sheet: SheetRenderer,
+  figma: FigmaRenderer,
+  file: FileRenderer,
+}
+
+// Wire render handlers from DocViewer into a page shell
+const handlers: DocRenderHandlers = {
+  currentPath: 'docs/introduction',
+  sourceId: 'openframe-docs' satisfies DocSourceId,
+  onInternalLinkClick: (path, opts) => router.push(path),
+  onResolveLink: async (href, currentPath) => {
+    const res = await fetch('/api/docs/resolve-link', {
+      method: 'POST',
+      body: JSON.stringify({ href, currentPath, sourceId: 'openframe-docs' }),
+    })
+    return res.json()
+  },
+}
+```
+
+## Notes
+
+- `documentType` is optional on both `DocNode` and `DocContent`; `undefined` is treated as `'markdown'` by all consumers.
+- `DocSourceDal<Client>` is intentionally generic — hub callers tighten `Client` to `SupabaseClient`; the lib itself never imports Supabase.
+- Adding a new source requires both adding its id to `DocSourceId` **and** registering it in the hub's `DOC_SOURCES` registry.
+
+**Source:** [`doc-source.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/doc-source.ts)

package/src/types/.entity-author.md

@@ -0,0 +1,53 @@
+<!-- source-hash: 18b303f8d0b4bb28e8b6346d79dc5665 -->
+Shared TypeScript interfaces defining the author data shapes used across content surfaces — detail pages, bylines, metadata grids, and author profile pages.
+
+## Key Components
+
+### `EntityAuthor`
+The universal author shape attached to content entities (product releases, onboarding guides, etc.) by the hub's `hydrateAuthor`. Powers metadata-grid author cells, bylines, and `/authors/[slug]` links.
+
+| Field | Notes |
+|---|---|
+| `full_name` | Display name, nullable |
+| `avatar_url` | Profile image, nullable |
+| `about` | Bio paragraph fed to `<ArticleAuthorByline bio>` |
+| `slug` | Present only when `is_real` profile gate passes |
+| `email` | Server/admin payloads only — stripped by public DALs |
+
+### `AuthorSocialLink`
+A single curated social link from the `profile_social_links` junction, ordered by `display_order`. The `platform` key (e.g. `'linkedin'`, `'x'`) feeds directly into `SocialIconRow`.
+
+### `AuthorProfile`
+Public author-page view model rendered by `<AuthorDetailView>`. Uses camelCase fields (contrast with `EntityAuthor`'s snake_case). The hub's `PublicAuthor` extends this with server-side extras like `updatedAt`.
+
+## Usage Example
+
+```typescript
+import type { EntityAuthor, AuthorProfile, AuthorSocialLink } from './entity-author'
+
+// Attach to a content entity (hub hydrateAuthor output)
+const author: EntityAuthor = {
+  id: 'usr_123',
+  full_name: 'Jane Smith',
+  avatar_url: 'https://cdn.example.com/avatars/jane.webp',
+  about: 'Infrastructure engineer focused on MSP automation.',
+  slug: 'jane-smith',
+}
+
+// Construct a public author-page view model
+const profile: AuthorProfile = {
+  id: 'usr_123',
+  slug: 'jane-smith',
+  fullName: 'Jane Smith',
+  avatarUrl: author.avatar_url,
+  about: author.about ?? null,
+  jobTitle: 'Infrastructure Engineer',
+  company: 'Flamingo',
+  knowsAbout: ['MSP', 'AI Automation'],
+  socialLinks: [
+    { platform: 'linkedin', url: 'https://linkedin.com/in/janesmith', username: 'janesmith' },
+  ],
+}
+```
+
+> **Note:** `EntityAuthor` uses snake_case (database-aligned); `AuthorProfile` uses camelCase (view-model aligned). Keep this distinction in mind when mapping between DAL output and UI components.

package/src/types/.entity-platform.md

@@ -0,0 +1,40 @@
+<!-- source-hash: d81e612913b63836481c6fd2b114b7ae -->
+Defines the shared `EntityPlatformAssoc` interface representing a hydrated `entity_platforms` junction row, used by all per-entity platform association types to ensure a consistent shape across the codebase.
+
+## Key Components
+
+### `EntityPlatformAssoc`
+A single interface describing the shape that `attachPlatformsToRows` places on every `<entity>_platforms[]` array (e.g. `case_study_platforms`, `blog_post_platforms`, `customer_interview_platforms`).
+
+| Field | Type | Description |
+|---|---|---|
+| `platform_id` | `string` | Required platform identifier |
+| `is_featured` | `boolean` | Whether the platform is featured |
+| `featured_order` | `number \| null` | Optional ordering for featured platforms |
+| `name` | `string` | Platform name, spread from the platform record; used by `composeContentUrlFromPlatforms` |
+| `display_name` | `string` | Optional display-friendly name |
+| `platform_name` | `string` | Alias added by some admin fetches (e.g. `getCaseStudyForAdmin`) |
+| `id` | `string` | Optional platform record ID |
+| `created_at` | `string` | Optional creation timestamp |
+
+## Usage Example
+
+```typescript
+import type { EntityPlatformAssoc } from './entity-platform'
+
+// Typed per-entity association reusing the shared interface
+type CaseStudyPlatform = EntityPlatformAssoc
+
+function getFeaturedPlatforms(platforms: EntityPlatformAssoc[]): EntityPlatformAssoc[] {
+  return platforms
+    .filter(p => p.is_featured)
+    .sort((a, b) => (a.featured_order ?? 0) - (b.featured_order ?? 0))
+}
+```
+
+## Notes
+
+- All per-entity platform types reference this single interface, preventing shape drift across entity types.
+- Fields spread from the platform record (via `PLATFORM_EMBED`) allow URL composition without casting.
+
+**Source:** [`entity-platform.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/entity-platform.ts)

package/src/types/.index.md

@@ -1,41 +1,47 @@
-<!-- source-hash: 2dec9acc6154e0160c391613c83b192e -->
-Centralized barrel export file for all type definitions in the `@flamingo/ui-kit` package, providing a single import entry point for platform, application, and domain types.
+<!-- source-hash: 803ae4425b112973a12ba40c193e0cdc -->
+Centralized barrel export file for the `@flamingo/ui-kit` package, re-exporting all platform, application, and domain types from a single entry point.
 
 ## Key Components
 
-| Export Group | Modules |
+| Export Group | Source Modules |
 |---|---|
-| **Core Platform** | `announcement`, `categories`, `category`, `media`, `platform` |
+| **Core Platform** | `announcement`, `doc-source`, `categories`, `category`, `media`, `platform` |
 | **Database & API** | `supabase` |
 | **Authentication** | `auth` |
-| **Content** | `blog`, `case-study`, `customer-interview`, `luma`, `product-release`, `delivery`, `vendor`, `video-processing` |
+| **Content** | `blog`, `entity-author`, `case-study`, `customer-interview`, `luma`, `product-release`, `delivery`, `vendor`, `video-processing` |
 | **User & Profile** | `employee`, `profile`, `team`, `user` |
 | **Communication** | `slack`, `waitlist` |
-| **Business Logic** | `faq`, `report`, `stack` |
+| **Business Logic** | `faq`, `content-ref`, `report`, `stack` |
 | **Navigation** | `navigation` |
-| **Tools & Shell** | `tool.types`, `shell.types`, `os.types` |
+| **Shell / OS / Tools** | `shell.types`, `os.types`, `tool.types` |
 | **Marketing & Access** | `marketing`, `access-code-cohorts`, `icons`, `permissions`, `tmcg` |
 
-> **Note:** `platform` uses named re-exports (`export type { ... }`) to avoid conflicts with internal types, exposing only `LegacyPlatform`, `PlatformFilter`, `PlatformName`, `PlatformOption`, `PlatformRecord`, `PlatformSettings`, and `PlatformStats`.
+> **Note:** `categories` and `platform` use named-only exports (`export type { ... }`) to avoid conflicts with overlapping identifiers from sibling modules.
 
 ## Usage Example
 
 ```typescript
-// Import any type directly from the package root
+// Import any type directly from the package root — no deep imports needed
 import type {
   PlatformSettings,
+  PlatformName,
   Category,
-  BlogPost,
-  UserProfile,
-  NavigationItem,
+  DocNode,
+  DocContent,
 } from '@flamingo/ui-kit'
 
-// No need to reach into individual type files
-const config: PlatformSettings = { /* ... */ }
-const nav: NavigationItem[] = []
+const config: PlatformSettings = {
+  name: 'openframe' as PlatformName,
+  // ...
+}
 ```
 
 ## Notes
 
-- Prefer importing from `@flamingo/ui-kit` directly rather than deep-importing individual type modules (e.g., `@flamingo/ui-kit/types/platform`).
-- `categories` also uses named exports to selectively expose `Category`, `CategoryCardProps`, and `RealCategoryCardProps`.
+- **Single import surface:** consumers never need to reach into sub-paths like `@flamingo/ui-kit/platform`.
+- **`doc-source` types** (`DocNode`, `DocContent`, `DocSourceDal`, `DocRenderHandlers`) are shared across knowledge-base, data-room, and future doc-source viewers.
+- **Selective re-exports** on `categories` and `platform` prevent name collisions while still exposing the most-used public types.
+
+## Source
+
+[`index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts)

package/src/types/.marketing.md

@@ -1,39 +1,32 @@
-<!-- source-hash: f0baaf40642c975086a4698fa70728a9 -->
-Brief description: Defines all TypeScript interfaces, types, and enums for the Flamingo Marketing AI system, covering campaigns, AI-generated content, media assets, social accounts, scheduled posts, approvals, and usage tracking.
+<!-- source-hash: 772ae04d34add00764dbf442ea4f82dc -->
+Defines the complete TypeScript type system for the Marketing AI module, covering campaigns, AI-generated content and media, social accounts, scheduled posts, approvals, and usage tracking.
 
 ## Key Components
 
 ### Campaign Types
 - **`MarketingCampaign`** — Core campaign entity with content seed fields (`content_source_type`, `content_source_id`, `custom_instructions`)
-- **`CreateCampaignInput`** / **`UpdateCampaignInput`** — Input shapes for campaign mutations
+- **`CreateCampaignInput`** / **`UpdateCampaignInput`** — Mutation payloads for campaign management
+- **`CampaignWithDetails`** — Aggregate type combining campaign, content, and media
+- **`CampaignStats`** — Counters for draft, active, and completed campaigns
 
-### Content Types
-- **`ContentType`** — `'blog_post' | 'social_post' | 'ad_copy' | 'email'`
-- **`ContentStatus`** — Lifecycle states from `'draft'` through `'published'`
-- **`AIContent`** — Generated text content with publishing, override, and URL injection fields
-- **`CreateAIContentInput`** — Input for creating AI-generated content records
-
-### Media Types
-- **`MediaType`** — `'image' | 'video' | 'figma_export'`
-- **`MediaProvider`** — Supported AI providers: `dalle`, `flux-pro`, `kling-v2.5`, `luma-ray2`, and more
-- **`AIMedia`** — Media asset entity including storage paths, dimensions, Figma integration, and publish overrides
+### AI Content & Media Types
+- **`AIContent`** — Generated text assets (`blog_post`, `social_post`, `ad_copy`, `email`) with approval workflow and URL injection fields
+- **`AIMedia`** — Generated image/video assets with provider tracking (`dalle-3`, `flux-pro`, `kling-v2.5`, etc.) and Figma export support
 - **`MediaDimensions`** — Width, height, and aspect ratio descriptor
+- **`ContentStatus`** / **`MediaStatus`** — Lifecycle enums from `draft` through `published`
 
 ### Social & Scheduling Types
-- **`SocialChannel`** — `'slack' | 'linkedin' | 'facebook' | 'instagram' | 'twitter' | 'youtube'`
-- **`SocialAccount`** / **`CreateSocialAccountInput`** — OAuth account records with encrypted tokens
-- **`ScheduledPost`** / **`CreateScheduledPostInput`** — Post scheduling with retry tracking
+- **`SocialAccount`** — OAuth-connected social channel (`slack`, `linkedin`, `facebook`, `instagram`, `twitter`, `youtube`)
+- **`ScheduledPost`** — Post scheduling with retry tracking and external post URL reference
+- **`SocialChannel`** / **`SocialAccountType`** — Channel and account classification enums
 
-### Approval & Usage Types
-- **`ContentApproval`** — Approval workflow for content, media, and campaigns
-- **`AIUsage`** / **`TrackAIUsageInput`** — Cost and token tracking per AI service and operation
-- **`AIService`** — `'anthropic' | 'openai' | 'replicate' | 'figma' | 'google'`
+### Approval & Usage Tracking
+- **`ContentApproval`** — Review workflow for content and media items
+- **`AIUsage`** / **`TrackAIUsageInput`** — Token and cost tracking per service (`anthropic`, `openai`, `replicate`, `figma`, `google`)
+- **`AIUsageSummary`** — Aggregated cost and token totals broken down by service
 
-### Aggregate & Source Types
-- **`CampaignWithDetails`** — Campaign bundled with its content and media arrays
-- **`CampaignStats`** / **`AIUsageSummary`** — Dashboard-level rollup statistics
-- **`ContentSourceType`** — Union of 11 seed content origins (`product_release`, `blog_post_seed`, `event`, `podcast`, etc.)
-- **`URLInjectionPreference`** — `'none' | 'in_post' | 'as_comment'`
+### Content Source Types
+- **`ContentSourceType`** — Union type covering 13 content origin strategies (`product_release`, `blog_post_seed`, `event`, `podcast`, `faq`, etc.)
 
 ## Usage Example
 
@@ -41,25 +34,29 @@ Brief description: Defines all TypeScript interfaces, types, and enums for the F
 import type {
   CreateCampaignInput,
   AIContent,
-  ContentType,
-  URLInjectionPreference,
+  ContentSourceType,
+  MediaProvider,
 } from './marketing';
 
-// Create a campaign seeded from a product release
 const newCampaign: CreateCampaignInput = {
   name: 'Q3 Product Launch',
   content_source_type: 'product_release',
   content_source_id: 42,
-  custom_instructions: 'Emphasize enterprise features and ROI',
-  start_date: '2025-07-01',
+  custom_instructions: 'Emphasize enterprise features and security compliance.',
+  start_date: '2025-08-01',
 };
 
-// Type-safe AI content with URL injection preference
-const socialPost: Partial<AIContent> = {
-  content_type: 'social_post' as ContentType,
+const generatedPost: Partial<AIContent> = {
+  content_type: 'social_post',
   status: 'draft',
   social_account_id: 7,
-  url_injection_preference: 'as_comment' as URLInjectionPreference,
+  url_injection_preference: 'as_comment',
   selected_for_publish: false,
 };
-```
+
+const provider: MediaProvider = 'flux-pro';
+```
+
+## Source
+
+[`marketing.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/marketing.ts)