@blackcode_sa/metaestetics-api 1.15.13 → 1.15.14

package/src/config/tiers.config.ts

@@ -53,20 +53,23 @@ export type PermissionKey = keyof typeof PERMISSION_KEYS;
  * All features are available on every tier — tiers differ only in usage caps.
  * -1 means unlimited.
  *
- * Confirmed by client on 2026-03-10:
- * - Free: 1 provider, 3 procedures, 3 appts/mo, 10 msgs/mo, 1 location
- * - Connect (CHF 59/mo): unlimited providers, 15 procedures, 100 appts/mo, unlimited msgs, 1 location
- * - Pro (CHF 149/mo): unlimited everything
+ * Updated 2026-03-17 (client meeting):
+ * - Appointments and messages are NEVER limited (bad patient UX)
+ * - Providers are per branch, not per clinic group
+ * - Procedures are per provider (each provider gets this allowance)
+ * - Add-ons available on Connect/Pro: +1 branch, +1 provider, +10 procedures
+ *
+ * Free: 1 branch, 1 provider/branch, 3 procedures/provider
+ * Connect (CHF 59/mo): 1 branch, 3 providers/branch, 10 procedures/provider
+ * Pro (CHF 149/mo): 3 branches, 10 providers/branch, 20 procedures/provider
  */
 export const TIER_CONFIG: Record<string, TierConfig> = {
   free: {
     tier: 'free',
     name: 'Free',
     limits: {
-      maxProviders: 1,
-      maxProcedures: 3,
-      maxAppointmentsPerMonth: 3,
-      maxMessagesPerMonth: 10,
+      maxProvidersPerBranch: 1,
+      maxProceduresPerProvider: 3,
       maxBranches: 1,
     },
   },
@@ -74,10 +77,8 @@ export const TIER_CONFIG: Record<string, TierConfig> = {
     tier: 'connect',
     name: 'Connect',
     limits: {
-      maxProviders: -1,
-      maxProcedures: 15,
-      maxAppointmentsPerMonth: 100,
-      maxMessagesPerMonth: -1,
+      maxProvidersPerBranch: 3,
+      maxProceduresPerProvider: 10,
       maxBranches: 1,
     },
   },
@@ -85,11 +86,9 @@ export const TIER_CONFIG: Record<string, TierConfig> = {
     tier: 'pro',
     name: 'Pro',
     limits: {
-      maxProviders: -1,
-      maxProcedures: -1,
-      maxAppointmentsPerMonth: -1,
-      maxMessagesPerMonth: -1,
-      maxBranches: -1,
+      maxProvidersPerBranch: 10,
+      maxProceduresPerProvider: 20,
+      maxBranches: 3,
     },
   },
 };

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

@@ -192,7 +192,7 @@ export class PractitionerService extends BaseService {
         if (clinicSnap.exists()) {
           const clinicGroupId = (clinicSnap.data() as any).clinicGroupId;
           if (clinicGroupId) {
-            await enforceProviderLimit(this.db, clinicGroupId);
+            await enforceProviderLimit(this.db, clinicGroupId, validData.clinics[0]);
           }
         }
       }
@@ -296,9 +296,9 @@ export class PractitionerService extends BaseService {
         throw new Error(`Clinic ${clinicId} not found`);
       }
 
-      // Enforce tier limit before creating draft practitioner
+      // Enforce tier limit before creating draft practitioner (per-branch)
       if (clinic.clinicGroupId) {
-        await enforceProviderLimit(this.db, clinic.clinicGroupId);
+        await enforceProviderLimit(this.db, clinic.clinicGroupId, clinicId);
       }
 
       // Make sure the primary clinic (clinicId) is always included

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

@@ -363,8 +363,8 @@ 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);
+    // Enforce tier limit before creating procedure (per-provider, per-branch)
+    await enforceProcedureLimit(this.db, clinic.clinicGroupId, validatedData.clinicBranchId, validatedData.practitionerId);
 
     const practitionerRef = doc(this.db, PRACTITIONERS_COLLECTION, validatedData.practitionerId);
     const practitionerSnapshot = await getDoc(practitionerRef);
@@ -885,8 +885,10 @@ 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);
+    // Enforce tier limit for each practitioner (per-provider, per-branch)
+    for (const practitionerId of practitionerIds) {
+      await enforceProcedureLimit(this.db, clinic.clinicGroupId, validatedData.clinicBranchId, practitionerId);
+    }
 
     // 3. Handle media uploads once for efficiency
     let processedPhotos: string[] = [];

package/src/services/tier-enforcement.ts

