<?php

namespace Tests\Feature\Billing;

use App\Models\Team;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Schema;
use Laravel\Cashier\Billable;
use Laravel\Cashier\Cashier;
use Tests\TestCase;

/**
 * Cashier replaces the dormant Spark 1.x schema from 2016, and bills the
 * team rather than the user (design doc "Package choice").
 */
class CashierInstallationTest extends TestCase
{
    use RefreshDatabase;

    public function test_the_dormant_spark_tables_are_dropped(): void
    {
        $this->assertFalse(Schema::hasTable('team_subscriptions'));
        $this->assertFalse(Schema::hasTable('invoices'));
    }

    public function test_cashier_owns_the_subscriptions_tables_and_keys_them_on_the_team(): void
    {
        $this->assertTrue(Schema::hasTable('subscriptions'));
        $this->assertTrue(Schema::hasColumn('subscriptions', 'team_id'));
        $this->assertTrue(Schema::hasColumn('subscriptions', 'stripe_status'));
        $this->assertTrue(Schema::hasTable('subscription_items'));
    }

    public function test_the_team_is_the_billable_model(): void
    {
        $this->assertSame(Team::class, Cashier::$customerModel);
        $this->assertContains(Billable::class, class_uses_recursive(Team::class));
    }

    public function test_a_team_starts_with_no_stripe_customer(): void
    {
        $team = Team::factory()->create(['name' => 'Acme Logistics']);

        $this->assertFalse($team->hasStripeId());
        $this->assertCount(0, $team->subscriptions);
    }
}

herd php /Applications/MAMP/bin/php/composer require laravel/cashier "^16.8"
herd php artisan vendor:publish --tag=cashier-config
herd php artisan vendor:publish --tag=cashier-migrations

rm database/migrations/2026_*_create_customer_columns.php
mv database/migrations/2026_*_create_subscriptions_table.php \
   database/migrations/2026_09_09_100200_create_subscriptions_table.php
mv database/migrations/2026_*_create_subscription_items_table.php \
   database/migrations/2026_09_09_100300_create_subscription_items_table.php

ls database/migrations | grep create_subscription

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Support\Facades\Schema;

/**
 * Retires the dormant Laravel Spark 1.x schema from 2016.
 *
 * Nothing in `app/`, `routes/`, `resources/js/`, `tests/` or
 * `database/seeders/` reads any of these tables, and there are no
 * self-service customers on the platform, so no data is lost. Dropping
 * `subscriptions` in particular is what frees the name for Cashier's own
 * stock table, which is recreated by the migration immediately after this
 * one. `App\Models\Enterprise\Invoice` is a MongoDB model on
 * `enterprises_invoices` and is unrelated to the `invoices` table here.
 */
return new class extends Migration
{
    public function up(): void
    {
        Schema::dropIfExists('team_subscriptions');
        Schema::dropIfExists('subscriptions');
        Schema::dropIfExists('invoices');
    }

    /**
     * Deliberately irreversible. Recreating empty copies of a dead schema
     * would collide with Cashier's own `subscriptions` table.
     */
    public function down(): void
    {
        //
    }
};

'model' => env('CASHIER_MODEL', App\Models\Team::class),

use Laravel\Cashier\Billable;

    /** @use HasFactory<TeamFactory> */
    use Billable, GeneratesUniqueTeamSlugs, HasFactory, SoftDeletes;

Cashier::useCustomerModel(Team::class);

STRIPE_KEY=
STRIPE_SECRET=
STRIPE_WEBHOOK_SECRET=
CASHIER_CURRENCY=usd
CASHIER_MODEL="App\Models\Team"

vendor/bin/pint --dirty --format agent
git add composer.json composer.lock config/cashier.php database/migrations app/Models/Team.php app/Providers/AppServiceProvider.php .env.example tests/Feature/Billing/CashierInstallationTest.php
git commit -m "Billing: install Cashier and retire the dormant Spark schema"

<?php

namespace Tests\Feature\Billing;

use App\Enums\TeamRole;
use App\Models\Team;
use App\Models\User;
use Tests\TestCase;

/**
 * Shared setup for the billing suite. Every helper builds real rows with
 * explicit, realistic data — this codebase deliberately has no factories
 * beyond the starter kit's Team/User/TeamInvitation ones.
 */
abstract class BillingTestCase extends TestCase
{
    /**
     * @param  array<string, mixed>  $attributes
     */
    protected function team(array $attributes = []): Team
    {
        return Team::factory()->create(array_merge(['name' => 'Acme Logistics'], $attributes));
    }

    /**
     * A user holding an active membership of the given team, with the
     * personal team the factory creates removed so it cannot compete as a
     * second membership.
     */
    protected function member(Team $team, TeamRole $role = TeamRole::Member): User
    {
        $user = User::factory()->create();
        $user->teamMemberships()->delete();

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

        return $user->refresh();
    }
}

<?php

namespace Tests\Feature\Billing;

use App\Enums\BillingAccessState;
use App\Enums\BillingType;
use App\Enums\TeamRole;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Schema;

/**
 * The billing state columns on `teams` (design doc "Schema").
 */
class TeamBillingColumnsTest extends BillingTestCase
{
    use RefreshDatabase;

    public function test_the_dead_spark_columns_are_gone(): void
    {
        foreach ([
            'current_billing_plan', 'card_brand', 'card_last_four', 'card_country',
            'billing_address', 'billing_address_line_2', 'billing_city',
            'billing_state', 'billing_zip', 'billing_country', 'vat_id',
            'extra_billing_information', 'subscriptiontype',
        ] as $column) {
            $this->assertFalse(Schema::hasColumn('teams', $column), "teams.{$column} should have been dropped");
        }
    }

    public function test_cashier_still_has_the_columns_it_needs(): void
    {
        foreach (['stripe_id', 'trial_ends_at', 'pm_type', 'pm_last_four'] as $column) {
            $this->assertTrue(Schema::hasColumn('teams', $column), "teams.{$column} is required by Cashier");
        }
    }

    public function test_a_team_defaults_to_an_active_enterprise_plan(): void
    {
        $team = $this->team();

        $this->assertSame(BillingType::Enterprise, $team->billing_type);
        $this->assertSame(BillingAccessState::Active, $team->billing_access_state);
        $this->assertNull($team->billing_seat_cap);
        $this->assertNull($team->billing_storage_quota_bytes);
        $this->assertSame(0, $team->billing_storage_used_bytes);
    }

    public function test_the_billing_columns_round_trip_through_their_casts(): void
    {
        $team = $this->team();

        $team->forceFill([
            'billing_type' => BillingType::SelfServe,
            'billing_access_state' => BillingAccessState::PastDue,
            'billing_cycle' => 'yearly',
            'billing_email' => '[email protected]',
            'billing_grace_ends_at' => '2026-10-01 00:00:00',
            'billing_seat_cap' => 25,
            'billing_storage_quota_bytes' => 53687091200,
            'billing_enterprise_amount_cents' => 450000,
            'billing_renewal_at' => '2027-01-01',
            'billing_notes' => 'Renewal handled by the account manager.',
        ])->save();

        $team->refresh();

        $this->assertSame(BillingType::SelfServe, $team->billing_type);
        $this->assertSame(BillingAccessState::PastDue, $team->billing_access_state);
        $this->assertSame('[email protected]', $team->billing_email);
        $this->assertSame('2026-10-01', $team->billing_grace_ends_at->toDateString());
        $this->assertSame(25, $team->billing_seat_cap);
        $this->assertSame(53687091200, $team->billing_storage_quota_bytes);
        $this->assertSame(450000, $team->billing_enterprise_amount_cents);
        $this->assertSame('2027-01-01', $team->billing_renewal_at->toDateString());
    }

    public function test_access_states_declare_whether_they_grant_app_access(): void
    {
        $this->assertTrue(BillingAccessState::Trialing->grantsAppAccess());
        $this->assertTrue(BillingAccessState::Active->grantsAppAccess());
        $this->assertTrue(BillingAccessState::PastDue->grantsAppAccess());
        $this->assertTrue(BillingAccessState::Cancelled->grantsAppAccess());
        $this->assertFalse(BillingAccessState::Restricted->grantsAppAccess());
        $this->assertFalse(BillingAccessState::Suspended->grantsAppAccess());
    }

    public function test_only_self_serve_teams_are_billable_through_stripe(): void
    {
        $this->assertTrue(BillingType::SelfServe->isBillable());
        $this->assertFalse(BillingType::Enterprise->isBillable());
        $this->assertFalse(BillingType::Internal->isBillable());
    }

    public function test_the_seat_count_is_active_memberships_including_the_owner(): void
    {
        $team = $this->team();
        $this->member($team, TeamRole::Owner);
        $this->member($team, TeamRole::Admin);
        $deactivated = $this->member($team, TeamRole::Member);
        $team->members()->updateExistingPivot($deactivated->id, ['status' => 0]);

        $this->assertSame(2, $team->fresh()->activeSeatCount());
    }
}

<?php

namespace App\Enums;

/**
 * How a team's plan is administered (design doc "Commercial rules").
 */
enum BillingType: string
{
    case SelfServe = 'self_serve';
    case Enterprise = 'enterprise';
    case Internal = 'internal';

    /**
     * Whether this team is charged through Stripe. Enterprise teams pay
     * offline against manually issued invoices, and internal teams (demo,
     * sales, QA, staging) are never billed at all.
     */
    public function isBillable(): bool
    {
        return $this === self::SelfServe;
    }

