@blackcode_sa/metaestetics-api 1.13.5 → 1.13.8

package/src/types/appointment/index.ts

@@ -1,481 +1,481 @@
-import { Timestamp, FieldValue } from 'firebase/firestore';
-import { ClinicInfo, PractitionerProfileInfo, PatientProfileInfo } from '../profile';
-import { ProcedureSummaryInfo } from '../procedure';
-import { Currency, type PricingMeasure } from '../../backoffice/types/static/pricing.types';
-import { BlockingCondition } from '../../backoffice/types/static/blocking-condition.types';
-import { Requirement } from '../../backoffice/types/requirement.types';
-import { FilledDocumentStatus } from '../documentation-templates';
-import type { ContraindicationDynamic, ProcedureFamily } from '../../backoffice';
-import type { MediaResource } from '../../services/media/media.service';
-import { string } from 'zod/v4';
-
-/**
- * Enum defining the possible statuses of an appointment.
- */
-export enum AppointmentStatus {
-  PENDING = 'pending', // 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_PATIENT_RESCHEDULED = 'canceled_patient_rescheduled', // Canceled by the patient and rescheduled by the clinic
-  CANCELED_CLINIC = 'canceled_clinic', // Canceled by the clinic/practitioner
-  NO_SHOW = 'no_show', // Patient did not attend
-  RESCHEDULED_BY_CLINIC = 'rescheduled_by_clinic', // When appointment is rescheduled by the clinic, waiting for patient confirmation or cancellation (when reschedule is accepted, status goes to confirmed, if not accepted, then status goes to canceled_patient_rescheduled)
-}
-
-/**
- * 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
-}
-
-/**
- * Enum for different types of media that can be attached to an appointment.
- */
-export enum MediaType {
-  BEFORE_PHOTO = 'before_photo',
-  AFTER_PHOTO = 'after_photo',
-  CONSENT_SCAN = 'consent_scan',
-  OTHER_DOCUMENT = 'other_document',
-}
-
-/**
- * Interface to describe a media file linked to an appointment.
- */
-export interface AppointmentMediaItem {
-  id: string; // Auto-generated unique ID for the media item
-  type: MediaType;
-  url: string; // Cloud Storage URL
-  fileName?: string;
-  uploadedAt: Timestamp;
-  uploadedBy: string; // User ID (patient, practitioner, or clinic_admin)
-  description?: string;
-}
-
-/**
- * Interface for procedure-specific information
- */
-export interface ProcedureExtendedInfo {
-  id: string;
-  name: string;
-  description: string;
-  cost: number;
-  duration: number;
-  procedureFamily: ProcedureFamily;
-  procedureCategoryId: string;
-  procedureCategoryName: string;
-  procedureSubCategoryId: string;
-  procedureSubCategoryName: string;
-  procedureTechnologyId: string;
-  procedureTechnologyName: string;
-  procedureProductBrandId: string;
-  procedureProductBrandName: string;
-  procedureProducts: Array<{
-    productId: string;
-    productName: string;
-    brandId: string;
-    brandName: string;
-  }>;
-}
-
-/**
- * Interface to describe a filled form linked to an appointment.
- */
-export interface LinkedFormInfo {
-  formId: string; // ID of the FilledDocument
-  templateId: string;
-  templateVersion: number;
-  title: string; // For display, usually from DocumentTemplate.title
-  isUserForm: boolean;
-  isRequired?: boolean;
-  sortingOrder?: number;
-  status: FilledDocumentStatus; // Status of the filled form (e.g., draft, completed, signed)
-  path: string; // Full Firestore path to the filled document (e.g., appointments/{aid}/user-forms/{fid})
-  submittedAt?: Timestamp;
-  completedAt?: Timestamp; // When the form reached a final state like 'completed' or 'signed'
-}
-
-/**
- * Interface for summarized patient review information linked to an appointment.
- */
-export interface PatientReviewInfo {
-  reviewId: string; // ID of the full review document/record if stored elsewhere
-  rating: number; // e.g., 1-5 stars
-  comment?: string; // A short snippet or the full comment
-  reviewedAt: Timestamp;
-}
-
-/**
- * Interface for before/after photos and notes per zone
- */
-export interface BeforeAfterPerZone {
-  /** URL for before photo or null if not available */
-  before: MediaResource | null;
-  /** URL for after photo or null if not available */
-  after: MediaResource | null;
-  /** Optional note for the zone */
-  afterNote?: string | null;
-  beforeNote?: string | null;
-}
-
-/**
- * Interface for zone photo upload data
- */
-export interface ZonePhotoUploadData {
-  appointmentId: string;
-  zoneId: string;
-  photoType: 'before' | 'after';
-  file: File | Blob;
-  notes?: string;
-}
-
-/**
- * Interface for zone item data (products or notes per zone)
- */
-export interface ZoneItemData {
-  productId?: string;
-  productName?: string;
-  productBrandId?: string;
-  productBrandName?: string;
-  belongingProcedureId: string;
-  type: 'item' | 'note';
-  stage?: 'before' | 'after'; // Stage of the note/item: 'before' for planning notes, 'after' for treatment notes
-  price?: number;
-  currency?: Currency;
-  unitOfMeasurement?: PricingMeasure;
-  priceOverrideAmount?: number; // If set, takes precedence over price
-  quantity?: number;
-  parentZone: string; // Zone key in format "category.zone" (e.g., "face.forehead")
-  subzones: string[];
-  notes?: string;
-  subtotal?: number;
-  ionNumber?: string;
-  createdAt?: string; // ISO timestamp
-  updatedAt?: string; // ISO timestamp
-}
-
-/**
- * @deprecated Use ZoneItemData instead
- */
-export interface BillingPerZone {
-  Product: string;
-  ProductId: string | null;
-  Quantity: number;
-  UnitOfMeasurement: PricingMeasure;
-  UnitPrice: number;
-  UnitCurency: Currency;
-  Subtotal: number;
-  Note: string | null;
-  IonNumber: string | null;
-}
-
-/**
- * Interface for final billing calculations of the appointment
- */
-export interface FinalBilling {
-  /** Total of all subtotals from all zones */
-  subtotalAll: number;
-  /** Tax rate as percentage (e.g., 0.20 for 20%) */
-  taxRate: number;
-  /** Calculated tax amount */
-  taxPrice: number;
-  /** Final price including tax */
-  finalPrice: number;
-  /** Currency for the final billing */
-  currency: Currency;
-}
-
-/**
- * Interface for product metadata in appointment
- */
-export interface AppointmentProductMetadata {
-  productId: string;
-  productName: string;
-  brandId: string;
-  brandName: string;
-  procedureId: string;
-  price: number;
-  currency: Currency;
-  unitOfMeasurement: PricingMeasure;
-}
-
-/**
- * Interface for extended procedures in appointment
- */
-export interface ExtendedProcedureInfo {
-  procedureId: string;
-  procedureName: string;
-  procedureFamily?: ProcedureFamily;
-  procedureCategoryId: string;
-  procedureCategoryName: string;
-  procedureSubCategoryId: string;
-  procedureSubCategoryName: string;
-  procedureTechnologyId: string;
-  procedureTechnologyName: string;
-  procedureProducts: Array<{
-    productId: string;
-    productName: string;
-    brandId: string;
-    brandName: string;
-  }>;
-}
-
-export interface RecommendedProcedure {
-  procedure: ExtendedProcedureInfo;
-  note: string;
-  timeframe: {
-    value: number;
-    unit: 'day' | 'week' | 'month' | 'year';
-  };
-}
-
-/**
- * Interface for appointment metadata containing zone-specific information
- */
-export interface AppointmentMetadata {
-  selectedZones: string[] | null;
-  zonePhotos: Record<string, BeforeAfterPerZone[]> | null;
-  zonesData?: Record<string, ZoneItemData[]> | null;
-  appointmentProducts?: AppointmentProductMetadata[];
-  extendedProcedures?: ExtendedProcedureInfo[];
-  recommendedProcedures: RecommendedProcedure[]
-  finalbilling: FinalBilling | null;
-  finalizationNotes: string | null;
-
-  /**
-   * @deprecated Use zonesData instead
-   */
-  zoneBilling?: Record<string, BillingPerZone> | null;
-}
-
-/**
- * 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;
-  /** IANA timezone of the clinic */
-  clinic_tz: string;
-
-  /** 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; // Aggregated procedure information
-  /** Extended procedure information */
-  procedureExtendedInfo: ProcedureExtendedInfo; // Aggregated extended procedure information
-
-  /** Status of the appointment */
-  status: AppointmentStatus;
-
-  /** Timestamps */
-  bookingTime: Timestamp;
-  confirmationTime?: Timestamp | null;
-  cancellationTime?: Timestamp | null;
-  rescheduleTime?: Timestamp | null;
-  appointmentStartTime: Timestamp;
-  appointmentEndTime: Timestamp;
-  procedureActualStartTime?: Timestamp | null; // NEW: Actual start time of the procedure
-  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: ContraindicationDynamic[];
-  preProcedureRequirements: Requirement[];
-  postProcedureRequirements: Requirement[];
-
-  /** Tracking information for requirements completion */
-  completedPreRequirements?: string[]; // IDs of completed pre-requirements
-  completedPostRequirements?: string[]; // IDs of completed post-requirements
-
-  /** NEW: Linked forms (consent, procedure-specific forms, etc.) */
-  linkedFormIds?: string[];
-  linkedForms?: LinkedFormInfo[];
-  pendingUserFormsIds?: string[]; // Determines if there are any user forms that are pending for this appointment, blocks the appointment from being checked in (only for user forms with isRequired = true)
-
-  /** NEW: Media items (before/after photos, scanned documents, etc.) */
-  media?: AppointmentMediaItem[];
-
-  /** NEW: Information about the patient's review for this appointment */
-  reviewInfo?: PatientReviewInfo | null;
-
-  /** NEW: Details about the finalization of the appointment by the practitioner */
-  finalizedDetails?: {
-    by: string; // Practitioner User ID
-    at: Timestamp;
-    notes?: string;
-  };
-
-  /** Timestamps for record creation and updates */
-  createdAt: Timestamp;
-  updatedAt: Timestamp;
-
-  /** Recurring appointment information */
-  isRecurring?: boolean;
-  recurringAppointmentId?: string | null;
-
-  /** NEW: Flag for soft deletion or archiving */
-  isArchived?: boolean;
-
-  /** NEW: Metadata for the appointment - used for area selection and photos */
-  metadata?: AppointmentMetadata;
-}
-
-/**
- * Data needed to create a new Appointment
- */
-export interface CreateAppointmentData {
-  clinicBranchId: string;
-  practitionerId: string;
-  patientId: string;
-  procedureId: string;
-  appointmentStartTime: Timestamp;
-  appointmentEndTime: Timestamp;
-  cost: number;
-  currency: Currency;
-  patientNotes?: string | null;
-  initialStatus: AppointmentStatus;
-  initialPaymentStatus?: PaymentStatus; // Defaults to UNPAID if not provided
-  clinic_tz: string;
-}
-
-/**
- * Data needed to create a new Appointment via CreateAppointmentHttp method
- */
-export interface CreateAppointmentHttpData {
-  patientId: string;
-  procedureId: string;
-  appointmentStartTime: Timestamp;
-  appointmentEndTime: Timestamp;
-  patientNotes?: string | null;
-}
-
-/**
- * Data allowed for updating an Appointment
- */
-export interface UpdateAppointmentData {
-  status?: AppointmentStatus;
-  confirmationTime?: Timestamp | FieldValue | null;
-  cancellationTime?: Timestamp | FieldValue | null;
-  rescheduleTime?: Timestamp | FieldValue | null;
-  procedureActualStartTime?: Timestamp | FieldValue | null; // NEW
-  actualDurationMinutes?: number;
-  cancellationReason?: string | null;
-  canceledBy?: 'patient' | 'clinic' | 'practitioner' | 'system';
-  internalNotes?: string | null;
-  patientNotes?: string | FieldValue | null; // Allow FieldValue for deleting
-  paymentStatus?: PaymentStatus;
-  paymentTransactionId?: string | FieldValue | null;
-  completedPreRequirements?: string[] | FieldValue; // Allow FieldValue for arrayUnion/arrayRemove
-  completedPostRequirements?: string[] | FieldValue;
-  appointmentStartTime?: Timestamp; // For rescheduling
-  appointmentEndTime?: Timestamp; // For rescheduling
-  calendarEventId?: string; // If calendar event needs to be re-linked
-  cost?: number; // If cost is adjusted
-  clinicBranchId?: string; // If appointment is moved to another branch (complex scenario)
-  practitionerId?: string; // If practitioner is changed
-  clinic_tz?: string;
-
-  /** NEW: For updating linked forms - typically managed by dedicated methods */
-  linkedFormIds?: string[] | FieldValue;
-  linkedForms?: LinkedFormInfo[] | FieldValue;
-
-  /** NEW: For updating media items - typically managed by dedicated methods */
-  media?: AppointmentMediaItem[] | FieldValue;
-
-  /** NEW: For adding/updating review information */
-  reviewInfo?: PatientReviewInfo | FieldValue | null;
-
-  /** NEW: For setting practitioner finalization details */
-  finalizedDetails?: { by: string; at: Timestamp; notes?: string } | FieldValue;
-
-  /** NEW: For archiving/unarchiving */
-  isArchived?: boolean;
-
-  updatedAt?: FieldValue; // To set server timestamp
-
-  /** NEW: For updating metadata */
-  metadata?: AppointmentMetadata;
-}
-
-/**
- * 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';
-
-/**
- * Interface for next steps recommendation with context about when and who suggested it
- */
-export interface NextStepsRecommendation {
-  /** Unique identifier for this recommendation (appointmentId + recommendationIndex) */
-  id: string;
-  /** The recommended procedure details */
-  recommendedProcedure: RecommendedProcedure;
-  /** ID of the appointment where this was recommended */
-  appointmentId: string;
-  /** Date of the appointment when this was recommended */
-  appointmentDate: Timestamp;
-  /** ID of the practitioner who made the recommendation */
-  practitionerId: string;
-  /** Name of the practitioner who made the recommendation */
-  practitionerName: string;
-  /** ID of the clinic where the appointment took place */
-  clinicBranchId: string;
-  /** Name of the clinic where the appointment took place */
-  clinicName: string;
-  /** Status of the appointment when recommendation was made */
-  appointmentStatus: AppointmentStatus;
-  /** Whether this recommendation has been dismissed by the patient */
-  isDismissed?: boolean;
-  /** When the recommendation was dismissed (if dismissed) */
-  dismissedAt?: Timestamp | null;
+import { Timestamp, FieldValue } from 'firebase/firestore';
+import { ClinicInfo, PractitionerProfileInfo, PatientProfileInfo } from '../profile';
+import { ProcedureSummaryInfo } from '../procedure';
+import { Currency, type PricingMeasure } from '../../backoffice/types/static/pricing.types';
+import { BlockingCondition } from '../../backoffice/types/static/blocking-condition.types';
+import { Requirement } from '../../backoffice/types/requirement.types';
+import { FilledDocumentStatus } from '../documentation-templates';
+import type { ContraindicationDynamic, ProcedureFamily } from '../../backoffice';
+import type { MediaResource } from '../../services/media/media.service';
+import { string } from 'zod/v4';
+
+/**
+ * Enum defining the possible statuses of an appointment.
+ */
+export enum AppointmentStatus {
+  PENDING = 'pending', // 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_PATIENT_RESCHEDULED = 'canceled_patient_rescheduled', // Canceled by the patient and rescheduled by the clinic
+  CANCELED_CLINIC = 'canceled_clinic', // Canceled by the clinic/practitioner
+  NO_SHOW = 'no_show', // Patient did not attend
+  RESCHEDULED_BY_CLINIC = 'rescheduled_by_clinic', // When appointment is rescheduled by the clinic, waiting for patient confirmation or cancellation (when reschedule is accepted, status goes to confirmed, if not accepted, then status goes to canceled_patient_rescheduled)
+}
+
+/**
+ * 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
+}
+
+/**
+ * Enum for different types of media that can be attached to an appointment.
+ */
+export enum MediaType {
+  BEFORE_PHOTO = 'before_photo',
+  AFTER_PHOTO = 'after_photo',
+  CONSENT_SCAN = 'consent_scan',
+  OTHER_DOCUMENT = 'other_document',
+}
+
+/**
+ * Interface to describe a media file linked to an appointment.
+ */
+export interface AppointmentMediaItem {
+  id: string; // Auto-generated unique ID for the media item
+  type: MediaType;
+  url: string; // Cloud Storage URL
+  fileName?: string;
+  uploadedAt: Timestamp;
+  uploadedBy: string; // User ID (patient, practitioner, or clinic_admin)
+  description?: string;
+}
+
+/**
+ * Interface for procedure-specific information
+ */
+export interface ProcedureExtendedInfo {
+  id: string;
+  name: string;
+  description: string;
+  cost: number;
+  duration: number;
+  procedureFamily: ProcedureFamily;
+  procedureCategoryId: string;
+  procedureCategoryName: string;
+  procedureSubCategoryId: string;
+  procedureSubCategoryName: string;
+  procedureTechnologyId: string;
+  procedureTechnologyName: string;
+  procedureProductBrandId: string;
+  procedureProductBrandName: string;
+  procedureProducts: Array<{
+    productId: string;
+    productName: string;
+    brandId: string;
+    brandName: string;
+  }>;
+}
+
+/**
+ * Interface to describe a filled form linked to an appointment.
+ */
+export interface LinkedFormInfo {
+  formId: string; // ID of the FilledDocument
+  templateId: string;
+  templateVersion: number;
+  title: string; // For display, usually from DocumentTemplate.title
+  isUserForm: boolean;
+  isRequired?: boolean;
+  sortingOrder?: number;
+  status: FilledDocumentStatus; // Status of the filled form (e.g., draft, completed, signed)
+  path: string; // Full Firestore path to the filled document (e.g., appointments/{aid}/user-forms/{fid})
+  submittedAt?: Timestamp;
+  completedAt?: Timestamp; // When the form reached a final state like 'completed' or 'signed'
+}
+
+/**
+ * Interface for summarized patient review information linked to an appointment.
+ */
+export interface PatientReviewInfo {
+  reviewId: string; // ID of the full review document/record if stored elsewhere
+  rating: number; // e.g., 1-5 stars
+  comment?: string; // A short snippet or the full comment
+  reviewedAt: Timestamp;
+}
+
+/**
+ * Interface for before/after photos and notes per zone
+ */
+export interface BeforeAfterPerZone {
+  /** URL for before photo or null if not available */
+  before: MediaResource | null;
+  /** URL for after photo or null if not available */
+  after: MediaResource | null;
+  /** Optional note for the zone */
+  afterNote?: string | null;
+  beforeNote?: string | null;
+}
+
+/**
+ * Interface for zone photo upload data
+ */
+export interface ZonePhotoUploadData {
+  appointmentId: string;
+  zoneId: string;
+  photoType: 'before' | 'after';
+  file: File | Blob;
+  notes?: string;
+}
+
+/**
+ * Interface for zone item data (products or notes per zone)
+ */
+export interface ZoneItemData {
+  productId?: string;
+  productName?: string;
+  productBrandId?: string;
+  productBrandName?: string;
+  belongingProcedureId: string;
+  type: 'item' | 'note';
+  stage?: 'before' | 'after'; // Stage of the note/item: 'before' for planning notes, 'after' for treatment notes
+  price?: number;
+  currency?: Currency;
+  unitOfMeasurement?: PricingMeasure;
+  priceOverrideAmount?: number; // If set, takes precedence over price
+  quantity?: number;
+  parentZone: string; // Zone key in format "category.zone" (e.g., "face.forehead")
+  subzones: string[];
+  notes?: string;
+  subtotal?: number;
+  ionNumber?: string;
+  createdAt?: string; // ISO timestamp
+  updatedAt?: string; // ISO timestamp
+}
+
+/**
+ * @deprecated Use ZoneItemData instead
+ */
+export interface BillingPerZone {
+  Product: string;
+  ProductId: string | null;
+  Quantity: number;
+  UnitOfMeasurement: PricingMeasure;
+  UnitPrice: number;
+  UnitCurency: Currency;
+  Subtotal: number;
+  Note: string | null;
+  IonNumber: string | null;
+}
+
+/**
+ * Interface for final billing calculations of the appointment
+ */
+export interface FinalBilling {
+  /** Total of all subtotals from all zones */
+  subtotalAll: number;
+  /** Tax rate as percentage (e.g., 0.20 for 20%) */
+  taxRate: number;
+  /** Calculated tax amount */
+  taxPrice: number;
+  /** Final price including tax */
+  finalPrice: number;
+  /** Currency for the final billing */
+  currency: Currency;
+}
+
+/**
+ * Interface for product metadata in appointment
+ */
+export interface AppointmentProductMetadata {
+  productId: string;
+  productName: string;
+  brandId: string;
+  brandName: string;
+  procedureId: string;
+  price: number;
+  currency: Currency;
+  unitOfMeasurement: PricingMeasure;
+}
+
+/**
+ * Interface for extended procedures in appointment
+ */
+export interface ExtendedProcedureInfo {
+  procedureId: string;
+  procedureName: string;
+  procedureFamily?: ProcedureFamily;
+  procedureCategoryId: string;
+  procedureCategoryName: string;
+  procedureSubCategoryId: string;
+  procedureSubCategoryName: string;
+  procedureTechnologyId: string;
+  procedureTechnologyName: string;
+  procedureProducts: Array<{
+    productId: string;
+    productName: string;
+    brandId: string;
+    brandName: string;
+  }>;
+}
+
+export interface RecommendedProcedure {
+  procedure: ExtendedProcedureInfo;
+  note: string;
+  timeframe: {
+    value: number;
+    unit: 'day' | 'week' | 'month' | 'year';
+  };
+}
+
+/**
+ * Interface for appointment metadata containing zone-specific information
+ */
+export interface AppointmentMetadata {
+  selectedZones: string[] | null;
+  zonePhotos: Record<string, BeforeAfterPerZone[]> | null;
+  zonesData?: Record<string, ZoneItemData[]> | null;
+  appointmentProducts?: AppointmentProductMetadata[];
+  extendedProcedures?: ExtendedProcedureInfo[];
+  recommendedProcedures: RecommendedProcedure[]
+  finalbilling: FinalBilling | null;
+  finalizationNotes: string | null;
+
+  /**
+   * @deprecated Use zonesData instead
+   */
+  zoneBilling?: Record<string, BillingPerZone> | null;
+}
+
+/**
+ * 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;
+  /** IANA timezone of the clinic */
+  clinic_tz: string;
+
+  /** 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; // Aggregated procedure information
+  /** Extended procedure information */
+  procedureExtendedInfo: ProcedureExtendedInfo; // Aggregated extended procedure information
+
+  /** Status of the appointment */
+  status: AppointmentStatus;
+
+  /** Timestamps */
+  bookingTime: Timestamp;
+  confirmationTime?: Timestamp | null;
+  cancellationTime?: Timestamp | null;
+  rescheduleTime?: Timestamp | null;
+  appointmentStartTime: Timestamp;
+  appointmentEndTime: Timestamp;
+  procedureActualStartTime?: Timestamp | null; // NEW: Actual start time of the procedure
+  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: ContraindicationDynamic[];
+  preProcedureRequirements: Requirement[];
+  postProcedureRequirements: Requirement[];
+
+  /** Tracking information for requirements completion */
+  completedPreRequirements?: string[]; // IDs of completed pre-requirements
+  completedPostRequirements?: string[]; // IDs of completed post-requirements
+
+  /** NEW: Linked forms (consent, procedure-specific forms, etc.) */
+  linkedFormIds?: string[];
+  linkedForms?: LinkedFormInfo[];
+  pendingUserFormsIds?: string[]; // Determines if there are any user forms that are pending for this appointment, blocks the appointment from being checked in (only for user forms with isRequired = true)
+
+  /** NEW: Media items (before/after photos, scanned documents, etc.) */
+  media?: AppointmentMediaItem[];
+
+  /** NEW: Information about the patient's review for this appointment */
+  reviewInfo?: PatientReviewInfo | null;
+
+  /** NEW: Details about the finalization of the appointment by the practitioner */
+  finalizedDetails?: {
+    by: string; // Practitioner User ID
+    at: Timestamp;
+    notes?: string;
+  };
+
+  /** Timestamps for record creation and updates */
+  createdAt: Timestamp;
+  updatedAt: Timestamp;
+
+  /** Recurring appointment information */
+  isRecurring?: boolean;
+  recurringAppointmentId?: string | null;
+
+  /** NEW: Flag for soft deletion or archiving */
+  isArchived?: boolean;
+
+  /** NEW: Metadata for the appointment - used for area selection and photos */
+  metadata?: AppointmentMetadata;
+}
+
+/**
+ * Data needed to create a new Appointment
+ */
+export interface CreateAppointmentData {
+  clinicBranchId: string;
+  practitionerId: string;
+  patientId: string;
+  procedureId: string;
+  appointmentStartTime: Timestamp;
+  appointmentEndTime: Timestamp;
+  cost: number;
+  currency: Currency;
+  patientNotes?: string | null;
+  initialStatus: AppointmentStatus;
+  initialPaymentStatus?: PaymentStatus; // Defaults to UNPAID if not provided
+  clinic_tz: string;
+}
+
+/**
+ * Data needed to create a new Appointment via CreateAppointmentHttp method
+ */
+export interface CreateAppointmentHttpData {
+  patientId: string;
+  procedureId: string;
+  appointmentStartTime: Timestamp;
+  appointmentEndTime: Timestamp;
+  patientNotes?: string | null;
+}
+
+/**
+ * Data allowed for updating an Appointment
+ */
+export interface UpdateAppointmentData {
+  status?: AppointmentStatus;
+  confirmationTime?: Timestamp | FieldValue | null;
+  cancellationTime?: Timestamp | FieldValue | null;
+  rescheduleTime?: Timestamp | FieldValue | null;
+  procedureActualStartTime?: Timestamp | FieldValue | null; // NEW
+  actualDurationMinutes?: number;
+  cancellationReason?: string | null;
+  canceledBy?: 'patient' | 'clinic' | 'practitioner' | 'system';
+  internalNotes?: string | null;
+  patientNotes?: string | FieldValue | null; // Allow FieldValue for deleting
+  paymentStatus?: PaymentStatus;
+  paymentTransactionId?: string | FieldValue | null;
+  completedPreRequirements?: string[] | FieldValue; // Allow FieldValue for arrayUnion/arrayRemove
+  completedPostRequirements?: string[] | FieldValue;
+  appointmentStartTime?: Timestamp; // For rescheduling
+  appointmentEndTime?: Timestamp; // For rescheduling
+  calendarEventId?: string; // If calendar event needs to be re-linked
+  cost?: number; // If cost is adjusted
+  clinicBranchId?: string; // If appointment is moved to another branch (complex scenario)
+  practitionerId?: string; // If practitioner is changed
+  clinic_tz?: string;
+
+  /** NEW: For updating linked forms - typically managed by dedicated methods */
+  linkedFormIds?: string[] | FieldValue;
+  linkedForms?: LinkedFormInfo[] | FieldValue;
+
+  /** NEW: For updating media items - typically managed by dedicated methods */
+  media?: AppointmentMediaItem[] | FieldValue;
+
+  /** NEW: For adding/updating review information */
+  reviewInfo?: PatientReviewInfo | FieldValue | null;
+
+  /** NEW: For setting practitioner finalization details */
+  finalizedDetails?: { by: string; at: Timestamp; notes?: string } | FieldValue;
+
+  /** NEW: For archiving/unarchiving */
+  isArchived?: boolean;
+
+  updatedAt?: FieldValue; // To set server timestamp
+
+  /** NEW: For updating metadata */
+  metadata?: AppointmentMetadata;
+}
+
+/**
+ * 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';
+
+/**
+ * Interface for next steps recommendation with context about when and who suggested it
+ */
+export interface NextStepsRecommendation {
+  /** Unique identifier for this recommendation (appointmentId + recommendationIndex) */
+  id: string;
+  /** The recommended procedure details */
+  recommendedProcedure: RecommendedProcedure;
+  /** ID of the appointment where this was recommended */
+  appointmentId: string;
+  /** Date of the appointment when this was recommended */
+  appointmentDate: Timestamp;
+  /** ID of the practitioner who made the recommendation */
+  practitionerId: string;
+  /** Name of the practitioner who made the recommendation */
+  practitionerName: string;
+  /** ID of the clinic where the appointment took place */
+  clinicBranchId: string;
+  /** Name of the clinic where the appointment took place */
+  clinicName: string;
+  /** Status of the appointment when recommendation was made */
+  appointmentStatus: AppointmentStatus;
+  /** Whether this recommendation has been dismissed by the patient */
+  isDismissed?: boolean;
+  /** When the recommendation was dismissed (if dismissed) */
+  dismissedAt?: Timestamp | null;
 }