@@ -29,9 +29,13 @@ export class TierLimitError extends Error {
     maxAllowed: number
   ) {
     const tierLabel = currentTier.charAt(0).toUpperCase() + currentTier.slice(1);
+    const canBuyAddons = currentTier === 'connect' || currentTier === 'pro';
+    const actionHint = canBuyAddons
+      ? 'Please upgrade your plan or purchase an add-on.'
+      : 'Please upgrade to Connect or Pro to add more.';
     super(
       `Your ${tierLabel} plan allows a maximum of ${maxAllowed} ${resource}. ` +
-      `You currently have ${currentCount}. Please upgrade your plan to add more.`
+      `You currently have ${currentCount}. ${actionHint}`
     );
     this.name = 'TierLimitError';
     this.currentTier = currentTier;
@@ -42,88 +46,82 @@ export class TierLimitError extends Error {
 }
 
 /**
- * Fetches the effective tier for a clinic group.
- * Returns the resolved tier string (e.g., 'free', 'connect', 'pro').
+ * Reads the clinic group doc and returns tier + billing data in one call.
  */
-export async function getEffectiveTier(
+async function getClinicGroupTierData(
   db: Firestore,
   clinicGroupId: string
-): Promise<string> {
+): Promise<{
+  tier: string;
+  billing: Record<string, any> | undefined;
+}> {
   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);
+  const data = groupSnap.data();
+  const subscriptionModel = data.subscriptionModel || 'no_subscription';
+  return {
+    tier: resolveEffectiveTier(subscriptionModel),
+    billing: data.billing,
+  };
 }
 
 /**
- * Counts active providers (practitioners) across all clinics in a clinic group.
+ * Fetches the effective tier for a clinic group.
  */
-async function countProvidersInGroup(
+export async function getEffectiveTier(
   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;
+): Promise<string> {
+  const { tier } = await getClinicGroupTierData(db, clinicGroupId);
+  return tier;
+}
 
+/**
+ * Counts active providers (practitioners) assigned to a specific clinic branch.
+ */
+async function countProvidersInBranch(
+  db: Firestore,
+  branchId: string
+): Promise<number> {
   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;
+  return practitionersSnap.docs.filter(d => {
+    const clinics: string[] = d.data().clinics || [];
+    return clinics.includes(branchId);
+  }).length;
 }
 
 /**
- * Counts active procedures across all clinics in a clinic group.
+ * Counts active procedures for a specific provider in a specific branch.
+ * Uses unique technologyId to avoid double-counting same procedure type.
  */
-async function countProceduresInGroup(
+async function countProceduresForProvider(
   db: Firestore,
-  clinicGroupId: string
+  branchId: string,
+  providerId: string
 ): Promise<number> {
-  const clinicsQuery = query(
-    collection(db, CLINICS_COLLECTION),
-    where('clinicGroupId', '==', clinicGroupId),
+  const proceduresQuery = query(
+    collection(db, PROCEDURES_COLLECTION),
+    where('clinicBranchId', '==', branchId),
+    where('practitionerId', '==', providerId),
     where('isActive', '==', true)
   );
-  const clinicsSnap = await getDocs(clinicsQuery);
-  const clinicIds = clinicsSnap.docs.map(d => d.id);
-
-  if (clinicIds.length === 0) return 0;
+  const proceduresSnap = await getDocs(proceduresQuery);
 
   const uniqueTechnologyIds = new Set<string>();
-  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);
-    proceduresSnap.docs.forEach(d => {
-      const technologyId = d.data().technologyId;
-      if (technologyId) {
-        uniqueTechnologyIds.add(technologyId);
-      }
-    });
-  }
+  proceduresSnap.docs.forEach(d => {
+    const technologyId = d.data().technologyId;
+    if (technologyId) {
+      uniqueTechnologyIds.add(technologyId);
+    }
+  });
 
   return uniqueTechnologyIds.size;
 }
@@ -145,124 +143,98 @@ async function countBranchesInGroup(
 }
 
 /**
- * Enforces tier limit before adding a provider (practitioner/doctor/nurse/etc.).
- * Throws TierLimitError if the limit would be exceeded.
+ * Resolves the clinicGroupId for a given branch.
  */
-export async function enforceProviderLimit(
+async function resolveClinicGroupId(
   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);
+  branchId: string
+): Promise<string> {
+  const clinicRef = doc(db, CLINICS_COLLECTION, branchId);
+  const clinicSnap = await getDoc(clinicRef);
+  if (!clinicSnap.exists()) {
+    throw new Error(`Clinic branch ${branchId} not found`);
+  }
+  const clinicGroupId = clinicSnap.data().clinicGroupId;
+  if (!clinicGroupId) {
+    throw new Error(`Clinic branch ${branchId} has no clinicGroupId`);
   }
+  return clinicGroupId;
 }
 
 /**
- * Enforces tier limit before creating a procedure.
- * @param count - Number of procedures being created (default 1, higher for bulk)
+ * Enforces tier limit before adding a provider to a specific branch.
+ * Add-on aware: effective limit = base + per-branch extraProviders.
  */
-export async function enforceProcedureLimit(
+export async function enforceProviderLimit(
   db: Firestore,
   clinicGroupId: string,
-  count: number = 1
+  branchId: string
 ): Promise<void> {
-  const tier = await getEffectiveTier(db, clinicGroupId);
+  const { tier, billing } = await getClinicGroupTierData(db, clinicGroupId);
   const config = TIER_CONFIG[tier];
   if (!config) return;
 
-  const max = config.limits.maxProcedures;
-  if (max === -1) return;
+  const baseMax = config.limits.maxProvidersPerBranch;
+  if (baseMax === -1) return;
 
-  const currentCount = await countProceduresInGroup(db, clinicGroupId);
-  if (currentCount + count > max) {
-    throw new TierLimitError('procedures', tier, currentCount, max);
-  }
-}
+  const addOns = billing?.addOns || {};
+  const extraProviders = addOns[branchId]?.extraProviders || 0;
+  const effectiveMax = baseMax + extraProviders;
 
-/**
- * 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);
+  const currentCount = await countProvidersInBranch(db, branchId);
+  if (currentCount + 1 > effectiveMax) {
+    throw new TierLimitError('providers in this branch', tier, currentCount, effectiveMax);
   }
 }
 
 /**
- * Enforces tier limit before creating an appointment.
- * Reads the monthly counter from clinic_groups/{id}/usage_counters/{YYYY-MM}.
+ * Enforces tier limit before creating a procedure for a provider in a branch.
+ * Add-on aware: effective limit = base + (procedureBlocks × 10).
  */
-export async function enforceAppointmentLimit(
+export async function enforceProcedureLimit(
   db: Firestore,
-  clinicGroupId: string
+  clinicGroupId: string,
+  branchId: string,
+  providerId: string,
+  count: number = 1
 ): Promise<void> {
-  const tier = await getEffectiveTier(db, clinicGroupId);
+  const { tier, billing } = await getClinicGroupTierData(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 baseMax = config.limits.maxProceduresPerProvider;
+  if (baseMax === -1) return;
 
-  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;
+  const addOns = billing?.addOns || {};
+  const procedureBlocks = addOns[branchId]?.procedureBlocks || 0;
+  const effectiveMax = baseMax + (procedureBlocks * 10);
 
-  if (currentCount + 1 > max) {
-    throw new TierLimitError('appointments this month', tier, currentCount, max);
+  const currentCount = await countProceduresForProvider(db, branchId, providerId);
+  if (currentCount + count > effectiveMax) {
+    throw new TierLimitError('procedures for this provider', tier, currentCount, effectiveMax);
   }
 }
 
 /**
- * Enforces tier limit before sending a message.
- * Reads the monthly counter from clinic_groups/{id}/usage_counters/{YYYY-MM}.
+ * Enforces tier limit before creating a clinic branch.
+ * Add-on aware: effective limit = base + branchAddonCount.
  */
-export async function enforceMessageLimit(
+export async function enforceBranchLimit(
   db: Firestore,
   clinicGroupId: string
 ): Promise<void> {
-  const tier = await getEffectiveTier(db, clinicGroupId);
+  const { tier, billing } = await getClinicGroupTierData(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 baseMax = config.limits.maxBranches;
+  if (baseMax === -1) return;
 
-  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;
+  const branchAddonCount = billing?.branchAddonCount || 0;
+  const effectiveMax = baseMax + branchAddonCount;
 
-  if (currentCount + 1 > max) {
-    throw new TierLimitError('messages this month', tier, currentCount, max);
+  const currentCount = await countBranchesInGroup(db, clinicGroupId);
+  if (currentCount + 1 > effectiveMax) {
+    throw new TierLimitError('clinic branches', tier, currentCount, effectiveMax);
   }
 }

package/src/types/clinic/index.ts

@@ -210,6 +210,19 @@ export interface BillingInfo {
   updatedAt: Timestamp;
   seatCount?: number;
   seatPriceId?: string;
+  /** Number of extra branches purchased (group-level add-on) */
+  branchAddonCount?: number;
+  branchAddonPriceId?: string;
+  /** Total procedure blocks across all branches (for Stripe sync) */
+  procedureAddonTotalBlocks?: number;
+  procedureAddonPriceId?: string;
+  /** Per-branch add-on tracking */
+  addOns?: {
+    [branchId: string]: {
+      extraProviders?: number;
+      procedureBlocks?: number;
+    };
+  };
 }
 
 /**

package/src/types/clinic/rbac.types.ts

@@ -41,12 +41,14 @@ export interface RolePermissionConfig {
  * Usage limits for a given subscription tier.
  * All features are available on every tier — only usage is capped.
  * -1 means unlimited.
+ *
+ * Providers and procedures are scoped per branch, not per clinic group.
+ * Procedures are per provider (each provider in a branch gets this allowance).
+ * Appointments and messages are never limited.
  */
 export interface TierLimits {
-  maxProviders: number;
-  maxProcedures: number;
-  maxAppointmentsPerMonth: number;
-  maxMessagesPerMonth: number;
+  maxProvidersPerBranch: number;
+  maxProceduresPerProvider: number;
   maxBranches: number;
 }