    public function label(): string
    {
        return match ($this) {
            self::SelfServe => 'Self-serve',
            self::Enterprise => 'Enterprise',
            self::Internal => 'Internal',
        };
    }
}

<?php

namespace App\Enums;

/**
 * Where a team sits in the billing lifecycle (design doc "Access state
 * machine"). `PastDue` deliberately still grants access — it is the 21-day
 * grace window, during which the team works normally while the platform
 * retries payment daily.
 */
enum BillingAccessState: string
{
    case Trialing = 'trialing';
    case Active = 'active';
    case PastDue = 'past_due';
    case Restricted = 'restricted';
    case Cancelled = 'cancelled';
    case Suspended = 'suspended';

    /**
     * Whether members of a team in this state may still use the application.
     * `Cancelled` means "cancelled but paid until the period ends"; the
     * transition to `Restricted` is what actually removes access.
     */
    public function grantsAppAccess(): bool
    {
        return match ($this) {
            self::Trialing, self::Active, self::PastDue, self::Cancelled => true,
            self::Restricted, self::Suspended => false,
        };
    }

    public function label(): string
    {
        return match ($this) {
            self::Trialing => 'Trialing',
            self::Active => 'Active',
            self::PastDue => 'Past due',
            self::Restricted => 'Restricted',
            self::Cancelled => 'Cancelled',
            self::Suspended => 'Suspended',
        };
    }
}

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

/**
 * Billing state on `teams`, flattened onto the tenant root table by explicit
 * decision rather than living in a 1:1 side table.
 *
 * `billing_type` and `billing_access_state` default to `enterprise` / `active`,
 * which is what puts every team already on the platform onto a manually
 * managed enterprise plan — adding a column with a default backfills every
 * existing row, so no separate data migration is needed. Increment 4
 * (self-serve subscription) is what changes these defaults; until then no
 * team can land in a self-serve state that nothing manages yet.
 *
 * `billing_access_state` is deliberately not called `billing_state` — the
 * name is free now that the legacy Spark address column is dropped, but
 * reusing it would read as an address field.
 */
return new class extends Migration
{
    public function up(): void
    {
        Schema::table('teams', function (Blueprint $table) {
            $table->dropColumn([
                'current_billing_plan', 'card_brand', 'card_last_four', 'card_country',
                'billing_address', 'billing_address_line_2', 'billing_city',
                'billing_state', 'billing_zip', 'billing_country', 'vat_id',
                'extra_billing_information', 'subscriptiontype',
            ]);
        });

        Schema::table('teams', function (Blueprint $table) {
            $table->string('pm_type')->nullable();
            $table->string('pm_last_four', 4)->nullable();

            $table->string('billing_type', 20)->default('enterprise')->index();
            $table->string('billing_cycle', 10)->nullable();
            $table->string('billing_access_state', 20)->default('active')->index();
            $table->string('billing_email')->nullable();

            $table->timestamp('billing_grace_ends_at')->nullable();
            $table->timestamp('billing_restricted_at')->nullable();
            $table->timestamp('billing_current_period_ends_at')->nullable();

            $table->unsignedInteger('billing_seat_cap')->nullable();
            $table->unsignedBigInteger('billing_storage_quota_bytes')->nullable();
            $table->unsignedBigInteger('billing_storage_used_bytes')->default(0);
            $table->timestamp('billing_storage_calculated_at')->nullable();

            $table->unsignedBigInteger('billing_enterprise_amount_cents')->nullable();
            $table->string('billing_enterprise_interval', 10)->nullable();
            $table->date('billing_renewal_at')->nullable();

            $table->text('billing_notes')->nullable();
        });
    }

    public function down(): void
    {
        Schema::table('teams', function (Blueprint $table) {
            $table->dropColumn([
                'pm_type', 'pm_last_four',
                'billing_type', 'billing_cycle', 'billing_access_state', 'billing_email',
                'billing_grace_ends_at', 'billing_restricted_at', 'billing_current_period_ends_at',
                'billing_seat_cap', 'billing_storage_quota_bytes',
                'billing_storage_used_bytes', 'billing_storage_calculated_at',
                'billing_enterprise_amount_cents', 'billing_enterprise_interval',
                'billing_renewal_at', 'billing_notes',
            ]);
        });
    }
};

use App\Enums\BillingAccessState;
use App\Enums\BillingType;

    protected function casts(): array
    {
        return [
            'is_personal' => 'boolean',
            'modulesAllowed' => 'array',
            'trial_ends_at' => 'datetime',
            'billing_type' => BillingType::class,
            'billing_access_state' => BillingAccessState::class,
            'billing_grace_ends_at' => 'datetime',
            'billing_restricted_at' => 'datetime',
            'billing_current_period_ends_at' => 'datetime',
            'billing_seat_cap' => 'integer',
            'billing_storage_quota_bytes' => 'integer',
            'billing_storage_used_bytes' => 'integer',
            'billing_storage_calculated_at' => 'datetime',
            'billing_enterprise_amount_cents' => 'integer',
            'billing_renewal_at' => 'date',
        ];
    }

    /**
     * The number of billable seats this team occupies: every active
     * membership, the owner included. Pending invitations are not counted
     * until they are accepted.
     */
    public function activeSeatCount(): int
    {
        return $this->activeMembers()->count();
    }

vendor/bin/pint --dirty --format agent
git add app/Enums/BillingType.php app/Enums/BillingAccessState.php database/migrations app/Models/Team.php tests/Feature/Billing
git commit -m "Billing: add billing state columns and enums to teams"

<?php

namespace Tests\Feature\Billing;

use App\Enums\BillingProductType;
use App\Models\Billing\Product;
use Illuminate\Foundation\Testing\RefreshDatabase;

/**
 * The priced-item catalog (design doc "New tables (all MySQL)").
 */
class BillingProductCatalogTest extends BillingTestCase
{
    use RefreshDatabase;

    protected function setUp(): void
    {
        parent::setUp();

        Product::flushCache();
    }

    protected function tearDown(): void
    {
        Product::flushCache();

        parent::tearDown();
    }

    public function test_the_seeder_registers_the_seat_and_both_specialized_modules(): void
    {
        $this->seed(\Database\Seeders\BillingProductsSeeder::class);

        $seat = Product::where('key', 'seat')->firstOrFail();
        $this->assertSame(BillingProductType::Seat, $seat->type);
        $this->assertSame(1000, $seat->unit_amount_cents);
        $this->assertNull($seat->module_key);

        $threePl = Product::where('key', 'module.logistics3p')->firstOrFail();
        $this->assertSame(BillingProductType::Module, $threePl->type);
        $this->assertSame('logistics3p', $threePl->module_key);
        $this->assertSame(75000, $threePl->unit_amount_cents);

        $depot = Product::where('key', 'module.containers')->firstOrFail();
        $this->assertSame('containers', $depot->module_key);
        $this->assertSame(75000, $depot->unit_amount_cents);
    }

    public function test_the_seeder_is_idempotent(): void
    {
        $this->seed(\Database\Seeders\BillingProductsSeeder::class);
        $this->seed(\Database\Seeders\BillingProductsSeeder::class);

        $this->assertSame(3, Product::count());
    }

    public function test_the_specialized_module_keys_are_the_active_module_products(): void
    {
        $this->seed(\Database\Seeders\BillingProductsSeeder::class);

        $this->assertEqualsCanonicalizing(['logistics3p', 'containers'], Product::specializedModuleKeys());
    }

    public function test_a_deactivated_module_product_stops_being_specialized(): void
    {
        $this->seed(\Database\Seeders\BillingProductsSeeder::class);
        Product::where('key', 'module.containers')->update(['is_active' => false]);
        Product::flushCache();

        $this->assertSame(['logistics3p'], Product::specializedModuleKeys());
    }

    public function test_the_seat_product_is_reachable_by_helper(): void
    {
        $this->seed(\Database\Seeders\BillingProductsSeeder::class);

        $this->assertSame('seat', Product::seat()?->key);
    }
}

<?php

namespace App\Enums;

/**
 * What kind of priced thing a `billing_products` row represents. `Storage`
 * has no rows yet — paid storage packs are deferred, and this case is the
 * slot they will occupy.
 */
enum BillingProductType: string
{
    case Seat = 'seat';
    case Module = 'module';
    case Storage = 'storage';
}

<?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('billing_products', function (Blueprint $table) {
            $table->id();
            $table->string('key')->unique();
            $table->string('name');
            $table->string('type', 20)->index();
            $table->string('module_key')->nullable()->index();
            $table->string('stripe_price_monthly')->nullable();
            $table->string('stripe_price_yearly')->nullable();
            $table->unsignedBigInteger('unit_amount_cents');
            $table->boolean('is_active')->default(true)->index();
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('billing_products');
    }
};

<?php

namespace App\Models\Billing;

use App\Enums\BillingProductType;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Carbon;

/**
 * A priced item in the catalog: a seat, or a specialized module.
 *
 * Platform-level data, deliberately not tenant-scoped — the superadmin
 * console reads it across every team, so `BelongsToOrganization` would hide
 * it.
 *
 * @property int $id
 * @property string $key
 * @property string $name
 * @property BillingProductType $type
 * @property string|null $module_key
 * @property string|null $stripe_price_monthly
 * @property string|null $stripe_price_yearly
 * @property int $unit_amount_cents
 * @property bool $is_active
 * @property Carbon|null $created_at
 * @property Carbon|null $updated_at
 */
