@erlancarreira/evolution-chat 0.1.0

package/bridge/index.d.cts

@@ -0,0 +1,245 @@
+type ChatMessageDirection = "visitor" | "owner";
+type ChatMessageStatus = "pending" | "sent" | "failed";
+type ChatSessionStatus = "active" | "closed" | "failed";
+/** Mensagem persistida (domínio). */
+interface ChatMessage {
+    id: string;
+    sessionId: string;
+    direction: ChatMessageDirection;
+    body: string;
+    status: ChatMessageStatus;
+    waMessageId: string | null;
+    createdAt: string;
+}
+/** Sessão de chat (um grupo do WhatsApp por visitante). */
+interface ChatSession {
+    id: string;
+    code: string;
+    realtimeToken: string;
+    visitorName: string;
+    visitorPhone: string;
+    visitorContact: string | null;
+    groupJid: string | null;
+    status: ChatSessionStatus;
+    createdAt: string;
+    lastMessageAt: string | null;
+}
+/**
+ * Configuração resolvida da plataforma. Montada pelo consumidor (LMS) a partir
+ * das settings e injetada no bridge via `setConfig`.
+ */
+interface ChatConfig {
+    enabled: boolean;
+    projectName: string;
+    platformNumber: string;
+    evolutionUrl: string;
+    instance: string;
+    apiKey: string;
+    welcome: string;
+    closeHours: number;
+    leaveOnClose: boolean;
+    webhookToken: string;
+}
+/** Evento de tempo real publicado no canal broadcast `chat:<realtimeToken>`. */
+type ChatEvent = {
+    type: "message";
+    message: ChatMessage;
+} | {
+    type: "session";
+    status: ChatSessionStatus;
+};
+/**
+ * Mensagem de entrada normalizada do webhook da Evolution, independente do
+ * formato bruto do payload.
+ */
+interface InboundMessage {
+    waMessageId: string;
+    jid: string;
+    fromMe: boolean;
+    senderJid: string | null;
+    text: string | null;
+    timestamp: number;
+    raw: unknown;
+}
+
+/** Persistência de sessões/mensagens vista pela bridge. */
+interface SessionStore {
+    createSession(input: {
+        code: string;
+        realtimeToken: string;
+        visitorName: string;
+        visitorPhone: string;
+        visitorContact?: string | null;
+        groupJid: string | null;
+        /** Hash não-reversível do IP (LGPD): usado por countRecentSessionsByIpHash. */
+        ipHash?: string | null;
+        /** User-Agent bruto da requisição (auditoria/forense; nunca exibido). */
+        userAgent?: string | null;
+    }): Promise<ChatSession>;
+    getSessionByToken(token: string): Promise<ChatSession | null>;
+    getSessionByGroupJid(jid: string): Promise<ChatSession | null>;
+    appendMessage(input: {
+        sessionId: string;
+        direction: ChatMessageDirection;
+        body: string;
+        waMessageId?: string | null;
+        status?: ChatMessageStatus;
+    }): Promise<ChatMessage>;
+    /** Atualiza o status de uma mensagem já persistida (pending → sent/failed). */
+    updateMessageStatus(id: string, status: ChatMessageStatus): Promise<void>;
+    listMessages(sessionId: string, afterIso?: string | null): Promise<ChatMessage[]>;
+    /**
+     * Busca uma mensagem já persistida pelo `waMessageId` dentro da sessão (`null` se não
+     * existir). Suporta a idempotência de reentrega do webhook: a Evolution reenvia a
+     * mesma mensagem quando devolvemos `handled:false`, e o bridge precisa reconhecer o
+     * duplicado em vez de anexar/publicar de novo.
+     */
+    findMessageByWaId(sessionId: string, waMessageId: string): Promise<ChatMessage | null>;
+    /** Registra o waMessageId de uma mensagem enviada por ESTA instância (dedupe de eco). */
+    registerSentMessageId(sessionId: string, waMessageId: string): Promise<void>;
+    isEcho(sessionId: string, waMessageId: string): Promise<boolean>;
+    touchSession(sessionId: string, atIso: string): Promise<void>;
+    setGroupJid(sessionId: string, groupJid: string): Promise<void>;
+    markStatus(sessionId: string, status: ChatSessionStatus, reason?: string): Promise<void>;
+    countRecentSessionsByIpHash(ipHash: string, windowMs: number): Promise<number>;
+}
+/** Publicação server-side de eventos para o canal de uma sessão (fire-and-forget). */
+interface RealtimeTransport {
+    publish(realtimeToken: string, event: ChatEvent): Promise<void>;
+}
+/**
+ * Assinatura client-side do mesmo canal (usada pelo widget — Task 9).
+ * `subscribe` devolve o unsubscribe; `onStatus` reporta conexão do transporte.
+ */
+interface RealtimeHandle {
+    subscribe(realtimeToken: string, onEvent: (e: ChatEvent) => void, onStatus?: (s: "open" | "closed") => void): () => void;
+}
+/** Injeção de relógio (testes determinísticos). */
+type Clock = () => Date;
+interface ChatLimiterResult {
+    success: boolean;
+}
+/** Rate limiter (chave → janela). Implementações: memória, Redis, … */
+type ChatLimiter = (key: string, limit: number, windowMs: number) => ChatLimiterResult | Promise<ChatLimiterResult>;
+/**
+ * Saída de ConversationRouter.decide — união discriminada por `action`: só o ramo
+ * "route" carrega sessão/direção/texto (obrigatórios), eliminando o risco de
+ * `decision.session` ser undefined em tempo de execução no consumidor (Task 6).
+ *
+ * Os `?: undefined` explícitos no 2º ramo preservam o typecheck de acessos sem
+ * narrowing (ex.: `d.session` → `ChatSession | undefined` em testes já escritos);
+ * após `if (d.action === "route")` os campos continuam obrigatórios.
+ */
+type RouterDecision = {
+    action: "route";
+    session: ChatSession;
+    direction: ChatMessageDirection;
+    text: string;
+} | {
+    action: "echo" | "unknown_session" | "not_text" | "ignore";
+    session?: undefined;
+    direction?: undefined;
+    text?: undefined;
+};
+
+declare class ConversationRouter {
+    private readonly store;
+    constructor(store: Pick<SessionStore, "getSessionByGroupJid" | "isEcho">);
+    /**
+     * `now` faz parte do contrato para que a bridge propague uma única leitura de relógio
+     * por mensagem (touch/close/limite de horário nas próximas tasks); o router puro ainda
+     * não a consome.
+     */
+    decide(msg: InboundMessage, now: Date): Promise<RouterDecision>;
+}
+
+/** Primeira mensagem da conversa no grupo: destaca código, nome e quebra de linha. */
+declare function formatFirstMessage(code: string, name: string, text: string): string;
+/** Demais mensagens vindas do site: prefixo curto na mesma linha. */
+declare function formatFollowup(name: string, text: string): string;
+
+interface SendTextResult {
+    waMessageId: string;
+}
+interface CreateGroupResult {
+    groupJid: string;
+}
+interface EvolutionClient {
+    sendText(instance: string, number: string, text: string): Promise<SendTextResult>;
+    createGroup(instance: string, subject: string, participants: string[], description?: string): Promise<CreateGroupResult>;
+    leaveGroup(instance: string, groupJid: string): Promise<void>;
+    getConnectionState(instance: string): Promise<"open" | "connecting" | "close">;
+    connectQR(instance: string): Promise<{
+        qrBase64: string | null;
+        pairingCode: string | null;
+    }>;
+    setWebhook(instance: string, url: string, events: string[]): Promise<void>;
+}
+
+interface StartChatInput {
+    name: string;
+    phone: string;
+    message: string;
+    contact?: string | null;
+    ipHash?: string | null;
+    userAgent?: string | null;
+    honeypot?: string | null;
+}
+interface ChatBridgeDeps {
+    client: EvolutionClient;
+    store: SessionStore;
+    transport: RealtimeTransport;
+    /** Relógio injetável (testes determinísticos). Default: `() => new Date()`. */
+    clock?: Clock;
+}
+declare class ChatBridge {
+    private readonly deps;
+    private readonly router;
+    private readonly clock;
+    private config;
+    constructor(deps: ChatBridgeDeps);
+    /** Config injetada pelas rotas a cada request (setConfig → uso → getConfig). */
+    getConfig(): ChatConfig;
+    setConfig(cfg: ChatConfig): void;
+    /**
+     * Abre uma conversa: cria o grupo na Evolution, envia a primeira mensagem e persiste a
+     * sessão. Não publica no canal realtime — quem abriu o chat já tem a própria mensagem.
+     */
+    startChat(input: StartChatInput): Promise<{
+        session: ChatSession;
+        messages: ChatMessage[];
+    }>;
+    /** Relay site → grupo: persiste pending, envia, promove para sent (ou failed). */
+    sendVisitorMessage(token: string, text: string): Promise<ChatMessage>;
+    /**
+     * Entrada do webhook da Evolution. NUNCA lança: um 500 aqui faz a Evolution reenviar
+     * a mesma mensagem para sempre. Qualquer problema é logado e devolvido como não tratado.
+     */
+    handleWebhook(payload: unknown): Promise<{
+        handled: boolean;
+    }>;
+    /** Replay para o widget: sessão por token + mensagens (opcionalmente após um ISO). */
+    history(token: string, afterIso?: string | null): Promise<{
+        session: ChatSession | null;
+        messages: ChatMessage[];
+    }>;
+    /**
+     * createGroup com uma única retratação: um participante inválido (ex.: o número do
+     * visitante, vindo de um formulário web) não pode abortar o atendimento — a segunda
+     * tentativa cria o grupo só com a plataforma, o número que controlamos e é válido.
+     *
+     * Atenção (F1): createGroup NÃO é idempotente. Se a 1ª chamada criar o grupo e o erro
+     * observado for um timeout, a retratação pode orfanar um segundo grupo; a compensação
+     * (limpeza/reconciliação de órfãos) é preocupação das Tasks 7/8, não deste fix.
+     */
+    private createGroupWithRetry;
+}
+
+type ChatErrorCode = "invalid_input" | "rate_limited" | "group_create_failed" | "send_failed" | "session_not_found" | "session_closed" | "disabled" | "unauthorized" | "store_error" | "webhook_invalid";
+declare class ChatError extends Error {
+    readonly code: ChatErrorCode;
+    readonly cause?: unknown;
+    constructor(message: string, code: ChatErrorCode, cause?: unknown);
+}
+
+export { ChatBridge, type ChatBridgeDeps, ChatError, type ChatErrorCode, type ChatEvent, type ChatLimiter, type ChatLimiterResult, type ChatMessage, type ChatMessageDirection, type ChatMessageStatus, type ChatSession, type ChatSessionStatus, type Clock, ConversationRouter, type RealtimeHandle, type RealtimeTransport, type RouterDecision, type SessionStore, type StartChatInput, formatFirstMessage, formatFollowup };

