@lionchat/mcp-server 0.2.0 → 0.3.0

package/dist/docs/resources/data-model.md

@@ -0,0 +1,378 @@
+# Modelo de Dados LionChat (Detalhado)
+
+Mapa completo de entidades, relacionamentos e foreign keys. Use quando precisar entender como dados conectam ou como navegar entre recursos.
+
+## Multi-tenancy: Account
+
+`Account` é a raiz. **TODA** entidade tem `account_id` direta ou indiretamente. Nunca há "vazamento" entre contas.
+
+```
+Account
+├── id (PK)
+├── name
+├── plan_id (FK → Plan)
+├── feature_flags (bigint bitfield)
+├── feature_flags_2 (bigint bitfield, features 64+)
+├── usage_limits (jsonb)
+├── custom_attributes (jsonb)
+├── domain
+├── support_email
+└── locale (string, ex: 'pt_BR')
+```
+
+## Usuários e Permissões
+
+```
+User                           AccountUser (junction)
+├── id (PK)                    ├── id (PK)
+├── name                       ├── user_id (FK → User)
+├── email                      ├── account_id (FK → Account)
+├── pubsub_token               ├── role (enum: 'agent' | 'administrator')
+├── ui_settings (jsonb)        ├── custom_role_id (FK opcional)
+├── access_token (has_one)     ├── auto_offline (bool)
+└── account_users (has_many)   ├── availability (enum)
+                               ├── active_at
+                               └── permissions (string[])
+```
+
+**Importante:** o `role` no `AccountUser` é por conta. Mesmo `User` pode ser admin numa conta e agent em outra.
+
+## Canal de Comunicação
+
+```
+Inbox
+├── id (PK)
+├── account_id (FK)
+├── name
+├── channel_type (string, ex: 'Channel::Waha')
+├── channel_id (FK polimórfico)
+├── enable_auto_assignment (bool)
+├── working_hours_enabled (bool)
+└── greeting_enabled (bool)
+
+Channel::Waha / Channel::Whatsapp / Channel::WebWidget / ...
+├── id (PK, table específica)
+├── account_id (FK)
+├── (campos específicos por canal)
+└── has_one :inbox (via Channelable concern)
+
+InboxMember (junction Inbox ↔ User)
+├── inbox_id
+└── user_id
+```
+
+## Conversação e Mensagens
+
+```
+Conversation
+├── id (PK, global)
+├── account_id (FK)
+├── display_id (visível pra humanos, único por conta)
+├── inbox_id (FK, optional: pode ser NULL se inbox deletada)
+├── contact_id (FK → Contact)
+├── contact_inbox_id (FK → ContactInbox)
+├── assignee_id (FK → User, optional)
+├── team_id (FK → Team, optional)
+├── captain_assistant_id (FK → Captain::Assistant, optional)
+├── status (int: 0/1/2/3)
+├── priority (string)
+├── snoozed_until (datetime, se status=3)
+├── waiting_since (datetime)
+├── first_reply_created_at (datetime)
+├── last_activity_at (datetime)
+├── custom_attributes (jsonb)
+├── additional_attributes (jsonb)
+└── labels (via taggings)
+
+Message
+├── id (PK)
+├── account_id (FK)
+├── conversation_id (FK)
+├── inbox_id (FK)
+├── content (text, nullable)
+├── message_type (int: 0/1/2/3)
+├── content_type (string)
+├── content_attributes (jsonb)
+├── status (enum: sent/delivered/read/failed/progress)
+├── source_id (string, ID externo do canal)
+├── sender_type / sender_id (polimórfico)
+├── private (bool: nota privada)
+├── sentiment (jsonb)
+├── attachments (has_many)
+└── created_at
+
+Attachment
+├── id (PK)
+├── message_id (FK)
+├── account_id (FK)
+├── file_type (string ou int)
+├── extension
+├── file (ActiveStorage attached)
+├── transcribed_text (string, áudio/PDF)
+├── meta (jsonb, ex: image_description)
+├── width / height (pixels)
+└── file_size (bytes)
+```
+
+## Contatos
+
+```
+Contact
+├── id (PK)
+├── account_id (FK)
+├── name
+├── email
+├── phone_number (E.164, ex: +5511999999999)
+├── identifier (ID externo opcional)
+├── additional_attributes (jsonb)
+├── custom_attributes (jsonb)
+├── pubsub_token
+├── blocked (bool)
+├── last_activity_at
+└── company_id (FK → Company, optional)
+
+ContactInbox (junction Contact ↔ Inbox)
+├── id (PK)
+├── contact_id (FK)
+├── inbox_id (FK)
+├── source_id (string, ID do contato no canal)
+└── additional_attributes (jsonb, ex: not_on_whatsapp)
+
+Company
+├── id (PK)
+├── account_id (FK)
+├── name
+└── domain
+```
+
+**Padrões de `source_id` por canal:**
+- Waha: `5511999999999@c.us` (1-on-1) ou `120363xxx@g.us` (grupo) ou `XXXX@lid` (LID)
+- WhatsApp Cloud: `5511999999999` (E.164 sem prefixo)
+- Email: o email mesmo
+- WebWidget: UUID gerado
+
+## Kanban / CRM
+
+```
+Funnel
+├── id (PK)
+├── account_id (FK)
+├── name
+├── stages (jsonb: array de { name, color, position })
+├── archived (bool)
+└── created_at
+
+KanbanItem
+├── id (PK)
+├── account_id (FK)
+├── funnel_id (FK)
+├── funnel_stage (string, nome da etapa atual)
+├── stage_entered_at (datetime)
+├── position (int, ordem dentro da etapa)
+├── conversation_display_id (FK opcional → Conversation.display_id)
+├── item_details (jsonb)
+├── custom_attributes (jsonb)
+├── assigned_agents (jsonb array)
+├── linked_conversations (jsonb array de { display_id })
+├── checklist (jsonb)
+├── activities (jsonb)
+├── timer_started_at / timer_duration
+└── created_at
+
+KanbanChecklist
+├── kanban_item_id (FK)
+├── title
+├── completed (bool)
+└── position
+
+KanbanNote
+├── kanban_item_id (FK)
+├── content (text)
+└── created_at
+```
+
+## IA / Captain
+
+```
+Captain::Assistant
+├── id (PK)
+├── account_id (FK)
+├── name
+├── description
+├── config (jsonb: model, temperature, instructions, feature_memory, feature_faq, ...)
+├── guardrails (string[])
+├── response_guidelines (string[])
+└── active_conversations_count
+
+Captain::AssistantResponse (FAQ)
+├── assistant_id (FK)
+├── question
+├── answer
+├── status (pending/approved/rejected)
+├── embedding (vector, pgvector)
+└── documentable (polymorphic: Conversation que gerou)
+
+Captain::Document (Base de conhecimento)
+├── assistant_id (FK)
+├── content (text)
+└── name
+
+Captain::CopilotPrompt (Prompts salvos)
+├── account_id (FK)
+├── title
+└── prompt (text)
+```
+
+## Automações
+
+```
+AutomationRule
+├── id (PK)
+├── account_id (FK)
+├── name
+├── event_name (conversation_created, conversation_resolved, message_created, conversation_opened, conversation_updated)
+├── conditions (jsonb array)
+├── actions (jsonb array)
+└── active (bool)
+
+Macro
+├── id (PK)
+├── account_id (FK)
+├── name
+├── actions (jsonb array)
+└── visibility (personal/global)
+```
+
+## Agenda / Tarefas / Booking
+
+```
+AccountTask (agenda interna)
+├── id (PK)
+├── account_id (FK)
+├── user_id (FK → User, assignee)
+├── title
+├── description
+├── due_at (datetime)
+├── completed_at (datetime, nullable)
+└── color (string)
+
+BookingEventType (template de agendamento)
+├── id (PK)
+├── account_id (FK)
+├── name (ex: "Demo 30min")
+├── duration_minutes
+├── availability_rules (jsonb)
+└── description
+
+Booking (agendamento confirmado)
+├── id (PK)
+├── account_id (FK)
+├── booking_event_type_id (FK)
+├── user_id (FK, agente que vai atender)
+├── attendee_name / attendee_email / attendee_phone
+├── start_time / end_time (ISO 8601)
+├── status (scheduled/cancelled/completed)
+└── meeting_url (Google Calendar / Zoom / etc)
+```
+
+## Relatórios e Métricas
+
+```
+ReportingEvent
+├── account_id (FK)
+├── name (conversation_created, conversation_resolved, csat_score, ...)
+├── value (numeric)
+├── value_in_business_hours (numeric)
+├── conversation_id (FK opcional)
+├── user_id (FK opcional)
+├── inbox_id (FK opcional)
+└── created_at
+
+CsatSurveyResponse
+├── conversation_id (FK)
+├── contact_id (FK)
+├── score (1-5)
+├── feedback_message
+└── created_at
+
+SLA::Policy (políticas de SLA)
+├── account_id (FK)
+├── first_response_time_threshold (int, seconds)
+├── next_response_time_threshold
+├── resolution_time_threshold
+└── conditions (jsonb)
+```
+
+## Webhooks / Integrações
+
+```
+Webhook (saída)
+├── account_id (FK)
+├── url
+├── subscriptions (string[]: eventos a notificar)
+└── inbox_id (FK opcional, scope)
+
+Integrations::Hook (integrações: OpenAI, Groq, Slack, etc)
+├── account_id (FK)
+├── app_id (string: 'openai', 'groq', 'slack', 'dialogflow', ...)
+├── settings (jsonb: api_key, model, ...)
+├── status (boolean: ligado/desligado)
+└── reference_id (string opcional)
+
+MetaLeadIntegration (Facebook Lead Ads)
+├── account_id (FK)
+├── page_id
+├── page_name
+├── facebook_page_id (FK polimórfico)
+├── status (active/token_expired/paused)
+└── meta_lead_forms (has_many)
+```
+
+## Cardinalidades importantes
+
+- `Account` 1—N `User` (via AccountUser)
+- `Account` 1—N `Inbox`
+- `Account` 1—N `Contact`
+- `Account` 1—N `Conversation`
+- `Conversation` 1—N `Message`
+- `Message` 1—N `Attachment`
+- `Contact` 1—N `ContactInbox` (um por canal)
+- `Funnel` 1—N `KanbanItem`
+- `Conversation` 0..1—1 `KanbanItem` (opcional)
+- `Conversation` 0..1—1 `Captain::Assistant` (opcional, via captain_assistant_id)
+
+## Como navegar (queries comuns)
+
+### Conversa → Cliente
+```
+Conversation → contact_id → Contact
+```
+
+### Cliente → Todas as conversas
+```
+Contact → has_many :conversations
+```
+
+### Mensagem → Conta
+```
+Message → account_id (direto) OU Message → conversation → account_id
+```
+
+### Card Kanban → Conversa vinculada
+```
+KanbanItem → conversation_display_id → Conversation (where display_id = X)
+```
+
+### Conta → Plano e features
+```
+Account → plan_id → Plan
+Account.feature_enabled?('captain_v2')  # checa bitfield
+```
+
+## Soft-delete e statuses
+
+- Conversation NUNCA é deletada — só muda `status` (snoozed, resolved)
+- Inbox quando deletada → conversations ficam com `inbox_id = NULL` (dependent: :nullify)
+- Contact pode ser deletado (raro) — destroi conversations em cascata (cuidado)
+- KanbanItem pode ser deletado livremente
+- Funnel `archived = true` → não aparece na UI mas dados permanecem

