Merge pull request #14 from anikeen-com/docs/remove-live-test-hint

Document payments end to end, add subscription status helpers

CLAUDE.md

@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+Guidance for Claude Code (and other contributors) working in this repository.
+
+## What this is
+
+`anikeen/id` is the public PHP client for the Anikeen ID API, shipped as a Laravel package
+(Laravel 11–13, PHP 8.2+). It covers OAuth/Socialite login, an API token guard, and the billing
+API (subscriptions, orders, checkout sessions, shipments, invoices, webhooks). This is a public
+repo published on Packagist: never commit secrets, internal hostnames or customer data.
+
+## Commands
+
+```shell
+composer install
+composer test                                   # vendor/bin/phpunit
+vendor/bin/phpunit --filter AppSubscriptionsTest
+composer docs                                   # regenerate README.md from README.stub
+```
+
+CI (`.github/workflows/tests.yml`) runs PHPUnit on PHP 8.3 and 8.4.
+
+## Layout
+
+- `src/Id/AnikeenId.php` – the API client (singleton, facade `AnikeenId`). Reads
+  `config('services.anikeen.*')`; `mode=staging` switches to the staging base URL unless
+  `base_url` is set. `request()` wraps Guzzle and returns a `Result`.
+- `src/Id/Billable.php` – trait for the app's user model; composes the `Concerns/Manages*` traits.
+  Its API caches are declared properties on purpose (undeclared ones would be treated as Eloquent
+  attributes and break `save()`). Add a new cache property there when a concern caches.
+- `src/Id/Concerns/` – one trait per API area. Traits on `AnikeenId` act as the app/client;
+  traits on `Billable` act for one user.
+- `src/Id/Resources/` – `BaseResource` (single object, throws `ResourceException`, or
+  `ConfirmationRequiredException` for `confirmation_required`) and `BaseCollection` (lists,
+  lazily built via `::builder()`).
+- `src/Id/Resources/App*` – "app" variants that use the app's own client-credentials token
+  (`AnikeenId::asApp()`, `Support/AppRequest`) instead of the user's token, for trusted apps.
+  They throw `Exceptions/ApiException` with a stable `error` code and must not send any request
+  until a method is called.
+- `src/Id/Auth/`, `Providers/AnikeenIdServiceProvider.php`, `Http/Middleware/` – the `anikeen`
+  guard driver and user provider, JWT validation (`Helpers/JwtParser.php` with the bundled
+  `oauth-public*.key`), scope middleware.
+- `src/Id/Webhooks/` – signature verification (`Webhook::constructEvent`) and `EventType`
+  constants.
+- `src/Support/Query.php` – query-string builder.
+- `generator/generate-docs.php` – reflects the public methods of `AnikeenId` and `Billable` traits
+  into the README.
+
+## Conventions
+
+- **README:** edit `README.stub`, never `README.md` directly, then run `composer docs`. The
+  `<!-- GENERATED-DOCS -->` marker is replaced with the method reference. Commit both files.
+- **New endpoints:** add a method to the matching `Concerns/Manages*` trait (or a resource class),
+  document request attributes with an `array{…}` PHPDoc shape and a short description per key,
+  and add an example to `README.stub` when it is a new feature.
+- **Tests:** extend `Anikeen\Id\Tests\TestCase` (Orchestra Testbench). No live API: queue
+  responses with `$this->respond($status, $body)` (Guzzle `MockHandler`) and assert the sent
+  requests via `$this->sent` / `$this->sentJson($i)` – method, path, `Authorization` header and
+  JSON body. The app token is faked as `app-token`.
+- **Compatibility:** this is a library used by several apps. Keep public method signatures
+  backwards compatible; add optional parameters instead of changing existing ones.
+- Code, comments, docs and commit messages in English. Commit subjects are short, imperative,
+  sentence case (e.g. "Ship orders: shipments with delivery notes"). Work happens on feature
+  branches merged via PR into `main`.

README.md

@@ -6,14 +6,21 @@
 
 PHP Anikeen ID API Client for Laravel 11+
 
