@fayz-ai/plugin-conversations 0.2.0

package/src/data/mock.ts

@@ -0,0 +1,142 @@
+import type { ConversationsProvider } from './types'
+import type {
+  Conversation,
+  Message,
+  ListConversationsQuery,
+  SendMessageInput,
+  ConversationStatus,
+} from '../types'
+
+// Deterministic relative timestamps (no Date.now at module init for stable seeds).
+function minutesAgo(base: number, mins: number): string {
+  return new Date(base - mins * 60_000).toISOString()
+}
+
+function seed(): { conversations: Conversation[]; messages: Message[] } {
+  const base = new Date('2026-06-16T14:00:00Z').getTime()
+
+  const conversations: Conversation[] = [
+    {
+      id: 'c1', contactName: 'Marina Alves', contactHandle: '+55 11 99876-1020', channel: 'whatsapp',
+      lastMessagePreview: 'Perfect, can we book for Friday at 3pm?', lastMessageAt: minutesAgo(base, 4),
+      unreadCount: 2, status: 'open', assignedTo: 'You', accent: '#22c55e', tags: ['Hot lead'],
+      location: 'São Paulo, BR', note: 'Referred by Instagram ad — interested in full color + cut.',
+    },
+    {
+      id: 'c2', contactName: 'Jordan Pierce', contactHandle: '+1 (415) 555-0142', channel: 'sms',
+      lastMessagePreview: 'Got it — sending the deposit now.', lastMessageAt: minutesAgo(base, 22),
+      unreadCount: 0, status: 'open', assignedTo: 'You', accent: '#6366f1', tags: ['Customer'],
+      location: 'San Francisco, US',
+    },
+    {
+      id: 'c3', contactName: '@thehairloft', contactHandle: 'thehairloft', channel: 'instagram',
+      lastMessagePreview: 'Do you offer balayage on weekends?', lastMessageAt: minutesAgo(base, 51),
+      unreadCount: 1, status: 'open', accent: '#ec4899', tags: ['New'],
+    },
+    {
+      id: 'c4', contactName: 'David Whitman', contactHandle: 'david@whitman.co', channel: 'email',
+      lastMessagePreview: 'Re: Proposal — looks great, one question on pricing…', lastMessageAt: minutesAgo(base, 95),
+      unreadCount: 0, status: 'open', assignedTo: 'Sofia', accent: '#0ea5e9', tags: ['Proposal'],
+      location: 'Austin, US', note: 'Evaluating the retainer tier. Decision expected this week.',
+    },
+    {
+      id: 'c5', contactName: 'Website visitor', contactHandle: 'live chat · acme.com', channel: 'webchat',
+      lastMessagePreview: 'Is anyone available to chat?', lastMessageAt: minutesAgo(base, 140),
+      unreadCount: 0, status: 'snoozed', accent: '#f59e0b', tags: [],
+    },
+    {
+      id: 'c6', contactName: 'Priya Nair', contactHandle: '+44 7700 900123', channel: 'whatsapp',
+      lastMessagePreview: 'Thank you! See you next week 🙌', lastMessageAt: minutesAgo(base, 1440),
+      unreadCount: 0, status: 'closed', assignedTo: 'You', accent: '#14b8a6', tags: ['Customer'],
+      location: 'London, UK',
+    },
+  ]
+
+  const messages: Message[] = [
+    msg('m1', 'c1', 'whatsapp', 'inbound', 'Hi! I saw your ad — do you have availability this week?', 'Marina Alves', minutesAgo(base, 18)),
+    msg('m2', 'c1', 'whatsapp', 'outbound', 'Hi Marina! Yes, we do. What service are you interested in?', 'You', minutesAgo(base, 15)),
+    msg('m3', 'c1', 'whatsapp', 'inbound', 'A full color + cut.', 'Marina Alves', minutesAgo(base, 9)),
+    msg('m4', 'c1', 'whatsapp', 'inbound', 'Perfect, can we book for Friday at 3pm?', 'Marina Alves', minutesAgo(base, 4)),
+
+    msg('m5', 'c2', 'sms', 'outbound', 'Your appointment is confirmed for tomorrow at 10am.', 'You', minutesAgo(base, 40)),
+    msg('m6', 'c2', 'sms', 'inbound', 'Got it — sending the deposit now.', 'Jordan Pierce', minutesAgo(base, 22)),
+
+    msg('m7', 'c3', 'instagram', 'inbound', 'Do you offer balayage on weekends?', '@thehairloft', minutesAgo(base, 51)),
+
+    msg('m8', 'c4', 'email', 'inbound', 'Re: Proposal — looks great, one question on pricing for the retainer tier.', 'David Whitman', minutesAgo(base, 95)),
+    msg('m9', 'c4', 'email', 'outbound', 'Happy to walk you through it — are you free for a quick call tomorrow?', 'Sofia', minutesAgo(base, 80)),
+
+    msg('m10', 'c5', 'webchat', 'inbound', 'Is anyone available to chat?', 'Website visitor', minutesAgo(base, 140)),
+
+    msg('m11', 'c6', 'whatsapp', 'outbound', 'You are all set for next Tuesday. Anything else?', 'You', minutesAgo(base, 1500)),
+    msg('m12', 'c6', 'whatsapp', 'inbound', 'Thank you! See you next week 🙌', 'Priya Nair', minutesAgo(base, 1440)),
+  ]
+
+  return { conversations, messages }
+}
+
+function msg(
+  id: string, conversationId: string, channel: Message['channel'],
+  direction: Message['direction'], body: string, author: string, at: string,
+): Message {
+  return { id, conversationId, channel, direction, body, author, at }
+}
+
+export function createMockConversationsProvider(): ConversationsProvider {
+  const { conversations, messages } = seed()
+  let counter = 100
+
+  return {
+    async listConversations(query?: ListConversationsQuery): Promise<Conversation[]> {
+      let list = [...conversations]
+      if (query?.channel && query.channel !== 'all') list = list.filter((c) => c.channel === query.channel)
+      if (query?.status && query.status !== 'all') list = list.filter((c) => c.status === query.status)
+      if (query?.search) {
+        const q = query.search.toLowerCase()
+        list = list.filter(
+          (c) => c.contactName.toLowerCase().includes(q) || c.lastMessagePreview.toLowerCase().includes(q),
+        )
+      }
+      return list.sort((a, b) => b.lastMessageAt.localeCompare(a.lastMessageAt))
+    },
+
+    async getMessages(conversationId: string): Promise<Message[]> {
+      return messages
+        .filter((m) => m.conversationId === conversationId)
+        .sort((a, b) => a.at.localeCompare(b.at))
+    },
+
+    async sendMessage(input: SendMessageInput): Promise<Message> {
+      const conv = conversations.find((c) => c.id === input.conversationId)
+      const created: Message = {
+        id: `m${++counter}`,
+        conversationId: input.conversationId,
+        channel: conv?.channel ?? 'sms',
+        direction: 'outbound',
+        body: input.body,
+        author: 'You',
+        at: new Date().toISOString(),
+      }
+      messages.push(created)
+      if (conv) {
+        conv.lastMessagePreview = input.body
+        conv.lastMessageAt = created.at
+        conv.unreadCount = 0
+        if (conv.status === 'closed') conv.status = 'open'
+      }
+      return created
+    },
+
+    async markRead(conversationId: string): Promise<void> {
+      const conv = conversations.find((c) => c.id === conversationId)
+      if (conv) conv.unreadCount = 0
+    },
+
+    async setStatus(conversationId: string, status: ConversationStatus): Promise<Conversation> {
+      const conv = conversations.find((c) => c.id === conversationId)
+      if (!conv) throw new Error('Conversation not found')
+      conv.status = status
+      return conv
+    },
+  }
+}

