evo360-types 1.3.143 → 1.3.145

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

@@ -14,54 +14,96 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ITaskExternalObjectType = exports.IIATaskType = exports.ITaskPriority = exports.ITaskStatus = exports.ITaskAction = void 0;
+exports.TaskExecutionStatusEnum = exports.TaskExternalObjectTypeEnum = exports.TaskDedupWindowEnum = exports.TaskDedupScopeEnum = exports.TaskRetryStrategyEnum = exports.TaskAutoHandlerEnum = exports.TaskModeEnum = exports.TaskSourceEnum = exports.TaskPriorityEnum = exports.TaskStatusEnum = exports.TaskActionEnum = exports.EvoTaskCollections = void 0;
 __exportStar(require("./fb_collections"), exports);
-var ITaskAction;
-(function (ITaskAction) {
-    ITaskAction["Create_task"] = "CREATE_TASK";
-    ITaskAction["Delete_task"] = "DELETE_TASK";
-    ITaskAction["Update_task"] = "UPDATE_TASK";
-})(ITaskAction || (exports.ITaskAction = ITaskAction = {}));
-var ITaskStatus;
-(function (ITaskStatus) {
-    ITaskStatus["NotStarted"] = "not_started";
-    ITaskStatus["InProgress"] = "in_progress";
-    ITaskStatus["Completed"] = "completed";
-    ITaskStatus["Cancelled"] = "cancelled";
-    ITaskStatus["OnHold"] = "on_hold";
-})(ITaskStatus || (exports.ITaskStatus = ITaskStatus = {}));
-var ITaskPriority;
-(function (ITaskPriority) {
-    ITaskPriority["Low"] = "low";
-    ITaskPriority["Medium"] = "medium";
-    ITaskPriority["High"] = "high";
-})(ITaskPriority || (exports.ITaskPriority = ITaskPriority = {}));
-var IIATaskType;
-(function (IIATaskType) {
-    IIATaskType["DataAnalysis"] = "data_analysis";
-    IIATaskType["ContentGeneration"] = "content_generation";
-    IIATaskType["Classification"] = "classification";
-    IIATaskType["Extraction"] = "extraction";
-    IIATaskType["Summarization"] = "summarization";
-    IIATaskType["Translation"] = "translation";
-    IIATaskType["SentimentAnalysis"] = "sentiment_analysis";
-    IIATaskType["QuestionAnswering"] = "question_answering";
-    IIATaskType["SendReminder"] = "send_reminder";
-    IIATaskType["RequestContactInfo"] = "request_contact_info";
-    IIATaskType["RequestOperatorInfo"] = "request_operator_info";
-    IIATaskType["ConfirmAppointment"] = "confirm_appointment";
-    IIATaskType["SendDocuments"] = "send_documents";
-    IIATaskType["CreateAppointment"] = "create_appointment";
-    IIATaskType["RescheduleAppointment"] = "reschedule_appointment";
-    IIATaskType["CancelAppointment"] = "cancel_appointment";
-    IIATaskType["FinancialCharge"] = "financial_charge";
-    IIATaskType["Custom"] = "custom";
-})(IIATaskType || (exports.IIATaskType = IIATaskType = {}));
-var ITaskExternalObjectType;
-(function (ITaskExternalObjectType) {
-    ITaskExternalObjectType["CrmLead"] = "crm_lead";
-    ITaskExternalObjectType["MedPatient"] = "med_patient";
-    ITaskExternalObjectType["MedProfessional"] = "med_professional";
-    ITaskExternalObjectType["MedAppointment"] = "med_appointment";
-    ITaskExternalObjectType["ChatContact"] = "chat_contact";
-})(ITaskExternalObjectType || (exports.ITaskExternalObjectType = ITaskExternalObjectType = {}));
+// ======================================================
+// evo-task (Tasks)
+//
+// Design goals:
+// - Single, generic Task model used by humans and automation
+// - AUTO tasks are executed by Task Runner (in evo-task-runner)
+// - Payloads for specific handlers (notifications, AI, invoices, etc.)
+//   live in their own modules; here we keep the contract generic
+// - Sub-collections (executions/comments/logs) keep lists fast
+// ======================================================
+// ----- Firestore collection conventions (per tenant)
+// Root: /tenants/{tenant}/apps/evo-task/tasks/{taskId}
+exports.EvoTaskCollections = {
+    Tasks: "tasks",
+    Executions: "executions",
+    Comments: "comments",
+    Logs: "logs",
+};
+// ----- Activities tracking
+exports.TaskActionEnum = {
+    CreateTask: "CREATE_TASK",
+    DeleteTask: "DELETE_TASK",
+    UpdateTask: "UPDATE_TASK",
+};
+// ----- Task lifecycle status
+// Keep the human-friendly lifecycle states (legacy-friendly): not_started / in_progress.
+exports.TaskStatusEnum = {
+    NotStarted: "not_started",
+    InProgress: "in_progress",
+    Completed: "completed",
+    Failed: "failed", // final failure (after retries)
+    Cancelled: "cancelled",
+    OnHold: "on_hold",
+    Suppressed: "suppressed", // intentionally skipped (e.g., dedup)
+};
+// ----- Task priority (human-friendly)
+exports.TaskPriorityEnum = {
+    Low: "low",
+    Medium: "medium",
+    High: "high",
+};
+// ----- Task source (who created it)
+exports.TaskSourceEnum = {
+    User: "user",
+    AutomationHub: "automation_hub",
+    System: "system",
+};
+// ----- Task execution mode
+exports.TaskModeEnum = {
+    Human: "human",
+    Auto: "auto",
+};
+// ----- AUTO task handler (which executor processes the task)
+// Keep it open for future modules; these are logical handler identifiers.
+exports.TaskAutoHandlerEnum = {
+    Notifications: "notifications",
+    AIAgent: "ai_agent",
+    Invoices: "invoices",
+    Webhook: "webhook",
+    Custom: "custom",
+};
+// ----- Retry policy
+exports.TaskRetryStrategyEnum = {
+    Fixed: "fixed",
+    Exponential: "exponential",
+};
+// ----- Dedup / suppression (optional)
+exports.TaskDedupScopeEnum = {
+    PerRecipient: "per_recipient",
+    PerRecipientAndObject: "per_recipient_and_object",
+    Custom: "custom",
+};
+exports.TaskDedupWindowEnum = {
+    SameDay: "same_day",
+    NHours: "n_hours",
+    Custom: "custom",
+};
+// ----- External object links (for unified UI views)
+exports.TaskExternalObjectTypeEnum = {
+    CrmLead: "crm_lead",
+    MedPatient: "med_patient",
+    MedProfessional: "med_professional",
+    MedAppointment: "med_appointment",
+    ChatContact: "chat_contact",
+};
+// ----- Task execution attempts (sub-collection: tasks/{taskId}/executions)
+exports.TaskExecutionStatusEnum = {
+    Success: "success",
+    Error: "error",
+    Retry: "retry",
+};

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

