<?php

namespace Tests\Unit\Billing;

use App\Enums\BillingAccessState;
use PHPUnit\Framework\TestCase;

class BillingAccessStateTest extends TestCase
{
    public function test_it_lists_exactly_the_states_that_grant_access(): void
    {
        $this->assertSame(
            ['trialing', 'active', 'past_due', 'cancelled'],
            BillingAccessState::grantingAppAccess(),
        );
    }

    /**
     * The list must be DERIVED from grantsAppAccess(), not typed out beside
     * it. This asserts the two agree for every case, so a state added later
     * cannot appear in one and not the other.
     */
    public function test_the_list_agrees_with_the_rule_for_every_case(): void
    {
        $granting = BillingAccessState::grantingAppAccess();

        foreach (BillingAccessState::cases() as $case) {
            $this->assertSame(
                $case->grantsAppAccess(),
                in_array($case->value, $granting, true),
                "{$case->value} disagrees between grantsAppAccess() and grantingAppAccess().",
            );
        }
    }

    public function test_restricted_and_suspended_do_not_grant_access(): void
    {
        $this->assertFalse(BillingAccessState::Restricted->grantsAppAccess());
        $this->assertFalse(BillingAccessState::Suspended->grantsAppAccess());
    }
}

    /**
     * The values of every state that grants access, for narrowing a query.
     *
     * Derived from `grantsAppAccess()` rather than typed out beside it: a
     * second list is how a state added later ends up granting access in SQL
     * and denying it in PHP, or the reverse.
     *
     * @return list<string>
     */
    public static function grantingAppAccess(): array
    {
        return array_values(array_map(
            fn (self $case) => $case->value,
            array_filter(self::cases(), fn (self $case) => $case->grantsAppAccess()),
        ));
    }

    /**
     * Teams whose billing state still lets their members use the app.
     *
     * The scheduled jobs that create records for a team narrow with this
     * (design doc, "Increment 3 in detail" → "Scheduled work for a restricted
     * team"), so that "who has access" is answered in one place for both the
     * request path and the scheduler.
     */
    public function scopeWithAppAccess(Builder $query): void
    {
        $query->whereIn('billing_access_state', BillingAccessState::grantingAppAccess());
    }

<?php

namespace Tests\Feature\Billing;

use App\Enums\BillingAccessState;
use App\Models\Billing\BillingEvent;
use App\Models\Team;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Carbon;
use Tests\TestCase;

class ApplyAccessExpiryTest extends TestCase
{
    use RefreshDatabase;

    private function team(string $name, BillingAccessState $state, array $dates = []): Team
    {
        return Team::factory()->create([
            'name' => $name,
            'billing_access_state' => $state->value,
            ...$dates,
        ]);
    }

    public function test_it_restricts_a_past_due_team_whose_grace_has_ended(): void
    {
        $team = $this->team('Lapsed', BillingAccessState::PastDue, [
            'billing_grace_ends_at' => Carbon::now()->subDay(),
        ]);

        $this->artisan('billing:apply-access-expiry')->assertSuccessful();

        $this->assertSame(BillingAccessState::Restricted, $team->refresh()->billing_access_state);
        $this->assertNotNull($team->billing_restricted_at);
    }

    public function test_it_leaves_a_past_due_team_still_inside_its_grace_window(): void
    {
        $team = $this->team('Still In Grace', BillingAccessState::PastDue, [
            'billing_grace_ends_at' => Carbon::now()->addDays(5),
        ]);

        $this->artisan('billing:apply-access-expiry')->assertSuccessful();

        $this->assertSame(BillingAccessState::PastDue, $team->refresh()->billing_access_state);
    }

    public function test_it_restricts_a_cancelled_team_whose_paid_period_has_ended(): void
    {
        $team = $this->team('Cancelled', BillingAccessState::Cancelled, [
            'billing_current_period_ends_at' => Carbon::now()->subHour(),
        ]);

        $this->artisan('billing:apply-access-expiry')->assertSuccessful();

        $this->assertSame(BillingAccessState::Restricted, $team->refresh()->billing_access_state);
    }