package/src/data/supabase.ts

@@ -0,0 +1,202 @@
+import { getSupabaseClientOptional } from '@fayz-ai/core'
+import type { ConversationsProvider } from './types'
+import type {
+  Conversation,
+  Message,
+  ListConversationsQuery,
+  SendMessageInput,
+  ConversationStatus,
+} from '../types'
+
+// ---------------------------------------------------------------------------
+// Supabase-backed conversations provider — reads/writes the project's
+// `conversations` + `conversation_messages` tables (tenant-scoped via RLS +
+// an explicit tenant filter from the active-org context). Mirrors the inline
+// client-casting style of @fayz-ai/core's createSupabaseProvider; the global
+// client is `unknown`-typed so each call narrows the shape it needs.
+//
+// Real channel connectors (Twilio, WhatsApp Cloud, Meta, IMAP) deliver inbound
+// rows into these tables out-of-band; this provider is the read/compose surface.
+// ---------------------------------------------------------------------------
+
+export interface SupabaseConversationsConfig {
+  /** Supabase client; defaults to the global one registered by createFayzApp. */
+  supabaseClient?: unknown
+  /** Active tenant id (value or getter) used to scope reads and stamp writes. */
+  tenantId?: string | (() => string | undefined)
+  /** Display name stamped as the author of outbound messages. */
+  selfAuthor?: string
+}
+
+type Row = Record<string, unknown>
+
+function mapConversation(r: Row): Conversation {
+  return {
+    id: String(r.id),
+    contactName: (r.contact_name as string) ?? '',
+    contactHandle: (r.contact_handle as string) ?? '',
+    channel: (r.channel as Conversation['channel']) ?? 'sms',
+    lastMessagePreview: (r.last_message_preview as string) ?? '',
+    lastMessageAt: (r.last_message_at as string) ?? '',
+    unreadCount: Number(r.unread_count ?? 0),
+    status: (r.status as ConversationStatus) ?? 'open',
+    assignedTo: (r.assigned_to as string | null) ?? undefined,
+    accent: (r.accent as string) ?? '#6366f1',
+    tags: (r.tags as string[] | null) ?? [],
+    location: (r.location as string | null) ?? undefined,
+    note: (r.note as string | null) ?? undefined,
+  }
+}
+
+function mapMessage(r: Row): Message {
+  return {
+    id: String(r.id),
+    conversationId: String(r.conversation_id),
+    channel: (r.channel as Message['channel']) ?? 'sms',
+    direction: (r.direction as Message['direction']) ?? 'inbound',
+    body: (r.body as string) ?? '',
+    at: (r.at as string) ?? '',
+    author: (r.author as string) ?? '',
+  }
+}
+
+export function createSupabaseConversationsProvider(
+  config?: SupabaseConversationsConfig,
+): ConversationsProvider {
+  const selfAuthor = config?.selfAuthor ?? 'You'
+
+  function resolveTenantId(): string | undefined {
+    if (!config?.tenantId) return undefined
+    return typeof config.tenantId === 'function' ? config.tenantId() : config.tenantId
+  }
+
+  function client(): { from: (t: string) => Row } {
+    const supabase = (config?.supabaseClient ?? getSupabaseClientOptional()) as
+      | { from: (t: string) => Row }
+      | null
+    if (!supabase) {
+      throw new Error(
+        '[plugin-conversations] Supabase client not available. Pass supabaseClient or register the global client via createFayzApp.',
+      )
+    }
+    return supabase
+  }
+
+  return {
+    async listConversations(query?: ListConversationsQuery): Promise<Conversation[]> {
+      let q = (client().from('conversations') as { select: (s: string) => Row }).select('*')
+
+      const tenantId = resolveTenantId()
+      if (tenantId) q = (q as { eq: (c: string, v: string) => Row }).eq('tenant_id', tenantId)
+      if (query?.channel && query.channel !== 'all') {
+        q = (q as { eq: (c: string, v: string) => Row }).eq('channel', query.channel)
+      }
+      if (query?.status && query.status !== 'all') {
+        q = (q as { eq: (c: string, v: string) => Row }).eq('status', query.status)
+      }
+      if (query?.search) {
+        const term = `%${query.search}%`
+        q = (q as { or: (c: string) => Row }).or(
+          `contact_name.ilike.${term},last_message_preview.ilike.${term}`,
+        )
+      }
+      q = (q as { order: (c: string, o: unknown) => Row }).order('last_message_at', {
+        ascending: false,
+      })
+
+      const { data, error } = (await q) as { data: Row[] | null; error: unknown }
+      if (error) throw error
+      return (data ?? []).map(mapConversation)
+    },
+
+    async getMessages(conversationId: string): Promise<Message[]> {
+      const selected = (
+        client().from('conversation_messages') as { select: (s: string) => Row }
+      ).select('*')
+      const filtered = (selected as { eq: (c: string, v: string) => Row }).eq(
+        'conversation_id',
+        conversationId,
+      )
+      const ordered = (filtered as { order: (c: string, o: unknown) => Row }).order('at', {
+        ascending: true,
+      })
+      const { data, error } = (await ordered) as { data: Row[] | null; error: unknown }
+      if (error) throw error
+      return (data ?? []).map(mapMessage)
+    },
+
+    async sendMessage(input: SendMessageInput): Promise<Message> {
+      const tenantId = resolveTenantId()
+
+      // Resolve the channel from the parent conversation so the message matches.
+      const convSelected = (client().from('conversations') as { select: (s: string) => Row }).select(
+        'channel',
+      )
+      const convFiltered = (convSelected as { eq: (c: string, v: string) => Row }).eq(
+        'id',
+        input.conversationId,
+      )
+      const { data: conv } = (await (
+        convFiltered as { maybeSingle: () => Promise<{ data: Row | null }> }
+      ).maybeSingle()) as { data: Row | null }
+      const channel = (conv?.channel as Message['channel']) ?? 'sms'
+
+      const at = new Date().toISOString()
+      const row: Row = {
+        conversation_id: input.conversationId,
+        channel,
+        direction: 'outbound',
+        body: input.body,
+        author: selfAuthor,
+        at,
+      }
+      if (tenantId) row.tenant_id = tenantId
+
+      const { data: created, error } = (await (
+        (client().from('conversation_messages') as { insert: (r: Row) => Row }).insert(row) as {
+          select: () => { single: () => Promise<{ data: Row | null; error: unknown }> }
+        }
+      )
+        .select()
+        .single()) as { data: Row | null; error: unknown }
+      if (error) throw error
+
+      // Roll the parent conversation forward (preview / timestamp / unread / reopen).
+      await (
+        (client().from('conversations') as {
+          update: (r: Row) => Row
+        }).update({
+          last_message_preview: input.body,
+          last_message_at: at,
+          unread_count: 0,
+          status: 'open',
+        }) as { eq: (c: string, v: string) => Promise<unknown> }
+      ).eq('id', input.conversationId)
+
+      return mapMessage(created ?? row)
+    },
+
+    async markRead(conversationId: string): Promise<void> {
+      const { error } = (await (
+        (client().from('conversations') as { update: (r: Row) => Row }).update({
+          unread_count: 0,
+        }) as { eq: (c: string, v: string) => Promise<{ error: unknown }> }
+      ).eq('id', conversationId)) as { error: unknown }
+      if (error) throw error
+    },
+
+    async setStatus(conversationId: string, status: ConversationStatus): Promise<Conversation> {
+      const updated = (client().from('conversations') as { update: (r: Row) => Row }).update({
+        status,
+      })
+      const filtered = (updated as { eq: (c: string, v: string) => Row }).eq('id', conversationId)
+      const selected = (filtered as { select: () => Row }).select()
+      const { data, error } = (await (
+        selected as { single: () => Promise<{ data: Row | null; error: unknown }> }
+      ).single()) as { data: Row | null; error: unknown }
+      if (error) throw error
+      if (!data) throw new Error('Conversation not found')
+      return mapConversation(data)
+    },
+  }
+}

