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

package/src/utils/TimestampUtils.ts

@@ -1,241 +1,241 @@
-import * as admin from "firebase-admin";
-import { Timestamp as ClientTimestamp } from "firebase/firestore";
-
-/**
- * Detect if we're running in a server environment (like Cloud Functions)
- * or compiled for server usage
- */
-const IS_SERVER_ENV =
-  process.env.NODE_ENV === "production" ||
-  process.env.FUNCTIONS_EMULATOR === "true" ||
-  process.env.FIREBASE_CONFIG !== undefined;
-
-/**
- * Utilities for managing timestamps across client and server-side Firebase code.
- * This module provides conversion functions to ensure timestamp compatibility
- * between admin and client Firebase SDKs.
- */
-export class TimestampUtils {
-  /**
-   * Flag to force server mode where admin timestamps are preserved
-   * This should be true in Cloud Functions environments
-   */
-  private static serverMode = IS_SERVER_ENV;
-
-  /**
-   * Enables server mode where admin timestamps are preserved when saving
-   * to Firestore via the admin SDK
-   */
-  static enableServerMode(): void {
-    this.serverMode = true;
-  }
-
-  /**
-   * Disables server mode - use this only for client-side or mixed environments
-   */
-  static disableServerMode(): void {
-    this.serverMode = false;
-  }
-
-  /**
-   * Converts an admin Firestore Timestamp to a client Firestore Timestamp
-   * In server mode, returns the original admin timestamp for storage consistency
-   *
-   * @param adminTimestamp - Admin SDK Timestamp (from firebase-admin)
-   * @returns A client SDK Timestamp (from firebase/firestore) with same seconds/nanoseconds,
-   *          or the original admin timestamp in server mode,
-   *          or null if input is null
-   */
-  static adminToClient(
-    adminTimestamp: admin.firestore.Timestamp | null
-  ): ClientTimestamp | admin.firestore.Timestamp | null {
-    if (!adminTimestamp) return null;
-
-    // In server mode (Cloud Functions), just return the admin timestamp
-    if (this.serverMode) {
-      return adminTimestamp;
-    }
-
-    // In client mode, convert to client timestamp
-    return new ClientTimestamp(
-      adminTimestamp.seconds,
-      adminTimestamp.nanoseconds
-    );
-  }
-
-  /**
-   * Converts a client Firestore Timestamp to an admin Firestore Timestamp
-   * @param clientTimestamp - Client SDK Timestamp (from firebase/firestore)
-   * @returns An admin SDK Timestamp (from firebase-admin) with same seconds/nanoseconds or null if input is null
-   */
-  static clientToAdmin(
-    clientTimestamp: ClientTimestamp | null
-  ): admin.firestore.Timestamp | null {
-    if (!clientTimestamp) return null;
-
-    return new admin.firestore.Timestamp(
-      clientTimestamp.seconds,
-      clientTimestamp.nanoseconds
-    );
-  }
-
-  /**
-   * Creates a timestamp for the current time in the appropriate format based on environment
-   * @returns A timestamp for the current time (admin timestamp in server mode, client in client mode)
-   */
-  static nowAsTimestamp(): admin.firestore.Timestamp | ClientTimestamp {
-    const now = admin.firestore.Timestamp.now();
-    // In server mode, return the admin timestamp directly
-    if (this.serverMode) {
-      return now;
-    }
-    // In client mode, convert to client timestamp
-    return this.adminToClient(now) as ClientTimestamp;
-  }
-
-  /**
-   * @deprecated Use nowAsTimestamp() instead for better cross-environment compatibility
-   */
-  static nowAsClient(): ClientTimestamp {
-    const now = admin.firestore.Timestamp.now();
-    return this.adminToClient(now) as ClientTimestamp;
-  }
-
-  /**
-   * Converts a Date object to a timestamp in the appropriate format based on environment
-   * @param date - JavaScript Date object
-   * @returns A timestamp (admin timestamp in server mode, client in client mode) or null if input is null
-   */
-  static dateToTimestamp(
-    date: Date | null
-  ): admin.firestore.Timestamp | ClientTimestamp | null {
-    if (!date) return null;
-
-    if (this.serverMode) {
-      return admin.firestore.Timestamp.fromDate(date);
-    }
-
-    return ClientTimestamp.fromDate(date);
-  }
-
-  /**
-   * @deprecated Use dateToTimestamp() instead for better cross-environment compatibility
-   */
-  static dateToClientTimestamp(date: Date | null): ClientTimestamp | null {
-    if (!date) return null;
-    return ClientTimestamp.fromDate(date);
-  }
-
-  /**
-   * @deprecated Use dateToTimestamp() instead for better cross-environment compatibility
-   */
-  static dateToAdminTimestamp(
-    date: Date | null
-  ): admin.firestore.Timestamp | null {
-    if (!date) return null;
-    return admin.firestore.Timestamp.fromDate(date);
-  }
-
-  /**
-   * Gets a server timestamp field value for use in create/update operations
-   * Works in both admin and client environments
-   */
-  static serverTimestamp(): admin.firestore.FieldValue | any {
-    if (this.serverMode) {
-      return admin.firestore.FieldValue.serverTimestamp();
-    }
-    // In client mode, we'd need to import from firebase/firestore
-    // This would be implemented for client environments
-    throw new Error("Server timestamp in client mode not implemented");
-  }
-
-  /**
-   * For objects with mixed timestamp types, ensures all timestamps are
-   * in the correct format for the current environment
-   */
-  static normalizeTimestamps<T>(obj: T): T {
-    if (!obj || typeof obj !== "object") {
-      return obj;
-    }
-
-    if (obj instanceof admin.firestore.Timestamp) {
-      return this.serverMode ? obj : (this.adminToClient(obj) as unknown as T);
-    }
-
-    if (obj instanceof ClientTimestamp && this.serverMode) {
-      return this.clientToAdmin(obj) as unknown as T;
-    }
-
-    if (Array.isArray(obj)) {
-      return obj.map((item) => this.normalizeTimestamps(item)) as unknown as T;
-    }
-
-    const result = { ...obj } as any;
-
-    for (const key in result) {
-      if (Object.prototype.hasOwnProperty.call(result, key)) {
-        result[key] = this.normalizeTimestamps(result[key]);
-      }
-    }
-
-    return result as T;
-  }
-
-  /**
-   * @deprecated Use normalizeTimestamps() instead for better cross-environment compatibility
-   */
-  static convertObjectTimestampsAdminToClient<T>(obj: T): T {
-    if (!obj || typeof obj !== "object") {
-      return obj;
-    }
-
-    if (obj instanceof admin.firestore.Timestamp) {
-      return this.adminToClient(obj) as unknown as T;
-    }
-
-    if (Array.isArray(obj)) {
-      return obj.map((item) =>
-        this.convertObjectTimestampsAdminToClient(item)
-      ) as unknown as T;
-    }
-
-    const result = { ...obj } as any;
-
-    for (const key in result) {
-      if (Object.prototype.hasOwnProperty.call(result, key)) {
-        result[key] = this.convertObjectTimestampsAdminToClient(result[key]);
-      }
-    }
-
-    return result as T;
-  }
-
-  /**
-   * @deprecated Use normalizeTimestamps() instead for better cross-environment compatibility
-   */
-  static convertObjectTimestampsClientToAdmin<T>(obj: T): T {
-    if (!obj || typeof obj !== "object") {
-      return obj;
-    }
-
-    if (obj instanceof ClientTimestamp) {
-      return this.clientToAdmin(obj) as unknown as T;
-    }
-
-    if (Array.isArray(obj)) {
-      return obj.map((item) =>
-        this.convertObjectTimestampsClientToAdmin(item)
-      ) as unknown as T;
-    }
-
-    const result = { ...obj } as any;
-
-    for (const key in result) {
-      if (Object.prototype.hasOwnProperty.call(result, key)) {
-        result[key] = this.convertObjectTimestampsClientToAdmin(result[key]);
-      }
-    }
-
-    return result as T;
-  }
-}
+import * as admin from "firebase-admin";
+import { Timestamp as ClientTimestamp } from "firebase/firestore";
+
+/**
+ * Detect if we're running in a server environment (like Cloud Functions)
+ * or compiled for server usage
+ */
+const IS_SERVER_ENV =
+  process.env.NODE_ENV === "production" ||
+  process.env.FUNCTIONS_EMULATOR === "true" ||
+  process.env.FIREBASE_CONFIG !== undefined;
+
+/**
+ * Utilities for managing timestamps across client and server-side Firebase code.
+ * This module provides conversion functions to ensure timestamp compatibility
+ * between admin and client Firebase SDKs.
+ */
+export class TimestampUtils {
+  /**
+   * Flag to force server mode where admin timestamps are preserved
+   * This should be true in Cloud Functions environments
+   */
+  private static serverMode = IS_SERVER_ENV;
+
+  /**
+   * Enables server mode where admin timestamps are preserved when saving
+   * to Firestore via the admin SDK
+   */
+  static enableServerMode(): void {
+    this.serverMode = true;
+  }
+
+  /**
+   * Disables server mode - use this only for client-side or mixed environments
+   */
+  static disableServerMode(): void {
+    this.serverMode = false;
+  }
+
+  /**
+   * Converts an admin Firestore Timestamp to a client Firestore Timestamp
+   * In server mode, returns the original admin timestamp for storage consistency
+   *
+   * @param adminTimestamp - Admin SDK Timestamp (from firebase-admin)
+   * @returns A client SDK Timestamp (from firebase/firestore) with same seconds/nanoseconds,
+   *          or the original admin timestamp in server mode,
+   *          or null if input is null
+   */
+  static adminToClient(
+    adminTimestamp: admin.firestore.Timestamp | null
+  ): ClientTimestamp | admin.firestore.Timestamp | null {
+    if (!adminTimestamp) return null;
+
+    // In server mode (Cloud Functions), just return the admin timestamp
+    if (this.serverMode) {
+      return adminTimestamp;
+    }
+
+    // In client mode, convert to client timestamp
+    return new ClientTimestamp(
+      adminTimestamp.seconds,
+      adminTimestamp.nanoseconds
+    );
+  }
+
+  /**
+   * Converts a client Firestore Timestamp to an admin Firestore Timestamp
+   * @param clientTimestamp - Client SDK Timestamp (from firebase/firestore)
+   * @returns An admin SDK Timestamp (from firebase-admin) with same seconds/nanoseconds or null if input is null
+   */
+  static clientToAdmin(
+    clientTimestamp: ClientTimestamp | null
+  ): admin.firestore.Timestamp | null {
+    if (!clientTimestamp) return null;
+
+    return new admin.firestore.Timestamp(
+      clientTimestamp.seconds,
+      clientTimestamp.nanoseconds
+    );
+  }
+
+  /**
+   * Creates a timestamp for the current time in the appropriate format based on environment
+   * @returns A timestamp for the current time (admin timestamp in server mode, client in client mode)
+   */
+  static nowAsTimestamp(): admin.firestore.Timestamp | ClientTimestamp {
+    const now = admin.firestore.Timestamp.now();
+    // In server mode, return the admin timestamp directly
+    if (this.serverMode) {
+      return now;
+    }
+    // In client mode, convert to client timestamp
+    return this.adminToClient(now) as ClientTimestamp;
+  }
+
+  /**
+   * @deprecated Use nowAsTimestamp() instead for better cross-environment compatibility
+   */
+  static nowAsClient(): ClientTimestamp {
+    const now = admin.firestore.Timestamp.now();
+    return this.adminToClient(now) as ClientTimestamp;
+  }
+
+  /**
+   * Converts a Date object to a timestamp in the appropriate format based on environment
+   * @param date - JavaScript Date object
+   * @returns A timestamp (admin timestamp in server mode, client in client mode) or null if input is null
+   */
+  static dateToTimestamp(
+    date: Date | null
+  ): admin.firestore.Timestamp | ClientTimestamp | null {
+    if (!date) return null;
+
+    if (this.serverMode) {
+      return admin.firestore.Timestamp.fromDate(date);
+    }
+
+    return ClientTimestamp.fromDate(date);
+  }
+
+  /**
+   * @deprecated Use dateToTimestamp() instead for better cross-environment compatibility
+   */
+  static dateToClientTimestamp(date: Date | null): ClientTimestamp | null {
+    if (!date) return null;
+    return ClientTimestamp.fromDate(date);
+  }
+
+  /**
+   * @deprecated Use dateToTimestamp() instead for better cross-environment compatibility
+   */
+  static dateToAdminTimestamp(
+    date: Date | null
+  ): admin.firestore.Timestamp | null {
+    if (!date) return null;
+    return admin.firestore.Timestamp.fromDate(date);
+  }
+
+  /**
+   * Gets a server timestamp field value for use in create/update operations
+   * Works in both admin and client environments
+   */
+  static serverTimestamp(): admin.firestore.FieldValue | any {
+    if (this.serverMode) {
+      return admin.firestore.FieldValue.serverTimestamp();
+    }
+    // In client mode, we'd need to import from firebase/firestore
+    // This would be implemented for client environments
+    throw new Error("Server timestamp in client mode not implemented");
+  }
+
+  /**
+   * For objects with mixed timestamp types, ensures all timestamps are
+   * in the correct format for the current environment
+   */
+  static normalizeTimestamps<T>(obj: T): T {
+    if (!obj || typeof obj !== "object") {
+      return obj;
+    }
+
+    if (obj instanceof admin.firestore.Timestamp) {
+      return this.serverMode ? obj : (this.adminToClient(obj) as unknown as T);
+    }
+
+    if (obj instanceof ClientTimestamp && this.serverMode) {
+      return this.clientToAdmin(obj) as unknown as T;
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.map((item) => this.normalizeTimestamps(item)) as unknown as T;
+    }
+
+    const result = { ...obj } as any;
+
+    for (const key in result) {
+      if (Object.prototype.hasOwnProperty.call(result, key)) {
+        result[key] = this.normalizeTimestamps(result[key]);
+      }
+    }
+
+    return result as T;
+  }
+
+  /**
+   * @deprecated Use normalizeTimestamps() instead for better cross-environment compatibility
+   */
+  static convertObjectTimestampsAdminToClient<T>(obj: T): T {
+    if (!obj || typeof obj !== "object") {
+      return obj;
+    }
+
+    if (obj instanceof admin.firestore.Timestamp) {
+      return this.adminToClient(obj) as unknown as T;
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.map((item) =>
+        this.convertObjectTimestampsAdminToClient(item)
+      ) as unknown as T;
+    }
+
+    const result = { ...obj } as any;
+
+    for (const key in result) {
+      if (Object.prototype.hasOwnProperty.call(result, key)) {
+        result[key] = this.convertObjectTimestampsAdminToClient(result[key]);
+      }
+    }
+
+    return result as T;
+  }
+
+  /**
+   * @deprecated Use normalizeTimestamps() instead for better cross-environment compatibility
+   */
+  static convertObjectTimestampsClientToAdmin<T>(obj: T): T {
+    if (!obj || typeof obj !== "object") {
+      return obj;
+    }
+
+    if (obj instanceof ClientTimestamp) {
+      return this.clientToAdmin(obj) as unknown as T;
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.map((item) =>
+        this.convertObjectTimestampsClientToAdmin(item)
+      ) as unknown as T;
+    }
+
+    const result = { ...obj } as any;
+
+    for (const key in result) {
+      if (Object.prototype.hasOwnProperty.call(result, key)) {
+        result[key] = this.convertObjectTimestampsClientToAdmin(result[key]);
+      }
+    }
+
+    return result as T;
+  }
+}