    public function test_it_leaves_a_cancelled_team_still_inside_its_paid_period(): void
    {
        $team = $this->team('Cancelled Later', BillingAccessState::Cancelled, [
            'billing_current_period_ends_at' => Carbon::now()->addWeek(),
        ]);

        $this->artisan('billing:apply-access-expiry')->assertSuccessful();

        $this->assertSame(BillingAccessState::Cancelled, $team->refresh()->billing_access_state);
    }

    public function test_a_past_due_team_with_no_grace_date_is_left_alone(): void
    {
        $team = $this->team('No Date', BillingAccessState::PastDue, [
            'billing_grace_ends_at' => null,
        ]);

        $this->artisan('billing:apply-access-expiry')->assertSuccessful();

        $this->assertSame(BillingAccessState::PastDue, $team->refresh()->billing_access_state);
    }

    /**
     * An enterprise team sits in `active` and only a superadmin moves it.
     * A stale date on such a team must never restrict it.
     */
    public function test_it_never_touches_an_active_team(): void
    {
        $team = $this->team('Enterprise', BillingAccessState::Active, [
            'billing_grace_ends_at' => Carbon::now()->subYear(),
            'billing_current_period_ends_at' => Carbon::now()->subYear(),
        ]);

        $this->artisan('billing:apply-access-expiry')->assertSuccessful();

        $this->assertSame(BillingAccessState::Active, $team->refresh()->billing_access_state);
    }

    public function test_it_never_reopens_a_suspended_team(): void
    {
        $team = $this->team('Suspended', BillingAccessState::Suspended, [
            'billing_grace_ends_at' => Carbon::now()->subDay(),
        ]);

        $this->artisan('billing:apply-access-expiry')->assertSuccessful();

        $this->assertSame(BillingAccessState::Suspended, $team->refresh()->billing_access_state);
    }

    public function test_it_records_a_billing_event_naming_the_reason(): void
    {
        $this->team('Lapsed', BillingAccessState::PastDue, [
            'billing_grace_ends_at' => Carbon::now()->subDay(),
        ]);

        $this->artisan('billing:apply-access-expiry')->assertSuccessful();

        $event = BillingEvent::query()->where('type', 'access.restricted')->sole();

        $this->assertSame('grace_expired', $event->payload['reason']);
        $this->assertNull($event->actor_user_id);
    }

    public function test_running_it_twice_restricts_once(): void
    {
        $this->team('Lapsed', BillingAccessState::PastDue, [
            'billing_grace_ends_at' => Carbon::now()->subDay(),
        ]);

        $this->artisan('billing:apply-access-expiry')->assertSuccessful();
        $this->artisan('billing:apply-access-expiry')->assertSuccessful();

        $this->assertSame(1, BillingEvent::query()->where('type', 'access.restricted')->count());
    }

    public function test_dry_run_writes_nothing(): void
    {
        $team = $this->team('Lapsed', BillingAccessState::PastDue, [
            'billing_grace_ends_at' => Carbon::now()->subDay(),
        ]);

        $this->artisan('billing:apply-access-expiry --dry-run')->assertSuccessful();

        $this->assertSame(BillingAccessState::PastDue, $team->refresh()->billing_access_state);
        $this->assertSame(0, BillingEvent::query()->count());
    }

    public function test_a_run_with_nothing_to_do_says_so(): void
    {
        $this->artisan('billing:apply-access-expiry')
            ->expectsOutputToContain('No team has reached')
            ->assertSuccessful();
    }
}

<?php

namespace App\Actions\Billing;

use App\Enums\BillingAccessState;
use App\Models\Billing\BillingEvent;
use App\Models\Team;
use App\Models\User;
use App\Support\Billing\Entitlements;
use Illuminate\Support\Carbon;
use Illuminate\Support\Facades\DB;