package/src/data/types.ts

@@ -0,0 +1,15 @@
+import type {
+  Conversation,
+  Message,
+  ListConversationsQuery,
+  SendMessageInput,
+  ConversationStatus,
+} from '../types'
+
+export interface ConversationsProvider {
+  listConversations(query?: ListConversationsQuery): Promise<Conversation[]>
+  getMessages(conversationId: string): Promise<Message[]>
+  sendMessage(input: SendMessageInput): Promise<Message>
+  markRead(conversationId: string): Promise<void>
+  setStatus(conversationId: string, status: ConversationStatus): Promise<Conversation>
+}

package/src/index.ts

@@ -0,0 +1,132 @@
+import React from 'react'
+import type { PluginManifest, PluginScope, VerticalId } from '@fayz-ai/core'
+import { getActiveTenantId, getSupabaseClientOptional, registerTranslations } from '@fayz-ai/core'
+import { ConversationsPage } from './ConversationsPage'
+import type { ConversationsProvider } from './data/types'
+import { createMockConversationsProvider } from './data/mock'
+import { createSupabaseConversationsProvider } from './data/supabase'
+import { createConversationsStore } from './store'
+import { conversationsLocales } from './locales'
+
+// ---------------------------------------------------------------------------
+// @fayz-ai/plugin-conversations — the GoHighLevel "Conversations" equivalent:
+// one omni-channel inbox (SMS / WhatsApp / Instagram / Email / Web chat).
+// Universal plugin — reusable by any vertical (beauty, resto, agency…).
+//
+// M1 ships a full mock inbox. Real channel connectors (Twilio, WhatsApp Cloud,
+// Meta, IMAP) + Supabase-backed threads land in a later milestone.
+// ---------------------------------------------------------------------------
+
+export interface ConversationsPluginOptions {
+  navPosition?: number
+  navSection?: 'main' | 'secondary' | 'settings'
+  navLabel?: string
+  scope?: PluginScope
+  verticalId?: VerticalId
+  dataProvider?: ConversationsProvider
+}
+
+function createSafeProvider(): ConversationsProvider {
+  // Real data when a Supabase client is registered (reads/writes the
+  // `conversations` + `conversation_messages` tables, tenant-scoped via the
+  // active-org context); falls back to the mock inbox when no backend is wired.
+  if (getSupabaseClientOptional()) {
+    return createSupabaseConversationsProvider({ tenantId: () => getActiveTenantId() })
+  }
+  return createMockConversationsProvider()
+}
+
+export function createConversationsPlugin(options?: ConversationsPluginOptions): PluginManifest {
+  registerTranslations(conversationsLocales)
+  const provider = options?.dataProvider ?? createSafeProvider()
+  const store = createConversationsStore(provider)
+
+  const PageComponent: React.ComponentType<unknown> = () =>
+    React.createElement(ConversationsPage, { store })
+  PageComponent.displayName = 'ConversationsPage'
+
+  return {
+    id: 'conversations',
+    name: options?.navLabel ?? 'Conversations',
+    icon: 'MessageCircle',
+    version: '1.0.0',
+    scope: options?.scope ?? 'universal',
+    verticalId: options?.verticalId,
+    defaultEnabled: true,
+    dependencies: [],
+    declaredFeatures: [{ id: 'conversations', label: 'Conversations', group: 'Engage' }],
+    navigation: [
+      {
+        section: options?.navSection ?? 'main',
+        position: options?.navPosition ?? 1,
+        label: options?.navLabel ?? 'Conversations',
+        route: '/conversations',
+        icon: 'MessageCircle',
+        permission: { feature: 'conversations', action: 'read' as const },
+      },
+    ],
+    routes: [
+      {
+        path: '/conversations',
+        component: PageComponent,
+        fullBleed: true,
+        permission: { feature: 'conversations', action: 'read' as const },
+      },
+    ],
+    widgets: [],
+    events: [
+      { name: 'conversations.message.received', description: 'An inbound message arrived on any channel' },
+      { name: 'conversations.message.sent', description: 'An outbound message was sent' },
+    ],
+    aiTools: [
+      {
+        id: 'conversations.list-threads',
+        name: 'listConversations',
+        description: 'Lists open conversations across all channels, optionally filtered by channel.',
+        icon: 'MessageCircle',
+        mode: 'read' as const,
+        category: 'Conversations',
+        parameters: {
+          type: 'object' as const,
+          properties: {
+            channel: {
+              type: 'string' as const,
+              enum: ['all', 'sms', 'whatsapp', 'instagram', 'email', 'webchat'],
+            },
+          },
+        },
+        suggestions: [
+          { label: 'Show unread conversations' },
+          { label: 'Any new WhatsApp messages?' },
+        ],
+        permission: { feature: 'conversations', action: 'read' as const },
+      },
+      {
+        id: 'conversations.send-message',
+        name: 'sendMessage',
+        description: 'Sends a reply in a conversation thread.',
+        icon: 'Send',
+        mode: 'persist' as const,
+        category: 'Conversations',
+        parameters: {
+          type: 'object' as const,
+          properties: {
+            conversationId: { type: 'string' as const, description: 'Conversation id' },
+            body: { type: 'string' as const, description: 'Message body' },
+          },
+          required: ['conversationId', 'body'],
+        },
+        permission: { feature: 'conversations', action: 'create' as const },
+      },
+    ],
+    locales: conversationsLocales,
+  }
+}
+
+export type { ConversationsProvider } from './data/types'
+export type { Conversation, Message, Channel } from './types'
+export { createMockConversationsProvider } from './data/mock'
+export {
+  createSupabaseConversationsProvider,
+  type SupabaseConversationsConfig,
+} from './data/supabase'

