Add subscription tiers, notification preferences, and logging infrastructure

- Add database migrations for plans, subscriptions, notification preferences, and notification log tables
- Implement DispatchUserNotificationJob to handle channel resolution, daily limits, and logging (sent/tier_restricted/daily_limit)
- Add SendScheduledWhatsAppJob for scheduled notification delivery
- Create PlanFeatures service to resolve tier capabilities, check daily limits, and validate fuel

app/Enums/PlanTier.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace App\Enums;
+
+enum PlanTier: string
+{
+    case Free = 'free';
+    case Basic = 'basic';
+    case Plus = 'plus';
+    case Pro = 'pro';
+}

app/Filament/Resources/Plans/Pages/EditPlan.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace App\Filament\Resources\Plans\Pages;
+
+use App\Filament\Resources\Plans\PlanResource;
+use Filament\Resources\Pages\EditRecord;
+use Illuminate\Support\Facades\Cache;
+
+class EditPlan extends EditRecord
+{
+    protected static string $resource = PlanResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [];
+    }
+
+    protected function afterSave(): void
+    {
+        if (Cache::supportsTags()) {
+            Cache::tags(['plans'])->flush();
+        }
+    }
+}

app/Filament/Resources/Plans/Pages/ListPlans.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Filament\Resources\Plans\Pages;
+
+use App\Filament\Resources\Plans\PlanResource;
+use Filament\Resources\Pages\ListRecords;
+
+class ListPlans extends ListRecords
+{
+    protected static string $resource = PlanResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [];
+    }
+}

app/Filament/Resources/Plans/PlanResource.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace App\Filament\Resources\Plans;
+
+use App\Filament\NavigationGroup;
+use App\Filament\Resources\Plans\Pages\EditPlan;
+use App\Filament\Resources\Plans\Pages\ListPlans;
+use App\Filament\Resources\Plans\Schemas\PlanForm;
+use App\Filament\Resources\Plans\Tables\PlansTable;
+use App\Models\Plan;
+use Filament\Resources\Resource;
+use Filament\Schemas\Schema;
+use Filament\Tables\Table;
+
+class PlanResource extends Resource
+{
+    protected static ?string $model = Plan::class;
+
+    protected static string|\UnitEnum|null $navigationGroup = NavigationGroup::System;
+
+    protected static ?int $navigationSort = 10;
+
+    public static function form(Schema $schema): Schema
+    {
+        return PlanForm::configure($schema);
+    }
+
+    public static function table(Table $table): Table
+    {
+        return PlansTable::configure($table);
+    }
+
+    public static function getPages(): array
+    {
+        return [
+            'index' => ListPlans::route('/'),
+            'edit' => EditPlan::route('/{record}/edit'),
+        ];
+    }
+}

app/Filament/Resources/Plans/Schemas/PlanForm.php

@@ -0,0 +1,91 @@
+<?php
+
+namespace App\Filament\Resources\Plans\Schemas;
+
+use Filament\Forms\Components\Select;
+use Filament\Forms\Components\TextInput;
+use Filament\Forms\Components\Toggle;
+use Filament\Schemas\Components\Section;
+use Filament\Schemas\Schema;
+
+class PlanForm
+{
+    public static function configure(Schema $schema): Schema
+    {
+        return $schema
+            ->components([
+                Section::make('Fuel Types')
+                    ->schema([
+                        TextInput::make('features.fuel_types.max')
+                            ->label('Max fuel types')
+                            ->helperText('Leave blank for unlimited.')
+                            ->numeric()
+                            ->integer()
+                            ->minValue(1)
+                            ->nullable(),
+                    ]),
+
+                Section::make('Email')
+                    ->columns(2)
+                    ->schema([
+                        Toggle::make('features.email.enabled')
+                            ->label('Enabled'),
+                        Select::make('features.email.frequency')
+                            ->label('Frequency')
+                            ->options([
+                                'weekly_digest' => 'Weekly digest',
+                                'daily' => 'Daily',
+                                'triggered' => 'Triggered',
+                            ]),
+                    ]),
+
+                Section::make('Push')
+                    ->schema([
+                        Toggle::make('features.push.enabled')
+                            ->label('Enabled'),
+                    ]),
+
+                Section::make('WhatsApp')
+                    ->columns(3)
+                    ->schema([
+                        Toggle::make('features.whatsapp.enabled')
+                            ->label('Enabled'),
+                        TextInput::make('features.whatsapp.daily_limit')
+                            ->label('Daily limit')
+                            ->numeric()
+                            ->integer()
+                            ->minValue(0)
+                            ->required(),
+                        TextInput::make('features.whatsapp.scheduled_updates')
+                            ->label('Scheduled updates per day')
+                            ->numeric()
+                            ->integer()
+                            ->minValue(0)
+                            ->required(),
+                    ]),
+
+                Section::make('SMS')
+                    ->columns(2)
+                    ->schema([
+                        Toggle::make('features.sms.enabled')
+                            ->label('Enabled'),
+                        TextInput::make('features.sms.daily_limit')
+                            ->label('Daily limit')
+                            ->numeric()
+                            ->integer()
+                            ->minValue(0)
+                            ->required(),
+                    ]),
+
+                Section::make('Features')
+                    ->schema([
+                        Toggle::make('features.ai_predictions')
+                            ->label('AI predictions'),
+                        Toggle::make('features.price_threshold')
+                            ->label('Price threshold alerts'),
+                        Toggle::make('features.score_alerts')
+                            ->label('Score change alerts'),
+                    ]),
+            ]);
+    }
+}

