evo360-types 1.3.411 → 1.3.413

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

@@ -0,0 +1,355 @@
+import type { FirestoreDocumentReference, IFireDoc } from "../shared";
+import type { QualificationFunnelLevel } from "../evo-crm/dic";
+export declare const EVO_CAMPAIGNS_APP = "evo-campaigns";
+export declare const CAMPAIGNS_COLLECTION = "campaigns";
+export declare const CAMPAIGN_BUCKETS_COLLECTION = "buckets";
+export declare const CAMPAIGN_RECIPIENTS_COLLECTION = "recipients";
+export declare const CAMPAIGN_CONVERSIONS_COLLECTION = "conversions";
+/** Subcollection on the lead doc (evo-crm) — history + frequency + attribution. */
+export declare const LEAD_CAMPAIGN_HISTORY_COLLECTION = "campaign-history";
+export declare const EvoCampaignsPermissions: {
+    readonly Read: "evo_campaigns_read";
+    readonly Manage: "evo_campaigns_manage";
+    readonly Export: "evo_campaigns_export";
+    readonly CostsView: "evo_campaigns_costs_view";
+};
+export type EvoCampaignsPermissions = (typeof EvoCampaignsPermissions)[keyof typeof EvoCampaignsPermissions];
+/** 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";
+/** Where a template variable gets its value from at send time. */
+export type CampaignVariableSource = "placeholder" | "fixed" | "csv_column" | "qr_link";
+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;
+}
+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;
+}
+/** 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;
+}
+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;
+}
+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;
+}
+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;
+    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;
+}
+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;
+}
+/** 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;
+}
+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>;
+}
+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;
+}
+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-campaigns/index.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvoCampaignsPermissions = exports.LEAD_CAMPAIGN_HISTORY_COLLECTION = exports.CAMPAIGN_CONVERSIONS_COLLECTION = exports.CAMPAIGN_RECIPIENTS_COLLECTION = exports.CAMPAIGN_BUCKETS_COLLECTION = exports.CAMPAIGNS_COLLECTION = exports.EVO_CAMPAIGNS_APP = void 0;
+// ======================================================
+// 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
+exports.EVO_CAMPAIGNS_APP = "evo-campaigns";
+exports.CAMPAIGNS_COLLECTION = "campaigns";
+exports.CAMPAIGN_BUCKETS_COLLECTION = "buckets";
+exports.CAMPAIGN_RECIPIENTS_COLLECTION = "recipients";
+exports.CAMPAIGN_CONVERSIONS_COLLECTION = "conversions";
+/** Subcollection on the lead doc (evo-crm) — history + frequency + attribution. */
+exports.LEAD_CAMPAIGN_HISTORY_COLLECTION = "campaign-history";
+// ----- Permissions (Q13)
+exports.EvoCampaignsPermissions = {
+    Read: "evo_campaigns_read",
+    Manage: "evo_campaigns_manage",
+    Export: "evo_campaigns_export",
+    CostsView: "evo_campaigns_costs_view",
+};