evo360-types 1.3.472 → 1.3.476

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

@@ -28,11 +28,16 @@ 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. */

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

@@ -31,11 +31,16 @@ 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

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. */
@@ -350,6 +363,14 @@ 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
@@ -375,6 +396,15 @@ export type CampaignExclusionReason =
  | "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 {

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. */
@@ -479,6 +495,14 @@ 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
@@ -505,6 +529,15 @@ export type CampaignExclusionReason =
   | "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";
 

package/package.json

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