App subscriptions: manage a user's subscriptions with the app's own token

- $user->appSubscriptions(): create (idempotency_key), find, all, checkout, revoke, pause,
  resume, update against /v1/client/subscriptions with a client credentials token, so apps don't
  depend on the user's login
- user id from the billable's anikeen_id (AnikeenId::useUserIdField())
- ApiException with status, stable error code, isNotFound/isConflict/isTemporary; network
  errors no longer escape as raw Guzzle exceptions
- rejected app tokens are renewed once; asApp() never changes the shared client's token
- tests (testbench + Guzzle mock) and CI

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/Id/Resources/AppSubscription.php

@@ -0,0 +1,126 @@
+<?php
+
+namespace Anikeen\Id\Resources;
+
+use Anikeen\Id\Exceptions\ApiException;
+use Anikeen\Id\Support\AppRequest;
+use JsonSerializable;
+
+/**
+ * A subscription managed by the app itself (client credentials), see AppSubscriptions.
+ *
+ * @property string $id
+ * @property string $user_id
+ * @property ?string $group
+ * @property string $name
+ * @property ?string $description
+ * @property string $unit
+ * @property float $price
+ * @property ?float $vat_rate
+ * @property bool $active
+ * @property bool $autorenew
+ * @property bool $cancelled
+ * @property ?string $status "active" or "inactive"
+ * @property ?string $starts_at
+ * @property ?string $ends_at
+ * @property ?string $accounting_at
+ * @property bool $is_past_due
+ * @property int $failed_renewal_retries
+ * @property ?array $payload
+ * @property ?string $idempotency_key
+ */
+class AppSubscription implements JsonSerializable
+{
+    public function __construct(protected object $data)
+    {
+    }
+
+    public function __get(string $name): mixed
+    {
+        return $this->data->{$name} ?? null;
+    }
+
+    public function __isset(string $name): bool
+    {
+        return isset($this->data->{$name});
+    }
+
+    /**
+     * Change a subscription that wasn't checked out yet.
+     *
+     * @throws ApiException
+     */
+    public function update(array $attributes): self
+    {
+        return $this->send('PUT', '', $attributes);
+    }
+
+    /**
+     * Activate the subscription and bill its first period.
+     *
+     * @throws ApiException 409 "already_active", "billing_address_missing", …
+     */
+    public function checkout(): self
+    {
+        return $this->send('PUT', '/checkout');
+    }
+
+    /**
+     * Cancel the subscription. With $refund (only within 14 days of its start), its not yet
+     * charged usage is credited.
+     *
+     * @throws ApiException 409 "already_cancelled", 404 "subscription_not_found", …
+     */
+    public function revoke(bool $refund = false): self
+    {
+        return $this->send('PUT', '/revoke', ['refund' => $refund]);
+    }
+
+    /**
+     * Stop renewing; the subscription expires when its paid period ends.
+     *
+     * @throws ApiException
+     */
+    public function pause(): self
+    {
+        return $this->send('PUT', '/pause');
+    }
+
+    /**
+     * Renew again (an expired subscription starts a new period).
+     *
+     * @throws ApiException
+     */
+    public function resume(): self
+    {
+        return $this->send('PUT', '/resume');
+    }
+
+    /**
+     * @throws ApiException
+     */
+    public function refresh(): self
+    {
+        return $this->send('GET', '');
+    }
+
+    public function toArray(): array
+    {
+        return (array) $this->data;
+    }
+
+    public function jsonSerialize(): array
+    {
+        return $this->toArray();
+    }
+
+    /**
+     * @throws ApiException
+     */
+    private function send(string $method, string $action, ?array $payload = null): self
+    {
+        $this->data = AppRequest::send($method, sprintf('v1/client/subscriptions/%s%s', $this->id, $action), $payload)->data;
+
+        return $this;
+    }
+}

src/Id/Resources/AppSubscriptions.php

@@ -0,0 +1,116 @@
+<?php
+
+namespace Anikeen\Id\Resources;
+
+use Anikeen\Id\AnikeenId;
+use Anikeen\Id\Contracts\Billable;
+use Anikeen\Id\Exceptions\ApiException;
+use Anikeen\Id\Support\AppRequest;
+use Illuminate\Database\Eloquent\Model;
+use InvalidArgumentException;
+
+/**
+ * Subscriptions of a user, managed with the app's own token (client credentials, scope
+ * `subscriptions:client`) instead of the user's token, so they keep working when the user's
+ * login expired. The app has to be trusted by the ID service. Nothing is requested until a
+ * method is called.
+ */
+class AppSubscriptions
+{
+    public function __construct(protected Billable|Model $billable)
+    {
+    }
+
+    /**
+     * The user's Anikeen ID (see AnikeenId::useUserIdField()).
+     */
+    public function userId(): string
+    {
+        $userId = $this->billable->{AnikeenId::getUserIdField()} ?? null;
+
+        if (empty($userId)) {
+            throw new InvalidArgumentException(sprintf('The billable has no Anikeen ID in [%s].', AnikeenId::getUserIdField()));
+        }
+
+        return (string) $userId;
+    }
+
+    /**
+     * Create a subscription for the user (it is billed only after checkout()).
+     *
+     * @param array{
+     *     group?: null|string,
+     *     name: string,
+     *     description?: null|string,
+     *     unit: string,
+     *     price: float|string,
+     *     vat_rate?: float,
+     *     payload?: null|array,
+     *     ends_at?: null|string,
+     *     webhook_url?: null|string,
+     *     webhook_secret?: null|string,
+     *     idempotency_key?: null|string
+     * } $attributes With an idempotency_key (max. 191 characters), a retried call returns the
+     *               subscription created by the first one instead of a duplicate.
+     *
+     * @throws ApiException
+     */
+    public function create(array $attributes): AppSubscription
+    {
+        return new AppSubscription(AppRequest::send('POST', 'v1/client/subscriptions', [
+            ...$attributes,
+            'user_id' => $this->userId(),
+        ])->data);
+    }
+
+    /**
+     * Find one of the user's subscriptions; null when it doesn't exist (or belongs to someone else).
+     *
+     * @throws ApiException
+     */
+    public function find(string $id): ?AppSubscription
+    {
+        try {
+            $subscription = new AppSubscription(AppRequest::send('GET', sprintf('v1/client/subscriptions/%s', $id))->data);
+        } catch (ApiException $e) {
+            if ($e->isNotFound()) {
+                return null;
+            }
+
+            throw $e;
+        }
+
+        return $subscription->user_id === $this->userId() ? $subscription : null;
+    }
+
+    /**
+     * All of the user's subscriptions, optionally filtered.
+     *
+     * @param array{group?: string, active?: bool, cancelled?: bool} $filters
+     * @return list<AppSubscription>
+     *
+     * @throws ApiException
+     */
+    public function all(array $filters = []): array
+    {
+        $subscriptions = [];
+        $page = 1;
+
+        do {
+            $result = AppRequest::send('GET', 'v1/client/subscriptions', null, [
+                ...array_map(fn ($value) => is_bool($value) ? (int) $value : $value, $filters),
+                'user_id' => $this->userId(),
+                'per_page' => 100,
+                'page' => $page,
+            ]);
+
+            foreach ($result->data as $data) {
+                $subscriptions[] = new AppSubscription($data);
+            }
+
+            $lastPage = (int) ($result->meta->last_page ?? $page);
+        } while ($page++ < $lastPage);
+
+        return $subscriptions;
+    }
+}