evo360-types 1.3.469 → 1.3.474

package/dist/apps/evo-campaigns/zod-schemas.js

@@ -28,17 +28,27 @@ exports.zCampaignTypeSchema = zod_1.z.enum([
     "promotional",
 ]);
 exports.zCampaignChannelSchema = zod_1.z.enum(["whatsapp", "email"]);
+/** ADDITIVE ONLY — mirrors CampaignVariableSource in types/evo-campaigns/index.ts.
+ *  This list is SEPARATE from the TS union; dropping a value here rejects channel
+ *  configs already persisted in Firestore. */
 exports.zCampaignVariableSourceSchema = zod_1.z.enum([
     "placeholder",
     "fixed",
     "csv_column",
     "qr_link",
+    // E-MAIL ONLY (F3.2): resolves to channels.email.media.url.
+    "campaign_media",
 ]);
+/** ADDITIVE ONLY. The FE parses every recipient through this enum; a value written
+ *  to Firestore but missing here makes it drop the WHOLE recipient document. */
 exports.zRecipientDispatchStateSchema = zod_1.z.enum([
     "pending",
     "dispatched",
     "done",
     "excluded",
+    // Declared in RecipientDispatchState but with no writer yet — listed here FIRST so
+    // whoever starts writing it doesn't take the FE's recipient list down with them.
+    "canceled",
 ]);
 exports.zRecipientChannelStatusSchema = zod_1.z.enum([
     "pending",
@@ -194,10 +204,15 @@ exports.zCampaignSchema = zod_schemas_1.zFireDocSchema
     new_lead_config: exports.zCampaignNewLeadConfigSchema.optional(),
     frequency: exports.zCampaignFrequencySchema,
     schedule: exports.zCampaignScheduleSchema,
+    // Backend-owned state maps: declared so the field is documented, deliberately
+    // left unvalidated. They gain fields slice by slice and the FE reads them
+    // defensively — a structural schema here would drop the whole campaign doc the
+    // first time the backend writes a counter the FE's evo-types doesn't know yet.
     dispatch_state: zod_1.z.record(zod_1.z.unknown()).optional(),
     prevalidation: zod_1.z.record(zod_1.z.unknown()).optional(),
     cost_estimate: zod_1.z.record(zod_1.z.unknown()).optional(),
     counters: zod_1.z.record(zod_1.z.unknown()).optional(),
+    last_materialize: zod_1.z.record(zod_1.z.unknown()).optional(),
 })
     .passthrough();
 // ----- Bucket doc -----------------------------------------------------------
@@ -234,6 +249,10 @@ exports.zCampaignRecipientSchema = zod_schemas_1.zFireDocSchema
     primary_bucket_id: zod_1.z.string(),
     csv_variables: zod_1.z.record(zod_1.z.string()).optional(),
     dispatch_state: exports.zRecipientDispatchStateSchema,
+    /** Absent (field-deleted), not false, once a manual exclusion is restored. */
+    manual_excluded: zod_1.z.boolean().optional(),
+    // Same reasoning as the campaign state maps: unvalidated on purpose, so a new
+    // exclusion reason or channel field never costs the FE the whole recipient row.
     eligibility: zod_1.z.record(zod_1.z.unknown()),
     channels: zod_1.z.record(zod_1.z.unknown()),
     interaction_status: exports.zRecipientInteractionStatusSchema,

package/dist/apps/evo-campaigns/zod-schemas.ts

