@blackcode_sa/metaestetics-api 1.15.17-staging.1 → 1.15.17-staging.2

package/package.json

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

package/src/config/index.ts

@@ -12,6 +12,9 @@ export {
   PERMISSION_KEYS,
   TIER_CONFIG,
   DEFAULT_ROLE_PERMISSIONS,
+  DEFAULT_PLAN_CONFIG,
+  PERMISSION_LABELS,
+  PERMISSION_CATEGORIES,
   resolveEffectiveTier,
 } from "./tiers.config";
 export type { PermissionKey } from "./tiers.config";

package/src/config/tiers.config.ts

@@ -1,5 +1,6 @@
 import { ClinicRole } from '../types/clinic/rbac.types';
 import type { TierConfig } from '../types/clinic/rbac.types';
+import type { PlanConfigDocument } from '../types/system/planConfig.types';
 
 /**
  * Permission keys used for role-based access control.
@@ -236,6 +237,143 @@ export const DEFAULT_ROLE_PERMISSIONS: Record<ClinicRole, Record<string, boolean
   },
 };
 
+/**
+ * Default PlanConfigDocument — used as fallback when Firestore `system/planConfig`
+ * doesn't exist or is unavailable. Also used as the seed value.
+ *
+ * Stripe price IDs reference the SKS Innovation SA sandbox account.
+ */
+export const DEFAULT_PLAN_CONFIG: PlanConfigDocument = {
+  version: 1,
+  updatedAt: null,
+  updatedBy: 'system',
+
+  tiers: {
+    free: {
+      name: 'Free',
+      limits: { maxProvidersPerBranch: 1, maxProceduresPerProvider: 3, maxBranches: 1 },
+    },
+    connect: {
+      name: 'Connect',
+      limits: { maxProvidersPerBranch: 3, maxProceduresPerProvider: 10, maxBranches: 1 },
+    },
+    pro: {
+      name: 'Pro',
+      limits: { maxProvidersPerBranch: 5, maxProceduresPerProvider: 20, maxBranches: 3 },
+    },
+  },
+
+  plans: {
+    FREE: {
+      priceId: null,
+      priceMonthly: 0,
+      currency: 'CHF',
+      description: 'Get started with basic access',
+      stripeProductId: null,
+    },
+    CONNECT: {
+      priceId: 'price_1TD0l7AaFI0fqFWNC8Lg3QJG',
+      priceMonthly: 199,
+      currency: 'CHF',
+      description: 'Consultation tools and integrated booking',
+      stripeProductId: null,
+    },
+    PRO: {
+      priceId: 'price_1TD0lEAaFI0fqFWN3tzCrfUb',
+      priceMonthly: 449,
+      currency: 'CHF',
+      description: 'Complete clinic management with CRM and analytics',
+      stripeProductId: null,
+    },
+  },
+
+  addons: {
+    seat: {
+      priceId: 'price_1TD0lKAaFI0fqFWNH9pQgTzI',
+      pricePerUnit: 39,
+      currency: 'CHF',
+      allowedTiers: ['connect', 'pro'],
+    },
+    branch: {
+      connect: { priceId: 'price_1TD0lSAaFI0fqFWNjsPvzW1T', pricePerUnit: 119, currency: 'CHF' },
+      pro: { priceId: 'price_1TD0lTAaFI0fqFWNYxUnvUxH', pricePerUnit: 279, currency: 'CHF' },
+      allowedTiers: ['connect', 'pro'],
+    },
+    procedure: {
+      priceId: 'price_1TCL3eAaFI0fqFWNJVuMYjii',
+      pricePerBlock: 19,
+      proceduresPerBlock: 5,
+      currency: 'CHF',
+      allowedTiers: ['connect', 'pro'],
+    },
+  },
+
+  priceToModel: {
+    'price_1TD0l7AaFI0fqFWNC8Lg3QJG': 'connect',
+    'price_1TD0lEAaFI0fqFWN3tzCrfUb': 'pro',
+  },
+
+  priceToType: {
+    'price_1TD0l7AaFI0fqFWNC8Lg3QJG': 'CONNECT',
+    'price_1TD0lEAaFI0fqFWN3tzCrfUb': 'PRO',
+  },
+
+  addonPriceIds: [
+    'price_1TD0lKAaFI0fqFWNH9pQgTzI',  // seat
+    'price_1TD0lSAaFI0fqFWNjsPvzW1T',  // branch connect
+    'price_1TD0lTAaFI0fqFWNYxUnvUxH',  // branch pro
+    'price_1TCL3eAaFI0fqFWNJVuMYjii',  // procedure
+  ],
+};
+
+/**
+ * Human-readable labels and grouping for permission keys.
+ * Used by the staff management UI for role/permission display.
+ */
+export const PERMISSION_LABELS: Record<
+  string,
+  { label: string; description: string; category: string }
+> = {
+  'clinic.view': { label: 'View Clinic', description: 'See clinic information and profile', category: 'Clinic' },
+  'clinic.edit': { label: 'Edit Clinic', description: 'Modify clinic settings and profile', category: 'Clinic' },
+  'reviews.view': { label: 'View Reviews', description: 'See patient reviews and ratings', category: 'Clinic' },
+  'calendar.view': { label: 'View Calendar', description: 'See the clinic calendar and schedules', category: 'Calendar' },
+  'appointments.view': { label: 'View Appointments', description: 'See appointment list and details', category: 'Appointments' },
+  'appointments.confirm': { label: 'Confirm Appointments', description: 'Confirm pending appointment requests', category: 'Appointments' },
+  'appointments.cancel': { label: 'Cancel Appointments', description: 'Cancel existing appointments', category: 'Appointments' },
+  'messaging': { label: 'Messaging', description: 'Send and receive messages with patients', category: 'Messaging' },
+  'procedures.view': { label: 'View Procedures', description: 'See the procedures catalog', category: 'Procedures' },
+  'procedures.create': { label: 'Create Procedures', description: 'Add new procedures to the catalog', category: 'Procedures' },
+  'procedures.edit': { label: 'Edit Procedures', description: 'Modify existing procedures', category: 'Procedures' },
+  'procedures.delete': { label: 'Delete Procedures', description: 'Remove procedures from the catalog', category: 'Procedures' },
+  'resources.view': { label: 'View Resources', description: 'See clinic resources and equipment', category: 'Resources' },
+  'resources.create': { label: 'Create Resources', description: 'Add new resources', category: 'Resources' },
+  'resources.edit': { label: 'Edit Resources', description: 'Modify existing resources', category: 'Resources' },
+  'resources.delete': { label: 'Delete Resources', description: 'Remove resources', category: 'Resources' },
+  'patients.view': { label: 'View Patients', description: 'See patient list and profiles', category: 'Patients' },
+  'patients.edit': { label: 'Edit Patients', description: 'Modify patient records', category: 'Patients' },
+  'providers.view': { label: 'View Providers', description: 'See the practitioners/providers list', category: 'Providers' },
+  'providers.manage': { label: 'Manage Providers', description: 'Add, edit, or remove providers', category: 'Providers' },
+  'analytics.view': { label: 'View Analytics', description: 'Access analytics dashboards and reports', category: 'Analytics' },
+  'staff.manage': { label: 'Manage Staff', description: 'Add, remove, and assign roles to staff', category: 'Administration' },
+  'settings.manage': { label: 'Manage Settings', description: 'Modify clinic group settings', category: 'Administration' },
+  'billing.manage': { label: 'Manage Billing', description: 'Access billing, subscriptions, and payments', category: 'Administration' },
+};
+
+/** All unique permission categories in display order. */
+export const PERMISSION_CATEGORIES = [
+  'Clinic',
+  'Calendar',
+  'Appointments',
+  'Messaging',
+  'Procedures',
+  'Resources',
+  'Patients',
+  'Providers',
+  'Analytics',
+  'Administration',
+] as const;
+
 /**
  * Maps subscription model strings to tier keys.
  */

