@blackcode_sa/metaestetics-api 1.15.8 → 1.15.9

package/package.json

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

package/src/config/index.ts

@@ -7,3 +7,12 @@ export {
   getFirebaseStorage,
   getFirebaseFunctions,
 } from "./firebase";
+
+export {
+  PERMISSION_KEYS,
+  TIER_CONFIG,
+  DEFAULT_ROLE_PERMISSIONS,
+  LEGACY_TIER_MAP,
+  resolveEffectiveTier,
+} from "./tiers.config";
+export type { PermissionKey } from "./tiers.config";

package/src/config/tiers.config.ts

@@ -0,0 +1,237 @@
+import { ClinicRole } from '../types/clinic/rbac.types';
+import type { TierConfig } from '../types/clinic/rbac.types';
+
+/**
+ * Permission keys used for role-based access control.
+ * Every feature is available on every tier — these only control
+ * what a given role (owner/admin/doctor/etc.) can do.
+ */
+export const PERMISSION_KEYS = {
+  // Listing & profile
+  'clinic.view': true,
+  'clinic.edit': true,
+  'reviews.view': true,
+
+  // Calendar & Appointments
+  'calendar.view': true,
+  'appointments.view': true,
+  'appointments.confirm': true,
+  'appointments.cancel': true,
+
+  // Messaging
+  'messaging': true,
+
+  // Procedures
+  'procedures.view': true,
+  'procedures.create': true,
+  'procedures.edit': true,
+  'procedures.delete': true,
+
+  // Patients
+  'patients.view': true,
+  'patients.edit': true,
+
+  // Providers (doctors, nurses, laser assistants, etc.)
+  'providers.view': true,
+  'providers.manage': true,
+
+  // Analytics
+  'analytics.view': true,
+
+  // Staff management
+  'staff.manage': true,
+
+  // Settings / Admin
+  'settings.manage': true,
+  'billing.manage': true,
+} as const;
+
+export type PermissionKey = keyof typeof PERMISSION_KEYS;
+
+/**
+ * Usage limits per subscription tier.
+ * All features are available on every tier — tiers differ only in usage caps.
+ * -1 means unlimited.
+ *
+ * Confirmed by client on 2026-03-09:
+ * - Free: 1 provider, 3 procedures, 3 appts/mo, 10 msgs/mo, 1 staff, 1 branch
+ * - Connect: 5 providers, 15 procedures, 100 appts/mo, unlimited msgs, 5 staff, 1 branch
+ * - Pro: unlimited everything
+ */
+export const TIER_CONFIG: Record<string, TierConfig> = {
+  free: {
+    tier: 'free',
+    name: 'Free',
+    limits: {
+      maxProviders: 1,
+      maxProcedures: 3,
+      maxAppointmentsPerMonth: 3,
+      maxMessagesPerMonth: 10,
+      maxStaff: 1,
+      maxBranches: 1,
+    },
+  },
+  connect: {
+    tier: 'connect',
+    name: 'Connect',
+    limits: {
+      maxProviders: 5,
+      maxProcedures: 15,
+      maxAppointmentsPerMonth: 100,
+      maxMessagesPerMonth: -1,
+      maxStaff: 5,
+      maxBranches: 1,
+    },
+  },
+  pro: {
+    tier: 'pro',
+    name: 'Pro',
+    limits: {
+      maxProviders: -1,
+      maxProcedures: -1,
+      maxAppointmentsPerMonth: -1,
+      maxMessagesPerMonth: -1,
+      maxStaff: -1,
+      maxBranches: -1,
+    },
+  },
+};
+
+/**
+ * Default permissions per ClinicRole.
+ * These are the baseline permissions for each role; owners can override per-user.
+ */
+export const DEFAULT_ROLE_PERMISSIONS: Record<ClinicRole, Record<string, boolean>> = {
+  [ClinicRole.OWNER]: {
+    'clinic.view': true,
+    'clinic.edit': true,
+    'reviews.view': true,
+    'calendar.view': true,
+    'appointments.view': true,
+    'appointments.confirm': true,
+    'appointments.cancel': true,
+    'messaging': true,
+    'procedures.view': true,
+    'procedures.create': true,
+    'procedures.edit': true,
+    'procedures.delete': true,
+    'patients.view': true,
+    'patients.edit': true,
+    'providers.view': true,
+    'providers.manage': true,
+    'analytics.view': true,
+    'staff.manage': true,
+    'settings.manage': true,
+    'billing.manage': true,
+  },
+  [ClinicRole.ADMIN]: {
+    'clinic.view': true,
+    'clinic.edit': true,
+    'reviews.view': true,
+    'calendar.view': true,
+    'appointments.view': true,
+    'appointments.confirm': true,
+    'appointments.cancel': true,
+    'messaging': true,
+    'procedures.view': true,
+    'procedures.create': true,
+    'procedures.edit': true,
+    'procedures.delete': true,
+    'patients.view': true,
+    'patients.edit': true,
+    'providers.view': true,
+    'providers.manage': true,
+    'analytics.view': true,
+    'staff.manage': false,
+    'settings.manage': true,
+    'billing.manage': false,
+  },
+  [ClinicRole.DOCTOR]: {
+    'clinic.view': true,
+    'clinic.edit': false,
+    'reviews.view': true,
+    'calendar.view': true,
+    'appointments.view': true,
+    'appointments.confirm': true,
+    'appointments.cancel': true,
+    'messaging': true,
+    'procedures.view': true,
+    'procedures.create': false,
+    'procedures.edit': false,
+    'procedures.delete': false,
+    'patients.view': true,
+    'patients.edit': true,
+    'providers.view': true,
+    'providers.manage': false,
+    'analytics.view': true,
+    'staff.manage': false,
+    'settings.manage': false,
+    'billing.manage': false,
+  },
+  [ClinicRole.RECEPTIONIST]: {
+    'clinic.view': true,
+    'clinic.edit': false,
+    'reviews.view': true,
+    'calendar.view': true,
+    'appointments.view': true,
+    'appointments.confirm': true,
+    'appointments.cancel': false,
+    'messaging': true,
+    'procedures.view': true,
+    'procedures.create': false,
+    'procedures.edit': false,
+    'procedures.delete': false,
+    'patients.view': true,
+    'patients.edit': false,
+    'providers.view': true,
+    'providers.manage': false,
+    'analytics.view': false,
+    'staff.manage': false,
+    'settings.manage': false,
+    'billing.manage': false,
+  },
+  [ClinicRole.ASSISTANT]: {
+    'clinic.view': true,
+    'clinic.edit': false,
+    'reviews.view': true,
+    'calendar.view': true,
+    'appointments.view': true,
+    'appointments.confirm': false,
+    'appointments.cancel': false,
+    'messaging': false,
+    'procedures.view': true,
+    'procedures.create': false,
+    'procedures.edit': false,
+    'procedures.delete': false,
+    'patients.view': true,
+    'patients.edit': false,
+    'providers.view': true,
+    'providers.manage': false,
+    'analytics.view': false,
+    'staff.manage': false,
+    'settings.manage': false,
+    'billing.manage': false,
+  },
+};
+
+/**
+ * Maps legacy subscription models to new tier equivalents.
+ * All paid legacy tiers map to PRO.
+ */
+export const LEGACY_TIER_MAP: Record<string, string> = {
+  basic: 'pro',
+  premium: 'pro',
+  enterprise: 'pro',
+};
+
+/**
+ * Resolves the effective tier for a subscription model string,
+ * handling legacy values.
+ */
+export function resolveEffectiveTier(subscriptionModel: string): string {
+  const lower = subscriptionModel.toLowerCase();
+  if (LEGACY_TIER_MAP[lower]) {
+    return LEGACY_TIER_MAP[lower];
+  }
+  return lower;
+}