package/src/locales/en.ts

@@ -0,0 +1,4 @@
+export const en: Record<string, string> = {
+  'conversations.title': 'Conversations',
+  'conversations.subtitle': 'Unified inbox across every channel',
+}

package/src/locales/index.ts

@@ -0,0 +1,5 @@
+import { en } from './en'
+
+export const conversationsLocales: Record<string, Record<string, string>> = {
+  en,
+}

package/src/store.ts

@@ -0,0 +1,93 @@
+import { createStore, type StoreApi } from 'zustand/vanilla'
+import type { ConversationsProvider } from './data/types'
+import type { Conversation, Message, Channel, ConversationStatus } from './types'
+
+export interface ConversationsUIState {
+  conversations: Conversation[]
+  messages: Message[]
+  selectedId: string | null
+  channelFilter: Channel | 'all'
+  search: string
+  loading: boolean
+  sending: boolean
+
+  load(): Promise<void>
+  select(id: string): Promise<void>
+  deselect(): void
+  setChannelFilter(channel: Channel | 'all'): Promise<void>
+  setSearch(search: string): Promise<void>
+  send(body: string): Promise<void>
+  setStatus(status: ConversationStatus): Promise<void>
+}
+
+export function createConversationsStore(
+  provider: ConversationsProvider,
+): StoreApi<ConversationsUIState> {
+  return createStore<ConversationsUIState>((set, get) => ({
+    conversations: [],
+    messages: [],
+    selectedId: null,
+    channelFilter: 'all',
+    search: '',
+    loading: false,
+    sending: false,
+
+    async load() {
+      set({ loading: true })
+      const conversations = await provider.listConversations({
+        channel: get().channelFilter,
+        search: get().search || undefined,
+      })
+      const selectedId = get().selectedId ?? conversations[0]?.id ?? null
+      set({ conversations, loading: false, selectedId })
+      if (selectedId) await get().select(selectedId)
+    },
+
+    async select(id: string) {
+      set({ selectedId: id })
+      const messages = await provider.getMessages(id)
+      set({ messages })
+      await provider.markRead(id)
+      set((s) => ({
+        conversations: s.conversations.map((c) => (c.id === id ? { ...c, unreadCount: 0 } : c)),
+      }))
+    },
+
+    deselect() {
+      set({ selectedId: null, messages: [] })
+    },
+
+    async setChannelFilter(channel) {
+      set({ channelFilter: channel })
+      await get().load()
+    },
+
+    async setSearch(search) {
+      set({ search })
+      await get().load()
+    },
+
+    async send(body: string) {
+      const id = get().selectedId
+      if (!id || !body.trim()) return
+      set({ sending: true })
+      const created = await provider.sendMessage({ conversationId: id, body: body.trim() })
+      set((s) => ({
+        sending: false,
+        messages: [...s.messages, created],
+        conversations: s.conversations.map((c) =>
+          c.id === id ? { ...c, lastMessagePreview: created.body, lastMessageAt: created.at } : c,
+        ),
+      }))
+    },
+
+    async setStatus(status) {
+      const id = get().selectedId
+      if (!id) return
+      const updated = await provider.setStatus(id, status)
+      set((s) => ({
+        conversations: s.conversations.map((c) => (c.id === id ? updated : c)),
+      }))
+    },
+  }))
+}