package/src/services/plan-config.service.ts

@@ -0,0 +1,55 @@
+/**
+ * Plan Config Service — reads `system/planConfig` from Firestore with caching.
+ * Uses the Firebase client SDK (same as tier-enforcement.ts).
+ * Falls back to DEFAULT_PLAN_CONFIG if the document doesn't exist.
+ */
+import { Firestore, doc, getDoc } from 'firebase/firestore';
+import { DEFAULT_PLAN_CONFIG } from '../config/tiers.config';
+import type { PlanConfigDocument } from '../types/system/planConfig.types';
+import { PLAN_CONFIG_PATH } from '../types/system/planConfig.types';
+
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+class PlanConfigService {
+  private cachedConfig: PlanConfigDocument | null = null;
+  private cacheExpiry = 0;
+
+  /**
+   * Returns the current plan config, reading from Firestore if the cache
+   * has expired. Falls back to DEFAULT_PLAN_CONFIG if the doc is missing.
+   */
+  async getConfig(db: Firestore): Promise<PlanConfigDocument> {
+    const now = Date.now();
+    if (this.cachedConfig && now < this.cacheExpiry) {
+      return this.cachedConfig;
+    }
+
+    try {
+      const [collectionPath, docId] = PLAN_CONFIG_PATH.split('/');
+      const configRef = doc(db, collectionPath, docId);
+      const snap = await getDoc(configRef);
+
+      if (snap.exists()) {
+        this.cachedConfig = snap.data() as PlanConfigDocument;
+      } else {
+        this.cachedConfig = DEFAULT_PLAN_CONFIG;
+      }
+    } catch (error) {
+      console.error('PlanConfigService: Firestore read failed, using fallback config', error);
+      if (!this.cachedConfig) {
+        this.cachedConfig = DEFAULT_PLAN_CONFIG;
+      }
+    }
+
+    this.cacheExpiry = now + CACHE_TTL_MS;
+    return this.cachedConfig;
+  }
+
+  /** Clears the cache — useful for testing or after config updates. */
+  invalidateCache(): void {
+    this.cachedConfig = null;
+    this.cacheExpiry = 0;
+  }
+}
+
+export const planConfigService = new PlanConfigService();