class Product extends Model
{
    protected $table = 'billing_products';

    protected $guarded = [];

    protected $casts = [
        'type' => BillingProductType::class,
        'unit_amount_cents' => 'integer',
        'is_active' => 'boolean',
        'created_at' => 'datetime',
        'updated_at' => 'datetime',
    ];

    /**
     * Memoised per request. Every module-visibility check consults this, so
     * it must not cost a query per module.
     *
     * @var array<int, string>|null
     */
    private static ?array $specializedModuleKeys = null;

    /**
     * The module keys that cost extra — everything else is a standard module
     * included with any plan.
     *
     * @return array<int, string>
     */
    public static function specializedModuleKeys(): array
    {
        return self::$specializedModuleKeys ??= self::query()
            ->where('type', BillingProductType::Module)
            ->where('is_active', true)
            ->whereNotNull('module_key')
            ->pluck('module_key')
            ->all();
    }

    /**
     * Clear the per-request memo. Static caches survive across tests in one
     * process, so the billing suite flushes this in `setUp()`.
     */
    public static function flushCache(): void
    {
        self::$specializedModuleKeys = null;
    }

    public static function seat(): ?self
    {
        return self::query()->where('key', 'seat')->first();
    }
}

<?php

namespace Database\Seeders;

use App\Enums\BillingProductType;
use App\Models\Billing\Product;
use Illuminate\Database\Seeder;

/**
 * The priced-item catalog. Stripe Price ids are environment-specific and are
 * filled in by an operator after the Prices are created in Stripe, so they
 * are left null here rather than seeded with placeholder ids that would look
 * real and silently fail at charge time.
 */
class BillingProductsSeeder extends Seeder
{
    public function run(): void
    {
        $products = [
            [
                'key' => 'seat',
                'name' => 'User seat',
                'type' => BillingProductType::Seat->value,
                'module_key' => null,
                'unit_amount_cents' => 1000,
            ],
            [
                'key' => 'module.logistics3p',
                'name' => '3PL',
                'type' => BillingProductType::Module->value,
                'module_key' => 'logistics3p',
                'unit_amount_cents' => 75000,
            ],
            [
                'key' => 'module.containers',
                'name' => 'Container Depot',
                'type' => BillingProductType::Module->value,
                'module_key' => 'containers',
                'unit_amount_cents' => 75000,
            ],
        ];

        foreach ($products as $product) {
            Product::updateOrCreate(
                ['key' => $product['key']],
                [
                    'name' => $product['name'],
                    'type' => $product['type'],
                    'module_key' => $product['module_key'],
                    'unit_amount_cents' => $product['unit_amount_cents'],
                    'is_active' => true,
                ],
            );
        }
    }
}

vendor/bin/pint --dirty --format agent
git add app/Enums/BillingProductType.php app/Models/Billing/Product.php database/migrations database/seeders tests/Feature/Billing
git commit -m "Billing: add the priced-item catalog"

<?php

namespace Tests\Feature\Billing;

use App\Models\Billing\Product;
use App\Models\Billing\TeamModule;
use Database\Seeders\BillingProductsSeeder;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Carbon;

/**
 * Which specialized modules a team holds, and until when (design doc
 * "Module changes").
 */
class TeamModuleHoldingTest extends BillingTestCase
{
    use RefreshDatabase;

    protected function setUp(): void
    {
        parent::setUp();

        Product::flushCache();
        $this->seed(BillingProductsSeeder::class);
    }

    protected function tearDown(): void
    {
        Product::flushCache();
        Carbon::setTestNow();

        parent::tearDown();
    }

    public function test_an_open_ended_holding_is_active(): void
    {
        $team = $this->team();
        TeamModule::create([
            'team_id' => $team->id,
            'billing_product_id' => Product::where('key', 'module.logistics3p')->value('id'),
            'starts_at' => '2026-09-01 00:00:00',
            'ends_at' => null,
        ]);

        Carbon::setTestNow('2026-09-15 12:00:00');

        $this->assertSame(['logistics3p'], TeamModule::activeModuleKeysFor($team));
    }

    public function test_a_holding_scheduled_to_end_stays_active_until_that_moment(): void
    {
        $team = $this->team();
        TeamModule::create([
            'team_id' => $team->id,
            'billing_product_id' => Product::where('key', 'module.containers')->value('id'),
            'starts_at' => '2026-08-01 00:00:00',
            'ends_at' => '2026-10-01 00:00:00',
        ]);

        Carbon::setTestNow('2026-09-30 23:59:59');
        $this->assertSame(['containers'], TeamModule::activeModuleKeysFor($team));

        Carbon::setTestNow('2026-10-01 00:00:01');
        $this->assertSame([], TeamModule::activeModuleKeysFor($team));
    }

    public function test_a_holding_that_has_not_started_is_not_active(): void
    {
        $team = $this->team();
        TeamModule::create([
            'team_id' => $team->id,
            'billing_product_id' => Product::where('key', 'module.logistics3p')->value('id'),
            'starts_at' => '2026-11-01 00:00:00',
            'ends_at' => null,
        ]);

        Carbon::setTestNow('2026-09-15 12:00:00');

        $this->assertSame([], TeamModule::activeModuleKeysFor($team));
    }

    public function test_holdings_belong_to_their_team_and_product(): void
    {
        $team = $this->team();
        $holding = TeamModule::create([
            'team_id' => $team->id,
            'billing_product_id' => Product::where('key', 'module.logistics3p')->value('id'),
            'starts_at' => '2026-09-01 00:00:00',
        ]);

        $this->assertSame($team->id, $holding->team->id);
        $this->assertSame('module.logistics3p', $holding->product->key);
    }

    public function test_one_team_holdings_do_not_leak_into_another(): void
    {
        $acme = $this->team();
        $other = $this->team(['name' => 'Globex Freight']);
        TeamModule::create([
            'team_id' => $acme->id,
            'billing_product_id' => Product::where('key', 'module.logistics3p')->value('id'),
            'starts_at' => '2026-09-01 00:00:00',
        ]);

        Carbon::setTestNow('2026-09-15 12:00:00');

        $this->assertSame([], TeamModule::activeModuleKeysFor($other));
    }
}

<?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('billing_team_modules', function (Blueprint $table) {
            $table->id();
            $table->unsignedBigInteger('team_id');
            $table->unsignedBigInteger('billing_product_id');
            $table->string('stripe_subscription_item_id')->nullable();
            $table->timestamp('starts_at');
            $table->timestamp('ends_at')->nullable();
            $table->timestamps();

            $table->index(['team_id', 'ends_at']);
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('billing_team_modules');
    }
};

<?php

namespace App\Models\Billing;

use App\Models\Team;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Support\Carbon;
use Carbon\CarbonInterface;

/**
 * A specialized module a team holds.
 *
 * This row, not Stripe, is the authority for whether the team may reach the
 * module: dropping a module sets `ends_at` to the end of the paid period, so
 * "keeps access until the 1st" is a data fact rather than a scheduled job
 * that might not fire.
 *
 * @property int $id
 * @property int $team_id
 * @property int $billing_product_id
 * @property string|null $stripe_subscription_item_id
 * @property Carbon $starts_at
 * @property Carbon|null $ends_at
 * @property Carbon|null $created_at
 * @property Carbon|null $updated_at
 * @property-read Team $team
 * @property-read Product $product
 */
class TeamModule extends Model
{
    protected $table = 'billing_team_modules';

    protected $guarded = [];

    protected $casts = [
        'team_id' => 'integer',
        'billing_product_id' => 'integer',
        'starts_at' => 'datetime',
        'ends_at' => 'datetime',
        'created_at' => 'datetime',
        'updated_at' => 'datetime',
    ];

    /**
     * @return BelongsTo<Team, $this>
     */
    public function team(): BelongsTo
    {
        return $this->belongsTo(Team::class);
    }

    /**
     * @return BelongsTo<Product, $this>
     */
    public function product(): BelongsTo
    {
        return $this->belongsTo(Product::class, 'billing_product_id');
    }

    /**
     * Holdings in force at the given moment: started, and either open-ended
     * or not yet expired.
     *
     * @param  Builder<self>  $query
     * @return Builder<self>
     */
    public function scopeActiveAt(Builder $query, CarbonInterface $moment): Builder
    {
        return $query
            ->where('starts_at', '<=', $moment)
            ->where(function (Builder $query) use ($moment) {
                $query->whereNull('ends_at')->orWhere('ends_at', '>', $moment);
            });
    }

    /**
     * The module keys this team may currently reach through its holdings.
     *
     * @return array<int, string>
     */
    public static function activeModuleKeysFor(Team $team, ?CarbonInterface $moment = null): array
    {
        return self::query()
            ->where('team_id', $team->id)
            ->activeAt($moment ?? Carbon::now())
            ->join('billing_products', 'billing_products.id', '=', 'billing_team_modules.billing_product_id')
            ->where('billing_products.is_active', true)
            ->whereNotNull('billing_products.module_key')
            ->pluck('billing_products.module_key')
            ->all();
    }
}

vendor/bin/pint --dirty --format agent
git add app/Models/Billing/TeamModule.php database/migrations tests/Feature/Billing
git commit -m "Billing: record which specialized modules a team holds"

<?php

