evo360-types 1.3.550 → 1.3.552

package/dist/index.d.ts

@@ -33,6 +33,7 @@ export * from "./types/nex-vendas";
 export * from "./types/nexus-webhooks";
 export * from "./types/evo-hub-ia";
 export * from "./types/evo-mcp";
+export * from "./types/evo-reports";
 export * from "./apps/shared/zod-schemas";
 export * from "./apps/evo-core/zod-schemas";
 export * from "./apps/evo-tenant/zod-schemas";

package/dist/index.js

@@ -50,6 +50,7 @@ __exportStar(require("./types/nex-vendas"), exports);
 __exportStar(require("./types/nexus-webhooks"), exports);
 __exportStar(require("./types/evo-hub-ia"), exports);
 __exportStar(require("./types/evo-mcp"), exports);
+__exportStar(require("./types/evo-reports"), exports);
 // zod schemas
 __exportStar(require("./apps/shared/zod-schemas"), exports);
 __exportStar(require("./apps/evo-core/zod-schemas"), exports);

package/dist/index.ts

@@ -34,6 +34,7 @@ export * from "./types/nex-vendas";
 export * from "./types/nexus-webhooks";
 export * from "./types/evo-hub-ia";
 export * from "./types/evo-mcp";
+export * from "./types/evo-reports";
 
 // zod schemas
 export * from "./apps/shared/zod-schemas";

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.552",
   "description": "HREVO360 Shared Types",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",