app/Filament/Resources/Plans/Tables/PlansTable.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace App\Filament\Resources\Plans\Tables;
+
+use Filament\Actions\EditAction;
+use Filament\Tables\Columns\IconColumn;
+use Filament\Tables\Columns\TextColumn;
+use Filament\Tables\Table;
+
+class PlansTable
+{
+    public static function configure(Table $table): Table
+    {
+        return $table
+            ->columns([
+                TextColumn::make('name')
+                    ->label('Tier')
+                    ->badge()
+                    ->sortable(),
+                TextColumn::make('features.email.frequency')
+                    ->label('Email')
+                    ->placeholder('—'),
+                TextColumn::make('features.sms.daily_limit')
+                    ->label('SMS/day')
+                    ->placeholder('—'),
+                TextColumn::make('features.whatsapp.daily_limit')
+                    ->label('WhatsApp/day')
+                    ->placeholder('—'),
+                TextColumn::make('features.fuel_types.max')
+                    ->label('Fuel types')
+                    ->placeholder('Unlimited'),
+                IconColumn::make('active')
+                    ->boolean(),
+            ])
+            ->defaultSort('id', 'asc')
+            ->recordActions([
+                EditAction::make(),
+            ]);
+    }
+}

app/Http/Middleware/RequiresFeature.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use App\Services\PlanFeatures;
+use Closure;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+class RequiresFeature
+{
+    /**
+     * Handle an incoming request.
+     *
+     * @param  Closure(Request): (Response)  $next
+     */
+    public function handle(Request $request, Closure $next, string $feature): Response
+    {
+        $user = $request->user();
+
+        if (! $user || ! PlanFeatures::for($user)->can($feature)) {
+            return response()->json([
+                'error' => 'upgrade_required',
+                'feature' => $feature,
+            ], Response::HTTP_FORBIDDEN);
+        }
+
+        return $next($request);
+    }
+}

app/Jobs/DispatchUserNotificationJob.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace App\Jobs;
+
+use App\Models\NotificationLog;
+use App\Models\User;
+use App\Models\UserNotificationPreference;
+use App\Services\PlanFeatures;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Queue\Queueable;
+
+/**
+ * Resolves allowed notification channels for a user and trigger, sends
+ * notifications, and logs every outcome (sent, daily_limit, tier_restricted).
+ *
+ * Actual sending is stubbed until FuelPriceAlert notification class exists.
+ */
+final class DispatchUserNotificationJob implements ShouldQueue
+{
+    use Queueable;
+
+    /** @var string[] */
+    private const array ALL_CHANNELS = ['email', 'push', 'whatsapp', 'sms'];
+
+    public function __construct(
+        public readonly User $user,
+        public readonly string $triggerType,
+        public readonly string $fuelType,
+        public readonly ?float $price = null,
+    ) {
+        $this->onQueue('notifications');
+    }
+
+    public function handle(): void
+    {
+        $features = PlanFeatures::for($this->user);
+
+        // Step 3: channels that pass tier + user-pref + daily-limit checks
+        $allowed = $features->channelsFor($this->triggerType);
+
+        // Step 4: send and log sent notifications
+        foreach ($allowed as $channel) {
+            // TODO: $this->user->notify(new FuelPriceAlert($this->triggerType, $this->fuelType, $this->price));
+            $this->log($channel, sent: true);
+        }
+
+        // Channels not in the allowed set — split into missed reasons
+        $notAllowed = array_diff(self::ALL_CHANNELS, $allowed);
+
+        foreach ($notAllowed as $channel) {
+            if (! $this->userHasEnabledPref($channel)) {
+                // User intentionally disabled — do not log (noise)
+                continue;
+            }
+
+            if ($features->canUseChannel($channel)) {
+                // Step 5: tier allows but daily limit exhausted
+                $this->log($channel, sent: false, missedReason: 'daily_limit');
+            } else {
+                // Step 6: tier does not allow the channel the user wanted
+                $this->log($channel, sent: false, missedReason: 'tier_restricted');
+            }
+        }
+    }
+
+    private function log(string $channel, bool $sent, ?string $missedReason = null): void
+    {
+        NotificationLog::create([
+            'user_id' => $this->user->id,
+            'channel' => $channel,
+            'trigger_type' => $this->triggerType,
+            'fuel_type' => $this->fuelType,
+            'price' => $this->price,
+            'sent' => $sent,
+            'missed_reason' => $missedReason,
+            'created_at' => now(),
+        ]);
+    }
+
+    private function userHasEnabledPref(string $channel): bool
+    {
+        return UserNotificationPreference::where('user_id', $this->user->id)
+            ->where('channel', $channel)
+            ->where('enabled', true)
+            ->exists();
+    }
+}

