Add subscription status helpers

status() returns draft, trial, active, paused, cancelling, expired or
cancelled (SubscriptionStatus constants), derived from the fields the
same way Anikeen ID derives its status, so it also works with older
responses. isActive() is true while the subscription runs and is paid.
Both Subscription and AppSubscription have them. Document the states.

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

src/Id/Concerns/HasSubscriptionStatus.php

@@ -0,0 +1,82 @@
+<?php
+
+namespace Anikeen\Id\Concerns;
+
+use Anikeen\Id\Enums\SubscriptionStatus;
+
+/**
+ * The state of a subscription, derived from its fields the same way Anikeen ID derives `status`
+ * (so it also works with responses that only carry the fields).
+ */
+trait HasSubscriptionStatus
+{
+    /**
+     * One of the SubscriptionStatus constants: draft, trial, active, paused, cancelling, expired
+     * or cancelled.
+     */
+    public function status(): string
+    {
+        $active = (bool) $this->active;
+        $started = !empty($this->starts_at);
+
+        return match (true) {
+            (bool) $this->cancelled => SubscriptionStatus::CANCELLED,
+            !$active && !$started => SubscriptionStatus::DRAFT,
+            $active && !empty($this->cancels_at) => SubscriptionStatus::CANCELLING,
+            $active && !$this->autorenew => SubscriptionStatus::PAUSED,
+            $active && !empty($this->trial_ends_at) && strtotime($this->trial_ends_at) > time() => SubscriptionStatus::TRIAL,
+            $active => SubscriptionStatus::ACTIVE,
+            !$this->autorenew && $started => SubscriptionStatus::EXPIRED,
+            default => SubscriptionStatus::INACTIVE,
+        };
+    }
+
+    /**
+     * Not checked out or confirmed yet (third-party apps: send the user to confirmationUrl()).
+     */
+    public function isDraft(): bool
+    {
+        return $this->status() === SubscriptionStatus::DRAFT;
+    }
+
+    /**
+     * Running and paid: active, in trial, paused or with a scheduled cancellation. Grant access
+     * while this is true.
+     */
+    public function isActive(): bool
+    {
+        return in_array($this->status(), [SubscriptionStatus::TRIAL, SubscriptionStatus::ACTIVE, SubscriptionStatus::PAUSED, SubscriptionStatus::CANCELLING], true);
+    }
+
+    /**
+     * Paused: runs until the paid period ends, then expires (resume() to continue).
+     */
+    public function isPaused(): bool
+    {
+        return $this->status() === SubscriptionStatus::PAUSED;
+    }
+
+    /**
+     * Running until a scheduled cancellation takes effect.
+     */
+    public function isCancelling(): bool
+    {
+        return $this->status() === SubscriptionStatus::CANCELLING;
+    }
+
+    /**
+     * Paused and ran out: resume() starts a new period.
+     */
+    public function isExpired(): bool
+    {
+        return $this->status() === SubscriptionStatus::EXPIRED;
+    }
+
+    /**
+     * Cancelled for good.
+     */
+    public function isCancelled(): bool
+    {
+        return $this->status() === SubscriptionStatus::CANCELLED;
+    }
+}

src/Id/Enums/SubscriptionStatus.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Anikeen\Id\Enums;
+
+/**
+ * The state of a subscription, see Subscription::status() and AppSubscription::status().
+ */
+class SubscriptionStatus
+{
+    /** Created, not checked out or confirmed by the user yet. */
+    const DRAFT = 'draft';
+
+    /** Running and billed, in its trial period. */
+    const TRIAL = 'trial';
+
+    /** Running and billed. */
+    const ACTIVE = 'active';
+
+    /** Paused: runs until its paid period ends, then expires. */
+    const PAUSED = 'paused';
+
+    /** Running until a scheduled cancellation takes effect. */
+    const CANCELLING = 'cancelling';
+
+    /** Paused and ran out: can be resumed (new period) or cancelled. */
+    const EXPIRED = 'expired';
+
+    /** Cancelled for good. */
+    const CANCELLED = 'cancelled';
+
+    /** None of the above. */
+    const INACTIVE = 'inactive';
+}

src/Id/Resources/AppSubscription.php

@@ -2,6 +2,7 @@
 
 namespace Anikeen\Id\Resources;
 