package/src/types.ts

@@ -0,0 +1,58 @@
+// ---------------------------------------------------------------------------
+// @fayz-ai/plugin-conversations — domain types for the unified omni-channel
+// inbox (the GoHighLevel "Conversations" equivalent). Provider-agnostic.
+// ---------------------------------------------------------------------------
+
+export type Channel = 'sms' | 'whatsapp' | 'instagram' | 'email' | 'webchat'
+
+export type ConversationStatus = 'open' | 'snoozed' | 'closed'
+
+export type MessageDirection = 'inbound' | 'outbound'
+
+export interface Conversation {
+  id: string
+  contactName: string
+  /** Phone, @handle, or email depending on channel */
+  contactHandle: string
+  channel: Channel
+  lastMessagePreview: string
+  lastMessageAt: string
+  unreadCount: number
+  status: ConversationStatus
+  assignedTo?: string
+  /** Tailwind-ish accent for the avatar bubble */
+  accent: string
+  tags: string[]
+  // Optional context shown in the contact panel.
+  location?: string
+  note?: string
+}
+
+export interface Message {
+  id: string
+  conversationId: string
+  channel: Channel
+  direction: MessageDirection
+  body: string
+  at: string
+  author: string
+}
+
+export interface ListConversationsQuery {
+  channel?: Channel | 'all'
+  status?: ConversationStatus | 'all'
+  search?: string
+}
+
+export interface SendMessageInput {
+  conversationId: string
+  body: string
+}
+
+export const CHANNEL_LABELS: Record<Channel, string> = {
+  sms: 'SMS',
+  whatsapp: 'WhatsApp',
+  instagram: 'Instagram',
+  email: 'Email',
+  webchat: 'Web Chat',
+}