/**
 * Removes a team's access because a date it was living on has passed
 * (design doc, "Increment 3 in detail" → "The trigger").
 *
 * Distinct from `SuspendTeam`, which is a superadmin's deliberate act: this
 * is the lifecycle catching up with itself, so the actor is normally null and
 * the reason says which date ran out.
 *
 * Refuses to restrict a team that is not in a state the lifecycle restricts
 * FROM — notably `suspended`, which must never be quietly downgraded, and
 * `active`, where a stale date left over from an earlier cycle would
 * otherwise take a working enterprise team offline.
 */
class RestrictTeam
{
    /**
     * States the lifecycle may restrict from.
     */
    private const RESTRICTABLE = [
        BillingAccessState::PastDue,
        BillingAccessState::Cancelled,
    ];

    public function handle(Team $team, string $reason, ?User $actor = null): Team
    {
        return DB::transaction(function () use ($team, $reason, $actor) {
            // Lock, then re-check: a superadmin may have suspended or restored
            // this team between the command's query and this write.
            $locked = Team::query()->whereKey($team->getKey())->lockForUpdate()->firstOrFail();

            abort_unless(
                in_array($locked->billing_access_state, self::RESTRICTABLE, true),
                422,
                'Only a past-due or cancelled team can be restricted by the lifecycle.',
            );

            $locked->forceFill([
                'billing_access_state' => BillingAccessState::Restricted,
                'billing_restricted_at' => Carbon::now(),
            ])->save();

            BillingEvent::record(
                $locked,
                'access.restricted',
                [
                    'reason' => $reason,
                    'from' => $team->billing_access_state->value,
                ],
                $actor?->id,
            );

            Entitlements::flush();

            return $locked;
        });
    }
}

<?php

namespace App\Console\Commands;

use App\Actions\Billing\RestrictTeam;
use App\Enums\BillingAccessState;
use App\Models\Team;
use Illuminate\Console\Command;
use Illuminate\Support\Carbon;

/**
 * Applies the two lifecycle transitions that are simply a date passing
 * (design doc, "Increment 3 in detail" → "The trigger"):
 *
 *   past_due  --billing_grace_ends_at passed--------> restricted
 *   cancelled --billing_current_period_ends_at passed-> restricted
 *
 * Deliberately not part of increment 5's dunning: this sends no mail, calls
 * no Stripe and retries nothing. It reads two dates and writes one column, so
 * increment 3's restriction flow has a real trigger rather than only a
 * superadmin doing it by hand.
 *
 * Only actually runs once `schedule:run` is invoked by a real cron/systemd
 * timer in the deployment.
 */
class ApplyAccessExpiry extends Command
{
    protected $signature = 'billing:apply-access-expiry
                            {--dry-run : Show what would be restricted without writing anything}';

    protected $description = 'Restrict teams whose grace window or paid period has ended';

    public function handle(RestrictTeam $restrictTeam): int
    {
        $dryRun = (bool) $this->option('dry-run');
        $now = Carbon::now();
        $rows = [];

        $due = Team::query()
            ->where(fn ($query) => $query
                ->where('billing_access_state', BillingAccessState::PastDue->value)
                ->whereNotNull('billing_grace_ends_at')
                ->where('billing_grace_ends_at', '<=', $now))
            ->orWhere(fn ($query) => $query
                ->where('billing_access_state', BillingAccessState::Cancelled->value)
                ->whereNotNull('billing_current_period_ends_at')
                ->where('billing_current_period_ends_at', '<=', $now));

        $due->chunkById(200, function ($teams) use ($restrictTeam, $dryRun, &$rows) {
            foreach ($teams as $team) {
                $reason = $team->billing_access_state === BillingAccessState::PastDue
                    ? 'grace_expired'
                    : 'cancellation_period_ended';

                if ($dryRun) {
                    $rows[] = [$team->name, $team->billing_access_state->value, $reason, 'would restrict'];

                    continue;
                }

                $restrictTeam->handle($team, $reason);

                $rows[] = [$team->name, $team->billing_access_state->value, $reason, 'restricted'];
            }
        });

        if ($rows === []) {
            $this->info('No team has reached the end of a grace window or paid period.');

            return self::SUCCESS;
        }

        $this->table(['Organization', 'From', 'Reason', 'Outcome'], $rows);

        if ($dryRun) {
            $this->comment('Dry run — nothing was written.');
        }

        return self::SUCCESS;
    }
}

