evo360-types 1.3.143 → 1.3.145

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

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationRecipientKindEnum = exports.NotificationAttemptStatusEnum = exports.NotificationMessageStatusEnum = exports.NotificationChannelTypeEnum = exports.NotificationsTopics = exports.NotificationTaskKindEnum = exports.EvoNotificationsCollections = void 0;
+// ======================================================
+// evo-notifications
+//
+// Responsibilities (types only):
+// - Define the notification execution payload schema (used by Task Runner)
+// - Define persistence models for notification messages and attempts
+// - Keep channel/provider details generic and extensible
+//
+// Firestore (per tenant):
+// - Root app path: /tenants/{tenant}/apps/evo-notifications
+// - Messages:      /tenants/{tenant}/apps/evo-notifications/messages/{messageId}
+// - Attempts:      /tenants/{tenant}/apps/evo-notifications/messages/{messageId}/attempts/{attemptId}
+// - Logs:          /tenants/{tenant}/apps/evo-notifications/messages/{messageId}/logs/{logId}
+// ======================================================
+// ----- Firestore collections
+exports.EvoNotificationsCollections = {
+    Messages: "messages",
+    Attempts: "attempts",
+    Logs: "logs",
+};
+// ----- Task Runner integration
+exports.NotificationTaskKindEnum = {
+    Send: "notification.send",
+};
+// Logical Pub/Sub topic names (optional, but useful as shared constants)
+exports.NotificationsTopics = {
+    ExecuteRequests: "notifications.execute_requests",
+    ExecutionReports: "notifications.execution_reports",
+    ProviderWebhooks: "notifications.provider_webhooks",
+};
+// ----- Channel types
+exports.NotificationChannelTypeEnum = {
+    WhatsApp: "whatsapp",
+    Email: "email",
+    SMS: "sms",
+    Push: "push",
+};
+// ----- High-level message status (channel-agnostic)
+exports.NotificationMessageStatusEnum = {
+    Queued: "queued", // created and waiting execution
+    Processing: "processing", // being handled by notifications service
+    Sent: "sent", // accepted by provider
+    Delivered: "delivered", // delivery confirmed (when supported)
+    Failed: "failed", // permanent failure
+    Cancelled: "cancelled",
+    Suppressed: "suppressed", // dedup/skip decision
+};
+// ----- Attempt status
+exports.NotificationAttemptStatusEnum = {
+    Success: "success",
+    Retry: "retry",
+    Error: "error",
+};
+// ----- Recipient
+exports.NotificationRecipientKindEnum = {
+    Patient: "patient",
+    Professional: "professional",
+    Preconfigured: "preconfigured",
+    Raw: "raw",
+};

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

