Add freemium plans, wallet-billed host notifications, and Pro upgrades.

Host alerts use email/phone on the host record without requiring a Ladill
account link; SMS and over-quota emails debit the org wallet at platform rates.

Co-authored-by: Cursor <cursoragent@cursor.com>

app/Services/Frontdesk/NotificationBillingService.php

@@ -0,0 +1,110 @@
+<?php
+
+namespace App\Services\Frontdesk;
+
+use App\Models\Organization;
+use App\Services\Billing\BillingClient;
+use Illuminate\Support\Str;
+
+class NotificationBillingService
+{
+    public function __construct(
+        protected BillingClient $billing,
+        protected NotificationPricingService $pricing,
+        protected NotificationUsageService $usage,
+        protected PlanService $plans,
+    ) {}
+
+    public function emailCostMinor(Organization $organization): int
+    {
+        $allowance = $this->plans->freeEmailsPerMonth($organization);
+        if ($allowance === null || $this->usage->emailCountThisMonth($organization) < $allowance) {
+            return 0;
+        }
+
+        return $this->pricing->emailCostMinor();
+    }
+
+    public function canAffordEmail(Organization $organization): bool
+    {
+        $cost = $this->emailCostMinor($organization);
+        if ($cost <= 0) {
+            return true;
+        }
+
+        return $this->canAfford($organization->owner_ref, $cost);
+    }
+
+    public function canAffordSms(Organization $organization, string $message): bool
+    {
+        $cost = $this->pricing->smsCostMinor($message);
+        if ($cost <= 0) {
+            return true;
+        }
+
+        return $this->canAfford($organization->owner_ref, $cost);
+    }
+
+    /**
+     * Debit after a successful send. Returns false if the wallet could not be charged.
+     */
+    public function chargeEmail(Organization $organization, string $reference, string $description): bool
+    {
+        $cost = $this->emailCostMinor($organization);
+        if ($cost <= 0) {
+            $this->usage->recordEmail($organization, 0);
+
+            return true;
+        }
+
+        if (! $this->debit($organization->owner_ref, $cost, 'email', $reference, $description)) {
+            return false;
+        }
+
+        $this->usage->recordEmail($organization, $cost);
+
+        return true;
+    }
+
+    public function chargeSms(Organization $organization, string $message, string $reference, string $description): bool
+    {
+        $cost = $this->pricing->smsCostMinor($message);
+        if ($cost <= 0) {
+            $this->usage->recordSms($organization, 0);
+
+            return true;
+        }
+
+        if (! $this->debit($organization->owner_ref, $cost, 'sms', $reference, $description)) {
+            return false;
+        }
+
+        $this->usage->recordSms($organization, $cost);
+
+        return true;
+    }
+
+    private function canAfford(string $ownerRef, int $costMinor): bool
+    {
+        try {
+            return $this->billing->canAfford($ownerRef, $costMinor);
+        } catch (\Throwable) {
+            return true;
+        }
+    }
+
+    private function debit(string $ownerRef, int $costMinor, string $channel, string $reference, string $description): bool
+    {
+        try {
+            return $this->billing->debit(
+                $ownerRef,
+                $costMinor,
+                'notification_'.$channel,
+                'frontdesk-notify-'.$reference.'-'.Str::uuid(),
+                $description,
+            );
+        } catch (\Throwable) {
+            return false;
+        }
+    }
+}

app/Services/Frontdesk/NotificationDispatcher.php

@@ -19,11 +19,12 @@ class NotificationDispatcher
         protected EmailService $email,
         protected SmsService $sms,
         protected NotificationPreferenceService $preferences,
+        protected NotificationBillingService $billing,
     ) {}
 