namespace Tests\Feature\Billing;

use App\Enums\BillingInvoiceLineKind;
use App\Enums\BillingInvoiceSource;
use App\Enums\BillingInvoiceStatus;
use App\Enums\BillingPaymentMethod;
use App\Enums\TeamRole;
use App\Models\Billing\Invoice;
use App\Models\Billing\InvoiceLine;
use App\Models\Billing\Payment;
use Illuminate\Foundation\Testing\RefreshDatabase;

/**
 * Invoices, their lines, and the payments settling them (design doc
 * "New tables (all MySQL)" and "Enterprise plans").
 */
class BillingInvoiceTest extends BillingTestCase
{
    use RefreshDatabase;

    public function test_a_manual_enterprise_invoice_carries_its_lines(): void
    {
        $team = $this->team();

        $invoice = Invoice::create([
            'team_id' => $team->id,
            'number' => 'INV-2026-0001',
            'source' => BillingInvoiceSource::Manual,
            'period_start' => '2026-09-01',
            'period_end' => '2026-09-30',
            'subtotal_cents' => 450000,
            'total_cents' => 450000,
            'currency' => 'usd',
            'status' => BillingInvoiceStatus::Open,
            'issued_at' => '2026-09-01 09:00:00',
            'due_at' => '2026-09-15 09:00:00',
        ]);

        InvoiceLine::create([
            'billing_invoice_id' => $invoice->id,
            'kind' => BillingInvoiceLineKind::Module,
            'description' => '3PL — September 2026',
            'quantity' => 1,
            'unit_amount_cents' => 375000,
            'amount_cents' => 375000,
        ]);

        InvoiceLine::create([
            'billing_invoice_id' => $invoice->id,
            'kind' => BillingInvoiceLineKind::Usage,
            'description' => 'SMS — August 2026',
            'quantity' => 1500,
            'unit_amount_cents' => 50,
            'amount_cents' => 75000,
        ]);

        $invoice->refresh();

        $this->assertCount(2, $invoice->lines);
        $this->assertSame(450000, $invoice->lines->sum('amount_cents'));
        $this->assertNull($invoice->stripe_invoice_id);
        $this->assertSame(BillingInvoiceSource::Manual, $invoice->source);
    }

    public function test_an_offline_payment_settles_an_invoice(): void
    {
        $team = $this->team();
        $admin = $this->member($team, TeamRole::Admin);

        $invoice = Invoice::create([
            'team_id' => $team->id,
            'number' => 'INV-2026-0002',
            'source' => BillingInvoiceSource::Manual,
            'period_start' => '2026-09-01',
            'period_end' => '2026-09-30',
            'subtotal_cents' => 450000,
            'total_cents' => 450000,
            'currency' => 'usd',
            'status' => BillingInvoiceStatus::Open,
            'issued_at' => '2026-09-01 09:00:00',
        ]);

        Payment::create([
            'team_id' => $team->id,
            'billing_invoice_id' => $invoice->id,
            'method' => BillingPaymentMethod::BankTransfer,
            'amount_cents' => 450000,
            'paid_at' => '2026-09-12 14:30:00',
            'reference' => 'SWIFT 8842190',
            'recorded_by_user_id' => $admin->id,
            'notes' => 'Confirmed against the September statement.',
        ]);

        $invoice->refresh();

        $this->assertSame(450000, $invoice->amountPaidCents());
        $this->assertSame(0, $invoice->amountDueCents());
        $this->assertSame($admin->id, $invoice->payments->first()->recordedBy->id);
    }

    public function test_a_partially_paid_invoice_still_has_an_amount_due(): void
    {
        $team = $this->team();

        $invoice = Invoice::create([
            'team_id' => $team->id,
            'number' => 'INV-2026-0003',
            'source' => BillingInvoiceSource::Manual,
            'period_start' => '2026-09-01',
            'period_end' => '2026-09-30',
            'subtotal_cents' => 450000,
            'total_cents' => 450000,
            'currency' => 'usd',
            'status' => BillingInvoiceStatus::Open,
            'issued_at' => '2026-09-01 09:00:00',
        ]);

        Payment::create([
            'team_id' => $team->id,
            'billing_invoice_id' => $invoice->id,
            'method' => BillingPaymentMethod::Cheque,
            'amount_cents' => 200000,
            'paid_at' => '2026-09-12 14:30:00',
        ]);

        $this->assertSame(250000, $invoice->refresh()->amountDueCents());
    }

    public function test_a_stripe_invoice_keeps_its_stripe_identifier(): void
    {
        $team = $this->team();

        $invoice = Invoice::create([
            'team_id' => $team->id,
            'number' => 'INV-2026-0004',
            'source' => BillingInvoiceSource::Stripe,
            'stripe_invoice_id' => 'in_1QcExAmPlE0001',
            'period_start' => '2026-09-01',
            'period_end' => '2026-09-30',
            'subtotal_cents' => 85000,
            'total_cents' => 85000,
            'currency' => 'usd',
            'status' => BillingInvoiceStatus::Paid,
            'issued_at' => '2026-09-01 00:05:00',
            'paid_at' => '2026-09-01 00:05:12',
        ]);

        $this->assertSame('in_1QcExAmPlE0001', $invoice->fresh()->stripe_invoice_id);
        $this->assertSame(BillingInvoiceStatus::Paid, $invoice->status);
    }

    public function test_a_payment_may_exist_without_an_invoice(): void
    {
        $team = $this->team();

        $payment = Payment::create([
            'team_id' => $team->id,
            'billing_invoice_id' => null,
            'method' => BillingPaymentMethod::BankTransfer,
            'amount_cents' => 100000,
            'paid_at' => '2026-09-12 14:30:00',
            'reference' => 'Advance against Q4',
        ]);

        $this->assertNull($payment->fresh()->invoice);
        $this->assertSame($team->id, $payment->team->id);
    }
}

<?php

namespace App\Enums;

/**
 * Where an invoice came from. Enterprise invoices are issued by a superadmin
 * and settled offline, so they never have a Stripe counterpart.
 */
enum BillingInvoiceSource: string
{
    case Stripe = 'stripe';
    case Manual = 'manual';
}

<?php

namespace App\Enums;

enum BillingInvoiceStatus: string
{
    case Draft = 'draft';
    case Open = 'open';
    case Paid = 'paid';
    case Void = 'void';
    case Uncollectible = 'uncollectible';

    /**
     * Whether this invoice is still expected to be paid.
     */
    public function isOutstanding(): bool
    {
        return $this === self::Open;
    }
}

<?php

namespace App\Enums;

enum BillingInvoiceLineKind: string
{
    case Seat = 'seat';
    case Module = 'module';
    case Usage = 'usage';
    case Adjustment = 'adjustment';
}

<?php

namespace App\Enums;

enum BillingPaymentMethod: string
{
    case Stripe = 'stripe';
    case BankTransfer = 'bank_transfer';
    case Cheque = 'cheque';
    case Cash = 'cash';
    case Other = 'other';

    public function label(): string
    {
        return match ($this) {
            self::Stripe => 'Stripe',
            self::BankTransfer => 'Bank transfer',
            self::Cheque => 'Cheque',
            self::Cash => 'Cash',
            self::Other => 'Other',
        };
    }
}

<?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('billing_invoices', function (Blueprint $table) {
            $table->id();
            $table->unsignedBigInteger('team_id')->index();
            $table->string('number')->unique();
            $table->string('source', 10)->index();
            $table->string('stripe_invoice_id')->nullable()->unique();
            $table->date('period_start');
            $table->date('period_end');
            $table->unsignedBigInteger('subtotal_cents');
            $table->unsignedBigInteger('total_cents');
            $table->string('currency', 3)->default('usd');
            $table->string('status', 20)->index();
            $table->timestamp('issued_at')->nullable();
            $table->timestamp('due_at')->nullable();
            $table->timestamp('paid_at')->nullable();
            $table->string('pdf_url')->nullable();
            $table->text('notes')->nullable();
            $table->timestamps();

            $table->index(['team_id', 'status']);
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('billing_invoices');
    }
};

<?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('billing_invoice_lines', function (Blueprint $table) {
            $table->id();
            $table->unsignedBigInteger('billing_invoice_id')->index();
            $table->string('kind', 20);
            $table->string('description');
            $table->decimal('quantity', 20, 6)->default(1);
            $table->bigInteger('unit_amount_cents');
            $table->bigInteger('amount_cents');
            $table->json('meta')->nullable();
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('billing_invoice_lines');
    }
};

<?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('billing_payments', function (Blueprint $table) {
            $table->id();
            $table->unsignedBigInteger('team_id')->index();
            $table->unsignedBigInteger('billing_invoice_id')->nullable()->index();
            $table->string('method', 20);
            $table->bigInteger('amount_cents');
            $table->timestamp('paid_at');
            $table->string('reference')->nullable();
            $table->unsignedBigInteger('recorded_by_user_id')->nullable();
            $table->text('notes')->nullable();
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('billing_payments');
    }
};

<?php

namespace App\Models\Billing;

use App\Enums\BillingInvoiceSource;
use App\Enums\BillingInvoiceStatus;
use App\Models\Team;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Support\Carbon;