app/Jobs/SendScheduledWhatsAppJob.php

@@ -0,0 +1,64 @@
+<?php
+
+namespace App\Jobs;
+
+use App\Models\Plan;
+use App\Models\User;
+use App\Models\UserNotificationPreference;
+use App\Services\PlanFeatures;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Queue\Queueable;
+
+/**
+ * Fan-out job for scheduled WhatsApp updates (morning / evening).
+ * Finds all eligible users and dispatches DispatchUserNotificationJob per user.
+ *
+ * Scheduled at 07:30 (morning) and 18:00 (evening) via routes/console.php.
+ */
+final class SendScheduledWhatsAppJob implements ShouldQueue
+{
+    use Queueable;
+
+    public function __construct(public readonly string $period)
+    {
+        //
+    }
+
+    public function handle(): void
+    {
+        $triggerType = $this->period === 'morning' ? 'scheduled_morning' : 'scheduled_evening';
+
+        // Plans that allow scheduled WhatsApp updates
+        $eligiblePlanNames = Plan::where('active', true)
+            ->get()
+            ->filter(fn (Plan $plan): bool => ($plan->features['whatsapp']['scheduled_updates'] ?? 0) > 0)
+            ->pluck('name')
+            ->all();
+
+        if (empty($eligiblePlanNames)) {
+            return;
+        }
+
+        // Users who have whatsapp preference enabled
+        $userIds = UserNotificationPreference::where('channel', 'whatsapp')
+            ->where('enabled', true)
+            ->distinct()
+            ->pluck('user_id');
+
+        User::whereIn('id', $userIds)
+            ->each(function (User $user) use ($triggerType, $eligiblePlanNames): void {
+                $features = PlanFeatures::for($user);
+
+                // Skip if their tier isn't eligible or daily limit is hit
+                if (! in_array($features->tier(), $eligiblePlanNames, strict: true)) {
+                    return;
+                }
+
+                if (! $features->canSendNow('whatsapp')) {
+                    return;
+                }
+
+                DispatchUserNotificationJob::dispatch($user, $triggerType, fuelType: 'all');
+            });
+    }
+}

app/Models/NotificationLog.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace App\Models;
+
+use Database\Factories\NotificationLogFactory;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class NotificationLog extends Model
+{
+    /** @use HasFactory<NotificationLogFactory> */
+    use HasFactory;
+
+    public $timestamps = false;
+    protected $table = 'notification_log';
+    protected $fillable = [
+        'user_id',
+        'channel',
+        'trigger_type',
+        'fuel_type',
+        'price',
+        'sent',
+        'missed_reason',
+        'created_at',
+    ];
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    /** Count sent notifications for this channel today. */
+    public function scopeSentToday(Builder $query, string $channel): void
+    {
+        $query->where('channel', $channel)
+            ->where('sent', true)
+            ->whereDate('created_at', today());
+    }
+
+    /** Notifications that were not sent. */
+    public function scopeMissed(Builder $query): void
+    {
+        $query->where('sent', false);
+    }
+
+    protected function casts(): array
+    {
+        return [
+            'sent' => 'boolean',
+            'price' => 'decimal:3',
+            'created_at' => 'datetime',
+        ];
+    }
+}