-    public function visitorArrived(Visit $visit): void
+    public function visitorArrived(Visit $visit): bool
     {
-        $this->dispatchVisitEvent(
+        return $this->dispatchVisitEvent(
             $visit,
             'visitor_arrived',
             'Visitor has arrived',
@@ -149,15 +150,15 @@ class NotificationDispatcher
         string $title,
         string $message,
         array $meta = [],
-    ): void {
+    ): bool {
         $visit->load(['visitor', 'host', 'organization']);
         $channels = $this->preferences->channelsForEvent($visit->organization, $event);
 
         if ($channels === [] || ! $visit->host) {
-            return;
+            return false;
         }
 
-        $this->notifyHost($visit->host, $visit->organization, $channels, $title, $message, $visit, $event, $meta);
+        return $this->notifyHost($visit->host, $visit->organization, $channels, $title, $message, $visit, $event, $meta);
     }
 
     /** @param  list<string>  $channels */
@@ -170,17 +171,45 @@ class NotificationDispatcher
         ?Visit $visit = null,
         ?string $event = null,
         array $meta = [],
-    ): void {
+    ): bool {
+        $notified = false;
+        $reference = $visit ? 'visit-'.$visit->id.'-'.($event ?? 'alert') : 'host-'.$host->id;
+
         if (in_array('email', $channels, true) && $host->email) {
-            try {
-                $this->email->send($host->email, $title, $message);
-            } catch (\Throwable $e) {
-                Log::warning('Frontdesk host email failed', ['host_id' => $host->id, 'error' => $e->getMessage()]);
+            if (! $this->billing->canAffordEmail($organization)) {
+                Log::info('Frontdesk host email skipped — insufficient wallet balance', [
+                    'host_id' => $host->id,
+                    'organization_id' => $organization->id,
+                ]);
+            } else {
+                try {
+                    $this->email->send($host->email, $title, $message);
+                    if ($this->billing->chargeEmail($organization, $reference, "Host alert: {$title}")) {
+                        $notified = true;
+                    }
+                } catch (\Throwable $e) {
+                    Log::warning('Frontdesk host email failed', ['host_id' => $host->id, 'error' => $e->getMessage()]);
+                }
             }
         }
 
         if (in_array('sms', $channels, true) && $host->phone) {
-            $this->sms->send($host->phone, "{$title}: {$message}");
+            $smsBody = "{$title}: {$message}";
+            if (! $this->billing->canAffordSms($organization, $smsBody)) {
+                Log::info('Frontdesk host SMS skipped — insufficient wallet balance', [
+                    'host_id' => $host->id,
+                    'organization_id' => $organization->id,
+                ]);
+            } else {
+                try {
+                    $this->sms->send($host->phone, $smsBody);
+                    if ($this->billing->chargeSms($organization, $smsBody, $reference, "Host SMS: {$title}")) {
+                        $notified = true;
+                    }
+                } catch (\Throwable $e) {
+                    Log::warning('Frontdesk host SMS failed', ['host_id' => $host->id, 'error' => $e->getMessage()]);
+                }
+            }
         }
 
         if ($host->user_ref) {
@@ -193,6 +222,8 @@ class NotificationDispatcher
                 ])));
             }
         }
