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/Http/Controllers/Frontdesk/BranchController.php

@@ -38,6 +38,14 @@ class BranchController extends Controller
         $this->authorizeAbility($request, 'admin.branches.manage');
         $organization = $this->organization($request);
 
+        $currentCount = Branch::owned($this->ownerRef($request))
+            ->where('organization_id', $organization->id)
+            ->count();
+
+        if (! app(\App\Services\Frontdesk\PlanService::class)->canAddBranch($organization, $currentCount)) {
+            return back()->withInput()->with('error', 'Your plan allows one branch. Upgrade to Frontdesk Pro for unlimited branches.');
+        }
+
         $validated = $request->validate([
             'name' => ['required', 'string', 'max:255'],
             'code' => ['nullable', 'string', 'max:50'],

app/Http/Controllers/Frontdesk/DeviceController.php

@@ -61,6 +61,10 @@ class DeviceController extends Controller
             'reception_desk_id' => ['nullable', 'integer'],
         ]);
 
+        if ($validated['type'] === 'kiosk' && ! app(\App\Services\Frontdesk\PlanService::class)->canAddKiosk($organization)) {
+            return back()->withInput()->with('error', 'Your plan allows one kiosk device. Upgrade to Frontdesk Pro for unlimited kiosks.');
+        }
+
         $token = in_array($validated['type'], config('frontdesk.device_token_types', []), true)
             ? $devices->generateToken()
             : null;

app/Http/Controllers/Frontdesk/IntegrationController.php

@@ -17,6 +17,15 @@ class IntegrationController extends Controller
     {
         $this->authorizeAbility($request, 'settings.view');
         $organization = $this->organization($request);
+        $plans = app(\App\Services\Frontdesk\PlanService::class);
+
+        if (! $plans->hasFeature($organization, 'integrations')) {
+            return view('frontdesk.integrations.upgrade', [
+                'organization' => $organization,
+                'proPriceMinor' => $plans->proPriceMinor(),
+            ]);
+        }
+
         $canManage = app(\App\Services\Frontdesk\FrontdeskPermissions::class)
             ->isAdmin($this->member($request));
 
@@ -39,6 +48,10 @@ class IntegrationController extends Controller
         $this->authorizeAbility($request, 'settings.manage');
         $organization = $this->organization($request);
 
+        if (! app(\App\Services\Frontdesk\PlanService::class)->hasFeature($organization, 'integrations')) {
+            return back()->with('error', 'Webhooks and calendar feeds require Frontdesk Pro.');
+        }
+
         $validated = $request->validate([
             'webhook_url' => ['nullable', 'url', 'max:500'],
             'webhook_secret' => ['nullable', 'string', 'max:128'],

app/Http/Controllers/Frontdesk/KioskController.php

@@ -77,6 +77,7 @@ class KioskController extends Controller
                 'awaiting_approval' => $visit->awaitingApproval(),
                 'checked_in_at' => $visit->checked_in_at?->toIso8601String(),
                 'badge_url' => $visit->isInside() ? route('frontdesk.visits.badge', $visit) : null,
+                'host_notified' => (bool) ($visit->host_notified ?? false),
             ],
         ]);
     }

app/Http/Controllers/Frontdesk/KioskDeviceController.php

@@ -84,6 +84,7 @@ class KioskDeviceController extends Controller
                 'awaiting_approval' => $visit->awaitingApproval(),
                 'checked_in_at' => $visit->checked_in_at?->toIso8601String(),
                 'badge_url' => $visit->isInside() ? route('frontdesk.visits.badge', $visit) : null,
+                'host_notified' => (bool) ($visit->host_notified ?? false),
             ],
         ]);
     }

app/Http/Controllers/Frontdesk/SettingsController.php

@@ -6,6 +6,9 @@ use App\Http\Controllers\Controller;
 use App\Http\Controllers\Frontdesk\Concerns\ScopesToAccount;
 use App\Models\Branch;
 use App\Services\Frontdesk\FrontdeskPermissions;
+use App\Services\Frontdesk\NotificationPricingService;
+use App\Services\Frontdesk\NotificationUsageService;
+use App\Services\Frontdesk\PlanService;
 use App\Support\OrganizationBranding;
 use Illuminate\Http\RedirectResponse;
 use Illuminate\Http\Request;
