evo360-types 1.3.387 → 1.3.390

package/dist/types/evo-crm/lead/index.d.ts

@@ -29,6 +29,42 @@ export interface ILeadDistChannel {
     ref?: FirestoreDocumentReference;
     updated_at?: Date | null;
 }
+/** Origem de aquisição do lead (feat-038) — base expansível p/ múltiplas
+ *  plataformas. v1 implementa só `type:'ctwa'` (Click-to-WhatsApp da Meta);
+ *  Google Ads / Instagram Direct / TikTok / site ficam para fast-follow. */
+export type LeadReferralType = "ctwa" | "instagram_direct" | "google_ads" | "tiktok" | "site" | "other";
+export interface ILeadReferralBase {
+    type: LeadReferralType;
+    captured_at?: Date | string | null;
+    source_url?: string | null;
+    label?: string | null;
+    raw?: Record<string, unknown> | null;
+}
+export interface ILeadReferralCTWA extends ILeadReferralBase {
+    type: "ctwa";
+    ad_id?: string | null;
+    source_type?: string | null;
+    headline?: string | null;
+    body?: string | null;
+    media_type?: string | null;
+    ctwa_clid?: string | null;
+}
+export type ILeadReferral = ILeadReferralCTWA;
+/** Estado da régua de reativação de lead (feat-037).
+ *  Mantido pelo subscriber `ticket_closed` (streak) e pela task
+ *  `lead_reactivation` (último disparo). Semântica do streak alinhada ao
+ *  `seminter_streak` do feat-018: incrementa a cada fechamento "sem interação"
+ *  consecutivo e zera em fechamento não-seminter / resposta do lead. */
+export interface ILeadReactivation {
+    /** Fechamentos "sem interação" (`seminter`) consecutivos sem reengajamento.
+     *  Usado como teto anti-spam na condição da regra
+     *  (`lead.reactivation.no_interaction_streak < N`). */
+    no_interaction_streak?: number;
+    /** Quando ocorreu o último fechamento "sem interação" que incrementou o streak. */
+    last_no_interaction_close_at?: Date | null;
+    /** Quando a última mensagem de reativação foi efetivamente enviada. */
+    last_reactivation_at?: Date | null;
+}
 export interface ILead extends IProfile {
     external_id?: string | null;
     social_id?: string | null;
@@ -42,6 +78,10 @@ export interface ILead extends IProfile {
     tags?: ITag[] | null;
     userRef?: FirestoreDocumentReference;
     ctwa_clid?: string | null;
+    /**
+     * @deprecated A ESCRITA foi substituída por `acquisition_sources[]` (feat-038).
+     * Tipo mantido para leitura de leads antigos; sem backfill.
+     */
     ctwa_referral?: {
         source_type?: string;
         source_id?: string;
@@ -51,5 +91,7 @@ export interface ILead extends IProfile {
         media_type?: string;
         captured_at?: Date | string | null;
     } | null;
+    acquisition_sources?: ILeadReferral[] | null;
+    reactivation?: ILeadReactivation | null;
     [key: string]: unknown;
 }

package/dist/types/evo-crm/lead/index.ts

@@ -44,6 +44,53 @@ export interface ILeadDistChannel {
   updated_at?: Date | null;
 }
 
+/** Origem de aquisição do lead (feat-038) — base expansível p/ múltiplas
+ *  plataformas. v1 implementa só `type:'ctwa'` (Click-to-WhatsApp da Meta);
+ *  Google Ads / Instagram Direct / TikTok / site ficam para fast-follow. */
+export type LeadReferralType =
+  | "ctwa" // Click-to-WhatsApp (Meta FB/IG → WhatsApp)  ← v1
+  | "instagram_direct" // ig.me ?ref=                                 ← futuro
+  | "google_ads" // gclid / token em ?text=                     ← futuro
+  | "tiktok"
+  | "site"
+  | "other"; // ← futuro
+
+export interface ILeadReferralBase {
+  type: LeadReferralType; // discriminador p/ o parser
+  captured_at?: Date | string | null; // 1º toque desta origem (idioma do repo)
+  source_url?: string | null; // link clicável
+  label?: string | null; // rótulo de exibição (headline || ad_id || domínio)
+  raw?: Record<string, unknown> | null; // payload original lossless → re-parse futuro sem backfill
+}
+
+export interface ILeadReferralCTWA extends ILeadReferralBase {
+  type: "ctwa";
+  ad_id?: string | null; // referral.source_id
+  source_type?: string | null; // 'ad' | 'post'
+  headline?: string | null;
+  body?: string | null;
+  media_type?: string | null;
+  ctwa_clid?: string | null; // espelho; o de topo (CAPI/feat-034) permanece na raiz
+}
+
+export type ILeadReferral = ILeadReferralCTWA; // | ILeadReferralGoogleAds | ...
+
+/** Estado da régua de reativação de lead (feat-037).
+ *  Mantido pelo subscriber `ticket_closed` (streak) e pela task
+ *  `lead_reactivation` (último disparo). Semântica do streak alinhada ao
+ *  `seminter_streak` do feat-018: incrementa a cada fechamento "sem interação"
+ *  consecutivo e zera em fechamento não-seminter / resposta do lead. */
+export interface ILeadReactivation {
+  /** Fechamentos "sem interação" (`seminter`) consecutivos sem reengajamento.
+   *  Usado como teto anti-spam na condição da regra
+   *  (`lead.reactivation.no_interaction_streak < N`). */
+  no_interaction_streak?: number;
+  /** Quando ocorreu o último fechamento "sem interação" que incrementou o streak. */
+  last_no_interaction_close_at?: Date | null;
+  /** Quando a última mensagem de reativação foi efetivamente enviada. */
+  last_reactivation_at?: Date | null;
+}
+
 export interface ILead extends IProfile {
   external_id?: string | null; // ID externo do paciente
   social_id?: string | null; //CPF
@@ -58,6 +105,10 @@ export interface ILead extends IProfile {
   userRef?: FirestoreDocumentReference;
   // CTWA attribution (feat-034) — capturado do referral do 1º inbound vindo de anúncio Click-to-WhatsApp.
   ctwa_clid?: string | null;
+  /**
+   * @deprecated A ESCRITA foi substituída por `acquisition_sources[]` (feat-038).
+   * Tipo mantido para leitura de leads antigos; sem backfill.
+   */
   ctwa_referral?: {
     source_type?: string;
     source_id?: string;
@@ -67,5 +118,10 @@ export interface ILead extends IProfile {
     media_type?: string;
     captured_at?: Date | string | null;
   } | null;
+  // Origens de aquisição multi-touch (feat-038) — união discriminada por `type`.
+  // Substitui a escrita de `ctwa_referral`; `ctwa_clid` de topo permanece (CAPI).
+  acquisition_sources?: ILeadReferral[] | null;
+  // Régua de reativação (feat-037) — mantida pelo subscriber ticket_closed + task lead_reactivation.
+  reactivation?: ILeadReactivation | null;
   [key: string]: unknown; // index signature
 }

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

@@ -1,18 +1,25 @@
+import type { IExternalLink } from "../../shared";
 /** Fase de avaliação.
- *  - `pre_llm`  (v1.0) : avalia antes do orchestrator LLM.
- *  - `post_llm` (v1.1) : avalia depois do orchestrator e antes do envio
- *                        outbound (safety/governance).
+ *  - `pre_llm`       (v1.0) : avalia antes do orchestrator LLM.
+ *  - `post_llm`      (v1.1) : avalia depois do orchestrator e antes do envio
+ *                             outbound (safety/governance).
+ *  - `ticket_closed` (feat-037) : avalia quando um atendimento é fechado
+ *                             (v1: ATTENDANCE_CLOSED do Chatbee). Side-effects
+ *                             only — não há mensagem em trânsito; a regra
+ *                             apenas executa actions (ex: `create_task`).
  *  Ortogonal ao `when` (trigger): regras outbound (feat-027) usam
  *  `when=outbound_message + phase=pre_llm`. O par
- *  `outbound_message + post_llm` fica reservado p/ LLM-em-outbound futuro. */
-export type IHubiaRulePhase = "pre_llm" | "post_llm";
+ *  `outbound_message + post_llm` fica reservado p/ LLM-em-outbound futuro.
+ *  `ticket_closed` é a única phase em que phase e when andam juntos. */
+export type IHubiaRulePhase = "pre_llm" | "post_llm" | "ticket_closed";
 /** Gatilho que dispara a avaliação. Combinações válidas com `phase`
  *  (validado pelo superRefine de `zHubiaRuleSchema`):
- *  - `inbound_message`  + pre_llm  : mensagem do paciente (v1.0).
- *  - `llm_completed`    + post_llm : turno do LLM concluído (feat-026).
- *  - `outbound_message` + pre_llm  : mensagem enviada ao paciente, reativo
- *                                    pós-fato (feat-027). */
-export type IHubiaRuleTrigger = "inbound_message" | "llm_completed" | "outbound_message";
+ *  - `inbound_message`  + pre_llm       : mensagem do paciente (v1.0).
+ *  - `llm_completed`    + post_llm      : turno do LLM concluído (feat-026).
+ *  - `outbound_message` + pre_llm       : mensagem enviada ao paciente, reativo
+ *                                         pós-fato (feat-027).
+ *  - `ticket_closed`    + ticket_closed : atendimento fechado (feat-037). */
+export type IHubiaRuleTrigger = "inbound_message" | "llm_completed" | "outbound_message" | "ticket_closed";
 /** Desfecho do turno após a regra disparar:
  *  - `stop`                — finaliza turno; em pre_llm pula o LLM,
  *                            em post_llm bloqueia o envio outbound, em
@@ -102,10 +109,44 @@ export interface IHubiaRuleScope {
  *  `{{fact.path}}` resolvido em runtime pelo facts provider. */
 export interface IHubiaRuleAction {
     /** Nome de uma tool `category: 'action'` do evo-hubia-tools
-     *  (transfer_to_department, close_attendance, handoff_to_human, update_lead_tags, …). */
+     *  (transfer_to_department, close_attendance, handoff_to_human, update_lead_tags,
+     *   create_task, …). */
     tool: string;
     input?: Record<string, unknown>;
 }
+/** Input da action `create_task` (feat-037) — genérica: cria qualquer
+ *  `IAutoTask` (a reativação de lead é o 1º caso de uso). Disponível apenas na
+ *  phase `ticket_closed`. Todos os campos string/record aceitam templating
+ *  `{{fact.path}}` resolvido em runtime pelo facts provider.
+ *
+ *  Mapeamento p/ `IAutoTask` (no executor do cloud-functions):
+ *   - `handler`/`kind`/`payload`   → `auto.{handler,kind,payload}`.
+ *   - `delay_hours`                → `schedule.execute_at = now + delay_hours`.
+ *   - `send_window` (opcional)     → adia `execute_at` p/ a próxima abertura da
+ *                                    janela (via `isInsideSchedule`/`nowInTz`).
+ *   - `external_links` (opcional)  → `externalLinks[]` (além do `crm_lead`
+ *                                    derivado automaticamente do fact `lead.id`).
+ *   - `idempotency_key` (opcional) → `idempotency_key` (dedup de criação). */
+export interface ICreateTaskActionInput {
+    /** Handler lógico que processará a task (`TaskAutoHandler`). Define o tópico
+     *  PubSub do executor (`{handler}.execute_requests`). Ex: `lead_reactivation`. */
+    handler: string;
+    /** Sub-tipo do trabalho dentro do handler (`auto.kind`). Ex: `reactivate.send`. */
+    kind: string;
+    /** Payload específico do handler (`auto.payload`). Forma livre. */
+    payload?: Record<string, unknown>;
+    /** Atraso, em horas, a partir de agora para o `execute_at` da task. */
+    delay_hours: number;
+    /** Janela de horário opcional (por-regra). Quando presente, o `execute_at`
+     *  é adiado para a próxima abertura da janela. Reusa `IHubiaSchedule`
+     *  (mesma estrutura/editor das condições `in_schedule`). */
+    send_window?: IHubiaSchedule;
+    /** Links externos adicionais p/ a task (além do `crm_lead` automático). */
+    external_links?: IExternalLink[];
+    /** Chave de idempotência para a criação da task (evita duplicação em
+     *  entrega at-least-once do gatilho). */
+    idempotency_key?: string;
+}
 /** Uma regra completa. Mora em `binding.rules[]`. Avaliada pelo motor
  *  `evo-hubia-rules`. Reusa ToolRegistry para executar actions, herdando
  *  as policies já existentes (mode, requiresLinkedLead, etc.). */

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

@@ -5,24 +5,32 @@
 //
 // Ver docs em cloud-functions/docs/evo-hubia-rules/.
 
+import type { IExternalLink } from "../../shared";
+
 // ── Enums / Literals ──
 
 /** Fase de avaliação.
- *  - `pre_llm`  (v1.0) : avalia antes do orchestrator LLM.
- *  - `post_llm` (v1.1) : avalia depois do orchestrator e antes do envio
- *                        outbound (safety/governance).
+ *  - `pre_llm`       (v1.0) : avalia antes do orchestrator LLM.
+ *  - `post_llm`      (v1.1) : avalia depois do orchestrator e antes do envio
+ *                             outbound (safety/governance).
+ *  - `ticket_closed` (feat-037) : avalia quando um atendimento é fechado
+ *                             (v1: ATTENDANCE_CLOSED do Chatbee). Side-effects
+ *                             only — não há mensagem em trânsito; a regra
+ *                             apenas executa actions (ex: `create_task`).
  *  Ortogonal ao `when` (trigger): regras outbound (feat-027) usam
  *  `when=outbound_message + phase=pre_llm`. O par
- *  `outbound_message + post_llm` fica reservado p/ LLM-em-outbound futuro. */
-export type IHubiaRulePhase = "pre_llm" | "post_llm";
+ *  `outbound_message + post_llm` fica reservado p/ LLM-em-outbound futuro.
+ *  `ticket_closed` é a única phase em que phase e when andam juntos. */
+export type IHubiaRulePhase = "pre_llm" | "post_llm" | "ticket_closed";
 
 /** Gatilho que dispara a avaliação. Combinações válidas com `phase`
  *  (validado pelo superRefine de `zHubiaRuleSchema`):
- *  - `inbound_message`  + pre_llm  : mensagem do paciente (v1.0).
- *  - `llm_completed`    + post_llm : turno do LLM concluído (feat-026).
- *  - `outbound_message` + pre_llm  : mensagem enviada ao paciente, reativo
- *                                    pós-fato (feat-027). */
-export type IHubiaRuleTrigger = "inbound_message" | "llm_completed" | "outbound_message";
+ *  - `inbound_message`  + pre_llm       : mensagem do paciente (v1.0).
+ *  - `llm_completed`    + post_llm      : turno do LLM concluído (feat-026).
+ *  - `outbound_message` + pre_llm       : mensagem enviada ao paciente, reativo
+ *                                         pós-fato (feat-027).
+ *  - `ticket_closed`    + ticket_closed : atendimento fechado (feat-037). */
+export type IHubiaRuleTrigger = "inbound_message" | "llm_completed" | "outbound_message" | "ticket_closed";
 
 /** Desfecho do turno após a regra disparar:
  *  - `stop`                — finaliza turno; em pre_llm pula o LLM,
@@ -142,11 +150,46 @@ export interface IHubiaRuleScope {
  *  `{{fact.path}}` resolvido em runtime pelo facts provider. */
 export interface IHubiaRuleAction {
   /** Nome de uma tool `category: 'action'` do evo-hubia-tools
-   *  (transfer_to_department, close_attendance, handoff_to_human, update_lead_tags, …). */
+   *  (transfer_to_department, close_attendance, handoff_to_human, update_lead_tags,
+   *   create_task, …). */
   tool: string;
   input?: Record<string, unknown>;
 }
 
+/** Input da action `create_task` (feat-037) — genérica: cria qualquer
+ *  `IAutoTask` (a reativação de lead é o 1º caso de uso). Disponível apenas na
+ *  phase `ticket_closed`. Todos os campos string/record aceitam templating
+ *  `{{fact.path}}` resolvido em runtime pelo facts provider.
+ *
+ *  Mapeamento p/ `IAutoTask` (no executor do cloud-functions):
+ *   - `handler`/`kind`/`payload`   → `auto.{handler,kind,payload}`.
+ *   - `delay_hours`                → `schedule.execute_at = now + delay_hours`.
+ *   - `send_window` (opcional)     → adia `execute_at` p/ a próxima abertura da
+ *                                    janela (via `isInsideSchedule`/`nowInTz`).
+ *   - `external_links` (opcional)  → `externalLinks[]` (além do `crm_lead`
+ *                                    derivado automaticamente do fact `lead.id`).
+ *   - `idempotency_key` (opcional) → `idempotency_key` (dedup de criação). */
+export interface ICreateTaskActionInput {
+  /** Handler lógico que processará a task (`TaskAutoHandler`). Define o tópico
+   *  PubSub do executor (`{handler}.execute_requests`). Ex: `lead_reactivation`. */
+  handler: string;
+  /** Sub-tipo do trabalho dentro do handler (`auto.kind`). Ex: `reactivate.send`. */
+  kind: string;
+  /** Payload específico do handler (`auto.payload`). Forma livre. */
+  payload?: Record<string, unknown>;
+  /** Atraso, em horas, a partir de agora para o `execute_at` da task. */
+  delay_hours: number;
+  /** Janela de horário opcional (por-regra). Quando presente, o `execute_at`
+   *  é adiado para a próxima abertura da janela. Reusa `IHubiaSchedule`
+   *  (mesma estrutura/editor das condições `in_schedule`). */
+  send_window?: IHubiaSchedule;
+  /** Links externos adicionais p/ a task (além do `crm_lead` automático). */
+  external_links?: IExternalLink[];
+  /** Chave de idempotência para a criação da task (evita duplicação em
+   *  entrega at-least-once do gatilho). */
+  idempotency_key?: string;
+}
+
 // ── Main ──
 
 /** Uma regra completa. Mora em `binding.rules[]`. Avaliada pelo motor

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

@@ -52,6 +52,7 @@ export declare const TaskAutoHandlerEnum: {
     readonly Invoices: "invoices";
     readonly Webhook: "webhook";
     readonly Custom: "custom";
+    readonly LeadReactivation: "lead_reactivation";
 };
 export type TaskAutoHandler = (typeof TaskAutoHandlerEnum)[keyof typeof TaskAutoHandlerEnum];
 export declare const TaskRetryStrategyEnum: {

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

@@ -83,6 +83,10 @@ exports.TaskAutoHandlerEnum = {
     Invoices: "invoices",
     Webhook: "webhook",
     Custom: "custom",
+    // feat-037: handler que processa a régua de reativação de lead
+    // (gerado pela action `create_task` da phase `ticket_closed`).
+    // Tópico PubSub do executor: `lead_reactivation.execute_requests`.
+    LeadReactivation: "lead_reactivation",
 };
 // ----- Retry policy
 exports.TaskRetryStrategyEnum = {

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

@@ -94,6 +94,10 @@ export const TaskAutoHandlerEnum = {
   Invoices: "invoices",
   Webhook: "webhook",
   Custom: "custom",
+  // feat-037: handler que processa a régua de reativação de lead
+  // (gerado pela action `create_task` da phase `ticket_closed`).
+  // Tópico PubSub do executor: `lead_reactivation.execute_requests`.
+  LeadReactivation: "lead_reactivation",
 } as const;
 
 export type TaskAutoHandler =

package/package.json

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