+use Anikeen\Id\Concerns\HasSubscriptionStatus;
 use Anikeen\Id\Exceptions\ApiException;
 use Anikeen\Id\Support\AppRequest;
 use DateTimeInterface;
@@ -24,7 +25,9 @@ use JsonSerializable;
  * @property bool $active
  * @property bool $autorenew
  * @property bool $cancelled
- * @property ?string $status "active" or "inactive"
+ * @property ?string $status draft, trial, active, paused, cancelling, expired or cancelled, see status()
+ * @property ?string $cancels_at when a scheduled cancellation takes effect
+ * @property ?string $trial_ends_at
  * @property ?string $starts_at
  * @property ?string $ends_at
  * @property ?string $accounting_at
@@ -36,6 +39,8 @@ use JsonSerializable;
  */
 class AppSubscription implements JsonSerializable
 {
+    use HasSubscriptionStatus;
+
     public function __construct(protected object $data)
     {
     }

src/Id/Resources/Subscription.php

@@ -1,112 +1,121 @@
-<?php
-
-namespace Anikeen\Id\Resources;
-
-use Anikeen\Id\Concerns\HasBillable;
-use Anikeen\Id\Concerns\HasConfirmationUrl;
-use Anikeen\Id\Contracts\AppTokenRepository;
-use Throwable;
-
-/**
- * @property string $id
- * @property string $name
- * @property string $description
- * @property string $unit
- * @property float $price
- * @property ?float $monthly_cap net, at most this per calendar month (hour and day units)
- * @property ?float $expected_monthly_price gross estimate for a month (720 hours, at most the monthly cap)
- * @property ?string $predecessor_id the subscription this one replaced (a resize); they share the monthly cap
- * @property float $vat_rate
- * @property array $payload
- * @property string $ends_at
- * @property null|string $confirmation_url where the user confirms it (third-party apps)
- */
-class Subscription extends BaseResource
-{
-    use HasBillable;
-    use HasConfirmationUrl;
-
-    /**
-     * Update a given subscription from the current user.
-     *
-     * @param array{
-     *      group: string,
-     *      name: string,
-     *      description: null|string,
-     *      unit: string,
-     *      price: float,
-     *      monthly_cap?: null|float,
-     *      vat_rate: float,
-     *      payload: null|array,
-     *      ends_at: null|string
-     *  } $attributes The subscription data:
-     *    - group:          The group (optional)
-     *    - name:           The name (required when set)
-     *    - description:    The description (optional)
-     *    - unit:           The unit (required when set, e.g. "hour", "day", "week", "month", "year")
-     *    - price:          The price per unit (required when set)
-     *    - monthly_cap:    Net, at most this per calendar month (hour and day units; optional)
-     *    - vat_rate:       The VAT rate (required when set)
-     *    - payload:        The payload (optional)
-     *    - ends_at:        The end date (optional)
-     * @throws Throwable
-     */
-    public function update(array $attributes): self
-    {
-        return (new self(fn() => $this->billable->anikeenId()
-            ->request('PUT', sprintf('v1/subscriptions/%s', $this->id), $attributes)))
-            ->setBillable($this->billable);
-    }
-
-    /**
-     * Force given subscription to check out (trusted apps only).
-     *
-     * @throws Throwable
-     */
-    public function checkout(): self
-    {
-        return (new self(fn() => $this->billable->anikeenId()
-            ->request('PUT', sprintf('v1/subscriptions/%s/checkout', $this->id))))
-            ->setBillable($this->billable);
-    }
-
-    /**
-     * Revoke a given running subscription from the current user.
-     *
-     * @throws Throwable
-     */
-    public function revoke(bool $refund = false): self
-    {
-        $attributes = [
-            'refund' => $refund,
-        ];
-
-        return (new self(fn() => $this->billable->anikeenId()
-            ->request('PUT', sprintf('v1/subscriptions/%s/revoke', $this->id), $attributes)))
-            ->setBillable($this->billable);
-    }
-
-    /**
-     * Pause a given running subscription from the current user.
-     *
-     * @throws Throwable
-     */
-    public function pause(): self
-    {
-        return (new self(fn() => $this->billable->anikeenId()
-            ->request('PUT', sprintf('v1/subscriptions/%s/pause', $this->id))))
-            ->setBillable($this->billable);
-    }
-
-    /**
-     * Resume a given running subscription from the current user.
-     *
-     * @throws Throwable
-     */
-    public function resume(): self
-    {
-        return (new self(fn() => $this->billable->anikeenId()
-            ->request('PUT', sprintf('v1/subscriptions/%s/resume', $this->id))))
-            ->setBillable($this->billable);
-    }
-}
+<?php
+
+namespace Anikeen\Id\Resources;
+
+use Anikeen\Id\Concerns\HasBillable;
+use Anikeen\Id\Concerns\HasConfirmationUrl;
+use Anikeen\Id\Concerns\HasSubscriptionStatus;
+use Anikeen\Id\Contracts\AppTokenRepository;
+use Throwable;
+
+/**
+ * @property string $id
+ * @property string $name
+ * @property string $description
+ * @property string $unit
+ * @property float $price
+ * @property ?float $monthly_cap net, at most this per calendar month (hour and day units)
+ * @property ?float $expected_monthly_price gross estimate for a month (720 hours, at most the monthly cap)
+ * @property ?string $predecessor_id the subscription this one replaced (a resize); they share the monthly cap
+ * @property float $vat_rate
+ * @property array $payload
+ * @property bool $active
+ * @property bool $autorenew
+ * @property bool $cancelled
+ * @property ?string $status draft, trial, active, paused, cancelling, expired or cancelled, see status()
+ * @property ?string $starts_at
+ * @property string $ends_at
+ * @property ?string $cancels_at when a scheduled cancellation takes effect
+ * @property ?string $trial_ends_at
+ * @property null|string $confirmation_url where the user confirms it (third-party apps)
+ */
+class Subscription extends BaseResource
+{
+    use HasBillable;
+    use HasConfirmationUrl;
+    use HasSubscriptionStatus;
+
+    /**
+     * Update a given subscription from the current user.
+     *
+     * @param array{
+     *      group: string,
+     *      name: string,
+     *      description: null|string,
+     *      unit: string,
+     *      price: float,
+     *      monthly_cap?: null|float,
+     *      vat_rate: float,
+     *      payload: null|array,
+     *      ends_at: null|string
+     *  } $attributes The subscription data:
+     *    - group:          The group (optional)
+     *    - name:           The name (required when set)
+     *    - description:    The description (optional)
+     *    - unit:           The unit (required when set, e.g. "hour", "day", "week", "month", "year")
+     *    - price:          The price per unit (required when set)
+     *    - monthly_cap:    Net, at most this per calendar month (hour and day units; optional)
+     *    - vat_rate:       The VAT rate (required when set)
+     *    - payload:        The payload (optional)
+     *    - ends_at:        The end date (optional)
+     * @throws Throwable
+     */
+    public function update(array $attributes): self
+    {
+        return (new self(fn() => $this->billable->anikeenId()
+            ->request('PUT', sprintf('v1/subscriptions/%s', $this->id), $attributes)))
+            ->setBillable($this->billable);
+    }
+
+    /**
+     * Force given subscription to check out (trusted apps only).
+     *
+     * @throws Throwable
+     */
+    public function checkout(): self
+    {
+        return (new self(fn() => $this->billable->anikeenId()
+            ->request('PUT', sprintf('v1/subscriptions/%s/checkout', $this->id))))
+            ->setBillable($this->billable);
+    }
+
+    /**
+     * Revoke a given running subscription from the current user.
+     *
+     * @throws Throwable
+     */
+    public function revoke(bool $refund = false): self
+    {
+        $attributes = [
+            'refund' => $refund,
+        ];
+
+        return (new self(fn() => $this->billable->anikeenId()
+            ->request('PUT', sprintf('v1/subscriptions/%s/revoke', $this->id), $attributes)))
+            ->setBillable($this->billable);
+    }
+
+    /**
+     * Pause a given running subscription from the current user.
+     *
+     * @throws Throwable
+     */
+    public function pause(): self
+    {
+        return (new self(fn() => $this->billable->anikeenId()
+            ->request('PUT', sprintf('v1/subscriptions/%s/pause', $this->id))))
+            ->setBillable($this->billable);
+    }
+
+    /**
+     * Resume a given running subscription from the current user.
+     *
+     * @throws Throwable
+     */
+    public function resume(): self
+    {
+        return (new self(fn() => $this->billable->anikeenId()
+            ->request('PUT', sprintf('v1/subscriptions/%s/resume', $this->id))))
+            ->setBillable($this->billable);
+    }
+}