evo360-types 1.3.324 → 1.3.328

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

@@ -0,0 +1,71 @@
+"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.OBLIGATORY_CAPABILITIES = exports.SYNC_RUN_HANDLER = exports.SYNC_RUN_PUBSUB_TOPIC = exports.EvoIntegrationsPermissions = void 0;
+exports.isInternalCapability = isInternalCapability;
+exports.splitCapabilityName = splitCapabilityName;
+__exportStar(require("./fb_collections"), exports);
+// ======================================================
+// evo-integrations
+//
+// Padroniza integração com sistemas externos de agenda/prontuário
+// (iClinic, Feegow, MedX, ...). Feat-004.
+//
+// Arquitetura em 4 pilares:
+// 1. Adapter registry global (Nexus-managed, /platform/evo-integrations/adapters)
+// 2. Credential vault (Google Secret Manager; n8n lê via SA direto)
+// 3. Sync engine (handler do evo-task-runner; janelas hot/warm/recent_reconcile/cold)
+// 4. Action envelope (dispatcher transparente — uma URL fixa pra consumers)
+// ======================================================
+// ----- Permissions
+exports.EvoIntegrationsPermissions = {
+    List: "evo_integrations_read",
+    Get: "evo_integrations_read",
+    Create: "evo_integrations_write",
+    Update: "evo_integrations_write",
+    Delete: "evo_integrations_write",
+    InvokeAction: "evo_integrations_action_invoke",
+};
+// ----- PubSub topics
+// 1 evento por sync run, sink em BigQuery (hr-evo360.evo_log.evo_integrations_sync_runs).
+exports.SYNC_RUN_PUBSUB_TOPIC = "evo-integrations.sync_runs";
+// Handler do evo-task-runner — resolve pro tópico ${handler}.execute_requests.
+exports.SYNC_RUN_HANDLER = "evo-integrations.sync-run";
+/**
+ * Capabilities obrigatórias em qualquer adapter. Sem elas, o adapter
+ * não pode ser ativado. `appointment.get` é fundamental pra auto-deleção
+ * confiável via get-after-diff.
+ */
+exports.OBLIGATORY_CAPABILITIES = [
+    "appointment.get",
+    "appointment.create",
+    "appointment.update",
+    "appointment.cancel",
+    "appointment.confirm",
+    "patient.get",
+    "sync.appointments",
+];
+/**
+ * Capabilities internas (não expostas via action dispatcher — apenas
+ * via sync engine / task-runner).
+ */
+function isInternalCapability(name) {
+    return name === "sync.appointments";
+}
+function splitCapabilityName(name) {
+    const [entity, ...rest] = name.split(".");
+    return { entity: entity, action: rest.join(".") };
+}

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

