evo360-types 1.3.143 → 1.3.144

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

@@ -0,0 +1,144 @@
+import type { FirestoreDocumentReference, IFireDoc } from "../shared";
+export declare const EvoNotificationsCollections: {
+    readonly Messages: "messages";
+    readonly Attempts: "attempts";
+    readonly Logs: "logs";
+};
+export type EvoNotificationsCollectionName = (typeof EvoNotificationsCollections)[keyof typeof EvoNotificationsCollections];
+export declare const NotificationTaskKindEnum: {
+    readonly Send: "notification.send";
+};
+export type NotificationTaskKind = (typeof NotificationTaskKindEnum)[keyof typeof NotificationTaskKindEnum];
+export declare const NotificationsTopics: {
+    readonly ExecuteRequests: "notifications.execute_requests";
+    readonly ExecutionReports: "notifications.execution_reports";
+    readonly ProviderWebhooks: "notifications.provider_webhooks";
+};
+export type NotificationsTopic = (typeof NotificationsTopics)[keyof typeof NotificationsTopics];
+export declare const NotificationChannelTypeEnum: {
+    readonly WhatsApp: "whatsapp";
+    readonly Email: "email";
+    readonly SMS: "sms";
+    readonly Push: "push";
+};
+export type NotificationChannelType = (typeof NotificationChannelTypeEnum)[keyof typeof NotificationChannelTypeEnum];
+export declare const NotificationMessageStatusEnum: {
+    readonly Queued: "queued";
+    readonly Processing: "processing";
+    readonly Sent: "sent";
+    readonly Delivered: "delivered";
+    readonly Failed: "failed";
+    readonly Cancelled: "cancelled";
+    readonly Suppressed: "suppressed";
+};
+export type NotificationMessageStatus = (typeof NotificationMessageStatusEnum)[keyof typeof NotificationMessageStatusEnum];
+export declare const NotificationAttemptStatusEnum: {
+    readonly Success: "success";
+    readonly Retry: "retry";
+    readonly Error: "error";
+};
+export type NotificationAttemptStatus = (typeof NotificationAttemptStatusEnum)[keyof typeof NotificationAttemptStatusEnum];
+export declare const NotificationRecipientKindEnum: {
+    readonly Patient: "patient";
+    readonly Professional: "professional";
+    readonly Preconfigured: "preconfigured";
+    readonly Raw: "raw";
+};
+export type NotificationRecipientKind = (typeof NotificationRecipientKindEnum)[keyof typeof NotificationRecipientKindEnum];
+export interface INotificationRecipient {
+    kind: NotificationRecipientKind;
+    id?: string;
+    ref?: FirestoreDocumentReference;
+    address?: string;
+    display_name?: string;
+    [key: string]: unknown;
+}
+export interface INotificationChannelRef {
+    type: NotificationChannelType;
+    channel_id: string;
+    sender_id?: string;
+    [key: string]: unknown;
+}
+export interface INotificationTemplateRef {
+    template_id: string;
+    locale?: string;
+    version?: number | string;
+    [key: string]: unknown;
+}
+export interface INotificationProviderMeta {
+    name?: string;
+    message_id?: string;
+    status?: string;
+    raw?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface INotificationError {
+    message: string;
+    code?: string | number;
+    details?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface INotificationSendPayload {
+    kind: "notification.send";
+    classification?: string;
+    importance?: number;
+    recipient: INotificationRecipient;
+    channel: INotificationChannelRef;
+    template?: INotificationTemplateRef;
+    variables?: Record<string, unknown>;
+    routine?: {
+        id: string;
+        version?: number | string;
+        [key: string]: unknown;
+    };
+    idempotency_key?: string;
+    dedup_key?: string;
+    dedup_group_key?: string;
+    [key: string]: unknown;
+}
+export interface INotificationMessage extends IFireDoc {
+    tenant: string;
+    task_id?: string;
+    routine_id?: string;
+    routine_version?: number | string;
+    classification?: string;
+    importance?: number;
+    channel: INotificationChannelRef;
+    template?: INotificationTemplateRef;
+    recipient: INotificationRecipient;
+    variables?: Record<string, unknown>;
+    status: NotificationMessageStatus;
+    queued_at: Date;
+    processing_started_at?: Date;
+    sent_at?: Date;
+    delivered_at?: Date;
+    completed_at?: Date;
+    provider?: INotificationProviderMeta;
+    error?: INotificationError;
+    dedup_key?: string;
+    dedup_group_key?: string;
+    date_bucket?: string;
+    [key: string]: unknown;
+}
+export interface INotificationAttempt extends IFireDoc {
+    message_id: string;
+    task_id?: string;
+    attempt: number;
+    status: NotificationAttemptStatus;
+    requested_at: Date;
+    started_at?: Date;
+    finished_at?: Date;
+    provider?: INotificationProviderMeta;
+    error?: INotificationError;
+    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-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;
+}