evo360-types 1.3.409 → 1.3.413

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

@@ -0,0 +1,495 @@
+import type { FirestoreDocumentReference, IFireDoc } from "../shared";
+import type { QualificationFunnelLevel } from "../evo-crm/dic";
+
+// ======================================================
+// evo-campaigns (feat-081 — Hub Omni Campaigns)
+//
+// Campaign orchestrator: aggregate entity over audience enumeration,
+// multi-bucket dedup, pacing, ticket auto-close, conversion attribution
+// and exportable reporting. Firestore holds mutable state ONLY; business
+// events flow to BigQuery via evo_campaigns.events.
+//
+// Firestore (per tenant):
+// - App root:      /tenants/{t}/apps/evo-campaigns
+// - Campaigns:     /tenants/{t}/apps/evo-campaigns/campaigns/{campaignId}
+// - Buckets:       .../campaigns/{campaignId}/buckets/{bucketId}
+// - Recipients:    .../campaigns/{campaignId}/recipients/{recipientId}
+// - Conversions:   .../campaigns/{campaignId}/conversions/{leadId}
+// - Lead history:  /tenants/{t}/apps/evo-crm/leads/{leadId}/campaign-history/{campaignId}
+// ======================================================
+
+// ----- App + Firestore collections
+export const EVO_CAMPAIGNS_APP = "evo-campaigns";
+export const CAMPAIGNS_COLLECTION = "campaigns";
+export const CAMPAIGN_BUCKETS_COLLECTION = "buckets";
+export const CAMPAIGN_RECIPIENTS_COLLECTION = "recipients";
+export const CAMPAIGN_CONVERSIONS_COLLECTION = "conversions";
+/** Subcollection on the lead doc (evo-crm) — history + frequency + attribution. */
+export const LEAD_CAMPAIGN_HISTORY_COLLECTION = "campaign-history";
+
+// ----- Permissions (Q13)
+export const EvoCampaignsPermissions = {
+  Read: "evo_campaigns_read",
+  Manage: "evo_campaigns_manage",
+  Export: "evo_campaigns_export",
+  CostsView: "evo_campaigns_costs_view",
+} as const;
+
+export type EvoCampaignsPermissions =
+  (typeof EvoCampaignsPermissions)[keyof typeof EvoCampaignsPermissions];
+
+// ----- Shared value objects -------------------------------------------------
+
+/** Dictionary reference snapshot ({code,name}) — purpose, objective, close status... */
+export interface ICampaignCodeName {
+  code: string;
+  name: string;
+}
+
+/** Campaign FSM (§1.3). */
+export type CampaignStatus =
+  | "draft"
+  | "scheduled"
+  | "running"
+  | "paused"
+  | "finished"
+  | "canceled"
+  | "finished_error";
+
+/** Business classification of the campaign. */
+export type CampaignType =
+  | "conversion"
+  | "informative"
+  | "relationship"
+  | "operational"
+  | "promotional";
+
+/** Delivery channel of a campaign. */
+export type CampaignChannel = "whatsapp" | "email";
+
+// ----- Variable mapping + CTAs ----------------------------------------------
+
+/** Where a template variable gets its value from at send time. */
+export type CampaignVariableSource =
+  | "placeholder" // resolved by the placeholder engine (feat-055) via `token`
+  | "fixed" // literal `value`
+  | "csv_column" // pulled from the recipient's csv_variables by `column`
+  | "qr_link"; // a quick-reply /qr link for `cta_id`
+
+export interface ICampaignVariableMapping {
+  /** Template variable name/index this mapping fills. */
+  variable: string;
+  source: CampaignVariableSource;
+  /** source='placeholder': placeholder token (e.g. 'patient.first_name'). */
+  token?: string;
+  /** source='fixed': literal value. */
+  value?: string;
+  /** source='csv_column': column name in the uploaded CSV. */
+  column?: string;
+  /** source='qr_link': the CTA whose /qr link is injected. */
+  cta_id?: string;
+}
+
+export interface ICampaignCta {
+  cta_id: string;
+  label: string;
+  /** WhatsApp template button position (0,1,2...). */
+  button_index?: number;
+  /** Final destination for the /qr redirect. */
+  target_url?: string;
+}
+
+// ----- Pacing + ticket policy -----------------------------------------------
+
+export interface ICampaignPacingWindow {
+  /** 'HH:mm' local (tenant timezone). */
+  start: string;
+  /** 'HH:mm' local (tenant timezone). */
+  end: string;
+}
+
+export interface ICampaignPacing {
+  batch_size: number;
+  batch_interval_minutes: number;
+  daily_limit: number;
+  allowed_window: ICampaignPacingWindow;
+}
+
+export interface ICampaignTicketPolicy {
+  /** 'close' auto-closes the ticket after send (default, Q7); 'keep_open' leaves it. */
+  mode: "close" | "keep_open";
+  /** Status from the ticket-closes dic applied when mode='close'. */
+  close_status?: ICampaignCodeName;
+  /** Optional note stamped on the closed ticket. */
+  note?: string;
+}
+
+export interface ICampaignMedia {
+  /** 'image' | 'video' | 'document' — WhatsApp header media type. */
+  type: string;
+  gcs_path?: string;
+  url?: string;
+}
+
+// ----- Channel config -------------------------------------------------------
+
+/** Per-channel configuration (whatsapp/email) of a campaign. */
+export interface ICampaignChannelConfig {
+  /** evo-chat channel id (WABA channel or email channel). */
+  channel_id: string;
+  /** HSM/email template id. */
+  template_id: string;
+  /** WhatsApp: template language code (e.g. 'pt_BR'). */
+  template_language?: string;
+  /** WhatsApp: template category from introspection (MARKETING/UTILITY/AUTHENTICATION). */
+  template_category?: string;
+  variable_mappings: ICampaignVariableMapping[];
+  /** WhatsApp header media (when the template requires it). */
+  media?: ICampaignMedia;
+  ctas: ICampaignCta[];
+  /** Outbound department for the resulting ticket. */
+  department_id?: string;
+  ticket_policy: ICampaignTicketPolicy;
+  pacing: ICampaignPacing;
+  /** Email: overrides the template subject when set (F5). */
+  subject_override?: string;
+  /** Email: preheader text. */
+  preheader?: string;
+}
+
+// ----- Attribution / new-lead / frequency / schedule ------------------------
+
+export interface ICampaignAttribution {
+  /** Conversion window in days (default 30). */
+  window_days: number;
+  /** Conversion event key (default 'appointment_scheduled'). */
+  conversion_event: string;
+  /** statusBase values that count as a conversion (Q10 default). */
+  appointment_status_base_in: string[];
+  /** Minimum interaction required to attribute a conversion. */
+  requires: "delivery" | "click" | "reply";
+}
+
+export interface ICampaignNewLeadConfig {
+  dist_channel: ICampaignCodeName;
+  /** Optional (Q8) — no default; only stamped when explicitly selected. */
+  qualification?: {
+    code: string;
+    name: string;
+    funnelLevel: QualificationFunnelLevel;
+  } | null;
+  tags?: string[];
+}
+
+export interface ICampaignFrequency {
+  /** Minimum days since the last marketing touch (Q4, default 15). */
+  min_days: number;
+  /** Bypass the frequency check (requires evo_campaigns_manage, Q13). */
+  override: boolean;
+}
+
+export interface ICampaignSchedule {
+  mode: "immediate" | "scheduled";
+  scheduled_at?: Date | null;
+}
+
+// ----- Dispatch state / snapshots / counters --------------------------------
+
+export interface ICampaignSentToday {
+  /** 'yyyy-MM-dd' in tenant timezone. */
+  date: string;
+  per_channel: {
+    whatsapp?: number;
+    email?: number;
+  };
+}
+
+export interface ICampaignDispatchState {
+  cursor_doc_id?: string | null;
+  next_dispatch_task_id?: string | null;
+  sent_today?: ICampaignSentToday;
+  batches_dispatched?: number;
+}
+
+export type CampaignPrevalidationStatus = "approved" | "warnings" | "blocked";
+
+export interface ICampaignPrevalidation {
+  status: CampaignPrevalidationStatus;
+  errors: string[];
+  warnings: string[];
+  ran_at?: Date | null;
+}
+
+export interface ICampaignCostEstimate {
+  per_channel: Record<string, unknown>;
+  total?: number;
+  currency?: string;
+  tariff_version?: string;
+  estimated_at?: Date | null;
+}
+
+/** Per-channel delivery/engagement counters (increment/CAS). */
+export interface ICampaignChannelCounters {
+  pending?: number;
+  sent?: number;
+  delivered?: number;
+  read?: number;
+  failed?: number;
+  clicked?: number;
+  replied?: number;
+}
+
+export interface ICampaignCounters {
+  raw?: number;
+  unique?: number;
+  eligible?: number;
+  excluded_optout?: number;
+  excluded_frequency?: number;
+  excluded_invalid?: number;
+  excluded_no_channel?: number;
+  excluded_duplicate?: number;
+  per_channel?: {
+    whatsapp?: ICampaignChannelCounters;
+    email?: ICampaignChannelCounters;
+  };
+  converted?: number;
+}
+
+// ----- Campaign aggregate doc -----------------------------------------------
+
+export interface ICampaign extends IFireDoc {
+  name: string;
+  description?: string | null;
+  purpose: ICampaignCodeName;
+  objective: ICampaignCodeName;
+  campaign_type: CampaignType;
+  tags?: string[];
+
+  status: CampaignStatus;
+  /** true until the post-finished attribution window closes. */
+  attribution_open: boolean;
+  /** now + window_days, set when the campaign finishes. */
+  attribution_deadline?: Date | null;
+
+  attribution: ICampaignAttribution;
+
+  channels: {
+    whatsapp?: ICampaignChannelConfig;
+    email?: ICampaignChannelConfig;
+  };
+
+  new_lead_config?: ICampaignNewLeadConfig;
+  frequency: ICampaignFrequency;
+  schedule: ICampaignSchedule;
+
+  dispatch_state?: ICampaignDispatchState;
+  prevalidation?: ICampaignPrevalidation;
+  cost_estimate?: ICampaignCostEstimate;
+  counters?: ICampaignCounters;
+
+  // Audit (who/when per FSM transition)
+  created_by?: FirestoreDocumentReference;
+  updated_by?: FirestoreDocumentReference;
+  scheduled_by?: FirestoreDocumentReference;
+  started_by?: FirestoreDocumentReference;
+  paused_by?: FirestoreDocumentReference;
+  resumed_by?: FirestoreDocumentReference;
+  canceled_by?: FirestoreDocumentReference;
+  scheduled_at?: Date | null;
+  started_at?: Date | null;
+  paused_at?: Date | null;
+  resumed_at?: Date | null;
+  canceled_at?: Date | null;
+  finished_at?: Date | null;
+  cancel_reason?: string | null;
+  error_reason?: string | null;
+}
+
+// ----- Bucket ---------------------------------------------------------------
+
+export type CampaignBucketSourceType =
+  | "leads"
+  | "patients"
+  | "appointments"
+  | "csv";
+
+export interface ICampaignBucketCsvFile {
+  gcs_path: string;
+  original_name: string;
+  headers: string[];
+  row_count: number;
+  /** Invalid rows with reason, capped at 200 in the doc (full report in GCS). */
+  invalid_rows?: Array<{ row: number; reason: string; [key: string]: unknown }>;
+}
+
+export interface ICampaignBucketCounts {
+  raw?: number;
+  unique_contribution?: number;
+  eligible?: number;
+  invalid?: number;
+  opt_out?: number;
+  frequency_excluded?: number;
+  no_channel?: number;
+}
+
+export interface ICampaignBucket extends IFireDoc {
+  source_type: CampaignBucketSourceType;
+  label: string;
+  /** Shape depends on source_type (Algolia filters or CSV mapping). */
+  filters?: Record<string, unknown>;
+  csv_file?: ICampaignBucketCsvFile;
+  counts?: ICampaignBucketCounts;
+}
+
+// ----- Recipient ------------------------------------------------------------
+
+/** Flat field driving the batch queue (indexed). */
+export type RecipientDispatchState =
+  | "pending"
+  | "dispatched"
+  | "done"
+  | "excluded";
+
+/** Per-channel delivery status of a recipient (monotonic). */
+export type RecipientChannelStatus =
+  | "pending"
+  | "scheduled"
+  | "sent"
+  | "delivered"
+  | "read"
+  | "failed"
+  | "clicked"
+  | "replied";
+
+/** Aggregated, monotonic recipient status (Portuguese labels — FE display). */
+export type RecipientInteractionStatus =
+  | "pendente"
+  | "inelegivel"
+  | "agendado"
+  | "enviado"
+  | "entregue"
+  | "lido"
+  | "clicou"
+  | "respondeu"
+  | "convertido"
+  | "falhou"
+  | "optout"
+  | "cancelado";
+
+export interface ICampaignRecipientContact {
+  display_name?: string;
+  mobile?: string;
+  email?: string;
+  external_id?: string;
+}
+
+export interface ICampaignRecipientChannelState {
+  status: RecipientChannelStatus;
+  task_id?: string;
+  qr_action_ids?: string[];
+  sent_at?: Date | null;
+  delivered_at?: Date | null;
+  read_at?: Date | null;
+  clicked_at?: Date | null;
+  replied_at?: Date | null;
+  error?: string | null;
+}
+
+export interface ICampaignRecipientEligibility {
+  per_channel: {
+    whatsapp?: "eligible" | "excluded";
+    email?: "eligible" | "excluded";
+  };
+  /** channel -> exclusion reason. */
+  exclusion_reasons?: Record<string, string>;
+}
+
+export interface ICampaignRecipient extends IFireDoc {
+  lead_id?: string;
+  patient_id?: string;
+  is_new_lead: boolean;
+  contact: ICampaignRecipientContact;
+  bucket_ids: string[];
+  primary_bucket_id: string;
+  csv_variables?: Record<string, string>;
+  /** FLAT field for the batch queue (indexed). */
+  dispatch_state: RecipientDispatchState;
+  eligibility: ICampaignRecipientEligibility;
+  channels: {
+    whatsapp?: ICampaignRecipientChannelState;
+    email?: ICampaignRecipientChannelState;
+  };
+  interaction_status: RecipientInteractionStatus;
+  converted_at?: Date | null;
+  conversion_id?: string | null;
+}
+
+// ----- Conversion (docId = leadId) ------------------------------------------
+
+export type CampaignConversionSourceEntity =
+  | "appointment"
+  | "qr_action"
+  | "ticket"
+  | "message";
+
+export interface ICampaignConversion extends IFireDoc {
+  lead_id: string;
+  recipient_id: string;
+  conversion_event: string;
+  source_entity_type: CampaignConversionSourceEntity;
+  source_entity_id: string;
+  channel?: CampaignChannel;
+  cta_id?: string;
+  attributed_at: Date;
+  attribution_model: "last_campaign_in_window";
+  window_days: number;
+  metadata?: Record<string, unknown>;
+}
+
+// ----- Lead campaign-history entry ------------------------------------------
+// Path: /tenants/{t}/apps/evo-crm/leads/{leadId}/campaign-history/{campaignId}
+// Serves three consumers: lead history, 15d frequency check, attribution.
+
+export interface ILeadCampaignHistoryEntry extends IFireDoc {
+  campaign_id: string;
+  campaign_name: string;
+  /** e.g. 'marketing' — filters the frequency query (Q4). */
+  classification_level: string;
+  channels_sent: CampaignChannel[];
+  template_ids?: Record<string, string>;
+  bucket_ids?: string[];
+  first_sent_at?: Date | null;
+  last_sent_at?: Date | null;
+  delivered_at?: Date | null;
+  read_at?: Date | null;
+  clicked_at?: Date | null;
+  replied_at?: Date | null;
+  converted_at?: Date | null;
+  interaction_status: RecipientInteractionStatus;
+}
+
+// ----- Tariff dic item (Q6/Q12 — generic financial infra) -------------------
+// Path: /{base}/apps/evo-crm/dics/tariffs/{itemId}
+
+export interface ITariffItem {
+  code: string;
+  name: string;
+  description?: string;
+  /** 'messaging' | 'fees' | ... */
+  context: string;
+  channel?: string;
+  provider?: string;
+  /** ISO country code, e.g. 'BR'. */
+  country?: string;
+  /** 'marketing' | 'utility' | 'authentication'. */
+  category?: string;
+  currency: string;
+  calc_type: "fixed" | "percentage";
+  value: number;
+  /** For percentage: what the percent is applied over. */
+  percent_base?: string;
+  valid_from: Date;
+  valid_to?: Date | null;
+  active: boolean;
+  metadata?: Record<string, unknown>;
+}

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