+Sign in with Anikeen ID and let your users pay with their Anikeen ID account: one-off orders,
+subscriptions and physical goods, with invoices, VAT and payment handled by Anikeen ID.
+
 ## Table of contents
 
 1. [Installation](#installation)
 2. [Configuration](#configuration)
-3. [General](#general)
-4. [Examples](#examples)
-5. [Documentation](#documentation)
-6. [Development](#Development)
+3. [Sign in with Anikeen ID](#sign-in-with-anikeen-id)
+4. [Payments](#payments)
+5. [Trusted apps](#trusted-apps)
+6. [API authentication](#api-authentication)
+7. [General](#general)
+8. [Examples](#examples)
+9. [Documentation](#documentation)
+10. [Development](#development)
 
 ## Installation
 
@@ -23,12 +30,20 @@ composer require anikeen/id
 
 ## Configuration
 
-Add environmental variables to your `.env` file:
+Register your app in Anikeen ID first. You need:
+
+- an OAuth client with your callback URL as redirect URI (e.g. `https://shop.test/auth/callback`),
+- a webhook endpoint (e.g. `https://shop.test/webhooks/anikeen`) if you sell something; Anikeen ID
+  shows its signing secret `whsec_…`,
+- optionally a logo, shown to your users on the login and confirmation pages.
+
+Add the credentials to your `.env` file:
 
 ```
 ANIKEEN_ID_KEY=
 ANIKEEN_ID_SECRET=
 ANIKEEN_ID_CALLBACK_URL=http://localhost/auth/callback
+ANIKEEN_ID_WEBHOOK_SECRET=
 ```
 
 To switch from `production` to `staging` use following variable:
@@ -48,9 +63,12 @@ Add to `config/services.php` file:
     'client_secret' => env('ANIKEEN_ID_SECRET'),
     'redirect' => env('ANIKEEN_ID_CALLBACK_URL'),
     'base_url' => env('ANIKEEN_ID_BASE_URL'),
+    'webhook_secret' => env('ANIKEEN_ID_WEBHOOK_SECRET'),
 ],
 ```
 
+## Sign in with Anikeen ID
+
 ### Event Listener
 
 In Laravel 11, the default EventServiceProvider provider was removed. Instead, add the listener using the listen method on the Event facade, in your `AppServiceProvider` boot method:
@@ -64,21 +82,19 @@ public function boot(): void
 }
 ```
 
-### Registering Middleware
+### User model
 
-Append it to the global middleware stack in your application's `bootstrap/app.php` file:
+Your users table needs the user's Anikeen ID and their tokens:
 
 ```php
-->withMiddleware(function (Middleware $middleware) {
-    $middleware->web(append: [
-        \Anikeen\Id\Http\Middleware\CreateFreshApiToken::class,
-    ]);
-})
+Schema::table('users', function (Blueprint $table) {
+    $table->string('anikeen_id')->nullable()->unique();
+    $table->text('anikeen_id_access_token')->nullable();
+    $table->text('anikeen_id_refresh_token')->nullable();
+});
 ```
 
-### Implementing Billable
-
-To implement the `Billable` trait, you need to add the `Billable` trait to your user model.
+Add the `Billable` trait to the user model. Keep the tokens encrypted and out of JSON:
 
 ```php
 use Anikeen\Id\Billable;
@@ -87,11 +103,362 @@ class User extends Authenticatable
 {
     use Billable;
 
-    // Your model code...
+    protected $hidden = ['password', 'remember_token', 'anikeen_id_access_token', 'anikeen_id_refresh_token'];
+
+    protected function casts(): array
+    {
+        return [
+            'anikeen_id_access_token' => 'encrypted',
+            'anikeen_id_refresh_token' => 'encrypted',
+        ];
+    }
 }
 ```
 
-then, you can use the `Billable` trait methods in your user model.
+All user methods (`$user->orders()`, `$user->subscriptions()`, …) call the API with the user's
+access token from `anikeen_id_access_token`.
+
+### Login and callback
+
+Ask for the scopes your app needs (see [Scope](src/Id/Enums/Scope.php)). To sell orders and
+subscriptions, a shop typically asks for:
+
+```php
+use Laravel\Socialite\Facades\Socialite;
+
+Route::get('auth/redirect', fn () => Socialite::driver('anikeen')
+    ->scopes(['user:read', 'addresses:read', 'orders', 'subscriptions'])
+    ->redirect());
+
+Route::get('auth/callback', function () {
+    $account = Socialite::driver('anikeen')->user();
+
+    $user = User::updateOrCreate(['anikeen_id' => $account->getId()], [
+        'name' => $account->getName() ?: $account->getNickname(),
+        'email' => $account->getEmail(),
+        'anikeen_id_access_token' => $account->token,
+        'anikeen_id_refresh_token' => $account->refreshToken,
+    ]);
+
+    Auth::login($user, remember: true);
+
+    return redirect()->intended('/');
+});
+```
+
+Access tokens expire. Get a new one with the refresh token (or send the user through the login
+again):
+
+```php
+$result = app(\Anikeen\Id\AnikeenId::class)->refreshToken($user->anikeen_id_refresh_token);
+
+if ($result->success()) {
+    $user->update([
+        'anikeen_id_access_token' => $result->data()->access_token,
+        'anikeen_id_refresh_token' => $result->data()->refresh_token,
+    ]);
+}
+```
+
+### Change the default access token / refresh token field name
+
+If your access / refresh token fields differ from the default `anikeen_id_access_token` / `anikeen_id_refresh_token`, you can specify the field name in the `AppServiceProvider` boot method:
+
+```php
+use Anikeen\Id\AnikeenId;
+
+public function boot(): void
+{
+    AnikeenId::useAccessTokenField('anikeen_id_access_token');
+    AnikeenId::useRefreshTokenField('anikeen_id_refresh_token');
+}
+```
+
+## Payments
+
+### Which way fits?
+
+| You want to sell | Use | Token | Who starts the payment |
+|---|---|---|---|
+| One-off purchases (digital or physical goods) | [Orders](#selling-an-order) | user | the user, on Anikeen ID |
+| Something that recurs (a pass, a plan) | [Subscriptions](#subscriptions) | user | the user, on Anikeen ID |
+| Several subscriptions in one step | [Checkout sessions](#checkout-sessions-the-user-confirms-several-subscriptions-at-once) | user or app | the user, on Anikeen ID |
+| Usage billing from your backend, without the user online | [App subscriptions](#app-subscriptions-trusted-apps-no-user-token) | app | your app (trusted apps only) |
+
+Most apps are third-party apps: they create an order or subscription as a draft, send the user to
+Anikeen ID to confirm and pay, and get the user back afterwards. Anikeen ID shows the items, asks
+for missing addresses, takes the payment and writes the invoice. Trusted apps (operated by
+Anikeen) can also charge directly; see [Trusted apps](#trusted-apps).
+
+The flow, as in a typical shop:
+
+1. The user signs in with Anikeen ID ([above](#sign-in-with-anikeen-id)).
+2. Your app creates the order: `$user->orders()->create([...])`.
+3. Redirect the user to `$order->confirmationUrl($returnUrl)`.
+4. The user confirms and pays on Anikeen ID, then comes back to `$returnUrl?status=…&order=…`.
+5. Your app reads the order through the API (never trust the query string) and shows the result.
+6. The `order.completed` webhook arrives; fulfil the order there.
+
+### Selling an order
+
+```php
+use Anikeen\Id\Exceptions\ResourceException;
+
+$order = $user->orders()->create([
+    'billing_address_id' => $user->getUserData()->billing_address_id,
+    'items' => [
+        ['type' => 'digital', 'name' => 'Sticker pack', 'unit' => 'piece', 'units' => 1, 'gross_price' => '9.99'],
+    ],
+]);
+
+$shopOrder = ShopOrder::create(['user_id' => $user->id, 'anikeen_id' => $order->id, 'status' => $order->status]); // your own order model
+
+return redirect()->away($order->confirmationUrl(route('orders.return', $shopOrder)));
+// later: https://shop.test/orders/1/return?status=completed&order=01J…
+```
+
+When the user has no billing address on Anikeen ID yet, pass one instead of the ID. A name and
+the country are enough; the user completes it on the confirmation page:
+
+```php
+'billing_address' => ['first_name' => 'Ada', 'last_name' => 'Lovelace', 'country_iso' => 'DE', 'email' => $user->email],
+```
+
+Back in your app, read the order to know its state:
+
+```php
+Route::get('orders/{shopOrder}/return', function (ShopOrder $shopOrder) {
+    $order = auth()->user()->orders()->find($shopOrder->anikeen_id);
+
+    $shopOrder->update(['status' => $order->status]);
+
+    return redirect()->route('orders.show', $shopOrder);
+});
+```
+
+The order's `status`:
+
+| `status` | Meaning |
+|---|---|
+| `draft` | Created, not confirmed by the user yet |
+| `pending` | Confirmed, the payment is still processing |
+| `completed` | Paid |
+| `cancelled` | The user cancelled, or it wasn't confirmed within 24 hours |
+
+`return_url` must have the origin of one of your app's redirect URIs. The `status` in its query
+string (`completed`, `pending` or `cancelled`) is only a hint for the message you show.
+
+`checkout()` on such a draft throws `ConfirmationRequiredException`; its `confirmationUrl`
+points to the same page. Trusted apps keep checking out directly.
+
+### Prices and VAT
+
+Anikeen ID calculates VAT from the user's billing address and the item `type`:
+
+| `type` | For | VAT in Germany |
+|---|---|---|
+| `digital` | Downloads, streams, services | 19 % |
+| `physical` | Goods you ship | 19 % |
+| `physical-reduced` | Goods with the reduced rate (books, event tickets, …) | 7 % |
+
+Give each item either `gross_price` (VAT included, what the user pays) or `price` (net), per unit.
+`unit` is `piece` or `onetime` for orders; `units` is the quantity. Subscription prices are always
+net per unit (`hour`, `day`, `week`, `month`, `year`).
+
+To show a total before the user confirms, ask for a preview:
+
+```php
+$preview = app(\Anikeen\Id\AnikeenId::class)->createOrderPreview([
+    'country_iso' => 'DE',
+    'items' => [['type' => 'physical', 'name' => 'T-shirt', 'gross_price' => '24.90', 'unit' => 'piece', 'units' => 1]],
+])->shift();
+
+$preview->gross_total;
+```
+
+### Physical goods and shipments
+
+Physical goods need a shipping address (`first_name`, `last_name`, `address`, `postal_code`,
+`city`, `country_iso`). The user can change both addresses on the confirmation page, so read the
+shipping address from the order (or the `order.completed` webhook) before you ship. An item's
+`image_url` is copied to Anikeen ID and stays visible on the order and invoice:
+
+```php
+$order = $user->orders()->create([
+    'billing_address_id' => $addressId,
+    'shipping_address' => ['first_name' => 'Ada', 'last_name' => 'Lovelace', 'address' => 'Main St', 'house_number' => '1', 'postal_code' => '10115', 'city' => 'Berlin', 'country_iso' => 'DE'],
+    'items' => [
+        ['type' => 'physical', 'name' => 'T-shirt', 'unit' => 'piece', 'units' => 1, 'gross_price' => '24.90', 'image_url' => 'https://shop.test/img/shirt.png'],
+        ['type' => 'physical-reduced', 'name' => 'Artbook', 'unit' => 'piece', 'units' => 1, 'gross_price' => '19.95'],
+    ],
+]);
+```
+
+Once a paid order is sent, create a shipment. Anikeen ID adds its delivery note to the user's
+order documents (with the tracking link), mails it to the user (`'notify_customer' => false` if
+your shop sends its own mail) and sends `order.shipped` to your webhook endpoints.
+Without `items`, everything physical that is left is shipped; partial deliveries name the items:
+
+```php
+$order = $user->orders()->find($orderId);
+
+$shipment = $order->shipments()->create([
+    'carrier' => 'DHL',
+    'tracking_number' => '00340434161234567890',
+    'tracking_url' => 'https://www.dhl.de/…?piececode=00340434161234567890',
+    // 'items' => [['order_item_id' => $itemId, 'units' => 1]],
+]);
+
+$shipment->number;          // LS-2026-0001
+$shipment->deliveryNote();  // the delivery note as PDF
+```
+
+To know what is left to ship, compare the order's items with its shipments:
+
+```php
+$items = $order->orderItems()->toArray();     // id, type, name, units, …
+$shipments = $order->shipments()->toArray();  // each with items: [{order_item_id, units}]
+```
+
+Only the app that created the order (or a trusted app) can ship it, and only once it is paid.
+
+### Subscriptions
+
+Subscriptions work like orders: create a draft, let the user confirm it, read it back.
+
+```php
+$subscription = $user->subscriptions()->create([
+    'name' => 'Pixel Stream Pass',
+    'description' => 'All streams, every month',
+    'unit' => 'month',
+    'price' => 6.714286,           // net per unit, 7.99 with 19 % VAT
+]);
+
+return redirect()->away($subscription->confirmationUrl(route('pass.return')));
+// later: https://shop.test/pass/return?status=completed&subscription=01J…
+```
+
+After the return, read the subscription and check its state:
+
+```php
+$subscription = $user->subscriptions()->find($id);
+
+if ($subscription->isActive()) {
+    // grant access
+}
+```
+
+`status()` returns one of the `Anikeen\Id\Enums\SubscriptionStatus` constants (the API sends the
+same value as `status`):
+
+| `status()` | Meaning | `isActive()` |
+|---|---|---|
+| `draft` | Created, not confirmed by the user yet | no |
+| `trial` | Running, in its trial period | yes |
+| `active` | Running and billed | yes |
+| `paused` | Runs until the paid period ends, then expires (`resume()` to continue) | yes |
+| `cancelling` | Runs until a scheduled cancellation takes effect | yes |
+| `expired` | Paused and ran out; `resume()` starts a new period | no |
+| `cancelled` | Cancelled for good | no |
+
+There are shortcuts for each: `isDraft()`, `isPaused()`, `isCancelling()`, `isExpired()`,
+`isCancelled()`. App subscriptions (`appSubscriptions()`) have the same methods.
+
+### Webhooks
+
+Anikeen ID sends `order.*`, `subscription.*` and `checkout.*` events to the webhook endpoints of
+your app (see [`EventType`](src/Id/Webhooks/EventType.php) for all of them). Verify each request
+with the raw body and answer 2xx within 10 seconds; failed deliveries are retried for about three
+days.
+
+Exclude the route from CSRF protection in `bootstrap/app.php`:
+
+```php
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->validateCsrfTokens(except: ['webhooks/*']);
+})
+```
+
+```php
+use Anikeen\Id\Exceptions\SignatureVerificationException;
+use Anikeen\Id\Webhooks\EventType;
+use Anikeen\Id\Webhooks\Webhook;
+
+Route::post('webhooks/anikeen', function (Request $request) {
+    try {
+        $event = Webhook::constructEvent($request->getContent(), $request->header('Anikeen-Signature'), config('services.anikeen.webhook_secret'));
+    } catch (SignatureVerificationException) {
+        abort(400);
+    }
+
+    if (! ProcessedEvent::firstOrCreate(['id' => $event['id']])->wasRecentlyCreated) {
+        return response()->noContent(); // already handled
+    }
+
+    $object = $event['data']['object'];
+
+    match ($event['type']) {
+        EventType::ORDER_COMPLETED => Shop::fulfil($object['id'], $object['shipping_address']),
+        EventType::ORDER_CANCELLED => Shop::release($object['id']),
+        EventType::SUBSCRIPTION_ACTIVATED => Pass::grant($object['id']),
+        EventType::SUBSCRIPTION_CANCELLED => Pass::revoke($object['id']),
+        EventType::CHECKOUT_COMPLETED => Panel::provision($object['subscription_ids']),
+        default => null,
+    };
+
+    return response()->noContent();
+});
+```
+
+`data.object` is the order, subscription or checkout session as the API returns it. Events can
+arrive more than once or out of order: use `$event['id']` to skip duplicates, and reload the
+object through the API when the current state matters. The admin panel can send a
+`webhook.test` event to check your endpoint.
+
+### Errors
+
+Calls with the user's token throw `Anikeen\Id\Exceptions\ResourceException` when Anikeen ID
+rejects them; `getCode()` is the HTTP status (e.g. `422` for invalid data, `404` for an unknown
+ID) and `getMessage()` the reason. App calls (`app*()`) throw its subclass `ApiException`, which
+adds a stable `error` code. Catching `ResourceException` covers both:
+
+```php
+use Anikeen\Id\Exceptions\ResourceException;
+
+try {
+    $order = $user->orders()->create($attributes);
+} catch (ResourceException $e) {
+    report($e);
+
+    return back()->with('error', 'The order could not be created.');
+}
+```
+
+### Testing
+
+Develop against staging (`ANIKEEN_ID_MODE=staging`) with an OAuth client registered there.
+Payments on staging run in Stripe's test mode: pay with Stripe's
+[test cards](https://docs.stripe.com/testing), e.g. `4242 4242 4242 4242` with any future expiry
+date and any CVC. No money is charged.
+Point `ANIKEEN_ID_BASE_URL` at your own Anikeen ID instance if you run one locally.
+
+In unit tests, swap the HTTP client for a Guzzle `MockHandler`:
+
+```php
+$mock = new \GuzzleHttp\Handler\MockHandler([
+    new \GuzzleHttp\Psr7\Response(201, ['Content-Type' => 'application/json'], json_encode(['data' => ['id' => '01JORDER', 'status' => 'draft']])),
+]);
+
+$this->app->instance(AnikeenId::class, (new AnikeenId())->setHttpClient(new \GuzzleHttp\Client([
+    'handler' => \GuzzleHttp\HandlerStack::create($mock),
+    'base_uri' => 'https://id.test/api/',
+])));
+```
+
+## Trusted apps
+
+Apps operated by Anikeen can be marked as trusted. They can charge without asking the user and
+use their own token (client credentials), so billing keeps working when the user's login expired.
 
 ### App subscriptions (trusted apps, no user token)
 
@@ -166,7 +533,7 @@ period, confirms (all subscriptions start, or none) or cancels, and returns to `
 Open sessions expire after 24 hours with their drafts. Trusted apps can still check out directly;
 sessions are opt-in.
 
-Example: the Console's builder ("Jetzt kaufen") with several products and coupon prices:
+Example: a cart with several products and coupon prices:
 
 ```php
 use Anikeen\Id\Exceptions\ApiException;
@@ -214,113 +581,22 @@ While a session is open, its subscriptions can't be checked out or repriced by t
 `subscription.activated` / `subscription.cancelled` are still sent per subscription, before the
 `checkout.*` event of the session.
 
-### Selling as a third-party app (user confirms on Anikeen ID)
 
-Apps that are not trusted can create orders and subscriptions for the signed-in user (user token),
-but can't charge them. The user confirms on Anikeen ID and comes back to your `return_url`:
+## API authentication
+
+Use this when your own API accepts access tokens issued by Anikeen ID.
+
+### Registering Middleware
+
+To call your API from your own frontend with the user's session, append the middleware to the
+web middleware group in your application's `bootstrap/app.php` file:
 
 ```php
-use Anikeen\Id\Exceptions\ConfirmationRequiredException;
-
-$order = $user->orders()->create([
-    'billing_address_id' => $addressId,
-    'items' => [['type' => 'digital', 'name' => 'Sticker pack', 'unit' => 'piece', 'units' => 1, 'gross_price' => '9.99']],
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->web(append: [
+        \Anikeen\Id\Http\Middleware\CreateFreshApiToken::class,
     ]);
-
-return redirect($order->confirmationUrl(route('shop.done')));
-// later: https://your-app.test/shop/done?status=completed&order=01J…
-```
-
-`return_url` must have the origin of one of your app's redirect URIs. `status` is `completed`,
-`pending` (payment still processing) or `cancelled`; check it with `$user->orders()->find($id)`
-instead of trusting the query string. Subscriptions work the same way
-(`$user->subscriptions()->create([...])->confirmationUrl(...)`, `&subscription=…`).
-Unconfirmed bookings are cancelled after 24 hours.
-
-Physical goods need a shipping address (`first_name`, `last_name`, `address`, `postal_code`,
-`city`, `country_iso`). The user can change both addresses on the confirmation page, so read the
-shipping address from the order (or the `order.completed` webhook) before you ship. An item's
-`image_url` is copied to Anikeen ID and stays visible on the order and invoice:
-
-```php
-$order = $user->orders()->create([
-    'billing_address_id' => $addressId,
-    'shipping_address' => ['first_name' => 'Ada', 'last_name' => 'Lovelace', 'address' => 'Main St', 'house_number' => '1', 'postal_code' => '10115', 'city' => 'Berlin', 'country_iso' => 'DE'],
-    'items' => [
-        ['type' => 'physical', 'name' => 'T-shirt', 'unit' => 'piece', 'units' => 1, 'gross_price' => '24.90', 'image_url' => 'https://shop.test/img/shirt.png'],
-        ['type' => 'physical-reduced', 'name' => 'Artbook', 'unit' => 'piece', 'units' => 1, 'gross_price' => '19.95'],
-    ],
-]);
-```
-
-Once a paid order is sent, create a shipment. Anikeen ID adds its delivery note to the user's
-order documents (with the tracking link), mails it to the user (`'notify_customer' => false` if
-your shop sends its own mail) and sends `order.shipped` to your webhook endpoints.
-Without `items`, everything physical that is left is shipped; partial deliveries name the items:
-
-```php
-$order = $user->orders()->find($orderId);
-
-$shipment = $order->shipments()->create([
-    'carrier' => 'DHL',
-    'tracking_number' => '00340434161234567890',
-    'tracking_url' => 'https://www.dhl.de/…?piececode=00340434161234567890',
-    // 'items' => [['order_item_id' => $itemId, 'units' => 1]],
-]);
-
-$shipment->number;          // LS-2026-0001
-$shipment->deliveryNote();  // the delivery note as PDF
-```
-
-Only the app that created the order (or a trusted app) can ship it, and only once it is paid.
-
-`checkout()` on such a draft throws `ConfirmationRequiredException`; its `confirmationUrl`
-points to the same page. Trusted apps keep checking out directly.
-
-### Webhooks
-
-Anikeen ID sends `order.*`, `subscription.*` and `checkout.*` events to the webhook endpoints of your app (set up
-in the Anikeen ID admin panel, which also shows the signing secret `whsec_…`). Verify each request
-with the raw body and answer 2xx within 10 seconds; failed deliveries are retried for about three days.
-
-```php
-use Anikeen\Id\Exceptions\SignatureVerificationException;
-use Anikeen\Id\Webhooks\EventType;
-use Anikeen\Id\Webhooks\Webhook;
-
-Route::post('webhooks/anikeen', function (Request $request) {
-    try {
-        $event = Webhook::constructEvent($request->getContent(), $request->header('Anikeen-Signature'), config('services.anikeen.webhook_secret'));
-    } catch (SignatureVerificationException) {
-        abort(400);
-    }
-
-    match ($event['type']) {
-        EventType::ORDER_COMPLETED => Shop::fulfil($event['data']['object']['id']),
-        EventType::SUBSCRIPTION_CANCELLED => Panel::suspend($event['data']['object']['id']),
-        EventType::CHECKOUT_COMPLETED => Panel::provision($event['data']['object']['subscription_ids']),
-        default => null,
-    };
-
-    return response()->noContent();
-})->withoutMiddleware(VerifyCsrfToken::class);
-```
-
-Events can arrive more than once or out of order: use `$event['id']` to skip duplicates, and
-reload the object through the API when the current state matters.
-
-### Change the default access token / refresh token field name
-
-If you access / refresh token fields differs from the default `anikeen_id_access_token` / `anikeen_id_refresh_token`, you can specify the field name in the `AppServiceProvider` boot method:
-
-```php
-use Anikeen\Id\AnikeenId;
-
-public function boot(): void
-{
-    AnikeenId::useAccessTokenField('anikeen_id_access_token');
-    AnikeenId::useRefreshTokenField('anikeen_id_refresh_token');
-}
+})
 ```
 
 ### Implementing Auth (API tokens)
@@ -408,70 +684,36 @@ $anikeenId = $anikeenId->withClientSecret('abc123');
 $anikeenId = $anikeenId->withToken('abcdef123456');
 ```
 
-#### Error handling for an unsuccessful query:
+#### Results and resources
+
+Low-level methods on `AnikeenId` (e.g. `getAuthedUser()`, `createOrderPreview()`,
+`refreshToken()`) return a `Result`. Check it before you use it:
 
 ```php
-$result = $anikeenId->sshKeysByUserId('someInvalidId');
+$result = $anikeenId->getAuthedUser();
 
-// Check, if the query was successfully
 if (!$result->success()) {
     die('Ooops: ' . $result->error());
 }
+
+$user = $result->shift(); // the object, or the first item of a list
 ```
 
-#### Shift result to get single key data:
-
-```php
-$result = $anikeenId->sshKeysByUserId('someValidId');
-
-$sshKey = $result->shift();
-
-echo $sshKey->name;
-```
+Resource methods (`$user->orders()`, `$anikeenId->sshKeysByUserId()`, …) return objects and throw
+`ResourceException` instead (see [Errors](#errors)).
 
 ## Examples
 
-#### Get User SSH Key
+#### Get User SSH Keys
+
+Uses the app's own token (client credentials):
 
 ```php
-$anikeenId = new Anikeen\IdAnikeenId();
-
-$anikeenId->setClientId('abc123');
-
-// Get SSH Key by User ID
-$result = $anikeenId->sshKeysByUserId('someValidId');
-
-// Check, if the query was successfully
-if (!$result->success()) {
-    die('Ooops: ' . $result->error());
-}
-
-// Shift result to get single key data
-$sshKey = $result->shift();
+$sshKeys = app(Anikeen\Id\AnikeenId::class)->sshKeysByUserId($anikeenUserId);
 
+foreach ($sshKeys->toArray() as $sshKey) {
     echo $sshKey->name;
-```
-
-#### Create Order Preview
-
-```php
-$anikeenId = new \Anikeen\Id\AnikeenId();
-
-// Create new Order Preview
-$result = $anikeenId->createOrderPreview([
-    'country_iso' => 'de',
-    'items' => [
-        [
-            'type' => 'physical',
-            'name' => 'Test',
-            'price' => 2.99,
-            'unit' => 'onetime',
-            'units' => 1,
-        ]
-    ]
-])->shift();
-
-echo $preview->gross_total;
+}
 ```
 
 #### OAuth Tokens
@@ -479,22 +721,13 @@ echo $preview->gross_total;
 ```php
 $anikeenId = new Anikeen\Id\AnikeenId();
 
-$anikeenId->setClientId('abc123');
 $anikeenId->setToken('abcdef123456');
 
-$result = $anikeenId->getAuthedUser();
-
-$user = $userResult->shift();
+$user = $anikeenId->getAuthedUser()->shift();
 ```
 
 ```php
-$anikeenId->setToken('uvwxyz456789');
-
-$result = $anikeenId->getAuthedUser();
-```
-
-```php
-$result = $anikeenId->withToken('uvwxyz456789')->getAuthedUser();
+$user = $anikeenId->withToken('uvwxyz456789')->getAuthedUser()->shift();
 ```
 
 #### Facade
@@ -502,7 +735,7 @@ $result = $anikeenId->withToken('uvwxyz456789')->getAuthedUser();
 ```php
 use Anikeen\Id\Facades\AnikeenId;
 
-AnikeenId::withClientId('abc123')->withToken('abcdef123456')->getAuthedUser();
+AnikeenId::withToken('abcdef123456')->getAuthedUser();
 ```
 
 ## Documentation
@@ -678,7 +911,7 @@ public function getBillable(): Billable
 ```
 
 
-[**OAuth Scopes Enums**](https://github.com/anikeen-com/id/blob/main/src/Enums/Scope.php)
+[**OAuth Scopes Enums**](https://github.com/anikeen-com/id/blob/main/src/Id/Enums/Scope.php)
 
 ## Development
 
@@ -688,10 +921,6 @@ public function getBillable(): Billable
 composer test
 ```
 
-```shell
-BASE_URL=xxxx CLIENT_ID=xxxx CLIENT_KEY=yyyy CLIENT_ACCESS_TOKEN=zzzz composer test
-```
-
 #### Generate Documentation
 
 ```shell

README.stub

@@ -6,14 +6,21 @@
 
 PHP Anikeen ID API Client for Laravel 11+
 
+Sign in with Anikeen ID and let your users pay with their Anikeen ID account: one-off orders,
+subscriptions and physical goods, with invoices, VAT and payment handled by Anikeen ID.
+
 ## Table of contents
 
 1. [Installation](#installation)
 2. [Configuration](#configuration)
-3. [General](#general)
-4. [Examples](#examples)
-5. [Documentation](#documentation)
-6. [Development](#Development)
+3. [Sign in with Anikeen ID](#sign-in-with-anikeen-id)
+4. [Payments](#payments)
+5. [Trusted apps](#trusted-apps)
+6. [API authentication](#api-authentication)
+7. [General](#general)
+8. [Examples](#examples)
+9. [Documentation](#documentation)
+10. [Development](#development)
 
 ## Installation
 
@@ -23,12 +30,20 @@ composer require anikeen/id
 
 ## Configuration
 
-Add environmental variables to your `.env` file:
+Register your app in Anikeen ID first. You need:
+
+- an OAuth client with your callback URL as redirect URI (e.g. `https://shop.test/auth/callback`),
+- a webhook endpoint (e.g. `https://shop.test/webhooks/anikeen`) if you sell something; Anikeen ID
+  shows its signing secret `whsec_…`,
+- optionally a logo, shown to your users on the login and confirmation pages.
+
+Add the credentials to your `.env` file:
 
 ```
 ANIKEEN_ID_KEY=
 ANIKEEN_ID_SECRET=
 ANIKEEN_ID_CALLBACK_URL=http://localhost/auth/callback
+ANIKEEN_ID_WEBHOOK_SECRET=
 ```
 
 To switch from `production` to `staging` use following variable:
@@ -48,9 +63,12 @@ Add to `config/services.php` file:
     'client_secret' => env('ANIKEEN_ID_SECRET'),
     'redirect' => env('ANIKEEN_ID_CALLBACK_URL'),
     'base_url' => env('ANIKEEN_ID_BASE_URL'),
+    'webhook_secret' => env('ANIKEEN_ID_WEBHOOK_SECRET'),
 ],
 ```
 
+## Sign in with Anikeen ID
+
 ### Event Listener
 
 In Laravel 11, the default EventServiceProvider provider was removed. Instead, add the listener using the listen method on the Event facade, in your `AppServiceProvider` boot method:
@@ -64,21 +82,19 @@ public function boot(): void
 }
 ```
 
-### Registering Middleware
+### User model
 
-Append it to the global middleware stack in your application's `bootstrap/app.php` file:
+Your users table needs the user's Anikeen ID and their tokens:
 
 ```php
-->withMiddleware(function (Middleware $middleware) {
-    $middleware->web(append: [
-        \Anikeen\Id\Http\Middleware\CreateFreshApiToken::class,
-    ]);
-})
+Schema::table('users', function (Blueprint $table) {
+    $table->string('anikeen_id')->nullable()->unique();
+    $table->text('anikeen_id_access_token')->nullable();
+    $table->text('anikeen_id_refresh_token')->nullable();
+});
 ```
 
-### Implementing Billable
-
-To implement the `Billable` trait, you need to add the `Billable` trait to your user model.
+Add the `Billable` trait to the user model. Keep the tokens encrypted and out of JSON:
 
 ```php
 use Anikeen\Id\Billable;
@@ -87,11 +103,362 @@ class User extends Authenticatable
 {
     use Billable;
 
-    // Your model code...
+    protected $hidden = ['password', 'remember_token', 'anikeen_id_access_token', 'anikeen_id_refresh_token'];
+
+    protected function casts(): array
+    {
+        return [
+            'anikeen_id_access_token' => 'encrypted',
+            'anikeen_id_refresh_token' => 'encrypted',
+        ];
+    }
 }
 ```
 
-then, you can use the `Billable` trait methods in your user model.
+All user methods (`$user->orders()`, `$user->subscriptions()`, …) call the API with the user's
+access token from `anikeen_id_access_token`.
+
+### Login and callback
+
+Ask for the scopes your app needs (see [Scope](src/Id/Enums/Scope.php)). To sell orders and
+subscriptions, a shop typically asks for:
+
+```php
+use Laravel\Socialite\Facades\Socialite;
+
+Route::get('auth/redirect', fn () => Socialite::driver('anikeen')
+    ->scopes(['user:read', 'addresses:read', 'orders', 'subscriptions'])
+    ->redirect());
+
+Route::get('auth/callback', function () {
+    $account = Socialite::driver('anikeen')->user();
+
+    $user = User::updateOrCreate(['anikeen_id' => $account->getId()], [
+        'name' => $account->getName() ?: $account->getNickname(),
+        'email' => $account->getEmail(),
+        'anikeen_id_access_token' => $account->token,
+        'anikeen_id_refresh_token' => $account->refreshToken,
+    ]);
+
+    Auth::login($user, remember: true);
+
+    return redirect()->intended('/');
+});
+```
+
+Access tokens expire. Get a new one with the refresh token (or send the user through the login
+again):
+
+```php
+$result = app(\Anikeen\Id\AnikeenId::class)->refreshToken($user->anikeen_id_refresh_token);
+
+if ($result->success()) {
+    $user->update([
+        'anikeen_id_access_token' => $result->data()->access_token,
+        'anikeen_id_refresh_token' => $result->data()->refresh_token,
+    ]);
+}
+```
+
+### Change the default access token / refresh token field name
+
+If your access / refresh token fields differ from the default `anikeen_id_access_token` / `anikeen_id_refresh_token`, you can specify the field name in the `AppServiceProvider` boot method:
+
+```php
+use Anikeen\Id\AnikeenId;
+
+public function boot(): void
+{
+    AnikeenId::useAccessTokenField('anikeen_id_access_token');
+    AnikeenId::useRefreshTokenField('anikeen_id_refresh_token');
+}
+```
+
+## Payments
+
+### Which way fits?
+
+| You want to sell | Use | Token | Who starts the payment |
+|---|---|---|---|
+| One-off purchases (digital or physical goods) | [Orders](#selling-an-order) | user | the user, on Anikeen ID |
+| Something that recurs (a pass, a plan) | [Subscriptions](#subscriptions) | user | the user, on Anikeen ID |
+| Several subscriptions in one step | [Checkout sessions](#checkout-sessions-the-user-confirms-several-subscriptions-at-once) | user or app | the user, on Anikeen ID |
+| Usage billing from your backend, without the user online | [App subscriptions](#app-subscriptions-trusted-apps-no-user-token) | app | your app (trusted apps only) |
+
+Most apps are third-party apps: they create an order or subscription as a draft, send the user to
+Anikeen ID to confirm and pay, and get the user back afterwards. Anikeen ID shows the items, asks
+for missing addresses, takes the payment and writes the invoice. Trusted apps (operated by
+Anikeen) can also charge directly; see [Trusted apps](#trusted-apps).
+
+The flow, as in a typical shop:
+
+1. The user signs in with Anikeen ID ([above](#sign-in-with-anikeen-id)).
+2. Your app creates the order: `$user->orders()->create([...])`.
+3. Redirect the user to `$order->confirmationUrl($returnUrl)`.
+4. The user confirms and pays on Anikeen ID, then comes back to `$returnUrl?status=…&order=…`.
+5. Your app reads the order through the API (never trust the query string) and shows the result.
+6. The `order.completed` webhook arrives; fulfil the order there.
+
+### Selling an order
+
+```php
+use Anikeen\Id\Exceptions\ResourceException;
+
+$order = $user->orders()->create([
+    'billing_address_id' => $user->getUserData()->billing_address_id,
+    'items' => [
+        ['type' => 'digital', 'name' => 'Sticker pack', 'unit' => 'piece', 'units' => 1, 'gross_price' => '9.99'],
+    ],
+]);
+
+$shopOrder = ShopOrder::create(['user_id' => $user->id, 'anikeen_id' => $order->id, 'status' => $order->status]); // your own order model
+
+return redirect()->away($order->confirmationUrl(route('orders.return', $shopOrder)));
+// later: https://shop.test/orders/1/return?status=completed&order=01J…
+```
+
+When the user has no billing address on Anikeen ID yet, pass one instead of the ID. A name and
+the country are enough; the user completes it on the confirmation page:
+
+```php
+'billing_address' => ['first_name' => 'Ada', 'last_name' => 'Lovelace', 'country_iso' => 'DE', 'email' => $user->email],
+```
+
+Back in your app, read the order to know its state:
+
+```php
+Route::get('orders/{shopOrder}/return', function (ShopOrder $shopOrder) {
+    $order = auth()->user()->orders()->find($shopOrder->anikeen_id);
+
+    $shopOrder->update(['status' => $order->status]);
+
+    return redirect()->route('orders.show', $shopOrder);
+});
+```
+
+The order's `status`:
+
+| `status` | Meaning |
+|---|---|
+| `draft` | Created, not confirmed by the user yet |
+| `pending` | Confirmed, the payment is still processing |
+| `completed` | Paid |
+| `cancelled` | The user cancelled, or it wasn't confirmed within 24 hours |
+
+`return_url` must have the origin of one of your app's redirect URIs. The `status` in its query
+string (`completed`, `pending` or `cancelled`) is only a hint for the message you show.
+
+`checkout()` on such a draft throws `ConfirmationRequiredException`; its `confirmationUrl`
+points to the same page. Trusted apps keep checking out directly.
+
+### Prices and VAT
+
+Anikeen ID calculates VAT from the user's billing address and the item `type`:
+
+| `type` | For | VAT in Germany |
+|---|---|---|
+| `digital` | Downloads, streams, services | 19 % |
+| `physical` | Goods you ship | 19 % |
+| `physical-reduced` | Goods with the reduced rate (books, event tickets, …) | 7 % |
+
+Give each item either `gross_price` (VAT included, what the user pays) or `price` (net), per unit.
+`unit` is `piece` or `onetime` for orders; `units` is the quantity. Subscription prices are always
+net per unit (`hour`, `day`, `week`, `month`, `year`).
+
+To show a total before the user confirms, ask for a preview:
+
+```php
+$preview = app(\Anikeen\Id\AnikeenId::class)->createOrderPreview([
+    'country_iso' => 'DE',
+    'items' => [['type' => 'physical', 'name' => 'T-shirt', 'gross_price' => '24.90', 'unit' => 'piece', 'units' => 1]],
+])->shift();
+
+$preview->gross_total;
+```
+
+### Physical goods and shipments
+
+Physical goods need a shipping address (`first_name`, `last_name`, `address`, `postal_code`,
+`city`, `country_iso`). The user can change both addresses on the confirmation page, so read the
+shipping address from the order (or the `order.completed` webhook) before you ship. An item's
+`image_url` is copied to Anikeen ID and stays visible on the order and invoice:
+
+```php
+$order = $user->orders()->create([
+    'billing_address_id' => $addressId,
+    'shipping_address' => ['first_name' => 'Ada', 'last_name' => 'Lovelace', 'address' => 'Main St', 'house_number' => '1', 'postal_code' => '10115', 'city' => 'Berlin', 'country_iso' => 'DE'],
+    'items' => [
+        ['type' => 'physical', 'name' => 'T-shirt', 'unit' => 'piece', 'units' => 1, 'gross_price' => '24.90', 'image_url' => 'https://shop.test/img/shirt.png'],
+        ['type' => 'physical-reduced', 'name' => 'Artbook', 'unit' => 'piece', 'units' => 1, 'gross_price' => '19.95'],
+    ],
+]);
+```
+
+Once a paid order is sent, create a shipment. Anikeen ID adds its delivery note to the user's
+order documents (with the tracking link), mails it to the user (`'notify_customer' => false` if
+your shop sends its own mail) and sends `order.shipped` to your webhook endpoints.
+Without `items`, everything physical that is left is shipped; partial deliveries name the items:
+
+```php
+$order = $user->orders()->find($orderId);
+
+$shipment = $order->shipments()->create([
+    'carrier' => 'DHL',
+    'tracking_number' => '00340434161234567890',
+    'tracking_url' => 'https://www.dhl.de/…?piececode=00340434161234567890',
+    // 'items' => [['order_item_id' => $itemId, 'units' => 1]],
+]);
+
+$shipment->number;          // LS-2026-0001
+$shipment->deliveryNote();  // the delivery note as PDF
+```
+
+To know what is left to ship, compare the order's items with its shipments:
+
+```php
+$items = $order->orderItems()->toArray();     // id, type, name, units, …
+$shipments = $order->shipments()->toArray();  // each with items: [{order_item_id, units}]
+```
+
+Only the app that created the order (or a trusted app) can ship it, and only once it is paid.
+
+### Subscriptions
+
+Subscriptions work like orders: create a draft, let the user confirm it, read it back.
+
+```php
+$subscription = $user->subscriptions()->create([
+    'name' => 'Pixel Stream Pass',
+    'description' => 'All streams, every month',
+    'unit' => 'month',
+    'price' => 6.714286,           // net per unit, 7.99 with 19 % VAT
+]);
+
+return redirect()->away($subscription->confirmationUrl(route('pass.return')));
+// later: https://shop.test/pass/return?status=completed&subscription=01J…
+```
+
+After the return, read the subscription and check its state:
+
+```php
+$subscription = $user->subscriptions()->find($id);
+
+if ($subscription->isActive()) {
+    // grant access
+}
+```
+
+`status()` returns one of the `Anikeen\Id\Enums\SubscriptionStatus` constants (the API sends the
+same value as `status`):
+
+| `status()` | Meaning | `isActive()` |
+|---|---|---|
+| `draft` | Created, not confirmed by the user yet | no |
+| `trial` | Running, in its trial period | yes |
+| `active` | Running and billed | yes |
+| `paused` | Runs until the paid period ends, then expires (`resume()` to continue) | yes |
+| `cancelling` | Runs until a scheduled cancellation takes effect | yes |
+| `expired` | Paused and ran out; `resume()` starts a new period | no |
+| `cancelled` | Cancelled for good | no |
+
+There are shortcuts for each: `isDraft()`, `isPaused()`, `isCancelling()`, `isExpired()`,
+`isCancelled()`. App subscriptions (`appSubscriptions()`) have the same methods.
+
+### Webhooks
+
+Anikeen ID sends `order.*`, `subscription.*` and `checkout.*` events to the webhook endpoints of
+your app (see [`EventType`](src/Id/Webhooks/EventType.php) for all of them). Verify each request
+with the raw body and answer 2xx within 10 seconds; failed deliveries are retried for about three
+days.
+
+Exclude the route from CSRF protection in `bootstrap/app.php`:
+
+```php
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->validateCsrfTokens(except: ['webhooks/*']);
+})
+```
+
+```php
+use Anikeen\Id\Exceptions\SignatureVerificationException;
+use Anikeen\Id\Webhooks\EventType;
+use Anikeen\Id\Webhooks\Webhook;
+
+Route::post('webhooks/anikeen', function (Request $request) {
+    try {
+        $event = Webhook::constructEvent($request->getContent(), $request->header('Anikeen-Signature'), config('services.anikeen.webhook_secret'));
+    } catch (SignatureVerificationException) {
+        abort(400);
+    }
+
+    if (! ProcessedEvent::firstOrCreate(['id' => $event['id']])->wasRecentlyCreated) {
+        return response()->noContent(); // already handled
+    }
+
+    $object = $event['data']['object'];
+
+    match ($event['type']) {
+        EventType::ORDER_COMPLETED => Shop::fulfil($object['id'], $object['shipping_address']),
+        EventType::ORDER_CANCELLED => Shop::release($object['id']),
+        EventType::SUBSCRIPTION_ACTIVATED => Pass::grant($object['id']),
+        EventType::SUBSCRIPTION_CANCELLED => Pass::revoke($object['id']),
+        EventType::CHECKOUT_COMPLETED => Panel::provision($object['subscription_ids']),
+        default => null,
+    };
+
+    return response()->noContent();
+});
+```
+
+`data.object` is the order, subscription or checkout session as the API returns it. Events can
+arrive more than once or out of order: use `$event['id']` to skip duplicates, and reload the
+object through the API when the current state matters. The admin panel can send a
+`webhook.test` event to check your endpoint.
+
+### Errors
+
+Calls with the user's token throw `Anikeen\Id\Exceptions\ResourceException` when Anikeen ID
+rejects them; `getCode()` is the HTTP status (e.g. `422` for invalid data, `404` for an unknown
+ID) and `getMessage()` the reason. App calls (`app*()`) throw its subclass `ApiException`, which
+adds a stable `error` code. Catching `ResourceException` covers both:
+
+```php
+use Anikeen\Id\Exceptions\ResourceException;
+
+try {
+    $order = $user->orders()->create($attributes);
+} catch (ResourceException $e) {
+    report($e);
+
+    return back()->with('error', 'The order could not be created.');
+}
+```
+
+### Testing
+
+Develop against staging (`ANIKEEN_ID_MODE=staging`) with an OAuth client registered there.
+Payments on staging run in Stripe's test mode: pay with Stripe's
+[test cards](https://docs.stripe.com/testing), e.g. `4242 4242 4242 4242` with any future expiry
+date and any CVC. No money is charged.
+Point `ANIKEEN_ID_BASE_URL` at your own Anikeen ID instance if you run one locally.
+
+In unit tests, swap the HTTP client for a Guzzle `MockHandler`:
+
+```php
+$mock = new \GuzzleHttp\Handler\MockHandler([
+    new \GuzzleHttp\Psr7\Response(201, ['Content-Type' => 'application/json'], json_encode(['data' => ['id' => '01JORDER', 'status' => 'draft']])),
+]);
+
+$this->app->instance(AnikeenId::class, (new AnikeenId())->setHttpClient(new \GuzzleHttp\Client([
+    'handler' => \GuzzleHttp\HandlerStack::create($mock),
+    'base_uri' => 'https://id.test/api/',
+])));
+```
+
+## Trusted apps
+
+Apps operated by Anikeen can be marked as trusted. They can charge without asking the user and
+use their own token (client credentials), so billing keeps working when the user's login expired.
 
 ### App subscriptions (trusted apps, no user token)
 
@@ -166,7 +533,7 @@ period, confirms (all subscriptions start, or none) or cancels, and returns to `
 Open sessions expire after 24 hours with their drafts. Trusted apps can still check out directly;
 sessions are opt-in.
 
-Example: the Console's builder ("Jetzt kaufen") with several products and coupon prices:
+Example: a cart with several products and coupon prices:
 
 ```php
 use Anikeen\Id\Exceptions\ApiException;
@@ -214,76 +581,22 @@ While a session is open, its subscriptions can't be checked out or repriced by t
 `subscription.activated` / `subscription.cancelled` are still sent per subscription, before the
 `checkout.*` event of the session.
 
-### Selling as a third-party app (user confirms on Anikeen ID)
 
-Apps that are not trusted can create orders and subscriptions for the signed-in user (user token),
-but can't charge them. The user confirms on Anikeen ID and comes back to your `return_url`:
+## API authentication
+
+Use this when your own API accepts access tokens issued by Anikeen ID.
+
+### Registering Middleware
+
+To call your API from your own frontend with the user's session, append the middleware to the
+web middleware group in your application's `bootstrap/app.php` file:
 
 ```php
-use Anikeen\Id\Exceptions\ConfirmationRequiredException;
-
-$order = $user->orders()->create([
-    'billing_address_id' => $addressId,
-    'items' => [['type' => 'digital', 'name' => 'Sticker pack', 'unit' => 'piece', 'units' => 1, 'gross_price' => '9.99']],
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->web(append: [
+        \Anikeen\Id\Http\Middleware\CreateFreshApiToken::class,
     ]);
-
-return redirect($order->confirmationUrl(route('shop.done')));
-// later: https://your-app.test/shop/done?status=completed&order=01J…
-```
-
-`return_url` must have the origin of one of your app's redirect URIs. `status` is `completed`,
-`pending` (payment still processing) or `cancelled`; check it with `$user->orders()->find($id)`
-instead of trusting the query string. Subscriptions work the same way
-(`$user->subscriptions()->create([...])->confirmationUrl(...)`, `&subscription=…`).
-Unconfirmed bookings are cancelled after 24 hours.
-
-`checkout()` on such a draft throws `ConfirmationRequiredException`; its `confirmationUrl`
-points to the same page. Trusted apps keep checking out directly.
-
-### Webhooks
-
-Anikeen ID sends `order.*`, `subscription.*` and `checkout.*` events to the webhook endpoints of your app (set up
-in the Anikeen ID admin panel, which also shows the signing secret `whsec_…`). Verify each request
-with the raw body and answer 2xx within 10 seconds; failed deliveries are retried for about three days.
-
-```php
-use Anikeen\Id\Exceptions\SignatureVerificationException;
-use Anikeen\Id\Webhooks\EventType;
-use Anikeen\Id\Webhooks\Webhook;
-
-Route::post('webhooks/anikeen', function (Request $request) {
-    try {
-        $event = Webhook::constructEvent($request->getContent(), $request->header('Anikeen-Signature'), config('services.anikeen.webhook_secret'));
-    } catch (SignatureVerificationException) {
-        abort(400);
-    }
-
-    match ($event['type']) {
-        EventType::ORDER_COMPLETED => Shop::fulfil($event['data']['object']['id']),
-        EventType::SUBSCRIPTION_CANCELLED => Panel::suspend($event['data']['object']['id']),
-        EventType::CHECKOUT_COMPLETED => Panel::provision($event['data']['object']['subscription_ids']),
-        default => null,
-    };
-
-    return response()->noContent();
-})->withoutMiddleware(VerifyCsrfToken::class);
-```
-
-Events can arrive more than once or out of order: use `$event['id']` to skip duplicates, and
-reload the object through the API when the current state matters.
-
-### Change the default access token / refresh token field name
-
-If you access / refresh token fields differs from the default `anikeen_id_access_token` / `anikeen_id_refresh_token`, you can specify the field name in the `AppServiceProvider` boot method:
-
-```php
-use Anikeen\Id\AnikeenId;
-
-public function boot(): void
-{
-    AnikeenId::useAccessTokenField('anikeen_id_access_token');
-    AnikeenId::useRefreshTokenField('anikeen_id_refresh_token');
-}
+})
 ```
 
 ### Implementing Auth (API tokens)
@@ -371,70 +684,36 @@ $anikeenId = $anikeenId->withClientSecret('abc123');
 $anikeenId = $anikeenId->withToken('abcdef123456');
 ```
 
-#### Error handling for an unsuccessful query:
+#### Results and resources
+
+Low-level methods on `AnikeenId` (e.g. `getAuthedUser()`, `createOrderPreview()`,
+`refreshToken()`) return a `Result`. Check it before you use it:
 
 ```php
-$result = $anikeenId->sshKeysByUserId('someInvalidId');
+$result = $anikeenId->getAuthedUser();
 
-// Check, if the query was successfully
 if (!$result->success()) {
     die('Ooops: ' . $result->error());
 }
+
+$user = $result->shift(); // the object, or the first item of a list
 ```
 
-#### Shift result to get single key data:
-
-```php
-$result = $anikeenId->sshKeysByUserId('someValidId');
-
-$sshKey = $result->shift();
-
-echo $sshKey->name;
-```
+Resource methods (`$user->orders()`, `$anikeenId->sshKeysByUserId()`, …) return objects and throw
+`ResourceException` instead (see [Errors](#errors)).
 
 ## Examples
 
-#### Get User SSH Key
+#### Get User SSH Keys
+
+Uses the app's own token (client credentials):
 
 ```php
-$anikeenId = new Anikeen\IdAnikeenId();
-
-$anikeenId->setClientId('abc123');
-
-// Get SSH Key by User ID
-$result = $anikeenId->sshKeysByUserId('someValidId');
-
-// Check, if the query was successfully
-if (!$result->success()) {
-    die('Ooops: ' . $result->error());
-}
-
-// Shift result to get single key data
-$sshKey = $result->shift();
+$sshKeys = app(Anikeen\Id\AnikeenId::class)->sshKeysByUserId($anikeenUserId);
 
+foreach ($sshKeys->toArray() as $sshKey) {
     echo $sshKey->name;
-```
-
-#### Create Order Preview
-
-```php
-$anikeenId = new \Anikeen\Id\AnikeenId();
-
-// Create new Order Preview
-$result = $anikeenId->createOrderPreview([
-    'country_iso' => 'de',
-    'items' => [
-        [
-            'type' => 'physical',
-            'name' => 'Test',
-            'price' => 2.99,
-            'unit' => 'onetime',
-            'units' => 1,
-        ]
-    ]
-])->shift();
-
-echo $preview->gross_total;
+}
 ```
 
 #### OAuth Tokens
@@ -442,22 +721,13 @@ echo $preview->gross_total;
 ```php
 $anikeenId = new Anikeen\Id\AnikeenId();
 
-$anikeenId->setClientId('abc123');
 $anikeenId->setToken('abcdef123456');
 
-$result = $anikeenId->getAuthedUser();
-
-$user = $userResult->shift();
+$user = $anikeenId->getAuthedUser()->shift();
 ```
 
 ```php
-$anikeenId->setToken('uvwxyz456789');
-
-$result = $anikeenId->getAuthedUser();
-```
-
-```php
-$result = $anikeenId->withToken('uvwxyz456789')->getAuthedUser();
+$user = $anikeenId->withToken('uvwxyz456789')->getAuthedUser()->shift();
 ```
 
 #### Facade
@@ -465,14 +735,14 @@ $result = $anikeenId->withToken('uvwxyz456789')->getAuthedUser();
 ```php
 use Anikeen\Id\Facades\AnikeenId;
 
-AnikeenId::withClientId('abc123')->withToken('abcdef123456')->getAuthedUser();
+AnikeenId::withToken('abcdef123456')->getAuthedUser();
 ```
 
 ## Documentation
 
 <!-- GENERATED-DOCS -->
 
-[**OAuth Scopes Enums**](https://github.com/anikeen-com/id/blob/main/src/Enums/Scope.php)
+[**OAuth Scopes Enums**](https://github.com/anikeen-com/id/blob/main/src/Id/Enums/Scope.php)
 
 ## Development
 
@@ -482,10 +752,6 @@ AnikeenId::withClientId('abc123')->withToken('abcdef123456')->getAuthedUser();
 composer test
 ```
 
-```shell
-BASE_URL=xxxx CLIENT_ID=xxxx CLIENT_KEY=yyyy CLIENT_ACCESS_TOKEN=zzzz composer test
-```
-
 #### Generate Documentation
 
 ```shell

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

@@ -4,6 +4,7 @@ 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;
 
@@ -18,13 +19,21 @@ use Throwable;
  * @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.

tests/Id/SubscriptionStatusTest.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace Anikeen\Id\Tests;
+
+use Anikeen\Id\Billable;
+use Anikeen\Id\Enums\SubscriptionStatus;
+use Anikeen\Id\Resources\AppSubscription;
+use Illuminate\Database\Eloquent\Model;
+use PHPUnit\Framework\Attributes\DataProvider;
+
+class SubscriptionStatusTest extends TestCase
+{
+    private const BASE = ['id' => '01JSUB', 'active' => false, 'autorenew' => true, 'cancelled' => false, 'starts_at' => null, 'cancels_at' => null, 'trial_ends_at' => null];
+
+    public static function states(): array
+    {
+        $started = ['starts_at' => '2026-10-01T00:00:00+00:00'];
+
+        return [
+            'draft' => [[], SubscriptionStatus::DRAFT, false],
+            'active' => [['active' => true, ...$started], SubscriptionStatus::ACTIVE, true],
+            'trial' => [['active' => true, 'trial_ends_at' => date(DATE_ATOM, time() + 86400), ...$started], SubscriptionStatus::TRIAL, true],
+            'trial over' => [['active' => true, 'trial_ends_at' => '2026-01-01T00:00:00+00:00', ...$started], SubscriptionStatus::ACTIVE, true],
+            'paused' => [['active' => true, 'autorenew' => false, ...$started], SubscriptionStatus::PAUSED, true],
+            'cancelling' => [['active' => true, 'cancels_at' => '2027-01-01T00:00:00+00:00', ...$started], SubscriptionStatus::CANCELLING, true],
+            'expired' => [['autorenew' => false, ...$started], SubscriptionStatus::EXPIRED, false],
+            'cancelled' => [['autorenew' => false, 'cancelled' => true, ...$started], SubscriptionStatus::CANCELLED, false],
+        ];
+    }
+
+    #[DataProvider('states')]
+    public function test_the_status_follows_the_fields(array $fields, string $status, bool $running): void
+    {
+        $data = [...self::BASE, ...$fields];
+
+        $this->respond(200, ['data' => [$data]]); // subscriptions() loads the list
+        $this->respond(200, ['data' => $data]);
+        $owner = new class extends Model {
+            use Billable;
+        };
+        $owner->anikeen_id_access_token = 'user-token';
+        $subscription = $owner->subscriptions()->find('01JSUB');
+
+        $app = new AppSubscription((object) $data);
+
+        foreach ([$subscription, $app] as $resource) {
+            $this->assertSame($status, $resource->status());
+            $this->assertSame($running, $resource->isActive());
+            $this->assertSame($status === SubscriptionStatus::DRAFT, $resource->isDraft());
+            $this->assertSame($status === SubscriptionStatus::PAUSED, $resource->isPaused());
+            $this->assertSame($status === SubscriptionStatus::CANCELLING, $resource->isCancelling());
+            $this->assertSame($status === SubscriptionStatus::EXPIRED, $resource->isExpired());
+            $this->assertSame($status === SubscriptionStatus::CANCELLED, $resource->isCancelled());
+        }
+    }
+}