// design doc, "Increment 3 in detail" → "The trigger": past_due -> restricted
// and cancelled -> restricted are dates passing, not payment events, so they
// run here rather than waiting for increment 5's dunning. Daily because both
// governing values are dates; the Action re-checks state under a lock, so a
// superadmin acting between the query and the write wins.
Schedule::command('billing:apply-access-expiry')
    ->daily()
    ->withoutOverlapping()
    ->description('Restrict teams whose grace window or paid period has ended');

herd php -d memory_limit=2G artisan test --compact tests/Feature/Billing tests/Unit/Billing tests/Feature/SuperAdmin
herd php -d memory_limit=1G vendor/bin/phpstan analyse app/Actions/Billing app/Console/Commands app/Enums app/Models app/Support/Billing --no-progress
vendor/bin/pint --dirty --format agent
git add app/Enums/BillingAccessState.php app/Models/Team.php app/Actions/Billing/RestrictTeam.php \
        app/Console/Commands/ApplyAccessExpiry.php routes/console.php \
        tests/Unit/Billing/BillingAccessStateTest.php tests/Feature/Billing/ApplyAccessExpiryTest.php
git commit -m "Billing: let a date be what restricts a team"

<?php

namespace Tests\Feature\Billing;

use App\Enums\BillingAccessState;
use App\Enums\TeamRole;
use App\Models\Team;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Inertia\Testing\AssertableInertia;
use Tests\TestCase;

class RestrictedAccessTest extends TestCase
{
    use RefreshDatabase;

    private function member(BillingAccessState $state, TeamRole $role = TeamRole::Member): User
    {
        $team = Team::factory()->create([
            'name' => 'Acme Logistics',
            'billing_access_state' => $state->value,
        ]);

        $user = User::factory()->create();

        $team->members()->attach($user, ['role' => $role->value, 'status' => 1]);
        $user->forceFill(['current_team_id' => $team->id])->save();

        return $user->refresh();
    }

    public function test_a_member_of_an_active_team_reaches_the_dashboard(): void
    {
        $this->actingAs($this->member(BillingAccessState::Active))
            ->get('/dashboard')
            ->assertOk();
    }

    public function test_a_member_of_a_restricted_team_is_sent_to_the_restricted_page(): void
    {
        $this->actingAs($this->member(BillingAccessState::Restricted))
            ->get('/dashboard')
            ->assertRedirect(route('billing.restricted'));
    }

    public function test_a_member_of_a_suspended_team_is_also_turned_away(): void
    {
        $this->actingAs($this->member(BillingAccessState::Suspended))
            ->get('/dashboard')
            ->assertRedirect(route('billing.restricted'));
    }

    /**
     * `past_due` is the 21-day grace window: the team works normally while
     * the platform retries. Restricting here would take a paying customer
     * offline on their first failed charge.
     */
    public function test_a_past_due_team_still_works_normally(): void
    {
        $this->actingAs($this->member(BillingAccessState::PastDue))
            ->get('/dashboard')
            ->assertOk();
    }

    public function test_a_cancelled_team_still_works_until_its_period_ends(): void
    {
        $this->actingAs($this->member(BillingAccessState::Cancelled))
            ->get('/dashboard')
            ->assertOk();
    }

    public function test_a_member_sees_the_explanation_page(): void
    {
        $this->actingAs($this->member(BillingAccessState::Restricted))
            ->get('/billing/restricted')
            ->assertOk()
            ->assertInertia(fn (AssertableInertia $page) => $page
                ->component('billing/Restricted')
                ->where('teamName', 'Acme Logistics')
            );
    }

    public function test_an_owner_sees_the_recovery_page_instead(): void
    {
        $this->actingAs($this->member(BillingAccessState::Restricted, TeamRole::Owner))
            ->get('/billing/restricted')
            ->assertOk()
            ->assertInertia(fn (AssertableInertia $page) => $page->component('billing/Recover'));
    }

