evo360-types 1.3.550 → 1.3.555

package/dist/types/evo-hub-ia/v1/index.d.ts

@@ -180,3 +180,40 @@ export interface IHubiaRule {
     /** Passthrough no schema zod — campos custom são preservados. */
     [key: string]: unknown;
 }
+/** Disposição de fechamento publicada no evento. */
+export interface IHubiaTicketClosedEventClose {
+    code?: string | null;
+    name?: string | null;
+    type_code?: string | null;
+    type_name?: string | null;
+    /** Observação livre do operador ao fechar (novo em feat-154). */
+    notes?: string | null;
+    [key: string]: unknown;
+}
+/** Payload do tópico `hubia-ticket-closed`. Publicado pelo bridge do hub-omni
+ *  (`provider: 'hub-waba'`) e pelo do Chatbee (`provider: 'chatbee'`).
+ *  Consumidores: o handler de regras `ticket_closed` da HubIA e o pipeline do
+ *  CSQ 2.0. Os campos novos da feat-154 são opcionais porque o bridge do
+ *  Chatbee continua publicando o shape antigo. */
+export interface IHubiaTicketClosedEvent {
+    tenant: string;
+    evoChatChannelId: string;
+    contactId: string;
+    departmentId?: string | null;
+    close: IHubiaTicketClosedEventClose;
+    /** ISO 8601 do instante de fechamento. */
+    closedAt: string;
+    /** Idempotência do consumidor de regras. */
+    idempotencyKey?: string | null;
+    /** `${ticketId}:${closedAt ISO}` — chave do ledger `runs/{eventId}` do CSQ. */
+    event_id?: string;
+    /** Versão do payload. 1 = feat-154. */
+    schema_version?: number;
+    ticketId?: string | null;
+    threadId?: string | null;
+    leadId?: string | null;
+    closedByUserId?: string | null;
+    /** Quem fechou. O CSQ só avalia `human`. */
+    actorType?: "human" | "system" | "automation";
+    [key: string]: unknown;
+}

package/dist/types/evo-hub-ia/v1/index.ts

@@ -230,3 +230,47 @@ export interface IHubiaRule {
   /** Passthrough no schema zod — campos custom são preservados. */
   [key: string]: unknown;
 }
+
+// ── Evento `hubia-ticket-closed` (feat-154) ──
+
+/** Disposição de fechamento publicada no evento. */
+export interface IHubiaTicketClosedEventClose {
+  code?: string | null;
+  name?: string | null;
+  type_code?: string | null;
+  type_name?: string | null;
+  /** Observação livre do operador ao fechar (novo em feat-154). */
+  notes?: string | null;
+  [key: string]: unknown;
+}
+
+/** Payload do tópico `hubia-ticket-closed`. Publicado pelo bridge do hub-omni
+ *  (`provider: 'hub-waba'`) e pelo do Chatbee (`provider: 'chatbee'`).
+ *  Consumidores: o handler de regras `ticket_closed` da HubIA e o pipeline do
+ *  CSQ 2.0. Os campos novos da feat-154 são opcionais porque o bridge do
+ *  Chatbee continua publicando o shape antigo. */
+export interface IHubiaTicketClosedEvent {
+  tenant: string;
+  evoChatChannelId: string;
+  contactId: string;
+  departmentId?: string | null;
+  close: IHubiaTicketClosedEventClose;
+  /** ISO 8601 do instante de fechamento. */
+  closedAt: string;
+  /** Idempotência do consumidor de regras. */
+  idempotencyKey?: string | null;
+
+  // ── novos em feat-154 (opcionais) ──
+  /** `${ticketId}:${closedAt ISO}` — chave do ledger `runs/{eventId}` do CSQ. */
+  event_id?: string;
+  /** Versão do payload. 1 = feat-154. */
+  schema_version?: number;
+  ticketId?: string | null;
+  threadId?: string | null;
+  leadId?: string | null;
+  closedByUserId?: string | null;
+  /** Quem fechou. O CSQ só avalia `human`. */
+  actorType?: "human" | "system" | "automation";
+
+  [key: string]: unknown;
+}

package/dist/types/evo-reports/index.d.ts

