From 2acbef72c805c1694aee4b5ad9813147c4ba76b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maurice=20Preu=C3=9F?= Date: Wed, 4 Nov 2026 16:00:24 +0100 Subject: [PATCH 1/5] 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 --- README.md | 4 ---- README.stub | 41 +++++++++++++++++++++++++++++++++++++---- 2 files changed, 37 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index c409476..2f52ef2 100644 --- a/README.md +++ b/README.md @@ -688,10 +688,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 diff --git a/README.stub b/README.stub index f512bd4..04f2788 100644 --- a/README.stub +++ b/README.stub @@ -237,6 +237,43 @@ 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. @@ -482,10 +519,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 From 26716e7bba8efd58e4b092e27af482dc054830a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maurice=20Preu=C3=9F?= Date: Wed, 4 Nov 2026 16:00:29 +0100 Subject: [PATCH 2/5] Add CLAUDE.md Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..4ad4d18 --- /dev/null +++ b/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 + `` 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`. From e3e59fb8a4eb9c4aeb42b40e388b94f9aa4d5646 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maurice=20Preu=C3=9F?= Date: Wed, 4 Nov 2026 16:06:23 +0100 Subject: [PATCH 3/5] 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 --- README.md | 575 +++++++++++++++++++++++++++++++++++----------------- README.stub | 575 +++++++++++++++++++++++++++++++++++----------------- 2 files changed, 782 insertions(+), 368 deletions(-) diff --git a/README.md b/README.md index 2f52ef2..4a3d55b 100644 --- a/README.md +++ b/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,336 @@ 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… +``` + +A subscription has `active` (running and paid), `cancelled` and `autorenew` (false once paused). +After the return, check `$user->subscriptions()->find($id)->active`. + +### 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. +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 +507,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 +555,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 +658,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 +695,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 +709,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 +885,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 diff --git a/README.stub b/README.stub index 04f2788..f9dbd40 100644 --- a/README.stub +++ b/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,336 @@ 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… +``` + +A subscription has `active` (running and paid), `cancelled` and `autorenew` (false once paused). +After the return, check `$user->subscriptions()->find($id)->active`. + +### 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. +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 +507,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 +555,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 +658,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 +695,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,14 +709,14 @@ $result = $anikeenId->withToken('uvwxyz456789')->getAuthedUser(); ```php use Anikeen\Id\Facades\AnikeenId; -AnikeenId::withClientId('abc123')->withToken('abcdef123456')->getAuthedUser(); +AnikeenId::withToken('abcdef123456')->getAuthedUser(); ``` ## Documentation -[**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 From 2faccac0f4f7c6214dab00a6261ad98b481762d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maurice=20Preu=C3=9F?= Date: Wed, 4 Nov 2026 16:09:47 +0100 Subject: [PATCH 4/5] Document Stripe test cards on staging Co-Authored-By: Claude Opus 5.5 --- README.md | 3 +++ README.stub | 3 +++ 2 files changed, 6 insertions(+) diff --git a/README.md b/README.md index 4a3d55b..d719615 100644 --- a/README.md +++ b/README.md @@ -414,6 +414,9 @@ try { ### 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`: diff --git a/README.stub b/README.stub index f9dbd40..5bb5ac5 100644 --- a/README.stub +++ b/README.stub @@ -414,6 +414,9 @@ try { ### 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`: From ce820cd198f8d3dd7d0ce23ace5c44c36df1e2ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maurice=20Preu=C3=9F?= Date: Wed, 4 Nov 2026 16:15:48 +0100 Subject: [PATCH 5/5] 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 --- README.md | 27 ++- README.stub | 27 ++- src/Id/Concerns/HasSubscriptionStatus.php | 82 ++++++++ src/Id/Enums/SubscriptionStatus.php | 33 +++ src/Id/Resources/AppSubscription.php | 7 +- src/Id/Resources/Subscription.php | 233 +++++++++++----------- tests/Id/SubscriptionStatusTest.php | 56 ++++++ 7 files changed, 348 insertions(+), 117 deletions(-) create mode 100644 src/Id/Concerns/HasSubscriptionStatus.php create mode 100644 src/Id/Enums/SubscriptionStatus.php create mode 100644 tests/Id/SubscriptionStatusTest.php diff --git a/README.md b/README.md index d719615..a5157c1 100644 --- a/README.md +++ b/README.md @@ -338,8 +338,31 @@ return redirect()->away($subscription->confirmationUrl(route('pass.return'))); // later: https://shop.test/pass/return?status=completed&subscription=01J… ``` -A subscription has `active` (running and paid), `cancelled` and `autorenew` (false once paused). -After the return, check `$user->subscriptions()->find($id)->active`. +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 diff --git a/README.stub b/README.stub index 5bb5ac5..b135453 100644 --- a/README.stub +++ b/README.stub @@ -338,8 +338,31 @@ return redirect()->away($subscription->confirmationUrl(route('pass.return'))); // later: https://shop.test/pass/return?status=completed&subscription=01J… ``` -A subscription has `active` (running and paid), `cancelled` and `autorenew` (false once paused). -After the return, check `$user->subscriptions()->find($id)->active`. +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 diff --git a/src/Id/Concerns/HasSubscriptionStatus.php b/src/Id/Concerns/HasSubscriptionStatus.php new file mode 100644 index 0000000..2cddb04 --- /dev/null +++ b/src/Id/Concerns/HasSubscriptionStatus.php @@ -0,0 +1,82 @@ +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; + } +} diff --git a/src/Id/Enums/SubscriptionStatus.php b/src/Id/Enums/SubscriptionStatus.php new file mode 100644 index 0000000..95aeff5 --- /dev/null +++ b/src/Id/Enums/SubscriptionStatus.php @@ -0,0 +1,33 @@ + $this->billable->anikeenId() - ->request('PUT', sprintf('v1/subscriptions/%s', $this->id), $attributes))) - ->setBillable($this->billable); - } - - /** - * Force given subscription to check out (trusted apps only). - * - * @throws Throwable - */ - public function checkout(): self - { - return (new self(fn() => $this->billable->anikeenId() - ->request('PUT', sprintf('v1/subscriptions/%s/checkout', $this->id)))) - ->setBillable($this->billable); - } - - /** - * Revoke a given running subscription from the current user. - * - * @throws Throwable - */ - public function revoke(bool $refund = false): self - { - $attributes = [ - 'refund' => $refund, - ]; - - return (new self(fn() => $this->billable->anikeenId() - ->request('PUT', sprintf('v1/subscriptions/%s/revoke', $this->id), $attributes))) - ->setBillable($this->billable); - } - - /** - * Pause a given running subscription from the current user. - * - * @throws Throwable - */ - public function pause(): self - { - return (new self(fn() => $this->billable->anikeenId() - ->request('PUT', sprintf('v1/subscriptions/%s/pause', $this->id)))) - ->setBillable($this->billable); - } - - /** - * Resume a given running subscription from the current user. - * - * @throws Throwable - */ - public function resume(): self - { - return (new self(fn() => $this->billable->anikeenId() - ->request('PUT', sprintf('v1/subscriptions/%s/resume', $this->id)))) - ->setBillable($this->billable); - } -} + $this->billable->anikeenId() + ->request('PUT', sprintf('v1/subscriptions/%s', $this->id), $attributes))) + ->setBillable($this->billable); + } + + /** + * Force given subscription to check out (trusted apps only). + * + * @throws Throwable + */ + public function checkout(): self + { + return (new self(fn() => $this->billable->anikeenId() + ->request('PUT', sprintf('v1/subscriptions/%s/checkout', $this->id)))) + ->setBillable($this->billable); + } + + /** + * Revoke a given running subscription from the current user. + * + * @throws Throwable + */ + public function revoke(bool $refund = false): self + { + $attributes = [ + 'refund' => $refund, + ]; + + return (new self(fn() => $this->billable->anikeenId() + ->request('PUT', sprintf('v1/subscriptions/%s/revoke', $this->id), $attributes))) + ->setBillable($this->billable); + } + + /** + * Pause a given running subscription from the current user. + * + * @throws Throwable + */ + public function pause(): self + { + return (new self(fn() => $this->billable->anikeenId() + ->request('PUT', sprintf('v1/subscriptions/%s/pause', $this->id)))) + ->setBillable($this->billable); + } + + /** + * Resume a given running subscription from the current user. + * + * @throws Throwable + */ + public function resume(): self + { + return (new self(fn() => $this->billable->anikeenId() + ->request('PUT', sprintf('v1/subscriptions/%s/resume', $this->id)))) + ->setBillable($this->billable); + } +} diff --git a/tests/Id/SubscriptionStatusTest.php b/tests/Id/SubscriptionStatusTest.php new file mode 100644 index 0000000..ddeca9c --- /dev/null +++ b/tests/Id/SubscriptionStatusTest.php @@ -0,0 +1,56 @@ + '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()); + } + } +}