+
+        return $notified;
     }
 
     protected function notifyStaffUsers(

app/Services/Frontdesk/NotificationPricingService.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Services\Frontdesk;
+
+class NotificationPricingService
+{
+    public function emailCostMinor(): int
+    {
+        return (int) round((float) config('frontdesk.billing.email_cost_ghs', 0.0135) * 100);
+    }
+
+    public function smsCostMinor(string $message): int
+    {
+        $segmentLength = max(1, (int) config('frontdesk.billing.sms_segment_length', 160));
+        $segments = max(1, (int) ceil(mb_strlen($message) / $segmentLength));
+
+        return (int) round($segments * (float) config('frontdesk.billing.sms_cost_per_segment_ghs', 0.05) * 100);
+    }
+
+    public function formatMinor(int $minor): string
+    {
+        $currency = (string) config('billing.currency', 'GHS');
+
+        return $currency.' '.number_format($minor / 100, 2);
+    }
+}

app/Services/Frontdesk/NotificationUsageService.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace App\Services\Frontdesk;
+
+use App\Models\NotificationUsage;
+use App\Models\Organization;
+
+class NotificationUsageService
+{
+    public function currentPeriod(): string
+    {
+        return now()->format('Y-m');
+    }
+
+    public function forOrganization(Organization $organization, ?string $period = null): NotificationUsage
+    {
+        $period ??= $this->currentPeriod();
+
+        return NotificationUsage::firstOrCreate(
+            ['organization_id' => $organization->id, 'period' => $period],
+            ['email_count' => 0, 'sms_count' => 0, 'email_charged_minor' => 0, 'sms_charged_minor' => 0],
+        );
+    }
+
+    public function emailCountThisMonth(Organization $organization): int
+    {
+        return (int) $this->forOrganization($organization)->email_count;
+    }
+
+    public function recordEmail(Organization $organization, int $chargedMinor = 0): void
+    {
+        $usage = $this->forOrganization($organization);
+        $usage->increment('email_count');
+        if ($chargedMinor > 0) {
+            $usage->increment('email_charged_minor', $chargedMinor);
+        }
+    }
+
+    public function recordSms(Organization $organization, int $chargedMinor): void
+    {
+        $usage = $this->forOrganization($organization);
+        $usage->increment('sms_count');
+        if ($chargedMinor > 0) {
+            $usage->increment('sms_charged_minor', $chargedMinor);
+        }
+    }
+}

app/Services/Frontdesk/PlanService.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace App\Services\Frontdesk;
+
+use App\Models\Device;
+use App\Models\Organization;
+use Carbon\Carbon;
+
+class PlanService
+{
+    public function planKey(Organization $organization): string
+    {
+        $settings = $organization->settings ?? [];
+        $plan = (string) ($settings['plan'] ?? 'free');
+
+        if ($plan === 'pro' && ! empty($settings['plan_expires_at'])) {
+            $expires = Carbon::parse($settings['plan_expires_at']);
+            if ($expires->isPast()) {
+                return 'free';
+            }
+        }
+
+        return array_key_exists($plan, config('frontdesk.plans', [])) ? $plan : 'free';
+    }
+
+    public function isPro(Organization $organization): bool
+    {
+        return $this->planKey($organization) === 'pro';
+    }
+
+    /** @return array<string, mixed> */
+    public function plan(Organization $organization): array
+    {
+        $key = $this->planKey($organization);
+
+        return [
+            'key' => $key,
+            ...(array) config('frontdesk.plans.'.$key, []),
+        ];
+    }
+
+    /** Null means unlimited included host emails (Pro). */
+    public function freeEmailsPerMonth(Organization $organization): ?int
+    {
+        $value = config('frontdesk.plans.'.$this->planKey($organization).'.free_emails_per_month', 100);
+
+        return $value === null ? null : (int) $value;
+    }
+
+    public function canAddBranch(Organization $organization, int $currentCount): bool
+    {
+        $limit = config('frontdesk.plans.'.$this->planKey($organization).'.max_branches');
+
+        return $limit === null || $currentCount < (int) $limit;
+    }
+
+    public function canAddKiosk(Organization $organization): bool
+    {
+        $limit = config('frontdesk.plans.'.$this->planKey($organization).'.max_kiosk_devices');
+        if ($limit === null) {
+            return true;
+        }
+
+        $count = Device::query()
+            ->where('organization_id', $organization->id)
+            ->where('type', 'kiosk')
+            ->count();
+
+        return $count < (int) $limit;
+    }
+
+    public function hasFeature(Organization $organization, string $feature): bool
+    {
+        $features = config('frontdesk.plans.'.$this->planKey($organization).'.features', []);
+
+        return in_array($feature, $features, true);
+    }
+
+    public function proPriceMinor(): int
+    {
+        return (int) config('frontdesk.plans.pro.price_minor', 9900);
+    }
+}

app/Services/Frontdesk/VisitCheckInService.php

@@ -144,7 +144,7 @@ class VisitCheckInService
             ['visitor' => $visitor->full_name, 'badge_code' => $visit->badge_code],
         );
 
-        $this->notifications->visitorArrived($visit);
+        $visit->host_notified = $this->notifications->visitorArrived($visit);
         $this->webhooks->dispatch('visit.checked_in', $visit);
     }