@@ -0,0 +1,100 @@
+export declare const EvoReportsPermissions: {
+    readonly Read: "evo_reports_read";
+};
+export type EvoReportsPermissions = (typeof EvoReportsPermissions)[keyof typeof EvoReportsPermissions];
+/**
+ * Quais séries o tenant pode exibir na janela consultada.
+ *
+ * `true` quando existe canal ativo OU houve uso no período — desligar o canal
+ * em outubro não pode apagar as barras de agosto.
+ *
+ * Consequência no resto do contrato: capability ligada e mês sem linha vale
+ * `0`; só capability desligada vale `null`.
+ */
+export interface IUsageCapabilities {
+    sms: boolean;
+    email: boolean;
+    llm: boolean;
+    /**
+     * Data (YYYY-MM-DD) a partir da qual existe medição de LLM — o publisher não
+     * tem backfill. `null` antes do deploy dele. A série de IA não é desenhada
+     * antes dessa data: ausência de medição não é consumo zero.
+     */
+    llm_since: string | null;
+}
+/**
+ * Uma linha da abertura por departamento dentro de um mês.
+ *
+ * `department_id` vive em DOIS espaços de id: `fonte: 'chatbee'` usa o id
+ * numérico do Chatbee e `fonte: 'evo_chat'` usa o id do Firestore. Os dois
+ * espaços não se cruzam, por isso `fonte` faz parte da chave da linha — agrupar
+ * só por `department_id` mistura departamentos diferentes.
+ */
+export interface IUsageDepartmentRow {
+    fonte: "chatbee" | "evo_chat";
+    department_id: string | null;
+    department_name: string | null;
+    atendidos: number;
+    ativados: number;
+}
+export interface IUsageContacts {
+    /** Contatos únicos no tenant no mês (dedup por pessoa, tenant-wide). */
+    atendidos: number;
+    /** Contatos únicos ativados no tenant no mês. */
+    ativados: number;
+    /**
+     * Abertura por departamento, com contatos únicos DENTRO de cada departamento.
+     *
+     * A soma destas linhas PODE exceder `atendidos`/`ativados` do tenant: a mesma
+     * pessoa pode ser atendida em mais de um departamento no mesmo mês (medido:
+     * até 21%). São dois números diferentes de propósito — não é bug e não deve
+     * ser "corrigido" batendo um contra o outro.
+     */
+    por_departamento: IUsageDepartmentRow[];
+    /** Contatos por `contact_type` (ex.: `waba`, `instagram`). */
+    por_contact_type: Record<string, number>;
+}
+/**
+ * Notificações enviadas no mês.
+ *
+ * `null` = capability desligada, a série não é desenhada. `0` = capability
+ * ligada e sem envio no mês. Os dois significam coisas diferentes e não podem
+ * ser tratados como equivalentes na tela.
+ *
+ * `sms_enviados` conta MENSAGENS, não partes/segmentos — SMS longo é cobrado em
+ * 2+ partes pela Infobip. O rótulo é "SMS enviados", nunca "SMS cobrados".
+ */
+export interface IUsageNotifications {
+    sms_enviados: number | null;
+    emails_enviados: number | null;
+}
+/**
+ * Uso de LLM no mês. O bloco inteiro é `null` quando a capability está
+ * desligada; com ela ligada e sem uso no mês, os campos vêm zerados.
+ *
+ * `turnos` é a quantidade de executions que chamaram o LLM (não a soma de
+ * rounds do orchestrator). `tokens_total` = input + output + cache_write +
+ * cache_read.
+ */
+export interface IUsageLlm {
+    turnos: number;
+    tokens_total: number;
+    tokens_input: number;
+    tokens_output: number;
+    tokens_cache_write: number;
+    tokens_cache_read: number;
+}
+export interface IMonthlyUsageRow {
+    /** Primeiro dia do mês em UTC, `YYYY-MM-DD`. */
+    mes: string;
+    /** `true` apenas no mês corrente, que ainda não fechou. */
+    partial: boolean;
+    contatos: IUsageContacts;
+    notificacoes: IUsageNotifications;
+    ia: IUsageLlm | null;
+}
+export interface IMonthlyUsageResponse {
+    ok: true;
+    capabilities: IUsageCapabilities;
+    months: IMonthlyUsageRow[];
+}

package/dist/types/evo-reports/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvoReportsPermissions = void 0;
+// Permissão de leitura dos relatórios tenant-scoped: o relatório de atendimento
+// servido pela CF `evo_reports` e o registro de uso exibido no portal.
+exports.EvoReportsPermissions = {
+    Read: "evo_reports_read",
+};

package/dist/types/evo-reports/index.ts

