fuel-price/docs/tiers.md

# Tier & Entitlement System

FuelAlert has four tiers: **free**, **basic**, **plus**, **pro**. Every entitlement
decision — which channels a user can receive, how often, and what features they can access
— flows through a single `PlanFeatures` service. Nothing else makes entitlement decisions.

---

## Tiers at a glance

| Tier  | Price  | Email             | Push    | WhatsApp | SMS          | AI predictions | Fuel types |
|-------|--------|-------------------|---------|----------|--------------|----------------|------------|
| free  | £0     | weekly digest     | —       | —        | —            | —              | 1          |
| basic | £0.99  | daily             | daily   | daily    | —            | —              | 1          |
| plus  | £2.49  | triggered         | triggered | triggered | max 1/day  | yes            | 1          |
| pro   | £3.99  | triggered         | triggered | triggered | max 3/day  | yes            | unlimited  |

Tiers are stored in the `plans` table. The `features` JSON column defines every limit and flag.

---

## Key files

| File | Purpose |
|------|---------|
| `app/Enums/PlanTier.php` | Backed enum — always use `PlanTier::Plus->value`, never raw strings |
| `app/Models/Plan.php` | Plan model with `resolveForUser()` and cache bust on save |
| `app/Models/UserNotificationPreference.php` | Per-user channel opt-in/out |
| `app/Models/NotificationLog.php` | Append-only send/miss log |
| `app/Services/PlanFeatures.php` | Single entry point for all entitlement checks |
| `app/Http/Middleware/RequiresFeature.php` | Route-level feature gates |
| `app/Jobs/DispatchUserNotificationJob.php` | Sends notifications and logs every outcome |
| `app/Jobs/SendScheduledWhatsAppJob.php` | Fan-out job for scheduled morning/evening updates |
| `database/seeders/PlanSeeder.php` | Idempotent seeder — run after deploy |

---

## The `plans` table

```
id                  bigint PK
name                string          — free | basic | plus | pro
stripe_price_id     string nullable — matches Cashier's stripe_price column
features            json            — see shape below
active              boolean
timestamps
```

### `features` JSON shape

```json
{
  "fuel_types": { "max": 1 },
  "email":      { "enabled": true, "frequency": "triggered" },
  "push":       { "enabled": true },
  "whatsapp":   { "enabled": true, "daily_limit": 5, "scheduled_updates": 2 },
  "sms":        { "enabled": true, "daily_limit": 3 },
  "ai_predictions": true,
  "price_threshold": true,
  "score_alerts": true
}
```

`fuel_types.max: null` means unlimited (pro only).
`email.frequency` values: `weekly_digest`, `daily`, `triggered`.
Boolean features default to `false` on the free tier.

---

## Resolving the plan for a user

`Plan::resolveForUser(User $user)` maps a user's active Cashier subscription to a plan row,
falling back to the free plan if no active subscription exists. The result is cached for 1 hour.

```php
// Resolve the plan — cached automatically
$plan = Plan::resolveForUser($user);

echo $plan->name;                             // 'plus'
echo $plan->features['sms']['daily_limit'];   // 3
```

The cache is tagged `plans` and flushed whenever a `Plan` row is saved. Use
`Cache::supportsTags()` guard if your driver (e.g. file/database) doesn't support tagging.

---

## Checking entitlements — `PlanFeatures`

Always use `PlanFeatures::for($user)` — never query `notification_log` directly for limit
checks, and never hardcode tier names in jobs or controllers.

```php
$features = PlanFeatures::for($user);

// Does the tier allow this channel at all?
$features->canUseChannel('sms');              // bool

// Tier allows AND daily limit not yet hit?
$features->canSendNow('sms');                 // bool

// All channels passing: tier allows → user enabled → limit not hit
$features->channelsFor('price_threshold');    // string[] e.g. ['email', 'push']

// Fuel type tracking
$features->canTrackFuelType('E10');           // bool
$features->fuelTypeLimit();                   // int|null (null = unlimited)
$features->trackedFuelTypeCount();            // int

// Boolean feature flags
$features->can('ai_predictions');             // bool

// Missed notification counts (for dashboard / digest emails)
$features->missedToday('sms');                // int
$features->missedThisMonth('sms');            // int

// Resolved tier name
$features->tier();                            // 'free' | 'basic' | 'plus' | 'pro'
```

