@blackcode_sa/metaestetics-api 1.5.32 → 1.5.33

package/src/types/appointment/index.ts

@@ -0,0 +1,161 @@
+import { Timestamp, FieldValue } from "firebase/firestore";
+import {
+  ClinicInfo,
+  PractitionerProfileInfo,
+  PatientProfileInfo,
+} from "../profile";
+import { ProcedureSummaryInfo } from "../procedure";
+import { Currency } from "../../backoffice/types/static/pricing.types";
+import { CalendarEventStatus } from "../calendar";
+import { BlockingCondition } from "../../backoffice/types/static/blocking-condition.types";
+import { Contraindication } from "../../backoffice/types/static/contraindication.types";
+import { Requirement } from "../../backoffice/types/requirement.types";
+
+/**
+ * Enum defining the possible statuses of an appointment.
+ */
+export enum AppointmentStatus {
+  SCHEDULED = "scheduled", // Initial state after booking, before confirmation (if applicable)
+  CONFIRMED = "confirmed", // Confirmed by clinic/practitioner
+  CHECKED_IN = "checked_in", // Patient has arrived
+  IN_PROGRESS = "in_progress", // Procedure has started
+  COMPLETED = "completed", // Procedure finished successfully
+  CANCELED_PATIENT = "canceled_patient", // Canceled by the patient
+  CANCELED_CLINIC = "canceled_clinic", // Canceled by the clinic/practitioner
+  NO_SHOW = "no_show", // Patient did not attend
+  RESCHEDULED = "rescheduled", // Original appointment replaced by a new one
+}
+
+/**
+ * Enum defining the payment status of an appointment.
+ */
+export enum PaymentStatus {
+  UNPAID = "unpaid",
+  PAID = "paid",
+  PARTIALLY_PAID = "partially_paid",
+  REFUNDED = "refunded",
+  NOT_APPLICABLE = "not_applicable", // For free services or other scenarios
+}
+
+/**
+ * Represents a booked appointment, aggregating key information and relevant procedure rules.
+ */
+export interface Appointment {
+  /** Unique identifier for the appointment */
+  id: string;
+  /** Reference to the associated CalendarEvent */
+  calendarEventId: string;
+
+  /** ID of the clinic branch */
+  clinicBranchId: string;
+  /** Aggregated clinic information (snapshot) */
+  clinicInfo: ClinicInfo;
+
+  /** ID of the practitioner */
+  practitionerId: string;
+  /** Aggregated practitioner information (snapshot) */
+  practitionerInfo: PractitionerProfileInfo;
+
+  /** ID of the patient */
+  patientId: string;
+  /** Aggregated patient information (snapshot) */
+  patientInfo: PatientProfileInfo;
+
+  /** ID of the procedure */
+  procedureId: string;
+  /** Aggregated procedure information including product/brand (snapshot) */
+  procedureInfo: ProcedureSummaryInfo;
+
+  /** Status of the appointment */
+  status: AppointmentStatus;
+
+  /** Timestamps */
+  bookingTime: Timestamp;
+  confirmationTime?: Timestamp | null;
+  appointmentStartTime: Timestamp;
+  appointmentEndTime: Timestamp;
+  actualDurationMinutes?: number;
+
+  /** Cancellation Details */
+  cancellationReason?: string | null;
+  canceledBy?: "patient" | "clinic" | "practitioner" | "system";
+
+  /** Notes */
+  internalNotes?: string | null;
+  patientNotes?: string | null;
+
+  /** Payment Details */
+  cost: number;
+  currency: Currency;
+  paymentStatus: PaymentStatus;
+  paymentTransactionId?: string | null;
+
+  /** Procedure-related conditions and requirements */
+  blockingConditions: BlockingCondition[];
+  contraindications: Contraindication[];
+  preProcedureRequirements: Requirement[];
+  postProcedureRequirements: Requirement[];
+
+  /** Tracking information for requirements completion */
+  completedPreRequirements?: string[]; // IDs of completed pre-requirements
+  completedPostRequirements?: string[]; // IDs of completed post-requirements
+
+  /** Timestamps */
+  createdAt: Timestamp;
+  updatedAt: Timestamp;
+
+  /** Recurring appointment information */
+  isRecurring?: boolean;
+  recurringAppointmentId?: string | null;
+}
+
+/**
+ * Data needed to create a new Appointment
+ */
+export interface CreateAppointmentData {
+  calendarEventId: string;
+  clinicBranchId: string;
+  practitionerId: string;
+  patientId: string;
+  procedureId: string;
+  appointmentStartTime: Timestamp;
+  appointmentEndTime: Timestamp;
+  cost: number;
+  currency: Currency;
+  patientNotes?: string | null;
+  initialStatus: AppointmentStatus;
+  initialPaymentStatus?: PaymentStatus;
+}
+
+/**
+ * Data allowed for updating an Appointment
+ */
+export interface UpdateAppointmentData {
+  status?: AppointmentStatus;
+  confirmationTime?: Timestamp | null;
+  actualDurationMinutes?: number;
+  cancellationReason?: string | null;
+  canceledBy?: "patient" | "clinic" | "practitioner" | "system";
+  internalNotes?: string | null;
+  paymentStatus?: PaymentStatus;
+  paymentTransactionId?: string | null;
+  completedPreRequirements?: string[]; // IDs of pre-requirements to mark as completed
+  completedPostRequirements?: string[]; // IDs of post-requirements to mark as completed
+}
+
+/**
+ * Parameters for searching appointments
+ */
+export interface SearchAppointmentsParams {
+  patientId?: string;
+  practitionerId?: string;
+  clinicBranchId?: string;
+  startDate?: Date;
+  endDate?: Date;
+  status?: AppointmentStatus | AppointmentStatus[];
+  limit?: number;
+  startAfter?: any;
+}
+
+/** Firestore collection name */
+export const APPOINTMENTS_COLLECTION = "appointments";

