evo360-types 1.3.407 → 1.3.408

package/dist/types/hub-automation/index.js

@@ -0,0 +1,86 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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.AutomationRunStatusEnum = exports.AutomationOutputTypeEnum = exports.AutomationOperatorEnum = exports.AUTOMATION_APPOINTMENT_FACTS = exports.HubAutomationPermissions = void 0;
+__exportStar(require("./fb_collections"), exports);
+// ======================================================
+// hub-automation
+//
+// Declarative automation routines that MATERIALIZE Tasks (no side effects —
+// every effect on the world flows through the Task Runner, decision Q1).
+//
+// A routine is: a TRIGGER (F1: cron) + a SELECTION of domain targets
+// (F1: appointments) + nested condition BRANCHES → OUTPUTS (auto/human Tasks).
+//
+// NOTE:
+// - These are hand-written contracts (no z.infer). Zod schemas live in
+//   src/apps/hub-automation/zod-schemas.ts.
+// - F1 has no `patient.*` facts and no patient hydration (decision Q15):
+//   contact-data validation is the handler's responsibility at run time.
+// ======================================================
+// ----- Permissions (Firestore path: tenants/{t}/apps/hub-automation/...)
+exports.HubAutomationPermissions = {
+    Read: "hub_automation_read",
+    Write: "hub_automation_write",
+};
+// ------------------------------------------------------
+// Fact catalog (F1: appointment domain facts only — Q15: no patient.* facts)
+// ------------------------------------------------------
+exports.AUTOMATION_APPOINTMENT_FACTS = [
+    "appointment.status",
+    // Confirmation is a first-class fact via statusBase (Q9) — no dedicated field.
+    "appointment.status_base",
+    "appointment.appointment_type",
+    "appointment.appointment_base_type",
+    // 'telemedicine' | 'in_person'
+    "appointment.appointment_mode",
+    // Derived from professional.professionalRef.id
+    "appointment.professional_id",
+    "appointment.procedure_ids",
+    "appointment.payment_status",
+    "appointment.calendar_id",
+];
+// ------------------------------------------------------
+// Conditions (recursive AND/OR groups)
+// ------------------------------------------------------
+exports.AutomationOperatorEnum = {
+    Eq: "eq",
+    Neq: "neq",
+    In: "in",
+    NotIn: "not_in",
+    Exists: "exists",
+    NotExists: "not_exists",
+    IsTrue: "is_true",
+    IsFalse: "is_false",
+};
+// ------------------------------------------------------
+// Outputs (auto Task | human Task)
+// ------------------------------------------------------
+exports.AutomationOutputTypeEnum = {
+    AutoTask: "auto_task",
+    HumanTask: "human_task",
+};
+// ------------------------------------------------------
+// Run trace (Firestore doc: tenants/{t}/apps/hub-automation/runs/{runId})
+// One doc per run; trace kept as fields (not a subcollection). 1MB cap →
+// counts + capped samples, never a dump of every target.
+// ------------------------------------------------------
+exports.AutomationRunStatusEnum = {
+    Ok: "ok",
+    Limited: "limited",
+    BlockedDryRunRequired: "blocked_dry_run_required",
+    Error: "error",
+};

package/dist/types/hub-automation/index.ts