    public function test_an_admin_sees_the_recovery_page(): void
    {
        $this->actingAs($this->member(BillingAccessState::Restricted, TeamRole::Admin))
            ->get('/billing/restricted')
            ->assertOk()
            ->assertInertia(fn (AssertableInertia $page) => $page->component('billing/Recover'));
    }

    /**
     * A manager is not a billing role. The spec names Owner and Admin as the
     * roles that may manage billing, and they are the same two that recover.
     */
    public function test_a_manager_sees_the_member_page_not_the_recovery_page(): void
    {
        $this->actingAs($this->member(BillingAccessState::Restricted, TeamRole::Manager))
            ->get('/billing/restricted')
            ->assertOk()
            ->assertInertia(fn (AssertableInertia $page) => $page->component('billing/Restricted'));
    }

    public function test_a_restricted_team_can_still_log_out(): void
    {
        $this->actingAs($this->member(BillingAccessState::Restricted))
            ->post('/logout')
            ->assertRedirect();
    }

    public function test_an_api_request_from_a_restricted_team_gets_402_not_a_redirect(): void
    {
        $this->actingAs($this->member(BillingAccessState::Restricted))
            ->getJson('/api/v1/files/uploads')
            ->assertStatus(402)
            ->assertJsonStructure(['message']);
    }

    public function test_a_user_with_no_team_is_not_caught_by_the_middleware(): void
    {
        $user = User::factory()->create(['current_team_id' => null]);

        $this->actingAs($user)->get('/dashboard')->assertRedirect();

        $this->assertNotSame(route('billing.restricted'), url()->previous());
    }

    /**
     * A superadmin must be able to run the console while their own team is
     * restricted — otherwise restriction locks out the only person who can
     * lift it.
     */
    public function test_a_superadmin_still_reaches_the_console(): void
    {
        $user = $this->member(BillingAccessState::Restricted);
        $user->forceFill(['superAdmin' => true])->save();

        $this->actingAs($user->refresh())
            ->get('/superadmin/billing')
            ->assertOk();
    }
}

<?php

namespace App\Http\Middleware;

use App\Support\Billing\Entitlements;
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

/**
 * Holds a restricted team out of the application (design doc, "Restriction").
 *
 * Registered globally on the `web` and `api` stacks rather than on each
 * module's route group. Thirty-six route files apply `EnsureTeamMembership`;
 * a second middleware on each is thirty-six chances to miss one, and a missed
 * one is a module that stays reachable while restricted, silently and
 * forever. `EnforceForcedLogout` and `EnforcePasswordChange` are registered
 * the same way for the same reason.
 *
 * The decision is `Entitlements::for($team)->grantsAppAccess()` — never a
 * list of states re-spelled here. `BillingAccessState` owns that question,
 * and a second copy is how `suspended` ends up remembered in one place and
 * forgotten in the other.
 */
class EnsureTeamNotRestricted
{
    /**
     * Routes a restricted team must still reach, or it could never leave,
     * pay, or find out why.
     *
     * @var array<int, string>
     */
    private const ALLOWED_ROUTES = [
        'billing.restricted',
        'billing.recover',
        'logout',
        'login',
        'password.confirm',
        'password.confirm.store',
        'password.confirmation',
        'verification.notice',
        'verification.verify',
        'verification.send',
        'superadmin.impersonate.stop',
    ];