package/dist/docs/resources/glossary.md

@@ -0,0 +1,242 @@
+# Glossário LionChat
+
+Glossário completo de termos, status codes, enums e conceitos da plataforma. Use como referência sempre que encontrar um campo numérico ou enum desconhecido na resposta de qualquer endpoint.
+
+## Conversation (Conversa)
+
+### `status` — Estado da conversa
+| Valor | Nome | Significado |
+|---|---|---|
+| `0` | `open` | Aberta — em atendimento ativo |
+| `1` | `resolved` | Resolvida — encerrada como sucesso |
+| `2` | `pending` | Pendente — aguardando alguém (cliente ou agente) |
+| `3` | `snoozed` | Adiada — voltará a aparecer em data futura (`snoozed_until`) |
+
+### `priority` — Prioridade
+| Valor | Significado |
+|---|---|
+| `urgent` | Urgente — atender o quanto antes |
+| `high` | Alta |
+| `medium` | Média |
+| `low` | Baixa |
+| `null` | Sem prioridade definida |
+
+### `assignee_type` (parâmetro de listagem)
+| Valor | Filtro aplicado |
+|---|---|
+| `me` | Conversas atribuídas ao usuário autenticado |
+| `assigned` | Conversas com qualquer agente atribuído |
+| `unassigned` | Conversas sem agente |
+| `all` | Todas (sem filtro) |
+
+### Campos importantes
+- `display_id`: número visível na UI (use ao falar com humanos: "conversa #245")
+- `id`: ID interno (use em parâmetros de outras chamadas)
+- `last_activity_at`: Unix timestamp (segundos) da última atividade
+- `waiting_since`: Unix timestamp (segundos) — desde quando aguarda resposta
+- `first_reply_created_at`: Unix timestamp da primeira resposta humana (`null` se nunca respondida)
+- `captain_assistant_id`: FK pro AI Agente (`null` = atendimento humano)
+- `custom_attributes.captain_manually_disabled`: `true` se admin desativou a IA explicitamente
+
+## Message (Mensagem)
+
+### `message_type`
+| Valor | Nome | Significado |
+|---|---|---|
+| `0` | `incoming` | Cliente → empresa (recebida) |
+| `1` | `outgoing` | Empresa → cliente (enviada) |
+| `2` | `activity` | Evento de sistema (atribuições, ativações IA, mudanças de status) |
+| `3` | `template` | Template aprovado WhatsApp Cloud API |
+
+### `status` (mensagens outgoing)
+| Valor | Significado |
+|---|---|
+| `sent` | Enviada com sucesso |
+| `delivered` | Entregue ao destinatário |
+| `read` | Lida pelo destinatário |
+| `failed` | Falha no envio |
+| `progress` | Em processamento |
+
+### `content_type`
+- `text`: texto puro
+- `input_select`: pergunta com opções (formulários do widget)
+- `cards`: cards interativos
+- `form`: formulário
+- `article`: artigo da central de ajuda
+
+### Campos importantes
+- `content`: texto da mensagem (pode ser `null` se for só anexo)
+- `attachments[]`: array de anexos (image, audio, video, file, location, contact)
+- `private`: `true` = nota privada (só visível pra equipe, não pro cliente)
+- `sender_type`: `User`, `Contact`, `Captain::Assistant`, `AgentBot`
+- `processed_message_content`: texto após processamento (com markdown removido, links resolvidos)
+
+## Attachment (Anexo)
+
+### `file_type`
+| Valor | Conteúdo |
+|---|---|
+| `image` | Foto / imagem (JPG, PNG, etc) |
+| `audio` | Áudio (geralmente vem com `transcribed_text` preenchido) |
+| `video` | Vídeo |
+| `file` | PDF, DOCX, qualquer outro (pode vir com `extracted_text` se for processado) |
+| `location` | Coordenadas GPS |
+| `contact` | vCard |
+| `share` | Link compartilhado |
+| `story_mention` | Menção em story (Instagram) |
+| `fallback` | Fallback de tipo não-reconhecido |
+
+### Campos importantes
+- `data_url`: URL pra baixar o arquivo (válida por tempo limitado)
+- `transcribed_text`: transcrição (áudio) ou texto extraído (PDF/imagem com OCR)
+- `meta.image_description`: descrição gerada pela IA (cache, se disponível)
+- `file_size`: bytes
+- `width`/`height`: pixels (imagens/vídeos)
+
+## Contact (Contato)
+
+### Campos importantes
+- `id`: ID interno
+- `identifier`: ID externo configurado pelo cliente (ex: ID interno do CRM dele)
+- `phone_number`: E.164 obrigatoriamente (`+5511999999999`)
+- `email`: opcional
+- `name`: nome completo
+- `additional_attributes`: hash de campos do sistema (não-editáveis)
+- `custom_attributes`: hash de campos custom (editáveis, definidos pela conta)
+
+### ContactInbox (vínculo Contato ↔ Inbox)
+- `source_id`: ID do contato no canal (ex: `5511999999999@c.us` no WhatsApp WAHA)
+- Um contato pode ter vários ContactInboxes (um por canal)
+
+## Inbox (Caixa de Entrada / Canal)
+
+### `channel_type`
+- `Channel::Waha` — WhatsApp via WAHA (não-oficial, QR code)
+- `Channel::Whatsapp` — WhatsApp Cloud API (oficial)
+- `Channel::WebWidget` — chat ao vivo no site
+- `Channel::Email` — email
+- `Channel::FacebookPage` — Messenger
+- `Channel::Instagram` — Instagram DM
+- `Channel::Telegram` — Telegram
+- `Channel::Api` — webhook custom
+- `Channel::Voice` — VoIP / chamadas
+
+### Campos importantes
+- `id`: ID interno
+- `name`: nome configurado pelo admin
+- `channel_id`: FK pro canal polimórfico
+- `enable_auto_assignment`: se está atribuindo automaticamente
+- `working_hours_enabled`: se respeita horário de atendimento
+- `greeting_enabled` / `greeting_message`: mensagem de boas-vindas
+
+## KanbanItem (Card do CRM)
+
+### Estrutura
+- `id`: ID interno
+- `conversation_display_id`: vinculação opcional com Conversa
+- `funnel_id`: FK pro Funnel (funil)
+- `funnel_stage`: nome da etapa atual (string)
+- `position`: ordem dentro da etapa (inteiro)
+- `stage_entered_at`: timestamp de quando entrou na etapa atual
+
+### `item_details` (jsonb)
+```json
+{
+  "title": "Negociação Empresa X",
+  "value": 5000.0,
+  "priority": "high",
+  "description": "...",
+  "notes": [{ "text": "..." }],
+  "offers": [{ "offer_id": 3 }],
+  "custom_attributes": { ... }
+}
+```
+
+### `assigned_agents` (jsonb array)
+```json
+[{ "id": 6, "name": "Elvis", "email": "...", "assigned_at": "..." }]
+```
+
+## Funnel (Funil do Kanban)
+
+- `name`: nome do funil
+- `stages`: array de etapas — cada uma com `name`, `color`, `position`
+- `archived`: `true` = não aparece na UI principal
+
+## Captain::Assistant (AI Agente / IA de atendimento)
+
+- `id`: ID interno
+- `name`: nome do agente (ex: "Luna", "Diogo")
+- `config.feature_memory`: gera notas no contato ao resolver conversas
+- `config.feature_faq`: gera FAQs sugeridas ao resolver conversas
+- `config.model`: modelo OpenAI usado (gpt-4o, gpt-4o-mini)
+- `config.temperature`: 0.0-1.0
+- `config.instructions`: prompt sistema (Liquid template)
+
+## Account (Conta)
+
+- `id`: ID interno (NÃO é o ID da empresa cliente — é o ID interno do LionChat)
+- `name`: nome da empresa
+- `plan_id`: FK pro Plan (qual plano assinou)
+- `feature_flags`: bigint bitfield com features ativas
+- `usage_limits`: hash de limites do plano + uso atual
+- `custom_attributes`: dados livres da conta
+
+## AccountUser (User dentro de uma Account)
+
+- `user_id` + `account_id`: chave composta
+- `role`: `agent` (atendente) ou `administrator` (admin/dono)
+- `availability`: `online`, `busy`, `offline`
+- `permissions`: array de strings com permissões granulares
+
+## AutomationRule (Regra de automação)
+
+- `event_name`: `conversation_created`, `conversation_resolved`, `message_created`, etc
+- `conditions`: jsonb array de condições
+- `actions`: jsonb array de ações
+- `active`: `true` = rodando
+
+## Booking (Agendamento)
+
+- `event_type_id`: FK pro tipo de evento (ex: "Demo 30min")
+- `attendee_email`, `attendee_name`, `attendee_phone`
+- `start_time`, `end_time`: ISO 8601
+- `status`: `scheduled`, `cancelled`, `completed`
+
+## Métricas (Reports)
+
+### Endpoints `lionchat_reports_*` retornam métricas em SEGUNDOS por padrão
+
+- `avg_first_response_time`: tempo médio em segundos até primeira resposta humana
+- `avg_resolution_time`: tempo médio em segundos até resolução
+- `conversations_count`: contagem absoluta
+- `incoming_messages_count`: contagem absoluta
+- `outgoing_messages_count`: contagem absoluta
+- `resolutions_count`: contagem absoluta
+
+### CSAT
+- `score`: 1 a 5 (estrelas) ou `csat_survey_response_at` (Unix ts)
+- `feedback_message`: texto opcional
+
+### SLA
+- `breach_count`: quantas SLAs estouraram
+- `hit_count`: quantas foram cumpridas
+- `due_at`: timestamp da SLA aplicada
+
+## Resumo de unidades
+
+| Métrica | Unidade |
+|---|---|
+| Tempo (avg_*_time) | **segundos** (converta pra min/h ao exibir) |
+| Datas | ISO 8601 ou Unix timestamp (segundos) |
+| Valores (KanbanItem.value) | Reais (BRL) por padrão, mas `value` é só numeric |
+| Coordenadas (location) | latitude/longitude decimais |
+| File size | bytes |
+| Pixels | inteiros |
+
+## Diferença entre `id` e `display_id`
+
+- `id`: **sempre use** ao passar pra outras chamadas API
+- `display_id`: **sempre use** ao falar com humanos ("conversa #245", "card #12")
+- Pra Conversation: `id` global, `display_id` por conta (mais amigável)
+- Pra Contact, Inbox, etc: só `id` (não tem display_id separado)