@blackcode_sa/metaestetics-api 1.6.12 → 1.6.14

package/dist/index.d.mts

@@ -1905,7 +1905,7 @@ interface CreatePatientProfileData {
 /**
  * Tip za ažuriranje Patient profila
  */
-interface UpdatePatientProfileData extends Partial<Omit<PatientProfile, "id" | "createdAt" | "updatedAt">> {
+interface UpdatePatientProfileData extends Partial<Omit<PatientProfile, 'id' | 'createdAt' | 'updatedAt'>> {
     updatedAt?: FieldValue;
 }
 /**
@@ -1924,7 +1924,7 @@ interface RequesterInfo {
     /** ID of the clinic admin user or practitioner user making the request. */
     id: string;
     /** Role of the requester, determining the search context. */
-    role: "clinic_admin" | "practitioner";
+    role: 'clinic_admin' | 'practitioner';
     /** If role is 'clinic_admin', this is the associated clinic ID. */
     associatedClinicId?: string;
     /** If role is 'practitioner', this is the associated practitioner profile ID. */

package/dist/index.d.ts

@@ -1905,7 +1905,7 @@ interface CreatePatientProfileData {
 /**
  * Tip za ažuriranje Patient profila
  */
-interface UpdatePatientProfileData extends Partial<Omit<PatientProfile, "id" | "createdAt" | "updatedAt">> {
+interface UpdatePatientProfileData extends Partial<Omit<PatientProfile, 'id' | 'createdAt' | 'updatedAt'>> {
     updatedAt?: FieldValue;
 }
 /**
@@ -1924,7 +1924,7 @@ interface RequesterInfo {
     /** ID of the clinic admin user or practitioner user making the request. */
     id: string;
     /** Role of the requester, determining the search context. */
-    role: "clinic_admin" | "practitioner";
+    role: 'clinic_admin' | 'practitioner';
     /** If role is 'clinic_admin', this is the associated clinic ID. */
     associatedClinicId?: string;
     /** If role is 'practitioner', this is the associated practitioner profile ID. */

package/package.json

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

package/src/admin/booking/booking.admin.ts

@@ -62,6 +62,7 @@ import {
 } from "../../types/calendar";
 import { DocumentManagerAdminService } from "../documentation-templates/document-manager.admin";
 import { LinkedFormInfo } from "../../types/appointment";
+import { TimestampUtils } from "../../utils/TimestampUtils";
 
 /**
  * Interface for the data required by orchestrateAppointmentCreation
@@ -205,15 +206,8 @@ export class BookingAdmin {
   private adminTimestampToClientTimestamp(
     timestamp: admin.firestore.Timestamp
   ): any {
-    // Create a client Timestamp with the same seconds and nanoseconds
-    return {
-      seconds: timestamp.seconds,
-      nanoseconds: timestamp.nanoseconds,
-      toDate: () => timestamp.toDate(),
-      toMillis: () => timestamp.toMillis(),
-      valueOf: () => timestamp.valueOf(),
-      // Add any other required methods/properties
-    };
+    // Use TimestampUtils instead of custom implementation
+    return TimestampUtils.adminToClient(timestamp);
   }
 
   /**
@@ -223,8 +217,8 @@ export class BookingAdmin {
     return events.map((event) => ({
       ...event,
       eventTime: {
-        start: this.adminTimestampToClientTimestamp(event.eventTime.start),
-        end: this.adminTimestampToClientTimestamp(event.eventTime.end),
+        start: TimestampUtils.adminToClient(event.eventTime.start),
+        end: TimestampUtils.adminToClient(event.eventTime.end),
       },
       // Convert any other timestamps in the event if needed
     }));

package/src/admin/index.ts

@@ -12,6 +12,7 @@ import {
 import { DoctorInfo } from "../types/clinic";
 import { Procedure, ProcedureSummaryInfo } from "../types/procedure";
 import { PatientProfile } from "../types/patient";
+import { Appointment, AppointmentStatus } from "../types/appointment";
 
 // Explicitly import the services to re-export them by name
 import { ClinicAggregationService } from "./aggregation/clinic/clinic.aggregation.service";
@@ -46,6 +47,7 @@ export type { Practitioner, PractitionerToken } from "../types/practitioner";
 export type { DoctorInfo } from "../types/clinic";
 export type { Procedure, ProcedureSummaryInfo } from "../types/procedure";
 export type { PatientProfile as Patient } from "../types/patient";
+export type { Appointment } from "../types/appointment";
 
 // Re-export enums/consts
 export {
@@ -55,6 +57,7 @@ export {
 } from "../types/notifications";
 export { UserRole } from "../types";
 export { PractitionerTokenStatus } from "../types/practitioner";
+export { AppointmentStatus } from "../types/appointment";
 
 // Export admin classes/services explicitly by name
 export {

package/src/admin/notifications/notifications.admin.ts

@@ -8,6 +8,7 @@ import { Expo, ExpoPushMessage, ExpoPushTicket } from "expo-server-sdk";
 import { Appointment, PaymentStatus } from "../../types/appointment";
 import { UserRole } from "../../types";
 import { Timestamp as FirebaseClientTimestamp } from "@firebase/firestore";
+import { TimestampUtils } from "../../utils/TimestampUtils";
 
 export class NotificationsAdmin {
   private expo: Expo;
@@ -277,10 +278,9 @@ export class NotificationsAdmin {
     }
 
     const adminTsNow = admin.firestore.Timestamp.now();
-    const clientCompatibleNotificationTime = new FirebaseClientTimestamp(
-      adminTsNow.seconds,
-      adminTsNow.nanoseconds
-    );
+    const clientCompatibleNotificationTime = TimestampUtils.adminToClient(
+      adminTsNow
+    ) as FirebaseClientTimestamp;
 
     const notificationData: Omit<
       Notification,
@@ -354,10 +354,9 @@ export class NotificationsAdmin {
     }
 
     const adminTsNow = admin.firestore.Timestamp.now();
-    const clientCompatibleNotificationTime = new FirebaseClientTimestamp(
-      adminTsNow.seconds,
-      adminTsNow.nanoseconds
-    );
+    const clientCompatibleNotificationTime = TimestampUtils.adminToClient(
+      adminTsNow
+    ) as FirebaseClientTimestamp;
 
     const notificationData: Omit<
       Notification,
@@ -406,10 +405,9 @@ export class NotificationsAdmin {
     const body = `Action Required: A new time has been proposed for your appointment for ${appointment.procedureInfo.name}. Please review in the app.`;
 
     const adminTsNow = admin.firestore.Timestamp.now();
-    const clientCompatibleNotificationTime = new FirebaseClientTimestamp(
-      adminTsNow.seconds,
-      adminTsNow.nanoseconds
-    );
+    const clientCompatibleNotificationTime = TimestampUtils.adminToClient(
+      adminTsNow
+    ) as FirebaseClientTimestamp;
 
     const notificationData: Omit<
       Notification,
@@ -461,10 +459,9 @@ export class NotificationsAdmin {
       .toLocaleDateString()} is now ${appointment.paymentStatus}.`;
 
     const adminTsNow = admin.firestore.Timestamp.now();
-    const clientCompatibleNotificationTime = new FirebaseClientTimestamp(
-      adminTsNow.seconds,
-      adminTsNow.nanoseconds
-    );
+    const clientCompatibleNotificationTime = TimestampUtils.adminToClient(
+      adminTsNow
+    ) as FirebaseClientTimestamp;
 
     const notificationType =
       appointment.paymentStatus === PaymentStatus.PAID
@@ -518,10 +515,9 @@ export class NotificationsAdmin {
     const body = `How was your recent appointment for ${appointment.procedureInfo.name}? We'd love to hear your feedback!`;
 
     const adminTsNow = admin.firestore.Timestamp.now();
-    const clientCompatibleNotificationTime = new FirebaseClientTimestamp(
-      adminTsNow.seconds,
-      adminTsNow.nanoseconds
-    );
+    const clientCompatibleNotificationTime = TimestampUtils.adminToClient(
+      adminTsNow
+    ) as FirebaseClientTimestamp;
 
     const notificationData: Omit<
       Notification,
@@ -581,10 +577,9 @@ export class NotificationsAdmin {
       .toLocaleDateString()}.`;
 
     const adminTsNow = admin.firestore.Timestamp.now();
-    const clientCompatibleNotificationTime = new FirebaseClientTimestamp(
-      adminTsNow.seconds,
-      adminTsNow.nanoseconds
-    );
+    const clientCompatibleNotificationTime = TimestampUtils.adminToClient(
+      adminTsNow
+    ) as FirebaseClientTimestamp;
 
     const tempNotificationType = NotificationType.GENERAL_MESSAGE;
 

package/src/admin/requirements/patient-requirements.admin.service.ts

@@ -17,6 +17,7 @@ import {
 import { PatientProfile, PATIENTS_COLLECTION } from "../../types/patient";
 import { UserRole } from "../../types"; // Assuming UserRole is in the main types index
 import { NotificationsAdmin } from "../notifications/notifications.admin";
+import { TimestampUtils } from "../../utils/TimestampUtils";
 
 /**
  * @class PatientRequirementsAdminService
@@ -106,10 +107,9 @@ export class PatientRequirementsAdminService {
             ...currentInstruction,
             notificationId: undefined,
             status: PatientInstructionStatus.CANCELLED,
-            updatedAt: new FirebaseClientTimestamp(
-              adminTsNow.seconds,
-              adminTsNow.nanoseconds
-            ),
+            updatedAt: TimestampUtils.adminToClient(
+              adminTsNow
+            ) as FirebaseClientTimestamp,
           };
           updatedInstructions[i] = currentInstruction;
           instructionUpdatesMade = true;
@@ -144,10 +144,9 @@ export class PatientRequirementsAdminService {
         currentInstruction = {
           ...currentInstruction,
           notificationId: undefined,
-          updatedAt: new FirebaseClientTimestamp(
-            adminTsNow.seconds,
-            adminTsNow.nanoseconds
-          ),
+          updatedAt: TimestampUtils.adminToClient(
+            adminTsNow
+          ) as FirebaseClientTimestamp,
         };
         updatedInstructions[i] = currentInstruction;
         instructionUpdatesMade = true;
@@ -196,10 +195,9 @@ export class PatientRequirementsAdminService {
             ...currentInstruction,
             notificationId: createdNotificationId,
             status: PatientInstructionStatus.PENDING_NOTIFICATION,
-            updatedAt: new FirebaseClientTimestamp(
-              adminTsNow.seconds,
-              adminTsNow.nanoseconds
-            ),
+            updatedAt: TimestampUtils.adminToClient(
+              adminTsNow
+            ) as FirebaseClientTimestamp,
           };
           updatedInstructions[i] = currentInstruction;
           instructionUpdatesMade = true;
@@ -225,10 +223,9 @@ export class PatientRequirementsAdminService {
       const finalAdminTsNow = admin.firestore.Timestamp.now();
       await instanceDocRef.update({
         instructions: updatedInstructions, // Array of instructions with actual Timestamps
-        updatedAt: new FirebaseClientTimestamp(
-          finalAdminTsNow.seconds,
-          finalAdminTsNow.nanoseconds
-        ),
+        updatedAt: TimestampUtils.adminToClient(
+          finalAdminTsNow
+        ) as FirebaseClientTimestamp,
       });
     }
   }
@@ -332,10 +329,9 @@ export class PatientRequirementsAdminService {
         currentInstruction = {
           ...currentInstruction,
           status: PatientInstructionStatus.MISSED,
-          updatedAt: new FirebaseClientTimestamp(
-            adminNowForMissed.seconds,
-            adminNowForMissed.nanoseconds
-          ),
+          updatedAt: TimestampUtils.adminToClient(
+            adminNowForMissed
+          ) as FirebaseClientTimestamp,
         };
         updatedInstructions[i] = currentInstruction;
         changesMade = true;
@@ -349,10 +345,9 @@ export class PatientRequirementsAdminService {
       const finalAdminNowForMissedUpdate = admin.firestore.Timestamp.now();
       await instanceRef.update({
         instructions: updatedInstructions, // Array of instructions with actual Timestamps
-        updatedAt: new FirebaseClientTimestamp(
-          finalAdminNowForMissedUpdate.seconds,
-          finalAdminNowForMissedUpdate.nanoseconds
-        ),
+        updatedAt: TimestampUtils.adminToClient(
+          finalAdminNowForMissedUpdate
+        ) as FirebaseClientTimestamp,
       });
       console.log(
         `[PRA_Service] Updated missed instructions for instance ${instanceId}.`
@@ -416,10 +411,9 @@ export class PatientRequirementsAdminService {
         );
         await instanceRef.update({
           overallStatus: PatientRequirementOverallStatus.ACTIVE,
-          updatedAt: new FirebaseClientTimestamp(
-            admin.firestore.Timestamp.now().seconds,
-            admin.firestore.Timestamp.now().nanoseconds
-          ),
+          updatedAt: TimestampUtils.adminToClient(
+            admin.firestore.Timestamp.now()
+          ) as FirebaseClientTimestamp,
         });
       }
       return;
@@ -468,10 +462,9 @@ export class PatientRequirementsAdminService {
       const adminTsNow = admin.firestore.Timestamp.now();
       await instanceRef.update({
         overallStatus: newOverallStatus,
-        updatedAt: new FirebaseClientTimestamp(
-          adminTsNow.seconds,
-          adminTsNow.nanoseconds
-        ),
+        updatedAt: TimestampUtils.adminToClient(
+          adminTsNow
+        ) as FirebaseClientTimestamp,
       });
     } else {
       console.log(

package/src/types/clinic/index.ts

@@ -1,26 +1,18 @@
-import { Timestamp, FieldValue } from "firebase/firestore";
-import type { ProcedureFamily } from "../../backoffice/types/static/procedure-family.types";
-import type { TreatmentBenefit } from "../../backoffice/types/static/treatment-benefit.types";
-import type {
-  Currency,
-  PricingMeasure,
-} from "../../backoffice/types/static/pricing.types";
-import type { ClinicInfo } from "../profile";
-import { ClinicReviewInfo } from "../reviews";
-import { ProcedureSummaryInfo } from "../procedure";
+import { Timestamp, FieldValue } from 'firebase/firestore';
+import type { ProcedureFamily } from '../../backoffice/types/static/procedure-family.types';
+import type { TreatmentBenefit } from '../../backoffice/types/static/treatment-benefit.types';
+import type { Currency, PricingMeasure } from '../../backoffice/types/static/pricing.types';
+import type { ClinicInfo } from '../profile';
+import { ClinicReviewInfo } from '../reviews';
+import { ProcedureSummaryInfo } from '../procedure';
 
-export const CLINIC_GROUPS_COLLECTION = "clinic_groups";
-export const CLINIC_ADMINS_COLLECTION = "clinic_admins";
-export const CLINICS_COLLECTION = "clinics";
+export const CLINIC_GROUPS_COLLECTION = 'clinic_groups';
+export const CLINIC_ADMINS_COLLECTION = 'clinic_admins';
+export const CLINICS_COLLECTION = 'clinics';
 
-import {
-  PracticeType,
-  Language,
-  ClinicTag,
-  ClinicPhotoTag,
-} from "./preferences.types";
+import { PracticeType, Language, ClinicTag, ClinicPhotoTag } from './preferences.types';
 
-export * from "./preferences.types";
+export * from './preferences.types';
 
 /**
  * Interface for clinic contact information
@@ -140,9 +132,9 @@ export interface UpdateClinicAdminData extends Partial<CreateClinicAdminData> {
  * Enum for admin token status
  */
 export enum AdminTokenStatus {
-  ACTIVE = "active",
-  USED = "used",
-  EXPIRED = "expired",
+  ACTIVE = 'active',
+  USED = 'used',
+  EXPIRED = 'expired',
 }
 
 /**
@@ -171,10 +163,10 @@ export interface AdminInfo {
  * Enum for subscription models
  */
 export enum SubscriptionModel {
-  NO_SUBSCRIPTION = "no_subscription",
-  BASIC = "basic",
-  PREMIUM = "premium",
-  ENTERPRISE = "enterprise",
+  NO_SUBSCRIPTION = 'no_subscription',
+  BASIC = 'basic',
+  PREMIUM = 'premium',
+  ENTERPRISE = 'enterprise',
 }
 
 /**

package/src/types/patient/index.ts

@@ -1,24 +1,24 @@
-import { Timestamp, FieldValue } from "firebase/firestore";
-import { User } from "..";
-import type { PatientMedicalInfo } from "./medical-info.types";
-import { PATIENT_MEDICAL_INFO_COLLECTION } from "./medical-info.types";
+import { Timestamp, FieldValue } from 'firebase/firestore';
+import { User } from '..';
+import type { PatientMedicalInfo } from './medical-info.types';
+import { PATIENT_MEDICAL_INFO_COLLECTION } from './medical-info.types';
 
-export const PATIENTS_COLLECTION = "patients";
-export const PATIENT_SENSITIVE_INFO_COLLECTION = "sensitive-info";
-export const PATIENT_MEDICAL_HISTORY_COLLECTION = "medical-history";
-export const PATIENT_APPOINTMENTS_COLLECTION = "appointments";
-export const PATIENT_LOCATION_INFO_COLLECTION = "location-info";
+export const PATIENTS_COLLECTION = 'patients';
+export const PATIENT_SENSITIVE_INFO_COLLECTION = 'sensitive-info';
+export const PATIENT_MEDICAL_HISTORY_COLLECTION = 'medical-history';
+export const PATIENT_APPOINTMENTS_COLLECTION = 'appointments';
+export const PATIENT_LOCATION_INFO_COLLECTION = 'location-info';
 
 /**
  * Enumeracija za pol pacijenta
  */
 export enum Gender {
-  MALE = "male",
-  FEMALE = "female",
-  TRANSGENDER_MALE = "transgender_male",
-  TRANSGENDER_FEMALE = "transgender_female",
-  PREFER_NOT_TO_SAY = "prefer_not_to_say",
-  OTHER = "other",
+  MALE = 'male',
+  FEMALE = 'female',
+  TRANSGENDER_MALE = 'transgender_male',
+  TRANSGENDER_FEMALE = 'transgender_female',
+  PREFER_NOT_TO_SAY = 'prefer_not_to_say',
+  OTHER = 'other',
 }
 
 /**
@@ -83,8 +83,7 @@ export interface CreatePatientLocationInfoData {
 /**
  * Tip za ažuriranje lokacijskih informacija
  */
-export interface UpdatePatientLocationInfoData
-  extends Partial<CreatePatientLocationInfoData> {
+export interface UpdatePatientLocationInfoData extends Partial<CreatePatientLocationInfoData> {
   updatedAt?: FieldValue;
 }
 
@@ -129,8 +128,7 @@ export interface CreatePatientSensitiveInfoData {
 /**
  * Tip za ažuriranje osetljivih informacija
  */
-export interface UpdatePatientSensitiveInfoData
-  extends Partial<CreatePatientSensitiveInfoData> {
+export interface UpdatePatientSensitiveInfoData extends Partial<CreatePatientSensitiveInfoData> {
   updatedAt?: FieldValue;
 }
 
@@ -198,7 +196,7 @@ export interface CreatePatientProfileData {
  * Tip za ažuriranje Patient profila
  */
 export interface UpdatePatientProfileData
-  extends Partial<Omit<PatientProfile, "id" | "createdAt" | "updatedAt">> {
+  extends Partial<Omit<PatientProfile, 'id' | 'createdAt' | 'updatedAt'>> {
   // Use Omit to exclude base fields
   updatedAt?: FieldValue;
   // Note: doctors, clinics, doctorIds, clinicIds should ideally be updated via specific methods (add/removeDoctor/Clinic)
@@ -221,14 +219,14 @@ export interface RequesterInfo {
   /** ID of the clinic admin user or practitioner user making the request. */
   id: string;
   /** Role of the requester, determining the search context. */
-  role: "clinic_admin" | "practitioner";
+  role: 'clinic_admin' | 'practitioner';
   /** If role is 'clinic_admin', this is the associated clinic ID. */
   associatedClinicId?: string;
   /** If role is 'practitioner', this is the associated practitioner profile ID. */
   associatedPractitionerId?: string;
 }
 
-export * from "./medical-info.types";
+export * from './medical-info.types';
 
 // This is a type that combines all the patient data - used only in UI Frontend App
 export interface PatientProfileComplete {

package/src/utils/TIMESTAMPS.md

@@ -0,0 +1,176 @@
+# Timestamp Management Strategy
+
+## Problem Statement
+
+Firebase provides two different Timestamp implementations across its SDKs:
+
+1. **Client-side Timestamp**: `import { Timestamp } from 'firebase/firestore'`
+
+   - Used in client applications (web, mobile)
+   - Lives in the `firebase/firestore` package
+
+2. **Admin-side Timestamp**: `import * as admin from 'firebase-admin'; admin.firestore.Timestamp`
+   - Used in server-side code (Cloud Functions)
+   - Lives in the `firebase-admin` package
+
+These types are structurally similar but are different JavaScript classes, causing type conflicts when:
+
+- Data with client Timestamps is processed in admin code
+- Data with admin Timestamps is sent to client code
+- Shared type definitions across client and admin code
+
+## Solution: TimestampUtils
+
+We've created a central `TimestampUtils` class providing:
+
+1. Conversion utilities between admin and client Timestamps
+2. Best practices for timestamp handling
+3. Consistent patterns for timestamp operations
+
+## Usage Guidelines
+
+### 1. Type Definitions
+
+All shared type definitions (in `src/types/*`) should:
+
+- Import Timestamp from client SDK: `import { Timestamp } from 'firebase/firestore'`
+- Define fields using this client Timestamp: `timestamp: Timestamp`
+
+This ensures types are consumable by both client and admin code.
+
+### 2. Admin Code (Cloud Functions)
+
+When writing admin code that:
+
+- **Reads data from Firestore**: No conversion needed, as Firestore returns admin Timestamps
+- **Processes timestamps**: Use standard admin timestamp methods
+- **Writes data to shared types**: Convert admin → client using `TimestampUtils.adminToClient()`
+- **Creates server timestamps**: For fields created with `serverTimestamp()`, use Firebase Admin's version: `admin.firestore.FieldValue.serverTimestamp()`
+
+Example:
+
+```typescript
+import * as admin from "firebase-admin";
+import { TimestampUtils } from "../../utils/TimestampUtils";
+import { YourSharedType } from "../../types/shared";
+
+// In your admin service
+async function processAndUpdateData() {
+  const adminTsNow = admin.firestore.Timestamp.now();
+
+  // When populating a shared type that clients will use
+  const data: YourSharedType = {
+    // Convert admin timestamp to client timestamp
+    createdAt: TimestampUtils.adminToClient(adminTsNow),
+
+    // For server timestamps, use admin version
+    updatedAt: admin.firestore.FieldValue.serverTimestamp(),
+
+    // Other fields...
+  };
+
+  // When you need to process objects with nested timestamps
+  const objectWithNestedTimestamps = {
+    // Complex data from another source
+  };
+
+  // Convert all timestamps in the object from admin to client
+  const clientCompatible = TimestampUtils.convertObjectTimestampsAdminToClient(
+    objectWithNestedTimestamps
+  );
+}
+```
+
+### 3. Client Code (Web/Mobile Apps)
+
+Client code should:
+
+- Use `firebase/firestore` Timestamp when needed
+- No conversion is necessary for data returned by `getDocs()` or similar client SDK methods
+- For new timestamps, use `Timestamp.now()` or `Timestamp.fromDate()`
+
+### 4. Utility Functions
+
+The `TimestampUtils` class provides these key functions:
+
+- `adminToClient(adminTimestamp)`: Converts admin → client Timestamp
+- `clientToAdmin(clientTimestamp)`: Converts client → admin Timestamp
+- `nowAsClient()`: Creates current timestamp as client Timestamp
+- `dateToClientTimestamp(date)`: Converts Date → client Timestamp
+- `dateToAdminTimestamp(date)`: Converts Date → admin Timestamp
+- `convertObjectTimestampsAdminToClient(obj)`: Deep conversion of all timestamps in an object from admin → client
+- `convertObjectTimestampsClientToAdmin(obj)`: Deep conversion of all timestamps in an object from client → admin
+
+## Common Patterns
+
+### 1. Creating New Documents
+
+```typescript
+// In admin code
+const adminTimestamp = admin.firestore.Timestamp.now();
+const clientCompatibleTimestamp = TimestampUtils.adminToClient(adminTimestamp);
+
+const newDocument = {
+  id: "doc123",
+  createdAt: clientCompatibleTimestamp,
+  // For server-managed timestamps, use serverTimestamp()
+  updatedAt: admin.firestore.FieldValue.serverTimestamp(),
+};
+
+await docRef.set(newDocument);
+```
+
+### 2. Updating Fields in a Document
+
+```typescript
+// In admin code
+await docRef.update({
+  someField: "new value",
+  // For immediate timestamp, convert admin to client
+  processedAt: TimestampUtils.adminToClient(admin.firestore.Timestamp.now()),
+  // For server-managed timestamps, use serverTimestamp()
+  updatedAt: admin.firestore.FieldValue.serverTimestamp(),
+});
+```
+
+### 3. Processing Calendar Events
+
+Calendar events and date ranges should be consistently handled:
+
+```typescript
+// Calendar event time conversion
+const firestoreCompatibleEventTime = {
+  start: {
+    seconds: newEventTime.start.seconds,
+    nanoseconds: newEventTime.start.nanoseconds,
+  },
+  end: {
+    seconds: newEventTime.end.seconds,
+    nanoseconds: newEventTime.end.nanoseconds,
+  },
+};
+```
+
+## Edge Cases and Limitations
+
+1. **null/undefined Handling**: All utility methods handle null safely
+2. **Serialization**: If serializing for JSON, convert to ISO strings first
+3. **Performance**: The conversion is lightweight, but for large batches, process efficiently
+
+## Migration Strategy
+
+1. Identify timestamp usage in your code using static analysis or grep
+2. Replace direct timestamp conversions with TimestampUtils methods
+3. Update methods like:
+   - `adminTimestampToClientTimestamp` → `TimestampUtils.adminToClient`
+   - Direct creation of client timestamps → `TimestampUtils.nowAsClient`
+4. Test thoroughly after each change
+
+## Conclusion
+
+Following this strategy will:
+
+- Eliminate type errors between admin and client code
+- Provide consistent timestamp handling throughout the codebase
+- Minimize conversion bugs by centralizing conversion logic
+- Make it easier to onboard new developers to the codebase