<?php

namespace App\Services\Stripe;

/**
 * The bit of Stripe we drive ourselves: the catalogue.
 *
 * Everything else about recurring billing — retries, dunning, off-session SCA,
 * invoice numbering — is Stripe's job, and we learn about it through webhooks.
 * Our side owns capability, because Stripe does not know how big the VM should
 * be.
 */
interface StripeClient
{
    /** Whether an account is actually configured. */
    public function isConfigured(): bool;

    /**
     * Create a Product for a plan family; returns its Stripe id.
     *
     * `$idempotencyKey` is Stripe's own guard: a crash between their creating
     * the object and our storing the id would otherwise mint a second one on
     * the next run, and there is no way to tell duplicates apart afterwards.
     */
    public function createProduct(string $name, array $metadata = [], ?string $idempotencyKey = null): string;

    /**
     * Create a Price. Stripe Prices are immutable and carry their own interval,
     * which is why one exists per plan version AND term.
     */
    public function createPrice(
        string $productId,
        int $amountCents,
        string $currency,
        string $interval,
        array $metadata = [],
        ?string $idempotencyKey = null,
    ): string;

    /** Stop a Price being offered. The Price itself stays, as Stripe requires. */
    public function archivePrice(string $priceId): void;
}