package/src/services/tier-enforcement.ts

@@ -14,6 +14,7 @@ import {
 import { PRACTITIONERS_COLLECTION } from '../types/practitioner/index';
 import { PROCEDURES_COLLECTION } from '../types/procedure/index';
 import { TIER_CONFIG, resolveEffectiveTier } from '../config/tiers.config';
+import { planConfigService } from './plan-config.service';
 
 export class TierLimitError extends Error {
   public readonly code = 'TIER_LIMIT_EXCEEDED';
@@ -171,10 +172,11 @@ export async function enforceProviderLimit(
   branchId: string
 ): Promise<void> {
   const { tier, billing } = await getClinicGroupTierData(db, clinicGroupId);
-  const config = TIER_CONFIG[tier];
-  if (!config) return;
+  const dynamicConfig = await planConfigService.getConfig(db);
+  const tierDef = dynamicConfig.tiers[tier] ?? TIER_CONFIG[tier];
+  if (!tierDef) return;
 
-  const baseMax = config.limits.maxProvidersPerBranch;
+  const baseMax = tierDef.limits.maxProvidersPerBranch;
   if (baseMax === -1) return;
 
   const addOns = billing?.addOns || {};
@@ -199,15 +201,17 @@ export async function enforceProcedureLimit(
   count: number = 1
 ): Promise<void> {
   const { tier, billing } = await getClinicGroupTierData(db, clinicGroupId);
-  const config = TIER_CONFIG[tier];
-  if (!config) return;
+  const dynamicConfig = await planConfigService.getConfig(db);
+  const tierDef = dynamicConfig.tiers[tier] ?? TIER_CONFIG[tier];
+  if (!tierDef) return;
 
-  const baseMax = config.limits.maxProceduresPerProvider;
+  const baseMax = tierDef.limits.maxProceduresPerProvider;
   if (baseMax === -1) return;
 
   const addOns = billing?.addOns || {};
   const procedureBlocks = addOns[branchId]?.procedureBlocks || 0;
-  const effectiveMax = baseMax + (procedureBlocks * 5);
+  const proceduresPerBlock = dynamicConfig.addons?.procedure?.proceduresPerBlock ?? 5;
+  const effectiveMax = baseMax + (procedureBlocks * proceduresPerBlock);
 
   const currentCount = await countProceduresForProvider(db, branchId, providerId);
   if (currentCount + count > effectiveMax) {
@@ -224,10 +228,11 @@ export async function enforceBranchLimit(
   clinicGroupId: string
 ): Promise<void> {
   const { tier, billing } = await getClinicGroupTierData(db, clinicGroupId);
-  const config = TIER_CONFIG[tier];
-  if (!config) return;
+  const dynamicConfig = await planConfigService.getConfig(db);
+  const tierDef = dynamicConfig.tiers[tier] ?? TIER_CONFIG[tier];
+  if (!tierDef) return;
 
-  const baseMax = config.limits.maxBranches;
+  const baseMax = tierDef.limits.maxBranches;
   if (baseMax === -1) return;
 
   const branchAddonCount = billing?.branchAddonCount || 0;

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

@@ -14,6 +14,15 @@ export enum ClinicRole {
   ASSISTANT = 'assistant',
 }
 
+/**
+ * Display info denormalized onto a staff record for fast list rendering.
+ */
+export interface StaffDisplayInfo {
+  firstName: string;
+  lastName: string;
+  email: string;
+}
+
 /**
  * Represents a staff member within a clinic group
  */
@@ -25,6 +34,8 @@ export interface ClinicStaffMember {
   role: ClinicRole;
   permissions: Record<string, boolean>;
   isActive: boolean;
+  displayInfo?: StaffDisplayInfo;
+  invitedBy?: string;
   createdAt?: Timestamp;
   updatedAt?: Timestamp;
 }
@@ -38,6 +49,31 @@ export interface RolePermissionConfig {
   permissions: Record<string, boolean>;
 }
 
+/**
+ * Status of a staff invitation
+ */
+export enum StaffInviteStatus {
+  PENDING = 'pending',
+  ACCEPTED = 'accepted',
+  EXPIRED = 'expired',
+  CANCELLED = 'cancelled',
+}
+
+/**
+ * An invitation for a new staff member to join a clinic group
+ */
+export interface ClinicStaffInvite {
+  id: string;
+  email: string;
+  clinicGroupId: string;
+  role: ClinicRole;
+  token: string;
+  status: StaffInviteStatus;
+  invitedBy: string;
+  createdAt?: Timestamp;
+  expiresAt?: Timestamp;
+}
+
 /**
  * Usage limits for a given subscription tier.
  * All features are available on every tier — only usage is capped.

package/src/types/index.ts

@@ -43,6 +43,9 @@ export * from "./resource";
 // Reviews types
 export * from "./reviews";
 
+// System config types
+export * from "./system";
+
 // Analytics types
 export * from "./analytics";
 

package/src/types/system/index.ts

@@ -0,0 +1 @@
+export * from './planConfig.types';

package/src/types/system/planConfig.types.ts

@@ -0,0 +1,86 @@
+/**
+ * Dynamic Plan Configuration — stored in Firestore at `system/planConfig`.
+ * Editable from the admin dashboard. Hardcoded defaults in tiers.config.ts
+ * serve as fallback when the Firestore document doesn't exist.
+ */
+
+export interface TierDefinition {
+  name: string;
+  limits: {
+    maxProvidersPerBranch: number;
+    maxProceduresPerProvider: number;
+    maxBranches: number;
+  };
+}
+
+export interface PlanDefinition {
+  /** Stripe price ID. null for the free plan. */
+  priceId: string | null;
+  /** Monthly price in the plan currency (e.g. 199 for CHF 199). */
+  priceMonthly: number;
+  currency: string;
+  description: string;
+  /** Stripe product ID — needed when auto-creating new prices. */
+  stripeProductId?: string | null;
+}
+
+export interface SeatAddonDefinition {
+  priceId: string;
+  pricePerUnit: number;
+  currency: string;
+  allowedTiers: string[];
+}
+
+export interface BranchAddonTierPrice {
+  priceId: string;
+  pricePerUnit: number;
+  currency: string;
+}
+
+export interface BranchAddonDefinition {
+  connect: BranchAddonTierPrice;
+  pro: BranchAddonTierPrice;
+  allowedTiers: string[];
+}
+
+export interface ProcedureAddonDefinition {
+  priceId: string;
+  pricePerBlock: number;
+  proceduresPerBlock: number;
+  currency: string;
+  allowedTiers: string[];
+}
+
+export interface PlanConfigDocument {
+  version: number;
+  updatedAt: any; // Firestore Timestamp (any to avoid SDK coupling)
+  updatedBy: string;
+
+  /** Tier definitions with usage limits. Keys: 'free', 'connect', 'pro'. */
+  tiers: Record<string, TierDefinition>;
+
+  /** Plan pricing and Stripe config. Keys: 'FREE', 'CONNECT', 'PRO'. */
+  plans: Record<string, PlanDefinition>;
+
+  /** Add-on pricing and Stripe config. */
+  addons: {
+    seat: SeatAddonDefinition;
+    branch: BranchAddonDefinition;
+    procedure: ProcedureAddonDefinition;
+  };
+
+  /** Auto-computed: maps Stripe priceId → Firestore subscriptionModel ('connect'/'pro'). */
+  priceToModel: Record<string, string>;
+
+  /** Auto-computed: maps Stripe priceId → plan type label ('CONNECT'/'PRO'). */
+  priceToType: Record<string, string>;
+
+  /** Auto-computed: all add-on price IDs for webhook filtering. */
+  addonPriceIds: string[];
+}
+
+/** Firestore path for the plan config document. */
+export const PLAN_CONFIG_PATH = 'system/planConfig';
+
+/** Firestore subcollection path for version history. */
+export const PLAN_CONFIG_HISTORY_PATH = 'system/planConfig/history';