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

Document payments end to end, add subscription status helpers
Add subscription status helpers
2026-11-04 22:59:41 +00:00 · 2026-11-04 17:56:25 +01:00 · 2026-11-04 16:15:48 +01:00 · 2026-11-04 16:09:47 +01:00 · 2026-11-04 16:06:23 +01:00 · 2026-11-04 16:00:29 +01:00
8 changed files with 1084 additions and 340 deletions
@@ -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`.
@@ -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']],
-]);
-
-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');
-}
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->web(append: [
+        \Anikeen\Id\Http\Middleware\CreateFreshApiToken::class,
+    ]);
+})
 ```

 ### 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();
+$sshKeys = app(Anikeen\Id\AnikeenId::class)->sshKeysByUserId($anikeenUserId);

-$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());
+foreach ($sshKeys->toArray() as $sshKey) {
+    echo $sshKey->name;
 }
-
-// Shift result to get single key data
-$sshKey = $result->shift();
-
-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
@@ -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']],
-]);
-
-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');
-}
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->web(append: [
+        \Anikeen\Id\Http\Middleware\CreateFreshApiToken::class,
+    ]);
+})
 ```

 ### 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();
+$sshKeys = app(Anikeen\Id\AnikeenId::class)->sshKeysByUserId($anikeenUserId);

-$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());
+foreach ($sshKeys->toArray() as $sshKey) {
+    echo $sshKey->name;
 }
-
-// Shift result to get single key data
-$sshKey = $result->shift();
-
-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
@@ -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;
+    }
+}
@@ -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';
+}
@@ -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)
    {
    }
@@ -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.
@@ -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());
+        }
+    }
+}
Author	SHA1	Message	Date
envoyr	a4345e72ec	Merge pull request #14 from anikeen-com/docs/remove-live-test-hint Document payments end to end, add subscription status helpers	2026-11-04 17:56:25 +01:00
Maurice PreußandClaude Opus 5.5	ce820cd198	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>	2026-11-04 16:15:48 +01:00
Maurice PreußandClaude Opus 5.5	2faccac0f4	Document Stripe test cards on staging Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-11-04 16:09:47 +01:00
Maurice PreußandClaude Opus 5.5	e3e59fb8a4	Document payments end to end Add a Payments guide that follows a typical third-party shop: sign-in scopes, user table and token storage, creating orders and subscriptions, the confirmation and return flow, statuses, prices and VAT, shipments, webhooks with Laravel 11 CSRF exclusion, error handling and testing. Move the trusted-app sections and API authentication after it, add the webhook secret to the config, fix the broken General/Examples snippets and the Scope enum link. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-11-04 16:06:23 +01:00
Maurice PreußandClaude Opus 5.5	26716e7bba	Add CLAUDE.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-11-04 16:00:29 +01:00
Maurice PreußandClaude Opus 5.5	2acbef72c8	Drop the live API test hint from the README The tests use a mocked HTTP client and ignore these variables. Also move the shipping address and shipment docs into README.stub, so composer docs no longer drops them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-11-04 16:00:24 +01:00