package/bridge/index.d.ts

@@ -0,0 +1,245 @@
+type ChatMessageDirection = "visitor" | "owner";
+type ChatMessageStatus = "pending" | "sent" | "failed";
+type ChatSessionStatus = "active" | "closed" | "failed";
+/** Mensagem persistida (domínio). */
+interface ChatMessage {
+    id: string;
+    sessionId: string;
+    direction: ChatMessageDirection;
+    body: string;
+    status: ChatMessageStatus;
+    waMessageId: string | null;
+    createdAt: string;
+}
+/** Sessão de chat (um grupo do WhatsApp por visitante). */
+interface ChatSession {
+    id: string;
+    code: string;
+    realtimeToken: string;
+    visitorName: string;
+    visitorPhone: string;
+    visitorContact: string | null;
+    groupJid: string | null;
+    status: ChatSessionStatus;
+    createdAt: string;
+    lastMessageAt: string | null;
+}
+/**
+ * Configuração resolvida da plataforma. Montada pelo consumidor (LMS) a partir
+ * das settings e injetada no bridge via `setConfig`.
+ */
+interface ChatConfig {
+    enabled: boolean;
+    projectName: string;
+    platformNumber: string;
+    evolutionUrl: string;
+    instance: string;
+    apiKey: string;
+    welcome: string;
+    closeHours: number;
+    leaveOnClose: boolean;
+    webhookToken: string;
+}
+/** Evento de tempo real publicado no canal broadcast `chat:<realtimeToken>`. */
+type ChatEvent = {
+    type: "message";
+    message: ChatMessage;
+} | {
+    type: "session";
+    status: ChatSessionStatus;
+};
+/**
+ * Mensagem de entrada normalizada do webhook da Evolution, independente do
+ * formato bruto do payload.
+ */
+interface InboundMessage {
+    waMessageId: string;
+    jid: string;
+    fromMe: boolean;
+    senderJid: string | null;
+    text: string | null;
+    timestamp: number;
+    raw: unknown;
+}
+
+/** Persistência de sessões/mensagens vista pela bridge. */
+interface SessionStore {
+    createSession(input: {
+        code: string;
+        realtimeToken: string;
+        visitorName: string;
+        visitorPhone: string;
+        visitorContact?: string | null;
+        groupJid: string | null;
+        /** Hash não-reversível do IP (LGPD): usado por countRecentSessionsByIpHash. */
+        ipHash?: string | null;
+        /** User-Agent bruto da requisição (auditoria/forense; nunca exibido). */
+        userAgent?: string | null;
+    }): Promise<ChatSession>;
+    getSessionByToken(token: string): Promise<ChatSession | null>;
+    getSessionByGroupJid(jid: string): Promise<ChatSession | null>;
+    appendMessage(input: {
+        sessionId: string;
+        direction: ChatMessageDirection;
+        body: string;
+        waMessageId?: string | null;
+        status?: ChatMessageStatus;
+    }): Promise<ChatMessage>;
+    /** Atualiza o status de uma mensagem já persistida (pending → sent/failed). */
+    updateMessageStatus(id: string, status: ChatMessageStatus): Promise<void>;
+    listMessages(sessionId: string, afterIso?: string | null): Promise<ChatMessage[]>;
+    /**
+     * Busca uma mensagem já persistida pelo `waMessageId` dentro da sessão (`null` se não
+     * existir). Suporta a idempotência de reentrega do webhook: a Evolution reenvia a
+     * mesma mensagem quando devolvemos `handled:false`, e o bridge precisa reconhecer o
+     * duplicado em vez de anexar/publicar de novo.
+     */
+    findMessageByWaId(sessionId: string, waMessageId: string): Promise<ChatMessage | null>;
+    /** Registra o waMessageId de uma mensagem enviada por ESTA instância (dedupe de eco). */
+    registerSentMessageId(sessionId: string, waMessageId: string): Promise<void>;
+    isEcho(sessionId: string, waMessageId: string): Promise<boolean>;
+    touchSession(sessionId: string, atIso: string): Promise<void>;
+    setGroupJid(sessionId: string, groupJid: string): Promise<void>;
+    markStatus(sessionId: string, status: ChatSessionStatus, reason?: string): Promise<void>;
+    countRecentSessionsByIpHash(ipHash: string, windowMs: number): Promise<number>;
+}
+/** Publicação server-side de eventos para o canal de uma sessão (fire-and-forget). */
+interface RealtimeTransport {
+    publish(realtimeToken: string, event: ChatEvent): Promise<void>;
+}
+/**
+ * Assinatura client-side do mesmo canal (usada pelo widget — Task 9).
+ * `subscribe` devolve o unsubscribe; `onStatus` reporta conexão do transporte.
+ */
+interface RealtimeHandle {
+    subscribe(realtimeToken: string, onEvent: (e: ChatEvent) => void, onStatus?: (s: "open" | "closed") => void): () => void;
+}
+/** Injeção de relógio (testes determinísticos). */
+type Clock = () => Date;
+interface ChatLimiterResult {
+    success: boolean;
+}
+/** Rate limiter (chave → janela). Implementações: memória, Redis, … */
+type ChatLimiter = (key: string, limit: number, windowMs: number) => ChatLimiterResult | Promise<ChatLimiterResult>;
+/**
+ * Saída de ConversationRouter.decide — união discriminada por `action`: só o ramo
+ * "route" carrega sessão/direção/texto (obrigatórios), eliminando o risco de
+ * `decision.session` ser undefined em tempo de execução no consumidor (Task 6).
+ *
+ * Os `?: undefined` explícitos no 2º ramo preservam o typecheck de acessos sem
+ * narrowing (ex.: `d.session` → `ChatSession | undefined` em testes já escritos);
+ * após `if (d.action === "route")` os campos continuam obrigatórios.
+ */
+type RouterDecision = {
+    action: "route";
+    session: ChatSession;
+    direction: ChatMessageDirection;
+    text: string;
+} | {
+    action: "echo" | "unknown_session" | "not_text" | "ignore";
+    session?: undefined;
+    direction?: undefined;
+    text?: undefined;
+};
+
+declare class ConversationRouter {
+    private readonly store;
+    constructor(store: Pick<SessionStore, "getSessionByGroupJid" | "isEcho">);
+    /**
+     * `now` faz parte do contrato para que a bridge propague uma única leitura de relógio
+     * por mensagem (touch/close/limite de horário nas próximas tasks); o router puro ainda
+     * não a consome.
+     */
+    decide(msg: InboundMessage, now: Date): Promise<RouterDecision>;
+}
+
+/** Primeira mensagem da conversa no grupo: destaca código, nome e quebra de linha. */
+declare function formatFirstMessage(code: string, name: string, text: string): string;
+/** Demais mensagens vindas do site: prefixo curto na mesma linha. */
+declare function formatFollowup(name: string, text: string): string;
+
+interface SendTextResult {
+    waMessageId: string;
+}
+interface CreateGroupResult {
+    groupJid: string;
+}
+interface EvolutionClient {
+    sendText(instance: string, number: string, text: string): Promise<SendTextResult>;
+    createGroup(instance: string, subject: string, participants: string[], description?: string): Promise<CreateGroupResult>;
+    leaveGroup(instance: string, groupJid: string): Promise<void>;
+    getConnectionState(instance: string): Promise<"open" | "connecting" | "close">;
+    connectQR(instance: string): Promise<{
+        qrBase64: string | null;
+        pairingCode: string | null;
+    }>;
+    setWebhook(instance: string, url: string, events: string[]): Promise<void>;
+}
+
+interface StartChatInput {
+    name: string;
+    phone: string;
+    message: string;
+    contact?: string | null;
+    ipHash?: string | null;
+    userAgent?: string | null;
+    honeypot?: string | null;
+}
+interface ChatBridgeDeps {
+    client: EvolutionClient;
+    store: SessionStore;
+    transport: RealtimeTransport;
+    /** Relógio injetável (testes determinísticos). Default: `() => new Date()`. */
+    clock?: Clock;
+}
+declare class ChatBridge {
+    private readonly deps;
+    private readonly router;
+    private readonly clock;
+    private config;
+    constructor(deps: ChatBridgeDeps);
+    /** Config injetada pelas rotas a cada request (setConfig → uso → getConfig). */
+    getConfig(): ChatConfig;
+    setConfig(cfg: ChatConfig): void;
+    /**
+     * Abre uma conversa: cria o grupo na Evolution, envia a primeira mensagem e persiste a
+     * sessão. Não publica no canal realtime — quem abriu o chat já tem a própria mensagem.
+     */
+    startChat(input: StartChatInput): Promise<{
+        session: ChatSession;
+        messages: ChatMessage[];
+    }>;
+    /** Relay site → grupo: persiste pending, envia, promove para sent (ou failed). */
+    sendVisitorMessage(token: string, text: string): Promise<ChatMessage>;
+    /**
+     * Entrada do webhook da Evolution. NUNCA lança: um 500 aqui faz a Evolution reenviar
+     * a mesma mensagem para sempre. Qualquer problema é logado e devolvido como não tratado.
+     */
+    handleWebhook(payload: unknown): Promise<{
+        handled: boolean;
+    }>;
+    /** Replay para o widget: sessão por token + mensagens (opcionalmente após um ISO). */
+    history(token: string, afterIso?: string | null): Promise<{
+        session: ChatSession | null;
+        messages: ChatMessage[];
+    }>;
+    /**
+     * createGroup com uma única retratação: um participante inválido (ex.: o número do
+     * visitante, vindo de um formulário web) não pode abortar o atendimento — a segunda
+     * tentativa cria o grupo só com a plataforma, o número que controlamos e é válido.
+     *
+     * Atenção (F1): createGroup NÃO é idempotente. Se a 1ª chamada criar o grupo e o erro
+     * observado for um timeout, a retratação pode orfanar um segundo grupo; a compensação
+     * (limpeza/reconciliação de órfãos) é preocupação das Tasks 7/8, não deste fix.
+     */
+    private createGroupWithRetry;
+}
+
+type ChatErrorCode = "invalid_input" | "rate_limited" | "group_create_failed" | "send_failed" | "session_not_found" | "session_closed" | "disabled" | "unauthorized" | "store_error" | "webhook_invalid";
+declare class ChatError extends Error {
+    readonly code: ChatErrorCode;
+    readonly cause?: unknown;
+    constructor(message: string, code: ChatErrorCode, cause?: unknown);
+}
+
+export { ChatBridge, type ChatBridgeDeps, ChatError, type ChatErrorCode, type ChatEvent, type ChatLimiter, type ChatLimiterResult, type ChatMessage, type ChatMessageDirection, type ChatMessageStatus, type ChatSession, type ChatSessionStatus, type Clock, ConversationRouter, type RealtimeHandle, type RealtimeTransport, type RouterDecision, type SessionStore, type StartChatInput, formatFirstMessage, formatFollowup };