@@ -31,18 +31,28 @@ export const zCampaignTypeSchema = z.enum([
 
 export const zCampaignChannelSchema = z.enum(["whatsapp", "email"]);
 
+/** ADDITIVE ONLY — mirrors CampaignVariableSource in types/evo-campaigns/index.ts.
+ *  This list is SEPARATE from the TS union; dropping a value here rejects channel
+ *  configs already persisted in Firestore. */
 export const zCampaignVariableSourceSchema = z.enum([
   "placeholder",
   "fixed",
   "csv_column",
   "qr_link",
+  // E-MAIL ONLY (F3.2): resolves to channels.email.media.url.
+  "campaign_media",
 ]);
 
+/** ADDITIVE ONLY. The FE parses every recipient through this enum; a value written
+ *  to Firestore but missing here makes it drop the WHOLE recipient document. */
 export const zRecipientDispatchStateSchema = z.enum([
   "pending",
   "dispatched",
   "done",
   "excluded",
+  // Declared in RecipientDispatchState but with no writer yet — listed here FIRST so
+  // whoever starts writing it doesn't take the FE's recipient list down with them.
+  "canceled",
 ]);
 
 export const zRecipientChannelStatusSchema = z.enum([
@@ -212,10 +222,15 @@ export const zCampaignSchema = zFireDocSchema
     new_lead_config: zCampaignNewLeadConfigSchema.optional(),
     frequency: zCampaignFrequencySchema,
     schedule: zCampaignScheduleSchema,
+    // Backend-owned state maps: declared so the field is documented, deliberately
+    // left unvalidated. They gain fields slice by slice and the FE reads them
+    // defensively — a structural schema here would drop the whole campaign doc the
+    // first time the backend writes a counter the FE's evo-types doesn't know yet.
     dispatch_state: z.record(z.unknown()).optional(),
     prevalidation: z.record(z.unknown()).optional(),
     cost_estimate: z.record(z.unknown()).optional(),
     counters: z.record(z.unknown()).optional(),
+    last_materialize: z.record(z.unknown()).optional(),
   })
   .passthrough();
 
@@ -255,6 +270,10 @@ export const zCampaignRecipientSchema = zFireDocSchema
     primary_bucket_id: z.string(),
     csv_variables: z.record(z.string()).optional(),
     dispatch_state: zRecipientDispatchStateSchema,
+    /** Absent (field-deleted), not false, once a manual exclusion is restored. */
+    manual_excluded: z.boolean().optional(),
+    // Same reasoning as the campaign state maps: unvalidated on purpose, so a new
+    // exclusion reason or channel field never costs the FE the whole recipient row.
     eligibility: z.record(z.unknown()),
     channels: z.record(z.unknown()),
     interaction_status: zRecipientInteractionStatusSchema,

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

@@ -26,7 +26,7 @@ export type CampaignType = "conversion" | "informative" | "relationship" | "oper
 /** 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 type CampaignVariableSource = "placeholder" | "fixed" | "csv_column" | "qr_link" | "campaign_media";
 export interface ICampaignVariableMapping {
     /** Template variable name/index this mapping fills. */
     variable: string;
@@ -76,10 +76,19 @@ export interface ICampaignTicketPolicy {
     note?: string;
 }
 export interface ICampaignMedia {
-    /** 'image' | 'video' | 'document' — WhatsApp header media type. */
+    /** 'image' | 'video' | 'document' — WhatsApp header media type; always 'image' on e-mail. */
     type: string;
-    /** Full gs:// URI in WABA_MEDIA_BUCKET under tenants/<tenant>/ (feat-082/084 flow). */
+    /**
+     * Full gs:// URI of the stored object.
+     * WhatsApp: WABA_MEDIA_BUCKET (private) under tenants/<tenant>/ (feat-082/084 flow).
+     * E-mail:   the PUBLIC bucket (F3.2) — an e-mail client fetches the image
+     *           unauthenticated, so a private object or a signed URL cannot work.
+     */
     gcs_path?: string;
+    /**
+     * Public https URL of the object. E-mail REQUIRES it (it is what goes in the
+     * <img src>); on WhatsApp it is optional (`gcs_path` wins at send time).
+     */
     url?: string;
     /** Mime type of the uploaded media (drives the header component). */
     mime_type?: string | null;
@@ -96,7 +105,11 @@ export interface ICampaignChannelConfig {
     /** WhatsApp: template category from introspection (MARKETING/UTILITY/AUTHENTICATION). */
     template_category?: string;
     variable_mappings: ICampaignVariableMapping[];
-    /** WhatsApp header media (when the template requires it). */
+    /**
+     * WhatsApp: the template's header media (when the template requires it).
+     * E-mail: the campaign's image, reachable from the HTML through a
+     * `campaign_media` variable mapping (F3.2). PUBLICLY READABLE — never a patient asset.
+     */
     media?: ICampaignMedia;
     ctas: ICampaignCta[];
     /** Outbound department for the resulting ticket. */
@@ -181,16 +194,61 @@ export interface ICampaignCounters {
     unique?: number;
     eligible?: number;
     excluded_optout?: number;
+    /** Excluded by the 15-day fatigue rule. INCLUDES `excluded_frequency_unavailable`
+     *  (the fail-closed subset) — never sum the two, the second is a breakdown of
+     *  the first. */
     excluded_frequency?: number;
+    /**
+     * Subset of `excluded_frequency` excluded because the lead's marketing history
+     * could NOT be read, so the check failed CLOSED — not because the contact was
+     * touched recently. Reported apart because the two lead to opposite actions:
+     * "everybody was contacted in the last 15 days" (wait) vs "the history query is
+     * broken" (fix the index and re-materialize). Rolling them together made the
+     * screen state something actively false (F3.1 review A1).
+     */
+    excluded_frequency_unavailable?: number;
+    /** Always 0 today — no code path increments it (see audit note at the bottom). */
     excluded_invalid?: number;
     excluded_no_channel?: number;
     excluded_duplicate?: number;
+    /** Recipients removed by hand from the audience (`manual_excluded=true`). Written
+     *  wholesale by the materializer and incremented/decremented by the exclude/restore
+     *  endpoints. */
+    excluded_manual?: number;
     per_channel?: {
         whatsapp?: ICampaignChannelCounters;
         email?: ICampaignChannelCounters;
     };
     converted?: number;
 }
+/** Caveat on a materialization that SUCCEEDED but whose result is not what it looks like. */
+export type CampaignMaterializeWarning = 
+/** The campaign has no bucket at all — the audience is empty by construction,
+ *  not because the filters matched nobody. */
+"no_buckets"
+/** The 15-day fatigue check could not read the lead history and failed closed:
+ *  the recipients were excluded as a precaution, not for being contacted recently. */
+ | "frequency_check_unavailable";
+/**
+ * Progress/outcome stamp of the last audience materialization, written by the
+ * `campaign-materialize` handler (deep merge, so `error`/`warning` are written
+ * explicitly as null when absent — a stale caveat must not survive the next run).
+ * Drives the FE progress indicator and gates the interactive re-publish
+ * (`shouldSuppressMaterialize`).
+ */
+export interface ICampaignLastMaterialize {
+    status: "running" | "done" | "error";
+    /** Required — every one of the four write-sites sets it, and the suppression guard
+     *  reads it. Firestore returns a Timestamp here: `.toDate()` before comparing. */
+    at: Date;
+    /** Written EXPLICITLY as null on a run without one — a caveat from the previous run
+     *  must not survive the next (the stamp is a deep merge). */
+    error?: string | null;
+    warning?: CampaignMaterializeWarning | null;
+    /** Result snapshot (status='done' only) — mirrors counters.unique / counters.eligible. */
+    unique?: number;
+    eligible?: number;
+}
 export interface ICampaign extends IFireDoc {
     name: string;
     description?: string | null;
@@ -215,6 +273,9 @@ export interface ICampaign extends IFireDoc {
     prevalidation?: ICampaignPrevalidation;
     cost_estimate?: ICampaignCostEstimate;
     counters?: ICampaignCounters;
+    /** Cleared (field delete) when the last bucket is removed — an audience of zero
+     *  must not keep advertising the numbers of the previous run. */
+    last_materialize?: ICampaignLastMaterialize;
     created_by?: FirestoreDocumentReference;
     updated_by?: FirestoreDocumentReference;
     scheduled_by?: FirestoreDocumentReference;
@@ -245,9 +306,13 @@ export interface ICampaignBucketCsvFile {
     }>;
 }
 export interface ICampaignBucketCounts {
+    /** Rows enumerated by this bucket (CSV: row_count; Algolia: preview/enumeration count). */
     raw?: number;
+    /** CSV only, at upload: parseable contacts the bucket contributes. */
     unique_contribution?: number;
+    /** Set per bucket by the materializer (dot-path update, never set/merge). */
     eligible?: number;
+    /** CSV only, at upload: rows rejected by the parser. */
     invalid?: number;
     opt_out?: number;
     frequency_excluded?: number;
@@ -263,8 +328,15 @@ export interface ICampaignBucket extends IFireDoc {
 }
 /** Flat field driving the batch queue (indexed). */
 export type RecipientDispatchState = "pending" | "dispatched" | "done" | "excluded"
-/** Campaign canceled with this recipient still pending (feat-081 F3 — formalizes
- *  what F2 stored as 'excluded'; readers must accept both on old docs). */
+/**
+ * RESERVED — no writer today. `cancelCampaign` still parks pending recipients as
+ * `excluded` and carries the cancellation in `interaction_status='cancelado'`, so
+ * this value never reaches Firestore. Kept because the FSM wants it, but whoever
+ * starts writing it must check every `dispatch_state` reader first: the queue query
+ * filters on `=='pending'` (unaffected), but the FE parses recipients through
+ * `zRecipientDispatchStateSchema` and a value missing from that enum makes it drop
+ * the WHOLE document, not just the field.
+ */
  | "canceled";
 /** Per-channel delivery status of a recipient (monotonic). */
 export type RecipientChannelStatus = "pending" | "scheduled" | "sent" | "delivered" | "read" | "failed" | "clicked" | "replied";
@@ -276,6 +348,13 @@ export interface ICampaignRecipientContact {
     email?: string;
     external_id?: string;
 }
+/**
+ * Per-channel delivery state. The six milestones (sent/delivered/read/clicked/
+ * replied/failed) are FACTS, each with its own timestamp — and the timestamp, not the
+ * label, is the idempotency key of the tracking consumers. `status` is a monotonic
+ * LABEL derived from them and is shared mutable state, so it cannot serve as a stamp:
+ * a late event that moves the label would silently un-stamp the milestone under it.
+ */
 export interface ICampaignRecipientChannelState {
     status: RecipientChannelStatus;
     task_id?: string;
@@ -284,16 +363,59 @@ export interface ICampaignRecipientChannelState {
     delivered_at?: Date | null;
     read_at?: Date | null;
     clicked_at?: Date | null;
+    /**
+     * CTA that produced `clicked_at` (F3.2). The click consumer already carried the
+     * `cta_id` to BigQuery but dropped it from the doc, so a conversion could only be
+     * written with `cta_id: null` and no report could answer WHICH call to action
+     * converted. Stamped in the same transaction as `clicked_at`, sharing that
+     * milestone's idempotency: the FIRST click wins, later ones never overwrite it.
+     */
+    clicked_cta_id?: string | null;
     replied_at?: Date | null;
+    /** Milestone stamp of a provider failure. Completes the six — `failed` was the one
+     *  milestone without a timestamp, so its consumer had to key idempotency off
+     *  `status === 'failed'` instead (F3.1). */
+    failed_at?: Date | null;
+    /** Provider error text that accompanies `failed_at`. */
     error?: string | null;
 }
+/**
+ * Why a recipient was kept out. Closed union: every value here HAS a writer in
+ * `packages/model/src/evo-campaigns/audience/materializer.ts`, and the FE carries a
+ * label for each. Adding a value means adding its label in the same slice —
+ * `reasonLabel()` falls back to printing the raw code, which is how
+ * `frequency_check_unavailable` would have reached the operator as gibberish.
+ */
+export type CampaignExclusionReason = 
+/** Contact opted out of the marketing level (feat-067). */
+"optout"
+/** Touched by another marketing campaign inside `frequency.min_days`. */
+ | "frequency"
+/** The fatigue check could not read the lead history and failed CLOSED — the
+ *  contact was excluded as a precaution, NOT for being contacted recently. */
+ | "frequency_check_unavailable"
+/** No identifier for this channel (no mobile / no e-mail). */
+ | "no_channel"
+/**
+ * There IS an identifier for this channel, but it cannot be delivered to — a phone
+ * that is not a valid E.164 number, an address that is not an e-mail (F3.2). Before
+ * this existed, eligibility was decided by `!!mobile` / `!!email`, so a malformed
+ * value counted as ELIGIBLE, burned a send and failed at the provider. Distinct from
+ * `no_channel` on purpose: "fix this contact's data" and "this contact has no such
+ * channel" are different instructions for whoever reads the audience.
+ */
+ | "invalid"
+/** Removed by hand from the audience — always the value under the `manual` key. */
+ | "manual_removed";
 export interface ICampaignRecipientEligibility {
     per_channel: {
         whatsapp?: "eligible" | "excluded";
         email?: "eligible" | "excluded";
     };
-    /** channel -> exclusion reason. */
-    exclusion_reasons?: Record<string, string>;
+    /** Keys: `whatsapp` / `email` (per-channel) and `manual` (always `manual_removed`).
+     *  A recipient can carry several at once — `manual` stacks on top of a real
+     *  per-channel reason, which is what makes a restore keep it ineligible. */
+    exclusion_reasons?: Record<string, CampaignExclusionReason>;
 }
 export interface ICampaignRecipient extends IFireDoc {
     lead_id?: string;
@@ -305,6 +427,13 @@ export interface ICampaignRecipient extends IFireDoc {
     csv_variables?: Record<string, string>;
     /** FLAT field for the batch queue (indexed). */
     dispatch_state: RecipientDispatchState;
+    /**
+     * Removed by hand from the audience (F2.6/F2.7). This is the DETERMINISTIC marker:
+     * `eligibility.per_channel` is deliberately kept at its real value so a restore is
+     * symmetric, so per_channel alone cannot tell a manual removal from an organic
+     * exclusion. Survives re-materialization; deleted (not set false) on restore.
+     */
+    manual_excluded?: boolean;
     eligibility: ICampaignRecipientEligibility;
     channels: {
         whatsapp?: ICampaignRecipientChannelState;

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

@@ -74,7 +74,8 @@ 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`
+  | "qr_link" // a quick-reply /qr link for `cta_id`
+  | "campaign_media"; // E-MAIL ONLY: the public URL of `channels.email.media` (F3.2)
 
 export interface ICampaignVariableMapping {
   /** Template variable name/index this mapping fills. */
@@ -88,6 +89,8 @@ export interface ICampaignVariableMapping {
   column?: string;
   /** source='qr_link': the CTA whose /qr link is injected. */
   cta_id?: string;
+  // source='campaign_media' carries no extra field: it resolves to
+  // `channels.email.media.url` of the campaign it belongs to.
 }
 
 export interface ICampaignCta {
@@ -132,10 +135,19 @@ export interface ICampaignTicketPolicy {
 }
 
 export interface ICampaignMedia {
-  /** 'image' | 'video' | 'document' — WhatsApp header media type. */
+  /** 'image' | 'video' | 'document' — WhatsApp header media type; always 'image' on e-mail. */
   type: string;
-  /** Full gs:// URI in WABA_MEDIA_BUCKET under tenants/<tenant>/ (feat-082/084 flow). */
+  /**
+   * Full gs:// URI of the stored object.
+   * WhatsApp: WABA_MEDIA_BUCKET (private) under tenants/<tenant>/ (feat-082/084 flow).
+   * E-mail:   the PUBLIC bucket (F3.2) — an e-mail client fetches the image
+   *           unauthenticated, so a private object or a signed URL cannot work.
+   */
   gcs_path?: string;
+  /**
+   * Public https URL of the object. E-mail REQUIRES it (it is what goes in the
+   * <img src>); on WhatsApp it is optional (`gcs_path` wins at send time).
+   */
   url?: string;
   /** Mime type of the uploaded media (drives the header component). */
   mime_type?: string | null;
@@ -155,7 +167,11 @@ export interface ICampaignChannelConfig {
   /** WhatsApp: template category from introspection (MARKETING/UTILITY/AUTHENTICATION). */
   template_category?: string;
   variable_mappings: ICampaignVariableMapping[];
-  /** WhatsApp header media (when the template requires it). */
+  /**
+   * WhatsApp: the template's header media (when the template requires it).
+   * E-mail: the campaign's image, reachable from the HTML through a
+   * `campaign_media` variable mapping (F3.2). PUBLICLY READABLE — never a patient asset.
+   */
   media?: ICampaignMedia;
   ctas: ICampaignCta[];
   /** Outbound department for the resulting ticket. */
@@ -255,10 +271,27 @@ export interface ICampaignCounters {
   unique?: number;
   eligible?: number;
   excluded_optout?: number;
+  /** Excluded by the 15-day fatigue rule. INCLUDES `excluded_frequency_unavailable`
+   *  (the fail-closed subset) — never sum the two, the second is a breakdown of
+   *  the first. */
   excluded_frequency?: number;
+  /**
+   * Subset of `excluded_frequency` excluded because the lead's marketing history
+   * could NOT be read, so the check failed CLOSED — not because the contact was
+   * touched recently. Reported apart because the two lead to opposite actions:
+   * "everybody was contacted in the last 15 days" (wait) vs "the history query is
+   * broken" (fix the index and re-materialize). Rolling them together made the
+   * screen state something actively false (F3.1 review A1).
+   */
+  excluded_frequency_unavailable?: number;
+  /** Always 0 today — no code path increments it (see audit note at the bottom). */
   excluded_invalid?: number;
   excluded_no_channel?: number;
   excluded_duplicate?: number;
+  /** Recipients removed by hand from the audience (`manual_excluded=true`). Written
+   *  wholesale by the materializer and incremented/decremented by the exclude/restore
+   *  endpoints. */
+  excluded_manual?: number;
   per_channel?: {
     whatsapp?: ICampaignChannelCounters;
     email?: ICampaignChannelCounters;
@@ -266,6 +299,38 @@ export interface ICampaignCounters {
   converted?: number;
 }
 
+// ----- Last materialization stamp -------------------------------------------
+
+/** Caveat on a materialization that SUCCEEDED but whose result is not what it looks like. */
+export type CampaignMaterializeWarning =
+  /** The campaign has no bucket at all — the audience is empty by construction,
+   *  not because the filters matched nobody. */
+  | "no_buckets"
+  /** The 15-day fatigue check could not read the lead history and failed closed:
+   *  the recipients were excluded as a precaution, not for being contacted recently. */
+  | "frequency_check_unavailable";
+
+/**
+ * Progress/outcome stamp of the last audience materialization, written by the
+ * `campaign-materialize` handler (deep merge, so `error`/`warning` are written
+ * explicitly as null when absent — a stale caveat must not survive the next run).
+ * Drives the FE progress indicator and gates the interactive re-publish
+ * (`shouldSuppressMaterialize`).
+ */
+export interface ICampaignLastMaterialize {
+  status: "running" | "done" | "error";
+  /** Required — every one of the four write-sites sets it, and the suppression guard
+   *  reads it. Firestore returns a Timestamp here: `.toDate()` before comparing. */
+  at: Date;
+  /** Written EXPLICITLY as null on a run without one — a caveat from the previous run
+   *  must not survive the next (the stamp is a deep merge). */
+  error?: string | null;
+  warning?: CampaignMaterializeWarning | null;
+  /** Result snapshot (status='done' only) — mirrors counters.unique / counters.eligible. */
+  unique?: number;
+  eligible?: number;
+}
+
 // ----- Campaign aggregate doc -----------------------------------------------
 
 export interface ICampaign extends IFireDoc {
@@ -297,6 +362,9 @@ export interface ICampaign extends IFireDoc {
   prevalidation?: ICampaignPrevalidation;
   cost_estimate?: ICampaignCostEstimate;
   counters?: ICampaignCounters;
+  /** Cleared (field delete) when the last bucket is removed — an audience of zero
+   *  must not keep advertising the numbers of the previous run. */
+  last_materialize?: ICampaignLastMaterialize;
 
   // Audit (who/when per FSM transition)
   created_by?: FirestoreDocumentReference;
@@ -334,10 +402,18 @@ export interface ICampaignBucketCsvFile {
 }
 
 export interface ICampaignBucketCounts {
+  /** Rows enumerated by this bucket (CSV: row_count; Algolia: preview/enumeration count). */
   raw?: number;
+  /** CSV only, at upload: parseable contacts the bucket contributes. */
   unique_contribution?: number;
+  /** Set per bucket by the materializer (dot-path update, never set/merge). */
   eligible?: number;
+  /** CSV only, at upload: rows rejected by the parser. */
   invalid?: number;
+  // The three below have NO writer anywhere today — a per-bucket exclusion breakdown
+  // was never implemented (the breakdown lives on the campaign counters instead).
+  // Left declared, optional and empty rather than removed: they are the shape a future
+  // per-bucket breakdown should take, and nothing reads them meanwhile.
   opt_out?: number;
   frequency_excluded?: number;
   no_channel?: number;
@@ -360,8 +436,15 @@ export type RecipientDispatchState =
   | "dispatched"
   | "done"
   | "excluded"
-  /** Campaign canceled with this recipient still pending (feat-081 F3 — formalizes
-   *  what F2 stored as 'excluded'; readers must accept both on old docs). */
+  /**
+   * RESERVED — no writer today. `cancelCampaign` still parks pending recipients as
+   * `excluded` and carries the cancellation in `interaction_status='cancelado'`, so
+   * this value never reaches Firestore. Kept because the FSM wants it, but whoever
+   * starts writing it must check every `dispatch_state` reader first: the queue query
+   * filters on `=='pending'` (unaffected), but the FE parses recipients through
+   * `zRecipientDispatchStateSchema` and a value missing from that enum makes it drop
+   * the WHOLE document, not just the field.
+   */
   | "canceled";
 
 /** Per-channel delivery status of a recipient (monotonic). */
@@ -397,6 +480,13 @@ export interface ICampaignRecipientContact {
   external_id?: string;
 }
 
+/**
+ * Per-channel delivery state. The six milestones (sent/delivered/read/clicked/
+ * replied/failed) are FACTS, each with its own timestamp — and the timestamp, not the
+ * label, is the idempotency key of the tracking consumers. `status` is a monotonic
+ * LABEL derived from them and is shared mutable state, so it cannot serve as a stamp:
+ * a late event that moves the label would silently un-stamp the milestone under it.
+ */
 export interface ICampaignRecipientChannelState {
   status: RecipientChannelStatus;
   task_id?: string;
@@ -405,17 +495,61 @@ export interface ICampaignRecipientChannelState {
   delivered_at?: Date | null;
   read_at?: Date | null;
   clicked_at?: Date | null;
+  /**
+   * CTA that produced `clicked_at` (F3.2). The click consumer already carried the
+   * `cta_id` to BigQuery but dropped it from the doc, so a conversion could only be
+   * written with `cta_id: null` and no report could answer WHICH call to action
+   * converted. Stamped in the same transaction as `clicked_at`, sharing that
+   * milestone's idempotency: the FIRST click wins, later ones never overwrite it.
+   */
+  clicked_cta_id?: string | null;
   replied_at?: Date | null;
+  /** Milestone stamp of a provider failure. Completes the six — `failed` was the one
+   *  milestone without a timestamp, so its consumer had to key idempotency off
+   *  `status === 'failed'` instead (F3.1). */
+  failed_at?: Date | null;
+  /** Provider error text that accompanies `failed_at`. */
   error?: string | null;
 }
 
+/**
+ * Why a recipient was kept out. Closed union: every value here HAS a writer in
+ * `packages/model/src/evo-campaigns/audience/materializer.ts`, and the FE carries a
+ * label for each. Adding a value means adding its label in the same slice —
+ * `reasonLabel()` falls back to printing the raw code, which is how
+ * `frequency_check_unavailable` would have reached the operator as gibberish.
+ */
+export type CampaignExclusionReason =
+  /** Contact opted out of the marketing level (feat-067). */
+  | "optout"
+  /** Touched by another marketing campaign inside `frequency.min_days`. */
+  | "frequency"
+  /** The fatigue check could not read the lead history and failed CLOSED — the
+   *  contact was excluded as a precaution, NOT for being contacted recently. */
+  | "frequency_check_unavailable"
+  /** No identifier for this channel (no mobile / no e-mail). */
+  | "no_channel"
+  /**
+   * There IS an identifier for this channel, but it cannot be delivered to — a phone
+   * that is not a valid E.164 number, an address that is not an e-mail (F3.2). Before
+   * this existed, eligibility was decided by `!!mobile` / `!!email`, so a malformed
+   * value counted as ELIGIBLE, burned a send and failed at the provider. Distinct from
+   * `no_channel` on purpose: "fix this contact's data" and "this contact has no such
+   * channel" are different instructions for whoever reads the audience.
+   */
+  | "invalid"
+  /** Removed by hand from the audience — always the value under the `manual` key. */
+  | "manual_removed";
+
 export interface ICampaignRecipientEligibility {
   per_channel: {
     whatsapp?: "eligible" | "excluded";
     email?: "eligible" | "excluded";
   };
-  /** channel -> exclusion reason. */
-  exclusion_reasons?: Record<string, string>;
+  /** Keys: `whatsapp` / `email` (per-channel) and `manual` (always `manual_removed`).
+   *  A recipient can carry several at once — `manual` stacks on top of a real
+   *  per-channel reason, which is what makes a restore keep it ineligible. */
+  exclusion_reasons?: Record<string, CampaignExclusionReason>;
 }
 
 export interface ICampaignRecipient extends IFireDoc {
@@ -428,6 +562,13 @@ export interface ICampaignRecipient extends IFireDoc {
   csv_variables?: Record<string, string>;
   /** FLAT field for the batch queue (indexed). */
   dispatch_state: RecipientDispatchState;
+  /**
+   * Removed by hand from the audience (F2.6/F2.7). This is the DETERMINISTIC marker:
+   * `eligibility.per_channel` is deliberately kept at its real value so a restore is
+   * symmetric, so per_channel alone cannot tell a manual removal from an organic
+   * exclusion. Survives re-materialization; deleted (not set false) on restore.
+   */
+  manual_excluded?: boolean;
   eligibility: ICampaignRecipientEligibility;
   channels: {
     whatsapp?: ICampaignRecipientChannelState;

package/dist/types/evo-finops/common/contract.d.ts

@@ -1,5 +1,11 @@
 import type { IFireGlobalDoc } from '../../shared';
-export type NexFinopsContractStatus = 'draft' | 'active' | 'inactive' | 'ended' | 'canceled';
+/**
+ * `cancellation_requested`: o cliente pediu o cancelamento e o contrato está em
+ * processo de encerramento — mas **continua em vigência** e continua faturando
+ * (ver `NEX_FINOPS_BILLABLE_CONTRACT_STATUSES`). Só sai desse estado ao encerrar
+ * (`ended`), ao ser anulado (`canceled`) ou se o cliente voltar atrás (`active`).
+ */
+export type NexFinopsContractStatus = 'draft' | 'active' | 'cancellation_requested' | 'inactive' | 'ended' | 'canceled';
 export type NexFinopsContractRecurrence = 'one_time' | 'monthly';
 export type NexFinopsPaymentMethod = 'pix' | 'boleto' | 'payment_link';
 export interface INexFinopsContractServiceItem {
@@ -25,3 +31,13 @@ export interface INexFinopsContract extends IFireGlobalDoc {
     notes?: string | null;
 }
 export declare const NEX_FINOPS_CONTRACT_STATUS_TRANSITIONS: Record<NexFinopsContractStatus, NexFinopsContractStatus[]>;
+/**
+ * Status em que um contrato ainda gera cobrança.
+ *
+ * `cancellation_requested` entra aqui de propósito: o contrato pediu cancelamento
+ * mas segue em vigência até encerrar, e deve continuar sendo cobrado no período.
+ *
+ * Tipado como `readonly string[]` (e não `readonly NexFinopsContractStatus[]`) para
+ * que `.includes(x)` aceite qualquer string sem cast no ponto de uso.
+ */
+export declare const NEX_FINOPS_BILLABLE_CONTRACT_STATUSES: readonly string[];

package/dist/types/evo-finops/common/contract.js

@@ -1,11 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NEX_FINOPS_CONTRACT_STATUS_TRANSITIONS = void 0;
+exports.NEX_FINOPS_BILLABLE_CONTRACT_STATUSES = exports.NEX_FINOPS_CONTRACT_STATUS_TRANSITIONS = void 0;
 // ── Status transitions ──
 exports.NEX_FINOPS_CONTRACT_STATUS_TRANSITIONS = {
     draft: ['active', 'canceled'],
-    active: ['inactive', 'ended', 'canceled'],
+    active: ['cancellation_requested', 'inactive', 'ended', 'canceled'],
+    // Volta para 'active' cobre o cliente que desiste do cancelamento.
+    cancellation_requested: ['ended', 'canceled', 'active'],
     inactive: ['active'],
     ended: [],
     canceled: [],
 };
+/**
+ * Status em que um contrato ainda gera cobrança.
+ *
+ * `cancellation_requested` entra aqui de propósito: o contrato pediu cancelamento
+ * mas segue em vigência até encerrar, e deve continuar sendo cobrado no período.
+ *
+ * Tipado como `readonly string[]` (e não `readonly NexFinopsContractStatus[]`) para
+ * que `.includes(x)` aceite qualquer string sem cast no ponto de uso.
+ */
+exports.NEX_FINOPS_BILLABLE_CONTRACT_STATUSES = ['active', 'cancellation_requested'];