@@ -0,0 +1,261 @@
+import type { FirestoreDocumentReference, IFireDoc } from "../shared";
+
+// ======================================================
+// evo-notifications
+//
+// Responsibilities (types only):
+// - Define the notification execution payload schema (used by Task Runner)
+// - Define persistence models for notification messages and attempts
+// - Keep channel/provider details generic and extensible
+//
+// Firestore (per tenant):
+// - Root app path: /tenants/{tenant}/apps/evo-notifications
+// - Messages:      /tenants/{tenant}/apps/evo-notifications/messages/{messageId}
+// - Attempts:      /tenants/{tenant}/apps/evo-notifications/messages/{messageId}/attempts/{attemptId}
+// - Logs:          /tenants/{tenant}/apps/evo-notifications/messages/{messageId}/logs/{logId}
+// ======================================================
+
+// ----- Firestore collections
+export const EvoNotificationsCollections = {
+  Messages: "messages",
+  Attempts: "attempts",
+  Logs: "logs",
+} as const;
+
+export type EvoNotificationsCollectionName =
+  (typeof EvoNotificationsCollections)[keyof typeof EvoNotificationsCollections];
+
+// ----- Task Runner integration
+export const NotificationTaskKindEnum = {
+  Send: "notification.send",
+} as const;
+
+export type NotificationTaskKind =
+  (typeof NotificationTaskKindEnum)[keyof typeof NotificationTaskKindEnum];
+
+// Logical Pub/Sub topic names (optional, but useful as shared constants)
+export const NotificationsTopics = {
+  ExecuteRequests: "notifications.execute_requests",
+  ExecutionReports: "notifications.execution_reports",
+  ProviderWebhooks: "notifications.provider_webhooks",
+} as const;
+
+export type NotificationsTopic =
+  (typeof NotificationsTopics)[keyof typeof NotificationsTopics];
+
+// ----- Channel types
+export const NotificationChannelTypeEnum = {
+  WhatsApp: "whatsapp",
+  Email: "email",
+  SMS: "sms",
+  Push: "push",
+} as const;
+
+export type NotificationChannelType =
+  (typeof NotificationChannelTypeEnum)[keyof typeof NotificationChannelTypeEnum];
+
+// ----- High-level message status (channel-agnostic)
+export const NotificationMessageStatusEnum = {
+  Queued: "queued", // created and waiting execution
+  Processing: "processing", // being handled by notifications service
+  Sent: "sent", // accepted by provider
+  Delivered: "delivered", // delivery confirmed (when supported)
+  Failed: "failed", // permanent failure
+  Cancelled: "cancelled",
+  Suppressed: "suppressed", // dedup/skip decision
+} as const;
+
+export type NotificationMessageStatus =
+  (typeof NotificationMessageStatusEnum)[keyof typeof NotificationMessageStatusEnum];
+
+// ----- Attempt status
+export const NotificationAttemptStatusEnum = {
+  Success: "success",
+  Retry: "retry",
+  Error: "error",
+} as const;
+
+export type NotificationAttemptStatus =
+  (typeof NotificationAttemptStatusEnum)[keyof typeof NotificationAttemptStatusEnum];
+
+// ----- Recipient
+export const NotificationRecipientKindEnum = {
+  Patient: "patient",
+  Professional: "professional",
+  Preconfigured: "preconfigured",
+  Raw: "raw",
+} as const;
+
+export type NotificationRecipientKind =
+  (typeof NotificationRecipientKindEnum)[keyof typeof NotificationRecipientKindEnum];
+
+export interface INotificationRecipient {
+  kind: NotificationRecipientKind;
+
+  // Internal references (optional)
+  id?: string; // patientId/professionalId/etc.
+  ref?: FirestoreDocumentReference;
+
+  // Destination address (required for kind=raw, may also be filled for others)
+  // - whatsapp/sms: E.164 phone
+  // - email: email address
+  // - push: device token or topic
+  address?: string;
+
+  // Display helpers
+  display_name?: string;
+
+  [key: string]: unknown;
+}
+
+// ----- Channel reference (points to CHAT module configuration)
+export interface INotificationChannelRef {
+  type: NotificationChannelType;
+  channel_id: string; // reference to channel config in CHAT module
+  sender_id?: string; // optional (e.g., whatsapp business number, email sender id)
+  [key: string]: unknown;
+}
+
+// ----- Template reference
+export interface INotificationTemplateRef {
+  template_id: string; // HSM template id, email template id, push template id...
+  locale?: string;
+  version?: number | string;
+  [key: string]: unknown;
+}
+
+// ----- Provider metadata (generic)
+export interface INotificationProviderMeta {
+  name?: string; // e.g., meta, twilio, sendgrid, firebase
+  message_id?: string; // provider-specific id
+  status?: string; // provider status string
+  raw?: Record<string, unknown>; // sanitized provider response
+  [key: string]: unknown;
+}
+
+// ----- Error model
+export interface INotificationError {
+  message: string;
+  code?: string | number;
+  details?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+// ======================================================
+// Payload schema for Task Runner (task.auto.kind = "notification.send")
+// ======================================================
+
+export interface INotificationSendPayload {
+  kind: "notification.send";
+
+  // Classification/category is useful for UI filters and dedup grouping
+  classification?: string; // e.g. REMINDER, CSAT, BILLING, SYSTEM
+  importance?: number; // 0-100 tie-breaker
+
+  // Destination + channel
+  recipient: INotificationRecipient;
+  channel: INotificationChannelRef;
+
+  // Template and variables
+  template?: INotificationTemplateRef;
+  variables?: Record<string, unknown>; // resolved upstream (Automation Hub / Task Runner)
+
+  // Optional business context
+  routine?: {
+    id: string;
+    version?: number | string;
+    [key: string]: unknown;
+  };
+
+  // Idempotency for provider send (for the same attempt)
+  idempotency_key?: string;
+
+  // Optional dedup keys (mirrors Task dedup; helpful when writing message docs)
+  dedup_key?: string;
+  dedup_group_key?: string;
+
+  [key: string]: unknown;
+}
+
+// ======================================================
+// Persistence models
+// ======================================================
+
+// A persisted notification message represents the execution of a task in this module.
+// It should be easily listable/filterable in the UI.
+export interface INotificationMessage extends IFireDoc {
+  tenant: string;
+
+  // Link back to the originating task
+  task_id?: string;
+
+  // Optional routine context
+  routine_id?: string;
+  routine_version?: number | string;
+
+  // Classification and importance for filtering
+  classification?: string;
+  importance?: number;
+
+  // Channel/template snapshot
+  channel: INotificationChannelRef;
+  template?: INotificationTemplateRef;
+
+  // Recipient snapshot
+  recipient: INotificationRecipient;
+
+  // Variables snapshot (avoid storing sensitive info when possible)
+  variables?: Record<string, unknown>;
+
+  // Status tracking
+  status: NotificationMessageStatus;
+  queued_at: Date;
+  processing_started_at?: Date;
+  sent_at?: Date;
+  delivered_at?: Date;
+  completed_at?: Date;
+
+  // Final outcome
+  provider?: INotificationProviderMeta;
+  error?: INotificationError;
+
+  // Dedup helpers
+  dedup_key?: string;
+  dedup_group_key?: string;
+
+  // Indexing helpers (optional)
+  date_bucket?: string; // e.g., YYYY-MM-DD (tenant timezone)
+
+  [key: string]: unknown;
+}
+
+// Each send attempt is stored in a sub-collection to keep the message list lightweight.
+export interface INotificationAttempt extends IFireDoc {
+  message_id: string;
+  task_id?: string;
+
+  attempt: number; // 0-based
+  status: NotificationAttemptStatus;
+
+  requested_at: Date;
+  started_at?: Date;
+  finished_at?: Date;
+
+  provider?: INotificationProviderMeta;
+  error?: INotificationError;
+
+  // Sanitized request/response summaries (never store secrets)
+  request_summary?: Record<string, unknown>;
+  response_summary?: Record<string, unknown>;
+
+  [key: string]: unknown;
+}
+
+export interface INotificationLog extends IFireDoc {
+  message_id: string;
+  level: "debug" | "info" | "warn" | "error";
+  message: string;
+  data?: Record<string, unknown>;
+  at: Date;
+  [key: string]: unknown;
+}

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

@@ -1,94 +1,228 @@
 export * from "./fb_collections";
 import type { FirestoreDocumentReference, IFireDoc, ITag } from "../shared";
-export type TaskAction = "CREATE_TASK" | "DELETE_TASK" | "UPDATE_TASK";
-export declare enum ITaskAction {
-    Create_task = "CREATE_TASK",
-    Delete_task = "DELETE_TASK",
-    Update_task = "UPDATE_TASK"
-}
-export type TaskStatus = "not_started" | "in_progress" | "completed" | "cancelled" | "on_hold";
-export declare enum ITaskStatus {
-    NotStarted = "not_started",
-    InProgress = "in_progress",
-    Completed = "completed",
-    Cancelled = "cancelled",
-    OnHold = "on_hold"
-}
-export type TaskPriority = "low" | "medium" | "high";
-export declare enum ITaskPriority {
-    Low = "low",
-    Medium = "medium",
-    High = "high"
+export declare const EvoTaskCollections: {
+    readonly Tasks: "tasks";
+    readonly Executions: "executions";
+    readonly Comments: "comments";
+    readonly Logs: "logs";
+};
+export type EvoTaskCollectionName = (typeof EvoTaskCollections)[keyof typeof EvoTaskCollections];
+export declare const TaskActionEnum: {
+    readonly CreateTask: "CREATE_TASK";
+    readonly DeleteTask: "DELETE_TASK";
+    readonly UpdateTask: "UPDATE_TASK";
+};
+export type TaskAction = (typeof TaskActionEnum)[keyof typeof TaskActionEnum];
+export declare const TaskStatusEnum: {
+    readonly NotStarted: "not_started";
+    readonly InProgress: "in_progress";
+    readonly Completed: "completed";
+    readonly Failed: "failed";
+    readonly Cancelled: "cancelled";
+    readonly OnHold: "on_hold";
+    readonly Suppressed: "suppressed";
+};
+export type TaskStatus = (typeof TaskStatusEnum)[keyof typeof TaskStatusEnum];
+export declare const TaskPriorityEnum: {
+    readonly Low: "low";
+    readonly Medium: "medium";
+    readonly High: "high";
+};
+export type TaskPriority = (typeof TaskPriorityEnum)[keyof typeof TaskPriorityEnum];
+export declare const TaskSourceEnum: {
+    readonly User: "user";
+    readonly AutomationHub: "automation_hub";
+    readonly System: "system";
+};
+export type TaskSource = (typeof TaskSourceEnum)[keyof typeof TaskSourceEnum];
+export declare const TaskModeEnum: {
+    readonly Human: "human";
+    readonly Auto: "auto";
+};
+export type TaskMode = (typeof TaskModeEnum)[keyof typeof TaskModeEnum];
+export declare const TaskAutoHandlerEnum: {
+    readonly Notifications: "notifications";
+    readonly AIAgent: "ai_agent";
+    readonly Invoices: "invoices";
+    readonly Webhook: "webhook";
+    readonly Custom: "custom";
+};
+export type TaskAutoHandler = (typeof TaskAutoHandlerEnum)[keyof typeof TaskAutoHandlerEnum];
+export declare const TaskRetryStrategyEnum: {
+    readonly Fixed: "fixed";
+    readonly Exponential: "exponential";
+};
+export type TaskRetryStrategy = (typeof TaskRetryStrategyEnum)[keyof typeof TaskRetryStrategyEnum];
+export interface ITaskRetryPolicy {
+    max_attempts: number;
+    attempt: number;
+    strategy: TaskRetryStrategy;
+    backoff_seconds: number;
+    next_attempt_at?: Date;
+    last_error?: {
+        message: string;
+        code?: string | number;
+        at: Date;
+        details?: Record<string, unknown>;
+    };
+    [key: string]: unknown;
 }
-export type IATaskType = "data_analysis" | "content_generation" | "classification" | "extraction" | "summarization" | "translation" | "sentiment_analysis" | "question_answering" | "send_reminder" | "request_contact_info" | "request_operator_info" | "confirm_appointment" | "send_documents" | "create_appointment" | "reschedule_appointment" | "cancel_appointment" | "financial_charge" | "custom";
-export declare enum IIATaskType {
-    DataAnalysis = "data_analysis",
-    ContentGeneration = "content_generation",
-    Classification = "classification",
-    Extraction = "extraction",
-    Summarization = "summarization",
-    Translation = "translation",
-    SentimentAnalysis = "sentiment_analysis",
-    QuestionAnswering = "question_answering",
-    SendReminder = "send_reminder",
-    RequestContactInfo = "request_contact_info",
-    RequestOperatorInfo = "request_operator_info",
-    ConfirmAppointment = "confirm_appointment",
-    SendDocuments = "send_documents",
-    CreateAppointment = "create_appointment",
-    RescheduleAppointment = "reschedule_appointment",
-    CancelAppointment = "cancel_appointment",
-    FinancialCharge = "financial_charge",
-    Custom = "custom"
+export interface ITaskLock {
+    locked_by: string;
+    lock_until: Date;
+    [key: string]: unknown;
 }
-export type TaskExternalObjectType = "crm_lead" | "med_patient" | "med_professional" | "med_appointment" | "chat_contact";
-export declare enum ITaskExternalObjectType {
-    CrmLead = "crm_lead",
-    MedPatient = "med_patient",
-    MedProfessional = "med_professional",
-    MedAppointment = "med_appointment",
-    ChatContact = "chat_contact"
+export declare const TaskDedupScopeEnum: {
+    readonly PerRecipient: "per_recipient";
+    readonly PerRecipientAndObject: "per_recipient_and_object";
+    readonly Custom: "custom";
+};
+export type TaskDedupScope = (typeof TaskDedupScopeEnum)[keyof typeof TaskDedupScopeEnum];
+export declare const TaskDedupWindowEnum: {
+    readonly SameDay: "same_day";
+    readonly NHours: "n_hours";
+    readonly Custom: "custom";
+};
+export type TaskDedupWindow = (typeof TaskDedupWindowEnum)[keyof typeof TaskDedupWindowEnum];
+export interface ITaskDedup {
+    enabled: boolean;
+    key: string;
+    group_key?: string;
+    scope?: TaskDedupScope;
+    window?: TaskDedupWindow;
+    window_hours?: number;
+    importance?: number;
+    [key: string]: unknown;
 }
+export declare const TaskExternalObjectTypeEnum: {
+    readonly CrmLead: "crm_lead";
+    readonly MedPatient: "med_patient";
+    readonly MedProfessional: "med_professional";
+    readonly MedAppointment: "med_appointment";
+    readonly ChatContact: "chat_contact";
+};
+export type TaskExternalObjectType = (typeof TaskExternalObjectTypeEnum)[keyof typeof TaskExternalObjectTypeEnum];
 export interface ITaskExternalLink {
     type: TaskExternalObjectType;
     id: string;
+    label?: string;
+    [key: string]: unknown;
+}
+export interface ITaskUserAssignee {
+    kind: "user";
+    name?: string;
+    ref?: FirestoreDocumentReference;
+    [key: string]: unknown;
+}
+export interface ITaskSchedule {
+    execute_at?: Date;
+    due_at?: Date;
+    timezone?: string;
+    [key: string]: unknown;
+}
+export interface ITaskAutoSpec {
+    handler: TaskAutoHandler;
+    kind: string;
+    version?: number | string;
+    payload: Record<string, unknown>;
+    idempotency_key?: string;
     [key: string]: unknown;
 }
-export interface ITask extends IFireDoc {
+export interface ITaskOnFailure {
+    handoff_to_user?: {
+        name?: string;
+        ref?: FirestoreDocumentReference;
+    };
+    create_handoff_task?: {
+        title?: string;
+        description?: string;
+        priority?: TaskPriority;
+        tags?: ITag[] | null;
+    };
+    auto_fallbacks?: Array<{
+        handler: TaskAutoHandler;
+        kind: string;
+        payload: Record<string, unknown>;
+    }>;
+    [key: string]: unknown;
+}
+export interface ITaskBase extends IFireDoc {
     title: string;
     description?: string;
-    creatorName: string;
-    creatorRef?: FirestoreDocumentReference;
-    startDate: Date;
-    dueDate?: Date;
     status: TaskStatus;
     priority?: TaskPriority;
-    assigneeName?: string;
-    assigneeRef?: FirestoreDocumentReference;
+    importance?: number;
+    source: TaskSource;
+    creator: {
+        name: string;
+        ref?: FirestoreDocumentReference;
+    };
+    schedule?: ITaskSchedule;
     tags?: ITag[] | null;
-    ia_assigned?: boolean;
-    ia_agent?: string;
-    ia_duescheduled?: Date;
-    ia_task_type?: IATaskType;
-    ia_result?: string;
-    ia_result_code?: number;
-    ia_started_at?: Date;
-    ia_completed_at?: Date;
-    ia_error?: string;
-    ia_retry_count?: number;
-    ia_metadata?: Record<string, unknown>;
-    ia_prompt?: string;
-    ia_model?: string;
-    ia_progress?: number;
     externalLinks?: ITaskExternalLink[];
+    idempotency_key?: string;
+    dedup?: ITaskDedup;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface IHumanTask extends ITaskBase {
+    mode: "human";
+    assignee?: ITaskUserAssignee;
+}
+export interface IAutoTask extends ITaskBase {
+    mode: "auto";
+    schedule: ITaskSchedule & {
+        execute_at: Date;
+    };
+    lock?: ITaskLock;
+    retry?: ITaskRetryPolicy;
+    on_failure?: ITaskOnFailure;
+    auto: ITaskAutoSpec;
+}
+export type ITask = IHumanTask | IAutoTask;
+export declare const TaskExecutionStatusEnum: {
+    readonly Success: "success";
+    readonly Error: "error";
+    readonly Retry: "retry";
+};
+export type TaskExecutionStatus = (typeof TaskExecutionStatusEnum)[keyof typeof TaskExecutionStatusEnum];
+export interface ITaskExecution extends IFireDoc {
+    taskId: string;
+    handler: TaskAutoHandler;
+    kind: string;
+    status: TaskExecutionStatus;
+    attempt: number;
+    started_at: Date;
+    completed_at?: Date;
+    result?: Record<string, unknown>;
+    error?: {
+        message: string;
+        code?: string | number;
+        details?: Record<string, unknown>;
+    };
+    provider?: {
+        name?: string;
+        message_id?: string;
+        [key: string]: unknown;
+    };
     [key: string]: unknown;
 }
 export interface ITaskComment extends IFireDoc {
     taskId: string;
     text: string;
-    authorName: string;
-    authorRef?: FirestoreDocumentReference;
+    author: {
+        name: string;
+        ref?: FirestoreDocumentReference;
+    };
     edited?: boolean;
     edited_at?: Date;
     [key: string]: unknown;
 }
+export interface ITaskLog extends IFireDoc {
+    taskId: string;
+    level: "debug" | "info" | "warn" | "error";
+    message: string;
+    data?: Record<string, unknown>;
+    at: Date;
+    [key: string]: unknown;
+}