app/Models/Plan.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace App\Models;
+
+use App\Enums\PlanTier;
+use Database\Factories\PlanFactory;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Facades\Cache;
+
+class Plan extends Model
+{
+    /** @use HasFactory<PlanFactory> */
+    use HasFactory;
+
+    protected $fillable = [
+        'name',
+        'stripe_price_id',
+        'features',
+        'active',
+    ];
+
+    /**
+     * Resolve the active plan for a user.
+     * Falls back to the free plan when no active Cashier subscription exists.
+     */
+    public static function resolveForUser(User $user): self
+    {
+        $cache = Cache::supportsTags() ? Cache::tags(['plans']) : Cache::store();
+
+        return $cache->remember(
+            "plan_for_user_{$user->id}",
+            3600,
+            function () use ($user): self {
+                $priceId = null;
+
+                if (method_exists($user, 'subscriptions')) {
+                    $subscription = $user->subscriptions()->active()->first();
+                    $priceId = $subscription?->stripe_price ?? null;
+                }
+
+                if ($priceId) {
+                    $plan = static::where('stripe_price_id', $priceId)->where('active', true)->first();
+
+                    if ($plan) {
+                        return $plan;
+                    }
+                }
+
+                return static::where('name', PlanTier::Free->value)->firstOrFail();
+            }
+        );
+    }
+
+    protected static function booted(): void
+    {
+        static::saved(function (): void {
+            if (Cache::supportsTags()) {
+                Cache::tags(['plans'])->flush();
+            }
+        });
+    }
+
+    protected function casts(): array
+    {
+        return [
+            'features' => 'array',
+            'active' => 'boolean',
+        ];
+    }
+}

app/Models/User.php

@@ -58,4 +58,14 @@ class User extends Authenticatable implements FilamentUser
     {
         return $this->hasMany(SavedStation::class);
     }
+
+    public function notificationPreferences(): HasMany
+    {
+        return $this->hasMany(UserNotificationPreference::class);
+    }
+
+    public function notificationLogs(): HasMany
+    {
+        return $this->hasMany(NotificationLog::class);
+    }
 }

app/Models/UserNotificationPreference.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace App\Models;
+
+use Database\Factories\UserNotificationPreferenceFactory;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class UserNotificationPreference extends Model
+{
+    /** @use HasFactory<UserNotificationPreferenceFactory> */
+    use HasFactory;
+
+    protected $fillable = [
+        'user_id',
+        'channel',
+        'fuel_type',
+        'enabled',
+    ];
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function scopeEnabled(Builder $query): void
+    {
+        $query->where('enabled', true);
+    }
+
+    public function scopeForChannel(Builder $query, string $channel): void
+    {
+        $query->where('channel', $channel);
+    }
+
+    public function scopeForFuelType(Builder $query, string $fuelType): void
+    {
+        $query->where('fuel_type', $fuelType);
+    }
+
+    protected function casts(): array
+    {
+        return [
+            'enabled' => 'boolean',
+        ];
+    }
+}

app/Services/PlanFeatures.php