`PlanFeatures` never throws — if plan resolution fails it falls back to a free-tier stub.

---

## Route-level feature gates

Register the `feature` middleware alias in `bootstrap/app.php`, then use it on any route:

```php
// bootstrap/app.php
$middleware->alias(['feature' => RequiresFeature::class]);

// routes/web.php or routes/api.php
Route::get('/predictions', PredictionsController::class)
    ->middleware('feature:ai_predictions');
```

Returns `403 JSON` when the feature is not available:

```json
{ "error": "upgrade_required", "feature": "ai_predictions" }
```

Use this for route-level gates only. Channel-level logic stays in `DispatchUserNotificationJob`.

---

## Dispatching notifications

### Triggered (price update, score change)

```php
// Dispatched by ProcessPriceAlerts or similar upstream job
DispatchUserNotificationJob::dispatch($user, 'price_threshold', 'E10', price: 143.9);
```

The job resolves channels, sends (stubbed until `FuelPriceAlert` notification exists), and
logs every outcome:

| Outcome | `sent` | `missed_reason` |
|---------|--------|-----------------|
| Sent    | `true` | `null` |
| Tier allows, limit hit | `false` | `daily_limit` |
| Tier blocks channel user wanted | `false` | `tier_restricted` |
| User deliberately disabled channel | not logged | — |

### Scheduled WhatsApp (morning / evening)

```php
// routes/console.php
Schedule::job(new SendScheduledWhatsAppJob('morning'))->dailyAt('07:30')->onOneServer();
Schedule::job(new SendScheduledWhatsAppJob('evening'))->dailyAt('18:00')->onOneServer();
```

`SendScheduledWhatsAppJob` finds users whose plan has `whatsapp.scheduled_updates > 0`,
whose whatsapp preference is enabled, and who have not hit their daily limit. It then
dispatches `DispatchUserNotificationJob` per user with trigger type `scheduled_morning`
or `scheduled_evening`.

---

## Adding a new feature flag

1. Add the key to the `features` JSON in `PlanSeeder` for each tier.
2. Add a method to `PlanFeatures` (e.g. `canExportData(): bool`).
3. Update the Filament `PlanResource` form (`app/Filament/Resources/Plans/Schemas/PlanForm.php`).
4. Add a test in `tests/Feature/Tiers/`.

---

## Adding a new notification channel

1. Add the channel key to the `features` JSON shape in `PlanSeeder`.
2. Add `enabled` and `daily_limit` sub-keys following the existing pattern.
3. Add the channel to `DispatchUserNotificationJob::ALL_CHANNELS`.
4. Update `PlanFeatures::channelsFor()` if any trigger-type filtering is needed.
5. Add tests.

---

## Testing

Seed the four plan rows before each test:

```php
beforeEach(function (): void {
    $this->artisan('db:seed', ['--class' => 'PlanSeeder']);
});
```

Use `Queue::fake()` when asserting dispatch behaviour:

```php
Queue::fake();

DispatchUserNotificationJob::dispatch($user, 'price_threshold', 'E10');

Queue::assertPushedOn('notifications', DispatchUserNotificationJob::class);
```

Test files live in `tests/Feature/Tiers/`:

| File | Covers |
|------|--------|
| `PlanFeaturesTest.php` | `canUseChannel`, `canSendNow`, `canTrackFuelType`, `can()`, middleware, log scopes |
| `PlanResourceTest.php` | Filament list/edit, no create/delete, saves features correctly |
| `DispatchUserNotificationJobTest.php` | Sent logging, `tier_restricted`, `daily_limit`, user-disabled suppression, queue name, fan-out |