/**
 * An invoice issued to a team, whether Stripe generated it or a superadmin
 * did. Holding both in one table is what lets the billing console read a
 * team's history without reconciling two systems.
 *
 * Not tenant-scoped: the console reads across every team.
 *
 * @property int $id
 * @property int $team_id
 * @property string $number
 * @property BillingInvoiceSource $source
 * @property string|null $stripe_invoice_id
 * @property Carbon $period_start
 * @property Carbon $period_end
 * @property int $subtotal_cents
 * @property int $total_cents
 * @property string $currency
 * @property BillingInvoiceStatus $status
 * @property Carbon|null $issued_at
 * @property Carbon|null $due_at
 * @property Carbon|null $paid_at
 * @property string|null $pdf_url
 * @property string|null $notes
 * @property Carbon|null $created_at
 * @property Carbon|null $updated_at
 * @property-read Team $team
 * @property-read Collection<int, InvoiceLine> $lines
 * @property-read Collection<int, Payment> $payments
 */
class Invoice extends Model
{
    protected $table = 'billing_invoices';

    protected $guarded = [];

    protected $casts = [
        'team_id' => 'integer',
        'source' => BillingInvoiceSource::class,
        'period_start' => 'date',
        'period_end' => 'date',
        'subtotal_cents' => 'integer',
        'total_cents' => 'integer',
        'status' => BillingInvoiceStatus::class,
        'issued_at' => 'datetime',
        'due_at' => 'datetime',
        'paid_at' => 'datetime',
        'created_at' => 'datetime',
        'updated_at' => 'datetime',
    ];

    /**
     * @return BelongsTo<Team, $this>
     */
    public function team(): BelongsTo
    {
        return $this->belongsTo(Team::class);
    }

    /**
     * @return HasMany<InvoiceLine, $this>
     */
    public function lines(): HasMany
    {
        return $this->hasMany(InvoiceLine::class, 'billing_invoice_id');
    }

    /**
     * @return HasMany<Payment, $this>
     */
    public function payments(): HasMany
    {
        return $this->hasMany(Payment::class, 'billing_invoice_id');
    }

    public function amountPaidCents(): int
    {
        return (int) $this->payments()->sum('amount_cents');
    }

    public function amountDueCents(): int
    {
        return max(0, $this->total_cents - $this->amountPaidCents());
    }
}

<?php

namespace App\Models\Billing;

use App\Enums\BillingInvoiceLineKind;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Support\Carbon;

/**
 * One line on an invoice. Amounts are signed so an `Adjustment` line can
 * carry a credit.
 *
 * @property int $id
 * @property int $billing_invoice_id
 * @property BillingInvoiceLineKind $kind
 * @property string $description
 * @property string $quantity
 * @property int $unit_amount_cents
 * @property int $amount_cents
 * @property array<string, mixed>|null $meta
 * @property Carbon|null $created_at
 * @property Carbon|null $updated_at
 * @property-read Invoice $invoice
 */
class InvoiceLine extends Model
{
    protected $table = 'billing_invoice_lines';

    protected $guarded = [];

    protected $casts = [
        'billing_invoice_id' => 'integer',
        'kind' => BillingInvoiceLineKind::class,
        'unit_amount_cents' => 'integer',
        'amount_cents' => 'integer',
        'meta' => 'array',
        'created_at' => 'datetime',
        'updated_at' => 'datetime',
    ];

    /**
     * @return BelongsTo<Invoice, $this>
     */
    public function invoice(): BelongsTo
    {
        return $this->belongsTo(Invoice::class, 'billing_invoice_id');
    }
}

<?php

namespace App\Models\Billing;

use App\Enums\BillingPaymentMethod;
use App\Models\Team;
use App\Models\User;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Support\Carbon;

/**
 * A payment received from a team. Offline payments (bank transfer, cheque,
 * cash) are recorded here by a superadmin; Stripe payments are mirrored from
 * webhooks.
 *
 * @property int $id
 * @property int $team_id
 * @property int|null $billing_invoice_id
 * @property BillingPaymentMethod $method
 * @property int $amount_cents
 * @property Carbon $paid_at
 * @property string|null $reference
 * @property int|null $recorded_by_user_id
 * @property string|null $notes
 * @property Carbon|null $created_at
 * @property Carbon|null $updated_at
 * @property-read Team $team
 * @property-read Invoice|null $invoice
 * @property-read User|null $recordedBy
 */
class Payment extends Model
{
    protected $table = 'billing_payments';

    protected $guarded = [];

    protected $casts = [
        'team_id' => 'integer',
        'billing_invoice_id' => 'integer',
        'method' => BillingPaymentMethod::class,
        'amount_cents' => 'integer',
        'paid_at' => 'datetime',
        'recorded_by_user_id' => 'integer',
        'created_at' => 'datetime',
        'updated_at' => 'datetime',
    ];

    /**
     * @return BelongsTo<Team, $this>
     */
    public function team(): BelongsTo
    {
        return $this->belongsTo(Team::class);
    }

    /**
     * @return BelongsTo<Invoice, $this>
     */
    public function invoice(): BelongsTo
    {
        return $this->belongsTo(Invoice::class, 'billing_invoice_id');
    }

    /**
     * @return BelongsTo<User, $this>
     */
    public function recordedBy(): BelongsTo
    {
        return $this->belongsTo(User::class, 'recorded_by_user_id');
    }
}

vendor/bin/pint --dirty --format agent
git add app/Enums app/Models/Billing database/migrations tests/Feature/Billing
git commit -m "Billing: add invoices, invoice lines and payments"

<?php

namespace Tests\Feature\Billing;

use App\Enums\TeamRole;
use App\Models\Billing\BillingEvent;
use App\Models\Billing\UsageEvent;
use App\Models\Billing\UsageRate;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Carbon;

/**
 * The usage ledger and the billing audit trail (design doc "Usage metering").
 */
class BillingLedgerTest extends BillingTestCase
{
    use RefreshDatabase;

    protected function tearDown(): void
    {
        Carbon::setTestNow();

        parent::tearDown();
    }

    public function test_a_usage_event_keeps_the_rate_it_was_priced_at(): void
    {
        $team = $this->team();

        $event = UsageEvent::create([
            'team_id' => $team->id,
            'service' => 'sms',
            'quantity' => 1500,
            'unit' => 'message',
            'unit_amount_cents' => 50,
            'amount_cents' => 75000,
            'occurred_at' => '2026-08-14 10:22:00',
            'billing_period' => '2026-08',
        ]);

        UsageRate::create([
            'service' => 'sms',
            'team_id' => null,
            'unit' => 'message',
            'unit_amount_cents' => 90,
            'effective_from' => '2026-09-01 00:00:00',
        ]);

        $this->assertSame(50, $event->fresh()->unit_amount_cents);
        $this->assertSame(75000, $event->fresh()->amount_cents);
    }

    public function test_a_usage_event_gets_a_ulid_key(): void
    {
        $team = $this->team();

        $event = UsageEvent::create([
            'team_id' => $team->id,
            'service' => 'ai_tokens',
            'quantity' => 250000,
            'unit' => 'token',
            'unit_amount_cents' => 1,
            'amount_cents' => 250000,
            'occurred_at' => '2026-08-14 10:22:00',
            'billing_period' => '2026-08',
        ]);

        $this->assertIsString($event->id);
        $this->assertSame(26, strlen($event->id));
    }

    public function test_uninvoiced_events_for_a_period_can_be_found(): void
    {
        $team = $this->team();

        UsageEvent::create([
            'team_id' => $team->id, 'service' => 'sms', 'quantity' => 10, 'unit' => 'message',
            'unit_amount_cents' => 50, 'amount_cents' => 500,
            'occurred_at' => '2026-08-02 09:00:00', 'billing_period' => '2026-08',
        ]);
        UsageEvent::create([
            'team_id' => $team->id, 'service' => 'sms', 'quantity' => 20, 'unit' => 'message',
            'unit_amount_cents' => 50, 'amount_cents' => 1000,
            'occurred_at' => '2026-08-03 09:00:00', 'billing_period' => '2026-08',
            'invoiced_at' => '2026-09-01 00:05:00',
        ]);
        UsageEvent::create([
            'team_id' => $team->id, 'service' => 'sms', 'quantity' => 30, 'unit' => 'message',
            'unit_amount_cents' => 50, 'amount_cents' => 1500,
            'occurred_at' => '2026-09-02 09:00:00', 'billing_period' => '2026-09',
        ]);

        $pending = UsageEvent::query()->forPeriod('2026-08')->uninvoiced()->get();

        $this->assertCount(1, $pending);
        $this->assertSame(500, $pending->sum('amount_cents'));
    }

    public function test_a_team_rate_override_beats_the_platform_default(): void
    {
        $team = $this->team();

        UsageRate::create([
            'service' => 'sms', 'team_id' => null, 'unit' => 'message',
            'unit_amount_cents' => 50, 'effective_from' => '2026-01-01 00:00:00',
        ]);
        UsageRate::create([
            'service' => 'sms', 'team_id' => $team->id, 'unit' => 'message',
            'unit_amount_cents' => 35, 'effective_from' => '2026-06-01 00:00:00',
        ]);

        $rate = UsageRate::resolve('sms', $team, Carbon::parse('2026-08-14 10:00:00'));

        $this->assertSame(35, $rate?->unit_amount_cents);
    }