    /**
     * @param  Closure(Request): (Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        $user = $request->user();

        if (! $user) {
            return $next($request);
        }

        // A superadmin must be able to run the console while their own team is
        // restricted — otherwise restriction locks out the only person who can
        // lift it. While impersonating, the acting user is the impersonated
        // one, who is not a superadmin, so the restriction is seen exactly as
        // that user sees it.
        if ($user->superAdmin === true) {
            return $next($request);
        }

        $team = $user->currentTeam;

        if (! $team || Entitlements::for($team)->grantsAppAccess()) {
            return $next($request);
        }

        $routeName = $request->route()?->getName();

        if ($routeName !== null && in_array($routeName, self::ALLOWED_ROUTES, true)) {
            return $next($request);
        }

        if ($request->expectsJson()) {
            abort(402, __('This organization\'s account is restricted.'));
        }

        return redirect()->route('billing.restricted');
    }
}

            // Restriction has to apply to every authenticated page for the
            // same reason the two above do: 36 route files apply
            // `EnsureTeamMembership`, and a restriction middleware added to
            // 35 of them is not enforcement, it is a gap nobody finds until a
            // customer uses it.
            EnsureTeamNotRestricted::class,

        $middleware->api(append: [
            EnsureTeamNotRestricted::class,
        ]);

<?php

namespace App\Http\Controllers\Billing;

use App\Enums\BillingInvoiceStatus;
use App\Enums\TeamRole;
use App\Http\Controllers\Controller;
use App\Models\Billing\Invoice;
use App\Support\Billing\Money;
use Illuminate\Http\Request;
use Inertia\Inertia;
use Inertia\Response;

/**
 * What a restricted team sees instead of the application (design doc,
 * "Restriction").
 *
 * One route, two pages, chosen by role: a member gets an explanation they can
 * act on by talking to someone, an Owner or Admin gets the outstanding
 * invoices and what to do about them. Splitting them into two routes would
 * mean a member could read their organization's balance by typing the other
 * URL.
 */
class RestrictionController extends Controller
{
    public function show(Request $request): Response
    {
        $user = $request->user();
        $team = $user->currentTeam;

        $role = $user->teamRole($team);

        $canRecover = $role !== null
            && in_array($role, [TeamRole::Owner, TeamRole::Admin], true);

        if (! $canRecover) {
            return Inertia::render('billing/Restricted', [
                'teamName' => $team->name,
            ])->rootView('auth');
        }

        $invoices = Invoice::query()
            ->where('team_id', $team->id)
            ->whereIn('status', BillingInvoiceStatus::outstandingValues())
            ->with('payments')
            ->orderBy('period_start')
            ->get()
            ->map(fn (Invoice $invoice) => [
                'id' => $invoice->id,
                'number' => $invoice->number,
                'period_start' => $invoice->period_start?->toDateString(),
                'period_end' => $invoice->period_end?->toDateString(),
                'total' => Money::format($invoice->total_cents, $invoice->currency),
                'amount_due' => Money::format($invoice->amountDueCents(), $invoice->currency),
            ])
            ->values()
            ->all();

        return Inertia::render('billing/Recover', [
            'teamName' => $team->name,
            'billingEmail' => $team->billing_email,
            'invoices' => $invoices,
        ])->rootView('auth');
    }
}

<?php

use App\Http\Controllers\Billing\RestrictionController;
use Illuminate\Support\Facades\Route;

/**
 * The only part of the application a restricted team can reach (design doc,
 * "Restriction"). Deliberately behind `auth` alone — NOT
 * `EnsureTeamMembership`, and reachable while `EnsureTeamNotRestricted` is
 * turning every other route away, because a restricted team that could not
 * reach this page would see nothing but a redirect loop.
 */
Route::middleware(['auth'])->prefix('billing')->name('billing.')->group(function () {
    Route::get('restricted', [RestrictionController::class, 'show'])->name('restricted');
});

<script setup lang="ts">
/**
 * Shown to a member whose organization's billing account is restricted.
 *
 * Deliberately carries no figures: a member cannot settle an invoice, and
 * their organization's balance is not their business. They get the one fact
 * they can act on — who to talk to.
 */
import { Head, Link } from '@inertiajs/vue3';
import { logout } from '@/routes';

defineProps<{
    teamName: string;
}>();

defineOptions({
    layout: {
        title: 'Account restricted',
        description: 'This organization’s account needs attention',
    },
});
</script>

<template>
    <Head title="Account restricted" />

    <div class="text-center w-100">
        <p class="text-gray-700 mb-8">
            <span class="fw-semibold">{{ teamName }}</span> is temporarily restricted while its account is brought up to date. Your work and
            everything you created are safe — an owner or administrator of this organization can restore access.
        </p>

