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

config/frontdesk.php

@@ -106,11 +106,49 @@ return [
     ],
 
     'notification_channels' => [
-        'email' => 'Email',
+        'email' => 'Email (platform SMTP)',
         'sms' => 'SMS',
-        'push' => 'Push Notification',
-        'teams' => 'Microsoft Teams',
-        'slack' => 'Slack',
+    ],
+
+    'billing' => [
+        'email_cost_ghs' => (float) env('FRONTDESK_EMAIL_COST_GHS', 0.0135),
+        'sms_cost_per_segment_ghs' => (float) env('FRONTDESK_SMS_COST_PER_SEGMENT_GHS', 0.05),
+        'sms_segment_length' => (int) env('FRONTDESK_SMS_SEGMENT_LENGTH', 160),
+    ],
+
+    'plans' => [
+        'free' => [
+            'label' => 'Free',
+            'price_minor' => 0,
+            'max_branches' => 1,
+            'max_kiosk_devices' => 1,
+            'free_emails_per_month' => (int) env('FRONTDESK_FREE_EMAILS_PER_MONTH', 100),
+            'features' => [
+                'check_in',
+                'hosts',
+                'badges',
+                'watchlist',
+            ],
+        ],
+        'pro' => [
+            'label' => 'Pro',
+            'price_minor' => (int) env('FRONTDESK_PRO_PRICE_MINOR', 9900),
+            'max_branches' => null,
+            'max_kiosk_devices' => null,
+            'free_emails_per_month' => env('FRONTDESK_PRO_FREE_EMAILS_PER_MONTH') !== null
+                ? (int) env('FRONTDESK_PRO_FREE_EMAILS_PER_MONTH')
+                : null,
+            'features' => [
+                'check_in',
+                'hosts',
+                'badges',
+                'watchlist',
+                'integrations',
+                'webhooks',
+                'scheduled_reports',
+                'custom_badge_templates',
+            ],
+        ],
     ],
 
     'notification_events' => [

database/migrations/2026_06_28_020000_create_frontdesk_notification_usage_table.php

@@ -0,0 +1,29 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('frontdesk_notification_usage', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('organization_id')->constrained('frontdesk_organizations')->cascadeOnDelete();
+            $table->string('period', 7);
+            $table->unsignedInteger('email_count')->default(0);
+            $table->unsignedInteger('sms_count')->default(0);
+            $table->unsignedInteger('email_charged_minor')->default(0);
+            $table->unsignedInteger('sms_charged_minor')->default(0);
+            $table->timestamps();
+
+            $table->unique(['organization_id', 'period']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('frontdesk_notification_usage');
+    }
+};

resources/views/frontdesk/hosts/create.blade.php

@@ -21,10 +21,12 @@
                 <div>
                     <label class="block text-sm font-medium text-slate-700">Email</label>
                     <input type="email" name="email" class="mt-1 w-full rounded-lg border-slate-300 text-sm">
+                    <p class="mt-1 text-xs text-slate-500">Used for arrival alerts when email notifications are enabled.</p>
                 </div>
                 <div>
                     <label class="block text-sm font-medium text-slate-700">Phone</label>
                     <input type="tel" name="phone" class="mt-1 w-full rounded-lg border-slate-300 text-sm">
+                    <p class="mt-1 text-xs text-slate-500">Used for SMS alerts when SMS is enabled in settings.</p>
                 </div>
             </div>
             <div>

resources/views/frontdesk/hosts/edit.blade.php

@@ -24,7 +24,8 @@
             <label class="flex items-center gap-2 text-sm"><input type="checkbox" name="is_available" value="1" @checked(old('is_available', $host->is_available))> Available for visits</label>
             <div>
                 <label class="block text-sm font-medium">Linked user (platform ID)</label>
-                <input type="text" name="user_ref" value="{{ old('user_ref', $host->user_ref) }}" placeholder="User public_id for host portal access" class="mt-1 w-full rounded-lg border-slate-300 text-sm">
+                <input type="text" name="user_ref" value="{{ old('user_ref', $host->user_ref) }}" placeholder="User public_id (optional)" class="mt-1 w-full rounded-lg border-slate-300 text-sm">
+                <p class="mt-1 text-xs text-slate-500">Optional — enables the host portal and in-app bell. Email and phone above are used for alerts.</p>
                 <p class="mt-1 text-xs text-slate-500">When set, this user can access the host self-service portal.</p>
             </div>
             <button type="submit" class="btn-primary w-full">Save changes</button>

resources/views/frontdesk/integrations/upgrade.blade.php

@@ -0,0 +1,22 @@
+<x-app-layout title="Integrations">
+    <div class="mx-auto max-w-lg">
+        <h1 class="text-xl font-semibold text-slate-900">Integrations</h1>
+        <p class="mt-2 text-sm text-slate-600">Webhooks, calendar feeds, and third-party connectors are included with Frontdesk Pro.</p>
+
+        <div class="mt-6 rounded-2xl border border-indigo-200 bg-indigo-50 p-6">
+            <h2 class="font-semibold text-indigo-900">Upgrade to Pro</h2>
+            <p class="mt-2 text-sm text-indigo-800">
+                GHS {{ number_format($proPriceMinor / 100, 2) }} / month from your Ladill wallet — unlimited branches and kiosks, integrations, scheduled reports, and more.
+            </p>
+            <form method="POST" action="{{ route('frontdesk.settings.upgrade') }}" class="mt-4">
+                @csrf
+                <button type="submit" class="btn-primary">Upgrade from wallet</button>
+            </form>
+            <p class="mt-3 text-xs text-indigo-700">
+                <a href="{{ route('frontdesk.wallet') }}" class="underline">Top up your wallet</a> if you need more balance.
+            </p>
+        </div>
+
+        <a href="{{ route('frontdesk.settings') }}" class="mt-6 inline-block text-sm text-slate-600 hover:text-slate-900">&larr; Back to settings</a>
+    </div>
+</x-app-layout>

resources/views/frontdesk/kiosk/index.blade.php

@@ -243,7 +243,8 @@
                     <template x-if="!result?.awaiting_approval">
                         <p class="mt-1 text-sm text-slate-500">Badge code: <span class="font-mono font-bold" x-text="result?.badge_code"></span></p>
                     </template>
-                    <p class="mt-4 text-sm text-slate-500" x-text="result?.awaiting_approval ? 'Please wait at reception.' : 'Your host has been notified.'"></p>
+                    <p class="mt-4 text-sm text-slate-500"
+                       x-text="result?.awaiting_approval ? 'Please wait at reception.' : (result?.host_notified ? 'Your host has been notified.' : (result?.host_name ? 'Check in complete.' : 'Thank you for checking in.'))"></p>
                     <button type="button" @click="reset()" class="btn-primary btn-primary-lg mt-8 w-full">Done</button>
                 </div>
             </div>

resources/views/frontdesk/settings/edit.blade.php

@@ -6,6 +6,50 @@
     <h1 class="text-xl font-semibold text-slate-900">Settings</h1>
     <p class="text-sm text-slate-500">{{ $organization->name }}</p>
 
+    @if ($canManage)
+        <section class="mt-6 max-w-2xl rounded-2xl border border-slate-200 bg-white p-5">
+            <div class="flex flex-wrap items-start justify-between gap-4">
+                <div>
+                    <h2 class="text-sm font-semibold text-slate-900">Plan</h2>
+                    <p class="mt-1 text-sm text-slate-600">
+                        @if ($isPro)
+                            <span class="font-medium text-indigo-700">{{ $plan['label'] ?? 'Pro' }}</span> — unlimited branches &amp; kiosks, integrations, and unlimited host emails (SMS still billed per segment).
+                        @else
+                            <span class="font-medium">Free</span> — 1 branch, 1 kiosk, core check-in &amp; badges. Host alerts billed after {{ number_format($freeEmailAllowance) }} free emails/month.
+                        @endif
+                    </p>
+                </div>
+                @if (! $isPro)
+                    <form method="POST" action="{{ route('frontdesk.settings.upgrade') }}">
+                        @csrf
+                        <button type="submit" class="btn-primary text-sm">Upgrade to Pro (GHS {{ number_format($proPriceMinor / 100, 2) }}/mo)</button>
+                    </form>
+                @endif
+            </div>
+            <dl class="mt-4 grid gap-3 text-sm sm:grid-cols-2">
+                <div>
+                    <dt class="text-slate-500">Host emails this month</dt>
+                    <dd class="font-medium">
+                        @if ($freeEmailAllowance === null)
+                            {{ number_format($monthlyUsage->email_count) }} sent (unlimited on Pro)
+                        @else
+                            {{ number_format($monthlyUsage->email_count) }} / {{ number_format($freeEmailAllowance) }} free
+                        @endif
+                    </dd>
+                </div>
+                <div>
+                    <dt class="text-slate-500">Host SMS this month</dt>
+                    <dd class="font-medium">{{ number_format($monthlyUsage->sms_count) }} sent</dd>
+                </div>
+            </dl>
+            <p class="mt-3 text-xs text-slate-500">
+                Email {{ $emailCostFormatted }} each after free allowance · SMS from {{ $smsCostFormatted }} per segment — charged to your
+                <a href="{{ route('frontdesk.wallet') }}" class="text-indigo-600 underline">Ladill wallet</a>.
+                Hosts are notified via email or phone on their profile; linking a Ladill account is optional (in-app bell only).
+            </p>
+        </section>
+    @endif
+
     <form method="POST" action="{{ route('frontdesk.settings.update') }}" enctype="multipart/form-data" class="mt-6 max-w-2xl space-y-6">
         @csrf @method('PUT')
 
@@ -70,6 +114,7 @@
                 </div>
                 <div>
                     <p class="text-sm font-medium text-slate-700">Notification channels</p>
+                    <p class="mt-1 text-xs text-slate-500">Alerts go to each host's email and/or phone — no Ladill account required.</p>
                     <div class="mt-2 flex flex-wrap gap-3">
                         @foreach ($notificationChannels as $key => $label)
                             <label class="flex items-center gap-2 text-sm">

routes/web.php

@@ -23,7 +23,7 @@ use App\Http\Controllers\Frontdesk\SecurityController;
 use App\Http\Controllers\Frontdesk\SettingsController;
 use App\Http\Controllers\Frontdesk\VisitController;
 use App\Http\Controllers\Frontdesk\VisitorController;
-use App\Http\Controllers\Frontdesk\WatchlistController;
+use App\Http\Controllers\Frontdesk\WalletController;
 use App\Http\Controllers\IcalFeedController;
 use App\Http\Controllers\NotificationController;
 use Illuminate\Support\Facades\Route;
@@ -145,6 +145,7 @@ Route::middleware(['auth', 'platform.session'])->group(function () {
 
         Route::get('/settings', [SettingsController::class, 'edit'])->name('frontdesk.settings');
         Route::put('/settings', [SettingsController::class, 'update'])->name('frontdesk.settings.update');
+        Route::post('/settings/upgrade', [WalletController::class, 'upgrade'])->name('frontdesk.settings.upgrade');
 
         Route::get('/branches', [BranchController::class, 'index'])->name('frontdesk.branches.index');
         Route::get('/branches/create', [BranchController::class, 'create'])->name('frontdesk.branches.create');
@@ -166,6 +167,7 @@ Route::middleware(['auth', 'platform.session'])->group(function () {
         Route::delete('/members/{member}', [MemberController::class, 'destroy'])->name('frontdesk.members.destroy');
 
         Route::get('/wallet', fn () => redirect()->away(ladill_account_url('/wallet')))->name('frontdesk.wallet');
+        Route::get('/wallet/balance', [WalletController::class, 'balance'])->name('frontdesk.wallet.balance');
         Route::get('/team', fn () => redirect()->away(ladill_account_url('/account/team')))->name('frontdesk.team');
     });
 });

tests/Feature/FrontdeskNotificationBillingTest.php

@@ -0,0 +1,309 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Http\Middleware\EnsurePlatformSession;
+use App\Models\Branch;
+use App\Models\Host;
+use App\Models\Member;
+use App\Models\NotificationUsage;
+use App\Models\Organization;
+use App\Models\User;
+use App\Models\Visit;
+use App\Notifications\FrontdeskAlertNotification;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Mail;
+use Illuminate\Support\Facades\Notification;
+use Tests\TestCase;
+
+class FrontdeskNotificationBillingTest extends TestCase
+{
+    use RefreshDatabase;
+
+    protected User $owner;
+
+    protected Organization $organization;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->withoutMiddleware(EnsurePlatformSession::class);
+
+        config(['billing.api_url' => 'https://billing.test']);
+
+        $this->owner = User::create([
+            'public_id' => 'notify-owner-001',
+            'name' => 'Owner',
+            'email' => 'owner@example.com',
+        ]);
+
+        $this->organization = Organization::create([
+            'owner_ref' => $this->owner->public_id,
+            'name' => 'Notify Org',
+            'slug' => 'notify-org',
+            'settings' => [
+                'onboarded' => true,
+                'badge_expiry_hours' => 8,
+                'notification_channels' => ['email'],
+                'notification_events' => config('frontdesk.default_notification_events'),
+            ],
+        ]);
+
+        Member::create([
+            'owner_ref' => $this->owner->public_id,
+            'organization_id' => $this->organization->id,
+            'user_ref' => $this->owner->public_id,
+            'role' => 'org_admin',
+        ]);
+
+        Branch::create([
+            'owner_ref' => $this->owner->public_id,
+            'organization_id' => $this->organization->id,
+            'name' => 'HQ',
+            'is_active' => true,
+        ]);
+    }
+
+    public function test_host_email_notification_without_ladill_user_link(): void
+    {
+        Mail::fake();
+        Http::fake([
+            'billing.test/can-afford*' => Http::response(['affordable' => true]),
+            'billing.test/debit' => Http::response(['ok' => true]),
+        ]);
+
+        $host = Host::create([
+            'owner_ref' => $this->owner->public_id,
+            'organization_id' => $this->organization->id,
+            'name' => 'Email Host',
+            'email' => 'host-only@example.com',
+            'is_available' => true,
+        ]);
+
+        $this->actingAs($this->owner)
+            ->post(route('frontdesk.visits.store'), [
+                'full_name' => 'Walk-in',
+                'host_id' => $host->id,
+                'visitor_type' => 'visitor',
+                'policies_accepted' => '1',
+            ])
+            ->assertRedirect();
+
+        Mail::assertSent(\App\Mail\ContactMessageMail::class);
+
+        $usage = NotificationUsage::where('organization_id', $this->organization->id)->first();
+        $this->assertNotNull($usage);
+        $this->assertSame(1, $usage->email_count);
+        $this->assertSame(0, $usage->email_charged_minor);
+    }
+
+    public function test_paid_email_charges_wallet_after_free_allowance(): void
+    {
+        Mail::fake();
+        Http::fake([
+            'billing.test/can-afford*' => Http::response(['affordable' => true]),
+            'billing.test/debit' => Http::response(['ok' => true]),
+        ]);
+
+        NotificationUsage::create([
+            'organization_id' => $this->organization->id,
+            'period' => now()->format('Y-m'),
+            'email_count' => 100,
+            'sms_count' => 0,
+            'email_charged_minor' => 0,
+            'sms_charged_minor' => 0,
+        ]);
+
+        $host = Host::create([
+            'owner_ref' => $this->owner->public_id,
+            'organization_id' => $this->organization->id,
+            'name' => 'Paid Host',
+            'email' => 'paid@example.com',
+            'is_available' => true,
+        ]);
+
+        $this->actingAs($this->owner)
+            ->post(route('frontdesk.visits.store'), [
+                'full_name' => 'Paid Walk-in',
+                'host_id' => $host->id,
+                'visitor_type' => 'visitor',
+                'policies_accepted' => '1',
+            ])
+            ->assertRedirect();
+
+        Http::assertSent(fn ($request) => str_contains($request->url(), '/debit'));
+
+        $usage = NotificationUsage::where('organization_id', $this->organization->id)->first();
+        $this->assertSame(101, $usage->email_count);
+        $this->assertGreaterThan(0, $usage->email_charged_minor);
+    }
+
+    public function test_insufficient_balance_skips_host_email(): void
+    {
+        Mail::fake();
+        Http::fake([
+            'billing.test/can-afford*' => Http::response(['affordable' => false]),
+        ]);
+
+        NotificationUsage::create([
+            'organization_id' => $this->organization->id,
+            'period' => now()->format('Y-m'),
+            'email_count' => 100,
+        ]);
+
+        $host = Host::create([
+            'owner_ref' => $this->owner->public_id,
+            'organization_id' => $this->organization->id,
+            'name' => 'Blocked Host',
+            'email' => 'blocked@example.com',
+            'is_available' => true,
+        ]);
+
+        $this->actingAs($this->owner)
+            ->post(route('frontdesk.visits.store'), [
+                'full_name' => 'No Alert',
+                'host_id' => $host->id,
+                'visitor_type' => 'visitor',
+                'policies_accepted' => '1',
+            ])
+            ->assertRedirect();
+
+        Mail::assertNothingSent();
+    }
+
+    public function test_kiosk_returns_host_notified_flag(): void
+    {
+        Mail::fake();
+        Http::fake([
+            'billing.test/can-afford*' => Http::response(['affordable' => true]),
+            'billing.test/debit' => Http::response(['ok' => true]),
+        ]);
+
+        $host = Host::create([
+            'owner_ref' => $this->owner->public_id,
+            'organization_id' => $this->organization->id,
+            'name' => 'Kiosk Host',
+            'email' => 'kiosk-host@example.com',
+            'is_available' => true,
+        ]);
+
+        $this->actingAs($this->owner)
+            ->postJson(route('frontdesk.kiosk.check-in'), [
+                'full_name' => 'Kiosk Guest',
+                'host_id' => $host->id,
+                'visitor_type' => 'visitor',
+                'policies_accepted' => '1',
+            ])
+            ->assertOk()
+            ->assertJsonPath('visit.host_notified', true);
+    }
+
+    public function test_free_plan_blocks_second_branch(): void
+    {
+        $this->actingAs($this->owner)
+            ->post(route('frontdesk.branches.store'), [
+                'name' => 'Second Branch',
+            ])
+            ->assertRedirect()
+            ->assertSessionHas('error');
+    }
+
+    public function test_settings_shows_plan_and_usage(): void
+    {
+        NotificationUsage::create([
+            'organization_id' => $this->organization->id,
+            'period' => now()->format('Y-m'),
+            'email_count' => 12,
+            'sms_count' => 3,
+        ]);
+
+        $this->actingAs($this->owner)
+            ->get(route('frontdesk.settings'))
+            ->assertOk()
+            ->assertSee('Free')
+            ->assertSee('12')
+            ->assertSee('Upgrade to Pro');
+    }
+
+    public function test_pro_plan_emails_are_unlimited(): void
+    {
+        Mail::fake();
+        Http::fake([
+            'billing.test/can-afford*' => Http::response(['affordable' => true]),
+            'billing.test/debit' => Http::response(['ok' => true]),
+        ]);
+
+        $this->organization->update([
+            'settings' => array_merge($this->organization->settings ?? [], [
+                'plan' => 'pro',
+                'plan_expires_at' => now()->addMonth()->toIso8601String(),
+            ]),
+        ]);
+
+        NotificationUsage::create([
+            'organization_id' => $this->organization->id,
+            'period' => now()->format('Y-m'),
+            'email_count' => 10_000,
+        ]);
+
+        $host = Host::create([
+            'owner_ref' => $this->owner->public_id,
+            'organization_id' => $this->organization->id,
+            'name' => 'Pro Host',
+            'email' => 'pro@example.com',
+            'is_available' => true,
+        ]);
+
+        $this->actingAs($this->owner)
+            ->post(route('frontdesk.visits.store'), [
+                'full_name' => 'Pro Guest',
+                'host_id' => $host->id,
+                'visitor_type' => 'visitor',
+                'policies_accepted' => '1',
+            ])
+            ->assertRedirect();
+
+        Mail::assertSent(\App\Mail\ContactMessageMail::class);
+        Http::assertNotSent(fn ($request) => str_contains($request->url(), '/debit'));
+
+        $usage = NotificationUsage::where('organization_id', $this->organization->id)->first();
+        $this->assertSame(10_001, $usage->email_count);
+        $this->assertSame(0, $usage->email_charged_minor);
+    }
+
+    public function test_linked_user_still_gets_in_app_notification(): void
+    {
+        Notification::fake();
+        Mail::fake();
+        Http::fake([
+            'billing.test/can-afford*' => Http::response(['affordable' => true]),
+            'billing.test/debit' => Http::response(['ok' => true]),
+        ]);
+
+        $linkedUser = User::create([
+            'public_id' => 'linked-host-user',
+            'name' => 'Linked Host User',
+            'email' => 'linked@example.com',
+        ]);
+
+        $host = Host::create([
+            'owner_ref' => $this->owner->public_id,
+            'organization_id' => $this->organization->id,
+            'name' => 'Linked Host',
+            'email' => 'linked-host@example.com',
+            'user_ref' => $linkedUser->public_id,
+            'is_available' => true,
+        ]);
+
+        $this->actingAs($this->owner)
+            ->post(route('frontdesk.visits.store'), [
+                'full_name' => 'Guest',
+                'host_id' => $host->id,
+                'visitor_type' => 'visitor',
+                'policies_accepted' => '1',
+            ]);
+
+        Notification::assertSentTo($linkedUser, FrontdeskAlertNotification::class);
+    }
+}