evo360-types 1.3.469 → 1.3.472

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

@@ -4,7 +4,9 @@ export type ICampaignStatus = z.infer<typeof zCampaignStatusSchema>;
 export declare const zCampaignTypeSchema: z.ZodEnum<["conversion", "informative", "relationship", "operational", "promotional"]>;
 export declare const zCampaignChannelSchema: z.ZodEnum<["whatsapp", "email"]>;
 export declare const zCampaignVariableSourceSchema: z.ZodEnum<["placeholder", "fixed", "csv_column", "qr_link"]>;
-export declare const zRecipientDispatchStateSchema: z.ZodEnum<["pending", "dispatched", "done", "excluded"]>;
+/** 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 declare const zRecipientDispatchStateSchema: z.ZodEnum<["pending", "dispatched", "done", "excluded", "canceled"]>;
 export declare const zRecipientChannelStatusSchema: z.ZodEnum<["pending", "scheduled", "sent", "delivered", "read", "failed", "clicked", "replied"]>;
 export declare const zRecipientInteractionStatusSchema: z.ZodEnum<["pendente", "inelegivel", "agendado", "enviado", "entregue", "lido", "clicou", "respondeu", "convertido", "falhou", "optout", "cancelado"]>;
 export declare const zCampaignCodeNameSchema: z.ZodObject<{
@@ -3738,6 +3740,7 @@ export declare const zCampaignSchema: z.ZodObject<{
     prevalidation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     cost_estimate: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     counters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    last_materialize: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     id: z.ZodString;
     ref: z.ZodAny;
@@ -6726,6 +6729,7 @@ export declare const zCampaignSchema: z.ZodObject<{
     prevalidation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     cost_estimate: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     counters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    last_materialize: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     id: z.ZodString;
     ref: z.ZodAny;
@@ -9714,6 +9718,7 @@ export declare const zCampaignSchema: z.ZodObject<{
     prevalidation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     cost_estimate: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     counters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    last_materialize: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.ZodTypeAny, "passthrough">>;
 export declare const zCampaignBucketSourceTypeSchema: z.ZodEnum<["leads", "patients", "appointments", "csv"]>;
 export declare const zCampaignBucketSchema: z.ZodObject<{
@@ -9790,7 +9795,9 @@ export declare const zCampaignRecipientSchema: z.ZodObject<{
     bucket_ids: z.ZodArray<z.ZodString, "many">;
     primary_bucket_id: z.ZodString;
     csv_variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    dispatch_state: z.ZodEnum<["pending", "dispatched", "done", "excluded"]>;
+    dispatch_state: z.ZodEnum<["pending", "dispatched", "done", "excluded", "canceled"]>;
+    /** Absent (field-deleted), not false, once a manual exclusion is restored. */
+    manual_excluded: z.ZodOptional<z.ZodBoolean>;
     eligibility: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     channels: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     interaction_status: z.ZodEnum<["pendente", "inelegivel", "agendado", "enviado", "entregue", "lido", "clicou", "respondeu", "convertido", "falhou", "optout", "cancelado"]>;
@@ -9827,7 +9834,9 @@ export declare const zCampaignRecipientSchema: z.ZodObject<{
     bucket_ids: z.ZodArray<z.ZodString, "many">;
     primary_bucket_id: z.ZodString;
     csv_variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    dispatch_state: z.ZodEnum<["pending", "dispatched", "done", "excluded"]>;
+    dispatch_state: z.ZodEnum<["pending", "dispatched", "done", "excluded", "canceled"]>;
+    /** Absent (field-deleted), not false, once a manual exclusion is restored. */
+    manual_excluded: z.ZodOptional<z.ZodBoolean>;
     eligibility: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     channels: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     interaction_status: z.ZodEnum<["pendente", "inelegivel", "agendado", "enviado", "entregue", "lido", "clicou", "respondeu", "convertido", "falhou", "optout", "cancelado"]>;
@@ -9864,7 +9873,9 @@ export declare const zCampaignRecipientSchema: z.ZodObject<{
     bucket_ids: z.ZodArray<z.ZodString, "many">;
     primary_bucket_id: z.ZodString;
     csv_variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    dispatch_state: z.ZodEnum<["pending", "dispatched", "done", "excluded"]>;
+    dispatch_state: z.ZodEnum<["pending", "dispatched", "done", "excluded", "canceled"]>;
+    /** Absent (field-deleted), not false, once a manual exclusion is restored. */
+    manual_excluded: z.ZodOptional<z.ZodBoolean>;
     eligibility: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     channels: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     interaction_status: z.ZodEnum<["pendente", "inelegivel", "agendado", "enviado", "entregue", "lido", "clicou", "respondeu", "convertido", "falhou", "optout", "cancelado"]>;

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

@@ -34,11 +34,16 @@ exports.zCampaignVariableSourceSchema = zod_1.z.enum([
     "csv_column",
     "qr_link",
 ]);
+/** 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 +199,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 +244,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

@@ -38,11 +38,16 @@ export const zCampaignVariableSourceSchema = z.enum([
   "qr_link",
 ]);
 
+/** 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 +217,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 +265,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

@@ -181,16 +181,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 +260,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 +293,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 +315,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 +335,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;
@@ -285,15 +351,41 @@ export interface ICampaignRecipientChannelState {
     read_at?: Date | null;
     clicked_at?: Date | 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"
+/** 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 +397,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

@@ -255,10 +255,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 +283,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 +346,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 +386,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 +420,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 +464,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;
@@ -406,16 +480,43 @@ export interface ICampaignRecipientChannelState {
   read_at?: Date | null;
   clicked_at?: Date | 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"
+  /** 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 +529,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'];

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

@@ -2,7 +2,13 @@ import type { IFireGlobalDoc } from '../../shared';
 
 // ── Status & Recurrence ──
 
-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';
 
@@ -55,8 +61,21 @@ export interface INexFinopsContract extends IFireGlobalDoc {
 
 export const NEX_FINOPS_CONTRACT_STATUS_TRANSITIONS: Record<NexFinopsContractStatus, NexFinopsContractStatus[]> = {
   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.
+ */
+export const NEX_FINOPS_BILLABLE_CONTRACT_STATUSES: readonly string[] = ['active', 'cancellation_requested'];

package/package.json

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