        <Link :href="logout()" method="post" as="button" class="btn btn-light-primary">Sign out</Link>
    </div>
</template>

<script setup lang="ts">
/**
 * Shown to an Owner or Admin whose organization is restricted.
 *
 * In increment 3 this page explains and lists; it does not take a card.
 * Self-serve payment is increment 4, and a button that appears to charge and
 * does not would be worse than none.
 */
import { Head, Link } from '@inertiajs/vue3';
import { logout } from '@/routes';
import type { BillingRecoverInvoice } from '@/types';

defineProps<{
    teamName: string;
    billingEmail: string | null;
    invoices: BillingRecoverInvoice[];
}>();

defineOptions({
    layout: {
        title: 'Account restricted',
        description: 'Settle the outstanding balance to restore access',
    },
});
</script>

<template>
    <Head title="Account restricted" />

    <div class="w-100">
        <p class="text-gray-700 mb-6">
            <span class="fw-semibold">{{ teamName }}</span> is restricted until its outstanding balance is settled. Everything your team created is
            safe and will be available again as soon as the account is up to date.
        </p>

        <div v-if="invoices.length" class="card mb-6">
            <div class="card-header">
                <h3 class="card-title">Outstanding invoices</h3>
            </div>
            <div class="card-body">
                <div class="table-responsive">
                    <table class="table align-middle">
                        <thead>
                            <tr class="fw-semibold text-muted">
                                <th>Invoice</th>
                                <th>Period</th>
                                <th class="text-end">Total</th>
                                <th class="text-end">Due</th>
                            </tr>
                        </thead>
                        <tbody>
                            <tr v-for="invoice in invoices" :key="invoice.id">
                                <td>{{ invoice.number ?? 'Draft' }}</td>
                                <td>{{ invoice.period_start }} – {{ invoice.period_end }}</td>
                                <td class="text-end">{{ invoice.total }}</td>
                                <td class="text-end fw-semibold">{{ invoice.amount_due }}</td>
                            </tr>
                        </tbody>
                    </table>
                </div>
            </div>
        </div>

        <p class="text-muted mb-8">
            To settle the balance, contact us<span v-if="billingEmail"> — we’ll reply to {{ billingEmail }}</span>. Online payment is coming soon.
        </p>

        <Link :href="logout()" method="post" as="button" class="btn btn-light-primary">Sign out</Link>
    </div>
</template>

export type BillingRecoverInvoice = {
    id: number;
    number: string | null;
    period_start: string | null;
    period_end: string | null;
    total: string;
    amount_due: string;
};

herd php artisan wayfinder:generate --with-form
npm run build
herd php -d memory_limit=2G artisan test --compact tests/Feature/Billing/RestrictedAccessTest.php

herd php -d memory_limit=2G artisan test --compact tests/Feature/Billing tests/Unit/Billing tests/Feature/SuperAdmin
herd php -d memory_limit=1G vendor/bin/phpstan analyse app/Http/Middleware app/Http/Controllers/Billing app/Support/Billing --no-progress
vendor/bin/pint --dirty --format agent
npm run format && npm run lint
git add <the paths above> && git commit -m "Billing: hold a restricted team out of the application"

public function test_recurring_tasks_generate_for_a_team_with_access(): void
{
    // ... seed an active team + a due schedule-mode recurrence
    $this->artisan('tasks:generate-recurring-occurrences')->assertSuccessful();
    // assert the occurrence row exists
}

public function test_recurring_tasks_do_not_generate_for_a_restricted_team(): void
{
    // ... same seed, billing_access_state = restricted
    $this->artisan('tasks:generate-recurring-occurrences')->assertSuccessful();
    // assert no occurrence row was created
}

Team::query()->withAppAccess()

->whereHas('team', fn (Builder $query) => $query->withAppAccess())

herd php -d memory_limit=2G artisan test --compact tests/Feature/Billing tests/Unit/Billing tests/Feature/SuperAdmin
herd php -d memory_limit=1G vendor/bin/phpstan analyse app/Console/Commands app/Models --no-progress
vendor/bin/pint --dirty --format agent
git add <paths> && git commit -m "Billing: stop generating work a restricted team cannot act on"