package/src/types/procedure/index.ts

@@ -132,6 +132,8 @@ export interface ProcedureSummaryInfo {
   categoryName: string; // Use names for aggregation
   subcategoryName: string; // Use names for aggregation
   technologyName: string; // Use names for aggregation
+  brandName?: string; // Added: Name of the brand used (if applicable)
+  productName?: string; // Added: Name of the product used (if applicable)
   price: number;
   pricingMeasure: PricingMeasure;
   currency: Currency;

package/src/validations/appointment.schema.ts

@@ -0,0 +1,125 @@
+import { z } from "zod";
+import { AppointmentStatus, PaymentStatus } from "../types/appointment";
+
+/**
+ * Schema for validating appointment creation data
+ */
+export const createAppointmentSchema = z.object({
+  calendarEventId: z.string().min(1, "Calendar event ID is required"),
+  clinicBranchId: z.string().min(1, "Clinic branch ID is required"),
+  practitionerId: z.string().min(1, "Practitioner ID is required"),
+  patientId: z.string().min(1, "Patient ID is required"),
+  procedureId: z.string().min(1, "Procedure ID is required"),
+  appointmentStartTime: z
+    .any()
+    .refine(
+      (val) => val instanceof Date || val?._seconds !== undefined,
+      "Appointment start time must be a valid timestamp"
+    ),
+  appointmentEndTime: z
+    .any()
+    .refine(
+      (val) => val instanceof Date || val?._seconds !== undefined,
+      "Appointment end time must be a valid timestamp"
+    ),
+  cost: z.number().min(0, "Cost must be a non-negative number"),
+  currency: z.string().min(1, "Currency is required"),
+  patientNotes: z.string().nullable().optional(),
+  initialStatus: z.nativeEnum(AppointmentStatus, {
+    errorMap: () => ({ message: "Invalid appointment status" }),
+  }),
+  initialPaymentStatus: z
+    .nativeEnum(PaymentStatus, {
+      errorMap: () => ({ message: "Invalid payment status" }),
+    })
+    .optional()
+    .default(PaymentStatus.UNPAID),
+});
+
+/**
+ * Schema for validating appointment update data
+ */
+export const updateAppointmentSchema = z
+  .object({
+    status: z
+      .nativeEnum(AppointmentStatus, {
+        errorMap: () => ({ message: "Invalid appointment status" }),
+      })
+      .optional(),
+    confirmationTime: z
+      .any()
+      .refine(
+        (val) =>
+          val === null ||
+          val === undefined ||
+          val instanceof Date ||
+          val?._seconds !== undefined,
+        "Confirmation time must be a valid timestamp or null"
+      )
+      .optional(),
+    actualDurationMinutes: z
+      .number()
+      .positive("Duration must be positive")
+      .optional(),
+    cancellationReason: z.string().nullable().optional(),
+    canceledBy: z
+      .enum(["patient", "clinic", "practitioner", "system"])
+      .optional(),
+    internalNotes: z.string().nullable().optional(),
+    paymentStatus: z
+      .nativeEnum(PaymentStatus, {
+        errorMap: () => ({ message: "Invalid payment status" }),
+      })
+      .optional(),
+    paymentTransactionId: z.string().nullable().optional(),
+    completedPreRequirements: z.array(z.string()).optional(),
+    completedPostRequirements: z.array(z.string()).optional(),
+  })
+  .refine(
+    (data) => {
+      // If status is being set to canceled, make sure reason and canceledBy are provided
+      if (
+        data.status === AppointmentStatus.CANCELED_CLINIC ||
+        data.status === AppointmentStatus.CANCELED_PATIENT
+      ) {
+        return !!data.cancellationReason && !!data.canceledBy;
+      }
+      return true;
+    },
+    {
+      message:
+        "Cancellation reason and canceled by must be provided when canceling an appointment",
+      path: ["status"],
+    }
+  );
+
+/**
+ * Schema for validating appointment search parameters
+ */
+export const searchAppointmentsSchema = z
+  .object({
+    patientId: z.string().optional(),
+    practitionerId: z.string().optional(),
+    clinicBranchId: z.string().optional(),
+    startDate: z.date().optional(),
+    endDate: z.date().optional(),
+    status: z
+      .union([
+        z.nativeEnum(AppointmentStatus),
+        z.array(z.nativeEnum(AppointmentStatus)),
+      ])
+      .optional(),
+    limit: z.number().positive().optional(),
+    startAfter: z.any().optional(),
+  })
+  .refine(
+    (data) => {
+      // Ensure at least one search parameter is provided
+      return !!(data.patientId || data.practitionerId || data.clinicBranchId);
+    },
+    {
+      message:
+        "At least one of patientId, practitionerId, or clinicBranchId must be provided",
+      path: ["searchCriteria"],
+    }
+  );