package/src/services/clinic/clinic.service.ts

@@ -20,6 +20,7 @@ import {
 import { getFunctions, httpsCallable } from "firebase/functions";
 import tzlookup from "tz-lookup";
 import { BaseService } from "../base.service";
+import { enforceBranchLimit } from "../tier-enforcement";
 import {
   Clinic,
   CreateClinicData,
@@ -221,6 +222,9 @@ export class ClinicService extends BaseService {
         );
       }
 
+      // Enforce tier limit before creating clinic branch
+      await enforceBranchLimit(this.db, validatedData.clinicGroupId);
+
       // Process media fields - convert File/Blob objects to URLs
       const logoUrl = await this.processMedia(
         validatedData.logo,
@@ -587,6 +591,9 @@ export class ClinicService extends BaseService {
     }
     console.log("[CLINIC_SERVICE] Clinic group verified");
 
+    // Enforce tier limit before creating clinic branch
+    await enforceBranchLimit(this.db, clinicGroupId);
+
     // Validate branch setup data first
     const validatedSetupData = clinicBranchSetupSchema.parse(setupData);
 

package/src/services/index.ts

@@ -12,3 +12,4 @@ export * from "./procedure";
 export * from "./reviews";
 export * from "./user";
 export * from "./base.service";
+export * from "./tier-enforcement";

package/src/services/patient/patientRequirements.service.ts

@@ -212,6 +212,30 @@ export class PatientRequirementsService extends BaseService {
 
     const instructionToUpdate = instance.instructions[instructionIndex];
 
+    // Date enforcement: reject premature completions outside actionable window
+    const currentTime = Timestamp.now();
+    const dueTime = instructionToUpdate.dueTime;
+    if (dueTime) {
+      const dueTimeMs =
+        typeof dueTime === "number"
+          ? dueTime
+          : typeof (dueTime as any).toMillis === "function"
+            ? (dueTime as any).toMillis()
+            : 0;
+      if (dueTimeMs > 0) {
+        const actionableWindowHours =
+          (instructionToUpdate as any).actionableWindow || 24;
+        const windowStartMs =
+          dueTimeMs - actionableWindowHours * 60 * 60 * 1000;
+        if (currentTime.toMillis() < windowStartMs) {
+          throw new Error(
+            `Instruction ${instructionId} cannot be completed yet. ` +
+              `Actionable window starts at ${new Date(windowStartMs).toISOString()}.`
+          );
+        }
+      }
+    }
+
     // Allow completion if it's PENDING_NOTIFICATION, ACTION_DUE, or even MISSED (if policy allows late completion)
     if (
       instructionToUpdate.status !==

package/src/services/practitioner/practitioner.service.ts

@@ -19,6 +19,7 @@ import {
   FieldValue,
 } from "firebase/firestore";
 import { BaseService } from "../base.service";
+import { enforceProviderLimit } from "../tier-enforcement";
 import {
   Practitioner,
   CreatePractitionerData,
@@ -183,6 +184,19 @@ export class PractitionerService extends BaseService {
   ): Promise<Practitioner> {
     try {
       const validData = createPractitionerSchema.parse(data);
+
+      // Enforce tier limit: resolve clinicGroupId from the first assigned clinic
+      if (validData.clinics && validData.clinics.length > 0) {
+        const clinicRef = doc(this.db, CLINICS_COLLECTION, validData.clinics[0]);
+        const clinicSnap = await getDoc(clinicRef);
+        if (clinicSnap.exists()) {
+          const clinicGroupId = (clinicSnap.data() as any).clinicGroupId;
+          if (clinicGroupId) {
+            await enforceProviderLimit(this.db, clinicGroupId);
+          }
+        }
+      }
+
       const practitionerId = this.generateId();
 
       // Default review info
@@ -282,6 +296,11 @@ export class PractitionerService extends BaseService {
         throw new Error(`Clinic ${clinicId} not found`);
       }
 
+      // Enforce tier limit before creating draft practitioner
+      if (clinic.clinicGroupId) {
+        await enforceProviderLimit(this.db, clinic.clinicGroupId);
+      }
+
       // Make sure the primary clinic (clinicId) is always included
       // Merge the clinics array with the primary clinicId, avoiding duplicates
       const clinicsToAdd = new Set<string>([clinicId]);

package/src/services/procedure/procedure.service.ts

@@ -22,6 +22,7 @@ import {
   documentId,
 } from 'firebase/firestore';
 import { BaseService } from '../base.service';
+import { enforceProcedureLimit } from '../tier-enforcement';
 import {
   Procedure,
   CreateProcedureData,
@@ -362,6 +363,9 @@ export class ProcedureService extends BaseService {
     }
     const clinic = clinicSnapshot.data() as Clinic; // Assert type
 
+    // Enforce tier limit before creating procedure
+    await enforceProcedureLimit(this.db, clinic.clinicGroupId);
+
     const practitionerRef = doc(this.db, PRACTITIONERS_COLLECTION, validatedData.practitionerId);
     const practitionerSnapshot = await getDoc(practitionerRef);
     if (!practitionerSnapshot.exists()) {
@@ -881,6 +885,9 @@ export class ProcedureService extends BaseService {
     }
     const clinic = clinicSnapshot.data() as Clinic;
 
+    // Enforce tier limit before bulk creating procedures
+    await enforceProcedureLimit(this.db, clinic.clinicGroupId, practitionerIds.length);
+
     // 3. Handle media uploads once for efficiency
     let processedPhotos: string[] = [];
     if (validatedData.photos && validatedData.photos.length > 0) {

package/src/services/tier-enforcement.ts

@@ -0,0 +1,290 @@
+import {
+  Firestore,
+  collection,
+  doc,
+  getDoc,
+  getDocs,
+  query,
+  where,
+} from 'firebase/firestore';
+import {
+  CLINIC_GROUPS_COLLECTION,
+  CLINICS_COLLECTION,
+} from '../types/clinic/index';
+import { PRACTITIONERS_COLLECTION } from '../types/practitioner/index';
+import { PROCEDURES_COLLECTION } from '../types/procedure/index';
+import { TIER_CONFIG, resolveEffectiveTier } from '../config/tiers.config';
+
+export class TierLimitError extends Error {
+  public readonly code = 'TIER_LIMIT_EXCEEDED';
+  public readonly currentTier: string;
+  public readonly resource: string;
+  public readonly currentCount: number;
+  public readonly maxAllowed: number;
+
+  constructor(
+    resource: string,
+    currentTier: string,
+    currentCount: number,
+    maxAllowed: number
+  ) {
+    const tierLabel = currentTier.charAt(0).toUpperCase() + currentTier.slice(1);
+    super(
+      `Your ${tierLabel} plan allows a maximum of ${maxAllowed} ${resource}. ` +
+      `You currently have ${currentCount}. Please upgrade your plan to add more.`
+    );
+    this.name = 'TierLimitError';
+    this.currentTier = currentTier;
+    this.resource = resource;
+    this.currentCount = currentCount;
+    this.maxAllowed = maxAllowed;
+  }
+}
+
+/**
+ * Fetches the effective tier for a clinic group.
+ * Returns the resolved tier string (e.g., 'free', 'connect', 'pro').
+ */
+export async function getEffectiveTier(
+  db: Firestore,
+  clinicGroupId: string
+): Promise<string> {
+  const groupRef = doc(db, CLINIC_GROUPS_COLLECTION, clinicGroupId);
+  const groupSnap = await getDoc(groupRef);
+  if (!groupSnap.exists()) {
+    throw new Error(`Clinic group ${clinicGroupId} not found`);
+  }
+  const subscriptionModel = groupSnap.data().subscriptionModel || 'no_subscription';
+  return resolveEffectiveTier(subscriptionModel);
+}
+
+/**
+ * Counts active providers (practitioners) across all clinics in a clinic group.
+ */
+async function countProvidersInGroup(
+  db: Firestore,
+  clinicGroupId: string
+): Promise<number> {
+  const clinicsQuery = query(
+    collection(db, CLINICS_COLLECTION),
+    where('clinicGroupId', '==', clinicGroupId),
+    where('isActive', '==', true)
+  );
+  const clinicsSnap = await getDocs(clinicsQuery);
+  const clinicIds = clinicsSnap.docs.map(d => d.id);
+
+  if (clinicIds.length === 0) return 0;
+
+  const practitionersQuery = query(
+    collection(db, PRACTITIONERS_COLLECTION),
+    where('isActive', '==', true)
+  );
+  const practitionersSnap = await getDocs(practitionersQuery);
+
+  const clinicIdSet = new Set(clinicIds);
+  const uniqueProviders = practitionersSnap.docs.filter(d => {
+    const data = d.data();
+    const clinics: string[] = data.clinics || [];
+    return clinics.some(c => clinicIdSet.has(c));
+  });
+
+  return uniqueProviders.length;
+}
+
+/**
+ * Counts active procedures across all clinics in a clinic group.
+ */
+async function countProceduresInGroup(
+  db: Firestore,
+  clinicGroupId: string
+): Promise<number> {
+  const clinicsQuery = query(
+    collection(db, CLINICS_COLLECTION),
+    where('clinicGroupId', '==', clinicGroupId),
+    where('isActive', '==', true)
+  );
+  const clinicsSnap = await getDocs(clinicsQuery);
+  const clinicIds = clinicsSnap.docs.map(d => d.id);
+
+  if (clinicIds.length === 0) return 0;
+
+  let totalProcedures = 0;
+  for (let i = 0; i < clinicIds.length; i += 30) {
+    const batch = clinicIds.slice(i, i + 30);
+    const proceduresQuery = query(
+      collection(db, PROCEDURES_COLLECTION),
+      where('clinicBranchId', 'in', batch),
+      where('isActive', '==', true)
+    );
+    const proceduresSnap = await getDocs(proceduresQuery);
+    totalProcedures += proceduresSnap.size;
+  }
+
+  return totalProcedures;
+}
+
+/**
+ * Counts active clinic branches in a clinic group.
+ */
+async function countBranchesInGroup(
+  db: Firestore,
+  clinicGroupId: string
+): Promise<number> {
+  const clinicsQuery = query(
+    collection(db, CLINICS_COLLECTION),
+    where('clinicGroupId', '==', clinicGroupId),
+    where('isActive', '==', true)
+  );
+  const clinicsSnap = await getDocs(clinicsQuery);
+  return clinicsSnap.size;
+}
+
+/**
+ * Enforces tier limit before adding a provider (practitioner/doctor/nurse/etc.).
+ * Throws TierLimitError if the limit would be exceeded.
+ */
+export async function enforceProviderLimit(
+  db: Firestore,
+  clinicGroupId: string
+): Promise<void> {
+  const tier = await getEffectiveTier(db, clinicGroupId);
+  const config = TIER_CONFIG[tier];
+  if (!config) return;
+
+  const max = config.limits.maxProviders;
+  if (max === -1) return;
+
+  const currentCount = await countProvidersInGroup(db, clinicGroupId);
+  if (currentCount + 1 > max) {
+    throw new TierLimitError('providers', tier, currentCount, max);
+  }
+}
+
+/**
+ * Enforces tier limit before creating a procedure.
+ * @param count - Number of procedures being created (default 1, higher for bulk)
+ */
+export async function enforceProcedureLimit(
+  db: Firestore,
+  clinicGroupId: string,
+  count: number = 1
+): Promise<void> {
+  const tier = await getEffectiveTier(db, clinicGroupId);
+  const config = TIER_CONFIG[tier];
+  if (!config) return;
+
+  const max = config.limits.maxProcedures;
+  if (max === -1) return;
+
+  const currentCount = await countProceduresInGroup(db, clinicGroupId);
+  if (currentCount + count > max) {
+    throw new TierLimitError('procedures', tier, currentCount, max);
+  }
+}
+
+/**
+ * Enforces tier limit before creating a clinic branch.
+ */
+export async function enforceBranchLimit(
+  db: Firestore,
+  clinicGroupId: string
+): Promise<void> {
+  const tier = await getEffectiveTier(db, clinicGroupId);
+  const config = TIER_CONFIG[tier];
+  if (!config) return;
+
+  const max = config.limits.maxBranches;
+  if (max === -1) return;
+
+  const currentCount = await countBranchesInGroup(db, clinicGroupId);
+  if (currentCount + 1 > max) {
+    throw new TierLimitError('clinic branches', tier, currentCount, max);
+  }
+}
+
+/**
+ * Enforces tier limit before creating a staff member.
+ */
+export async function enforceStaffLimit(
+  db: Firestore,
+  clinicGroupId: string
+): Promise<void> {
+  const tier = await getEffectiveTier(db, clinicGroupId);
+  const config = TIER_CONFIG[tier];
+  if (!config) return;
+
+  const max = config.limits.maxStaff;
+  if (max === -1) return;
+
+  const staffQuery = query(
+    collection(db, 'clinic_staff_members'),
+    where('clinicGroupId', '==', clinicGroupId),
+    where('isActive', '==', true)
+  );
+  const staffSnap = await getDocs(staffQuery);
+  const currentCount = staffSnap.size;
+
+  if (currentCount + 1 > max) {
+    throw new TierLimitError('staff members', tier, currentCount, max);
+  }
+}
+
+/**
+ * Enforces tier limit before creating an appointment.
+ * Reads the monthly counter from clinic_groups/{id}/usage_counters/{YYYY-MM}.
+ */
+export async function enforceAppointmentLimit(
+  db: Firestore,
+  clinicGroupId: string
+): Promise<void> {
+  const tier = await getEffectiveTier(db, clinicGroupId);
+  const config = TIER_CONFIG[tier];
+  if (!config) return;
+
+  const max = config.limits.maxAppointmentsPerMonth;
+  if (max === -1) return;
+
+  const now = new Date();
+  const yearMonth = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
+
+  const counterRef = doc(
+    db,
+    `${CLINIC_GROUPS_COLLECTION}/${clinicGroupId}/usage_counters/${yearMonth}`
+  );
+  const counterSnap = await getDoc(counterRef);
+  const currentCount = counterSnap.exists() ? (counterSnap.data()?.appointmentsCreated || 0) : 0;
+
+  if (currentCount + 1 > max) {
+    throw new TierLimitError('appointments this month', tier, currentCount, max);
+  }
+}
+
+/**
+ * Enforces tier limit before sending a message.
+ * Reads the monthly counter from clinic_groups/{id}/usage_counters/{YYYY-MM}.
+ */
+export async function enforceMessageLimit(
+  db: Firestore,
+  clinicGroupId: string
+): Promise<void> {
+  const tier = await getEffectiveTier(db, clinicGroupId);
+  const config = TIER_CONFIG[tier];
+  if (!config) return;
+
+  const max = config.limits.maxMessagesPerMonth;
+  if (max === -1) return;
+
+  const now = new Date();
+  const yearMonth = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
+
+  const counterRef = doc(
+    db,
+    `${CLINIC_GROUPS_COLLECTION}/${clinicGroupId}/usage_counters/${yearMonth}`
+  );
+  const counterSnap = await getDoc(counterRef);
+  const currentCount = counterSnap.exists() ? (counterSnap.data()?.messagesCount || 0) : 0;
+
+  if (currentCount + 1 > max) {
+    throw new TierLimitError('messages this month', tier, currentCount, max);
+  }
+}