@@ -0,0 +1,232 @@
+export * from "./fb_collections";
+import type { IFireDoc } from "../shared";
+
+// ======================================================
+// evo-integrations
+//
+// Padroniza integração com sistemas externos de agenda/prontuário
+// (iClinic, Feegow, MedX, ...). Feat-004.
+//
+// Arquitetura em 4 pilares:
+// 1. Adapter registry global (Nexus-managed, /platform/evo-integrations/adapters)
+// 2. Credential vault (Google Secret Manager; n8n lê via SA direto)
+// 3. Sync engine (handler do evo-task-runner; janelas hot/warm/recent_reconcile/cold)
+// 4. Action envelope (dispatcher transparente — uma URL fixa pra consumers)
+// ======================================================
+
+// ----- Permissions
+export const EvoIntegrationsPermissions = {
+  List: "evo_integrations_read",
+  Get: "evo_integrations_read",
+  Create: "evo_integrations_write",
+  Update: "evo_integrations_write",
+  Delete: "evo_integrations_write",
+  InvokeAction: "evo_integrations_action_invoke",
+} as const;
+
+export type EvoIntegrationsPermissions =
+  (typeof EvoIntegrationsPermissions)[keyof typeof EvoIntegrationsPermissions];
+
+// ----- PubSub topics
+// 1 evento por sync run, sink em BigQuery (hr-evo360.evo_log.evo_integrations_sync_runs).
+export const SYNC_RUN_PUBSUB_TOPIC = "evo-integrations.sync_runs";
+
+// Handler do evo-task-runner — resolve pro tópico ${handler}.execute_requests.
+export const SYNC_RUN_HANDLER = "evo-integrations.sync-run";
+
+// ======================================================
+// Capabilities — nomenclatura {entity}.{action}
+// ======================================================
+
+export type CapabilityEntity = "appointment" | "patient" | "payment" | "sync";
+
+export type CapabilityName =
+  | "appointment.get"
+  | "appointment.list"
+  | "appointment.create"
+  | "appointment.update"
+  | "appointment.cancel"
+  | "appointment.confirm"
+  | "appointment.reschedule"
+  | "patient.get"
+  | "patient.list"
+  | "patient.create"
+  | "patient.update"
+  | "patient.document.upload"
+  | "payment.update"
+  | "sync.appointments";
+
+/**
+ * Capabilities obrigatórias em qualquer adapter. Sem elas, o adapter
+ * não pode ser ativado. `appointment.get` é fundamental pra auto-deleção
+ * confiável via get-after-diff.
+ */
+export const OBLIGATORY_CAPABILITIES: readonly CapabilityName[] = [
+  "appointment.get",
+  "appointment.create",
+  "appointment.update",
+  "appointment.cancel",
+  "appointment.confirm",
+  "patient.get",
+  "sync.appointments",
+] as const;
+
+/**
+ * Capabilities internas (não expostas via action dispatcher — apenas
+ * via sync engine / task-runner).
+ */
+export function isInternalCapability(name: CapabilityName): boolean {
+  return name === "sync.appointments";
+}
+
+export function splitCapabilityName(name: CapabilityName): {
+  entity: CapabilityEntity;
+  action: string;
+} {
+  const [entity, ...rest] = name.split(".");
+  return { entity: entity as CapabilityEntity, action: rest.join(".") };
+}
+
+// ======================================================
+// Adapter — contrato declarativo
+// Código do adapter vive em @evo/model/evo-integrations/adapters/{id}.
+// Doc correspondente em Firestore (/platform/evo-integrations/adapters/{id})
+// pode overrider URLs default sem deploy.
+// ======================================================
+
+export type AdapterCategory = "clinic-agenda" | "prontuario" | "misc";
+export type AdapterStatus = "active" | "disabled" | "beta";
+
+/**
+ * Doc Firestore global do adapter, gerenciado pela Nexus UI.
+ * Path: /platform/evo-integrations/adapters/{adapter_id}
+ */
+export interface IIntegrationsAdapterDoc extends IFireDoc {
+  name: string;
+  description?: string;
+  category: AdapterCategory;
+  status: AdapterStatus;
+  /** Semver string do código do adapter (distinto do `version` numérico do IFireDoc). */
+  adapter_version: string;
+  /**
+   * URLs default dos workflows n8n por capability.
+   * Precedência: calendar.integration.workflow_overrides → este doc → adapter code default.
+   */
+  default_workflow_urls: Partial<Record<CapabilityName, string>>;
+  supported_capabilities: readonly CapabilityName[];
+  auth_schema_version?: number;
+}
+
+// ======================================================
+// Credential — metadados. Raw creds vivem no Google Secret Manager.
+// Path: /tenants/{t}/apps/evo-med/integration-credentials/{cred_id}
+// ======================================================
+
+export type IntegrationCredentialStatus = "active" | "paused" | "revoked";
+
+export interface IIntegrationsCredential extends IFireDoc {
+  adapter_id: string;
+  name: string;
+  /**
+   * Referência ao secret no Google Secret Manager.
+   * Formato: projects/hr-evo360/secrets/evo-integrations-{tenant}-{cred_id}
+   */
+  secret_ref: string;
+  /** Config não-secreta (api_base, external_org_id, etc.). */
+  config?: Record<string, unknown>;
+  status: IntegrationCredentialStatus;
+  last_used_at?: Date | null;
+}
+
+// ======================================================
+// Sync state — 1 doc por calendar, mutável.
+// Path: /tenants/{t}/apps/evo-med/sync-states/{calendar_id}
+// ======================================================
+
+export type SyncWindowType = "hot" | "warm" | "recent_reconcile" | "cold";
+
+export interface ICoveredWindow {
+  start: Date;
+  end: Date;
+}
+
+export interface ISyncedHashes {
+  patients: Record<string, string>;
+  appointments: Record<string, string>;
+}
+
+export interface ISyncState extends IFireDoc {
+  calendar_id: string;
+  last_sync_at?: Date | null;
+  last_window_type?: SyncWindowType;
+  last_synced_hashes: ISyncedHashes;
+  last_coveredWindow?: ICoveredWindow | null;
+}
+
+// ======================================================
+// Sync run event — publicado no SYNC_RUN_PUBSUB_TOPIC ao final de cada run.
+// Schema espelha a tabela BigQuery (hr-evo360.evo_log.evo_integrations_sync_runs).
+// ======================================================
+
+export type SyncRunStatus = "success" | "partial" | "error";
+
+export interface ISyncRunEventError {
+  code?: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export interface ISyncRunEvent {
+  run_id: string;
+  tenant: string;
+  calendar_id: string;
+  adapter_id: string;
+  window_type: SyncWindowType;
+  started_at: Date;
+  finished_at: Date;
+  status: SyncRunStatus;
+  patients_upserted: number;
+  appointments_upserted: number;
+  appointments_skipped: number;
+  deletions_detected: number;
+  coveredWindow_start?: Date;
+  coveredWindow_end?: Date;
+  duration_ms: number;
+  firestore_reads: number;
+  firestore_writes: number;
+  n8n_calls: number;
+  errors?: ISyncRunEventError[];
+}
+
+// ======================================================
+// Calendar integration config — vive inline no calendar doc.
+// Ver IMedCalendar em evo-types/src/types/evo-med/calendar.
+// ======================================================
+
+export interface ISyncWindowConfig {
+  enabled: boolean;
+  /** Cadência em minutos. Ex.: hot=60, warm=360, cold=10080 (semanal). */
+  cadence_minutes: number;
+  /** Janela absoluta em dias a partir de "hoje". */
+  window_days: {
+    past: number;
+    future: number;
+  };
+}
+
+export interface ISyncConfig {
+  hot?: ISyncWindowConfig;
+  warm?: ISyncWindowConfig;
+  recent_reconcile?: ISyncWindowConfig;
+  cold?: ISyncWindowConfig;
+}
+
+export interface IMedCalendarIntegration {
+  adapter_id: string;
+  credentials_id: string;
+  /** Prefixo opcional pra namespacing de patient_id entre adapters/calendars. Default vazio. */
+  patient_prefix?: string;
+  sync_config: ISyncConfig;
+  /** Override por capability — precedência mais alta no resolver de URL. */
+  workflow_overrides?: Partial<Record<CapabilityName, string>>;
+}

package/dist/types/evo-med/calendar/index.d.ts

@@ -1,6 +1,7 @@
 export * from "../../evo-people/fb_collections";
 import type { FirestoreDocumentReference, IFireDoc, ITag } from "../../shared";
 import type { IAppointmentCounters } from "../people";
+import type { IMedCalendarIntegration } from "../../evo-integrations";
 export declare const EvoMedCalendarPermissions: {
     readonly List: "evo_med_calendar_read";
     readonly Get: "evo_med_calendar_read";
@@ -35,5 +36,6 @@ export interface IMedCalendar extends IFireDoc {
     appointmentCounters?: IAppointmentCounters | null;
     available_weekdays?: number[];
     available_for_hubia?: boolean;
+    integration?: IMedCalendarIntegration;
     [key: string]: unknown;
 }

package/dist/types/evo-med/calendar/index.ts

@@ -1,6 +1,7 @@
 export * from "../../evo-people/fb_collections";
 import type { FirestoreDocumentReference, IFireDoc, ITag } from "../../shared";
 import type { IAppointmentCounters } from "../people";
+import type { IMedCalendarIntegration } from "../../evo-integrations";
 
 // Permissões para o calendário
 export const EvoMedCalendarPermissions = {
@@ -44,5 +45,7 @@ export interface IMedCalendar extends IFireDoc {
   available_weekdays?: number[];
   // Se true, a agenda é elegível para oferecer horários via HubIA
   available_for_hubia?: boolean;
+  // Config de integração (feat-004 evo-integrations). Opcional — calendars legados mantêm n8n_wf/url/ext_urls.
+  integration?: IMedCalendarIntegration;
   [key: string]: unknown; // index signature
 }

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

@@ -22,6 +22,7 @@ export declare const TaskStatusEnum: {
     readonly Cancelled: "cancelled";
     readonly OnHold: "on_hold";
     readonly Suppressed: "suppressed";
+    readonly DeadLetter: "dead_letter";
 };
 export type TaskStatus = (typeof TaskStatusEnum)[keyof typeof TaskStatusEnum];
 export declare const TaskPriorityEnum: {
@@ -73,6 +74,13 @@ export interface ITaskLock {
     lock_until: Date;
     [key: string]: unknown;
 }
+export interface ITaskRunnerState {
+    reclaim_count?: number;
+    fallback_index?: number;
+    last_dispatch_at?: Date;
+    dispatched_attempts?: number;
+    [key: string]: unknown;
+}
 export declare const TaskDedupScopeEnum: {
     readonly PerRecipient: "per_recipient";
     readonly PerRecipientAndObject: "per_recipient_and_object";
@@ -167,6 +175,7 @@ export interface IAutoTask extends ITaskBase {
     lock?: ITaskLock;
     retry?: ITaskRetryPolicy;
     on_failure?: ITaskOnFailure;
+    runner_state?: ITaskRunnerState;
     auto: ITaskAutoSpec;
 }
 export type ITask = IHumanTask | IAutoTask;

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

@@ -50,6 +50,7 @@ exports.TaskStatusEnum = {
     Cancelled: "cancelled",
     OnHold: "on_hold",
     Suppressed: "suppressed", // intentionally skipped (e.g., dedup)
+    DeadLetter: "dead_letter", // unrecoverable after reclaim attempts
 };
 // ----- Task priority (human-friendly)
 exports.TaskPriorityEnum = {

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

@@ -48,6 +48,7 @@ export const TaskStatusEnum = {
   Cancelled: "cancelled",
   OnHold: "on_hold",
   Suppressed: "suppressed", // intentionally skipped (e.g., dedup)
+  DeadLetter: "dead_letter", // unrecoverable after reclaim attempts
 } as const;
 
 export type TaskStatus = (typeof TaskStatusEnum)[keyof typeof TaskStatusEnum];
@@ -123,6 +124,15 @@ export interface ITaskLock {
   [key: string]: unknown;
 }
 
+// ----- Runtime state maintained by the Task Runner
+export interface ITaskRunnerState {
+  reclaim_count?: number;
+  fallback_index?: number; // -1 = primary, 0..N = auto_fallbacks[i]
+  last_dispatch_at?: Date;
+  dispatched_attempts?: number;
+  [key: string]: unknown;
+}
+
 // ----- Dedup / suppression (optional)
 export const TaskDedupScopeEnum = {
   PerRecipient: "per_recipient",
@@ -276,6 +286,9 @@ export interface IAutoTask extends ITaskBase {
   retry?: ITaskRetryPolicy;
   on_failure?: ITaskOnFailure;
 
+  // Runtime state populated by the Task Runner
+  runner_state?: ITaskRunnerState;
+
   // What to execute
   auto: ITaskAutoSpec;
 }

package/dist/types/evo-task-runner/fb_collections.d.ts

@@ -0,0 +1 @@
+export declare const TASK_RUNNER_CONFIG_DOC = "config";

package/dist/types/evo-task-runner/fb_collections.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TASK_RUNNER_CONFIG_DOC = void 0;
+// Per-tenant task runner configuration.
+// Path: tenants/{tenant}/apps/evo-task-runner/config/config
+// - `config` subcollection reuses the shared CONFIG_COLLECTION ("config")
+// - TASK_RUNNER_CONFIG_DOC is the fixed doc id inside that subcollection
+exports.TASK_RUNNER_CONFIG_DOC = "config";

package/dist/types/evo-task-runner/fb_collections.ts

@@ -0,0 +1,5 @@
+// Per-tenant task runner configuration.
+// Path: tenants/{tenant}/apps/evo-task-runner/config/config
+// - `config` subcollection reuses the shared CONFIG_COLLECTION ("config")
+// - TASK_RUNNER_CONFIG_DOC is the fixed doc id inside that subcollection
+export const TASK_RUNNER_CONFIG_DOC = "config";

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

@@ -1,3 +1,4 @@
+export * from "./fb_collections";
 import type { IFireDoc } from "../shared";
 import type { TaskAutoHandler, TaskExecutionStatus, TaskRetryStrategy } from "../evo-task";
 export declare const EvoTaskRunnerPermissions: {
@@ -8,12 +9,15 @@ export declare const EvoTaskRunnerPermissions: {
     readonly Delete: "evo_task_runner_write";
 };
 export type EvoTaskRunnerPermissions = (typeof EvoTaskRunnerPermissions)[keyof typeof EvoTaskRunnerPermissions];
+export declare const EVO_TASK_RUNNER_APP = "evo-task-runner";
+export declare const TaskRunnerWorkerIdPrefix = "task-runner";
 export declare const TaskRunnerTopics: {
     readonly Tick: "task_runner.tick";
     readonly ExecuteRequests: "task_runner.execute_requests";
     readonly ExecutionReports: "task_runner.execution_reports";
 };
 export type TaskRunnerTopic = (typeof TaskRunnerTopics)[keyof typeof TaskRunnerTopics];
+export declare const taskRunnerHandlerTopic: (handler: string) => string;
 export declare const TaskRunnerTickReasonEnum: {
     readonly Schedule: "schedule";
     readonly Manual: "manual";

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

@@ -1,6 +1,21 @@
 "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.TaskRunnerTickReasonEnum = exports.TaskRunnerTopics = exports.EvoTaskRunnerPermissions = void 0;
+exports.TaskRunnerTickReasonEnum = exports.taskRunnerHandlerTopic = exports.TaskRunnerTopics = exports.TaskRunnerWorkerIdPrefix = exports.EVO_TASK_RUNNER_APP = exports.EvoTaskRunnerPermissions = void 0;
+__exportStar(require("./fb_collections"), exports);
 // Permissões para o task runner
 exports.EvoTaskRunnerPermissions = {
     List: "evo_task_runner_read",
@@ -21,12 +36,19 @@ exports.EvoTaskRunnerPermissions = {
 // - Task payload schemas live in their respective modules.
 // - This contract is handler-agnostic and safe to share between backend/frontend.
 // ======================================================
+// ----- App identifier (Firestore path: tenants/{t}/apps/evo-task-runner/...)
+exports.EVO_TASK_RUNNER_APP = "evo-task-runner";
+// ----- Prefix used to compose worker ids (e.g. `${prefix}-${K_SERVICE}-${uuid}`)
+exports.TaskRunnerWorkerIdPrefix = "task-runner";
 // ----- Pub/Sub topic suggestions (logical names)
 exports.TaskRunnerTopics = {
     Tick: "task_runner.tick",
     ExecuteRequests: "task_runner.execute_requests",
     ExecutionReports: "task_runner.execution_reports",
 };
+// ----- Per-handler execute requests topic (one topic per handler id)
+const taskRunnerHandlerTopic = (handler) => `${handler}.execute_requests`;
+exports.taskRunnerHandlerTopic = taskRunnerHandlerTopic;
 // ----- Runner tick messages (optional)
 exports.TaskRunnerTickReasonEnum = {
     Schedule: "schedule",

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

@@ -1,3 +1,4 @@
+export * from "./fb_collections";
 import type { IFireDoc } from "../shared";
 import type {
   TaskAutoHandler,
@@ -29,6 +30,12 @@ export type EvoTaskRunnerPermissions =
 // - This contract is handler-agnostic and safe to share between backend/frontend.
 // ======================================================
 
+// ----- App identifier (Firestore path: tenants/{t}/apps/evo-task-runner/...)
+export const EVO_TASK_RUNNER_APP = "evo-task-runner";
+
+// ----- Prefix used to compose worker ids (e.g. `${prefix}-${K_SERVICE}-${uuid}`)
+export const TaskRunnerWorkerIdPrefix = "task-runner";
+
 // ----- Pub/Sub topic suggestions (logical names)
 export const TaskRunnerTopics = {
   Tick: "task_runner.tick",
@@ -39,6 +46,10 @@ export const TaskRunnerTopics = {
 export type TaskRunnerTopic =
   (typeof TaskRunnerTopics)[keyof typeof TaskRunnerTopics];
 
+// ----- Per-handler execute requests topic (one topic per handler id)
+export const taskRunnerHandlerTopic = (handler: string) =>
+  `${handler}.execute_requests`;
+
 // ----- Runner tick messages (optional)
 export const TaskRunnerTickReasonEnum = {
   Schedule: "schedule",

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

@@ -35,7 +35,7 @@ export declare enum ITenantStatus {
 }
 export interface ITenant extends IFireDoc {
     name: string;
-    base_tenant?: string;
+    base_tenant?: string | null;
     hidden?: boolean;
     readonly?: boolean;
     url_alias: string;

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

@@ -48,7 +48,7 @@ export enum ITenantStatus {
 
 export interface ITenant extends IFireDoc {
   name: string;
-  base_tenant?: string;
+  base_tenant?: string | null;
   hidden?: boolean;
   readonly?: boolean;
   url_alias: string;

package/package.json

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