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 | Price threshold | Score alerts | Fuel types |
|-------|--------|---------------|-----------|-----------|------------|----------------|-----------------|--------------|------------|
| free  | £0     | weekly digest | —         | —         | —          | —              | —               | —            | 1          |
| basic | £0.99  | daily         | daily     | daily     | —          | —              | ✓               | ✓            | 1          |
| plus  | £2.49  | triggered     | triggered | triggered | max 1/day  | ✓              | ✓               | ✓            | 1          |
| pro   | £3.99  | triggered     | triggered | triggered | max 3/day  | ✓              | ✓               | ✓            | unlimited  |

Tiers are stored in the `plans` table. The `features` JSON column defines every limit and flag.
`database/seeders/PlanSeeder.php` is the source of truth — this table mirrors it.

> **Deeper entitlements** (history window, prediction level, leaderboard size, saved stations,
> fuel log caps, brand comparison, route planner, family sharing) are defined in
> `docs/superpowers/specs/2026-04-15-tier-features-design.md`. That spec extends the
> `features` JSON shape with additional keys beyond the notification-channel flags below.

---

## 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_monthly     string nullable — Cashier price ID for monthly billing
stripe_price_id_annual      string nullable — Cashier price ID for annual billing
features                    json            — see shape below
active                      boolean
timestamps
```

### `features` JSON shape (notification-channel flags)

```json
{
  "fuel_types": { "max": 1 },
  "email":      { "enabled": true, "frequency": "triggered" },
  "push":       { "enabled": true, "frequency": "triggered" },
  "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`.
`push.frequency` values: `none` (when disabled), `daily`, `triggered`.
`whatsapp` and `sms` always carry `daily_limit` (and whatsapp carries `scheduled_updates`)
even when `enabled: false` — set to `0` on disabled tiers. See `PlanSeeder`.
Boolean features default to `false` on the free tier.

**`price_threshold` and `score_alerts` are enabled on basic and above** (not plus-only).
**`ai_predictions` is plus and above only.**

---

## 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, display name, `push.frequency` shape |
| `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 |

Unit:

| File | Covers |
|------|--------|
| `tests/Unit/Enums/PlanTierTest.php` | `PlanTier::label()` — user-facing display names |

---

## Change log

### 2026-04-20 — display-name layer, `push.frequency`, pricing card rename

Reconciled docs with `PlanSeeder` reality and introduced the display-name layer from `Downloads/pricing-plan.md` v2.

**Entitlement reality (docs were stale before this pass):**
- `price_threshold` and `score_alerts` are on **basic, plus, pro** — not plus-only.
- `ai_predictions` is plus+pro only.
- Schema columns are `stripe_price_id_monthly` and `stripe_price_id_annual` (not a single `stripe_price_id`).

**New: display-name layer.** Backend tier identifiers stay `basic/plus/pro`; UI-facing names are `Free/Daily/Smart/Pro`.
- `app/Enums/PlanTier.php` — added `label(): string`
- `app/Models/Plan.php` — added `displayName(): string` (delegates to enum)
- `app/Services/PlanFeatures.php` — added `displayName(): string`

**New: `push.frequency` key in `features` JSON.** Mirrors `email.frequency` so Daily's "daily push" is distinguishable from Smart/Pro's "triggered push".
- Values: `none` (when disabled), `daily`, `triggered`
- Seeded: free=`none`, basic=`daily`, plus=`triggered`, pro=`triggered`
- Touched: `PlanSeeder`, `PlanFactory`, free-tier stubs in `Plan::resolveForUser` + `PlanFeatures::__construct`, Filament `PlanForm`

**Marketing: homepage pricing cards renamed.** `resources/js/views/Home.vue`:
- Card labels: `Basic` → `Daily`, `Plus` → `Smart`
- Badge: `Most Popular` → `Most pick this`
- CTAs: `Select Basic` → `Choose Daily`, `Join Plus` → `Choose Smart`, `Go Pro` → `Choose Pro`, free unauthed `Get started` → `Start free`
- Smart retains the existing accent-ring highlight; Pro retains the dark card.

**Deferred:** `Fleet` tier (per-seat B2B), `Start 14-day trial` CTA on Smart (no trial backend), swapping Smart to a dark card (current accent ring is sufficient).

**Operational:** existing DB rows won't have `push.frequency` until `php artisan db:seed --class=PlanSeeder` runs. The seeder is idempotent.