@@ -1,145 +1,343 @@
 export * from "./fb_collections";
 import type { FirestoreDocumentReference, IFireDoc, ITag } from "../shared";
-// ----- TaskTypes
-
-// Enum for Task Action - used in Activities tracking
-export type TaskAction = "CREATE_TASK" | "DELETE_TASK" | "UPDATE_TASK";
-export enum ITaskAction {
-  Create_task = "CREATE_TASK",
-  Delete_task = "DELETE_TASK",
-  Update_task = "UPDATE_TASK",
-}
 
-// Enum for Task Instance Status
-
-export type TaskStatus =
-  | "not_started"
-  | "in_progress"
-  | "completed"
-  | "cancelled"
-  | "on_hold";
-
-export enum ITaskStatus {
-  NotStarted = "not_started",
-  InProgress = "in_progress",
-  Completed = "completed",
-  Cancelled = "cancelled",
-  OnHold = "on_hold",
+// ======================================================
+// evo-task (Tasks)
+//
+// Design goals:
+// - Single, generic Task model used by humans and automation
+// - AUTO tasks are executed by Task Runner (in evo-task-runner)
+// - Payloads for specific handlers (notifications, AI, invoices, etc.)
+//   live in their own modules; here we keep the contract generic
+// - Sub-collections (executions/comments/logs) keep lists fast
+// ======================================================
+
+// ----- Firestore collection conventions (per tenant)
+// Root: /tenants/{tenant}/apps/evo-task/tasks/{taskId}
+export const EvoTaskCollections = {
+  Tasks: "tasks",
+  Executions: "executions",
+  Comments: "comments",
+  Logs: "logs",
+} as const;
+
+export type EvoTaskCollectionName =
+  (typeof EvoTaskCollections)[keyof typeof EvoTaskCollections];
+
+// ----- Activities tracking
+export const TaskActionEnum = {
+  CreateTask: "CREATE_TASK",
+  DeleteTask: "DELETE_TASK",
+  UpdateTask: "UPDATE_TASK",
+} as const;
+
+export type TaskAction = (typeof TaskActionEnum)[keyof typeof TaskActionEnum];
+
+// ----- Task lifecycle status
+// Keep the human-friendly lifecycle states (legacy-friendly): not_started / in_progress.
+export const TaskStatusEnum = {
+  NotStarted: "not_started",
+  InProgress: "in_progress",
+  Completed: "completed",
+  Failed: "failed", // final failure (after retries)
+  Cancelled: "cancelled",
+  OnHold: "on_hold",
+  Suppressed: "suppressed", // intentionally skipped (e.g., dedup)
+} as const;
+
+export type TaskStatus = (typeof TaskStatusEnum)[keyof typeof TaskStatusEnum];
+
+// ----- Task priority (human-friendly)
+export const TaskPriorityEnum = {
+  Low: "low",
+  Medium: "medium",
+  High: "high",
+} as const;
+
+export type TaskPriority =
+  (typeof TaskPriorityEnum)[keyof typeof TaskPriorityEnum];
+
+// ----- Task source (who created it)
+export const TaskSourceEnum = {
+  User: "user",
+  AutomationHub: "automation_hub",
+  System: "system",
+} as const;
+
+export type TaskSource = (typeof TaskSourceEnum)[keyof typeof TaskSourceEnum];
+
+// ----- Task execution mode
+export const TaskModeEnum = {
+  Human: "human",
+  Auto: "auto",
+} as const;
+
+export type TaskMode = (typeof TaskModeEnum)[keyof typeof TaskModeEnum];
+
+// ----- AUTO task handler (which executor processes the task)
+// Keep it open for future modules; these are logical handler identifiers.
+export const TaskAutoHandlerEnum = {
+  Notifications: "notifications",
+  AIAgent: "ai_agent",
+  Invoices: "invoices",
+  Webhook: "webhook",
+  Custom: "custom",
+} as const;
+
+export type TaskAutoHandler =
+  (typeof TaskAutoHandlerEnum)[keyof typeof TaskAutoHandlerEnum];
+
+// ----- Retry policy
+export const TaskRetryStrategyEnum = {
+  Fixed: "fixed",
+  Exponential: "exponential",
+} as const;
+
+export type TaskRetryStrategy =
+  (typeof TaskRetryStrategyEnum)[keyof typeof TaskRetryStrategyEnum];
+
+export interface ITaskRetryPolicy {
+  max_attempts: number; // total attempts allowed (including first attempt)
+  attempt: number; // 0-based attempt counter
+  strategy: TaskRetryStrategy;
+  backoff_seconds: number; // base backoff in seconds
+  next_attempt_at?: Date; // computed by Task Runner
+  last_error?: {
+    message: string;
+    code?: string | number;
+    at: Date;
+    details?: Record<string, unknown>;
+  };
+  [key: string]: unknown;
 }
 
-// Interface for Task Priority
-export type TaskPriority = "low" | "medium" | "high";
-export enum ITaskPriority {
-  Low = "low",
-  Medium = "medium",
-  High = "high",
+// ----- Lock/lease control (to avoid double execution)
+export interface ITaskLock {
+  locked_by: string; // worker id / instance id
+  lock_until: Date; // lease expiration time
+  [key: string]: unknown;
 }
 
-// Enum for IA Task Type
-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 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",
+// ----- Dedup / suppression (optional)
+export const TaskDedupScopeEnum = {
+  PerRecipient: "per_recipient",
+  PerRecipientAndObject: "per_recipient_and_object",
+  Custom: "custom",
+} as const;
+
+export type TaskDedupScope =
+  (typeof TaskDedupScopeEnum)[keyof typeof TaskDedupScopeEnum];
+
+export const TaskDedupWindowEnum = {
+  SameDay: "same_day",
+  NHours: "n_hours",
+  Custom: "custom",
+} as const;
+
+export type TaskDedupWindow =
+  (typeof TaskDedupWindowEnum)[keyof typeof TaskDedupWindowEnum];
+
+export interface ITaskDedup {
+  enabled: boolean;
+  key: string; // deterministic key used for suppression
+  group_key?: string; // e.g. "APPT_REMINDER"
+  scope?: TaskDedupScope;
+  window?: TaskDedupWindow;
+  window_hours?: number; // when window = n_hours
+  importance?: number; // numeric tie-breaker (0-100)
+  [key: string]: unknown;
 }
 
-// Enum for External Object Type (for task links)
+// ----- External object links (for unified UI views)
+export const TaskExternalObjectTypeEnum = {
+  CrmLead: "crm_lead",
+  MedPatient: "med_patient",
+  MedProfessional: "med_professional",
+  MedAppointment: "med_appointment",
+  ChatContact: "chat_contact",
+} as const;
+
 export type TaskExternalObjectType =
-  | "crm_lead"
-  | "med_patient"
-  | "med_professional"
-  | "med_appointment"
-  | "chat_contact";
-
-export enum ITaskExternalObjectType {
-  CrmLead = "crm_lead",
-  MedPatient = "med_patient",
-  MedProfessional = "med_professional",
-  MedAppointment = "med_appointment",
-  ChatContact = "chat_contact",
-}
+  (typeof TaskExternalObjectTypeEnum)[keyof typeof TaskExternalObjectTypeEnum];
 
-// Interface for External Object Link
 export interface ITaskExternalLink {
-  type: TaskExternalObjectType; // Type of external object
-  id: string; // ID of the linked object
-  [key: string]: unknown; // index signature
+  type: TaskExternalObjectType;
+  id: string;
+  label?: string;
+  [key: string]: unknown;
+}
+
+// ----- Assignee (human)
+export interface ITaskUserAssignee {
+  kind: "user";
+  name?: string;
+  ref?: FirestoreDocumentReference;
+  [key: string]: unknown;
+}
+
+// ----- Common schedule fields
+export interface ITaskSchedule {
+  execute_at?: Date; // when AUTO tasks should run (Task Runner uses this)
+  due_at?: Date; // optional deadline (also used for human tasks)
+  timezone?: string; // optional IANA timezone
+  [key: string]: unknown;
+}
+
+// ----- AUTO execution contract (generic)
+// The concrete payload schema for each handler/kind should live in its own module.
+export interface ITaskAutoSpec {
+  handler: TaskAutoHandler;
+  kind: string; // e.g. "notification.send", "ai.execute", "invoice.issue"
+  version?: number | string;
+  payload: Record<string, unknown>;
+  idempotency_key?: string; // used by the handler to deduplicate provider calls
+  [key: string]: unknown;
 }
 
-// Interface for Task Instances (taskInstances)
-export interface ITask extends IFireDoc {
-  title: string; // Title of the task
-  description?: string; // Optional description of the task
-  creatorName: string; // Name of the user who created the task
-  creatorRef?: FirestoreDocumentReference; // reference to the user who created the task
-  startDate: Date; // Start date and time of the task
-  dueDate?: Date; // Optional due date and time of the task
-  status: TaskStatus; // Status of the task
-  priority?: TaskPriority; // Priority of the task (optional)
-  assigneeName?: string; // Name of the assignee (optional)
-  assigneeRef?: FirestoreDocumentReference; // Reference to the assignee (optional)
+// ----- Failure handling / handoff (generic)
+export interface ITaskOnFailure {
+  // Task Runner can optionally create/convert into a HUMAN task.
+  handoff_to_user?: {
+    name?: string;
+    ref?: FirestoreDocumentReference;
+  };
+
+  create_handoff_task?: {
+    title?: string;
+    description?: string;
+    priority?: TaskPriority;
+    tags?: ITag[] | null;
+  };
+
+  // Optional fallbacks the Task Runner may attempt (still AUTO).
+  auto_fallbacks?: Array<{
+    handler: TaskAutoHandler;
+    kind: string;
+    payload: Record<string, unknown>;
+  }>;
+
+  [key: string]: unknown;
+}
+
+// ----- Base task shape
+export interface ITaskBase extends IFireDoc {
+  title: string;
+  description?: string;
+  status: TaskStatus;
+
+  // Human-friendly priority + numeric tie-breaker (optional)
+  priority?: TaskPriority;
+  importance?: number; // 0-100 (recommended for automation tie-breakers)
+
+  // Who created it
+  source: TaskSource;
+  creator: {
+    name: string;
+    ref?: FirestoreDocumentReference;
+  };
+
+  // Scheduling / deadlines
+  schedule?: ITaskSchedule;
+
+  // Links and taxonomy
   tags?: ITag[] | null;
-  // IA (Inteligência Artificial) related fields
-  ia_assigned?: boolean; // Indicates if the task is assigned to an AI agent
-  ia_agent?: string; // Identifier/name of the AI agent assigned to the task
-  ia_duescheduled?: Date; // Scheduled due date for AI execution
-  ia_task_type?: IATaskType; // Type of AI task to be executed
-  ia_result?: string; // Result/output from AI execution
-  ia_result_code?: number; // Result code from AI execution (e.g., HTTP status, error code)
-  ia_started_at?: Date; // Timestamp when AI started processing the task
-  ia_completed_at?: Date; // Timestamp when AI completed processing the task
-  ia_error?: string; // Error message if AI execution failed
-  ia_retry_count?: number; // Number of retry attempts for AI execution
-  ia_metadata?: Record<string, unknown>; // Additional metadata about AI execution
-  ia_prompt?: string; // Prompt used for AI task execution
-  ia_model?: string; // AI model used for task execution
-  ia_progress?: number; // Progress percentage (0-100) of AI task execution
-  // External object links
-  externalLinks?: ITaskExternalLink[]; // Array of links to external objects
-  [key: string]: unknown; // index signature
+  externalLinks?: ITaskExternalLink[];
+
+  // Optional deterministic key to avoid duplicates on rebuild/events
+  idempotency_key?: string;
+
+  // Optional dedup configuration
+  dedup?: ITaskDedup;
+
+  // Free metadata
+  metadata?: Record<string, unknown>;
+
+  [key: string]: unknown;
+}
+
+// ----- HUMAN task
+export interface IHumanTask extends ITaskBase {
+  mode: "human";
+  assignee?: ITaskUserAssignee;
 }
 
-// Interface for Task Comments (sub-collection in Firestore)
+// ----- AUTO task
+export interface IAutoTask extends ITaskBase {
+  mode: "auto";
+
+  // Required for AUTO execution
+  schedule: ITaskSchedule & {
+    execute_at: Date;
+  };
+
+  // Execution control
+  lock?: ITaskLock;
+  retry?: ITaskRetryPolicy;
+  on_failure?: ITaskOnFailure;
+
+  // What to execute
+  auto: ITaskAutoSpec;
+}
+
+// Union task type
+export type ITask = IHumanTask | IAutoTask;
+
+// ----- Task execution attempts (sub-collection: tasks/{taskId}/executions)
+export const TaskExecutionStatusEnum = {
+  Success: "success",
+  Error: "error",
+  Retry: "retry",
+} as const;
+
+export type TaskExecutionStatus =
+  (typeof TaskExecutionStatusEnum)[keyof typeof TaskExecutionStatusEnum];
+
+export interface ITaskExecution extends IFireDoc {
+  taskId: string;
+  handler: TaskAutoHandler;
+  kind: string; // mirrors task.auto.kind
+  status: TaskExecutionStatus;
+  attempt: number;
+  started_at: Date;
+  completed_at?: Date;
+
+  // Handler-specific outputs/errors (keep concise)
+  result?: Record<string, unknown>;
+  error?: {
+    message: string;
+    code?: string | number;
+    details?: Record<string, unknown>;
+  };
+
+  // Optional provider metadata (e.g. WhatsApp provider message id)
+  provider?: {
+    name?: string;
+    message_id?: string;
+    [key: string]: unknown;
+  };
+
+  [key: string]: unknown;
+}
+
+// ----- Task comments (sub-collection: tasks/{taskId}/comments)
 export interface ITaskComment extends IFireDoc {
-  taskId: string; // ID of the task
-  text: string; // Comment text content
-  authorName: string; // Name of the user who created the comment
-  authorRef?: FirestoreDocumentReference; // Reference to the user who created the comment
-  edited?: boolean; // Indicates if the comment was edited
-  edited_at?: Date; // Timestamp when the comment was last edited
-  [key: string]: unknown; // index signature
+  taskId: string;
+  text: string;
+  author: {
+    name: string;
+    ref?: FirestoreDocumentReference;
+  };
+  edited?: boolean;
+  edited_at?: Date;
+  [key: string]: unknown;
+}
+
+// ----- Task logs (optional sub-collection: tasks/{taskId}/logs)
+export interface ITaskLog extends IFireDoc {
+  taskId: string;
+  level: "debug" | "info" | "warn" | "error";
+  message: string;
+  data?: Record<string, unknown>;
+  at: Date;
+  [key: string]: unknown;
 }