    public function test_the_most_recent_rate_in_force_wins(): void
    {
        $team = $this->team();

        UsageRate::create([
            'service' => 'sms', 'team_id' => null, 'unit' => 'message',
            'unit_amount_cents' => 50, 'effective_from' => '2026-01-01 00:00:00',
        ]);
        UsageRate::create([
            'service' => 'sms', 'team_id' => null, 'unit' => 'message',
            'unit_amount_cents' => 90, 'effective_from' => '2026-09-01 00:00:00',
        ]);

        $this->assertSame(50, UsageRate::resolve('sms', $team, Carbon::parse('2026-08-14 10:00:00'))?->unit_amount_cents);
        $this->assertSame(90, UsageRate::resolve('sms', $team, Carbon::parse('2026-09-14 10:00:00'))?->unit_amount_cents);
    }

    public function test_an_unpriced_service_resolves_to_nothing(): void
    {
        $team = $this->team();

        $this->assertNull(UsageRate::resolve('carrier_pigeon', $team, Carbon::parse('2026-08-14 10:00:00')));
    }

    public function test_a_billing_event_records_who_did_it(): void
    {
        $team = $this->team();
        $admin = $this->member($team, TeamRole::Admin);

        $event = BillingEvent::record($team, 'grace.extended', ['days' => 14], $admin->id);

        $this->assertSame('grace.extended', $event->type);
        $this->assertSame($admin->id, $event->actor_user_id);
        $this->assertSame(14, $event->payload['days']);
    }

    public function test_a_system_billing_event_has_no_actor(): void
    {
        $team = $this->team();

        $event = BillingEvent::record($team, 'invoice.payment_failed', ['attempt' => 1]);

        $this->assertNull($event->actor_user_id);
    }

    public function test_a_stripe_event_is_only_handled_once(): void
    {
        $team = $this->team();

        $this->assertFalse(BillingEvent::hasHandledStripeEvent('evt_1QcExAmPlE'));

        BillingEvent::record($team, 'invoice.paid', [], null, 'evt_1QcExAmPlE');

        $this->assertTrue(BillingEvent::hasHandledStripeEvent('evt_1QcExAmPlE'));
    }
}

<?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('billing_usage_rates', function (Blueprint $table) {
            $table->id();
            $table->string('service')->index();
            $table->unsignedBigInteger('team_id')->nullable()->index();
            $table->string('unit', 30);
            $table->unsignedBigInteger('unit_amount_cents');
            $table->timestamp('effective_from');
            $table->timestamps();

            $table->unique(['service', 'team_id', 'effective_from'], 'billing_usage_rates_scope_unique');
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('billing_usage_rates');
    }
};

<?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('billing_usage_events', function (Blueprint $table) {
            $table->ulid('id')->primary();
            $table->unsignedBigInteger('team_id');
            $table->string('service')->index();
            $table->decimal('quantity', 20, 6);
            $table->string('unit', 30);
            $table->unsignedBigInteger('unit_amount_cents');
            $table->unsignedBigInteger('amount_cents');
            $table->timestamp('occurred_at');
            $table->string('billing_period', 7);
            $table->string('reference_type')->nullable();
            $table->string('reference_id')->nullable();
            $table->json('metadata')->nullable();
            $table->timestamp('invoiced_at')->nullable();
            $table->unsignedBigInteger('billing_invoice_id')->nullable()->index();
            $table->timestamps();

            $table->index(['team_id', 'billing_period']);
            $table->index(['billing_period', 'invoiced_at']);
            $table->index(['reference_type', 'reference_id']);
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('billing_usage_events');
    }
};

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

/**
 * The append-only audit of billing state changes.
 *
 * A dedicated table rather than `owen-it/laravel-auditing`, for the same
 * reason `superadmin_impersonation_logs` is one: these events have two
 * actors (or none — Stripe is not a user) and are not changes to a model's
 * own attributes, so forcing them through `Auditable` would misrepresent
 * them.
 *
 * The unique `stripe_event_id` doubles as the webhook idempotency key: a
 * replayed webhook cannot double-charge or double-transition.
 */
