@adatechnology/conversations-ui 0.1.0-rc.4 → 0.1.0-rc.6

package/dist/types-CeixG2Z9.d.ts

@@ -0,0 +1,324 @@
+import * as react from 'react';
+
+interface ConversationsUIConfig {
+    apiBaseUrl: string;
+    theme?: ConversationsTheme;
+    features?: ConversationsFeatures;
+}
+interface ConversationsTheme {
+    primaryColor?: string;
+    backgroundColor?: string;
+    bubbleSent?: string;
+    bubbleReceived?: string;
+    textPrimary?: string;
+    textSecondary?: string;
+}
+interface ConversationsFeatures {
+    audio?: boolean;
+    documents?: boolean;
+    emoji?: boolean;
+    darkMode?: boolean;
+}
+interface MessagePayload {
+    id: string;
+    type: 'text' | 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'template';
+    content?: string;
+    caption?: string;
+    mediaUrl?: string;
+    base64?: string;
+    uploadId?: string;
+    mediaId?: string;
+    mimeType?: string;
+    filename?: string;
+    sizeBytes?: number;
+    direction: 'inbound' | 'outbound';
+    sender: 'bot' | 'customer' | 'agent';
+    timestamp: string;
+    status?: 'sent' | 'delivered' | 'read' | 'failed';
+    readAt?: string;
+    agentName?: string | null;
+    templateName?: string;
+    /**
+     * Veredito de moderação vindo do backend — a UI só exibe, nunca calcula. Dicionário no browser
+     * seria peso morto e daria veredito diferente por versão de cliente.
+     *
+     * `null`/ausente = não avaliado (moderação desligada, ou mensagem anterior ao recurso), que é
+     * diferente de avaliado e limpo.
+     */
+    moderation?: {
+        isOffensive: boolean;
+        terms: string[];
+    } | null;
+    isFirstInGroup?: boolean;
+    isLastInGroup?: boolean;
+}
+
+type ResolveMediaUrl = (message: MessagePayload) => Promise<string | null>;
+interface MediaRendererProps {
+    message: MessagePayload;
+    onLightbox: (src: string) => void;
+    onResolveUrl?: ResolveMediaUrl;
+    /** Aplicado no wrapper de cada tipo de mídia — imagem, vídeo, áudio e documento. */
+    className?: string;
+}
+declare function MediaRenderer({ message, onLightbox, onResolveUrl, className }: MediaRendererProps): react.JSX.Element | null;
+
+/**
+ * Canal de origem da conversa e o que cada um permite.
+ *
+ * Existe porque as regras que a inbox precisa respeitar não são do WhatsApp, são **de cada canal**:
+ * a janela de sessão, o jeito de reabrir a conversa e o formato do identificador do contato mudam
+ * entre WhatsApp, Messenger, Instagram e chat de site. Tratar a regra do WhatsApp como universal
+ * faria a UI bloquear o composer num chat de site, onde janela nenhuma existe.
+ *
+ * `whatsapp` é o padrão em todo lugar: instalações que ainda não informam canal continuam
+ * funcionando exatamente como antes.
+ */
+declare const CONVERSATION_CHANNEL: {
+    readonly WHATSAPP: "whatsapp";
+    readonly MESSENGER: "messenger";
+    readonly INSTAGRAM: "instagram";
+    readonly WEBCHAT: "webchat";
+};
+type ConversationChannel = (typeof CONVERSATION_CHANNEL)[keyof typeof CONVERSATION_CHANNEL];
+declare const DEFAULT_CONVERSATION_CHANNEL: ConversationChannel;
+/** Como o canal reabre uma conversa fora da janela de sessão. */
+declare const REOPEN_MECHANISM: {
+    readonly TEMPLATE: "template";
+    readonly TAG: "tag";
+    readonly NONE: "none";
+};
+type ReopenMechanism = (typeof REOPEN_MECHANISM)[keyof typeof REOPEN_MECHANISM];
+/** Natureza do identificador do contato — decide como exibi-lo. */
+declare const HANDLE_KIND: {
+    readonly PHONE: "phone";
+    readonly USERNAME: "username";
+    readonly SESSION: "session";
+};
+type HandleKind = (typeof HANDLE_KIND)[keyof typeof HANDLE_KIND];
+type ChannelCapabilities = {
+    readonly label: string;
+    readonly icon: string;
+    readonly hasSessionWindow: boolean;
+    readonly windowHours: number;
+    readonly reopenMechanism: ReopenMechanism;
+    readonly handleKind: HandleKind;
+};
+declare const CHANNEL_CAPABILITIES: Readonly<Record<ConversationChannel, ChannelCapabilities>>;
+declare function capabilitiesOf(channel: ConversationChannel | undefined): ChannelCapabilities;
+declare const CHANNEL_FILTER_ALL = "all";
+type ChannelFilter = ConversationChannel | typeof CHANNEL_FILTER_ALL;
+type ChannelFilterOption = {
+    readonly value: ChannelFilter;
+    readonly label: string;
+};
+/**
+ * Opções derivadas do que existe na lista, não do catálogo inteiro: oferecer Instagram numa conta
+ * que só tem WhatsApp promete um recorte que nunca traz resultado.
+ *
+ * Devolve vazio com menos de dois canais — um filtro de opção única não filtra nada, e a barra só
+ * ocuparia espaço. O host usa isso para esconder a seção.
+ */
+declare function channelFiltersFor(conversations: readonly {
+    readonly channel?: ConversationChannel | undefined;
+}[]): ChannelFilterOption[];
+type FormatContactHandleParams = {
+    readonly handle: string;
+    readonly channel?: ConversationChannel | undefined;
+};
+/**
+ * Exibição do identificador conforme a natureza dele. Formatar tudo como telefone — o que a UI
+ * fazia — transforma um `@perfil` do Instagram em dígitos sem sentido.
+ */
+declare function formatContactHandle(params: FormatContactHandleParams): string;
+/** Bandeira só faz sentido quando o identificador é telefone. */
+declare function contactFlag(params: FormatContactHandleParams): string;
+
+interface ListConversationsParams {
+    page?: number;
+    limit?: number;
+    waitingHuman?: boolean;
+    search?: string;
+    /**
+     * Recortes que só o produto conhece (tipo de financiamento, carteira, campanha) repassados
+     * crus ao backend dele. É o que evita o vocabulário de uma vertical virar campo fixo aqui:
+     * o pacote transporta o filtro sem saber o que ele significa.
+     */
+    filters?: Record<string, string | undefined>;
+}
+/**
+ * Página com o total, para a UI conseguir desenhar controles de paginação.
+ *
+ * `fetchConversations` devolve isto **ou** o array puro de antes: implementações existentes
+ * continuam válidas sem mudar uma linha, e quem precisa paginar passa a ter o total. Sem a união
+ * seria impossível saber se um retorno curto é a última página ou uma página cheia por acaso.
+ */
+interface ConversationPage {
+    conversations: ConversationSummary[];
+    total: number;
+}
+interface ListDocumentsParams {
+    search?: string;
+    page?: number;
+    /** Tamanho da página. Sem ele, `page` sozinho não define fatia nenhuma. */
+    limit?: number;
+    /** Origem do arquivo (`customer`, `agent`, `bot`…). O vocabulário é do host. */
+    source?: string;
+    sortDirection?: 'asc' | 'desc';
+}
+/** Arquivo na biblioteca da empresa: o mesmo da conversa, mais de qual conversa veio. */
+interface CompanyDocument extends ConversationDocument {
+    conversationId: string;
+}
+interface CompanyDocumentPage {
+    documents: CompanyDocument[];
+    total: number;
+}
+interface ConversationDocumentPage {
+    documents: ConversationDocument[];
+    total: number;
+}
+/**
+ * Template disponível para envio a partir da inbox. Distinto do `WhatsAppTemplateSummary` de
+ * `settings/`, e de propósito: aquele serve ao formulário que **edita** template e carrega o que
+ * a edição precisa (`shortId`, `variableCount`); este serve a quem só vai **escolher um para
+ * enviar**, e pedir os campos de edição obrigaria todo host a produzi-los sem uso.
+ */
+interface ConversationTemplate {
+    name: string;
+    language: string;
+    status: string;
+    category?: string;
+    bodyText?: string | null;
+}
+interface ConversationsApi {
+    fetchMessages(conversationId: string, params?: {
+        limit?: number;
+        before?: string;
+    }): Promise<MessagePayload[]>;
+    fetchConversations(params?: ListConversationsParams): Promise<ConversationSummary[] | ConversationPage>;
+    sendMessage(conversationId: string, text: string): Promise<MessagePayload>;
+    sendMedia(conversationId: string, data: {
+        base64: string;
+        mimeType: string;
+        filename: string;
+        caption?: string;
+    }): Promise<MessagePayload>;
+    /**
+     * `templateName` é opcional porque reabrir a janela é a operação, e escolher *qual* template a
+     * usa nem sempre é decisão da UI: backends que guardam um template padrão configurado só
+     * precisam do "reabra". Exigir o nome obrigaria toda inbox a listar templates antes de poder
+     * mandar o primeiro — e a listagem é `listTemplates?`, opcional.
+     */
+    sendTemplate(conversationId: string, data: {
+        templateName?: string;
+        languageCode?: string;
+        bodyParams?: string[];
+    }): Promise<void>;
+    markRead(conversationId: string): Promise<void>;
+    getContext(conversationId: string): Promise<Record<string, unknown>>;
+    getDocuments(conversationId: string, params?: ListDocumentsParams): Promise<ConversationDocument[] | ConversationDocumentPage>;
+    /**
+     * `disposition` decide entre abrir no navegador e baixar. É o backend que assina a URL e grava
+     * o `Content-Disposition` nela, então a escolha precisa viajar na chamada — depois de assinada
+     * não há como o cliente mudá-la. Ausente = o padrão do host.
+     */
+    getDocumentUrl(uploadId: string, disposition?: 'inline' | 'attachment'): Promise<string>;
+    /**
+     * Baixa vários arquivos num zip único.
+     *
+     * **Opcional por capacidade:** montar zip exige o host LER os bytes do storage, o que nem toda
+     * instalação faz — as que só assinam URL não conseguem. Ausente, o painel esconde a seleção em
+     * lote em vez de oferecer um botão que falha.
+     */
+    downloadDocumentsArchive?(conversationId: string, uploadIds: readonly string[]): Promise<Blob>;
+    /**
+     * Biblioteca de TODAS as conversas, para uma tela de Documentos fora do atendimento.
+     *
+     * Opcional por capacidade: host que só expõe anexo dentro da conversa não implementa, e o
+     * componente de biblioteca simplesmente não é usável — melhor que uma tela que sempre erra.
+     */
+    getAllDocuments?(params?: ListDocumentsParams): Promise<CompanyDocumentPage>;
+    getMediaProxyUrl(mediaId: string): Promise<{
+        mimeType: string;
+        data: string;
+    }>;
+    /**
+     * Operações de atendimento humano. **Opcionais por capacidade, não por descuido:** nem toda
+     * inbox tem fila humana — um canal só-bot, ou um chat de site sem operador, não sabe o que é
+     * assumir conversa. Quem não implementa não ganha o botão, em vez de ganhar um botão que
+     * estoura no clique. Os hooks devolvem `undefined` para a ação ausente, e é isso que a UI
+     * consulta para decidir se desenha a afordância.
+     */
+    takeover?(conversationId: string): Promise<void>;
+    release?(conversationId: string): Promise<void>;
+    /** Encerra o atendimento. Despedida, se houver, é decisão do host — o pacote não a inventa. */
+    finalize?(conversationId: string): Promise<void>;
+    markAllRead?(): Promise<void>;
+    listTemplates?(): Promise<ConversationTemplate[]>;
+    /**
+     * Transcrição completa gerada pelo servidor. Existe ao lado de `buildTranscriptText`, que monta
+     * a partir das mensagens já em memória: a tela costuma ter só a última página carregada, e
+     * exportar dali entregaria um recorte parcial com cara de histórico inteiro. Opcional porque
+     * nem todo backend expõe a rota — quem não tem continua usando o builder local.
+     */
+    exportTranscript?(conversationId: string): Promise<{
+        transcript: string;
+        filename: string;
+    }>;
+}
+/**
+ * Superfície mínima de stream que o pacote consome — exatamente o que `useConversationRealtime`
+ * usa: assinar 'message', desassinar e fechar. Deliberadamente estrutural em vez de
+ * `EventSource`: sem servidor HTTP não existe `EventSource`, e é isso que impediria alimentar a
+ * inbox com dados mockados em desenvolvimento. Um `EventSource` nativo satisfaz este tipo, então
+ * quem já implementa `SSEProvider` continua válido sem mudança.
+ */
+interface ConversationEventSource {
+    addEventListener(type: string, listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: string, listener: (event: MessageEvent) => void): void;
+    close(): void;
+}
+interface SSEProvider {
+    connectConversationStream(conversationId: string): ConversationEventSource;
+    connectGlobalStream(): ConversationEventSource;
+}
+interface ConversationSummary {
+    id: string;
+    /**
+     * @deprecated Use `contactId` com `channel`. Mantido obrigatório para não quebrar quem já
+     * consome; some quando o segundo canal entrar em produção.
+     */
+    whatsappNumber: string;
+    /** Identificador neutro do contato. Ausente = usa `whatsappNumber`. */
+    contactId?: string;
+    /** Ausente = `whatsapp`, o comportamento de antes desta mudança. */
+    channel?: ConversationChannel;
+    clientName?: string;
+    lastContent?: string;
+    lastDirection?: 'inbound' | 'outbound';
+    lastAt: string;
+    lastInboundAt: string | null;
+    mode: 'bot' | 'human';
+    assignedUserId: string | null;
+    waitingHuman: boolean;
+    unread: number;
+    currentState: string;
+    /**
+     * Atributos que só o produto conhece e desenha (tipo de financiamento, carteira, campanha). É a
+     * contraparte de leitura do `filters` de `ListConversationsParams`: o pacote transporta e nunca
+     * interpreta. Sem isto, exibir um selo próprio na linha exigiria o host manter uma segunda
+     * consulta paralela à mesma listagem — a implementação duplicada que o pacote existe para evitar.
+     */
+    attributes?: Record<string, string | undefined>;
+}
+interface ConversationDocument {
+    id: string;
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+    source: string;
+    linkedAt: string;
+}
+
+export { contactFlag as A, formatContactHandle as B, CHANNEL_CAPABILITIES as C, DEFAULT_CONVERSATION_CHANNEL as D, type FormatContactHandleParams as F, HANDLE_KIND as H, type ListConversationsParams as L, MediaRenderer as M, REOPEN_MECHANISM as R, type SSEProvider as S, CHANNEL_FILTER_ALL as a, CONVERSATION_CHANNEL as b, type ChannelCapabilities as c, type ChannelFilter as d, type ChannelFilterOption as e, type CompanyDocument as f, type CompanyDocumentPage as g, type ConversationChannel as h, type ConversationDocument as i, type ConversationDocumentPage as j, type ConversationEventSource as k, type ConversationPage as l, type ConversationSummary as m, type ConversationTemplate as n, type ConversationsApi as o, type ConversationsFeatures as p, type ConversationsTheme as q, type ConversationsUIConfig as r, type HandleKind as s, type ListDocumentsParams as t, type MediaRendererProps as u, type MessagePayload as v, type ReopenMechanism as w, type ResolveMediaUrl as x, capabilitiesOf as y, channelFiltersFor as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adatechnology/conversations-ui",
-  "version": "0.1.0-rc.4",
+  "version": "0.1.0-rc.6",
   "description": "WhatsApp conversation UI components — parametrizável por endpoint, tema e feature flags",
   "publishConfig": {
     "access": "public"
@@ -31,7 +31,7 @@
     "clsx": "^2.1.1",
     "lucide-react": "^1.21.0",
     "tailwind-merge": "^3.6.0",
-    "@adatechnology/meta-whatsapp-contracts": "0.2.0-rc.4"
+    "@adatechnology/meta-whatsapp-contracts": "0.2.0-rc.5"
   },
   "peerDependencies": {
     "react": "^18 || ^19",

package/src/Avatar.tsx

@@ -1,8 +1,18 @@
+export interface AvatarLabels {
+  /** Lido por leitor de tela quando não há nome nem imagem — a silhueta genérica. */
+  unnamedContact: string
+}
+
 export interface AvatarProps {
   name?: string | null
   avatarUrl?: string
   size?: 'sm' | 'md' | 'lg'
   className?: string
+  labels?: Partial<AvatarLabels>
+}
+
+export const DEFAULT_AVATAR_LABELS: AvatarLabels = {
+  unnamedContact: 'Contato sem nome',
 }
 
 const sizeClasses = {
@@ -36,8 +46,9 @@ function getBgColor(name: string | undefined | null): string {
 
 // Paridade com financiamento-imobiliario-bot/apps/web/src/components/Avatar.tsx —
 // mesmas iniciais (primeira+última letra), mesmo hash de cor, mesmas classes de tamanho.
-export function Avatar({ name, avatarUrl, size = 'md', className = '' }: AvatarProps) {
+export function Avatar({ name, avatarUrl, size = 'md', className = '', labels }: AvatarProps) {
   const sizeClass = sizeClasses[size]
+  const unnamedContactLabel = labels?.unnamedContact ?? DEFAULT_AVATAR_LABELS.unnamedContact
 
   if (avatarUrl) {
     return (
@@ -58,7 +69,7 @@ export function Avatar({ name, avatarUrl, size = 'md', className = '' }: AvatarP
       <div
         className={`${sizeClass} ${bgColor} rounded-full flex items-center justify-center text-white flex-shrink-0 ${className}`}
         role="img"
-        aria-label="Contato sem nome"
+        aria-label={unnamedContactLabel}
       >
         <svg viewBox="0 0 24 24" fill="currentColor" className="h-[60%] w-[60%]" aria-hidden>
           <path d="M12 12a5 5 0 1 0 0-10 5 5 0 0 0 0 10Zm0 2c-4.42 0-8 2.24-8 5v1h16v-1c0-2.76-3.58-5-8-5Z" />