evo360-types 1.3.391 → 1.3.394

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

@@ -1,6 +1,6 @@
 import { z } from "zod";
 export declare const zNotificationChannelTypeSchema: z.ZodEnum<["whatsapp", "email", "sms", "push"]>;
-export declare const zNotificationMessageStatusSchema: z.ZodEnum<["queued", "processing", "sent", "delivered", "failed", "cancelled", "suppressed"]>;
+export declare const zNotificationMessageStatusSchema: z.ZodEnum<["queued", "processing", "sent", "delivered", "read", "failed", "cancelled", "suppressed"]>;
 export declare const zNotificationAttemptStatusSchema: z.ZodEnum<["success", "retry", "error"]>;
 export declare const zNotificationRecipientKindSchema: z.ZodEnum<["patient", "professional", "preconfigured", "raw"]>;
 export declare const zNotificationLogLevelSchema: z.ZodEnum<["debug", "info", "warn", "error"]>;
@@ -139,11 +139,12 @@ export declare const zNotificationMessageSchema: z.ZodObject<{
         display_name: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">>;
     variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    status: z.ZodEnum<["queued", "processing", "sent", "delivered", "failed", "cancelled", "suppressed"]>;
+    status: z.ZodEnum<["queued", "processing", "sent", "delivered", "read", "failed", "cancelled", "suppressed"]>;
     queued_at: z.ZodDate;
     processing_started_at: z.ZodOptional<z.ZodDate>;
     sent_at: z.ZodOptional<z.ZodDate>;
     delivered_at: z.ZodOptional<z.ZodDate>;
+    read_at: z.ZodOptional<z.ZodDate>;
     completed_at: z.ZodOptional<z.ZodDate>;
     provider: z.ZodOptional<z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
@@ -255,11 +256,12 @@ export declare const zNotificationMessageSchema: z.ZodObject<{
         display_name: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">>;
     variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    status: z.ZodEnum<["queued", "processing", "sent", "delivered", "failed", "cancelled", "suppressed"]>;
+    status: z.ZodEnum<["queued", "processing", "sent", "delivered", "read", "failed", "cancelled", "suppressed"]>;
     queued_at: z.ZodDate;
     processing_started_at: z.ZodOptional<z.ZodDate>;
     sent_at: z.ZodOptional<z.ZodDate>;
     delivered_at: z.ZodOptional<z.ZodDate>;
+    read_at: z.ZodOptional<z.ZodDate>;
     completed_at: z.ZodOptional<z.ZodDate>;
     provider: z.ZodOptional<z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
@@ -371,11 +373,12 @@ export declare const zNotificationMessageSchema: z.ZodObject<{
         display_name: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">>;
     variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    status: z.ZodEnum<["queued", "processing", "sent", "delivered", "failed", "cancelled", "suppressed"]>;
+    status: z.ZodEnum<["queued", "processing", "sent", "delivered", "read", "failed", "cancelled", "suppressed"]>;
     queued_at: z.ZodDate;
     processing_started_at: z.ZodOptional<z.ZodDate>;
     sent_at: z.ZodOptional<z.ZodDate>;
     delivered_at: z.ZodOptional<z.ZodDate>;
+    read_at: z.ZodOptional<z.ZodDate>;
     completed_at: z.ZodOptional<z.ZodDate>;
     provider: z.ZodOptional<z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;

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

@@ -16,6 +16,7 @@ exports.zNotificationMessageStatusSchema = zod_1.z.enum([
     "processing",
     "sent",
     "delivered",
+    "read",
     "failed",
     "cancelled",
     "suppressed",
@@ -95,6 +96,7 @@ exports.zNotificationMessageSchema = zod_schemas_1.zFireDocSchema
     processing_started_at: zod_1.z.coerce.date().optional(),
     sent_at: zod_1.z.coerce.date().optional(),
     delivered_at: zod_1.z.coerce.date().optional(),
+    read_at: zod_1.z.coerce.date().optional(),
     completed_at: zod_1.z.coerce.date().optional(),
     provider: exports.zNotificationProviderMetaSchema.optional(),
     error: exports.zNotificationErrorSchema.optional(),

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

@@ -16,6 +16,7 @@ export const zNotificationMessageStatusSchema = z.enum([
   "processing",
   "sent",
   "delivered",
+  "read",
   "failed",
   "cancelled",
   "suppressed",
@@ -106,6 +107,7 @@ export const zNotificationMessageSchema = zFireDocSchema
     processing_started_at: z.coerce.date().optional(),
     sent_at: z.coerce.date().optional(),
     delivered_at: z.coerce.date().optional(),
+    read_at: z.coerce.date().optional(),
     completed_at: z.coerce.date().optional(),
     provider: zNotificationProviderMetaSchema.optional(),
     error: zNotificationErrorSchema.optional(),

package/dist/types/evo-crm/dic/index.d.ts

@@ -33,6 +33,16 @@ export interface IDistChannel extends IFireDoc {
     type_name?: string;
     typeRef?: FirestoreDocumentReference;
     tags?: ITag[] | null;
+    rules?: {
+        regex: string;
+        flags?: string;
+        priority?: number;
+        description?: string | null;
+        examples?: string[] | null;
+    } | null;
+    /** Tipo FINO de aquisição (feat-039) — override explícito da derivação por `code`.
+     *  String crua p/ evitar ciclo de import com ../lead; o core estreita p/ LeadReferralType. */
+    acq_type?: string | null;
     [key: string]: unknown;
 }
 export type QualificationFunnelLevel = "invalid" | "new" | "trying_contact" | "contacted" | "qualifying" | "qualified" | "disqualified" | "presented" | "proposal_sent" | "negotiating" | "won" | "lost" | "waiting_reply" | "follow_up_later";

package/dist/types/evo-crm/dic/index.ts

@@ -54,6 +54,18 @@ export interface IDistChannel extends IFireDoc {
   type_name?: string;
   typeRef?: FirestoreDocumentReference;
   tags?: ITag[] | null;
+  // Regras de parsing da 1ª mensagem (feat-039) — regex casada contra o texto
+  // p/ atribuir este canal; `priority` ordena entre múltiplos matches.
+  rules?: {
+    regex: string;
+    flags?: string;
+    priority?: number;
+    description?: string | null;
+    examples?: string[] | null;
+  } | null;
+  /** Tipo FINO de aquisição (feat-039) — override explícito da derivação por `code`.
+   *  String crua p/ evitar ciclo de import com ../lead; o core estreita p/ LeadReferralType. */
+  acq_type?: string | null;
   [key: string]: unknown; // index signature
 }
 

package/dist/types/evo-crm/lead/index.d.ts

@@ -32,13 +32,15 @@ export interface ILeadDistChannel {
 /** Origem de aquisição do lead (feat-038) — base expansível p/ múltiplas
  *  plataformas. v1 implementa só `type:'ctwa'` (Click-to-WhatsApp da Meta);
  *  Google Ads / Instagram Direct / TikTok / site ficam para fast-follow. */
-export type LeadReferralType = "ctwa" | "instagram_direct" | "google_ads" | "tiktok" | "site" | "other";
+export type LeadReferralType = "ctwa" | "instagram_direct" | "google_ads" | "tiktok" | "site" | "meta_organic" | "referral" | "other";
 export interface ILeadReferralBase {
     type: LeadReferralType;
     captured_at?: Date | string | null;
     source_url?: string | null;
     label?: string | null;
     raw?: Record<string, unknown> | null;
+    dist_channel_code?: string | null;
+    matched_rule?: string | null;
 }
 export interface ILeadReferralCTWA extends ILeadReferralBase {
     type: "ctwa";
@@ -49,7 +51,14 @@ export interface ILeadReferralCTWA extends ILeadReferralBase {
     media_type?: string | null;
     ctwa_clid?: string | null;
 }
-export type ILeadReferral = ILeadReferralCTWA;
+/** Origem genérica derivada da 1ª mensagem (feat-039) — Google/TikTok/site/
+ *  FB-IG orgânico/indicação. O `type` FINO vem do `acq_type` do dict ou do mapa
+ *  por `code`; `dist_channel_code`/`matched_rule` ficam na base p/ auditoria. */
+export interface ILeadReferralGeneric extends ILeadReferralBase {
+    type: "google_ads" | "tiktok" | "site" | "instagram_direct" | "meta_organic" | "referral" | "other";
+    headline?: string | null;
+}
+export type ILeadReferral = ILeadReferralCTWA | ILeadReferralGeneric;
 /** Estado da régua de reativação de lead (feat-037).
  *  Mantido pelo subscriber `ticket_closed` (streak) e pela task
  *  `lead_reactivation` (último disparo). Semântica do streak alinhada ao

package/dist/types/evo-crm/lead/index.ts

@@ -53,6 +53,8 @@ export type LeadReferralType =
   | "google_ads" // gclid / token em ?text=                     ← futuro
   | "tiktok"
   | "site"
+  | "meta_organic" // menção/URL orgânica de FB/IG (não-pago, sem referral)  ← feat-039
+  | "referral" // indicação ("me indicaram", "amigo falou")              ← feat-039
   | "other"; // ← futuro
 
 export interface ILeadReferralBase {
@@ -61,6 +63,8 @@ export interface ILeadReferralBase {
   source_url?: string | null; // link clicável
   label?: string | null; // rótulo de exibição (headline || ad_id || domínio)
   raw?: Record<string, unknown> | null; // payload original lossless → re-parse futuro sem backfill
+  dist_channel_code?: string | null; // code do entry do dict que casou (ex.: 'GOOGLE')  ← feat-039
+  matched_rule?: string | null; // regex/priority que casou (debug; opcional)        ← feat-039
 }
 
 export interface ILeadReferralCTWA extends ILeadReferralBase {
@@ -73,7 +77,22 @@ export interface ILeadReferralCTWA extends ILeadReferralBase {
   ctwa_clid?: string | null; // espelho; o de topo (CAPI/feat-034) permanece na raiz
 }
 
-export type ILeadReferral = ILeadReferralCTWA; // | ILeadReferralGoogleAds | ...
+/** Origem genérica derivada da 1ª mensagem (feat-039) — Google/TikTok/site/
+ *  FB-IG orgânico/indicação. O `type` FINO vem do `acq_type` do dict ou do mapa
+ *  por `code`; `dist_channel_code`/`matched_rule` ficam na base p/ auditoria. */
+export interface ILeadReferralGeneric extends ILeadReferralBase {
+  type:
+    | "google_ads"
+    | "tiktok"
+    | "site"
+    | "instagram_direct"
+    | "meta_organic"
+    | "referral"
+    | "other";
+  headline?: string | null; // paridade com CTWA p/ o FE existente
+}
+
+export type ILeadReferral = ILeadReferralCTWA | ILeadReferralGeneric;
 
 /** Estado da régua de reativação de lead (feat-037).
  *  Mantido pelo subscriber `ticket_closed` (streak) e pela task

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

@@ -37,6 +37,7 @@ export declare const NotificationMessageStatusEnum: {
     readonly Processing: "processing";
     readonly Sent: "sent";
     readonly Delivered: "delivered";
+    readonly Read: "read";
     readonly Failed: "failed";
     readonly Cancelled: "cancelled";
     readonly Suppressed: "suppressed";
@@ -130,6 +131,7 @@ export interface INotificationMessage extends IFireDoc {
     processing_started_at?: Date;
     sent_at?: Date;
     delivered_at?: Date;
+    read_at?: Date;
     completed_at?: Date;
     provider?: INotificationProviderMeta;
     error?: INotificationError;

package/dist/types/evo-notifications/index.js

@@ -73,6 +73,7 @@ exports.NotificationMessageStatusEnum = {
     Processing: "processing", // being handled by notifications service
     Sent: "sent", // accepted by provider
     Delivered: "delivered", // delivery confirmed (when supported)
+    Read: "read", // read receipt confirmed (when supported, e.g. WhatsApp/WABA)
     Failed: "failed", // permanent failure
     Cancelled: "cancelled",
     Suppressed: "suppressed", // dedup/skip decision

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

@@ -80,6 +80,7 @@ export const NotificationMessageStatusEnum = {
   Processing: "processing", // being handled by notifications service
   Sent: "sent", // accepted by provider
   Delivered: "delivered", // delivery confirmed (when supported)
+  Read: "read", // read receipt confirmed (when supported, e.g. WhatsApp/WABA)
   Failed: "failed", // permanent failure
   Cancelled: "cancelled",
   Suppressed: "suppressed", // dedup/skip decision
@@ -242,6 +243,7 @@ export interface INotificationMessage extends IFireDoc {
   processing_started_at?: Date;
   sent_at?: Date;
   delivered_at?: Date;
+  read_at?: Date; // read receipt time (WABA-first; channel-neutral field)
   completed_at?: Date;
 
   // Final outcome

package/dist/types/nex-tenants/chatbee-import.d.ts

@@ -3,8 +3,20 @@ import type { IFireGlobalDoc } from "../shared";
 export declare const CHATBEE_IMPORT_SCHEMA_VERSION: 1;
 export declare const CHATBEE_IMPORT_FIRESTORE_PATH: "core/nexus/apps/nex-tenants/chatbee_imports";
 export declare const CHATBEE_IMPORT_PUBSUB_TOPIC: "app_nexus_chatbee-import_request";
+/**
+ * Per-(tenant, channel) department mapping doc, keyed `{tenant}__{channelId}`.
+ * Holds the operator's resolution of unresolved Chatbee departments before a
+ * real import is allowed to run.
+ */
+export declare const CHATBEE_IMPORT_DEPT_MAP_PATH: "core/nexus/apps/nex-tenants/chatbee_import_dept_maps";
+/** Mapping sentinel: route this Chatbee department to the channel's default. */
+export declare const CHANNEL_DEFAULT_DEPT_SENTINEL: "__channel_default__";
 export type ChatbeeImportStatus = "pending" | "running" | "done" | "failed";
-export type ChatbeeImportAuditAction = "import_requested" | "import_started" | "import_page" | "import_completed" | "import_failed";
+/** A job runs either as a read-only analysis pass or the real import. */
+export type ChatbeeImportMode = "analyze" | "import";
+export type ChatbeeImportAuditAction = "import_requested" | "import_started" | "import_page" | "import_completed" | "import_failed" | "analyze_requested" | "analyze_completed" | "dept_map_saved";
+/** Resolution status of one Chatbee department against the platform. */
+export type ChatbeeDeptResolutionStatus = "resolved" | "resolved_no_inbox" | "missing" | "no_external_id" | "mapped";
 /**
  * Keyset cursor over `chatbee.msgs_raw` ordered by
  * (contact.id, history.id, timestamp, message.id). A page resumes strictly
@@ -32,6 +44,12 @@ export interface IChatbeeImportCounters {
     contacts_reconciled: number;
     reconcile_conflicts: number;
     pages_processed: number;
+    /** Distinct Chatbee departments seen across the run. */
+    departments_found: number;
+    /** Departments still blocking (not resolved nor mapped). */
+    departments_unresolved: number;
+    /** Lead links dropped because the referenced lead was missing/deleted. */
+    lead_links_missing: number;
 }
 export interface IChatbeeImportError {
     code: string;
@@ -42,12 +60,67 @@ export interface IChatbeeImportRequestedBy {
     email: string;
     loginId: string;
 }
+/** Resolution of one DISTINCT Chatbee department against the platform. */
+export interface IChatbeeDepartmentResolution {
+    /** Chatbee department numeric id (stable) — the mapping key. */
+    chatbee_id: string;
+    /** Chatbee department external_id (may be null → no platform correlation). */
+    external_id: string | null;
+    /** Chatbee department display name. */
+    name: string;
+    /** Distinct attendances seen under this department in the window. */
+    event_count: number;
+    tickets_open: number;
+    tickets_closed: number;
+    status: ChatbeeDeptResolutionStatus;
+    /**
+     * The platform department this resolves to: the validated `external_id` for
+     * `resolved`/`resolved_no_inbox`, or the operator mapping target for `mapped`
+     * (a platform dept id, or CHANNEL_DEFAULT_DEPT_SENTINEL). Null while blocking.
+     */
+    mapped_to?: string | null;
+}
+/** Read-only pre-import analysis report, stored on the job-doc. */
+export interface IChatbeeImportAnalysis {
+    departments: IChatbeeDepartmentResolution[];
+    channel_default: {
+        department_id: string | null;
+        exists: boolean;
+        chat_enabled: boolean;
+        has_inbox: boolean;
+        /** True when the default is usable (exists + chat_enabled + has_inbox). */
+        valid: boolean;
+    };
+    lead_links: {
+        contacts_total: number;
+        /** Contacts whose contact.lead_id points at a missing/deleted lead. */
+        lead_missing_count: number;
+    };
+    contacts: {
+        total: number;
+        /** wa-index already points at a different contact (kept Chatbee canonical). */
+        index_conflicts: number;
+    };
+    /** True if any department is unresolved/unmapped or the channel default is invalid. */
+    blocking: boolean;
+    analyzed_at?: Date | null;
+}
+/**
+ * Operator's department mapping: Chatbee department id → platform department id
+ * (or CHANNEL_DEFAULT_DEPT_SENTINEL). Stored per (tenant, channel) at
+ * CHATBEE_IMPORT_DEPT_MAP_PATH/{tenant}__{channelId}.
+ */
+export type IChatbeeImportDeptMapping = Record<string, string>;
 export interface IChatbeeImportDoc extends IFireGlobalDoc {
     tenant: string;
     /** Destination hub-waba channel id — threads/tickets/messages carry this channel_id. */
     destination_channel_id: string;
+    /** 'analyze' = read-only pre-import pass; 'import' = the real import. */
+    mode?: ChatbeeImportMode;
     /** Count-only preview: zero Firestore/PubSub/BQ writes, projects counters + totals. */
     dry_run: boolean;
+    /** Read-only analysis report (set when mode === 'analyze'). */
+    analysis?: IChatbeeImportAnalysis | null;
     requested_by: IChatbeeImportRequestedBy;
     requested_at: Date | null;
     started_at?: Date | null;
@@ -77,10 +150,38 @@ export declare const ChatbeeImportRequestSchema: z.ZodObject<{
     dry_run?: boolean | undefined;
 }>;
 export type IChatbeeImportRequestPayload = z.infer<typeof ChatbeeImportRequestSchema>;
+export declare const ChatbeeImportAnalyzeSchema: z.ZodObject<{
+    tenant: z.ZodString;
+    destination_channel_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    tenant: string;
+    destination_channel_id: string;
+}, {
+    tenant: string;
+    destination_channel_id: string;
+}>;
+export type IChatbeeImportAnalyzePayload = z.infer<typeof ChatbeeImportAnalyzeSchema>;
+export declare const ChatbeeImportSaveDeptMapSchema: z.ZodObject<{
+    tenant: z.ZodString;
+    channel_id: z.ZodString;
+    /** chatbee_id → platform dept id (or CHANNEL_DEFAULT_DEPT_SENTINEL). */
+    map: z.ZodRecord<z.ZodString, z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    map: Record<string, string>;
+    tenant: string;
+    channel_id: string;
+}, {
+    map: Record<string, string>;
+    tenant: string;
+    channel_id: string;
+}>;
+export type IChatbeeImportSaveDeptMapPayload = z.infer<typeof ChatbeeImportSaveDeptMapSchema>;
 export interface IChatbeeImportPubSubEvent {
     importId: string;
     tenant: string;
     destination_channel_id: string;
+    /** 'analyze' = read-only pass; 'import' = real import. */
+    mode: ChatbeeImportMode;
     dry_run: boolean;
     /** Cursor to resume from on a self-continuation; null/absent for the first run. */
     cursor?: IChatbeeImportCursor | null;

package/dist/types/nex-tenants/chatbee-import.js

@@ -1,14 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ChatbeeImportRequestSchema = exports.CHATBEE_IMPORT_PUBSUB_TOPIC = exports.CHATBEE_IMPORT_FIRESTORE_PATH = exports.CHATBEE_IMPORT_SCHEMA_VERSION = void 0;
+exports.ChatbeeImportSaveDeptMapSchema = exports.ChatbeeImportAnalyzeSchema = exports.ChatbeeImportRequestSchema = exports.CHANNEL_DEFAULT_DEPT_SENTINEL = exports.CHATBEE_IMPORT_DEPT_MAP_PATH = exports.CHATBEE_IMPORT_PUBSUB_TOPIC = exports.CHATBEE_IMPORT_FIRESTORE_PATH = exports.CHATBEE_IMPORT_SCHEMA_VERSION = void 0;
 const zod_1 = require("zod");
 // ── Constants ──
 exports.CHATBEE_IMPORT_SCHEMA_VERSION = 1;
 exports.CHATBEE_IMPORT_FIRESTORE_PATH = "core/nexus/apps/nex-tenants/chatbee_imports";
 exports.CHATBEE_IMPORT_PUBSUB_TOPIC = "app_nexus_chatbee-import_request";
+/**
+ * Per-(tenant, channel) department mapping doc, keyed `{tenant}__{channelId}`.
+ * Holds the operator's resolution of unresolved Chatbee departments before a
+ * real import is allowed to run.
+ */
+exports.CHATBEE_IMPORT_DEPT_MAP_PATH = "core/nexus/apps/nex-tenants/chatbee_import_dept_maps";
+/** Mapping sentinel: route this Chatbee department to the channel's default. */
+exports.CHANNEL_DEFAULT_DEPT_SENTINEL = "__channel_default__";
 // ── Zod Schemas (callable payloads) ──
 exports.ChatbeeImportRequestSchema = zod_1.z.object({
     tenant: zod_1.z.string().min(1),
     destination_channel_id: zod_1.z.string().min(1),
     dry_run: zod_1.z.boolean().optional(),
 });
+exports.ChatbeeImportAnalyzeSchema = zod_1.z.object({
+    tenant: zod_1.z.string().min(1),
+    destination_channel_id: zod_1.z.string().min(1),
+});
+exports.ChatbeeImportSaveDeptMapSchema = zod_1.z.object({
+    tenant: zod_1.z.string().min(1),
+    channel_id: zod_1.z.string().min(1),
+    /** chatbee_id → platform dept id (or CHANNEL_DEFAULT_DEPT_SENTINEL). */
+    map: zod_1.z.record(zod_1.z.string(), zod_1.z.string().min(1)),
+});

package/dist/types/nex-tenants/chatbee-import.ts

@@ -11,6 +11,17 @@ export const CHATBEE_IMPORT_FIRESTORE_PATH =
 export const CHATBEE_IMPORT_PUBSUB_TOPIC =
   "app_nexus_chatbee-import_request" as const;
 
+/**
+ * Per-(tenant, channel) department mapping doc, keyed `{tenant}__{channelId}`.
+ * Holds the operator's resolution of unresolved Chatbee departments before a
+ * real import is allowed to run.
+ */
+export const CHATBEE_IMPORT_DEPT_MAP_PATH =
+  "core/nexus/apps/nex-tenants/chatbee_import_dept_maps" as const;
+
+/** Mapping sentinel: route this Chatbee department to the channel's default. */
+export const CHANNEL_DEFAULT_DEPT_SENTINEL = "__channel_default__" as const;
+
 // ── Enums / Literals ──
 
 export type ChatbeeImportStatus =
@@ -19,12 +30,26 @@ export type ChatbeeImportStatus =
   | "done"
   | "failed";
 
+/** A job runs either as a read-only analysis pass or the real import. */
+export type ChatbeeImportMode = "analyze" | "import";
+
 export type ChatbeeImportAuditAction =
   | "import_requested"
   | "import_started"
   | "import_page"
   | "import_completed"
-  | "import_failed";
+  | "import_failed"
+  | "analyze_requested"
+  | "analyze_completed"
+  | "dept_map_saved";
+
+/** Resolution status of one Chatbee department against the platform. */
+export type ChatbeeDeptResolutionStatus =
+  | "resolved"          // external_id → dept exists, chat_enabled, has dept inbox sub
+  | "resolved_no_inbox" // dept exists but no dept inbox subscription (ticket invisible)
+  | "missing"           // external_id set but dept doc does not exist
+  | "no_external_id"    // external_id NULL (no correlation possible)
+  | "mapped";           // operator mapped chatbee_id → platform dept (or channel default)
 
 // ── Sub-interfaces ──
 
@@ -56,6 +81,12 @@ export interface IChatbeeImportCounters {
   contacts_reconciled: number;
   reconcile_conflicts: number;
   pages_processed: number;
+  /** Distinct Chatbee departments seen across the run. */
+  departments_found: number;
+  /** Departments still blocking (not resolved nor mapped). */
+  departments_unresolved: number;
+  /** Lead links dropped because the referenced lead was missing/deleted. */
+  lead_links_missing: number;
 }
 
 export interface IChatbeeImportError {
@@ -69,14 +100,74 @@ export interface IChatbeeImportRequestedBy {
   loginId: string;
 }
 
+// ── Analysis sub-interfaces ──
+
+/** Resolution of one DISTINCT Chatbee department against the platform. */
+export interface IChatbeeDepartmentResolution {
+  /** Chatbee department numeric id (stable) — the mapping key. */
+  chatbee_id: string;
+  /** Chatbee department external_id (may be null → no platform correlation). */
+  external_id: string | null;
+  /** Chatbee department display name. */
+  name: string;
+  /** Distinct attendances seen under this department in the window. */
+  event_count: number;
+  tickets_open: number;
+  tickets_closed: number;
+  status: ChatbeeDeptResolutionStatus;
+  /**
+   * The platform department this resolves to: the validated `external_id` for
+   * `resolved`/`resolved_no_inbox`, or the operator mapping target for `mapped`
+   * (a platform dept id, or CHANNEL_DEFAULT_DEPT_SENTINEL). Null while blocking.
+   */
+  mapped_to?: string | null;
+}
+
+/** Read-only pre-import analysis report, stored on the job-doc. */
+export interface IChatbeeImportAnalysis {
+  departments: IChatbeeDepartmentResolution[];
+  channel_default: {
+    department_id: string | null;
+    exists: boolean;
+    chat_enabled: boolean;
+    has_inbox: boolean;
+    /** True when the default is usable (exists + chat_enabled + has_inbox). */
+    valid: boolean;
+  };
+  lead_links: {
+    contacts_total: number;
+    /** Contacts whose contact.lead_id points at a missing/deleted lead. */
+    lead_missing_count: number;
+  };
+  contacts: {
+    total: number;
+    /** wa-index already points at a different contact (kept Chatbee canonical). */
+    index_conflicts: number;
+  };
+  /** True if any department is unresolved/unmapped or the channel default is invalid. */
+  blocking: boolean;
+  analyzed_at?: Date | null;
+}
+
+/**
+ * Operator's department mapping: Chatbee department id → platform department id
+ * (or CHANNEL_DEFAULT_DEPT_SENTINEL). Stored per (tenant, channel) at
+ * CHATBEE_IMPORT_DEPT_MAP_PATH/{tenant}__{channelId}.
+ */
+export type IChatbeeImportDeptMapping = Record<string, string>;
+
 // ── Main Document ──
 
 export interface IChatbeeImportDoc extends IFireGlobalDoc {
   tenant: string;
   /** Destination hub-waba channel id — threads/tickets/messages carry this channel_id. */
   destination_channel_id: string;
+  /** 'analyze' = read-only pre-import pass; 'import' = the real import. */
+  mode?: ChatbeeImportMode;
   /** Count-only preview: zero Firestore/PubSub/BQ writes, projects counters + totals. */
   dry_run: boolean;
+  /** Read-only analysis report (set when mode === 'analyze'). */
+  analysis?: IChatbeeImportAnalysis | null;
   requested_by: IChatbeeImportRequestedBy;
   requested_at: Date | null;
   started_at?: Date | null;
@@ -105,12 +196,34 @@ export type IChatbeeImportRequestPayload = z.infer<
   typeof ChatbeeImportRequestSchema
 >;
 
+export const ChatbeeImportAnalyzeSchema = z.object({
+  tenant: z.string().min(1),
+  destination_channel_id: z.string().min(1),
+});
+
+export type IChatbeeImportAnalyzePayload = z.infer<
+  typeof ChatbeeImportAnalyzeSchema
+>;
+
+export const ChatbeeImportSaveDeptMapSchema = z.object({
+  tenant: z.string().min(1),
+  channel_id: z.string().min(1),
+  /** chatbee_id → platform dept id (or CHANNEL_DEFAULT_DEPT_SENTINEL). */
+  map: z.record(z.string(), z.string().min(1)),
+});
+
+export type IChatbeeImportSaveDeptMapPayload = z.infer<
+  typeof ChatbeeImportSaveDeptMapSchema
+>;
+
 // ── PubSub Event ──
 
 export interface IChatbeeImportPubSubEvent {
   importId: string;
   tenant: string;
   destination_channel_id: string;
+  /** 'analyze' = read-only pass; 'import' = real import. */
+  mode: ChatbeeImportMode;
   dry_run: boolean;
   /** Cursor to resume from on a self-continuation; null/absent for the first run. */
   cursor?: IChatbeeImportCursor | null;

package/package.json

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