evo360-types 1.3.476 → 1.3.478

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

@@ -159,11 +159,50 @@ export interface ICampaignSentToday {
         email?: number;
     };
 }
+/**
+ * Where ONE channel stands in the dispatch queue (F3.3).
+ *
+ * The four pacing knobs are configured per channel, so the two channels advance through
+ * the audience at different speeds and each needs its own position. Both channels read
+ * the SAME queue (`dispatch_state == 'pending'` ordered by `__name__`); what separates
+ * them is the `startAfter` each one uses.
+ */
+export interface ICampaignDispatchChannelState {
+    /**
+     * Last recipient id this channel dispatched — the `startAfter` of its own page.
+     * A channel held back by its window or its daily limit simply does NOT advance this,
+     * which is what records the legs it still owes.
+     */
+    cursor_doc_id?: string | null;
+    /**
+     * Earliest instant this channel may dispatch again (its own `batch_interval_minutes`).
+     * This is the AUTHORITY on the channel's turn: the scheduled `campaign.dispatch_batch`
+     * task is only a wake-up call and grants no permission by itself, so a batch that fires
+     * early (the feat-080 sweep reviving a chain, say) re-reads this and defers.
+     * Firestore returns a Timestamp — `.toDate()` before comparing.
+     */
+    next_at?: Date | null;
+}
 export interface ICampaignDispatchState {
+    /**
+     * LEGACY (pre-F3.3): the single campaign-wide cursor. It no longer governs sending —
+     * `per_channel.{channel}.cursor_doc_id` does. It is still written, as the MINIMUM of
+     * the per-channel cursors, for two reasons: a campaign in flight when F3.3 deployed
+     * seeds both channels from it, and a rollback to the previous engine must resume
+     * BEHIND every channel rather than ahead of one (re-reading is inert — the send task
+     * is idempotent on `dedup_key` — whereas skipping loses a send silently).
+     * Do not read this to answer "how far has the campaign got": ask per channel.
+     */
     cursor_doc_id?: string | null;
     next_dispatch_task_id?: string | null;
     sent_today?: ICampaignSentToday;
     batches_dispatched?: number;
+    /** Per-channel queue position and turn (F3.3). Absent on a campaign that last ran
+     *  under the pre-F3.3 engine; each channel then falls back to `cursor_doc_id`. */
+    per_channel?: {
+        whatsapp?: ICampaignDispatchChannelState;
+        email?: ICampaignDispatchChannelState;
+    };
 }
 export type CampaignPrevalidationStatus = "approved" | "warnings" | "blocked";
 export interface ICampaignPrevalidation {

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

@@ -231,11 +231,51 @@ export interface ICampaignSentToday {
   };
 }
 
+/**
+ * Where ONE channel stands in the dispatch queue (F3.3).
+ *
+ * The four pacing knobs are configured per channel, so the two channels advance through
+ * the audience at different speeds and each needs its own position. Both channels read
+ * the SAME queue (`dispatch_state == 'pending'` ordered by `__name__`); what separates
+ * them is the `startAfter` each one uses.
+ */
+export interface ICampaignDispatchChannelState {
+  /**
+   * Last recipient id this channel dispatched — the `startAfter` of its own page.
+   * A channel held back by its window or its daily limit simply does NOT advance this,
+   * which is what records the legs it still owes.
+   */
+  cursor_doc_id?: string | null;
+  /**
+   * Earliest instant this channel may dispatch again (its own `batch_interval_minutes`).
+   * This is the AUTHORITY on the channel's turn: the scheduled `campaign.dispatch_batch`
+   * task is only a wake-up call and grants no permission by itself, so a batch that fires
+   * early (the feat-080 sweep reviving a chain, say) re-reads this and defers.
+   * Firestore returns a Timestamp — `.toDate()` before comparing.
+   */
+  next_at?: Date | null;
+}
+
 export interface ICampaignDispatchState {
+  /**
+   * LEGACY (pre-F3.3): the single campaign-wide cursor. It no longer governs sending —
+   * `per_channel.{channel}.cursor_doc_id` does. It is still written, as the MINIMUM of
+   * the per-channel cursors, for two reasons: a campaign in flight when F3.3 deployed
+   * seeds both channels from it, and a rollback to the previous engine must resume
+   * BEHIND every channel rather than ahead of one (re-reading is inert — the send task
+   * is idempotent on `dedup_key` — whereas skipping loses a send silently).
+   * Do not read this to answer "how far has the campaign got": ask per channel.
+   */
   cursor_doc_id?: string | null;
   next_dispatch_task_id?: string | null;
   sent_today?: ICampaignSentToday;
   batches_dispatched?: number;
+  /** Per-channel queue position and turn (F3.3). Absent on a campaign that last ran
+   *  under the pre-F3.3 engine; each channel then falls back to `cursor_doc_id`. */
+  per_channel?: {
+    whatsapp?: ICampaignDispatchChannelState;
+    email?: ICampaignDispatchChannelState;
+  };
 }
 
 export type CampaignPrevalidationStatus = "approved" | "warnings" | "blocked";

package/package.json

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