@@ -0,0 +1,122 @@
+// Permissão de leitura dos relatórios tenant-scoped: o relatório de atendimento
+// servido pela CF `evo_reports` e o registro de uso exibido no portal.
+export const EvoReportsPermissions = {
+  Read: "evo_reports_read",
+} as const;
+
+export type EvoReportsPermissions =
+  (typeof EvoReportsPermissions)[keyof typeof EvoReportsPermissions];
+
+// ======================================================
+// evo-reports — contrato do registro de uso mensal
+//
+// Resposta de `GET /me/usage?months=N` (CF `evo_billing`).
+//
+// Este contrato é REGISTRO DE USO, não memória de cálculo de fatura: os números
+// saem das fontes operacionais (views de atendimento em BQ, eventos de
+// notificação e eventos de uso de LLM) e não são conciliados com o valor
+// cobrado. A ligação entre uso e cobrança é escopo da feat-150.
+// ======================================================
+
+/**
+ * Quais séries o tenant pode exibir na janela consultada.
+ *
+ * `true` quando existe canal ativo OU houve uso no período — desligar o canal
+ * em outubro não pode apagar as barras de agosto.
+ *
+ * Consequência no resto do contrato: capability ligada e mês sem linha vale
+ * `0`; só capability desligada vale `null`.
+ */
+export interface IUsageCapabilities {
+  sms: boolean;
+  email: boolean;
+  llm: boolean;
+  /**
+   * Data (YYYY-MM-DD) a partir da qual existe medição de LLM — o publisher não
+   * tem backfill. `null` antes do deploy dele. A série de IA não é desenhada
+   * antes dessa data: ausência de medição não é consumo zero.
+   */
+  llm_since: string | null;
+}
+
+/**
+ * Uma linha da abertura por departamento dentro de um mês.
+ *
+ * `department_id` vive em DOIS espaços de id: `fonte: 'chatbee'` usa o id
+ * numérico do Chatbee e `fonte: 'evo_chat'` usa o id do Firestore. Os dois
+ * espaços não se cruzam, por isso `fonte` faz parte da chave da linha — agrupar
+ * só por `department_id` mistura departamentos diferentes.
+ */
+export interface IUsageDepartmentRow {
+  fonte: "chatbee" | "evo_chat";
+  department_id: string | null;
+  department_name: string | null;
+  atendidos: number;
+  ativados: number;
+}
+
+export interface IUsageContacts {
+  /** Contatos únicos no tenant no mês (dedup por pessoa, tenant-wide). */
+  atendidos: number;
+  /** Contatos únicos ativados no tenant no mês. */
+  ativados: number;
+  /**
+   * Abertura por departamento, com contatos únicos DENTRO de cada departamento.
+   *
+   * A soma destas linhas PODE exceder `atendidos`/`ativados` do tenant: a mesma
+   * pessoa pode ser atendida em mais de um departamento no mesmo mês (medido:
+   * até 21%). São dois números diferentes de propósito — não é bug e não deve
+   * ser "corrigido" batendo um contra o outro.
+   */
+  por_departamento: IUsageDepartmentRow[];
+  /** Contatos por `contact_type` (ex.: `waba`, `instagram`). */
+  por_contact_type: Record<string, number>;
+}
+
+/**
+ * Notificações enviadas no mês.
+ *
+ * `null` = capability desligada, a série não é desenhada. `0` = capability
+ * ligada e sem envio no mês. Os dois significam coisas diferentes e não podem
+ * ser tratados como equivalentes na tela.
+ *
+ * `sms_enviados` conta MENSAGENS, não partes/segmentos — SMS longo é cobrado em
+ * 2+ partes pela Infobip. O rótulo é "SMS enviados", nunca "SMS cobrados".
+ */
+export interface IUsageNotifications {
+  sms_enviados: number | null;
+  emails_enviados: number | null;
+}
+
+/**
+ * Uso de LLM no mês. O bloco inteiro é `null` quando a capability está
+ * desligada; com ela ligada e sem uso no mês, os campos vêm zerados.
+ *
+ * `turnos` é a quantidade de executions que chamaram o LLM (não a soma de
+ * rounds do orchestrator). `tokens_total` = input + output + cache_write +
+ * cache_read.
+ */
+export interface IUsageLlm {
+  turnos: number;
+  tokens_total: number;
+  tokens_input: number;
+  tokens_output: number;
+  tokens_cache_write: number;
+  tokens_cache_read: number;
+}
+
+export interface IMonthlyUsageRow {
+  /** Primeiro dia do mês em UTC, `YYYY-MM-DD`. */
+  mes: string;
+  /** `true` apenas no mês corrente, que ainda não fechou. */
+  partial: boolean;
+  contatos: IUsageContacts;
+  notificacoes: IUsageNotifications;
+  ia: IUsageLlm | null;
+}
+
+export interface IMonthlyUsageResponse {
+  ok: true;
+  capabilities: IUsageCapabilities;
+  months: IMonthlyUsageRow[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evo360-types",
-  "version": "1.3.550",
+  "version": "1.3.555",
   "description": "HREVO360 Shared Types",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",