@@ -32,7 +32,7 @@ export interface ILeadDistChannel {
 /** 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" | "meta_organic" | "referral" | "other";
+export type LeadReferralType = "ctwa" | "instagram_direct" | "google_ads" | "tiktok" | "site" | "meta_organic" | "referral" | "campaign" | "other";
 export interface ILeadReferralBase {
     type: LeadReferralType;
     captured_at?: Date | string | null;
@@ -61,7 +61,21 @@ export interface ILeadReferralGeneric extends ILeadReferralBase {
     type: "google_ads" | "tiktok" | "site" | "instagram_direct" | "meta_organic" | "referral" | "other";
     headline?: string | null;
 }
-export type ILeadReferral = ILeadReferralCTWA | ILeadReferralGeneric;
+/** Origem via campanha do Hub Omni (feat-081) — carimbada em `acquisition_sources`
+ *  quando o lead é criado/vinculado no provisionamento de destinatários da campanha. */
+export interface ILeadReferralCampaign extends ILeadReferralBase {
+    type: "campaign";
+    campaignId: string;
+    campaignName: string;
+    campaignType: string;
+    campaignObjective: string;
+    channel: string;
+    bucketId: string;
+    createdAt: Date | string | null;
+    importedFrom?: string | null;
+    initialCtaId?: string | null;
+}
+export type ILeadReferral = ILeadReferralCTWA | ILeadReferralGeneric | ILeadReferralCampaign;
 /** 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

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

@@ -55,6 +55,7 @@ export type LeadReferralType =
   | "site"
   | "meta_organic" // menção/URL orgânica de FB/IG (não-pago, sem referral)  ← feat-039
   | "referral" // indicação ("me indicaram", "amigo falou")              ← feat-039
+  | "campaign" // origem via campanha do Hub Omni (feat-081)             ← feat-081
   | "other"; // ← futuro
 
 export interface ILeadReferralBase {
@@ -95,7 +96,25 @@ export interface ILeadReferralGeneric extends ILeadReferralBase {
   headline?: string | null; // paridade com CTWA p/ o FE existente
 }
 
-export type ILeadReferral = ILeadReferralCTWA | ILeadReferralGeneric;
+/** Origem via campanha do Hub Omni (feat-081) — carimbada em `acquisition_sources`
+ *  quando o lead é criado/vinculado no provisionamento de destinatários da campanha. */
+export interface ILeadReferralCampaign extends ILeadReferralBase {
+  type: "campaign";
+  campaignId: string;
+  campaignName: string;
+  campaignType: string; // CampaignType da campanha (conversion/informative/...)
+  campaignObjective: string; // code do objetivo (dic)
+  channel: string; // 'whatsapp' | 'email' — canal que originou o toque
+  bucketId: string; // bucket primário do destinatário
+  createdAt: Date | string | null;
+  importedFrom?: string | null; // 'csv' | 'leads' | 'patients' | 'appointments'
+  initialCtaId?: string | null; // CTA inicial associado, quando houver
+}
+
+export type ILeadReferral =
+  | ILeadReferralCTWA
+  | ILeadReferralGeneric
+  | ILeadReferralCampaign;
 
 /** Estado da régua de reativação de lead (feat-037).
  *  Mantido pelo subscriber `ticket_closed` (streak) e pela task

package/dist/types/hub-automation/index.d.ts

@@ -29,10 +29,24 @@ export interface IAutomationAppointmentSelection {
         status_in?: string[];
         status_base_in?: string[];
         appointment_type_not_in?: string[];
+        professional_names?: string[];
+        procedure_names?: string[];
+        insurance_names?: string[];
+        address_names?: string[];
+        payment_status_in?: string[];
     };
 }
 export type IAutomationSelection = IAutomationAppointmentSelection;
-export declare const AUTOMATION_APPOINTMENT_FACTS: readonly ["appointment.status", "appointment.status_base", "appointment.appointment_type", "appointment.appointment_base_type", "appointment.appointment_mode", "appointment.professional_id", "appointment.procedure_ids", "appointment.payment_status", "appointment.calendar_id"];
+export interface IAutomationFilterValues {
+    professionals: string[];
+    procedures: string[];
+    insurances: string[];
+    addresses: string[];
+    statuses: string[];
+    status_bases: string[];
+    appointment_types: string[];
+}
+export declare const AUTOMATION_APPOINTMENT_FACTS: readonly ["appointment.status", "appointment.status_base", "appointment.appointment_type", "appointment.appointment_base_type", "appointment.appointment_mode", "appointment.professional_id", "appointment.procedure_ids", "appointment.professional_name", "appointment.procedure_names", "appointment.insurance_name", "appointment.address_name", "appointment.payment_status", "appointment.calendar_id"];
 export type AutomationAppointmentFact = (typeof AUTOMATION_APPOINTMENT_FACTS)[number];
 export type AutomationFact = AutomationAppointmentFact;
 export declare const AutomationOperatorEnum: {
@@ -67,6 +81,9 @@ export type IAutomationExecuteAt = {
     rule: "send_at_local";
     time: string;
     base: "target_date" | "run_date";
+} | {
+    rule: "relative_to_appointment";
+    offset_minutes: number;
 };
 export interface IAutomationAutoTaskOutput {
     type: "auto_task";

package/dist/types/hub-automation/index.js

@@ -47,9 +47,16 @@ exports.AUTOMATION_APPOINTMENT_FACTS = [
     "appointment.appointment_base_type",
     // 'telemedicine' | 'in_person'
     "appointment.appointment_mode",
-    // Derived from professional.professionalRef.id
+    // Derived from professional.professionalRef.id. On external calendars the
+    // reliable value is the name (Q21) — professional_id kept for internal.
     "appointment.professional_id",
     "appointment.procedure_ids",
+    // Embed-sourced names (Q20-C passthrough); reliable across adapters.
+    "appointment.professional_name",
+    // string[] — matches if ANY procedure name matches.
+    "appointment.procedure_names",
+    "appointment.insurance_name",
+    "appointment.address_name",
     "appointment.payment_status",
     "appointment.calendar_id",
 ];