@blackcode_sa/metaestetics-api 1.14.44 → 1.14.45

package/dist/index.mjs

@@ -3758,8 +3758,14 @@ var finalizedDetailsSchema = z3.object({
 var beforeAfterPerZoneSchema = z3.object({
   before: mediaResourceSchema.nullable(),
   after: mediaResourceSchema.nullable(),
+  beforeNote: z3.string().nullable().optional(),
   afterNote: z3.string().nullable().optional(),
-  beforeNote: z3.string().nullable().optional()
+  showToPatient: z3.boolean().optional().default(false),
+  beforeNoteVisibleToPatient: z3.boolean().optional().default(false),
+  afterNoteVisibleToPatient: z3.boolean().optional().default(false),
+  visibilityUpdatedAt: z3.any().optional(),
+  // Timestamp
+  visibilityUpdatedBy: z3.string().optional()
 });
 var billingPerZoneSchema = z3.object({
   Product: z3.string().min(MIN_STRING_LENGTH, "Product name is required"),
@@ -3817,11 +3823,9 @@ var zoneItemDataSchema = z3.object({
     }
   ),
   notes: z3.string().max(MAX_STRING_LENGTH_LONG, "Notes too long").optional(),
+  notesVisibleToPatient: z3.boolean().optional().default(false),
   subtotal: z3.number().min(0, "Subtotal must be non-negative").optional(),
   ionNumber: z3.string().optional(),
-  lotNumber: z3.string().max(MAX_STRING_LENGTH, "Lot number too long").optional(),
-  expiryDate: z3.string().optional(),
-  // ISO date string (YYYY-MM-DD format)
   createdAt: z3.string().optional(),
   updatedAt: z3.string().optional()
 }).refine(
@@ -3883,7 +3887,10 @@ var appointmentMetadataSchema = z3.object({
   recommendedProcedures: z3.array(recommendedProcedureSchema).optional().default([]),
   zoneBilling: z3.record(z3.string(), billingPerZoneSchema).nullable().optional(),
   finalbilling: finalBillingSchema.nullable(),
-  finalizationNotes: z3.string().nullable()
+  finalizationNotesShared: z3.string().nullable().optional(),
+  finalizationNotesInternal: z3.string().nullable().optional(),
+  finalizationNotes: z3.string().nullable().optional()
+  // @deprecated - kept for backward compatibility
 });
 var createAppointmentSchema = z3.object({
   clinicBranchId: z3.string().min(MIN_STRING_LENGTH, "Clinic branch ID is required"),
@@ -4715,10 +4722,14 @@ function initializeMetadata(appointment) {
     extendedProcedures: [],
     recommendedProcedures: [],
     finalbilling: null,
+    finalizationNotesShared: null,
+    finalizationNotesInternal: null,
     finalizationNotes: null
+    // @deprecated - kept for backward compatibility
   };
 }
 async function addItemToZoneUtil(db, appointmentId, zoneId, item) {
+  var _a;
   validateZoneKeyFormat(zoneId);
   const appointment = await getAppointmentOrThrow(db, appointmentId);
   const metadata = initializeMetadata(appointment);
@@ -4732,6 +4743,8 @@ async function addItemToZoneUtil(db, appointmentId, zoneId, item) {
     parentZone: zoneId,
     // Set parentZone to the zone key
     subtotal: calculateItemSubtotal(item),
+    // Set default visibility to false (privacy-first) if notes exist and visibility not explicitly set
+    notesVisibleToPatient: (_a = item.notesVisibleToPatient) != null ? _a : item.notes ? false : void 0,
     createdAt: now,
     updatedAt: now
   };
@@ -5231,7 +5244,17 @@ async function getRecommendedProceduresUtil(db, appointmentId) {
 
 // src/services/appointment/utils/zone-photo.utils.ts
 import { updateDoc as updateDoc6, serverTimestamp as serverTimestamp6, doc as doc9 } from "firebase/firestore";
-async function updateZonePhotoEntryUtil(db, appointmentId, zoneId, photoIndex, updates) {
+function addVisibilityAudit(updates, doctorId) {
+  if (updates.showToPatient !== void 0 || updates.beforeNoteVisibleToPatient !== void 0 || updates.afterNoteVisibleToPatient !== void 0) {
+    return {
+      ...updates,
+      visibilityUpdatedAt: serverTimestamp6(),
+      visibilityUpdatedBy: doctorId
+    };
+  }
+  return updates;
+}
+async function updateZonePhotoEntryUtil(db, appointmentId, zoneId, photoIndex, updates, doctorId) {
   var _a;
   const appointment = await getAppointmentOrThrow(db, appointmentId);
   const zonePhotos = (_a = appointment.metadata) == null ? void 0 : _a.zonePhotos;
@@ -5242,11 +5265,12 @@ async function updateZonePhotoEntryUtil(db, appointmentId, zoneId, photoIndex, u
   if (photoIndex < 0 || photoIndex >= zoneArray.length) {
     throw new Error(`Invalid photo index ${photoIndex} for zone ${zoneId}. Must be between 0 and ${zoneArray.length - 1}`);
   }
+  const updatesWithAudit = doctorId ? addVisibilityAudit(updates, doctorId) : updates;
   const updatedZonePhotos = { ...zonePhotos };
   updatedZonePhotos[zoneId] = [...zoneArray];
   updatedZonePhotos[zoneId][photoIndex] = {
     ...zoneArray[photoIndex],
-    ...updates
+    ...updatesWithAudit
   };
   const appointmentRef = doc9(db, APPOINTMENTS_COLLECTION, appointmentId);
   await updateDoc6(appointmentRef, {
@@ -5290,6 +5314,20 @@ async function getZonePhotoEntryUtil(db, appointmentId, zoneId, photoIndex) {
   }
   return zoneArray[photoIndex];
 }
+async function updateZonePhotoVisibilityUtil(db, appointmentId, zoneId, photoIndex, showToPatient, doctorId) {
+  return updateZonePhotoEntryUtil(
+    db,
+    appointmentId,
+    zoneId,
+    photoIndex,
+    { showToPatient },
+    doctorId
+  );
+}
+async function updateZonePhotoNoteVisibilityUtil(db, appointmentId, zoneId, photoIndex, noteType, visibleToPatient, doctorId) {
+  const updates = noteType === "before" ? { beforeNoteVisibleToPatient: visibleToPatient } : { afterNoteVisibleToPatient: visibleToPatient };
+  return updateZonePhotoEntryUtil(db, appointmentId, zoneId, photoIndex, updates, doctorId);
+}
 
 // src/services/appointment/appointment.service.ts
 var AppointmentService = class extends BaseService {
@@ -6156,6 +6194,7 @@ var AppointmentService = class extends BaseService {
    * @returns The updated appointment
    */
   async updateAppointmentZonePhoto(appointmentId, zoneId, photoType, mediaMetadata, notes) {
+    var _a, _b, _c, _d;
     try {
       console.log(
         `[APPOINTMENT_SERVICE] Updating appointment metadata for ${photoType} photo in zone ${zoneId}`
@@ -6173,7 +6212,10 @@ var AppointmentService = class extends BaseService {
         recommendedProcedures: [],
         zoneBilling: null,
         finalbilling: null,
+        finalizationNotesShared: null,
+        finalizationNotesInternal: null,
         finalizationNotes: null
+        // @deprecated - kept for backward compatibility
       };
       let currentZonePhotos = {};
       if (currentMetadata.zonePhotos) {
@@ -6188,7 +6230,11 @@ var AppointmentService = class extends BaseService {
                 before: oldData.before || null,
                 after: oldData.after || null,
                 beforeNote: null,
-                afterNote: null
+                afterNote: null,
+                showToPatient: false,
+                // Default: not visible to patient (privacy-first)
+                beforeNoteVisibleToPatient: false,
+                afterNoteVisibleToPatient: false
               }
             ];
           }
@@ -6201,7 +6247,13 @@ var AppointmentService = class extends BaseService {
         before: photoType === "before" ? mediaMetadata.url : null,
         after: photoType === "after" ? mediaMetadata.url : null,
         beforeNote: photoType === "before" ? notes || null : null,
-        afterNote: photoType === "after" ? notes || null : null
+        afterNote: photoType === "after" ? notes || null : null,
+        showToPatient: false,
+        // Default: not visible to patient
+        beforeNoteVisibleToPatient: false,
+        // Default: not visible to patient
+        afterNoteVisibleToPatient: false
+        // Default: not visible to patient
       };
       currentZonePhotos[zoneId] = [...currentZonePhotos[zoneId], newEntry];
       if (currentZonePhotos[zoneId].length > 10) {
@@ -6220,7 +6272,10 @@ var AppointmentService = class extends BaseService {
             zoneBilling: currentMetadata.zoneBilling
           },
           finalbilling: currentMetadata.finalbilling,
-          finalizationNotes: currentMetadata.finalizationNotes
+          finalizationNotesShared: (_a = currentMetadata.finalizationNotesShared) != null ? _a : null,
+          finalizationNotesInternal: (_b = currentMetadata.finalizationNotesInternal) != null ? _b : null,
+          finalizationNotes: (_d = (_c = currentMetadata.finalizationNotes) != null ? _c : currentMetadata.finalizationNotesShared) != null ? _d : null
+          // @deprecated - migrate from old field if exists
         },
         updatedAt: serverTimestamp7()
       };
@@ -6274,7 +6329,7 @@ var AppointmentService = class extends BaseService {
    * @returns The updated appointment
    */
   async deleteZonePhoto(appointmentId, zoneId, photoIndex) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _i;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p;
     try {
       console.log(
         `[APPOINTMENT_SERVICE] Deleting zone photo index ${photoIndex} for zone ${zoneId} in appointment ${appointmentId}`
@@ -6331,7 +6386,10 @@ var AppointmentService = class extends BaseService {
             zoneBilling: appointment.metadata.zoneBilling
           },
           finalbilling: ((_h = appointment.metadata) == null ? void 0 : _h.finalbilling) || null,
-          finalizationNotes: ((_i = appointment.metadata) == null ? void 0 : _i.finalizationNotes) || null
+          finalizationNotesShared: (_l = (_k = (_i = appointment.metadata) == null ? void 0 : _i.finalizationNotesShared) != null ? _k : (_j = appointment.metadata) == null ? void 0 : _j.finalizationNotes) != null ? _l : null,
+          finalizationNotesInternal: (_n = (_m = appointment.metadata) == null ? void 0 : _m.finalizationNotesInternal) != null ? _n : null,
+          finalizationNotes: (_p = (_o = appointment.metadata) == null ? void 0 : _o.finalizationNotes) != null ? _p : null
+          // @deprecated
         },
         updatedAt: serverTimestamp7()
       };
@@ -6530,7 +6588,7 @@ var AppointmentService = class extends BaseService {
    * @returns The updated appointment with recalculated billing
    */
   async recalculateFinalBilling(appointmentId, taxRate) {
-    var _a;
+    var _a, _b, _c, _d, _e;
     try {
       console.log(
         `[APPOINTMENT_SERVICE] Recalculating final billing for appointment ${appointmentId}`
@@ -6552,7 +6610,10 @@ var AppointmentService = class extends BaseService {
         extendedProcedures: [],
         recommendedProcedures: [],
         finalbilling: null,
+        finalizationNotesShared: null,
+        finalizationNotesInternal: null,
         finalizationNotes: null
+        // @deprecated
       };
       const shouldUpdatePaymentStatus = finalbilling.finalPrice > 0 && appointment.paymentStatus === "not_applicable" /* NOT_APPLICABLE */;
       const updateData = {
@@ -6568,7 +6629,10 @@ var AppointmentService = class extends BaseService {
             zoneBilling: currentMetadata.zoneBilling
           },
           finalbilling,
-          finalizationNotes: currentMetadata.finalizationNotes
+          finalizationNotesShared: (_b = currentMetadata.finalizationNotesShared) != null ? _b : null,
+          finalizationNotesInternal: (_c = currentMetadata.finalizationNotesInternal) != null ? _c : null,
+          finalizationNotes: (_e = (_d = currentMetadata.finalizationNotes) != null ? _d : currentMetadata.finalizationNotesShared) != null ? _e : null
+          // @deprecated
         },
         ...shouldUpdatePaymentStatus && {
           paymentStatus: "unpaid" /* UNPAID */
@@ -6768,6 +6832,64 @@ var AppointmentService = class extends BaseService {
       throw error;
     }
   }
+  /**
+   * Updates visibility of a photo pair (before AND after together)
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId Zone ID
+   * @param photoIndex Index of the photo entry
+   * @param showToPatient Whether the photo pair should be visible to patient
+   * @param doctorId ID of the doctor making the change (for audit trail)
+   * @returns The updated appointment
+   */
+  async updateZonePhotoVisibility(appointmentId, zoneId, photoIndex, showToPatient, doctorId) {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Updating photo visibility at index ${photoIndex} for zone ${zoneId} to ${showToPatient}`
+      );
+      return await updateZonePhotoVisibilityUtil(
+        this.db,
+        appointmentId,
+        zoneId,
+        photoIndex,
+        showToPatient,
+        doctorId
+      );
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error updating zone photo visibility:`, error);
+      throw error;
+    }
+  }
+  /**
+   * Updates visibility of a photo note (before or after)
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId Zone ID
+   * @param photoIndex Index of the photo entry
+   * @param noteType Type of note ('before' or 'after')
+   * @param visibleToPatient Whether the note should be visible to patient
+   * @param doctorId ID of the doctor making the change (for audit trail)
+   * @returns The updated appointment
+   */
+  async updateZonePhotoNoteVisibility(appointmentId, zoneId, photoIndex, noteType, visibleToPatient, doctorId) {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Updating ${noteType} note visibility at index ${photoIndex} for zone ${zoneId} to ${visibleToPatient}`
+      );
+      return await updateZonePhotoNoteVisibilityUtil(
+        this.db,
+        appointmentId,
+        zoneId,
+        photoIndex,
+        noteType,
+        visibleToPatient,
+        doctorId
+      );
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error updating zone photo note visibility:`, error);
+      throw error;
+    }
+  }
   /**
    * Gets a specific photo entry from a zone
    *
@@ -6787,6 +6909,54 @@ var AppointmentService = class extends BaseService {
       throw error;
     }
   }
+  /**
+   * Updates finalization notes (shared with patient and/or internal only)
+   *
+   * @param appointmentId ID of the appointment
+   * @param sharedNotes Notes to be shared with patient (optional)
+   * @param internalNotes Notes for internal use only (optional)
+   * @returns The updated appointment
+   */
+  async updateFinalizationNotes(appointmentId, sharedNotes, internalNotes) {
+    try {
+      const appointment = await this.getAppointmentById(appointmentId);
+      if (!appointment) {
+        throw new Error(`Appointment ${appointmentId} not found`);
+      }
+      const currentMetadata = appointment.metadata || {
+        selectedZones: null,
+        zonePhotos: null,
+        zonesData: null,
+        appointmentProducts: [],
+        extendedProcedures: [],
+        recommendedProcedures: [],
+        finalbilling: null,
+        finalizationNotesShared: null,
+        finalizationNotesInternal: null,
+        finalizationNotes: null
+      };
+      const updateData = {
+        metadata: {
+          selectedZones: currentMetadata.selectedZones,
+          zonePhotos: currentMetadata.zonePhotos,
+          zonesData: currentMetadata.zonesData || null,
+          appointmentProducts: currentMetadata.appointmentProducts || [],
+          extendedProcedures: currentMetadata.extendedProcedures || [],
+          recommendedProcedures: currentMetadata.recommendedProcedures || [],
+          finalbilling: currentMetadata.finalbilling,
+          finalizationNotesShared: sharedNotes !== void 0 ? sharedNotes : currentMetadata.finalizationNotesShared,
+          finalizationNotesInternal: internalNotes !== void 0 ? internalNotes : currentMetadata.finalizationNotesInternal,
+          // Keep deprecated field for backward compatibility during migration
+          finalizationNotes: sharedNotes !== void 0 ? sharedNotes : currentMetadata.finalizationNotes || currentMetadata.finalizationNotesShared
+        },
+        updatedAt: serverTimestamp7()
+      };
+      return await this.updateAppointment(appointmentId, updateData);
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error updating finalization notes:`, error);
+      throw error;
+    }
+  }
   /**
    * Gets all next steps recommendations for a patient from their past appointments.
    * Returns recommendations with context about which appointment, practitioner, and clinic suggested them.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blackcode_sa/metaestetics-api",
   "private": false,
-  "version": "1.14.44",
+  "version": "1.14.45",
   "description": "Firebase authentication service with anonymous upgrade support",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/services/appointment/appointment.service.ts

@@ -92,6 +92,8 @@ import {
   removeAfterPhotoFromEntryUtil,
   updateZonePhotoNotesUtil,
   getZonePhotoEntryUtil,
+  updateZonePhotoVisibilityUtil,
+  updateZonePhotoNoteVisibilityUtil,
 } from './utils/zone-photo.utils';
 
 /**
@@ -1364,7 +1366,9 @@ export class AppointmentService extends BaseService {
         recommendedProcedures: [],
         zoneBilling: null,
         finalbilling: null,
-        finalizationNotes: null,
+        finalizationNotesShared: null,
+        finalizationNotesInternal: null,
+        finalizationNotes: null, // @deprecated - kept for backward compatibility
       };
 
       // Initialize zonePhotos if it doesn't exist (array model per zone)
@@ -1386,6 +1390,9 @@ export class AppointmentService extends BaseService {
                 after: oldData.after || null,
                 beforeNote: null,
                 afterNote: null,
+                showToPatient: false, // Default: not visible to patient (privacy-first)
+                beforeNoteVisibleToPatient: false,
+                afterNoteVisibleToPatient: false,
               },
             ];
           }
@@ -1398,11 +1405,15 @@ export class AppointmentService extends BaseService {
       }
 
       // Create a new entry for this uploaded photo with per-photo notes
+      // Default visibility is false (privacy-first approach)
       const newEntry: BeforeAfterPerZone = {
         before: photoType === 'before' ? mediaMetadata.url : null,
         after: photoType === 'after' ? mediaMetadata.url : null,
         beforeNote: photoType === 'before' ? notes || null : null,
         afterNote: photoType === 'after' ? notes || null : null,
+        showToPatient: false, // Default: not visible to patient
+        beforeNoteVisibleToPatient: false, // Default: not visible to patient
+        afterNoteVisibleToPatient: false, // Default: not visible to patient
       };
 
       // Append to the zone's photo list
@@ -1426,7 +1437,12 @@ export class AppointmentService extends BaseService {
             zoneBilling: currentMetadata.zoneBilling,
           }),
           finalbilling: currentMetadata.finalbilling,
-          finalizationNotes: currentMetadata.finalizationNotes,
+          finalizationNotesShared: currentMetadata.finalizationNotesShared ?? null,
+          finalizationNotesInternal: currentMetadata.finalizationNotesInternal ?? null,
+          finalizationNotes:
+            currentMetadata.finalizationNotes ??
+            currentMetadata.finalizationNotesShared ??
+            null, // @deprecated - migrate from old field if exists
         },
         updatedAt: serverTimestamp(),
       };
@@ -1571,7 +1587,12 @@ export class AppointmentService extends BaseService {
             zoneBilling: appointment.metadata.zoneBilling,
           }),
           finalbilling: appointment.metadata?.finalbilling || null,
-          finalizationNotes: appointment.metadata?.finalizationNotes || null,
+          finalizationNotesShared:
+            appointment.metadata?.finalizationNotesShared ??
+            appointment.metadata?.finalizationNotes ??
+            null,
+          finalizationNotesInternal: appointment.metadata?.finalizationNotesInternal ?? null,
+          finalizationNotes: appointment.metadata?.finalizationNotes ?? null, // @deprecated
         },
         updatedAt: serverTimestamp(),
       };
@@ -1831,7 +1852,9 @@ export class AppointmentService extends BaseService {
         extendedProcedures: [],
         recommendedProcedures: [],
         finalbilling: null,
-        finalizationNotes: null,
+        finalizationNotesShared: null,
+        finalizationNotesInternal: null,
+        finalizationNotes: null, // @deprecated
       };
 
       // Update payment status if billing data exists but status is NOT_APPLICABLE
@@ -1853,7 +1876,12 @@ export class AppointmentService extends BaseService {
             zoneBilling: currentMetadata.zoneBilling,
           }),
           finalbilling,
-          finalizationNotes: currentMetadata.finalizationNotes,
+          finalizationNotesShared: currentMetadata.finalizationNotesShared ?? null,
+          finalizationNotesInternal: currentMetadata.finalizationNotesInternal ?? null,
+          finalizationNotes:
+            currentMetadata.finalizationNotes ??
+            currentMetadata.finalizationNotesShared ??
+            null, // @deprecated
         },
         ...(shouldUpdatePaymentStatus && {
           paymentStatus: PaymentStatus.UNPAID,
@@ -2099,6 +2127,79 @@ export class AppointmentService extends BaseService {
     }
   }
 
+  /**
+   * Updates visibility of a photo pair (before AND after together)
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId Zone ID
+   * @param photoIndex Index of the photo entry
+   * @param showToPatient Whether the photo pair should be visible to patient
+   * @param doctorId ID of the doctor making the change (for audit trail)
+   * @returns The updated appointment
+   */
+  async updateZonePhotoVisibility(
+    appointmentId: string,
+    zoneId: string,
+    photoIndex: number,
+    showToPatient: boolean,
+    doctorId: string,
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Updating photo visibility at index ${photoIndex} for zone ${zoneId} to ${showToPatient}`,
+      );
+      return await updateZonePhotoVisibilityUtil(
+        this.db,
+        appointmentId,
+        zoneId,
+        photoIndex,
+        showToPatient,
+        doctorId,
+      );
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error updating zone photo visibility:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Updates visibility of a photo note (before or after)
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId Zone ID
+   * @param photoIndex Index of the photo entry
+   * @param noteType Type of note ('before' or 'after')
+   * @param visibleToPatient Whether the note should be visible to patient
+   * @param doctorId ID of the doctor making the change (for audit trail)
+   * @returns The updated appointment
+   */
+  async updateZonePhotoNoteVisibility(
+    appointmentId: string,
+    zoneId: string,
+    photoIndex: number,
+    noteType: 'before' | 'after',
+    visibleToPatient: boolean,
+    doctorId: string,
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Updating ${noteType} note visibility at index ${photoIndex} for zone ${zoneId} to ${visibleToPatient}`,
+      );
+      return await updateZonePhotoNoteVisibilityUtil(
+        this.db,
+        appointmentId,
+        zoneId,
+        photoIndex,
+        noteType,
+        visibleToPatient,
+        doctorId,
+      );
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error updating zone photo note visibility:`, error);
+      throw error;
+    }
+  }
+
   /**
    * Gets a specific photo entry from a zone
    *
@@ -2123,6 +2224,67 @@ export class AppointmentService extends BaseService {
     }
   }
 
+  /**
+   * Updates finalization notes (shared with patient and/or internal only)
+   *
+   * @param appointmentId ID of the appointment
+   * @param sharedNotes Notes to be shared with patient (optional)
+   * @param internalNotes Notes for internal use only (optional)
+   * @returns The updated appointment
+   */
+  async updateFinalizationNotes(
+    appointmentId: string,
+    sharedNotes?: string | null,
+    internalNotes?: string | null,
+  ): Promise<Appointment> {
+    try {
+      const appointment = await this.getAppointmentById(appointmentId);
+      if (!appointment) {
+        throw new Error(`Appointment ${appointmentId} not found`);
+      }
+
+      const currentMetadata = appointment.metadata || {
+        selectedZones: null,
+        zonePhotos: null,
+        zonesData: null,
+        appointmentProducts: [],
+        extendedProcedures: [],
+        recommendedProcedures: [],
+        finalbilling: null,
+        finalizationNotesShared: null,
+        finalizationNotesInternal: null,
+        finalizationNotes: null,
+      };
+
+      const updateData: UpdateAppointmentData = {
+        metadata: {
+          selectedZones: currentMetadata.selectedZones,
+          zonePhotos: currentMetadata.zonePhotos,
+          zonesData: currentMetadata.zonesData || null,
+          appointmentProducts: currentMetadata.appointmentProducts || [],
+          extendedProcedures: currentMetadata.extendedProcedures || [],
+          recommendedProcedures: currentMetadata.recommendedProcedures || [],
+          finalbilling: currentMetadata.finalbilling,
+          finalizationNotesShared:
+            sharedNotes !== undefined ? sharedNotes : currentMetadata.finalizationNotesShared,
+          finalizationNotesInternal:
+            internalNotes !== undefined ? internalNotes : currentMetadata.finalizationNotesInternal,
+          // Keep deprecated field for backward compatibility during migration
+          finalizationNotes:
+            sharedNotes !== undefined
+              ? sharedNotes
+              : currentMetadata.finalizationNotes || currentMetadata.finalizationNotesShared,
+        },
+        updatedAt: serverTimestamp(),
+      };
+
+      return await this.updateAppointment(appointmentId, updateData);
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error updating finalization notes:`, error);
+      throw error;
+    }
+  }
+
   /**
    * Gets all next steps recommendations for a patient from their past appointments.
    * Returns recommendations with context about which appointment, practitioner, and clinic suggested them.

package/src/services/appointment/utils/zone-management.utils.ts

@@ -121,7 +121,9 @@ export function initializeMetadata(appointment: Appointment): AppointmentMetadat
       extendedProcedures: [],
       recommendedProcedures: [],
       finalbilling: null,
-      finalizationNotes: null,
+      finalizationNotesShared: null,
+      finalizationNotesInternal: null,
+      finalizationNotes: null, // @deprecated - kept for backward compatibility
     }
   );
 }
@@ -161,6 +163,8 @@ export async function addItemToZoneUtil(
     ...item,
     parentZone: zoneId, // Set parentZone to the zone key
     subtotal: calculateItemSubtotal(item),
+    // Set default visibility to false (privacy-first) if notes exist and visibility not explicitly set
+    notesVisibleToPatient: item.notesVisibleToPatient ?? (item.notes ? false : undefined),
     createdAt: now,
     updatedAt: now,
   };