@blackcode_sa/metaestetics-api 1.15.14 → 1.15.17-staging.0

package/src/validations/appointment.schema.ts

@@ -1,589 +1,589 @@
-import { z } from 'zod';
-import { AppointmentStatus, PaymentStatus, MediaType } from '../types/appointment';
-import { filledDocumentStatusSchema } from './documentation-templates.schema';
-import { Currency, PricingMeasure } from '../backoffice/types/static/pricing.types';
-import { mediaResourceSchema } from './media.schema';
-
-// Define common constants locally if not available from common.schema.ts
-const MIN_STRING_LENGTH = 1;
-const MAX_STRING_LENGTH = 1024; // Example value
-const MAX_STRING_LENGTH_LONG = 4096; // Example value for longer notes/comments
-const MAX_ARRAY_LENGTH = 100; // Example value
-
-// --- Enum Schemas ---
-export const appointmentStatusSchema = z.nativeEnum(AppointmentStatus);
-export const paymentStatusSchema = z.nativeEnum(PaymentStatus);
-export const mediaTypeSchema = z.nativeEnum(MediaType);
-
-// --- Schemas for Nested Objects from types/appointment/index.ts ---
-
-export const appointmentMediaItemSchema = z.object({
-  id: z.string().min(MIN_STRING_LENGTH, 'Media item ID is required'),
-  type: mediaTypeSchema,
-  url: z.string().url('Media URL must be a valid URL'),
-  fileName: z.string().optional(),
-  uploadedAt: z
-    .any()
-    .refine(
-      val =>
-        val instanceof Date ||
-        val?._seconds !== undefined ||
-        val?.seconds !== undefined ||
-        typeof val === 'number' ||
-        typeof val === 'string' ||
-        (val && typeof val.toMillis === 'function'),
-      'uploadedAt must be a valid timestamp or Date object',
-    ),
-  uploadedBy: z.string().min(MIN_STRING_LENGTH, 'Uploaded by user ID is required'),
-  description: z.string().max(MAX_STRING_LENGTH, 'Description too long').optional(),
-});
-
-export const procedureExtendedInfoSchema = z.object({
-  id: z.string().min(MIN_STRING_LENGTH),
-  name: z.string().min(MIN_STRING_LENGTH),
-  description: z.string(),
-  cost: z.number().min(0),
-  duration: z.number().min(0),
-  procedureFamily: z.any(),
-  procedureCategoryId: z.string(),
-  procedureCategoryName: z.string(),
-  procedureSubCategoryId: z.string(),
-  procedureSubCategoryName: z.string(),
-  procedureTechnologyId: z.string(),
-  procedureTechnologyName: z.string(),
-  procedureProductBrandId: z.string(),
-  procedureProductBrandName: z.string(),
-  procedureProducts: z.array(
-    z.object({
-      productId: z.string().min(MIN_STRING_LENGTH, 'Product ID is required'),
-      productName: z.string().min(MIN_STRING_LENGTH, 'Product name is required'),
-      brandId: z.string().min(MIN_STRING_LENGTH, 'Brand ID is required'),
-      brandName: z.string().min(MIN_STRING_LENGTH, 'Brand name is required'),
-    }),
-  ),
-});
-
-export const linkedFormInfoSchema = z.object({
-  formId: z.string().min(MIN_STRING_LENGTH, 'Form ID is required'),
-  templateId: z.string().min(MIN_STRING_LENGTH, 'Template ID is required'),
-  templateVersion: z.number().int().positive('Template version must be a positive integer'),
-  title: z.string().min(MIN_STRING_LENGTH, 'Form title is required'),
-  isUserForm: z.boolean(),
-  isRequired: z.boolean().optional(),
-  status: filledDocumentStatusSchema,
-  path: z.string().min(MIN_STRING_LENGTH, 'Form path is required'),
-  submittedAt: z
-    .any()
-    .refine(
-      val =>
-        val === undefined ||
-        val instanceof Date ||
-        val?._seconds !== undefined ||
-        val?.seconds !== undefined ||
-        typeof val === 'number' ||
-        typeof val === 'string' ||
-        (val && typeof val.toMillis === 'function'),
-      'submittedAt must be a valid timestamp or Date object',
-    )
-    .optional(),
-  completedAt: z
-    .any()
-    .refine(
-      val =>
-        val === undefined ||
-        val instanceof Date ||
-        val?._seconds !== undefined ||
-        val?.seconds !== undefined ||
-        typeof val === 'number' ||
-        typeof val === 'string' ||
-        (val && typeof val.toMillis === 'function'),
-      'completedAt must be a valid timestamp or Date object',
-    )
-    .optional(),
-});
-
-export const patientReviewInfoSchema = z.object({
-  reviewId: z.string().min(MIN_STRING_LENGTH, 'Review ID is required'),
-  rating: z.number().min(1).max(5, 'Rating must be between 1 and 5'),
-  comment: z.string().max(MAX_STRING_LENGTH_LONG, 'Comment too long').optional(),
-  reviewedAt: z
-    .any()
-    .refine(
-      val =>
-        val instanceof Date ||
-        val?._seconds !== undefined ||
-        val?.seconds !== undefined ||
-        typeof val === 'number' ||
-        typeof val === 'string' ||
-        (val && typeof val.toMillis === 'function'),
-      'reviewedAt must be a valid timestamp or Date object',
-    ),
-});
-
-export const finalizedDetailsSchema = z.object({
-  by: z.string().min(MIN_STRING_LENGTH, 'Finalized by user ID is required'),
-  at: z
-    .any()
-    .refine(
-      val =>
-        val instanceof Date ||
-        val?._seconds !== undefined ||
-        val?.seconds !== undefined ||
-        typeof val === 'number' ||
-        typeof val === 'string' ||
-        (val && typeof val.toMillis === 'function'),
-      'Finalized at must be a valid timestamp or Date object',
-    ),
-  notes: z.string().max(MAX_STRING_LENGTH_LONG, 'Finalization notes too long').optional(),
-});
-
-/**
- * Schema for before/after photos and notes per zone
- */
-export const beforeAfterPerZoneSchema = z.object({
-  before: mediaResourceSchema.nullable(),
-  after: mediaResourceSchema.nullable(),
-  beforeNote: z.string().nullable().optional(),
-  afterNote: z.string().nullable().optional(),
-  showToPatient: z.boolean().optional().default(false),
-  beforeNoteVisibleToPatient: z.boolean().optional().default(false),
-  afterNoteVisibleToPatient: z.boolean().optional().default(false),
-  visibilityUpdatedAt: z.any().optional(), // Timestamp
-  visibilityUpdatedBy: z.string().optional(),
-});
-
-/**
- * Schema for billing information per zone
- */
-export const billingPerZoneSchema = z.object({
-  Product: z.string().min(MIN_STRING_LENGTH, 'Product name is required'),
-  ProductId: z.string().nullable(),
-  Quantity: z.number().min(0, 'Quantity must be non-negative'),
-  UnitOfMeasurement: z.nativeEnum(PricingMeasure),
-  UnitPrice: z.number().min(0, 'Unit price must be non-negative'),
-  UnitCurency: z.nativeEnum(Currency),
-  Subtotal: z.number().min(0, 'Subtotal must be non-negative'),
-  Note: z.string().nullable(),
-  IonNumber: z.string().nullable(),
-});
-
-/**
- * Schema for final billing calculations of the appointment
- */
-export const finalBillingSchema = z.object({
-  subtotalAll: z.number().min(0, 'Subtotal all must be non-negative'),
-  discount: z.object({
-    type: z.enum(['percentage', 'fixed']),
-    value: z.number().min(0),
-    amount: z.number().min(0),
-  }).optional(),
-  discountedSubtotal: z.number().min(0).optional(),
-  taxRate: z.number().min(0).max(1, 'Tax rate must be between 0 and 1'),
-  taxPrice: z.number().min(0, 'Tax price must be non-negative'),
-  finalPrice: z.number().min(0, 'Final price must be non-negative'),
-  currency: z.nativeEnum(Currency),
-});
-
-/**
- * Schema for zone item data (product or note per zone)
- */
-export const zoneItemDataSchema = z
-  .object({
-    productId: z.string().optional(),
-    productName: z.string().optional(),
-    productBrandId: z.string().optional(),
-    productBrandName: z.string().optional(),
-    belongingProcedureId: z.string().min(MIN_STRING_LENGTH, 'Belonging procedure ID is required'),
-    type: z.enum(['item', 'note'], {
-      required_error: 'Type must be either "item" or "note"',
-    }),
-    stage: z
-      .enum(['before', 'after'], {
-        required_error: 'Stage must be either "before" or "after"',
-      })
-      .optional(),
-    price: z.number().min(0, 'Price must be non-negative').optional(),
-    currency: z.nativeEnum(Currency).optional(),
-    unitOfMeasurement: z.nativeEnum(PricingMeasure).optional(),
-    priceOverrideAmount: z.number().min(0, 'Price override amount must be non-negative').optional(),
-    quantity: z.number().min(0, 'Quantity must be non-negative').optional(),
-    parentZone: z
-      .string()
-      .min(MIN_STRING_LENGTH, 'Parent zone is required')
-      .refine(
-        val => {
-          const parts = val.split('.');
-          return parts.length === 2;
-        },
-        {
-          message: 'Parent zone must be in "category.zone" format (e.g., "face.forehead")',
-        },
-      ),
-    subzones: z.array(z.string()).refine(
-      val => {
-        return val.every(subzone => {
-          const parts = subzone.split('.');
-          return parts.length === 3;
-        });
-      },
-      {
-        message: 'Subzones must be in "category.zone.subzone" format (e.g., "face.forehead.left")',
-      },
-    ),
-    notes: z.string().max(MAX_STRING_LENGTH_LONG, 'Notes too long').optional(),
-    notesVisibleToPatient: z.boolean().optional().default(false),
-    subtotal: z.number().min(0, 'Subtotal must be non-negative').optional(),
-    ionNumber: z.string().nullable().optional(), // Batch/Lot number - can be null to clear/delete
-    expiryDate: z.string().nullable().optional(), // ISO date string (YYYY-MM-DD) - can be null to clear/delete
-    createdAt: z.string().optional(),
-    updatedAt: z.string().optional(),
-  })
-  .refine(
-    data => {
-      if (data.type === 'item') {
-        return !!(data.productId && data.productName && (data.price || data.priceOverrideAmount));
-      }
-      return true;
-    },
-    {
-      message: 'Item type requires productId, productName, and either price or priceOverrideAmount',
-    },
-  );
-
-/**
- * Schema for appointment product metadata
- */
-export const appointmentProductMetadataSchema = z.object({
-  productId: z.string().min(MIN_STRING_LENGTH, 'Product ID is required'),
-  productName: z.string().min(MIN_STRING_LENGTH, 'Product name is required'),
-  brandId: z.string().min(MIN_STRING_LENGTH, 'Brand ID is required'),
-  brandName: z.string().min(MIN_STRING_LENGTH, 'Brand name is required'),
-  procedureId: z.string().min(MIN_STRING_LENGTH, 'Procedure ID is required'),
-  price: z.number().min(0, 'Price must be non-negative'),
-  currency: z.nativeEnum(Currency),
-  unitOfMeasurement: z.nativeEnum(PricingMeasure),
-});
-
-/**
- * Schema for extended procedure info
- */
-export const extendedProcedureInfoSchema = z.object({
-  procedureId: z.string().min(MIN_STRING_LENGTH, 'Procedure ID is required'),
-  procedureName: z.string().min(MIN_STRING_LENGTH, 'Procedure name is required'),
-  procedureFamily: z.any(),
-  procedureCategoryId: z.string().min(MIN_STRING_LENGTH, 'Category ID is required'),
-  procedureCategoryName: z.string().min(MIN_STRING_LENGTH, 'Category name is required'),
-  procedureSubCategoryId: z.string().min(MIN_STRING_LENGTH, 'Subcategory ID is required'),
-  procedureSubCategoryName: z.string().min(MIN_STRING_LENGTH, 'Subcategory name is required'),
-  procedureTechnologyId: z.string().min(MIN_STRING_LENGTH, 'Technology ID is required'),
-  procedureTechnologyName: z.string().min(MIN_STRING_LENGTH, 'Technology name is required'),
-  procedureProducts: z.array(
-    z.object({
-      productId: z.string().min(MIN_STRING_LENGTH, 'Product ID is required'),
-      productName: z.string().min(MIN_STRING_LENGTH, 'Product name is required'),
-      brandId: z.string().min(MIN_STRING_LENGTH, 'Brand ID is required'),
-      brandName: z.string().min(MIN_STRING_LENGTH, 'Brand name is required'),
-    }),
-  ),
-});
-
-/**
- * Schema for recommended procedure within metadata
- */
-export const recommendedProcedureTimeframeSchema = z.object({
-  value: z.number().int().positive('Timeframe value must be a positive integer'),
-  unit: z.enum(['day', 'week', 'month', 'year']),
-});
-
-export const recommendedProcedureSchema = z.object({
-  procedure: extendedProcedureInfoSchema,
-  note: z.string().max(MAX_STRING_LENGTH_LONG, 'Note too long'), // Note is now optional (no min length)
-  timeframe: recommendedProcedureTimeframeSchema,
-});
-
-/**
- * Schema for appointment metadata containing zone-specific information
- */
-export const appointmentMetadataSchema = z.object({
-  selectedZones: z.array(z.string()).nullable(),
-  zonePhotos: z.record(z.string(), z.array(beforeAfterPerZoneSchema).max(10)).nullable(),
-  zonesData: z.record(z.string(), z.array(zoneItemDataSchema)).nullable().optional(),
-  appointmentProducts: z.array(appointmentProductMetadataSchema).optional().default([]),
-  extendedProcedures: z.array(extendedProcedureInfoSchema).optional().default([]),
-  recommendedProcedures: z.array(recommendedProcedureSchema).optional().default([]),
-  zoneBilling: z.record(z.string(), billingPerZoneSchema).nullable().optional(),
-  finalbilling: finalBillingSchema.nullable(),
-  finalizationNotesShared: z.string().nullable().optional(),
-  finalizationNotesInternal: z.string().nullable().optional(),
-  finalizationNotes: z.string().nullable().optional(), // @deprecated - kept for backward compatibility
-});
-
-// --- Main Appointment Schemas ---
-
-/**
- * Schema for validating appointment creation data
- */
-export const createAppointmentSchema = z
-  .object({
-    clinicBranchId: z.string().min(MIN_STRING_LENGTH, 'Clinic branch ID is required'),
-    practitionerId: z.string().min(MIN_STRING_LENGTH, 'Practitioner ID is required'),
-    patientId: z.string().min(MIN_STRING_LENGTH, 'Patient ID is required'),
-    procedureId: z.string().min(MIN_STRING_LENGTH, 'Procedure ID is required'),
-    appointmentStartTime: z
-      .any()
-      .refine(
-        val =>
-          val instanceof Date ||
-          val?._seconds !== undefined ||
-          val?.seconds !== undefined ||
-          typeof val === 'number' ||
-          typeof val === 'string' ||
-          (val && typeof val.toMillis === 'function'),
-        'Appointment start time must be a valid timestamp or Date object',
-      ),
-    appointmentEndTime: z
-      .any()
-      .refine(
-        val =>
-          val instanceof Date ||
-          val?._seconds !== undefined ||
-          val?.seconds !== undefined ||
-          typeof val === 'number' ||
-          typeof val === 'string' ||
-          (val && typeof val.toMillis === 'function'),
-        'Appointment end time must be a valid timestamp or Date object',
-      ),
-    cost: z.number().min(0, 'Cost must be a non-negative number'),
-    currency: z.string().min(1, 'Currency is required'),
-    patientNotes: z.string().max(MAX_STRING_LENGTH, 'Patient notes too long').nullable().optional(),
-    initialStatus: appointmentStatusSchema,
-    initialPaymentStatus: paymentStatusSchema.optional().default(PaymentStatus.UNPAID),
-    clinic_tz: z.string().min(1, 'Timezone is required'),
-  })
-  .refine(data => data.appointmentEndTime > data.appointmentStartTime, {
-    message: 'Appointment end time must be after start time',
-    path: ['appointmentEndTime'],
-  });
-
-/**
- * Schema for validating appointment update data
- */
-export const updateAppointmentSchema = z
-  .object({
-    status: appointmentStatusSchema.optional(),
-    confirmationTime: z.any().optional().nullable(),
-    cancellationTime: z.any().optional().nullable(),
-    rescheduleTime: z.any().optional().nullable(),
-    procedureActualStartTime: z.any().optional().nullable(),
-    actualDurationMinutes: z
-      .number()
-      .int()
-      .positive('Duration must be a positive integer')
-      .optional(),
-    cancellationReason: z
-      .string()
-      .max(MAX_STRING_LENGTH, 'Cancellation reason too long')
-      .nullable()
-      .optional(),
-    canceledBy: z.enum(['patient', 'clinic', 'practitioner', 'system']).optional(),
-    internalNotes: z
-      .string()
-      .max(MAX_STRING_LENGTH_LONG, 'Internal notes too long')
-      .nullable()
-      .optional(),
-    patientNotes: z.any().optional().nullable(),
-    paymentStatus: paymentStatusSchema.optional(),
-    paymentTransactionId: z.any().optional().nullable(),
-    completedPreRequirements: z.union([z.array(z.string()), z.any()]).optional(),
-    completedPostRequirements: z.union([z.array(z.string()), z.any()]).optional(),
-    linkedFormIds: z.union([z.array(z.string()), z.any()]).optional(),
-    pendingUserFormsIds: z.union([z.array(z.string()), z.any()]).optional(),
-    appointmentStartTime: z
-      .any()
-      .refine(
-        val =>
-          val === undefined ||
-          val instanceof Date ||
-          val?._seconds !== undefined ||
-          val?.seconds !== undefined ||
-          typeof val === 'number' ||
-          typeof val === 'string' ||
-          (val && typeof val.toMillis === 'function'),
-        'Appointment start time must be a valid timestamp or Date object',
-      )
-      .optional(),
-    appointmentEndTime: z
-      .any()
-      .refine(
-        val =>
-          val === undefined ||
-          val instanceof Date ||
-          val?._seconds !== undefined ||
-          val?.seconds !== undefined ||
-          typeof val === 'number' ||
-          typeof val === 'string' ||
-          (val && typeof val.toMillis === 'function'),
-        'Appointment end time must be a valid timestamp or Date object',
-      )
-      .optional(),
-    calendarEventId: z.string().min(MIN_STRING_LENGTH).optional(),
-    cost: z.number().min(0).optional(),
-    clinicBranchId: z.string().min(MIN_STRING_LENGTH).optional(),
-    practitionerId: z.string().min(MIN_STRING_LENGTH).optional(),
-    clinic_tz: z.string().min(MIN_STRING_LENGTH).optional(),
-    linkedForms: z.union([z.array(linkedFormInfoSchema).max(MAX_ARRAY_LENGTH), z.any()]).optional(),
-    media: z.union([z.array(appointmentMediaItemSchema).max(MAX_ARRAY_LENGTH), z.any()]).optional(),
-    reviewInfo: z.union([patientReviewInfoSchema.nullable(), z.any()]).optional(),
-    finalizedDetails: z.union([finalizedDetailsSchema.nullable(), z.any()]).optional(),
-    isArchived: z.boolean().optional(),
-    updatedAt: z.any().optional(),
-    metadata: appointmentMetadataSchema.optional(),
-  })
-  .refine(
-    data => {
-      if (
-        data.status === AppointmentStatus.CANCELED_CLINIC ||
-        data.status === AppointmentStatus.CANCELED_PATIENT ||
-        data.status === AppointmentStatus.CANCELED_PATIENT_RESCHEDULED
-      ) {
-        return !!data.cancellationReason && !!data.canceledBy;
-      }
-      return true;
-    },
-    {
-      message:
-        'Cancellation reason and canceled by must be provided when canceling an appointment with patient or clinic origin.',
-      path: ['status'],
-    },
-  )
-  .refine(
-    data => {
-      if (data.appointmentStartTime && data.appointmentEndTime) {
-        return data.appointmentEndTime > data.appointmentStartTime;
-      }
-      return true;
-    },
-    {
-      message: 'Appointment end time must be after start time if both are provided',
-      path: ['appointmentEndTime'],
-    },
-  );
-
-/**
- * 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
-      .any()
-      .refine(
-        val =>
-          val === undefined ||
-          val instanceof Date ||
-          val?._seconds !== undefined ||
-          val?.seconds !== undefined ||
-          typeof val === 'number' ||
-          typeof val === 'string' ||
-          (val && typeof val.toMillis === 'function'),
-        'Start date must be a valid timestamp or Date object',
-      )
-      .optional(),
-    endDate: z
-      .any()
-      .refine(
-        val =>
-          val === undefined ||
-          val instanceof Date ||
-          val?._seconds !== undefined ||
-          val?.seconds !== undefined ||
-          typeof val === 'number' ||
-          typeof val === 'string' ||
-          (val && typeof val.toMillis === 'function'),
-        'End date must be a valid timestamp or Date object',
-      )
-      .optional(),
-    status: z
-      .union([appointmentStatusSchema, z.array(appointmentStatusSchema).nonempty()])
-      .optional(),
-    limit: z.number().positive().int().optional().default(20),
-    startAfter: z.any().optional(),
-  })
-  .refine(
-    data => {
-      if (!data.startDate && !data.endDate && !data.status) {
-        return !!(data.patientId || data.practitionerId || data.clinicBranchId);
-      }
-      return true;
-    },
-    {
-      message:
-        'At least one of patientId, practitionerId, or clinicBranchId must be provided if no date or status filters are set.',
-      path: ['patientId'],
-    },
-  )
-  .refine(
-    data => {
-      if (data.startDate && data.endDate) {
-        return data.endDate >= data.startDate;
-      }
-      return true;
-    },
-    {
-      message: 'End date must be after or the same as start date',
-      path: ['endDate'],
-    },
-  );
-
-/**
- * Schema for validating appointment reschedule data
- */
-export const rescheduleAppointmentSchema = z.object({
-  appointmentId: z.string().min(MIN_STRING_LENGTH, 'Appointment ID is required'),
-  newStartTime: z
-    .any()
-    .refine(
-      val =>
-        val instanceof Date ||
-        val?._seconds !== undefined ||
-        val?.seconds !== undefined ||
-        typeof val === 'number' ||
-        typeof val === 'string' ||
-        (val && typeof val.toMillis === 'function'),
-      'New start time must be a valid timestamp, Date object, number, or string',
-    ),
-  newEndTime: z
-    .any()
-    .refine(
-      val =>
-        val instanceof Date ||
-        val?._seconds !== undefined ||
-        val?.seconds !== undefined ||
-        typeof val === 'number' ||
-        typeof val === 'string' ||
-        (val && typeof val.toMillis === 'function'),
-      'New end time must be a valid timestamp, Date object, number, or string',
-    ),
-});
-
-/**
- * Schema for validating zone photo upload data
- */
-export const zonePhotoUploadSchema = z.object({
-  appointmentId: z.string().min(MIN_STRING_LENGTH, 'Appointment ID is required'),
-  zoneId: z.string().min(MIN_STRING_LENGTH, 'Zone ID is required'),
-  photoType: z.enum(['before', 'after'], {
-    required_error: 'Photo type must be either "before" or "after"',
-  }),
-  file: z.any().refine(file => {
-    // Check if it's a File or Blob object
-    return (
-      file instanceof File ||
-      file instanceof Blob ||
-      (file && typeof file.size === 'number' && typeof file.type === 'string')
-    );
-  }, 'File must be a valid File or Blob object'),
-  notes: z.string().max(MAX_STRING_LENGTH_LONG, 'Notes too long').optional(),
-});
+import { z } from 'zod';
+import { AppointmentStatus, PaymentStatus, MediaType } from '../types/appointment';
+import { filledDocumentStatusSchema } from './documentation-templates.schema';
+import { Currency, PricingMeasure } from '../backoffice/types/static/pricing.types';
+import { mediaResourceSchema } from './media.schema';
+
+// Define common constants locally if not available from common.schema.ts
+const MIN_STRING_LENGTH = 1;
+const MAX_STRING_LENGTH = 1024; // Example value
+const MAX_STRING_LENGTH_LONG = 4096; // Example value for longer notes/comments
+const MAX_ARRAY_LENGTH = 100; // Example value
+
+// --- Enum Schemas ---
+export const appointmentStatusSchema = z.nativeEnum(AppointmentStatus);
+export const paymentStatusSchema = z.nativeEnum(PaymentStatus);
+export const mediaTypeSchema = z.nativeEnum(MediaType);
+
+// --- Schemas for Nested Objects from types/appointment/index.ts ---
+
+export const appointmentMediaItemSchema = z.object({
+  id: z.string().min(MIN_STRING_LENGTH, 'Media item ID is required'),
+  type: mediaTypeSchema,
+  url: z.string().url('Media URL must be a valid URL'),
+  fileName: z.string().optional(),
+  uploadedAt: z
+    .any()
+    .refine(
+      val =>
+        val instanceof Date ||
+        val?._seconds !== undefined ||
+        val?.seconds !== undefined ||
+        typeof val === 'number' ||
+        typeof val === 'string' ||
+        (val && typeof val.toMillis === 'function'),
+      'uploadedAt must be a valid timestamp or Date object',
+    ),
+  uploadedBy: z.string().min(MIN_STRING_LENGTH, 'Uploaded by user ID is required'),
+  description: z.string().max(MAX_STRING_LENGTH, 'Description too long').optional(),
+});
+
+export const procedureExtendedInfoSchema = z.object({
+  id: z.string().min(MIN_STRING_LENGTH),
+  name: z.string().min(MIN_STRING_LENGTH),
+  description: z.string(),
+  cost: z.number().min(0),
+  duration: z.number().min(0),
+  procedureFamily: z.any(),
+  procedureCategoryId: z.string(),
+  procedureCategoryName: z.string(),
+  procedureSubCategoryId: z.string(),
+  procedureSubCategoryName: z.string(),
+  procedureTechnologyId: z.string(),
+  procedureTechnologyName: z.string(),
+  procedureProductBrandId: z.string(),
+  procedureProductBrandName: z.string(),
+  procedureProducts: z.array(
+    z.object({
+      productId: z.string().min(MIN_STRING_LENGTH, 'Product ID is required'),
+      productName: z.string().min(MIN_STRING_LENGTH, 'Product name is required'),
+      brandId: z.string().min(MIN_STRING_LENGTH, 'Brand ID is required'),
+      brandName: z.string().min(MIN_STRING_LENGTH, 'Brand name is required'),
+    }),
+  ),
+});
+
+export const linkedFormInfoSchema = z.object({
+  formId: z.string().min(MIN_STRING_LENGTH, 'Form ID is required'),
+  templateId: z.string().min(MIN_STRING_LENGTH, 'Template ID is required'),
+  templateVersion: z.number().int().positive('Template version must be a positive integer'),
+  title: z.string().min(MIN_STRING_LENGTH, 'Form title is required'),
+  isUserForm: z.boolean(),
+  isRequired: z.boolean().optional(),
+  status: filledDocumentStatusSchema,
+  path: z.string().min(MIN_STRING_LENGTH, 'Form path is required'),
+  submittedAt: z
+    .any()
+    .refine(
+      val =>
+        val === undefined ||
+        val instanceof Date ||
+        val?._seconds !== undefined ||
+        val?.seconds !== undefined ||
+        typeof val === 'number' ||
+        typeof val === 'string' ||
+        (val && typeof val.toMillis === 'function'),
+      'submittedAt must be a valid timestamp or Date object',
+    )
+    .optional(),
+  completedAt: z
+    .any()
+    .refine(
+      val =>
+        val === undefined ||
+        val instanceof Date ||
+        val?._seconds !== undefined ||
+        val?.seconds !== undefined ||
+        typeof val === 'number' ||
+        typeof val === 'string' ||
+        (val && typeof val.toMillis === 'function'),
+      'completedAt must be a valid timestamp or Date object',
+    )
+    .optional(),
+});
+
+export const patientReviewInfoSchema = z.object({
+  reviewId: z.string().min(MIN_STRING_LENGTH, 'Review ID is required'),
+  rating: z.number().min(1).max(5, 'Rating must be between 1 and 5'),
+  comment: z.string().max(MAX_STRING_LENGTH_LONG, 'Comment too long').optional(),
+  reviewedAt: z
+    .any()
+    .refine(
+      val =>
+        val instanceof Date ||
+        val?._seconds !== undefined ||
+        val?.seconds !== undefined ||
+        typeof val === 'number' ||
+        typeof val === 'string' ||
+        (val && typeof val.toMillis === 'function'),
+      'reviewedAt must be a valid timestamp or Date object',
+    ),
+});
+
+export const finalizedDetailsSchema = z.object({
+  by: z.string().min(MIN_STRING_LENGTH, 'Finalized by user ID is required'),
+  at: z
+    .any()
+    .refine(
+      val =>
+        val instanceof Date ||
+        val?._seconds !== undefined ||
+        val?.seconds !== undefined ||
+        typeof val === 'number' ||
+        typeof val === 'string' ||
+        (val && typeof val.toMillis === 'function'),
+      'Finalized at must be a valid timestamp or Date object',
+    ),
+  notes: z.string().max(MAX_STRING_LENGTH_LONG, 'Finalization notes too long').optional(),
+});
+
+/**
+ * Schema for before/after photos and notes per zone
+ */
+export const beforeAfterPerZoneSchema = z.object({
+  before: mediaResourceSchema.nullable(),
+  after: mediaResourceSchema.nullable(),
+  beforeNote: z.string().nullable().optional(),
+  afterNote: z.string().nullable().optional(),
+  showToPatient: z.boolean().optional().default(false),
+  beforeNoteVisibleToPatient: z.boolean().optional().default(false),
+  afterNoteVisibleToPatient: z.boolean().optional().default(false),
+  visibilityUpdatedAt: z.any().optional(), // Timestamp
+  visibilityUpdatedBy: z.string().optional(),
+});
+
+/**
+ * Schema for billing information per zone
+ */
+export const billingPerZoneSchema = z.object({
+  Product: z.string().min(MIN_STRING_LENGTH, 'Product name is required'),
+  ProductId: z.string().nullable(),
+  Quantity: z.number().min(0, 'Quantity must be non-negative'),
+  UnitOfMeasurement: z.nativeEnum(PricingMeasure),
+  UnitPrice: z.number().min(0, 'Unit price must be non-negative'),
+  UnitCurency: z.nativeEnum(Currency),
+  Subtotal: z.number().min(0, 'Subtotal must be non-negative'),
+  Note: z.string().nullable(),
+  IonNumber: z.string().nullable(),
+});
+
+/**
+ * Schema for final billing calculations of the appointment
+ */
+export const finalBillingSchema = z.object({
+  subtotalAll: z.number().min(0, 'Subtotal all must be non-negative'),
+  discount: z.object({
+    type: z.enum(['percentage', 'fixed']),
+    value: z.number().min(0),
+    amount: z.number().min(0),
+  }).optional(),
+  discountedSubtotal: z.number().min(0).optional(),
+  taxRate: z.number().min(0).max(1, 'Tax rate must be between 0 and 1'),
+  taxPrice: z.number().min(0, 'Tax price must be non-negative'),
+  finalPrice: z.number().min(0, 'Final price must be non-negative'),
+  currency: z.nativeEnum(Currency),
+});
+
+/**
+ * Schema for zone item data (product or note per zone)
+ */
+export const zoneItemDataSchema = z
+  .object({
+    productId: z.string().optional(),
+    productName: z.string().optional(),
+    productBrandId: z.string().optional(),
+    productBrandName: z.string().optional(),
+    belongingProcedureId: z.string().min(MIN_STRING_LENGTH, 'Belonging procedure ID is required'),
+    type: z.enum(['item', 'note'], {
+      required_error: 'Type must be either "item" or "note"',
+    }),
+    stage: z
+      .enum(['before', 'after'], {
+        required_error: 'Stage must be either "before" or "after"',
+      })
+      .optional(),
+    price: z.number().min(0, 'Price must be non-negative').optional(),
+    currency: z.nativeEnum(Currency).optional(),
+    unitOfMeasurement: z.nativeEnum(PricingMeasure).optional(),
+    priceOverrideAmount: z.number().min(0, 'Price override amount must be non-negative').optional(),
+    quantity: z.number().min(0, 'Quantity must be non-negative').optional(),
+    parentZone: z
+      .string()
+      .min(MIN_STRING_LENGTH, 'Parent zone is required')
+      .refine(
+        val => {
+          const parts = val.split('.');
+          return parts.length === 2;
+        },
+        {
+          message: 'Parent zone must be in "category.zone" format (e.g., "face.forehead")',
+        },
+      ),
+    subzones: z.array(z.string()).refine(
+      val => {
+        return val.every(subzone => {
+          const parts = subzone.split('.');
+          return parts.length === 3;
+        });
+      },
+      {
+        message: 'Subzones must be in "category.zone.subzone" format (e.g., "face.forehead.left")',
+      },
+    ),
+    notes: z.string().max(MAX_STRING_LENGTH_LONG, 'Notes too long').optional(),
+    notesVisibleToPatient: z.boolean().optional().default(false),
+    subtotal: z.number().min(0, 'Subtotal must be non-negative').optional(),
+    ionNumber: z.string().nullable().optional(), // Batch/Lot number - can be null to clear/delete
+    expiryDate: z.string().nullable().optional(), // ISO date string (YYYY-MM-DD) - can be null to clear/delete
+    createdAt: z.string().optional(),
+    updatedAt: z.string().optional(),
+  })
+  .refine(
+    data => {
+      if (data.type === 'item') {
+        return !!(data.productId && data.productName && (data.price || data.priceOverrideAmount));
+      }
+      return true;
+    },
+    {
+      message: 'Item type requires productId, productName, and either price or priceOverrideAmount',
+    },
+  );
+
+/**
+ * Schema for appointment product metadata
+ */
+export const appointmentProductMetadataSchema = z.object({
+  productId: z.string().min(MIN_STRING_LENGTH, 'Product ID is required'),
+  productName: z.string().min(MIN_STRING_LENGTH, 'Product name is required'),
+  brandId: z.string().min(MIN_STRING_LENGTH, 'Brand ID is required'),
+  brandName: z.string().min(MIN_STRING_LENGTH, 'Brand name is required'),
+  procedureId: z.string().min(MIN_STRING_LENGTH, 'Procedure ID is required'),
+  price: z.number().min(0, 'Price must be non-negative'),
+  currency: z.nativeEnum(Currency),
+  unitOfMeasurement: z.nativeEnum(PricingMeasure),
+});
+
+/**
+ * Schema for extended procedure info
+ */
+export const extendedProcedureInfoSchema = z.object({
+  procedureId: z.string().min(MIN_STRING_LENGTH, 'Procedure ID is required'),
+  procedureName: z.string().min(MIN_STRING_LENGTH, 'Procedure name is required'),
+  procedureFamily: z.any(),
+  procedureCategoryId: z.string().min(MIN_STRING_LENGTH, 'Category ID is required'),
+  procedureCategoryName: z.string().min(MIN_STRING_LENGTH, 'Category name is required'),
+  procedureSubCategoryId: z.string().min(MIN_STRING_LENGTH, 'Subcategory ID is required'),
+  procedureSubCategoryName: z.string().min(MIN_STRING_LENGTH, 'Subcategory name is required'),
+  procedureTechnologyId: z.string().min(MIN_STRING_LENGTH, 'Technology ID is required'),
+  procedureTechnologyName: z.string().min(MIN_STRING_LENGTH, 'Technology name is required'),
+  procedureProducts: z.array(
+    z.object({
+      productId: z.string().min(MIN_STRING_LENGTH, 'Product ID is required'),
+      productName: z.string().min(MIN_STRING_LENGTH, 'Product name is required'),
+      brandId: z.string().min(MIN_STRING_LENGTH, 'Brand ID is required'),
+      brandName: z.string().min(MIN_STRING_LENGTH, 'Brand name is required'),
+    }),
+  ),
+});
+
+/**
+ * Schema for recommended procedure within metadata
+ */
+export const recommendedProcedureTimeframeSchema = z.object({
+  value: z.number().int().positive('Timeframe value must be a positive integer'),
+  unit: z.enum(['day', 'week', 'month', 'year']),
+});
+
+export const recommendedProcedureSchema = z.object({
+  procedure: extendedProcedureInfoSchema,
+  note: z.string().max(MAX_STRING_LENGTH_LONG, 'Note too long'), // Note is now optional (no min length)
+  timeframe: recommendedProcedureTimeframeSchema,
+});
+
+/**
+ * Schema for appointment metadata containing zone-specific information
+ */
+export const appointmentMetadataSchema = z.object({
+  selectedZones: z.array(z.string()).nullable(),
+  zonePhotos: z.record(z.string(), z.array(beforeAfterPerZoneSchema).max(10)).nullable(),
+  zonesData: z.record(z.string(), z.array(zoneItemDataSchema)).nullable().optional(),
+  appointmentProducts: z.array(appointmentProductMetadataSchema).optional().default([]),
+  extendedProcedures: z.array(extendedProcedureInfoSchema).optional().default([]),
+  recommendedProcedures: z.array(recommendedProcedureSchema).optional().default([]),
+  zoneBilling: z.record(z.string(), billingPerZoneSchema).nullable().optional(),
+  finalbilling: finalBillingSchema.nullable(),
+  finalizationNotesShared: z.string().nullable().optional(),
+  finalizationNotesInternal: z.string().nullable().optional(),
+  finalizationNotes: z.string().nullable().optional(), // @deprecated - kept for backward compatibility
+});
+
+// --- Main Appointment Schemas ---
+
+/**
+ * Schema for validating appointment creation data
+ */
+export const createAppointmentSchema = z
+  .object({
+    clinicBranchId: z.string().min(MIN_STRING_LENGTH, 'Clinic branch ID is required'),
+    practitionerId: z.string().min(MIN_STRING_LENGTH, 'Practitioner ID is required'),
+    patientId: z.string().min(MIN_STRING_LENGTH, 'Patient ID is required'),
+    procedureId: z.string().min(MIN_STRING_LENGTH, 'Procedure ID is required'),
+    appointmentStartTime: z
+      .any()
+      .refine(
+        val =>
+          val instanceof Date ||
+          val?._seconds !== undefined ||
+          val?.seconds !== undefined ||
+          typeof val === 'number' ||
+          typeof val === 'string' ||
+          (val && typeof val.toMillis === 'function'),
+        'Appointment start time must be a valid timestamp or Date object',
+      ),
+    appointmentEndTime: z
+      .any()
+      .refine(
+        val =>
+          val instanceof Date ||
+          val?._seconds !== undefined ||
+          val?.seconds !== undefined ||
+          typeof val === 'number' ||
+          typeof val === 'string' ||
+          (val && typeof val.toMillis === 'function'),
+        'Appointment end time must be a valid timestamp or Date object',
+      ),
+    cost: z.number().min(0, 'Cost must be a non-negative number'),
+    currency: z.string().min(1, 'Currency is required'),
+    patientNotes: z.string().max(MAX_STRING_LENGTH, 'Patient notes too long').nullable().optional(),
+    initialStatus: appointmentStatusSchema,
+    initialPaymentStatus: paymentStatusSchema.optional().default(PaymentStatus.UNPAID),
+    clinic_tz: z.string().min(1, 'Timezone is required'),
+  })
+  .refine(data => data.appointmentEndTime > data.appointmentStartTime, {
+    message: 'Appointment end time must be after start time',
+    path: ['appointmentEndTime'],
+  });
+
+/**
+ * Schema for validating appointment update data
+ */
+export const updateAppointmentSchema = z
+  .object({
+    status: appointmentStatusSchema.optional(),
+    confirmationTime: z.any().optional().nullable(),
+    cancellationTime: z.any().optional().nullable(),
+    rescheduleTime: z.any().optional().nullable(),
+    procedureActualStartTime: z.any().optional().nullable(),
+    actualDurationMinutes: z
+      .number()
+      .int()
+      .positive('Duration must be a positive integer')
+      .optional(),
+    cancellationReason: z
+      .string()
+      .max(MAX_STRING_LENGTH, 'Cancellation reason too long')
+      .nullable()
+      .optional(),
+    canceledBy: z.enum(['patient', 'clinic', 'practitioner', 'system']).optional(),
+    internalNotes: z
+      .string()
+      .max(MAX_STRING_LENGTH_LONG, 'Internal notes too long')
+      .nullable()
+      .optional(),
+    patientNotes: z.any().optional().nullable(),
+    paymentStatus: paymentStatusSchema.optional(),
+    paymentTransactionId: z.any().optional().nullable(),
+    completedPreRequirements: z.union([z.array(z.string()), z.any()]).optional(),
+    completedPostRequirements: z.union([z.array(z.string()), z.any()]).optional(),
+    linkedFormIds: z.union([z.array(z.string()), z.any()]).optional(),
+    pendingUserFormsIds: z.union([z.array(z.string()), z.any()]).optional(),
+    appointmentStartTime: z
+      .any()
+      .refine(
+        val =>
+          val === undefined ||
+          val instanceof Date ||
+          val?._seconds !== undefined ||
+          val?.seconds !== undefined ||
+          typeof val === 'number' ||
+          typeof val === 'string' ||
+          (val && typeof val.toMillis === 'function'),
+        'Appointment start time must be a valid timestamp or Date object',
+      )
+      .optional(),
+    appointmentEndTime: z
+      .any()
+      .refine(
+        val =>
+          val === undefined ||
+          val instanceof Date ||
+          val?._seconds !== undefined ||
+          val?.seconds !== undefined ||
+          typeof val === 'number' ||
+          typeof val === 'string' ||
+          (val && typeof val.toMillis === 'function'),
+        'Appointment end time must be a valid timestamp or Date object',
+      )
+      .optional(),
+    calendarEventId: z.string().min(MIN_STRING_LENGTH).optional(),
+    cost: z.number().min(0).optional(),
+    clinicBranchId: z.string().min(MIN_STRING_LENGTH).optional(),
+    practitionerId: z.string().min(MIN_STRING_LENGTH).optional(),
+    clinic_tz: z.string().min(MIN_STRING_LENGTH).optional(),
+    linkedForms: z.union([z.array(linkedFormInfoSchema).max(MAX_ARRAY_LENGTH), z.any()]).optional(),
+    media: z.union([z.array(appointmentMediaItemSchema).max(MAX_ARRAY_LENGTH), z.any()]).optional(),
+    reviewInfo: z.union([patientReviewInfoSchema.nullable(), z.any()]).optional(),
+    finalizedDetails: z.union([finalizedDetailsSchema.nullable(), z.any()]).optional(),
+    isArchived: z.boolean().optional(),
+    updatedAt: z.any().optional(),
+    metadata: appointmentMetadataSchema.optional(),
+  })
+  .refine(
+    data => {
+      if (
+        data.status === AppointmentStatus.CANCELED_CLINIC ||
+        data.status === AppointmentStatus.CANCELED_PATIENT ||
+        data.status === AppointmentStatus.CANCELED_PATIENT_RESCHEDULED
+      ) {
+        return !!data.cancellationReason && !!data.canceledBy;
+      }
+      return true;
+    },
+    {
+      message:
+        'Cancellation reason and canceled by must be provided when canceling an appointment with patient or clinic origin.',
+      path: ['status'],
+    },
+  )
+  .refine(
+    data => {
+      if (data.appointmentStartTime && data.appointmentEndTime) {
+        return data.appointmentEndTime > data.appointmentStartTime;
+      }
+      return true;
+    },
+    {
+      message: 'Appointment end time must be after start time if both are provided',
+      path: ['appointmentEndTime'],
+    },
+  );
+
+/**
+ * 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
+      .any()
+      .refine(
+        val =>
+          val === undefined ||
+          val instanceof Date ||
+          val?._seconds !== undefined ||
+          val?.seconds !== undefined ||
+          typeof val === 'number' ||
+          typeof val === 'string' ||
+          (val && typeof val.toMillis === 'function'),
+        'Start date must be a valid timestamp or Date object',
+      )
+      .optional(),
+    endDate: z
+      .any()
+      .refine(
+        val =>
+          val === undefined ||
+          val instanceof Date ||
+          val?._seconds !== undefined ||
+          val?.seconds !== undefined ||
+          typeof val === 'number' ||
+          typeof val === 'string' ||
+          (val && typeof val.toMillis === 'function'),
+        'End date must be a valid timestamp or Date object',
+      )
+      .optional(),
+    status: z
+      .union([appointmentStatusSchema, z.array(appointmentStatusSchema).nonempty()])
+      .optional(),
+    limit: z.number().positive().int().optional().default(20),
+    startAfter: z.any().optional(),
+  })
+  .refine(
+    data => {
+      if (!data.startDate && !data.endDate && !data.status) {
+        return !!(data.patientId || data.practitionerId || data.clinicBranchId);
+      }
+      return true;
+    },
+    {
+      message:
+        'At least one of patientId, practitionerId, or clinicBranchId must be provided if no date or status filters are set.',
+      path: ['patientId'],
+    },
+  )
+  .refine(
+    data => {
+      if (data.startDate && data.endDate) {
+        return data.endDate >= data.startDate;
+      }
+      return true;
+    },
+    {
+      message: 'End date must be after or the same as start date',
+      path: ['endDate'],
+    },
+  );
+
+/**
+ * Schema for validating appointment reschedule data
+ */
+export const rescheduleAppointmentSchema = z.object({
+  appointmentId: z.string().min(MIN_STRING_LENGTH, 'Appointment ID is required'),
+  newStartTime: z
+    .any()
+    .refine(
+      val =>
+        val instanceof Date ||
+        val?._seconds !== undefined ||
+        val?.seconds !== undefined ||
+        typeof val === 'number' ||
+        typeof val === 'string' ||
+        (val && typeof val.toMillis === 'function'),
+      'New start time must be a valid timestamp, Date object, number, or string',
+    ),
+  newEndTime: z
+    .any()
+    .refine(
+      val =>
+        val instanceof Date ||
+        val?._seconds !== undefined ||
+        val?.seconds !== undefined ||
+        typeof val === 'number' ||
+        typeof val === 'string' ||
+        (val && typeof val.toMillis === 'function'),
+      'New end time must be a valid timestamp, Date object, number, or string',
+    ),
+});
+
+/**
+ * Schema for validating zone photo upload data
+ */
+export const zonePhotoUploadSchema = z.object({
+  appointmentId: z.string().min(MIN_STRING_LENGTH, 'Appointment ID is required'),
+  zoneId: z.string().min(MIN_STRING_LENGTH, 'Zone ID is required'),
+  photoType: z.enum(['before', 'after'], {
+    required_error: 'Photo type must be either "before" or "after"',
+  }),
+  file: z.any().refine(file => {
+    // Check if it's a File or Blob object
+    return (
+      file instanceof File ||
+      file instanceof Blob ||
+      (file && typeof file.size === 'number' && typeof file.type === 'string')
+    );
+  }, 'File must be a valid File or Blob object'),
+  notes: z.string().max(MAX_STRING_LENGTH_LONG, 'Notes too long').optional(),
+});