return new class extends Migration
{
    public function up(): void
    {
        Schema::create('billing_events', function (Blueprint $table) {
            $table->id();
            $table->unsignedBigInteger('team_id')->nullable()->index();
            $table->string('type')->index();
            $table->unsignedBigInteger('actor_user_id')->nullable()->index();
            $table->string('stripe_event_id')->nullable()->unique();
            $table->json('payload')->nullable();
            $table->timestamp('created_at')->nullable();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('billing_events');
    }
};

<?php

namespace App\Models\Billing;

use App\Models\Team;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Concerns\HasUlids;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Support\Carbon;

/**
 * One metered thing a team consumed.
 *
 * The rate is denormalized onto the row at record time, which is what makes
 * the ledger immutable: changing the SMS price next month never rewrites
 * what August cost.
 *
 * @property string $id
 * @property int $team_id
 * @property string $service
 * @property string $quantity
 * @property string $unit
 * @property int $unit_amount_cents
 * @property int $amount_cents
 * @property Carbon $occurred_at
 * @property string $billing_period
 * @property string|null $reference_type
 * @property string|null $reference_id
 * @property array<string, mixed>|null $metadata
 * @property Carbon|null $invoiced_at
 * @property int|null $billing_invoice_id
 * @property Carbon|null $created_at
 * @property Carbon|null $updated_at
 * @property-read Team $team
 * @property-read Invoice|null $invoice
 */
class UsageEvent extends Model
{
    use HasUlids;

    protected $table = 'billing_usage_events';

    protected $guarded = [];

    protected $casts = [
        'team_id' => 'integer',
        'unit_amount_cents' => 'integer',
        'amount_cents' => 'integer',
        'occurred_at' => 'datetime',
        'metadata' => 'array',
        'invoiced_at' => 'datetime',
        'billing_invoice_id' => 'integer',
        'created_at' => 'datetime',
        'updated_at' => 'datetime',
    ];

    /**
     * @return BelongsTo<Team, $this>
     */
    public function team(): BelongsTo
    {
        return $this->belongsTo(Team::class);
    }

    /**
     * @return BelongsTo<Invoice, $this>
     */
    public function invoice(): BelongsTo
    {
        return $this->belongsTo(Invoice::class, 'billing_invoice_id');
    }

    /**
     * @param  Builder<self>  $query
     * @return Builder<self>
     */
    public function scopeForPeriod(Builder $query, string $period): Builder
    {
        return $query->where('billing_period', $period);
    }

    /**
     * @param  Builder<self>  $query
     * @return Builder<self>
     */
    public function scopeUninvoiced(Builder $query): Builder
    {
        return $query->whereNull('invoiced_at');
    }
}

<?php

namespace App\Models\Billing;

use App\Models\Team;
use Carbon\CarbonInterface;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Carbon;

/**
 * What a metered service costs. A row with a null `team_id` is the platform
 * default; one with a team is that team's negotiated override.
 *
 * @property int $id
 * @property string $service
 * @property int|null $team_id
 * @property string $unit
 * @property int $unit_amount_cents
 * @property Carbon $effective_from
 * @property Carbon|null $created_at
 * @property Carbon|null $updated_at
 */
class UsageRate extends Model
{
    protected $table = 'billing_usage_rates';

    protected $guarded = [];

    protected $casts = [
        'team_id' => 'integer',
        'unit_amount_cents' => 'integer',
        'effective_from' => 'datetime',
        'created_at' => 'datetime',
        'updated_at' => 'datetime',
    ];

    /**
     * The rate in force for this team and service at the given moment: the
     * team's own override if it has one, otherwise the platform default,
     * taking the most recent row effective on or before that moment.
     */
    public static function resolve(string $service, Team $team, ?CarbonInterface $moment = null): ?self
    {
        $moment ??= Carbon::now();

        $find = fn (?int $teamId) => self::query()
            ->where('service', $service)
            ->where('team_id', $teamId)
            ->where('effective_from', '<=', $moment)
            ->orderByDesc('effective_from')
            ->first();

        return $find($team->id) ?? $find(null);
    }
}

<?php

namespace App\Models\Billing;

use App\Models\Team;
use App\Models\User;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Support\Carbon;

/**
 * An append-only record of a billing state change.
 *
 * Named `BillingEvent` rather than `Event` despite already living in the
 * `Billing` namespace, so a file importing it alongside Laravel's `Event`
 * facade never has to alias one of them.
 *
 * @property int $id
 * @property int|null $team_id
 * @property string $type
 * @property int|null $actor_user_id
 * @property string|null $stripe_event_id
 * @property array<string, mixed>|null $payload
 * @property Carbon|null $created_at
 * @property-read Team|null $team
 * @property-read User|null $actor
 */
class BillingEvent extends Model
{
    protected $table = 'billing_events';

    public const UPDATED_AT = null;

    protected $guarded = [];

    protected $casts = [
        'team_id' => 'integer',
        'actor_user_id' => 'integer',
        'payload' => 'array',
        'created_at' => 'datetime',
    ];

    /**
     * @return BelongsTo<Team, $this>
     */
    public function team(): BelongsTo
    {
        return $this->belongsTo(Team::class);
    }

    /**
     * @return BelongsTo<User, $this>
     */
    public function actor(): BelongsTo
    {
        return $this->belongsTo(User::class, 'actor_user_id');
    }

    /**
     * @param  array<string, mixed>  $payload
     */
    public static function record(
        ?Team $team,
        string $type,
        array $payload = [],
        ?int $actorUserId = null,
        ?string $stripeEventId = null,
    ): self {
        return self::create([
            'team_id' => $team?->id,
            'type' => $type,
            'payload' => $payload,
            'actor_user_id' => $actorUserId,
            'stripe_event_id' => $stripeEventId,
        ]);
    }

    /**
     * Whether this Stripe event has already been processed. The unique index
     * on `stripe_event_id` is the real guarantee; this is the cheap check
     * before doing the work.
     */
    public static function hasHandledStripeEvent(string $stripeEventId): bool
    {
        return self::query()->where('stripe_event_id', $stripeEventId)->exists();
    }
}

vendor/bin/pint --dirty --format agent
git add app/Models/Billing database/migrations tests/Feature/Billing
git commit -m "Billing: add the usage ledger and billing audit trail"

<?php

namespace Tests\Feature\Billing;

use App\Enums\BillingAccessState;
use App\Enums\BillingType;
use App\Enums\TeamRole;
use App\Models\Billing\Product;
use App\Models\Billing\TeamModule;
use App\Models\System\Module;
use App\Support\Billing\Entitlements;
use Database\Seeders\BillingProductsSeeder;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Carbon;

/**
 * The one thing the application asks about billing permissions (design doc
 * "Architecture: three layers").
 */
class EntitlementsTest extends BillingTestCase
{
    use RefreshDatabase;

    protected function setUp(): void
    {
        parent::setUp();

        Product::flushCache();
        Entitlements::flush();
        $this->seed(BillingProductsSeeder::class);

        // `System\Module` reads the default connection, which is an empty
        // in-memory SQLite database in tests. The resolver enumerates standard
        // modules from this table, so the rows these tests reason about have to
        // exist. Created explicitly rather than by running `ModulesSeeder`,
        // matching how `tests/Feature/Support/ModulesMenuFilterTest` does it.
        foreach ([
            ['key' => 'crm', 'name' => 'CRM', 'order' => 1],
            ['key' => 'warehouse', 'name' => 'Warehouse', 'order' => 2],
            ['key' => 'logistics3p', 'name' => '3PL', 'order' => 3],
            ['key' => 'containers', 'name' => 'Container Depot', 'order' => 4],
        ] as $module) {
            Module::create($module + ['menu' => true, 'status' => true]);
        }
    }

    protected function tearDown(): void
    {
        Product::flushCache();
        Entitlements::flush();
        Carbon::setTestNow();

        parent::tearDown();
    }

    public function test_an_enterprise_team_has_no_billing_module_restriction(): void
    {
        $team = $this->team();

        $entitlement = Entitlements::for($team);

        $this->assertNull($entitlement->allowedModuleKeys);
        $this->assertTrue($entitlement->allowsModule('logistics3p'));
        $this->assertTrue($entitlement->allowsModule('crm'));
    }

    public function test_a_self_serve_team_gets_standard_modules_but_not_specialized_ones(): void
    {
        $team = $this->team();
        $team->forceFill(['billing_type' => BillingType::SelfServe])->save();

        $entitlement = Entitlements::for($team->fresh());

        $this->assertTrue($entitlement->allowsModule('crm'));
        $this->assertTrue($entitlement->allowsModule('warehouse'));
        $this->assertFalse($entitlement->allowsModule('logistics3p'));
        $this->assertFalse($entitlement->allowsModule('containers'));
    }

    public function test_a_self_serve_team_holding_a_module_may_reach_it(): void
    {
        $team = $this->team();
        $team->forceFill(['billing_type' => BillingType::SelfServe])->save();
        TeamModule::create([
            'team_id' => $team->id,
            'billing_product_id' => Product::where('key', 'module.logistics3p')->value('id'),
            'starts_at' => '2026-09-01 00:00:00',
        ]);
        Carbon::setTestNow('2026-09-15 12:00:00');

        $entitlement = Entitlements::for($team->fresh());

        $this->assertTrue($entitlement->allowsModule('logistics3p'));
        $this->assertFalse($entitlement->allowsModule('containers'));
    }

    public function test_a_dropped_module_stops_being_allowed_once_the_period_ends(): void
    {
        $team = $this->team();
        $team->forceFill(['billing_type' => BillingType::SelfServe])->save();
        TeamModule::create([
            'team_id' => $team->id,
            'billing_product_id' => Product::where('key', 'module.containers')->value('id'),
            'starts_at' => '2026-08-01 00:00:00',
            'ends_at' => '2026-10-01 00:00:00',
        ]);

        Carbon::setTestNow('2026-09-30 23:59:59');
        Entitlements::flush();
        $this->assertTrue(Entitlements::for($team->fresh())->allowsModule('containers'));

        Carbon::setTestNow('2026-10-01 00:00:01');
        Entitlements::flush();
        $this->assertFalse(Entitlements::for($team->fresh())->allowsModule('containers'));
    }

    public function test_access_follows_the_teams_state(): void
    {
        $team = $this->team();

        $this->assertTrue(Entitlements::for($team)->grantsAppAccess());

        $team->forceFill(['billing_access_state' => BillingAccessState::Restricted])->save();
        Entitlements::flush();

        $this->assertFalse(Entitlements::for($team->fresh())->grantsAppAccess());
    }

    public function test_storage_defaults_to_ten_gigabytes_per_active_seat(): void
    {
        $team = $this->team();
        $this->member($team, TeamRole::Owner);
        $this->member($team, TeamRole::Member);
        $this->member($team, TeamRole::Member);

        $entitlement = Entitlements::for($team->fresh());

        $this->assertSame(3 * 10 * 1024 * 1024 * 1024, $entitlement->storageQuotaBytes);
    }

    public function test_an_explicit_storage_quota_overrides_the_per_seat_default(): void
    {
        $team = $this->team();
        $this->member($team, TeamRole::Owner);
        $team->forceFill(['billing_storage_quota_bytes' => 53687091200])->save();

        $this->assertSame(53687091200, Entitlements::for($team->fresh())->storageQuotaBytes);
    }

    public function test_storage_usage_is_reported_against_the_quota(): void
    {
        $team = $this->team();
        $this->member($team, TeamRole::Owner);
        $team->forceFill([
            'billing_storage_quota_bytes' => 1000,
            'billing_storage_used_bytes' => 850,
        ])->save();

        $entitlement = Entitlements::for($team->fresh());

        $this->assertSame(85.0, $entitlement->storagePercentUsed());
        $this->assertFalse($entitlement->isOverStorageQuota());

        $team->forceFill(['billing_storage_used_bytes' => 1200])->save();
        Entitlements::flush();

        $this->assertTrue(Entitlements::for($team->fresh())->isOverStorageQuota());
    }

    public function test_a_seat_cap_is_enforced_only_when_set(): void
    {
        $team = $this->team();

        $this->assertNull(Entitlements::for($team)->seatCap);
        $this->assertTrue(Entitlements::for($team)->hasSeatCapacity(9999));

        $team->forceFill(['billing_seat_cap' => 3])->save();
        Entitlements::flush();

        $entitlement = Entitlements::for($team->fresh());
        $this->assertTrue($entitlement->hasSeatCapacity(2));
        $this->assertFalse($entitlement->hasSeatCapacity(3));
    }

    public function test_a_null_team_is_fully_unrestricted(): void
    {
        $entitlement = Entitlements::for(null);

        $this->assertTrue($entitlement->grantsAppAccess());
        $this->assertNull($entitlement->allowedModuleKeys);
        $this->assertTrue($entitlement->allowsModule('logistics3p'));
    }

    public function test_the_resolver_does_not_query_per_call(): void
    {
        $team = $this->team();
        Entitlements::for($team);

        \Illuminate\Support\Facades\DB::enableQueryLog();
        Entitlements::for($team);
        $queries = \Illuminate\Support\Facades\DB::getQueryLog();
        \Illuminate\Support\Facades\DB::disableQueryLog();

        $this->assertCount(0, $queries);
    }
}

<?php

namespace App\Support\Billing;

use App\Enums\BillingAccessState;
use Carbon\CarbonImmutable;

/**
 * What a team may do right now, according to billing.
 *
 * Deliberately a plain immutable object with no database access of its own:
 * everything it needs is resolved once, by `Entitlements`, and every
 * enforcement point in the application reads this rather than reaching for
 * Stripe or for `teams` columns directly.
 */
readonly class Entitlement
{
    /**
     * @param  array<int, string>|null  $allowedModuleKeys  Null means billing
     *                                                      imposes no module restriction at all — the team's own
     *                                                      `modulesAllowed` configuration still applies on top.
     */
    public function __construct(
        public BillingAccessState $accessState,
        public ?array $allowedModuleKeys,
        public ?int $seatCap,
        public int $storageQuotaBytes,
        public int $storageUsedBytes,
        public ?CarbonImmutable $graceEndsAt = null,
    ) {}

    public function grantsAppAccess(): bool
    {
        return $this->accessState->grantsAppAccess();
    }

    public function allowsModule(string $moduleKey): bool
    {
        return $this->allowedModuleKeys === null
            || in_array($moduleKey, $this->allowedModuleKeys, true);
    }

    /**
     * Whether one more seat may be added, given how many are occupied now.
     * A null cap means unlimited.
     */
    public function hasSeatCapacity(int $currentSeats): bool
    {
        return $this->seatCap === null || $currentSeats < $this->seatCap;
    }

    public function storagePercentUsed(): float
    {
        if ($this->storageQuotaBytes <= 0) {
            return 100.0;
        }

        return round($this->storageUsedBytes / $this->storageQuotaBytes * 100, 2);
    }

    public function isOverStorageQuota(): bool
    {
        return $this->storageUsedBytes >= $this->storageQuotaBytes;
    }
}

<?php

namespace App\Support\Billing;

use App\Enums\BillingAccessState;
use App\Enums\BillingType;
use App\Models\Billing\Product;
use App\Models\Billing\TeamModule;
use App\Models\System\Module;
use App\Models\Team;
use Carbon\CarbonImmutable;

/**
 * Resolves what a team may do, from the database only — never from Stripe.
 *
 * Memoised per request by team id. Module visibility consults this on every
 * module of every page render, so it must not cost a query per call; the
 * memo is static and therefore survives across tests in one process, so the
 * billing suite flushes it in `setUp()` the same way
 * `ProjectPermissions`/`ProjectAccess` are flushed.
 */
class Entitlements
{
    /**
     * 10 GB per active user, pooled across the team, for any team without an
     * explicit quota. The per-seat calculation is floored at one seat: a team
     * with no active members cannot be used by anyone, so one seat's worth is
     * inert, whereas a quota of zero would make `isOverStorageQuota()` answer
     * true for a team that has stored nothing. Seatless teams are reachable —
     * `SuperAdmin\TeamController::store()` creates a team with no membership
     * and adds members on the next screen.
     */
    public const DEFAULT_STORAGE_BYTES_PER_SEAT = 10 * 1024 * 1024 * 1024;

    /** @var array<int, Entitlement> */
    private static array $resolved = [];

    public static function for(?Team $team): Entitlement
    {
        if ($team === null) {
            return self::unrestricted();
        }

        return self::$resolved[$team->id] ??= self::resolve($team);
    }

    public static function flush(): void
    {
        self::$resolved = [];
    }

    private static function resolve(Team $team): Entitlement
    {
        $seats = $team->activeSeatCount();

        return new Entitlement(
            accessState: $team->billing_access_state ?? BillingAccessState::Active,
            allowedModuleKeys: self::allowedModuleKeys($team),
            seatCap: $team->billing_seat_cap,
            storageQuotaBytes: $team->billing_storage_quota_bytes
                ?? max(1, $seats) * self::DEFAULT_STORAGE_BYTES_PER_SEAT,
            storageUsedBytes: $team->billing_storage_used_bytes ?? 0,
            graceEndsAt: $team->billing_grace_ends_at?->toImmutable(),
        );
    }

    /**
     * The module keys billing permits.
     *
     * Enterprise and internal teams return null — billing imposes no
     * restriction on them, and their module set is administered directly
     * through `Team::$modulesAllowed`. Self-serve teams get every standard
     * module plus whichever specialized modules they currently hold.
     *
     * @return array<int, string>|null
     */
    private static function allowedModuleKeys(Team $team): ?array
    {
        if (($team->billing_type ?? BillingType::Enterprise) !== BillingType::SelfServe) {
            return null;
        }

        $specialized = Product::specializedModuleKeys();

        $standard = Module::query()
            ->pluck('key')
            ->reject(fn (string $key) => in_array($key, $specialized, true))
            ->values()
            ->all();

        return array_values(array_unique([
            ...$standard,
            ...TeamModule::activeModuleKeysFor($team),
        ]));
    }

    private static function unrestricted(): Entitlement
    {
        return new Entitlement(
            accessState: BillingAccessState::Active,
            allowedModuleKeys: null,
            seatCap: null,
            storageQuotaBytes: self::DEFAULT_STORAGE_BYTES_PER_SEAT,
            storageUsedBytes: 0,
        );
    }
}

vendor/bin/pint --dirty --format agent
git add app/Support/Billing tests/Feature/Billing
git commit -m "Billing: add the entitlement resolver"

<?php

namespace Tests\Feature\Billing;

use App\Enums\BillingType;
use App\Models\Billing\Product;
use App\Models\Billing\TeamModule;
use App\Models\System\Module;
use App\Support\Billing\Entitlements;
use App\Support\Modules;
use Database\Seeders\BillingProductsSeeder;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Carbon;

/**
 * Billing entitlements layered onto the existing module-visibility gate
 * (design doc "Entitlement enforcement points").
 */
class ModuleVisibilityTest extends BillingTestCase
{
    use RefreshDatabase;

    protected function setUp(): void
    {
        parent::setUp();

        Product::flushCache();
        Entitlements::flush();
        $this->seed(BillingProductsSeeder::class);

        // See the note in EntitlementsTest: the resolver enumerates standard
        // modules from the `modules` table, which is empty in the test SQLite
        // database unless the test populates it.
        foreach ([
            ['key' => 'crm', 'name' => 'CRM', 'order' => 1],
            ['key' => 'warehouse', 'name' => 'Warehouse', 'order' => 2],
            ['key' => 'logistics3p', 'name' => '3PL', 'order' => 3],
            ['key' => 'containers', 'name' => 'Container Depot', 'order' => 4],
        ] as $module) {
            Module::create($module + ['menu' => true, 'status' => true]);
        }
    }

    protected function tearDown(): void
    {
        Product::flushCache();
        Entitlements::flush();
        Carbon::setTestNow();

        parent::tearDown();
    }

    public function test_an_enterprise_team_with_no_configuration_is_unrestricted_as_before(): void
    {
        $team = $this->team();

        $this->assertNull(Modules::allowedForTeam($team));
        $this->assertTrue(Modules::isAllowedForTeam($team, 'logistics3p'));
        $this->assertTrue(Modules::isAllowedForTeam($team, 'crm'));
    }

    public function test_an_enterprise_teams_own_configuration_still_decides(): void
    {
        $team = $this->team();
        $team->forceFill(['modulesAllowed' => ['crm' => true, 'logistics3p' => false]])->save();

        $this->assertSame(['crm'], Modules::allowedForTeam($team->fresh()));
        $this->assertFalse(Modules::isAllowedForTeam($team->fresh(), 'logistics3p'));
    }

    public function test_a_self_serve_team_cannot_reach_a_specialized_module_it_has_not_bought(): void
    {
        $team = $this->team();
        $team->forceFill(['billing_type' => BillingType::SelfServe])->save();

        $this->assertFalse(Modules::isAllowedForTeam($team->fresh(), 'logistics3p'));
        $this->assertTrue(Modules::isAllowedForTeam($team->fresh(), 'crm'));
    }

    public function test_a_self_serve_team_reaches_a_specialized_module_it_holds(): void
    {
        $team = $this->team();
        $team->forceFill(['billing_type' => BillingType::SelfServe])->save();
        TeamModule::create([
            'team_id' => $team->id,
            'billing_product_id' => Product::where('key', 'module.logistics3p')->value('id'),
            'starts_at' => '2026-09-01 00:00:00',
        ]);
        Carbon::setTestNow('2026-09-15 12:00:00');

        $this->assertTrue(Modules::isAllowedForTeam($team->fresh(), 'logistics3p'));
    }

    public function test_billing_and_team_configuration_are_intersected_not_replaced(): void
    {
        $team = $this->team();
        $team->forceFill([
            'billing_type' => BillingType::SelfServe,
            'modulesAllowed' => ['crm' => true, 'warehouse' => true, 'logistics3p' => true],
        ])->save();

        $allowed = Modules::allowedForTeam($team->fresh());

        $this->assertContains('crm', $allowed);
        $this->assertContains('warehouse', $allowed);
        $this->assertNotContains('logistics3p', $allowed, 'the team configured it, but billing has not sold it');
    }

    public function test_a_null_team_is_still_unrestricted(): void
    {
        $this->assertNull(Modules::allowedForTeam(null));
        $this->assertTrue(Modules::isAllowedForTeam(null, 'logistics3p'));
    }
}

    protected function setUp(): void
    {
        parent::setUp();

        Entitlements::flush();
        Product::flushCache();
    }

    protected function tearDown(): void
    {
        Entitlements::flush();
        Product::flushCache();

        parent::tearDown();
    }

use App\Support\Billing\Entitlements;

    /**
     * The module keys enabled for a team, or null if neither the team's own
     * configuration nor its billing entitlement restricts anything.
     *
     * Two independent layers, intersected: the team's `modulesAllowed`
     * (administered by an operator) and what billing has actually sold them.
     * Either being null means "that layer has no opinion", not "everything
     * is disabled" — the same semantics this method has always had, now
     * applied to both inputs. An enterprise team's billing layer is always
     * null, so those teams behave exactly as they did before billing
     * existed.
     *
     * @return array<int, string>|null
     */
    public static function allowedForTeam(?Team $team): ?array
    {
        if (! $team) {
            return null;
        }

        $configured = empty($team->modulesAllowed)
            ? null
            : collect($team->modulesAllowed)
                ->filter(fn (bool $allowed) => $allowed)
                ->keys()
                ->values()
                ->all();

        $entitled = Entitlements::for($team)->allowedModuleKeys;

        if ($configured === null) {
            return $entitled;
        }

        if ($entitled === null) {
            return $configured;
        }

        return array_values(array_intersect($configured, $entitled));
    }

herd php -d memory_limit=2G artisan test --compact tests/Feature/Support tests/Feature/Teams tests/Feature/Auth tests/Feature/DashboardTest.php tests/Feature/Containers

vendor/bin/pint --dirty --format agent
git add app/Support/Modules.php tests/Feature/Billing
git commit -m "Billing: gate specialized modules on the billing entitlement"