CluPilotCloud/app/Console/Commands/SyncStripeCatalogue.php

<?php

namespace App\Console\Commands;

use App\Models\PlanFamily;
use App\Models\PlanPrice;
use App\Models\PlanVersion;
use App\Models\Subscription;
use App\Services\Billing\AddonCatalogue;
use App\Services\Billing\AddonPrices;
use App\Services\Stripe\StripeClient;
use Illuminate\Console\Command;

/**
 * Mirrors our catalogue into Stripe: a Product per plan family, a Price per
 * priced row — and the same for every module we sell.
 *
 * Stripe owns the recurring billing — retries, dunning, off-session SCA,
 * invoice numbering — so it needs to know what it is billing for. It does not
 * need to know how big the VM is, and it is not asked.
 *
 * Idempotent by construction: a row that already carries an id is skipped. That
 * matters more here than usual, because a Stripe Price cannot be edited, so a
 * second run that minted duplicates would leave two live prices for one plan
 * and no way to tell which a customer is on.
 *
 * Only PUBLISHED versions are synced. A draft has promised nothing, and a
 * Product for it would be a price list entry for something that may never
 * exist.
 *
 * **Modules were missing from this entirely**, which is why a booked module was
 * charged in the month it was booked and never again: nothing in Stripe existed
 * to put on the subscription. They are pushed at today's catalogue price on both
 * terms — a Stripe Price carries its own interval, so a module on a yearly
 * contract needs a yearly one. What this run cannot cover is a customer
 * grandfathered on an older figure or holding a discounted grant; those mint
 * their own Price at the moment they are billed. See App\Services\Billing\AddonPrices.
 */
class SyncStripeCatalogue extends Command
{
    protected $signature = 'stripe:sync-catalogue {--dry-run : Show what would be created without touching Stripe}';

    protected $description = 'Create the Stripe products and prices for the plan catalogue';

    public function handle(StripeClient $stripe): int
    {
        $dryRun = (bool) $this->option('dry-run');

        if (! $dryRun && ! $stripe->isConfigured()) {
            $this->error('Stripe is not configured (STRIPE_SECRET is empty). Nothing was created.');

            return self::FAILURE;
        }

        $created = 0;

        foreach (PlanFamily::query()->with('versions.prices')->orderBy('tier')->get() as $family) {
            $published = $family->versions->filter(fn (PlanVersion $version) => $version->isPublished());

            // A family whose versions are all drafts has promised nothing, so
            // it has no business appearing in Stripe's price list yet.
            if ($published->isEmpty()) {
                continue;
            }

            $productId = $family->stripe_product_id;

            if ($productId === null) {
                $this->line("  product  {$family->key} — {$family->name}");
                $created++;

                if (! $dryRun) {
                    $productId = $stripe->createProduct(
                        $family->name,
                        ['plan_family' => $family->key, 'plan_family_id' => (string) $family->id],
                        // Keyed on our row, so a crash between Stripe creating
                        // the product and us storing its id gives back the same
                        // product on the next run rather than a second one.
                        idempotencyKey: "clupilot-product-{$family->id}",
                    );
                    $family->update(['stripe_product_id' => $productId]);
                }
            }

            foreach ($published as $version) {
                foreach ($version->prices as $price) {
                    if ($price->stripe_price_id !== null) {
                        continue;
                    }

                    $this->line(sprintf(
                        '  price    %s v%d %s %d %s',
                        $family->key, $version->version, $price->term, $price->amount_cents, $price->currency,
                    ));
                    $created++;

                    if ($dryRun || $productId === null) {
                        continue;
                    }

                    $priceId = $stripe->createPrice(
                        productId: $productId,
                        amountCents: $price->amount_cents,
                        currency: $price->currency,
                        interval: $price->term === 'yearly' ? 'year' : 'month',
                        metadata: [
                            'plan_family' => $family->key,
                            'plan_version' => (string) $version->version,
                            'plan_version_id' => (string) $version->id,
                            'plan_price_id' => (string) $price->id,
                        ],
                        idempotencyKey: "clupilot-price-{$price->id}",
                    );

                    // Written straight through the query builder: stripe_price_id
                    // is not part of what publication froze, and the model would
                    // otherwise have to be re-read first.
                    PlanPrice::query()->whereKey($price->id)->update(['stripe_price_id' => $priceId]);
                }
            }
        }

        $created += $this->syncModules($dryRun);

        $this->newLine();

        if ($created === 0) {
            $this->info('Stripe is already in step with the catalogue.');

            return self::SUCCESS;
        }

        $this->info($dryRun
            ? "{$created} object(s) would be created. Run without --dry-run to create them."
            : "{$created} object(s) created in Stripe.");

        return self::SUCCESS;
    }

    /**
     * A Product and two Prices — monthly and yearly — for every module on sale.
     *
     * Both terms, unconditionally, rather than only the ones somebody has bought
     * a contract on: the Price has to exist BEFORE the booking that needs it, and
     * a customer on a yearly package booking their first module would otherwise
     * discover the gap at the moment their money was due.
     *
     * @return int how many objects were created, for the run's own count
     */
    private function syncModules(bool $dryRun): int
    {
        $catalogue = app(AddonCatalogue::class);
        $prices = app(AddonPrices::class);
        $currency = Subscription::catalogueCurrency();
        $created = 0;

        $keys = array_merge(array_keys((array) config('provisioning.addons')), [AddonCatalogue::STORAGE]);

        foreach ($keys as $key) {
            $monthly = $catalogue->priceCents($key);

            // Nothing to bill and nothing to mirror. A module priced at zero is
            // either a placeholder or included, and an item at no money would
            // put a line saying so on every invoice a customer ever gets.
            if ($monthly === null || $monthly <= 0) {
                continue;
            }

            foreach ([Subscription::TERM_MONTHLY => $monthly, Subscription::TERM_YEARLY => $monthly * 12] as $term => $amount) {
                $interval = $term === Subscription::TERM_YEARLY ? 'year' : 'month';

                if ($prices->find($key, $amount, $currency, $interval) !== null) {
                    continue;
                }

                $this->line(sprintf('  module   %s %s %d %s', $key, $term, $amount, $currency));
                $created++;

                if ($dryRun) {
                    continue;
                }

                $prices->ensure($key, $monthly, $currency, $term);
            }
        }

        return $created;
    }

    /** Versions whose prices are live in Stripe, for the status line. */
    public static function syncedVersions(): int
    {
        return PlanVersion::query()
            ->whereNotNull('published_at')
            ->whereHas('prices', fn ($q) => $q->whereNotNull('stripe_price_id'))
            ->count();
    }
}