@@ -15,7 +18,7 @@ class SettingsController extends Controller
 {
     use ScopesToAccount;
 
-    public function edit(Request $request): View
+    public function edit(Request $request, PlanService $plans, NotificationUsageService $usage, NotificationPricingService $pricing): View
     {
         $this->authorizeAbility($request, 'settings.view');
         $organization = $this->organization($request);
@@ -25,6 +28,10 @@ class SettingsController extends Controller
             ->where('organization_id', $organization->id)
             ->count();
 
+        $monthlyUsage = $usage->forOrganization($organization);
+        $plan = $plans->plan($organization);
+        $freeEmailAllowance = $plans->freeEmailsPerMonth($organization);
+
         return view('frontdesk.settings.edit', [
             'organization' => $organization,
             'canManage' => $canManage,
@@ -33,6 +40,15 @@ class SettingsController extends Controller
             'deviceTypes' => config('frontdesk.device_types'),
             'notificationChannels' => config('frontdesk.notification_channels'),
             'notificationEvents' => config('frontdesk.notification_events'),
+            'plan' => $plan,
+            'isPro' => $plans->isPro($organization),
+            'proPriceMinor' => $plans->proPriceMinor(),
+            'monthlyUsage' => $monthlyUsage,
+            'freeEmailAllowance' => $freeEmailAllowance,
+            'emailCostFormatted' => $pricing->formatMinor($pricing->emailCostMinor()),
+            'smsCostFormatted' => $pricing->formatMinor(
+                $pricing->smsCostMinor('Sample SMS message for pricing display.'),
+            ),
         ]);
     }
 

app/Http/Controllers/Frontdesk/WalletController.php

@@ -0,0 +1,82 @@
+<?php
+
+namespace App\Http\Controllers\Frontdesk;
+
+use App\Http\Controllers\Controller;
+use App\Http\Controllers\Frontdesk\Concerns\ScopesToAccount;
+use App\Services\Billing\BillingClient;
+use App\Services\Frontdesk\PlanService;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Cache;
+
+class WalletController extends Controller
+{
+    use ScopesToAccount;
+
+    public function balance(Request $request, BillingClient $billing): JsonResponse
+    {
+        $publicId = (string) $request->user()->public_id;
+
+        $minor = Cache::remember("frontdesk_wallet_balance:{$publicId}", now()->addSeconds(30), function () use ($billing, $publicId) {
+            try {
+                return $billing->balanceMinor($publicId);
+            } catch (\Throwable) {
+                return null;
+            }
+        });
+
+        if ($minor === null) {
+            return response()->json(['available' => false]);
+        }
+
+        $currency = (string) config('billing.currency', 'GHS');
+
+        return response()->json([
+            'available' => true,
+            'balance_minor' => $minor,
+            'currency' => $currency,
+            'formatted' => $currency.' '.number_format($minor / 100, 2),
+        ]);
+    }
+
+    public function upgrade(Request $request, PlanService $plans, BillingClient $billing): RedirectResponse
+    {
+        $this->authorizeAbility($request, 'settings.manage');
+        $organization = $this->organization($request);
+
+        if ($plans->isPro($organization)) {
+            return back()->with('success', 'Your organization is already on Frontdesk Pro.');
+        }
+
+        $priceMinor = $plans->proPriceMinor();
+        $ownerRef = $organization->owner_ref;
+
+        try {
+            if (! $billing->canAfford($ownerRef, $priceMinor)) {
+                return back()->with('error', 'Insufficient wallet balance. Top up your Ladill wallet to upgrade to Pro.');
+            }
+
+            $charged = $billing->debit(
+                $ownerRef,
+                $priceMinor,
+                'frontdesk_pro',
+                'frontdesk-pro-'.$organization->id.'-'.now()->format('Y-m'),
+                'Ladill Frontdesk Pro — monthly subscription',
+            );
+        } catch (\Throwable) {
+            return back()->with('error', 'Could not process upgrade. Please try again.');
+        }
+
+        if (! $charged) {
+            return back()->with('error', 'Insufficient wallet balance. Top up your Ladill wallet to upgrade to Pro.');
+        }
+
+        $settings = $organization->settings ?? [];
+        $settings['plan'] = 'pro';
+        $settings['plan_expires_at'] = now()->addMonth()->toIso8601String();
+        $organization->update(['settings' => $settings]);
+
+        return back()->with('success', 'Upgraded to Frontdesk Pro for one month.');
+    }
+}

app/Models/NotificationUsage.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class NotificationUsage extends Model
+{
+    protected $table = 'frontdesk_notification_usage';
+
+    protected $fillable = [
+        'organization_id', 'period', 'email_count', 'sms_count',
+        'email_charged_minor', 'sms_charged_minor',
+    ];
+
+    public function organization(): BelongsTo
+    {
+        return $this->belongsTo(Organization::class, 'organization_id');
+    }
+}

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);
     }