@@ -0,0 +1,198 @@
+<?php
+
+namespace App\Services;
+
+use App\Models\NotificationLog;
+use App\Models\Plan;
+use App\Models\User;
+use App\Models\UserNotificationPreference;
+use Throwable;
+
+final class PlanFeatures
+{
+    private Plan $plan;
+
+    private function __construct(private readonly User $user)
+    {
+        try {
+            $this->plan = Plan::resolveForUser($user);
+        } catch (Throwable) {
+            // Never throw — fall back to a free-tier stub if resolution fails.
+            $this->plan = new Plan([
+                'name' => 'free',
+                'features' => [
+                    'fuel_types' => ['max' => 1],
+                    'email' => ['enabled' => true, 'frequency' => 'weekly_digest'],
+                    'push' => ['enabled' => false],
+                    'whatsapp' => ['enabled' => false, 'daily_limit' => 0, 'scheduled_updates' => 0],
+                    'sms' => ['enabled' => false, 'daily_limit' => 0],
+                    'ai_predictions' => false,
+                    'price_threshold' => false,
+                    'score_alerts' => false,
+                ],
+            ]);
+        }
+    }
+
+    public static function for(User $user): self
+    {
+        return new self($user);
+    }
+
+    /**
+     * Channels allowed for a given trigger type, filtered by:
+     * tier allows → user has enabled → daily limit not hit.
+     *
+     * @return string[]
+     */
+    public function channelsFor(string $triggerType): array
+    {
+        $allChannels = ['email', 'push', 'whatsapp', 'sms'];
+        $allowed = [];
+
+        foreach ($allChannels as $channel) {
+            if (! $this->canUseChannel($channel)) {
+                continue;
+            }
+
+            if (! $this->userHasEnabledChannel($channel)) {
+                continue;
+            }
+
+            if (! $this->canSendNow($channel)) {
+                continue;
+            }
+
+            $allowed[] = $channel;
+        }
+
+        return $allowed;
+    }
+
+    /** Whether the plan allows this channel at all. */
+    public function canUseChannel(string $channel): bool
+    {
+        return (bool) ($this->feature($channel, 'enabled') ?? false);
+    }
+
+    /** Read a nested feature value, e.g. feature('sms', 'daily_limit'). */
+    private function feature(string $channel, string $key): mixed
+    {
+        $features = $this->plan->features ?? [];
+
+        return $features[$channel][$key] ?? null;
+    }
+
+    /** Whether the user has opted in to this channel for at least one fuel type. */
+    private function userHasEnabledChannel(string $channel): bool
+    {
+        return UserNotificationPreference::where('user_id', $this->user->id)
+            ->where('channel', $channel)
+            ->where('enabled', true)
+            ->exists();
+    }
+
+    /**
+     * Whether a notification can be sent right now on this channel.
+     * Checks both the plan cap and today's live count in notification_log.
+     */
+    public function canSendNow(string $channel): bool
+    {
+        if (! $this->canUseChannel($channel)) {
+            return false;
+        }
+
+        $dailyLimit = $this->feature($channel, 'daily_limit');
+
+        // null or 0 in the feature means no SMS/unlimited — treat 0 as blocked, null as unlimited
+        if ($dailyLimit === null) {
+            return true;
+        }
+
+        if ($dailyLimit === 0) {
+            return false;
+        }
+
+        $sentToday = NotificationLog::where('user_id', $this->user->id)
+            ->where('channel', $channel)
+            ->where('sent', true)
+            ->whereDate('created_at', today())
+            ->count();
+
+        return $sentToday < $dailyLimit;
+    }
+
+    /** Whether the user can track an additional fuel type. */
+    public function canTrackFuelType(string $fuelType): bool
+    {
+        $limit = $this->fuelTypeLimit();
+
+        if ($limit === null) {
+            return true;
+        }
+
+        $count = $this->trackedFuelTypeCount();
+
+        // Allow if already tracking this type (not adding a new one)
+        $alreadyTracking = UserNotificationPreference::where('user_id', $this->user->id)
+            ->where('fuel_type', $fuelType)
+            ->exists();
+
+        if ($alreadyTracking) {
+            return true;
+        }
+
+        return $count < $limit;
+    }
+
+    /** Maximum fuel types allowed, or null for unlimited. */
+    public function fuelTypeLimit(): ?int
+    {
+        $features = $this->plan->features ?? [];
+
+        return $features['fuel_types']['max'] ?? 1;
+    }
+
+    /** Count of distinct fuel types the user has preferences for. */
+    public function trackedFuelTypeCount(): int
+    {
+        return UserNotificationPreference::where('user_id', $this->user->id)
+            ->distinct('fuel_type')
+            ->count('fuel_type');
+    }
+
+    /** Generic boolean feature flag check. */
+    public function can(string $feature): bool
+    {
+        $features = $this->plan->features ?? [];
+
+        return (bool) ($features[$feature] ?? false);
+    }
+
+    /** Count of notifications missed today on a channel. */
+    public function missedToday(string $channel): int
+    {
+        return NotificationLog::where('user_id', $this->user->id)
+            ->where('channel', $channel)
+            ->where('sent', false)
+            ->whereDate('created_at', today())
+            ->count();
+    }
+
+    /** Count of notifications missed this month on a channel. */
+    public function missedThisMonth(string $channel): int
+    {
+        return NotificationLog::where('user_id', $this->user->id)
+            ->where('channel', $channel)
+            ->where('sent', false)
+            ->whereMonth('created_at', now()->month)
+            ->whereYear('created_at', now()->year)
+            ->count();
+    }
+
+    /** The resolved plan tier name. */
+    public function tier(): string
+    {
+        return $this->plan->name ?? 'free';
+    }
+}