@@ -0,0 +1,312 @@
+export * from "./fb_collections";
+
+import type { TaskAutoHandler, ITaskRetryPolicy, ITaskOnFailure } from "../evo-task";
+
+// ======================================================
+// hub-automation
+//
+// Declarative automation routines that MATERIALIZE Tasks (no side effects —
+// every effect on the world flows through the Task Runner, decision Q1).
+//
+// A routine is: a TRIGGER (F1: cron) + a SELECTION of domain targets
+// (F1: appointments) + nested condition BRANCHES → OUTPUTS (auto/human Tasks).
+//
+// NOTE:
+// - These are hand-written contracts (no z.infer). Zod schemas live in
+//   src/apps/hub-automation/zod-schemas.ts.
+// - F1 has no `patient.*` facts and no patient hydration (decision Q15):
+//   contact-data validation is the handler's responsibility at run time.
+// ======================================================
+
+// ----- Permissions (Firestore path: tenants/{t}/apps/hub-automation/...)
+export const HubAutomationPermissions = {
+  Read: "hub_automation_read",
+  Write: "hub_automation_write",
+} as const;
+export type HubAutomationPermissions =
+  (typeof HubAutomationPermissions)[keyof typeof HubAutomationPermissions];
+
+// ------------------------------------------------------
+// Trigger (F1: cron only)
+// ------------------------------------------------------
+export interface IAutomationCronTrigger {
+  type: "cron";
+  cron: {
+    // Standard 5-field cron expression.
+    expression: string;
+    // IANA timezone; when omitted, the resolved tenant timezone is used.
+    timezone?: string;
+  };
+}
+
+export type IAutomationTrigger = IAutomationCronTrigger;
+
+// ------------------------------------------------------
+// Selection (F1: appointment target only)
+// ------------------------------------------------------
+
+// `calendar` → a single target date (runDate + offset), for clinics that
+//   run/notify on weekends.
+// `business` → an ARRAY of target dates via the D+X-Especial semantics
+//   (weekend anticipation/recovery); resolved by resolveTargetDates.
+export type AutomationDateOffsetMode = "calendar" | "business";
+
+export interface IAutomationDateWindow {
+  // May be negative (retroactive routines, e.g. post-consultation).
+  offset_days: number;
+  offset_mode: AutomationDateOffsetMode;
+}
+
+export interface IAutomationAppointmentSelection {
+  target: "appointment";
+  appointment: {
+    // Empty/omitted = all calendars of the tenant.
+    calendar_ids?: string[];
+    date_window: IAutomationDateWindow;
+    // Filters applied in memory over the day window (no server-side status query).
+    status_in?: string[];
+    status_base_in?: string[];
+    appointment_type_not_in?: string[];
+  };
+}
+
+export type IAutomationSelection = IAutomationAppointmentSelection;
+
+// ------------------------------------------------------
+// Fact catalog (F1: appointment domain facts only — Q15: no patient.* facts)
+// ------------------------------------------------------
+export const AUTOMATION_APPOINTMENT_FACTS = [
+  "appointment.status",
+  // Confirmation is a first-class fact via statusBase (Q9) — no dedicated field.
+  "appointment.status_base",
+  "appointment.appointment_type",
+  "appointment.appointment_base_type",
+  // 'telemedicine' | 'in_person'
+  "appointment.appointment_mode",
+  // Derived from professional.professionalRef.id
+  "appointment.professional_id",
+  "appointment.procedure_ids",
+  "appointment.payment_status",
+  "appointment.calendar_id",
+] as const;
+
+export type AutomationAppointmentFact =
+  (typeof AUTOMATION_APPOINTMENT_FACTS)[number];
+
+export type AutomationFact = AutomationAppointmentFact;
+
+// ------------------------------------------------------
+// Conditions (recursive AND/OR groups)
+// ------------------------------------------------------
+export const AutomationOperatorEnum = {
+  Eq: "eq",
+  Neq: "neq",
+  In: "in",
+  NotIn: "not_in",
+  Exists: "exists",
+  NotExists: "not_exists",
+  IsTrue: "is_true",
+  IsFalse: "is_false",
+} as const;
+
+export type AutomationOperator =
+  (typeof AutomationOperatorEnum)[keyof typeof AutomationOperatorEnum];
+
+export interface IAutomationCondition {
+  // A fact key from the catalog (AutomationFact); kept as string for forward
+  // compatibility with facts added in later slices.
+  fact: string;
+  operator: AutomationOperator;
+  // Not required for unary operators (exists/not_exists/is_true/is_false).
+  value?: unknown;
+}
+
+export type AutomationCombinator = "and" | "or";
+
+export interface IAutomationConditionGroup {
+  combinator: AutomationCombinator;
+  conditions: Array<IAutomationCondition | IAutomationConditionGroup>;
+}
+
+// ------------------------------------------------------
+// Outputs (auto Task | human Task)
+// ------------------------------------------------------
+export const AutomationOutputTypeEnum = {
+  AutoTask: "auto_task",
+  HumanTask: "human_task",
+} as const;
+
+export type AutomationOutputType =
+  (typeof AutomationOutputTypeEnum)[keyof typeof AutomationOutputTypeEnum];
+
+// When the materialized Task should execute:
+// - immediate: now (Task Runner picks it up on the next tick)
+// - send_at_local: HH:mm resolved in the tenant timezone, anchored to the
+//   target date or the run date.
+export type IAutomationExecuteAt =
+  | { rule: "immediate" }
+  | {
+      rule: "send_at_local";
+      // "HH:mm" (24h)
+      time: string;
+      base: "target_date" | "run_date";
+    };
+
+export interface IAutomationAutoTaskOutput {
+  type: "auto_task";
+  handler: TaskAutoHandler;
+  kind: string;
+  // Payload values that are strings accept refs: {{appointment.id}},
+  // {{appointment.calendar_id}}, {{patient.id}} (resolved by the materializer).
+  payload: Record<string, unknown>;
+  execute_at: IAutomationExecuteAt;
+  retry?: ITaskRetryPolicy;
+  on_failure?: ITaskOnFailure;
+}
+
+export interface IAutomationHumanTaskOutput {
+  type: "human_task";
+  title: string;
+  description?: string;
+  // Firestore path to the assignee user doc.
+  assignee_ref?: string;
+}
+
+export type IAutomationOutput =
+  | IAutomationAutoTaskOutput
+  | IAutomationHumanTaskOutput;
+
+// ------------------------------------------------------
+// Branches
+// ------------------------------------------------------
+export interface IAutomationBranch {
+  id: string;
+  name: string;
+  // Guard group; omitted = always matches (typical for a fallback branch).
+  when?: IAutomationConditionGroup;
+  // The "else" branch (fires when no other branch matched, exclusive mode).
+  is_fallback?: boolean;
+  outputs: IAutomationOutput[];
+}
+
+// 'all' = every matching branch fires; 'exclusive' = first match wins,
+// fallback catches the rest.
+export type AutomationBranchMode = "all" | "exclusive";
+
+// ------------------------------------------------------
+// Routine (Firestore doc: tenants/{t}/apps/hub-automation/routines/{id})
+// ------------------------------------------------------
+export interface IAutomationRoutine {
+  id: string;
+  name: string;
+  description?: string;
+  active: boolean;
+  // Routine's own version counter (bumped on edit; distinct from doc model_ver).
+  version: number;
+  trigger: IAutomationTrigger;
+  selection: IAutomationSelection;
+  branch_mode: AutomationBranchMode;
+  branches: IAutomationBranch[];
+  guards: {
+    max_tasks_per_run: number;
+  };
+  // Q11: presence gates materialization (dry-run required on first activation).
+  // `version` is stored for audit only (edits do not re-require a dry-run).
+  dry_run_stamp?: {
+    version: number;
+    at: Date;
+    by: string;
+  };
+  // Cron bookkeeping: last occurrence already fired by the sweeper.
+  trigger_state?: {
+    last_fired_at?: Date;
+  };
+  stats?: {
+    last_run_at?: Date;
+    last_materialized_at?: Date;
+    last_run_id?: string;
+  };
+  created_at: Date;
+  updated_at: Date;
+}
+
+// ------------------------------------------------------
+// Module config (Firestore doc: tenants/{t}/apps/hub-automation/config/config)
+// ------------------------------------------------------
+export interface IHubAutomationConfig {
+  active: boolean;
+  limits?: {
+    max_tasks_per_run_default?: number;
+  };
+}
+
+// ------------------------------------------------------
+// Run trace (Firestore doc: tenants/{t}/apps/hub-automation/runs/{runId})
+// One doc per run; trace kept as fields (not a subcollection). 1MB cap →
+// counts + capped samples, never a dump of every target.
+// ------------------------------------------------------
+export const AutomationRunStatusEnum = {
+  Ok: "ok",
+  Limited: "limited",
+  BlockedDryRunRequired: "blocked_dry_run_required",
+  Error: "error",
+} as const;
+
+export type AutomationRunStatus =
+  (typeof AutomationRunStatusEnum)[keyof typeof AutomationRunStatusEnum];
+
+// Per-condition evaluation result (shape mirrors HubIA's ConditionResult).
+export interface IAutomationConditionResult {
+  fact: string;
+  op: AutomationOperator;
+  value?: unknown;
+  actual?: unknown;
+  passed: boolean;
+}
+
+export interface IAutomationRunBranchCounts {
+  matched: number;
+  created: number;
+  already_existed: number;
+}
+
+export interface IAutomationRunSample {
+  appointment_id: string;
+  branch_id?: string;
+  // e.g. 'created' | 'already_existed' | 'not_matched' | 'suppressed_by_limit'
+  decision: string;
+  conditions?: IAutomationConditionResult[];
+  [key: string]: unknown;
+}
+
+export interface IAutomationRunTrace {
+  routine_id: string;
+  routine_version: number;
+  trigger: {
+    type: string;
+    fired_at: Date;
+    cron_expression?: string;
+  };
+  dry_run: boolean;
+  window: {
+    // Q16: a run may span multiple target dates (yyyy-MM-dd).
+    target_dates: string[];
+    timezone: string;
+  };
+  status: AutomationRunStatus;
+  counts: {
+    targets_scanned: number;
+    tasks_created: number;
+    tasks_already_existed: number;
+    tasks_suppressed_by_limit: number;
+    per_branch: Record<string, IAutomationRunBranchCounts>;
+  };
+  // Capped (~20/branch) — full detail goes to BigQuery.
+  samples?: IAutomationRunSample[];
+  error?: {
+    message: string;
+    code?: string | number;
+    details?: Record<string, unknown>;
+  };
+  duration_ms: number;
+}

package/package.json

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