package/src/utils/index.ts

@@ -1 +1 @@
-export * from "./TimestampUtils";
+export * from "./TimestampUtils";

package/src/validations/README.md

@@ -0,0 +1,94 @@
+# Validation Schemas (`Api/src/validations/`)
+
+Zod validation schemas for API input validation. Each schema file corresponds to a domain entity.
+
+## Files
+
+| File | Domain | Description |
+|------|--------|-------------|
+| `appointment.schema.ts` | Appointments | Create/update appointment validation |
+| `calendar.schema.ts` | Calendar | Calendar event validation |
+| `clinic.schema.ts` | Clinics | Clinic CRUD validation |
+| `common.schema.ts` | Shared | Common reusable schemas |
+| `media.schema.ts` | Media | File upload validation |
+| `notification.schema.ts` | Notifications | Notification payload validation |
+| `patient.schema.ts` | Patients | Patient profile validation |
+| `practitioner.schema.ts` | Practitioners | Practitioner profile validation |
+| `procedure.schema.ts` | Procedures | Procedure CRUD validation |
+| `procedure-product.schema.ts` | Products | Procedure product pricing validation |
+| `profile-info.schema.ts` | Profiles | Shared profile info validation |
+| **`resource.schema.ts`** | **Resources** | **Resource CRUD + blocking event validation** |
+| `reviews.schema.ts` | Reviews | Patient review validation |
+| `shared.schema.ts` | Shared | Cross-domain shared schemas |
+
+## Resource Validation (`resource.schema.ts`)
+
+Part of the [Clinic Resources System](../../../docs/RESOURCE_SYSTEM.md).
+
+### `createResourceSchema`
+
+Validates input for creating a new resource.
+
+```typescript
+{
+  clinicBranchId: z.string().min(1),     // Required clinic branch ID
+  name: z.string().min(1).max(200),      // Resource name (1-200 chars)
+  category: z.nativeEnum(ResourceCategory), // Must be valid ResourceCategory
+  description: z.string().max(1000).optional(), // Optional description
+  quantity: z.number().int().min(1).max(100),    // 1-100 instances
+}
+```
+
+### `updateResourceSchema`
+
+Validates input for updating an existing resource. All fields are optional.
+
+```typescript
+{
+  name: z.string().min(1).max(200).optional(),
+  category: z.nativeEnum(ResourceCategory).optional(),
+  description: z.string().max(1000).optional(),
+  quantity: z.number().int().min(1).max(100).optional(),
+  status: z.nativeEnum(ResourceStatus).optional(),
+}
+```
+
+**Note on quantity updates:** Validation only ensures the value is within range. The business logic for quantity decrease (checking for active bookings on affected instances) is handled by `ResourceService.updateResource()`.
+
+### `createResourceBlockingEventSchema`
+
+Validates input for creating a blocking event on a resource instance.
+
+```typescript
+{
+  clinicBranchId: z.string().min(1),
+  resourceId: z.string().min(1),
+  resourceInstanceId: z.string().min(1),
+  eventName: z.string().min(1).max(200),      // Event name (1-200 chars)
+  eventTime: z.object({
+    start: z.any(),                            // Firestore Timestamp
+    end: z.any(),                              // Firestore Timestamp
+  }),
+  description: z.string().max(1000).optional(), // Optional reason
+}
+```
+
+### `updateResourceBlockingEventSchema`
+
+Validates input for updating a blocking event. All fields except IDs are optional.
+
+```typescript
+{
+  clinicBranchId: z.string().min(1),
+  resourceId: z.string().min(1),
+  resourceInstanceId: z.string().min(1),
+  eventId: z.string().min(1),
+  eventName: z.string().min(1).max(200).optional(),
+  eventTime: z.object({ start: z.any(), end: z.any() }).optional(),
+  description: z.string().max(1000).optional(),
+}
+```
+
+## Export
+
+All schemas are exported via `index.ts`.