Merge pull request #24 from anikeen-com/feature/app-charges

Add charges and the billing limit for trusted apps
Merge pull request #23 from anikeen-com/feature/preferences
2026-11-06 23:58:35 +00:00 · 2026-11-06 21:25:38 +00:00 · 2026-11-06 21:25:11 +00:00 · 2026-11-06 20:03:12 +00:00 · 2026-11-06 20:01:15 +00:00 · 2026-11-06 20:01:15 +00:00
29 changed files with 2368 additions and 33 deletions
@@ -1,5 +1,33 @@
 # Changelog
 ## Unreleased
 Preferences, charges and the billing limit; they need an Anikeen ID release that supports them.
 ### Added
 - Preferences of any user with the app's token (trusted apps, registered by Anikeen per
  namespace): `preferencesByUserId()`, `preferenceByUserId()`, `setPreferenceByUserId()`,
  `deletePreferenceByUserId()` and `findUserIdByPreference()` (the user holding a value of a unique
  key, `null` when nobody does).
 - The user's shared preferences with their token: `globalPreferences()`, `globalPreference()`,
  `setGlobalPreference()` and `deleteGlobalPreference()` on `Billable`, cached per instance.
 - `Resources\Preference` and `Resources\Preferences`; `Enums\SharedPreference` and
  `Enums\Appearance`.
 - Conditional writes: `ifVersion` (`If-Match`) and `createOnly` (`If-None-Match: *`);
  `PreconditionFailedException` (a subclass of `ApiException`) for 412 with `currentVersion()`.
 - Scopes `Scope::PREFERENCES`, `PREFERENCES_READ` and `PREFERENCES_CLIENT`.
 - Webhook event `order.refunded` (`EventType::ORDER_REFUNDED`).
 - Charges on a user's monthly bill for trusted apps: `createChargeForUser()` (with an idempotency
  key), `findChargeForUser()` and `voidChargeForUser()`; `Resources\AppCharge`.
 - The user's billing limit for trusted apps: `billingLimitForUser()` and `Resources\BillingLimit`
  (`allows()` is advisory); the `billing_limit` key of `billingOverview()` is documented.
 - `ApiException::isBillingLimitReached()` for 409 `billing_limit_reached`.
 - Opt-in webhook events `billing_limit.reached` and `billing_limit.available`
  (`EventType::BILLING_LIMIT_REACHED`, `BILLING_LIMIT_AVAILABLE`).
 - An optional trailing `$headers` argument on `AnikeenId::request()`, `get()`, `post()`, `put()`,
  `delete()` and `AppRequest::send()`; calls without it send the same request as before.
 ## 3.3.0 (2026-11-06)
 App billing features; they need an Anikeen ID release that supports them.
@@ -16,11 +16,12 @@ subscriptions and physical goods, with invoices, VAT and payment handled by Anik
 3. [Sign in with Anikeen ID](#sign-in-with-anikeen-id)
 4. [Payments](#payments)
 5. [Trusted apps](#trusted-apps)
-6. [API authentication](#api-authentication)
+6. [Preferences](#preferences)
-7. [General](#general)
+7. [API authentication](#api-authentication)
-8. [Examples](#examples)
+8. [General](#general)
-9. [Documentation](#documentation)
+9. [Examples](#examples)
-10. [Development](#development)
+10. [Documentation](#documentation)
 11. [Development](#development)
 ## Installation
@@ -181,6 +182,14 @@ A full reseller scope includes reading. `user` and `*` do not open the reseller
 token has to carry the reseller scope itself. For the product APIs there is only `products:read`;
 changing products needs `user`.
 Anikeen ID's [preferences](#preferences) use these scopes:
 | Scope | Constant | Grants |
 |-------|----------|--------|
 | `preferences:read` | `Scope::PREFERENCES_READ` | read the user's shared preferences (`global`) |
 | `preferences` | `Scope::PREFERENCES` | read and change them |
 | `preferences:client` | `Scope::PREFERENCES_CLIENT` | app tokens: the preferences of any user, in the namespaces Anikeen registered for the app |
 ### 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:
@@ -205,11 +214,14 @@ public function boot(): void
 | 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) |
 | Single items on the user's monthly bill (e.g. a shipped item) | [Charges](#charges-and-billing-limit-trusted-apps) | 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).
+Anikeen) can also charge directly; see [Trusted apps](#trusted-apps). For a per-item charge on
 the user's monthly bill use `createChargeForUser()`, not `createOrderForUser()`: an order is a
 separate one-off purchase, charged on its own.
 The flow, as in a typical shop:
@@ -549,6 +561,16 @@ if ($event['type'] === EventType::SUBSCRIPTION_RENEWED) {
 `order.*` events list the order's `items` and `invoice` like
 [app orders](#app-orders-trusted-apps-no-user-token).
 `billing_limit.reached` and `billing_limit.available` (`EventType::BILLING_LIMIT_REACHED`,
 `BILLING_LIMIT_AVAILABLE`) tell trusted apps that a user's billing limit was reached or has room
 again; they are opt-in like `subscription.renewed`, see
 [Charges and billing limit](#charges-and-billing-limit-trusted-apps).
 `order.refunded` (`EventType::ORDER_REFUNDED`) is sent when money was given back for an order (a
 refund or a partial cancellation, with a credit note); the order carries its `refunds` and
 `refunded_total`. A full refund also cancels the order, so `order.cancelled` is sent too; don't rely on the
 order of the two events.
 ### Errors
 Every failed request throws `Anikeen\Id\Exceptions\ApiException`, with the user's token as
@@ -559,7 +581,11 @@ well as with the app's (`app*()`). It carries:
  `already_cancelled`), otherwise `null`,
 - `getMessage()`: Anikeen ID's reason,
 - `isNotFound()` (404), `isConflict()` (409) and `isTemporary()` (no response, 429 or 5xx: retry
-  later).
+  later),
 - `isBillingLimitReached()` (409 `billing_limit_reached`: a [charge](#charges-and-billing-limit-trusted-apps)
  would take the user's monthly bill above their billing limit),
 - `body()`: the error response, for errors with details (e.g. `remaining` of
  `billing_limit_reached`).
 ```php
 use Anikeen\Id\Exceptions\ApiException;
@@ -837,6 +863,127 @@ link's user. The session ends after an hour without activity or on "Back to *app
 payment) and back to `return_url`. For the signed-in user with their own token,
 `$user->billingPortalUrl()` stays available.
 ### Charges and billing limit (trusted apps)
 Trusted apps can book single items onto a user's **open monthly bill** of the app, e.g. each item
 a shipping app sends: one line per charge, no subscription, charged with the bill on the 1st like
 every other line (invoice and VAT by Anikeen ID). Anikeen has to enable charging for your app and
 sets a maximum per charge; the user must be connected to your app (they authorised it, or your app
 bills them through subscriptions or orders).
 ```php
 $anikeen = app(AnikeenId::class);
 $charge = $anikeen->createChargeForUser($user->anikeen_id, [
    'idempotency_key' => "shipment-{$shipment->id}", // per app and user: a retry returns the same charge
    'name' => 'Signed card',                         // the line on the bill
    'type' => 'physical',                            // digital (default), physical, physical-reduced
    'quantity' => 2,
    'unit_price' => '4.00',                          // net per piece, up to 6 decimals
    'reference' => "order-{$shipment->order_id}",    // your own id; not on the bill
    // 'group' => $team->id,                         // only a group your app already bills the user in
    // 'occurred_at' => '2026-11-05T14:00:00Z',      // the service date, at most 31 days ago
 ]);
 $charge->id();          // keep it to void the charge later
 $charge->grossAmount(); // "9.52": what it added to the bill
 $charge->orderId();     // the monthly bill it is on
 $charge->status();      // open, billed (the bill was closed) or voided
 $anikeen->findChargeForUser($user->anikeen_id, $chargeId);
 $anikeen->voidChargeForUser($user->anikeen_id, $chargeId, 'Parcel lost'); // while the bill is open
 ```
 - **Idempotency:** retrying with the same key and the same fields returns the existing charge
  (200 instead of 201), also after the limit was reached; the same key with other fields is 409
  `idempotency_key_conflict` (`charge_id` in `body()`). Use one key per item you charge for.
 - **Voiding** removes the line while the bill is open (an already voided charge is returned as
  it is). Once the bill was closed: 409 `charge_already_billed`; only a refund of the order by
  Anikeen credits it.
 - **`group`** is null or a group your app already bills the user in (a running subscription or an
  open monthly bill of your app); others are refused with 409 `group_not_allowed`.
 - `reference` and `metadata` (up to 20 string values) are your data about the user, kept with the
  charge and not shown on the bill: put nothing sensitive there.
 **Billing limit.** A user can set one monthly limit (gross) for their whole open monthly bill
 across all Anikeen services. A charge that would take the bill above it is refused with 409
 `billing_limit_reached`; exactly reaching the limit is allowed, `0.00` refuses every charge.
 Subscription renewals and usage are still billed, so the bill can end above the limit. Read the
 limit to stop offering paid actions early (advisory only, it reserves nothing):
 ```php
 $limit = $anikeen->billingLimitForUser($user->anikeen_id);
 $limit->hasLimit();     // false: no limit, every charge fits
 $limit->isReached();    // used >= limit: start no new paid service
 $limit->remaining();    // "17.60" gross room left, null without a limit
 $limit->remainingNet(); // "14.78" at the user's VAT rate, a hint
 $limit->allows('9.52'); // would this charge fit right now (advisory)
 $limit->resetsAt();     // when this month's bills are closed
 $limit->version();      // only goes up
 $limit->used();         // the user's open bills across all Anikeen services, null without a limit
 $limit->usedByApp();    // your app's share; used − usedByApp = "your other Anikeen services"
 ```
 `used` (the user's open bills across all Anikeen services) is visible to apps **only while the
 user has set a limit**; without one `limit`, `used`, `remaining` and `remaining_net` are null.
 `usedByApp()` (your app's own open bills) is always there. The user sees their own limit in
 `$user->billingOverview()->billing_limit` (with `used`, without `used_by_app`; null while they
 can't set one). Apps that may charge can read the limit; others need Anikeen to allow it (403
 `billing_limit_not_enabled`).
 Handling a refused charge:
 ```php
 use Anikeen\Id\Exceptions\ApiException;
 try {
    $charge = $anikeen->createChargeForUser($user->anikeen_id, $attributes);
 } catch (ApiException $e) {
    if ($e->isBillingLimitReached()) {
        $e->body()->remaining;  // room left before this charge, e.g. "2.60"
        $e->body()->required;   // the refused charge, gross
        $e->body()->resets_at;  // when the limit has room again at the latest
        return $shipment->holdForBillingLimit();
    }
    match ($e->error) {
        'charge_exceeds_maximum' => report($e),   // above your app's maximum ($e->body()->max_charge_net)
        'group_not_allowed' => report($e),
        'billing_address_missing' => $shipment->askForBillingAddress(),
        default => throw $e,
    };
 }
 ```
 **Webhooks.** `billing_limit.reached` and `billing_limit.available` are sent when the limit is
 reached or has room again (a raised or removed limit, a void, the monthly reset). They are
 **opt-in** (select them for your endpoint; `*` doesn't include them) and go only to apps that may
 read the limit of a user connected to them. `data.object` is the billing limit as your app reads
 it, `data.reason` says why (`booking`, `limit_changed`, `limit_removed`, `voided`,
 `period_reset`, `order_changed`). Keep the highest `version` per user and ignore events with a
 lower or equal one, so a late delivery can't undo a newer state. In the `match` of the
 [webhook route](#webhooks):
 ```php
 EventType::BILLING_LIMIT_REACHED, EventType::BILLING_LIMIT_AVAILABLE => Customer::syncBillingLimit(
    $object['user_id'], reached: $event['type'] === EventType::BILLING_LIMIT_REACHED, version: $object['version'],
 ),
 ```
 The limit is checked live when a charge is booked, so a late or missed webhook never lets a
 charge through; poll `billingLimitForUser()` if you need the current state.
 #### Error codes
 | Status | `error` |
 |--------|---------|
 | 403 | `client_not_allowed` (not a trusted app with its own token), `charges_not_enabled` (charging is not enabled for your app; also for reads and voids), `billing_limit_not_enabled` (limit read only) |
 | 404 | `user_not_found` (unknown, deleted or not connected to your app), `charge_not_found` |
 | 409 | `billing_limit_reached` (`isBillingLimitReached()`), `charge_exceeds_maximum` (+ `max_charge_net`), `group_not_allowed`, `idempotency_key_conflict` (+ `charge_id`), `billing_address_missing`, `charge_already_billed` (+ `charge_id`) |
 | 422 | validation (`errors`), no `error` code |
 | 429 | `too_many_requests` (`isTemporary()`) |
 ### Checkout sessions (the user confirms several subscriptions at once)
 Instead of checking subscriptions out itself, an app can let the user confirm them on Anikeen ID,
@@ -918,6 +1065,156 @@ $result->data->invitation_sent;        // only for an account created by this ca
 other than an unknown address.
 ## Preferences
 Anikeen ID keeps small per-user settings as JSON values under a *namespace* and a *key*, so they
 follow the user across devices and apps:
 - **`global`** is shared by all apps. Only registered keys and values are accepted: today
  `SharedPreference::APPEARANCE` with `Appearance::SYSTEM`, `LIGHT` or `DARK`.
 - **App namespaces** (e.g. `acme`) hold one app's own data: onboarding state, a default workspace,
  the user's customer ID at a payment provider. Use another namespace on staging (e.g.
  `acme-staging`), so test data never mixes with production.
 **Registration.** Access never comes from scopes alone: any client can request any scope. Ask
 Anikeen to register your OAuth client(s) (the app has to be [trusted](#trusted-apps)) for
 - the namespaces your app owns (read, write and the lookup),
 - read access to another app's namespace,
 - `global` with the app's token (users always read and write their own `global` with their token),
 - keys whose values are unique (see the lookup below).
 Without it, app requests fail with 403 `client_not_trusted` or 404 `namespace_not_found`.
 **Scopes.** User tokens need `Scope::PREFERENCES` (`preferences`, read and write) or
 `Scope::PREFERENCES_READ` (`preferences:read`); app tokens `Scope::PREFERENCES_CLIENT`
 (`preferences:client`).
 **Limits.** A value is at most 2048 bytes of JSON and 4 levels deep; at most 50 keys per user and
 namespace (updating a key always works); keys match `^[a-z][a-z0-9_]{0,63}$`. Per minute: 60
 requests per user and app with user tokens, 600 per app with the app token and 120 lookups per
 app (429 `rate_limited` with `Retry-After`).
 **Not a secrets store.** Values are stored as plain JSON and shown to Anikeen's support and to the
 user on a request for their data. Store IDs and settings, never passwords, API keys or tokens: keys
 that look like credentials (`secret`, `token`, `password`, `api_key`, …) are rejected with 422
 `forbidden_key`.
 ### The user's shared preferences (user token)
 ```php
 use Anikeen\Id\Enums\Appearance;
 use Anikeen\Id\Enums\SharedPreference;
 $user->globalPreference(SharedPreference::APPEARANCE, Appearance::SYSTEM); // the default when not set
 $user->globalPreferences()->values();     // ['appearance' => 'dark']
 $preference = $user->setGlobalPreference(SharedPreference::APPEARANCE, Appearance::DARK);
 $preference->version;                     // e.g. 1042
 $user->deleteGlobalPreference(SharedPreference::APPEARANCE);
 ```
 User tokens reach `global` only; an app namespace answers 404 `namespace_not_found`, whatever the
 token's scopes. The app's own token (client credentials) has no user and gets 401 on these routes.
 ### Preferences of any user (trusted apps)
 With the app's own token, by the user's Anikeen ID:
 ```php
 $anikeenId = app(AnikeenId::class);
 $preferences = $anikeenId->preferencesByUserId($userId, 'acme'); // sorted by key, no pagination
 $preferences->get('onboarding', []);     // the value or a default; also has(), find(), values()
 $preference = $anikeenId->preferenceByUserId($userId, 'acme', 'onboarding'); // 404 preference_not_found if not set
 $preference->value;                      // JSON objects as stdClass, so {} stays {}
 $preference->version;
 $preference->updated_by;                 // {type: "user"|"app", client_id}
 $anikeenId->setPreferenceByUserId($userId, 'acme', 'onboarding', ['step' => 3]);
 $anikeenId->deletePreferenceByUserId($userId, 'acme', 'onboarding');
 ```
 A value is any JSON value; pass `(object) []` for an empty object (`[]` is an empty list).
 `setPreferenceByUserId()` returns the stored preference; `wasCreated()` tells whether the write
 created the key. A deleted user's preferences are gone: every call answers 404 `user_not_found`.
 ### Conditional writes and retries
 Writes are *last write wins* by default. Every write gives the preference a new `version`.
 Versions are opaque: they only go up (also when a key is deleted and set again) and increase per
 user, not by one per key. Pass the version you read to write only if nobody changed it in between
 (`If-Match`), or `createOnly` to write only if the key isn't set yet (`If-None-Match: *`):
 ```php
 use Anikeen\Id\Exceptions\PreconditionFailedException;
 $preference = $anikeenId->preferenceByUserId($userId, 'acme', 'layout');
 try {
    $anikeenId->setPreferenceByUserId($userId, 'acme', 'layout', $merged, ifVersion: $preference->version);
 } catch (PreconditionFailedException $e) {
    $e->error;            // "preference_version_mismatch" (or "preference_exists" for createOnly)
    $e->currentVersion(); // the version stored now, null when the key isn't set: reload, merge, retry
 }
 $anikeenId->setPreferenceByUserId($userId, 'acme', 'welcome_sent_at', now()->toIso8601String(), createOnly: true);
 ```
 `deletePreferenceByUserId()`, `setGlobalPreference()` and `deleteGlobalPreference()` take
 `ifVersion` too. Writing the value that is already stored is a no-op that succeeds (no new version),
 even when the precondition would fail, so retrying a write after a timeout is safe.
 ### Unique keys and the lookup
 Anikeen can declare keys of your namespace unique, e.g. `customer_id`. Their values are strings of
 1 to 255 characters without surrounding whitespace, held by at most one user: setting another
 user's value fails with 409 `preference_value_taken`. Your app can then find the user by value, e.g.
 in a payment provider's webhook:
 ```php
 $userId = $anikeenId->findUserIdByPreference('acme', 'customer_id', 'cus_123'); // null if nobody holds it
 ```
 The value is sent in the body, never in the URL. `findUserIdByPreference()` returns `null` only for
 404 `preference_not_found` (also when the user was deleted); everything else throws, e.g. 422
 `key_not_unique` for a key that isn't declared unique.
 ### Error codes
 Failures throw `ApiException` (412 `PreconditionFailedException`) with these `error` codes:
 | Status | `error` |
 |--------|---------|
 | 401 | `unauthenticated` (no or an invalid token; an app token on the user routes) |
 | 403 | `missing_scope`, `app_token_required` (a user token on the app routes), `client_not_trusted`, `namespace_read_only`, `lookup_not_allowed` |
 | 404 | `namespace_not_found` (unknown or not accessible), `user_not_found` (also deleted users), `preference_not_found`, `not_found` |
 | 405 | `method_not_allowed` |
 | 409 | `preference_value_taken` |
 | 412 | `preference_version_mismatch`, `preference_exists` |
 | 422 | `invalid_key`, `forbidden_key`, `unknown_shared_key`, `value_required`, `value_too_large`, `value_too_deep`, `invalid_shared_value`, `invalid_unique_value`, `key_not_unique`, `preference_limit_exceeded` |
 | 429 | `rate_limited` |
 A `null` value is rejected with 422 `value_required`: delete the key instead.
 ### Caching
 Anikeen ID is the source of truth. `globalPreferences()` and `globalPreference()` cache the list
 on the model instance (one request per instance); `setGlobalPreference()` and
 `deleteGlobalPreference()` clear it. For a copy that outlives the request, keep a read cache: fill
 it at sign-in, write to Anikeen ID first and update the copy from the response, and let it expire
 after about an hour, since other apps and the user can change shared preferences too:
 ```php
 $appearance = Cache::remember("appearance:{$user->id}", now()->addHour(),
    fn () => $user->globalPreference(SharedPreference::APPEARANCE, Appearance::SYSTEM));
 $user->setGlobalPreference(SharedPreference::APPEARANCE, $request->appearance);
 Cache::put("appearance:{$user->id}", $request->appearance, now()->addHour());
 ```
 ## API authentication
 Use this when your own API accepts access tokens issued by Anikeen ID.
@@ -1084,6 +1381,16 @@ AnikeenId::withToken('abcdef123456')->getAuthedUser();
 public function retrievingToken(string $grantType, array $attributes): Result
 ```
 ### ManagesPreferences
 ```php
 public function preferencesByUserId(string $userId, string $namespace): Preferences
 public function preferenceByUserId(string $userId, string $namespace, string $key): Preference
 public function setPreferenceByUserId(string $userId, string $namespace, string $key, mixed $value, ?int $ifVersion = null, bool $createOnly = false): Preference
 public function deletePreferenceByUserId(string $userId, string $namespace, string $key, ?int $ifVersion = null): void
 public function findUserIdByPreference(string $namespace, string $key, string $value): ?string
 ```
 ### ManagesPricing
 ```php
@@ -1116,6 +1423,10 @@ public function appCheckoutSessions(): AppCheckoutSessions
 public function createBillingPortalLinkForUser(string $userId, array $attributes = []): object
 public function createOrderForUser(string $userId, array $attributes): Result
 public function createTransactionForUser(string $userId, array $attributes): Result
 public function createChargeForUser(string $userId, array $attributes): AppCharge
 public function findChargeForUser(string $userId, string $chargeId): AppCharge
 public function voidChargeForUser(string $userId, string $chargeId, ?string $reason = null): AppCharge
 public function billingLimitForUser(string $userId): BillingLimit
 ```
 ### ManagesSocialiteUsers
@@ -1241,6 +1552,15 @@ public function setBillable(Billable|Model $billable): self
 public function getBillable(): Billable
 ```
 ### ManagesUserPreferences
 ```php
 public function globalPreferences(): Preferences
 public function globalPreference(string $key, mixed $default = null): mixed
 public function setGlobalPreference(string $key, mixed $value, ?int $ifVersion = null): Preference
 public function deleteGlobalPreference(string $key, ?int $ifVersion = null): void
 ```
 ### ManagesUserSshKeys
 ```php
@@ -16,11 +16,12 @@ subscriptions and physical goods, with invoices, VAT and payment handled by Anik
 3. [Sign in with Anikeen ID](#sign-in-with-anikeen-id)
 4. [Payments](#payments)
 5. [Trusted apps](#trusted-apps)
-6. [API authentication](#api-authentication)
+6. [Preferences](#preferences)
-7. [General](#general)
+7. [API authentication](#api-authentication)
-8. [Examples](#examples)
+8. [General](#general)
-9. [Documentation](#documentation)
+9. [Examples](#examples)
-10. [Development](#development)
+10. [Documentation](#documentation)
 11. [Development](#development)
 ## Installation
@@ -181,6 +182,14 @@ A full reseller scope includes reading. `user` and `*` do not open the reseller
 token has to carry the reseller scope itself. For the product APIs there is only `products:read`;
 changing products needs `user`.
 Anikeen ID's [preferences](#preferences) use these scopes:
 | Scope | Constant | Grants |
 |-------|----------|--------|
 | `preferences:read` | `Scope::PREFERENCES_READ` | read the user's shared preferences (`global`) |
 | `preferences` | `Scope::PREFERENCES` | read and change them |
 | `preferences:client` | `Scope::PREFERENCES_CLIENT` | app tokens: the preferences of any user, in the namespaces Anikeen registered for the app |
 ### 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:
@@ -205,11 +214,14 @@ public function boot(): void
 | 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) |
 | Single items on the user's monthly bill (e.g. a shipped item) | [Charges](#charges-and-billing-limit-trusted-apps) | 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).
+Anikeen) can also charge directly; see [Trusted apps](#trusted-apps). For a per-item charge on
 the user's monthly bill use `createChargeForUser()`, not `createOrderForUser()`: an order is a
 separate one-off purchase, charged on its own.
 The flow, as in a typical shop:
@@ -549,6 +561,16 @@ if ($event['type'] === EventType::SUBSCRIPTION_RENEWED) {
 `order.*` events list the order's `items` and `invoice` like
 [app orders](#app-orders-trusted-apps-no-user-token).
 `billing_limit.reached` and `billing_limit.available` (`EventType::BILLING_LIMIT_REACHED`,
 `BILLING_LIMIT_AVAILABLE`) tell trusted apps that a user's billing limit was reached or has room
 again; they are opt-in like `subscription.renewed`, see
 [Charges and billing limit](#charges-and-billing-limit-trusted-apps).
 `order.refunded` (`EventType::ORDER_REFUNDED`) is sent when money was given back for an order (a
 refund or a partial cancellation, with a credit note); the order carries its `refunds` and
 `refunded_total`. A full refund also cancels the order, so `order.cancelled` is sent too; don't rely on the
 order of the two events.
 ### Errors
 Every failed request throws `Anikeen\Id\Exceptions\ApiException`, with the user's token as
@@ -559,7 +581,11 @@ well as with the app's (`app*()`). It carries:
  `already_cancelled`), otherwise `null`,
 - `getMessage()`: Anikeen ID's reason,
 - `isNotFound()` (404), `isConflict()` (409) and `isTemporary()` (no response, 429 or 5xx: retry
-  later).
+  later),
 - `isBillingLimitReached()` (409 `billing_limit_reached`: a [charge](#charges-and-billing-limit-trusted-apps)
  would take the user's monthly bill above their billing limit),
 - `body()`: the error response, for errors with details (e.g. `remaining` of
  `billing_limit_reached`).
 ```php
 use Anikeen\Id\Exceptions\ApiException;
@@ -837,6 +863,127 @@ link's user. The session ends after an hour without activity or on "Back to *app
 payment) and back to `return_url`. For the signed-in user with their own token,
 `$user->billingPortalUrl()` stays available.
 ### Charges and billing limit (trusted apps)
 Trusted apps can book single items onto a user's **open monthly bill** of the app, e.g. each item
 a shipping app sends: one line per charge, no subscription, charged with the bill on the 1st like
 every other line (invoice and VAT by Anikeen ID). Anikeen has to enable charging for your app and
 sets a maximum per charge; the user must be connected to your app (they authorised it, or your app
 bills them through subscriptions or orders).
 ```php
 $anikeen = app(AnikeenId::class);
 $charge = $anikeen->createChargeForUser($user->anikeen_id, [
    'idempotency_key' => "shipment-{$shipment->id}", // per app and user: a retry returns the same charge
    'name' => 'Signed card',                         // the line on the bill
    'type' => 'physical',                            // digital (default), physical, physical-reduced
    'quantity' => 2,
    'unit_price' => '4.00',                          // net per piece, up to 6 decimals
    'reference' => "order-{$shipment->order_id}",    // your own id; not on the bill
    // 'group' => $team->id,                         // only a group your app already bills the user in
    // 'occurred_at' => '2026-11-05T14:00:00Z',      // the service date, at most 31 days ago
 ]);
 $charge->id();          // keep it to void the charge later
 $charge->grossAmount(); // "9.52": what it added to the bill
 $charge->orderId();     // the monthly bill it is on
 $charge->status();      // open, billed (the bill was closed) or voided
 $anikeen->findChargeForUser($user->anikeen_id, $chargeId);
 $anikeen->voidChargeForUser($user->anikeen_id, $chargeId, 'Parcel lost'); // while the bill is open
 ```
 - **Idempotency:** retrying with the same key and the same fields returns the existing charge
  (200 instead of 201), also after the limit was reached; the same key with other fields is 409
  `idempotency_key_conflict` (`charge_id` in `body()`). Use one key per item you charge for.
 - **Voiding** removes the line while the bill is open (an already voided charge is returned as
  it is). Once the bill was closed: 409 `charge_already_billed`; only a refund of the order by
  Anikeen credits it.
 - **`group`** is null or a group your app already bills the user in (a running subscription or an
  open monthly bill of your app); others are refused with 409 `group_not_allowed`.
 - `reference` and `metadata` (up to 20 string values) are your data about the user, kept with the
  charge and not shown on the bill: put nothing sensitive there.
 **Billing limit.** A user can set one monthly limit (gross) for their whole open monthly bill
 across all Anikeen services. A charge that would take the bill above it is refused with 409
 `billing_limit_reached`; exactly reaching the limit is allowed, `0.00` refuses every charge.
 Subscription renewals and usage are still billed, so the bill can end above the limit. Read the
 limit to stop offering paid actions early (advisory only, it reserves nothing):
 ```php
 $limit = $anikeen->billingLimitForUser($user->anikeen_id);
 $limit->hasLimit();     // false: no limit, every charge fits
 $limit->isReached();    // used >= limit: start no new paid service
 $limit->remaining();    // "17.60" gross room left, null without a limit
 $limit->remainingNet(); // "14.78" at the user's VAT rate, a hint
 $limit->allows('9.52'); // would this charge fit right now (advisory)
 $limit->resetsAt();     // when this month's bills are closed
 $limit->version();      // only goes up
 $limit->used();         // the user's open bills across all Anikeen services, null without a limit
 $limit->usedByApp();    // your app's share; used − usedByApp = "your other Anikeen services"
 ```
 `used` (the user's open bills across all Anikeen services) is visible to apps **only while the
 user has set a limit**; without one `limit`, `used`, `remaining` and `remaining_net` are null.
 `usedByApp()` (your app's own open bills) is always there. The user sees their own limit in
 `$user->billingOverview()->billing_limit` (with `used`, without `used_by_app`; null while they
 can't set one). Apps that may charge can read the limit; others need Anikeen to allow it (403
 `billing_limit_not_enabled`).
 Handling a refused charge:
 ```php
 use Anikeen\Id\Exceptions\ApiException;
 try {
    $charge = $anikeen->createChargeForUser($user->anikeen_id, $attributes);
 } catch (ApiException $e) {
    if ($e->isBillingLimitReached()) {
        $e->body()->remaining;  // room left before this charge, e.g. "2.60"
        $e->body()->required;   // the refused charge, gross
        $e->body()->resets_at;  // when the limit has room again at the latest
        return $shipment->holdForBillingLimit();
    }
    match ($e->error) {
        'charge_exceeds_maximum' => report($e),   // above your app's maximum ($e->body()->max_charge_net)
        'group_not_allowed' => report($e),
        'billing_address_missing' => $shipment->askForBillingAddress(),
        default => throw $e,
    };
 }
 ```
 **Webhooks.** `billing_limit.reached` and `billing_limit.available` are sent when the limit is
 reached or has room again (a raised or removed limit, a void, the monthly reset). They are
 **opt-in** (select them for your endpoint; `*` doesn't include them) and go only to apps that may
 read the limit of a user connected to them. `data.object` is the billing limit as your app reads
 it, `data.reason` says why (`booking`, `limit_changed`, `limit_removed`, `voided`,
 `period_reset`, `order_changed`). Keep the highest `version` per user and ignore events with a
 lower or equal one, so a late delivery can't undo a newer state. In the `match` of the
 [webhook route](#webhooks):
 ```php
 EventType::BILLING_LIMIT_REACHED, EventType::BILLING_LIMIT_AVAILABLE => Customer::syncBillingLimit(
    $object['user_id'], reached: $event['type'] === EventType::BILLING_LIMIT_REACHED, version: $object['version'],
 ),
 ```
 The limit is checked live when a charge is booked, so a late or missed webhook never lets a
 charge through; poll `billingLimitForUser()` if you need the current state.
 #### Error codes
 | Status | `error` |
 |--------|---------|
 | 403 | `client_not_allowed` (not a trusted app with its own token), `charges_not_enabled` (charging is not enabled for your app; also for reads and voids), `billing_limit_not_enabled` (limit read only) |
 | 404 | `user_not_found` (unknown, deleted or not connected to your app), `charge_not_found` |
 | 409 | `billing_limit_reached` (`isBillingLimitReached()`), `charge_exceeds_maximum` (+ `max_charge_net`), `group_not_allowed`, `idempotency_key_conflict` (+ `charge_id`), `billing_address_missing`, `charge_already_billed` (+ `charge_id`) |
 | 422 | validation (`errors`), no `error` code |
 | 429 | `too_many_requests` (`isTemporary()`) |
 ### Checkout sessions (the user confirms several subscriptions at once)
 Instead of checking subscriptions out itself, an app can let the user confirm them on Anikeen ID,
@@ -918,6 +1065,156 @@ $result->data->invitation_sent;        // only for an account created by this ca
 other than an unknown address.
 ## Preferences
 Anikeen ID keeps small per-user settings as JSON values under a *namespace* and a *key*, so they
 follow the user across devices and apps:
 - **`global`** is shared by all apps. Only registered keys and values are accepted: today
  `SharedPreference::APPEARANCE` with `Appearance::SYSTEM`, `LIGHT` or `DARK`.
 - **App namespaces** (e.g. `acme`) hold one app's own data: onboarding state, a default workspace,
  the user's customer ID at a payment provider. Use another namespace on staging (e.g.
  `acme-staging`), so test data never mixes with production.
 **Registration.** Access never comes from scopes alone: any client can request any scope. Ask
 Anikeen to register your OAuth client(s) (the app has to be [trusted](#trusted-apps)) for
 - the namespaces your app owns (read, write and the lookup),
 - read access to another app's namespace,
 - `global` with the app's token (users always read and write their own `global` with their token),
 - keys whose values are unique (see the lookup below).
 Without it, app requests fail with 403 `client_not_trusted` or 404 `namespace_not_found`.
 **Scopes.** User tokens need `Scope::PREFERENCES` (`preferences`, read and write) or
 `Scope::PREFERENCES_READ` (`preferences:read`); app tokens `Scope::PREFERENCES_CLIENT`
 (`preferences:client`).
 **Limits.** A value is at most 2048 bytes of JSON and 4 levels deep; at most 50 keys per user and
 namespace (updating a key always works); keys match `^[a-z][a-z0-9_]{0,63}$`. Per minute: 60
 requests per user and app with user tokens, 600 per app with the app token and 120 lookups per
 app (429 `rate_limited` with `Retry-After`).
 **Not a secrets store.** Values are stored as plain JSON and shown to Anikeen's support and to the
 user on a request for their data. Store IDs and settings, never passwords, API keys or tokens: keys
 that look like credentials (`secret`, `token`, `password`, `api_key`, …) are rejected with 422
 `forbidden_key`.
 ### The user's shared preferences (user token)
 ```php
 use Anikeen\Id\Enums\Appearance;
 use Anikeen\Id\Enums\SharedPreference;
 $user->globalPreference(SharedPreference::APPEARANCE, Appearance::SYSTEM); // the default when not set
 $user->globalPreferences()->values();     // ['appearance' => 'dark']
 $preference = $user->setGlobalPreference(SharedPreference::APPEARANCE, Appearance::DARK);
 $preference->version;                     // e.g. 1042
 $user->deleteGlobalPreference(SharedPreference::APPEARANCE);
 ```
 User tokens reach `global` only; an app namespace answers 404 `namespace_not_found`, whatever the
 token's scopes. The app's own token (client credentials) has no user and gets 401 on these routes.
 ### Preferences of any user (trusted apps)
 With the app's own token, by the user's Anikeen ID:
 ```php
 $anikeenId = app(AnikeenId::class);
 $preferences = $anikeenId->preferencesByUserId($userId, 'acme'); // sorted by key, no pagination
 $preferences->get('onboarding', []);     // the value or a default; also has(), find(), values()
 $preference = $anikeenId->preferenceByUserId($userId, 'acme', 'onboarding'); // 404 preference_not_found if not set
 $preference->value;                      // JSON objects as stdClass, so {} stays {}
 $preference->version;
 $preference->updated_by;                 // {type: "user"|"app", client_id}
 $anikeenId->setPreferenceByUserId($userId, 'acme', 'onboarding', ['step' => 3]);
 $anikeenId->deletePreferenceByUserId($userId, 'acme', 'onboarding');
 ```
 A value is any JSON value; pass `(object) []` for an empty object (`[]` is an empty list).
 `setPreferenceByUserId()` returns the stored preference; `wasCreated()` tells whether the write
 created the key. A deleted user's preferences are gone: every call answers 404 `user_not_found`.
 ### Conditional writes and retries
 Writes are *last write wins* by default. Every write gives the preference a new `version`.
 Versions are opaque: they only go up (also when a key is deleted and set again) and increase per
 user, not by one per key. Pass the version you read to write only if nobody changed it in between
 (`If-Match`), or `createOnly` to write only if the key isn't set yet (`If-None-Match: *`):
 ```php
 use Anikeen\Id\Exceptions\PreconditionFailedException;
 $preference = $anikeenId->preferenceByUserId($userId, 'acme', 'layout');
 try {
    $anikeenId->setPreferenceByUserId($userId, 'acme', 'layout', $merged, ifVersion: $preference->version);
 } catch (PreconditionFailedException $e) {
    $e->error;            // "preference_version_mismatch" (or "preference_exists" for createOnly)
    $e->currentVersion(); // the version stored now, null when the key isn't set: reload, merge, retry
 }
 $anikeenId->setPreferenceByUserId($userId, 'acme', 'welcome_sent_at', now()->toIso8601String(), createOnly: true);
 ```
 `deletePreferenceByUserId()`, `setGlobalPreference()` and `deleteGlobalPreference()` take
 `ifVersion` too. Writing the value that is already stored is a no-op that succeeds (no new version),
 even when the precondition would fail, so retrying a write after a timeout is safe.
 ### Unique keys and the lookup
 Anikeen can declare keys of your namespace unique, e.g. `customer_id`. Their values are strings of
 1 to 255 characters without surrounding whitespace, held by at most one user: setting another
 user's value fails with 409 `preference_value_taken`. Your app can then find the user by value, e.g.
 in a payment provider's webhook:
 ```php
 $userId = $anikeenId->findUserIdByPreference('acme', 'customer_id', 'cus_123'); // null if nobody holds it
 ```
 The value is sent in the body, never in the URL. `findUserIdByPreference()` returns `null` only for
 404 `preference_not_found` (also when the user was deleted); everything else throws, e.g. 422
 `key_not_unique` for a key that isn't declared unique.
 ### Error codes
 Failures throw `ApiException` (412 `PreconditionFailedException`) with these `error` codes:
 | Status | `error` |
 |--------|---------|
 | 401 | `unauthenticated` (no or an invalid token; an app token on the user routes) |
 | 403 | `missing_scope`, `app_token_required` (a user token on the app routes), `client_not_trusted`, `namespace_read_only`, `lookup_not_allowed` |
 | 404 | `namespace_not_found` (unknown or not accessible), `user_not_found` (also deleted users), `preference_not_found`, `not_found` |
 | 405 | `method_not_allowed` |
 | 409 | `preference_value_taken` |
 | 412 | `preference_version_mismatch`, `preference_exists` |
 | 422 | `invalid_key`, `forbidden_key`, `unknown_shared_key`, `value_required`, `value_too_large`, `value_too_deep`, `invalid_shared_value`, `invalid_unique_value`, `key_not_unique`, `preference_limit_exceeded` |
 | 429 | `rate_limited` |
 A `null` value is rejected with 422 `value_required`: delete the key instead.
 ### Caching
 Anikeen ID is the source of truth. `globalPreferences()` and `globalPreference()` cache the list
 on the model instance (one request per instance); `setGlobalPreference()` and
 `deleteGlobalPreference()` clear it. For a copy that outlives the request, keep a read cache: fill
 it at sign-in, write to Anikeen ID first and update the copy from the response, and let it expire
 after about an hour, since other apps and the user can change shared preferences too:
 ```php
 $appearance = Cache::remember("appearance:{$user->id}", now()->addHour(),
    fn () => $user->globalPreference(SharedPreference::APPEARANCE, Appearance::SYSTEM));
 $user->setGlobalPreference(SharedPreference::APPEARANCE, $request->appearance);
 Cache::put("appearance:{$user->id}", $request->appearance, now()->addHour());
 ```
 ## API authentication
 Use this when your own API accepts access tokens issued by Anikeen ID.
@@ -2,6 +2,7 @@
 namespace Anikeen\Id;
 use Anikeen\Id\Concerns\ManagesPreferences;
 use Anikeen\Id\Concerns\ManagesPricing;
 use Anikeen\Id\Concerns\ManagesProducts;
 use Anikeen\Id\Concerns\ManagesShippingLabels;
@@ -23,6 +24,7 @@ use Illuminate\Contracts\Auth\Authenticatable;
 class AnikeenId
 {
    use OauthTrait;
    use ManagesPreferences;
    use ManagesPricing;
    use ManagesProducts;
    use ManagesShippingLabels;
@@ -369,10 +371,12 @@ class AnikeenId
    /**
     * Build query & execute.
     *
     * @param array<string, string> $headers Extra request headers, e.g. `If-Match` for conditional
     *     writes; they are sent in addition to (and may not replace) Client-ID, Accept and Authorization.
     * @throws GuzzleException
     * @throws RequestRequiresClientIdException
     */
-    public function request(string $method, string $path, null|array $payload = null, array $parameters = [], ?Paginator $paginator = null, bool $useClientSecret = false): Result
+    public function request(string $method, string $path, null|array $payload = null, array $parameters = [], ?Paginator $paginator = null, bool $useClientSecret = false, array $headers = []): Result
    {
        if ($paginator !== null) {
            $parameters[$paginator->action] = $paginator->cursor();
@@ -380,7 +384,7 @@ class AnikeenId
        try {
            $response = $this->client->request($method, $path, [
-                'headers' => $this->buildHeaders((bool)$payload, $useClientSecret),
+                'headers' => $this->buildHeaders((bool)$payload, $useClientSecret) + $headers,
                'query' => Query::build($parameters),
                'json' => $payload ?: null,
            ]);
@@ -419,35 +423,35 @@ class AnikeenId
     * @throws GuzzleException
     * @throws RequestRequiresClientIdException
     */
-    public function get(string $path, array $parameters = [], ?Paginator $paginator = null): Result
+    public function get(string $path, array $parameters = [], ?Paginator $paginator = null, array $headers = []): Result
    {
-        return $this->request('GET', $path, null, $parameters, $paginator);
+        return $this->request('GET', $path, null, $parameters, $paginator, false, $headers);
    }
    /**
     * @throws GuzzleException
     * @throws RequestRequiresClientIdException
     */
-    public function post(string $path, array $payload = [], array $parameters = [], ?Paginator $paginator = null): Result
+    public function post(string $path, array $payload = [], array $parameters = [], ?Paginator $paginator = null, array $headers = []): Result
    {
-        return $this->request('POST', $path, $payload, $parameters, $paginator);
+        return $this->request('POST', $path, $payload, $parameters, $paginator, false, $headers);
    }
    /**
     * @throws GuzzleException
     * @throws RequestRequiresClientIdException
     */
-    public function put(string $path, array $payload = [], array $parameters = [], ?Paginator $paginator = null): Result
+    public function put(string $path, array $payload = [], array $parameters = [], ?Paginator $paginator = null, array $headers = []): Result
    {
-        return $this->request('PUT', $path, $payload, $parameters, $paginator);
+        return $this->request('PUT', $path, $payload, $parameters, $paginator, false, $headers);
    }
    /**
     * @throws GuzzleException
     * @throws RequestRequiresClientIdException
     */
-    public function delete(string $path, array $payload = [], array $parameters = [], ?Paginator $paginator = null): Result
+    public function delete(string $path, array $payload = [], array $parameters = [], ?Paginator $paginator = null, array $headers = []): Result
    {
-        return $this->request('DELETE', $path, $payload, $parameters, $paginator);
+        return $this->request('DELETE', $path, $payload, $parameters, $paginator, false, $headers);
    }
 }
@@ -9,6 +9,7 @@ use Anikeen\Id\Concerns\ManagesInvoices;
 use Anikeen\Id\Concerns\ManagesOrders;
 use Anikeen\Id\Concerns\ManagesPaymentMethods;
 use Anikeen\Id\Concerns\ManagesProfile;
 use Anikeen\Id\Concerns\ManagesUserPreferences;
 use Anikeen\Id\Concerns\ManagesSubscriptions;
 use Anikeen\Id\Concerns\ManagesTaxation;
 use Anikeen\Id\Concerns\ManagesTransactions;
@@ -27,6 +28,7 @@ trait Billable
    use ManagesSubscriptions;
    use ManagesTaxation;
    use ManagesTransactions;
    use ManagesUserPreferences;
    use ManagesUserSshKeys;
    /*
@@ -40,6 +42,8 @@ trait Billable
    protected mixed $invoicesCache = null;
    protected mixed $ordersCache = null;
    protected mixed $paymentMethodsCache = null;
    /** @var array<string, \Anikeen\Id\Resources\Preferences> by namespace */
    protected array $preferencesCache = [];
    protected mixed $subscriptionsCache = null;
    protected mixed $transactionsCache = null;
    protected mixed $userDataCache = null;
@@ -31,7 +31,13 @@ trait ManagesBalance
    /**
     * Billing overview of the current user: current_balance, current_charges, vat_rate,
-     * has_billing_address, has_default_payment_method, open_orders.
+     * has_billing_address, has_default_payment_method, open_orders and billing_limit.
     *
     * billing_limit is the user's monthly billing limit {object: "billing_limit", user_id,
     * currency, basis, limit, used, remaining, remaining_net, vat_rate, reached, resets_at,
     * version} (`limit`, `remaining` and `remaining_net` null without a limit; wrap it in
     * `new \Anikeen\Id\Resources\BillingLimit(…)` for its helpers), or null while the user has no
     * limit and can't set one yet. Older Anikeen ID releases don't send the key.
     *
     * @throws Throwable
     */
@@ -0,0 +1,107 @@
 <?php
 namespace Anikeen\Id\Concerns;
 use Anikeen\Id\Exceptions\ApiException;
 use Anikeen\Id\Exceptions\PreconditionFailedException;
 use Anikeen\Id\Resources\Preference;
 use Anikeen\Id\Resources\Preferences;
 use Anikeen\Id\Support\AppRequest;
 use Anikeen\Id\Support\PreferenceRequest;
 /**
 * Preferences of any user, with the app's own token (client credentials, scope
 * `preferences:client`). Anikeen has to register the app for each namespace it uses: its own
 * namespaces (read, write, lookup), read access to another app's namespace, or access to `global`.
 * Without it every call fails with 403 "client_not_trusted" or 404 "namespace_not_found".
 */
 trait ManagesPreferences
 {
    /**
     * All preferences of a user in a namespace, sorted by key.
     *
     * @throws ApiException 404 "namespace_not_found", "user_not_found" (also deleted users), …
     */
    public function preferencesByUserId(string $userId, string $namespace): Preferences
    {
        return Preferences::builder(fn () => AppRequest::send('GET', $this->userPreferencePath($userId, $namespace)));
    }
    /**
     * One preference of a user.
     *
     * @throws ApiException 404 "preference_not_found" when the key isn't set, "user_not_found", …
     */
    public function preferenceByUserId(string $userId, string $namespace, string $key): Preference
    {
        return new Preference(fn () => AppRequest::send('GET', $this->userPreferencePath($userId, $namespace, $key)));
    }
    /**
     * Set a preference of a user. The value is any JSON value (pass `(object) []` for `{}`), at
     * most 2048 bytes and 4 levels deep. Writing the value already stored changes nothing and
     * succeeds, also when a precondition would fail, so a retried write is safe.
     *
     * @param int|null $ifVersion only if the stored version is this one (`If-Match`)
     * @param bool $createOnly only if the key isn't set yet (`If-None-Match: *`); not with $ifVersion
     * @throws PreconditionFailedException 412 "preference_version_mismatch" / "preference_exists",
     *     with currentVersion()
     * @throws ApiException 403 "namespace_read_only", 409 "preference_value_taken" (a unique key),
     *     422 "invalid_key", "forbidden_key", "value_too_large", "preference_limit_exceeded", …
     */
    public function setPreferenceByUserId(string $userId, string $namespace, string $key, mixed $value, ?int $ifVersion = null, bool $createOnly = false): Preference
    {
        $headers = PreferenceRequest::conditions($ifVersion, $createOnly);
        return new Preference(fn () => AppRequest::send('PUT', $this->userPreferencePath($userId, $namespace, $key), ['value' => $value], [], $headers));
    }
    /**
     * Delete a preference of a user.
     *
     * @param int|null $ifVersion only if the stored version is this one (`If-Match`)
     * @throws PreconditionFailedException 412 "preference_version_mismatch", with currentVersion()
     * @throws ApiException 404 "preference_not_found" when the key isn't set, …
     */
    public function deletePreferenceByUserId(string $userId, string $namespace, string $key, ?int $ifVersion = null): void
    {
        AppRequest::send('DELETE', $this->userPreferencePath($userId, $namespace, $key), null, [], PreferenceRequest::conditions($ifVersion));
    }
    /**
     * The ID of the user holding a value of a unique key in one of the app's own namespaces, e.g.
     * the user of a payment provider's customer ID. The value is sent in the body, never in the URL.
     *
     * @return string|null null when no (not deleted) user holds the value
     * @throws ApiException 422 "key_not_unique", "invalid_unique_value", 403 "lookup_not_allowed", …
     */
    public function findUserIdByPreference(string $namespace, string $key, string $value): ?string
    {
        try {
            $result = AppRequest::send('POST', PreferenceRequest::path('v1/client/preferences', $namespace, 'lookup'), [
                'key' => $key,
                'value' => $value,
            ]);
        } catch (ApiException $e) {
            // only Anikeen ID's own answer means "nobody holds it", not e.g. an unknown namespace
            if ($e->isNotFound() && $e->error === 'preference_not_found') {
                return null;
            }
            throw $e;
        }
        return $result->data->user_id;
    }
    private function userPreferencePath(string $userId, string $namespace, ?string $key = null): string
    {
        $segments = [$userId, 'preferences', $namespace];
        if ($key !== null) {
            $segments[] = $key;
        }
        return PreferenceRequest::path('v1/client/users', ...$segments);
    }
 }
@@ -3,8 +3,10 @@
 namespace Anikeen\Id\Concerns;
 use Anikeen\Id\Exceptions\ApiException;
 use Anikeen\Id\Resources\AppCharge;
 use Anikeen\Id\Resources\AppCheckoutSessions;
 use Anikeen\Id\Resources\AppOrders;
 use Anikeen\Id\Resources\BillingLimit;
 use Anikeen\Id\Result;
 use Anikeen\Id\Support\AppRequest;
 use Throwable;
@@ -123,4 +125,101 @@ trait ManagesUserBilling
    {
        return $this->asApp()->request('POST', 'v1/admin/transactions', [...$attributes, 'user_id' => $userId]);
    }
    /**
     * Book a charge onto a user's open monthly bill of the app, e.g. a shipped item: one line,
     * no subscription, charged with the bill on the 1st. Trusted apps that Anikeen allowed to
     * charge (with a maximum per charge), for users connected to the app (they authorised it or
     * the app bills them). The user's billing limit is checked when it is booked.
     *
     * Retrying with the same idempotency key and the same fields returns the existing charge
     * (also after the limit was reached); other fields with that key: 409
     * "idempotency_key_conflict" (`charge_id` in body()).
     *
     * @param string $userId The user's Anikeen ID.
     * @param array{
     *     idempotency_key: string,
     *     name: string,
     *     description?: null|string,
     *     type?: string,
     *     quantity: int,
     *     unit_price: float|int|string,
     *     currency_iso?: string,
     *     group?: null|string,
     *     occurred_at?: string,
     *     reference?: null|string,
     *     metadata?: null|array<string, string>,
     *     image_url?: null|string
     * } $attributes idempotency_key: unique per app and user, ≤ 255 (e.g. "shipment-123").
     *               name: the line on the bill, ≤ 255. description: ≤ 255.
     *               type: digital (default), physical or physical-reduced (the VAT treatment).
     *               quantity: 1–10000 pieces. unit_price: net per piece, > 0, ≤ 100000, up to 6
     *               decimals; quantity × unit_price rounded to cents must be at least 0.01.
     *               currency_iso: EUR only (default).
     *               group: null, or a group in which the app already bills the user (a running
     *               subscription or an open monthly bill of the app).
     *               occurred_at: the service date, not in the future, at most 31 days ago
     *               (default now).
     *               reference: the app's own id (≤ 255). metadata: ≤ 20 keys (≤ 40 characters),
     *               string values ≤ 500. Both are not on the bill; put nothing sensitive there.
     *               image_url: http(s) URL of an image for the line.
     *
     * @throws ApiException 403 "client_not_allowed" (not a trusted app), "charges_not_enabled";
     *     404 "user_not_found" (unknown, deleted or not connected); 409 "billing_limit_reached"
     *     (isBillingLimitReached(); body() has limit, used, remaining, remaining_net, required,
     *     currency, resets_at), "charge_exceeds_maximum" (+ max_charge_net),
     *     "group_not_allowed", "idempotency_key_conflict" (+ charge_id),
     *     "billing_address_missing"; 422 validation; 429 "too_many_requests"
     */
    public function createChargeForUser(string $userId, array $attributes): AppCharge
    {
        return new AppCharge(AppRequest::send('POST', $this->chargesPath($userId), $attributes)->data);
    }
    /**
     * A charge of the app (or of a client delegated to the same app) for a user.
     *
     * @throws ApiException 403 "client_not_allowed", "charges_not_enabled"; 404 "user_not_found",
     *     "charge_not_found"; 429 "too_many_requests"
     */
    public function findChargeForUser(string $userId, string $chargeId): AppCharge
    {
        return new AppCharge(AppRequest::send('GET', $this->chargesPath($userId, $chargeId))->data);
    }
    /**
     * Void a charge while its bill is open: the line is removed and the bill's total drops. An
     * already voided charge is returned as it is. Once the bill is closed only a refund of the
     * order by Anikeen credits it.
     *
     * @param string|null $reason why (≤ 255), stored with the charge
     * @throws ApiException 409 "charge_already_billed" (+ charge_id); 404 "charge_not_found",
     *     "user_not_found"; 403 "client_not_allowed", "charges_not_enabled"; 429 "too_many_requests"
     */
    public function voidChargeForUser(string $userId, string $chargeId, ?string $reason = null): AppCharge
    {
        $payload = $reason === null ? null : ['reason' => $reason];
        return new AppCharge(AppRequest::send('POST', $this->chargesPath($userId, $chargeId) . '/void', $payload)->data);
    }
    /**
     * A user's monthly billing limit as the app sees it, e.g. to pause paid features while it is
     * reached. Advisory only: it reserves nothing; a charge is checked when it is booked. Trusted
     * apps that may charge or that Anikeen allowed to read limits, for users connected to the app.
     *
     * @throws ApiException 403 "client_not_allowed", "billing_limit_not_enabled"; 404
     *     "user_not_found"; 429 "too_many_requests"
     */
    public function billingLimitForUser(string $userId): BillingLimit
    {
        return new BillingLimit(AppRequest::send('GET', sprintf('v1/client/users/%s/billing-limit', rawurlencode($userId)))->data);
    }
    private function chargesPath(string $userId, ?string $chargeId = null): string
    {
        $path = sprintf('v1/client/users/%s/charges', rawurlencode($userId));
        return $chargeId === null ? $path : $path . '/' . rawurlencode($chargeId);
    }
 }
@@ -0,0 +1,96 @@
 <?php
 namespace Anikeen\Id\Concerns;
 use Anikeen\Id\Enums\SharedPreference;
 use Anikeen\Id\Exceptions\ApiException;
 use Anikeen\Id\Exceptions\PreconditionFailedException;
 use Anikeen\Id\Resources\Preference;
 use Anikeen\Id\Resources\Preferences;
 use Anikeen\Id\Support\PreferenceRequest;
 use GuzzleHttp\Exception\GuzzleException;
 /**
 * The user's shared preferences (`global`, e.g. SharedPreference::APPEARANCE), with the user's
 * token (scope `preferences` or `preferences:read`). User tokens reach `global` only; an app's
 * own namespace needs the app token (AnikeenId::preferencesByUserId()).
 */
 trait ManagesUserPreferences
 {
    /**
     * The user's shared preferences, sorted by key. Cached on this instance; set and delete clear it.
     *
     * @throws ApiException
     */
    public function globalPreferences(): Preferences
    {
        $namespace = SharedPreference::NAMESPACE;
        if (!isset($this->preferencesCache[$namespace])) {
            $anikeenId = $this->anikeenId();
            $this->preferencesCache[$namespace] = Preferences::builder(
                fn () => $anikeenId->get(PreferenceRequest::path('v1/preferences', $namespace))
            );
        }
        return $this->preferencesCache[$namespace];
    }
    /**
     * The value of a shared preference, or $default when the user hasn't set it.
     *
     * @throws ApiException
     */
    public function globalPreference(string $key, mixed $default = null): mixed
    {
        return $this->globalPreferences()->get($key, $default);
    }
    /**
     * Set a shared preference of the user, e.g. setGlobalPreference(SharedPreference::APPEARANCE,
     * Appearance::DARK). Only registered keys and values are accepted (422 "unknown_shared_key",
     * "invalid_shared_value").
     *
     * @param int|null $ifVersion only if the stored version is this one (`If-Match`)
     * @throws PreconditionFailedException 412 "preference_version_mismatch", with currentVersion()
     * @throws ApiException
     */
    public function setGlobalPreference(string $key, mixed $value, ?int $ifVersion = null): Preference
    {
        $namespace = SharedPreference::NAMESPACE;
        $headers = PreferenceRequest::conditions($ifVersion);
        $anikeenId = $this->anikeenId();
        try {
            return new Preference(fn () => $anikeenId->put(PreferenceRequest::path('v1/preferences', $namespace, $key), ['value' => $value], [], null, $headers));
        } finally {
            unset($this->preferencesCache[$namespace]);
        }
    }
    /**
     * Delete a shared preference of the user.
     *
     * @param int|null $ifVersion only if the stored version is this one (`If-Match`)
     * @throws PreconditionFailedException 412 "preference_version_mismatch", with currentVersion()
     * @throws ApiException 404 "preference_not_found" when the key isn't set, …
     */
    public function deleteGlobalPreference(string $key, ?int $ifVersion = null): void
    {
        $namespace = SharedPreference::NAMESPACE;
        $headers = PreferenceRequest::conditions($ifVersion);
        try {
            $result = $this->anikeenId()->delete(PreferenceRequest::path('v1/preferences', $namespace, $key), [], [], null, $headers);
        } catch (GuzzleException $e) {
            throw ApiException::unreachable($e);
        } finally {
            unset($this->preferencesCache[$namespace]);
        }
        if (!$result->success()) {
            throw ApiException::fromResult($result);
        }
    }
 }
@@ -0,0 +1,22 @@
 <?php
 namespace Anikeen\Id\Enums;
 /**
 * The values of the shared preference SharedPreference::APPEARANCE.
 */
 class Appearance
 {
    /** Follow the operating system. */
    const SYSTEM = 'system';
    const LIGHT = 'light';
    const DARK = 'dark';
    /**
     * @return list<string>
     */
    public static function all(): array
    {
        return [self::SYSTEM, self::LIGHT, self::DARK];
    }
 }
@@ -33,6 +33,12 @@ class Scope
    const TRANSACTIONS_READ = 'transactions:read';
    const TRANSACTIONS_CLIENT = 'transactions:client';
    // The user's own shared preferences (`global`). PREFERENCES_CLIENT labels an app token for
    // the preferences of any user; access to a namespace is granted by Anikeen, not by the scope.
    const PREFERENCES = 'preferences';
    const PREFERENCES_READ = 'preferences:read';
    const PREFERENCES_CLIENT = 'preferences:client';
    const SSH_KEYS = 'ssh-keys';
    const SSH_KEYS_READ = 'ssh-keys:read';
@@ -0,0 +1,16 @@
 <?php
 namespace Anikeen\Id\Enums;
 /**
 * The keys of the `global` preferences namespace, shared by all apps. Anikeen ID accepts only
 * these keys there, each with its own values.
 */
 class SharedPreference
 {
    /** The namespace of the shared preferences. */
    const NAMESPACE = 'global';
    /** Light or dark mode: one of the Appearance constants. */
    const APPEARANCE = 'appearance';
 }
@@ -28,10 +28,16 @@ class ApiException extends ResourceException
    public static function fromResult(Result $result): static
    {
        $body = is_object($result->data) ? $result->data : null;
        $status = $result->response()?->getStatusCode() ?? 0;
        // a failed conditional write; subclasses (CollectionException) keep their own type
        if ($status === 412 && static::class === self::class) {
            return PreconditionFailedException::fromResult($result);
        }
        return new static(
            rtrim((string) ($body->message ?? $result->error()), '.'),
-            $result->response()?->getStatusCode() ?? 0,
+            $status,
            $body->error ?? null,
            $result->exception,
        );
@@ -73,6 +79,16 @@ class ApiException extends ResourceException
        return $this->status === 409;
    }
    /**
     * A charge was refused because it would take the user's open monthly bill above their billing
     * limit (409 "billing_limit_reached"). body() has limit, used, remaining, remaining_net,
     * required, currency and resets_at.
     */
    public function isBillingLimitReached(): bool
    {
        return $this->status === 409 && $this->error === 'billing_limit_reached';
    }
    /**
     * The ID service could not be reached (network error, timeout) or failed (5xx): retry later.
     */
@@ -0,0 +1,21 @@
 <?php
 namespace Anikeen\Id\Exceptions;
 /**
 * A conditional write failed (412): the stored version wasn't the one sent with `If-Match`
 * ("preference_version_mismatch"), or the key was already set and the write was create-only
 * ("preference_exists"). Reload, merge and retry with currentVersion().
 */
 class PreconditionFailedException extends ApiException
 {
    /**
     * The version stored now, null when the key isn't set (or Anikeen ID didn't send one).
     */
    public function currentVersion(): ?int
    {
        $version = $this->body()->current_version ?? null;
        return is_numeric($version) ? (int) $version : null;
    }
 }
@@ -0,0 +1,139 @@
 <?php
 namespace Anikeen\Id\Resources;
 use DateTimeImmutable;
 use JsonSerializable;
 /**
 * A charge a trusted app booked onto a user's open monthly bill, see
 * AnikeenId::createChargeForUser(). Amounts are decimal strings (`unit_price` with six decimals,
 * the others with two).
 *
 * @property string $object "charge"
 * @property string $id
 * @property string $user_id
 * @property string $status open (its bill is open), billed (the bill was closed) or voided
 * @property string $idempotency_key
 * @property string $name the line on the bill
 * @property ?string $description
 * @property string $type digital, physical or physical-reduced (the VAT treatment)
 * @property int $quantity
 * @property string $unit "piece"
 * @property string $unit_price net per piece
 * @property string $net_amount
 * @property string $gross_amount what the charge added to the bill, VAT included
 * @property string $currency_iso
 * @property ?string $group
 * @property string $occurred_at the line's service date (ISO 8601)
 * @property ?string $reference the app's own id
 * @property object $metadata the app's own data (string values)
 * @property ?string $order_id the monthly bill (order) the line is on; follows the line when a rollover moves it
 * @property ?string $voided_at
 * @property ?string $void_reason
 * @property string $created_at
 */
 class AppCharge implements JsonSerializable
 {
    public const STATUS_OPEN = 'open';
    public const STATUS_BILLED = 'billed';
    public const STATUS_VOIDED = 'voided';
    public function __construct(protected object $data)
    {
    }
    public function __get(string $name): mixed
    {
        return $this->data->{$name} ?? null;
    }
    public function __isset(string $name): bool
    {
        return isset($this->data->{$name});
    }
    public function id(): string
    {
        return $this->data->id;
    }
    /**
     * open, billed or voided (the STATUS_* constants).
     */
    public function status(): string
    {
        return $this->data->status;
    }
    /**
     * Its bill is still open: the charge can be voided.
     */
    public function isOpen(): bool
    {
        return $this->status() === self::STATUS_OPEN;
    }
    /**
     * Its bill was closed (paid, waiting for payment or cancelled): only a refund of the order by
     * Anikeen credits it.
     */
    public function isBilled(): bool
    {
        return $this->status() === self::STATUS_BILLED;
    }
    public function isVoided(): bool
    {
        return $this->status() === self::STATUS_VOIDED;
    }
    /**
     * Net, e.g. "8.00".
     */
    public function netAmount(): string
    {
        return $this->data->net_amount;
    }
    /**
     * Gross, what the charge added to the bill, e.g. "9.52".
     */
    public function grossAmount(): string
    {
        return $this->data->gross_amount;
    }
    /**
     * The monthly bill (order) the charge is on, null once its line is gone (voided).
     */
    public function orderId(): ?string
    {
        return $this->data->order_id ?? null;
    }
    /**
     * @return array<string, string>
     */
    public function metadata(): array
    {
        return (array) ($this->data->metadata ?? []);
    }
    public function occurredAt(): ?DateTimeImmutable
    {
        return isset($this->data->occurred_at) ? new DateTimeImmutable($this->data->occurred_at) : null;
    }
    public function toArray(): array
    {
        return (array) $this->data;
    }
    public function jsonSerialize(): array
    {
        return $this->toArray();
    }
 }
@@ -0,0 +1,186 @@
 <?php
 namespace Anikeen\Id\Resources;
 use DateTimeImmutable;
 use JsonSerializable;
 /**
 * A user's monthly billing limit: one gross limit for their whole open monthly bill across all
 * Anikeen services, see AnikeenId::billingLimitForUser() and the `billing_limit` key of
 * billingOverview(). Amounts are decimal strings with two decimals.
 *
 * Without a limit `limit`, `remaining` and `remaining_net` are null; for an app `used` is null
 * too (an app sees the user's whole open bill only while they have set a limit). `used_by_app`
 * (the open bills of your app) is there only when an app reads the limit.
 *
 * @property string $object "billing_limit"
 * @property string $user_id
 * @property string $currency "EUR"
 * @property string $basis "gross"
 * @property ?string $limit
 * @property ?string $used the user's open monthly bills across all Anikeen services
 * @property ?string $used_by_app the open monthly bills of your app (app reads only)
 * @property ?string $remaining max(0, limit − used)
 * @property ?string $remaining_net remaining at the user's VAT rate, rounded down (a hint)
 * @property int|float|null $vat_rate null without a billing address
 * @property bool $reached used >= limit: start no new paid service
 * @property string $resets_at when this month's bills are closed (ISO 8601)
 * @property int $version only goes up; keep the highest seen (also in the billing_limit.* webhooks)
 */
 class BillingLimit implements JsonSerializable
 {
    public function __construct(protected object $data)
    {
    }
    public function __get(string $name): mixed
    {
        return $this->data->{$name} ?? null;
    }
    public function __isset(string $name): bool
    {
        return isset($this->data->{$name});
    }
    /**
     * The user has set a limit (`0.00` is one too: no new charges at all).
     */
    public function hasLimit(): bool
    {
        return $this->limit() !== null;
    }
    /**
     * Gross, null without a limit.
     */
    public function limit(): ?string
    {
        return $this->data->limit ?? null;
    }
    /**
     * The user's open monthly bills across all Anikeen services (gross). Null for an app while the
     * user has no limit.
     */
    public function used(): ?string
    {
        return $this->data->used ?? null;
    }
    /**
     * The open monthly bills of your app (gross); null outside an app read (billingOverview()).
     * `used − used_by_app` is what the user spends on their other Anikeen services.
     */
    public function usedByApp(): ?string
    {
        return $this->data->used_by_app ?? null;
    }
    /**
     * Gross room left (never negative), null without a limit.
     */
    public function remaining(): ?string
    {
        return $this->data->remaining ?? null;
    }
    /**
     * The room left as a net amount at the user's VAT rate, rounded down: a hint only (the VAT of
     * a charge depends on its type). Null without a limit or a billing address.
     */
    public function remainingNet(): ?string
    {
        return $this->data->remaining_net ?? null;
    }
    /**
     * The user's VAT rate in percent (e.g. 19.0), null without a billing address.
     */
    public function vatRate(): ?float
    {
        return isset($this->data->vat_rate) ? (float) $this->data->vat_rate : null;
    }
    public function currency(): string
    {
        return $this->data->currency ?? 'EUR';
    }
    /**
     * The limit is reached (used >= limit): start no new paid service for the user.
     */
    public function isReached(): bool
    {
        return (bool) ($this->data->reached ?? false);
    }
    /**
     * When this month's bills are closed and `used` drops.
     */
    public function resetsAt(): ?DateTimeImmutable
    {
        return isset($this->data->resets_at) ? new DateTimeImmutable($this->data->resets_at) : null;
    }
    /**
     * Only goes up: keep the highest one seen and ignore webhooks with a lower or equal one.
     */
    public function version(): int
    {
        return (int) ($this->data->version ?? 0);
    }
    /**
     * Whether a charge of $gross (gross, e.g. "4.76") would fit as of this read: always without a
     * limit, else at most `remaining`. Advisory only: it reserves nothing, the binding check is
     * the booking (409 "billing_limit_reached").
     */
    public function allows(string|int|float $gross): bool
    {
        if (!$this->hasLimit()) {
            return true;
        }
        $remaining = $this->remaining();
        return $remaining !== null && self::compare($gross, $remaining) <= 0;
    }
    public function toArray(): array
    {
        return (array) $this->data;
    }
    public function jsonSerialize(): array
    {
        return $this->toArray();
    }
    /**
     * Compares two non-negative decimal amounts exactly (as digit strings, no float rounding);
     * negative amounts count as zero.
     */
    private static function compare(string|int|float $a, string|int|float $b): int
    {
        return strcmp(self::micros($a), self::micros($b)) <=> 0;
    }
    /**
     * The amount in millionths as a zero-padded digit string of a fixed width.
     */
    private static function micros(string|int|float $amount): string
    {
        $amount = is_float($amount) ? number_format($amount, 6, '.', '') : trim((string) $amount);
        if (str_starts_with($amount, '-')) {
            return str_repeat('0', 40);
        }
        [$whole, $fraction] = array_pad(explode('.', ltrim($amount, '+'), 2), 2, '');
        $digits = preg_replace('/\D/', '', $whole) . substr(str_pad(preg_replace('/\D/', '', $fraction), 6, '0'), 0, 6);
        return str_pad(ltrim($digits, '0'), 40, '0', STR_PAD_LEFT);
    }
 }
@@ -0,0 +1,27 @@
 <?php
 namespace Anikeen\Id\Resources;
 /**
 * A preference of a user: a JSON value under a namespace and a key. `version` is opaque: it only
 * goes up (per user, not consecutive per key) and is what ifVersion (`If-Match`) compares.
 * JSON objects come back as stdClass, so `{}` stays an object.
 *
 * @property string $namespace
 * @property string $key
 * @property mixed $value
 * @property int $version
 * @property string $updated_at
 * @property object{type: string, client_id: ?string} $updated_by `type` "user" (written with a user token) or "app"
 */
 class Preference extends BaseResource
 {
    /**
     * The write that returned this preference created the key (201). False for reads, updates and
     * writes of the value already stored.
     */
    public function wasCreated(): bool
    {
        return $this->result->response()?->getStatusCode() === 201;
    }
 }
@@ -0,0 +1,68 @@
 <?php
 namespace Anikeen\Id\Resources;
 /**
 * The preferences of a user in one namespace, sorted by key (at most 50, no pagination).
 */
 class Preferences extends BaseCollection
 {
    /**
     * The preference of a key; null when it isn't set. Reads the list, no request.
     */
    public function find(string $id): ?Preference
    {
        $data = $this->item($id);
        if ($data === null) {
            return null;
        }
        $result = clone $this->result;
        $result->data = $data;
        return new Preference(fn () => $result);
    }
    /**
     * The value of a key, or $default when it isn't set.
     */
    public function get(string $key, mixed $default = null): mixed
    {
        $data = $this->item($key);
        return $data !== null ? $data->value : $default;
    }
    public function has(string $key): bool
    {
        return $this->item($key) !== null;
    }
    /**
     * The values by key.
     *
     * @return array<string, mixed>
     */
    public function values(): array
    {
        $values = [];
        foreach ((array) $this->result->data as $data) {
            $values[$data->key] = $data->value;
        }
        return $values;
    }
    private function item(string $key): ?object
    {
        foreach ((array) $this->result->data as $data) {
            if (($data->key ?? null) === $key) {
                return $data;
            }
        }
        return null;
    }
 }
@@ -5,36 +5,40 @@ namespace Anikeen\Id\Support;
 use Anikeen\Id\AnikeenId;
 use Anikeen\Id\Contracts\AppTokenRepository;
 use Anikeen\Id\Exceptions\ApiException;
 use Anikeen\Id\Exceptions\PreconditionFailedException;
 use Anikeen\Id\Result;
 use GuzzleHttp\Exception\GuzzleException;
 use Throwable;
 /**
 * Sends a request with the app's own token (client credentials). A rejected token is renewed
- * once; every failure ends in an ApiException with status and error code.
+ * once; every failure ends in an ApiException with status and error code (a 412 in a
 * PreconditionFailedException).
 */
 final class AppRequest
 {
    /**
     * @param array<string, string> $headers Extra request headers, e.g. `If-Match`.
     * @throws ApiException
     */
-    public static function send(string $method, string $path, ?array $payload = null, array $query = []): Result
+    public static function send(string $method, string $path, ?array $payload = null, array $query = [], array $headers = []): Result
    {
-        $result = self::attempt($method, $path, $payload, $query);
+        $result = self::attempt($method, $path, $payload, $query, $headers);
        if ($result->status === 401) {
            $tokens = app(AppTokenRepository::class);
            if (method_exists($tokens, 'forgetAccessToken')) {
                $tokens->forgetAccessToken();
-                $result = self::attempt($method, $path, $payload, $query);
+                $result = self::attempt($method, $path, $payload, $query, $headers);
            }
        }
        if (!$result->success()) {
            $body = is_object($result->data) ? $result->data : null;
            $exception = $result->status === 412 ? PreconditionFailedException::class : ApiException::class;
-            throw new ApiException(
+            throw new $exception(
                sprintf('Anikeen ID request %s %s failed: %s', $method, $path, $body->message ?? $result->error()),
                $result->response()?->getStatusCode() ?? 0,
                $body->error ?? null,
@@ -48,10 +52,10 @@ final class AppRequest
    /**
     * @throws ApiException
     */
-    private static function attempt(string $method, string $path, ?array $payload, array $query): Result
+    private static function attempt(string $method, string $path, ?array $payload, array $query, array $headers = []): Result
    {
        try {
-            return app(AnikeenId::class)->asApp()->request($method, $path, $payload, $query);
+            return app(AnikeenId::class)->asApp()->request($method, $path, $payload, $query, null, false, $headers);
        } catch (ApiException $e) {
            throw $e;
        } catch (GuzzleException|Throwable $e) {
@@ -0,0 +1,42 @@
 <?php
 namespace Anikeen\Id\Support;
 use InvalidArgumentException;
 /**
 * @internal paths and preconditions of the preferences API
 */
 final class PreferenceRequest
 {
    /**
     * The path with every segment URL-encoded, e.g. path('v1/preferences', 'global', 'appearance').
     */
    public static function path(string $base, string ...$segments): string
    {
        return $base . '/' . implode('/', array_map('rawurlencode', $segments));
    }
    /**
     * `If-Match: "<version>"` (only if the stored version is this one) or `If-None-Match: *`
     * (only if the key isn't set yet).
     *
     * @return array<string, string>
     */
    public static function conditions(?int $ifVersion, bool $createOnly = false): array
    {
        if ($ifVersion !== null && $createOnly) {
            throw new InvalidArgumentException('A write is either conditional on a version or create-only, not both.');
        }
        return match (true) {
            $ifVersion !== null => ['If-Match' => sprintf('"%d"', $ifVersion)],
            $createOnly => ['If-None-Match' => '*'],
            default => [],
        };
    }
    private function __construct()
    {
    }
 }
@@ -13,6 +13,12 @@ final class EventType
    public const ORDER_PAYMENT_FAILED = 'order.payment_failed';
    public const ORDER_CANCELLED = 'order.cancelled';
    public const ORDER_SHIPPED = 'order.shipped';
    /**
     * Money was given back for an order (a refund or a partial cancellation, with a credit note);
     * see the order's `refunds` and `refunded_total`. A full refund also cancels the order,
     * so order.cancelled is sent too; don't rely on the order of the two events.
     */
    public const ORDER_REFUNDED = 'order.refunded';
    public const SUBSCRIPTION_CREATED = 'subscription.created';
    public const SUBSCRIPTION_ACTIVATED = 'subscription.activated';
@@ -55,6 +61,21 @@ final class EventType
    /** A checkout session was not confirmed within 24 hours; its drafts were cancelled. */
    public const CHECKOUT_EXPIRED = 'checkout.expired';
    /**
     * A user's open monthly bill reached their billing limit: start no new paid service for them.
     * `data.object` is the billing limit as the app reads it (with `version`), `data.reason`
     * `booking` or `limit_changed`. Opt-in: only endpoints that select this event get it (not
     * through `*`), and only apps that may read the limit of a user connected to them.
     */
    public const BILLING_LIMIT_REACHED = 'billing_limit.reached';
    /**
     * A user whose billing limit was reached has room again. `data.object` is the billing limit
     * (with `version`), `data.reason` `limit_changed`, `limit_removed`, `voided`, `period_reset`
     * or `order_changed`. Opt-in like BILLING_LIMIT_REACHED.
     */
    public const BILLING_LIMIT_AVAILABLE = 'billing_limit.available';
    public const TEST = 'webhook.test';
    /**
@@ -0,0 +1,269 @@
 <?php
 namespace Anikeen\Id\Tests;
 use Anikeen\Id\AnikeenId;
 use Anikeen\Id\Exceptions\ApiException;
 use Anikeen\Id\Resources\AppCharge;
 use Anikeen\Id\Resources\BillingLimit;
 use DateTimeImmutable;
 class AppChargesTest extends TestCase
 {
    private function sentCall(int $index): string
    {
        $request = $this->sent[$index]['request'];
        return $request->getMethod() . ' ' . $request->getUri()->getPath() . ' ' . $request->getHeaderLine('Authorization');
    }
    private function charge(array $overrides = []): array
    {
        return ['data' => [
            'object' => 'charge', 'id' => '01JCHARGE', 'user_id' => '01JUSER', 'status' => 'open',
            'idempotency_key' => 'shipment-123', 'name' => 'Signed card', 'description' => null,
            'type' => 'physical', 'quantity' => 2, 'unit' => 'piece', 'unit_price' => '4.000000',
            'net_amount' => '8.00', 'gross_amount' => '9.52', 'currency_iso' => 'EUR', 'group' => null,
            'occurred_at' => '2026-11-06T10:00:00+00:00', 'reference' => 'order-77', 'metadata' => ['parcel' => 'p-1'],
            'order_id' => '01JORDER', 'voided_at' => null, 'void_reason' => null, 'created_at' => '2026-11-06T10:00:01+00:00',
            ...$overrides,
        ]];
    }
    private function limit(array $overrides = []): array
    {
        return ['data' => [
            'object' => 'billing_limit', 'user_id' => '01JUSER', 'currency' => 'EUR', 'basis' => 'gross',
            'limit' => '100.00', 'used' => '82.40', 'used_by_app' => '60.00', 'remaining' => '17.60',
            'remaining_net' => '14.78', 'vat_rate' => 19, 'reached' => false,
            'resets_at' => '2026-12-01T02:00:00Z', 'version' => 7,
            ...$overrides,
        ]];
    }
    public function test_a_charge_is_booked_with_the_app_token(): void
    {
        $this->respond(201, $this->charge());
        $attributes = [
            'idempotency_key' => 'shipment-123',
            'name' => 'Signed card',
            'type' => 'physical',
            'quantity' => 2,
            'unit_price' => '4.00',
            'reference' => 'order-77',
            'metadata' => ['parcel' => 'p-1'],
        ];
        $charge = app(AnikeenId::class)->createChargeForUser('01JUSER', $attributes);
        $this->assertSame('POST /api/v1/client/users/01JUSER/charges Bearer app-token', $this->sentCall(0));
        $this->assertSame($attributes, $this->sentJson(0));
        $this->assertInstanceOf(AppCharge::class, $charge);
        $this->assertSame('01JCHARGE', $charge->id());
        $this->assertSame('open', $charge->status());
        $this->assertTrue($charge->isOpen());
        $this->assertFalse($charge->isBilled());
        $this->assertFalse($charge->isVoided());
        $this->assertSame('8.00', $charge->netAmount());
        $this->assertSame('9.52', $charge->grossAmount());
        $this->assertSame('01JORDER', $charge->orderId());
        $this->assertSame(['parcel' => 'p-1'], $charge->metadata());
        $this->assertEquals(new DateTimeImmutable('2026-11-06T10:00:00+00:00'), $charge->occurredAt());
        $this->assertSame(2, $charge->quantity);
        $this->assertSame('order-77', $charge->reference);
        $this->assertNull($charge->voided_at);
        $this->assertSame('Signed card', $charge->jsonSerialize()['name']);
    }
    public function test_empty_metadata_is_an_empty_array(): void
    {
        $this->respond(200, $this->charge(['metadata' => new \stdClass()]));
        $this->assertSame([], app(AnikeenId::class)->findChargeForUser('01JUSER', '01JCHARGE')->metadata());
    }
    public function test_a_charge_is_found_with_the_app_token(): void
    {
        $this->respond(200, $this->charge(['status' => 'billed']));
        $charge = app(AnikeenId::class)->findChargeForUser('01JUSER', '01JCHARGE');
        $this->assertSame('GET /api/v1/client/users/01JUSER/charges/01JCHARGE Bearer app-token', $this->sentCall(0));
        $this->assertTrue($charge->isBilled());
    }
    public function test_a_charge_is_voided_with_and_without_a_reason(): void
    {
        $voided = ['status' => 'voided', 'order_id' => null, 'voided_at' => '2026-11-06T11:00:00+00:00', 'void_reason' => 'Parcel lost'];
        $this->respond(200, $this->charge($voided));
        $this->respond(200, $this->charge($voided));
        $charge = app(AnikeenId::class)->voidChargeForUser('01JUSER', '01JCHARGE', 'Parcel lost');
        app(AnikeenId::class)->voidChargeForUser('01JUSER', '01JCHARGE');
        $this->assertSame('POST /api/v1/client/users/01JUSER/charges/01JCHARGE/void Bearer app-token', $this->sentCall(0));
        $this->assertSame(['reason' => 'Parcel lost'], $this->sentJson(0));
        $this->assertSame('POST /api/v1/client/users/01JUSER/charges/01JCHARGE/void Bearer app-token', $this->sentCall(1));
        $this->assertSame([], $this->sentJson(1));
        $this->assertTrue($charge->isVoided());
        $this->assertNull($charge->orderId());
        $this->assertSame('Parcel lost', $charge->void_reason);
    }
    public function test_path_segments_are_encoded(): void
    {
        $this->respond(200, $this->charge());
        app(AnikeenId::class)->findChargeForUser('01J/USER', '01J CHARGE');
        $this->assertSame('/api/v1/client/users/01J%2FUSER/charges/01J%20CHARGE', $this->sent[0]['request']->getUri()->getPath());
    }
    public function test_a_charge_over_the_billing_limit_carries_the_details(): void
    {
        $this->respond(409, [
            'message' => 'The customer\'s billing limit is reached.', 'error' => 'billing_limit_reached',
            'limit' => '100.00', 'used' => '97.40', 'remaining' => '2.60', 'remaining_net' => '2.18',
            'required' => '4.76', 'currency' => 'EUR', 'resets_at' => '2026-12-01T02:00:00Z',
        ]);
        try {
            app(AnikeenId::class)->createChargeForUser('01JUSER', ['idempotency_key' => 'k', 'name' => 'Card', 'quantity' => 1, 'unit_price' => '4.00']);
            $this->fail('Expected an ApiException.');
        } catch (ApiException $e) {
            $this->assertTrue($e->isBillingLimitReached());
            $this->assertTrue($e->isConflict());
            $this->assertSame(409, $e->status);
            $this->assertSame('2.60', $e->body()->remaining);
            $this->assertSame('4.76', $e->body()->required);
            $this->assertSame('2026-12-01T02:00:00Z', $e->body()->resets_at);
        }
    }
    public function test_other_conflicts_are_not_the_billing_limit(): void
    {
        $this->respond(409, ['message' => 'The charge is more than this app may charge at once.', 'error' => 'charge_exceeds_maximum', 'max_charge_net' => '50.00']);
        try {
            app(AnikeenId::class)->createChargeForUser('01JUSER', ['idempotency_key' => 'k', 'name' => 'Card', 'quantity' => 1, 'unit_price' => '60.00']);
            $this->fail('Expected an ApiException.');
        } catch (ApiException $e) {
            $this->assertFalse($e->isBillingLimitReached());
            $this->assertSame('charge_exceeds_maximum', $e->error);
            $this->assertSame('50.00', $e->body()->max_charge_net);
        }
    }
    public function test_an_already_billed_charge_cannot_be_voided(): void
    {
        $this->respond(409, ['message' => 'The charge is on a closed bill; only a refund of that order credits it.', 'error' => 'charge_already_billed', 'charge_id' => '01JCHARGE']);
        try {
            app(AnikeenId::class)->voidChargeForUser('01JUSER', '01JCHARGE');
            $this->fail('Expected an ApiException.');
        } catch (ApiException $e) {
            $this->assertSame('charge_already_billed', $e->error);
            $this->assertSame('01JCHARGE', $e->body()->charge_id);
        }
    }
    public function test_an_unknown_charge_is_not_found(): void
    {
        $this->respond(404, ['message' => 'Charge not found.', 'error' => 'charge_not_found']);
        try {
            app(AnikeenId::class)->findChargeForUser('01JUSER', '01JOTHER');
            $this->fail('Expected an ApiException.');
        } catch (ApiException $e) {
            $this->assertTrue($e->isNotFound());
            $this->assertSame('charge_not_found', $e->error);
        }
    }
    public function test_the_billing_limit_is_read_with_the_app_token(): void
    {
        $this->respond(200, $this->limit());
        $limit = app(AnikeenId::class)->billingLimitForUser('01JUSER');
        $this->assertSame('GET /api/v1/client/users/01JUSER/billing-limit Bearer app-token', $this->sentCall(0));
        $this->assertInstanceOf(BillingLimit::class, $limit);
        $this->assertTrue($limit->hasLimit());
        $this->assertSame('100.00', $limit->limit());
        $this->assertSame('82.40', $limit->used());
        $this->assertSame('60.00', $limit->usedByApp());
        $this->assertSame('17.60', $limit->remaining());
        $this->assertSame('14.78', $limit->remainingNet());
        $this->assertSame(19.0, $limit->vatRate());
        $this->assertSame('EUR', $limit->currency());
        $this->assertFalse($limit->isReached());
        $this->assertEquals(new DateTimeImmutable('2026-12-01T02:00:00Z'), $limit->resetsAt());
        $this->assertSame(7, $limit->version());
        $this->assertSame('gross', $limit->basis);
    }
    public function test_without_a_limit_the_app_sees_only_its_own_share(): void
    {
        $this->respond(200, $this->limit(['limit' => null, 'used' => null, 'remaining' => null, 'remaining_net' => null, 'vat_rate' => null]));
        $limit = app(AnikeenId::class)->billingLimitForUser('01JUSER');
        $this->assertFalse($limit->hasLimit());
        $this->assertNull($limit->limit());
        $this->assertNull($limit->used());
        $this->assertNull($limit->remaining());
        $this->assertNull($limit->remainingNet());
        $this->assertNull($limit->vatRate());
        $this->assertSame('60.00', $limit->usedByApp());
        $this->assertTrue($limit->allows('100000.00'));
    }
    public function test_allows_compares_with_the_remaining_amount(): void
    {
        $limit = new BillingLimit((object) $this->limit()['data']);
        $this->assertTrue($limit->allows('17.60'));
        $this->assertTrue($limit->allows('17.6'));
        $this->assertTrue($limit->allows('4.76'));
        $this->assertTrue($limit->allows(17.6));
        $this->assertTrue($limit->allows(17));
        $this->assertFalse($limit->allows('17.61'));
        $this->assertFalse($limit->allows('17.600001'));
        $this->assertFalse($limit->allows('100.00'));
        $this->assertFalse($limit->allows(1000));
    }
    public function test_a_reached_or_zero_limit_allows_nothing(): void
    {
        $reached = new BillingLimit((object) $this->limit(['used' => '100.00', 'remaining' => '0.00', 'remaining_net' => '0.00', 'reached' => true])['data']);
        $zero = new BillingLimit((object) $this->limit(['limit' => '0.00', 'used' => '0.00', 'remaining' => '0.00', 'reached' => true])['data']);
        $this->assertTrue($reached->isReached());
        $this->assertFalse($reached->allows('0.01'));
        $this->assertTrue($zero->hasLimit());
        $this->assertFalse($zero->allows('0.01'));
    }
    public function test_the_user_s_own_limit_has_no_app_share(): void
    {
        $limit = new BillingLimit((object) ['object' => 'billing_limit', 'user_id' => '01JUSER', 'currency' => 'EUR', 'basis' => 'gross', 'limit' => null, 'used' => '12.00', 'remaining' => null, 'remaining_net' => null, 'vat_rate' => 19.0, 'reached' => false, 'resets_at' => '2026-12-01T02:00:00Z', 'version' => 0]);
        $this->assertSame('12.00', $limit->used());
        $this->assertNull($limit->usedByApp());
        $this->assertSame(0, $limit->version());
    }
    public function test_a_refused_limit_read_is_an_api_exception(): void
    {
        $this->respond(403, ['message' => 'This app may not read customers\' billing limits.', 'error' => 'billing_limit_not_enabled']);
        try {
            app(AnikeenId::class)->billingLimitForUser('01JUSER');
            $this->fail('Expected an ApiException.');
        } catch (ApiException $e) {
            $this->assertSame(403, $e->status);
            $this->assertSame('billing_limit_not_enabled', $e->error);
            $this->assertFalse($e->isBillingLimitReached());
        }
    }
 }
@@ -19,6 +19,8 @@ class BillableModelTest extends TestCase
                foreach (['addresses', 'countries', 'defaultPaymentMethod', 'invoices', 'orders', 'paymentMethods', 'subscriptions', 'transactions', 'userData'] as $name) {
                    $this->{$name.'Cache'} = 'cached';
                }
                $this->preferencesCache['global'] = 'cached';
            }
        };
        $user->email = 'ada@example.com';
@@ -55,6 +55,36 @@ class EndpointsTest extends TestCase
        $this->assertSame('GET /api/v1/billing Bearer user-token', $this->sentCall(0));
    }
    public function test_billing_overview_carries_the_billing_limit(): void
    {
        $this->respond(200, ['data' => ['current_charges' => 11.9, 'billing_limit' => ['object' => 'billing_limit', 'limit' => '50.00', 'used' => '11.90', 'remaining' => '38.10', 'reached' => false, 'version' => 3]]]);
        $limit = new \Anikeen\Id\Resources\BillingLimit($this->owner()->billingOverview()->billing_limit);
        $this->assertSame('38.10', $limit->remaining());
        $this->assertTrue($limit->allows('38.10'));
        $this->assertNull($limit->usedByApp());
    }
    public function test_charges_and_billing_limits_of_users_use_the_app_token(): void
    {
        $charge = ['data' => ['object' => 'charge', 'id' => '01JCHARGE', 'status' => 'open']];
        $this->respond(201, $charge);
        $this->respond(200, $charge);
        $this->respond(200, $charge);
        $this->respond(200, ['data' => ['object' => 'billing_limit', 'limit' => null]]);
        app(AnikeenId::class)->createChargeForUser('01JUSER', ['idempotency_key' => 'k', 'name' => 'Card', 'quantity' => 1, 'unit_price' => '4.00']);
        app(AnikeenId::class)->findChargeForUser('01JUSER', '01JCHARGE');
        app(AnikeenId::class)->voidChargeForUser('01JUSER', '01JCHARGE');
        app(AnikeenId::class)->billingLimitForUser('01JUSER');
        $this->assertSame('POST /api/v1/client/users/01JUSER/charges Bearer app-token', $this->sentCall(0));
        $this->assertSame('GET /api/v1/client/users/01JUSER/charges/01JCHARGE Bearer app-token', $this->sentCall(1));
        $this->assertSame('POST /api/v1/client/users/01JUSER/charges/01JCHARGE/void Bearer app-token', $this->sentCall(2));
        $this->assertSame('GET /api/v1/client/users/01JUSER/billing-limit Bearer app-token', $this->sentCall(3));
    }
    public function test_invoice_download_url_is_read_not_updated(): void
    {
        $this->respond(200, $this->list([['id' => 'inv1']]));
@@ -283,4 +313,133 @@ class EndpointsTest extends TestCase
        $this->assertSame(['items' => [], 'billing_address' => ['country_iso' => 'DE']], $this->sentJson(0));
    }
    private function preference(string $namespace, string $key, mixed $value, int $version = 7): array
    {
        return ['namespace' => $namespace, 'key' => $key, 'value' => $value, 'version' => $version, 'updated_at' => '2026-11-06T10:00:00.000000Z', 'updated_by' => ['type' => 'app', 'client_id' => 'app-client']];
    }
    private function conditions(int $index): array
    {
        $request = $this->sent[$index]['request'];
        return [$request->getHeaderLine('If-Match'), $request->getHeaderLine('If-None-Match')];
    }
    public function test_global_preferences_of_the_user(): void
    {
        $this->respond(200, ['data' => [$this->preference('global', 'appearance', 'dark')]]);
        $preferences = $this->owner()->globalPreferences();
        $this->assertSame('dark', $preferences->get('appearance'));
        $this->assertSame('GET /api/v1/preferences/global Bearer user-token', $this->sentCall(0));
    }
    public function test_global_preference_with_a_default(): void
    {
        $this->respond(200, ['data' => [$this->preference('global', 'appearance', 'light')]]);
        $owner = $this->owner();
        $this->assertSame('light', $owner->globalPreference('appearance'));
        $this->assertSame('system', $owner->globalPreference('unknown', 'system'));
        $this->assertCount(1, $this->sent);
        $this->assertSame('GET /api/v1/preferences/global Bearer user-token', $this->sentCall(0));
    }
    public function test_set_global_preference(): void
    {
        $this->respond(201, ['data' => $this->preference('global', 'appearance', 'dark', 8)]);
        $this->respond(200, ['data' => $this->preference('global', 'appearance', 'light', 9)]);
        $created = $this->owner()->setGlobalPreference('appearance', 'dark');
        $updated = $this->owner()->setGlobalPreference('appearance', 'light', ifVersion: 8);
        $this->assertTrue($created->wasCreated());
        $this->assertFalse($updated->wasCreated());
        $this->assertSame(9, $updated->version);
        $this->assertSame('PUT /api/v1/preferences/global/appearance Bearer user-token', $this->sentCall(0));
        $this->assertSame(['value' => 'dark'], $this->sentJson(0));
        $this->assertSame(['', ''], $this->conditions(0));
        $this->assertSame(['"8"', ''], $this->conditions(1));
    }
    public function test_delete_global_preference(): void
    {
        $this->respond(204);
        $this->respond(204);
        $this->owner()->deleteGlobalPreference('appearance');
        $this->owner()->deleteGlobalPreference('appearance', ifVersion: 9);
        $this->assertSame('DELETE /api/v1/preferences/global/appearance Bearer user-token', $this->sentCall(0));
        $this->assertSame('', (string) $this->sent[0]['request']->getBody());
        $this->assertSame(['', ''], $this->conditions(0));
        $this->assertSame(['"9"', ''], $this->conditions(1));
    }
    public function test_preferences_by_user_id(): void
    {
        $this->respond(200, ['data' => [$this->preference('acme', 'plan', 'pro'), $this->preference('acme', 'theme', ['accent' => 'blue'])]]);
        $preferences = app(AnikeenId::class)->preferencesByUserId('01JUSER', 'acme');
        $this->assertEquals(['plan' => 'pro', 'theme' => (object) ['accent' => 'blue']], $preferences->values());
        $this->assertSame('blue', $preferences->find('theme')->value->accent);
        $this->assertNull($preferences->find('missing'));
        $this->assertSame('GET /api/v1/client/users/01JUSER/preferences/acme Bearer app-token', $this->sentCall(0));
    }
    public function test_preference_by_user_id(): void
    {
        $this->respond(200, ['data' => $this->preference('acme', 'plan', 'pro')]);
        $preference = app(AnikeenId::class)->preferenceByUserId('01JUSER', 'acme', 'plan');
        $this->assertSame('pro', $preference->value);
        $this->assertSame(7, $preference->version);
        $this->assertSame('GET /api/v1/client/users/01JUSER/preferences/acme/plan Bearer app-token', $this->sentCall(0));
    }
    public function test_set_preference_by_user_id(): void
    {
        $this->respond(200, ['data' => $this->preference('acme', 'plan', 'pro')]);
        $this->respond(200, ['data' => $this->preference('acme', 'plan', 'pro')]);
        $this->respond(201, ['data' => $this->preference('acme', 'plan', 'pro')]);
        $anikeenId = app(AnikeenId::class);
        $anikeenId->setPreferenceByUserId('01JUSER', 'acme', 'plan', 'pro');
        $anikeenId->setPreferenceByUserId('01JUSER', 'acme', 'plan', 'pro', ifVersion: 7);
        $anikeenId->setPreferenceByUserId('01JUSER', 'acme', 'plan', 'pro', createOnly: true);
        $this->assertSame('PUT /api/v1/client/users/01JUSER/preferences/acme/plan Bearer app-token', $this->sentCall(0));
        $this->assertSame(['value' => 'pro'], $this->sentJson(0));
        $this->assertSame(['', ''], $this->conditions(0));
        $this->assertSame(['"7"', ''], $this->conditions(1));
        $this->assertSame(['', '*'], $this->conditions(2));
    }
    public function test_delete_preference_by_user_id(): void
    {
        $this->respond(204);
        $this->respond(204);
        app(AnikeenId::class)->deletePreferenceByUserId('01JUSER', 'acme', 'plan');
        app(AnikeenId::class)->deletePreferenceByUserId('01JUSER', 'acme', 'plan', ifVersion: 7);
        $this->assertSame('DELETE /api/v1/client/users/01JUSER/preferences/acme/plan Bearer app-token', $this->sentCall(0));
        $this->assertSame(['', ''], $this->conditions(0));
        $this->assertSame(['"7"', ''], $this->conditions(1));
    }
    public function test_find_user_id_by_preference(): void
    {
        $this->respond(200, ['data' => ['user_id' => '01JUSER', 'namespace' => 'acme', 'key' => 'customer_id', 'version' => 7, 'updated_at' => '2026-11-06T10:00:00.000000Z']]);
        $this->assertSame('01JUSER', app(AnikeenId::class)->findUserIdByPreference('acme', 'customer_id', 'cus_123'));
        $this->assertSame('POST /api/v1/client/preferences/acme/lookup Bearer app-token', $this->sentCall(0));
        $this->assertSame(['key' => 'customer_id', 'value' => 'cus_123'], $this->sentJson(0));
        $this->assertSame('', $this->sent[0]['request']->getUri()->getQuery());
    }
 }
@@ -0,0 +1,226 @@
 <?php
 namespace Anikeen\Id\Tests;
 use Anikeen\Id\AnikeenId;
 use Anikeen\Id\Billable;
 use Anikeen\Id\Enums\Appearance;
 use Anikeen\Id\Enums\SharedPreference;
 use Anikeen\Id\Exceptions\ApiException;
 use Anikeen\Id\Exceptions\PreconditionFailedException;
 use Illuminate\Database\Eloquent\Model;
 use InvalidArgumentException;
 class PreferencesTest extends TestCase
 {
    private function owner(): Model
    {
        $owner = new class extends Model {
            use Billable;
            protected $guarded = [];
        };
        $owner->anikeen_id = '01JUSER';
        $owner->anikeen_id_access_token = 'user-token';
        return $owner;
    }
    private function preference(string $key, mixed $value, int $version = 7): array
    {
        return ['data' => ['namespace' => 'global', 'key' => $key, 'value' => $value, 'version' => $version, 'updated_at' => '2026-11-06T10:00:00.000000Z', 'updated_by' => ['type' => 'user', 'client_id' => 'app-client']]];
    }
    private function path(int $index): string
    {
        return $this->sent[$index]['request']->getUri()->getPath();
    }
    public function test_the_lookup_returns_null_when_nobody_holds_the_value(): void
    {
        $this->respond(404, ['message' => 'The preference is not set.', 'error' => 'preference_not_found']);
        $this->assertNull(app(AnikeenId::class)->findUserIdByPreference('acme', 'customer_id', 'cus_123'));
    }
    public function test_the_lookup_throws_on_other_not_found_answers(): void
    {
        $this->respond(404, ['message' => 'The namespace does not exist.', 'error' => 'namespace_not_found']);
        try {
            app(AnikeenId::class)->findUserIdByPreference('acme', 'customer_id', 'cus_123');
            $this->fail('no exception');
        } catch (ApiException $e) {
            $this->assertSame(404, $e->status);
            $this->assertSame('namespace_not_found', $e->error);
        }
    }
    public function test_the_lookup_throws_on_a_404_without_an_error_code(): void
    {
        $this->respond(404, ['message' => 'Not Found']);
        $this->expectException(ApiException::class);
        app(AnikeenId::class)->findUserIdByPreference('acme', 'customer_id', 'cus_123');
    }
    public function test_the_lookup_throws_on_validation_errors(): void
    {
        $this->respond(422, ['message' => 'The key is not unique.', 'error' => 'key_not_unique']);
        try {
            app(AnikeenId::class)->findUserIdByPreference('acme', 'plan', 'pro');
            $this->fail('no exception');
        } catch (ApiException $e) {
            $this->assertSame('key_not_unique', $e->error);
        }
    }
    public function test_a_failed_app_write_carries_the_current_version(): void
    {
        $this->respond(412, ['message' => 'The preference has another version.', 'error' => 'preference_version_mismatch', 'current_version' => 12]);
        try {
            app(AnikeenId::class)->setPreferenceByUserId('01JUSER', 'acme', 'plan', 'pro', ifVersion: 7);
            $this->fail('no exception');
        } catch (PreconditionFailedException $e) {
            $this->assertSame(412, $e->status);
            $this->assertSame('preference_version_mismatch', $e->error);
            $this->assertSame(12, $e->currentVersion());
        }
    }
    public function test_a_create_only_write_of_a_set_key_fails(): void
    {
        $this->respond(412, ['message' => 'The preference is already set.', 'error' => 'preference_exists', 'current_version' => 3]);
        try {
            app(AnikeenId::class)->setPreferenceByUserId('01JUSER', 'acme', 'plan', 'pro', createOnly: true);
            $this->fail('no exception');
        } catch (PreconditionFailedException $e) {
            $this->assertSame('preference_exists', $e->error);
            $this->assertSame(3, $e->currentVersion());
        }
    }
    public function test_a_failed_user_write_carries_the_current_version(): void
    {
        $this->respond(412, ['message' => 'The preference has another version.', 'error' => 'preference_version_mismatch', 'current_version' => null]);
        $this->respond(412, ['message' => 'The preference has another version.', 'error' => 'preference_version_mismatch', 'current_version' => 5]);
        foreach ([
            fn () => $this->owner()->setGlobalPreference('appearance', 'dark', ifVersion: 4),
            fn () => $this->owner()->deleteGlobalPreference('appearance', ifVersion: 4),
        ] as $i => $call) {
            try {
                $call();
                $this->fail('no exception');
            } catch (PreconditionFailedException $e) {
                $this->assertSame([null, 5][$i], $e->currentVersion());
            }
        }
    }
    public function test_a_write_is_either_conditional_or_create_only(): void
    {
        $this->expectException(InvalidArgumentException::class);
        try {
            app(AnikeenId::class)->setPreferenceByUserId('01JUSER', 'acme', 'plan', 'pro', ifVersion: 7, createOnly: true);
        } finally {
            $this->assertCount(0, $this->sent);
        }
    }
    public function test_writes_clear_the_cached_preferences(): void
    {
        $owner = $this->owner();
        $this->respond(200, ['data' => [$this->preference('appearance', 'light')['data']]]);
        $this->respond(200, $this->preference('appearance', 'dark', 8));
        $this->respond(200, ['data' => [$this->preference('appearance', 'dark', 8)['data']]]);
        $this->respond(204);
        $this->respond(200, ['data' => []]);
        $this->assertSame('light', $owner->globalPreference(SharedPreference::APPEARANCE));
        $this->assertSame('light', $owner->globalPreference(SharedPreference::APPEARANCE)); // cached
        $owner->setGlobalPreference(SharedPreference::APPEARANCE, Appearance::DARK);
        $this->assertSame('dark', $owner->globalPreference(SharedPreference::APPEARANCE));
        $owner->deleteGlobalPreference(SharedPreference::APPEARANCE);
        $this->assertSame(Appearance::SYSTEM, $owner->globalPreference(SharedPreference::APPEARANCE, Appearance::SYSTEM));
        $this->assertCount(5, $this->sent);
        $this->assertSame(['GET', 'PUT', 'GET', 'DELETE', 'GET'], array_map(fn ($sent) => $sent['request']->getMethod(), $this->sent));
    }
    public function test_a_failed_write_clears_the_cached_preferences_too(): void
    {
        $owner = $this->owner();
        $this->respond(200, ['data' => [$this->preference('appearance', 'light')['data']]]);
        $this->respond(412, ['message' => 'x', 'error' => 'preference_version_mismatch', 'current_version' => 9]);
        $this->respond(200, ['data' => [$this->preference('appearance', 'dark', 9)['data']]]);
        $owner->globalPreferences();
        try {
            $owner->setGlobalPreference('appearance', 'dark', ifVersion: 7);
        } catch (PreconditionFailedException) {
        }
        $this->assertSame('dark', $owner->globalPreference('appearance'));
        $this->assertCount(3, $this->sent);
    }
    public function test_path_segments_are_encoded(): void
    {
        $this->respond(200, ['data' => []]);
        $this->respond(204);
        $this->respond(200, ['data' => ['user_id' => '01JUSER']]);
        $anikeenId = app(AnikeenId::class);
        $anikeenId->preferencesByUserId('a/b', 'x y');
        $anikeenId->deletePreferenceByUserId('01JUSER', 'acme', '../key?');
        $anikeenId->findUserIdByPreference('ac/me', 'k', 'v');
        $this->assertSame('/api/v1/client/users/a%2Fb/preferences/x%20y', $this->path(0));
        $this->assertSame('/api/v1/client/users/01JUSER/preferences/acme/..%2Fkey%3F', $this->path(1));
        $this->assertSame('/api/v1/client/preferences/ac%2Fme/lookup', $this->path(2));
    }
    public function test_values_round_trip_as_json(): void
    {
        $this->respond(201, $this->preference('settings', (object) []));
        $preference = app(AnikeenId::class)->setPreferenceByUserId('01JUSER', 'acme', 'settings', (object) []);
        $this->assertSame('{"value":{}}', (string) $this->sent[0]['request']->getBody());
        $this->assertEquals((object) [], $preference->value);
    }
    public function test_a_deleted_user_is_not_found(): void
    {
        $this->respond(404, ['message' => 'The user does not exist.', 'error' => 'user_not_found']);
        try {
            app(AnikeenId::class)->preferenceByUserId('01JGONE', 'acme', 'plan');
            $this->fail('no exception');
        } catch (ApiException $e) {
            $this->assertTrue($e->isNotFound());
            $this->assertSame('user_not_found', $e->error);
        }
    }
    public function test_an_unreachable_service_is_temporary(): void
    {
        $this->http->append(new \GuzzleHttp\Exception\ConnectException('down', new \GuzzleHttp\Psr7\Request('DELETE', 'x')));
        try {
            $this->owner()->deleteGlobalPreference('appearance');
            $this->fail('no exception');
        } catch (ApiException $e) {
            $this->assertTrue($e->isTemporary());
        }
    }
 }
@@ -0,0 +1,113 @@
 <?php
 namespace Anikeen\Id\Tests;
 use Anikeen\Id\AnikeenId;
 use Anikeen\Id\Exceptions\ApiException;
 use Anikeen\Id\Exceptions\CollectionException;
 use Anikeen\Id\Exceptions\PreconditionFailedException;
 use Anikeen\Id\Resources\SshKeys;
 use Anikeen\Id\Support\AppRequest;
 class RequestHeadersTest extends TestCase
 {
    public function test_requests_without_extra_headers_send_the_same_headers_as_before(): void
    {
        $this->respond(200, ['data' => []]);
        AppRequest::send('GET', 'v1/client/subscriptions', null, ['page' => 1]);
        $request = $this->sent[0]['request'];
        $this->assertSame(['Bearer app-token'], $request->getHeader('Authorization'));
        $this->assertSame(['app-client'], $request->getHeader('Client-ID'));
        $this->assertFalse($request->hasHeader('If-Match'));
        $this->assertFalse($request->hasHeader('If-None-Match'));
        $this->assertSame('page=1', $request->getUri()->getQuery());
    }
    public function test_app_requests_send_extra_headers_also_on_the_retry_with_a_fresh_token(): void
    {
        $this->respond(401, ['message' => 'Unauthenticated.']);
        $this->respond(200, ['data' => []]);
        AppRequest::send('PUT', 'v1/x', ['value' => 1], [], ['If-Match' => '"7"']);
        $this->assertSame('"7"', $this->sent[0]['request']->getHeaderLine('If-Match'));
        $this->assertSame('"7"', $this->sent[1]['request']->getHeaderLine('If-Match'));
        $this->assertSame('Bearer fresh-app-token', $this->sent[1]['request']->getHeaderLine('Authorization'));
    }
    public function test_extra_headers_do_not_replace_the_client_and_token_headers(): void
    {
        $this->respond(200, ['data' => []]);
        app(AnikeenId::class)->withToken('user-token')
            ->put('v1/x', ['value' => 1], [], null, ['If-None-Match' => '*', 'Authorization' => 'Bearer other']);
        $request = $this->sent[0]['request'];
        $this->assertSame('*', $request->getHeaderLine('If-None-Match'));
        $this->assertSame('Bearer user-token', $request->getHeaderLine('Authorization'));
    }
    public function test_get_and_delete_helpers_take_headers(): void
    {
        $this->respond(200, ['data' => []]);
        $this->respond(204);
        $anikeenId = app(AnikeenId::class)->withToken('user-token');
        $anikeenId->get('v1/x', [], null, ['If-None-Match' => '"3"']);
        $anikeenId->delete('v1/x', [], [], null, ['If-Match' => '"3"']);
        $this->assertSame('"3"', $this->sent[0]['request']->getHeaderLine('If-None-Match'));
        $this->assertSame('"3"', $this->sent[1]['request']->getHeaderLine('If-Match'));
    }
    public function test_a_412_of_an_app_request_is_a_precondition_failed_exception(): void
    {
        $this->respond(412, ['message' => 'The preference has another version.', 'error' => 'preference_version_mismatch', 'current_version' => 12]);
        try {
            AppRequest::send('PUT', 'v1/x', ['value' => 1], [], ['If-Match' => '"7"']);
            $this->fail('no exception');
        } catch (PreconditionFailedException $e) {
            $this->assertSame(412, $e->status);
            $this->assertSame('preference_version_mismatch', $e->error);
            $this->assertSame(12, $e->currentVersion());
        }
    }
    public function test_a_412_of_a_user_request_is_a_precondition_failed_exception(): void
    {
        $this->respond(412, ['message' => 'The preference is already set.', 'error' => 'preference_exists', 'current_version' => null]);
        $result = app(AnikeenId::class)->withToken('user-token')->put('v1/x', ['value' => 1]);
        $e = ApiException::fromResult($result);
        $this->assertInstanceOf(PreconditionFailedException::class, $e);
        $this->assertSame('preference_exists', $e->error);
        $this->assertNull($e->currentVersion());
    }
    public function test_list_errors_keep_their_collection_exception_type(): void
    {
        $this->respond(412, ['message' => 'x', 'error' => 'x']);
        $this->expectException(CollectionException::class);
        $anikeenId = app(AnikeenId::class)->withToken('user-token');
        SshKeys::builder(fn () => $anikeenId->get('v1/ssh-keys'));
    }
    public function test_other_errors_stay_plain_api_exceptions(): void
    {
        $this->respond(409, ['message' => 'Taken.', 'error' => 'preference_value_taken']);
        try {
            AppRequest::send('PUT', 'v1/x', ['value' => 1]);
            $this->fail('no exception');
        } catch (ApiException $e) {
            $this->assertSame(ApiException::class, $e::class);
            $this->assertTrue($e->isConflict());
        }
    }
 }
@@ -25,6 +25,13 @@ class ScopeTest extends TestCase
        $this->assertSame($expected, $constant);
    }
    public function test_the_preference_scopes_match_anikeen_id(): void
    {
        $this->assertSame('preferences', Scope::PREFERENCES);
        $this->assertSame('preferences:read', Scope::PREFERENCES_READ);
        $this->assertSame('preferences:client', Scope::PREFERENCES_CLIENT);
    }
    public function test_there_is_no_full_products_scope_the_console_would_not_accept(): void
    {
        // the Console's product APIs accept `user`, `user:read` and `products:read` only
@@ -0,0 +1,16 @@
 <?php
 namespace Anikeen\Id\Tests;
 use Anikeen\Id\Enums\Appearance;
 use Anikeen\Id\Enums\SharedPreference;
 class SharedPreferenceTest extends TestCase
 {
    public function test_the_shared_keys_and_values_match_anikeen_id(): void
    {
        $this->assertSame('global', SharedPreference::NAMESPACE);
        $this->assertSame('appearance', SharedPreference::APPEARANCE);
        $this->assertSame(['system', 'light', 'dark'], Appearance::all());
    }
 }
@@ -70,6 +70,20 @@ class WebhookTest extends TestCase
        $this->assertContains(EventType::SUBSCRIPTION_RENEWED, EventType::all());
    }
    public function test_refunds_have_their_own_event_type(): void
    {
        $this->assertSame('order.refunded', EventType::ORDER_REFUNDED);
        $this->assertContains(EventType::ORDER_REFUNDED, EventType::all());
    }
    public function test_billing_limit_events_have_their_own_types(): void
    {
        $this->assertSame('billing_limit.reached', EventType::BILLING_LIMIT_REACHED);
        $this->assertSame('billing_limit.available', EventType::BILLING_LIMIT_AVAILABLE);
        $this->assertContains(EventType::BILLING_LIMIT_REACHED, EventType::all());
        $this->assertContains(EventType::BILLING_LIMIT_AVAILABLE, EventType::all());
    }
    public function test_a_change_carries_the_previous_attributes(): void
    {
        $this->payload = json_encode(['id' => '01JEVT', 'type' => EventType::SUBSCRIPTION_UPDATED, 'created' => time(), 'data' => [
Author	SHA1	Message	Date
envoyr	3d7ce65f61	Merge pull request #24 from anikeen-com/feature/app-charges Add charges and the billing limit for trusted apps	2026-11-06 21:25:38 +00:00
envoyr	b35c066b48	Merge pull request #23 from anikeen-com/feature/preferences Add the preferences API	2026-11-06 21:25:11 +00:00
envoyr	be91df6d18	Restore CRLF line endings in ManagesBalance	2026-11-06 20:03:12 +00:00
envoyr	3a78359f59	Add charges and the billing limit to the changelog	2026-11-06 20:01:15 +00:00
envoyr	32103f6921	Document charges and the billing limit	2026-11-06 20:01:15 +00:00
envoyr	7bd7249730	Add charges and the billing limit for trusted apps	2026-11-06 20:00:26 +00:00
envoyr	f5d48b7e35	Add the billing limit event types	2026-11-06 20:00:26 +00:00
envoyr	5a46add518	Drop event ordering claim for full refunds	2026-11-06 19:31:19 +00:00
envoyr	f5d63df9d2	Add preferences to the changelog	2026-11-06 19:29:21 +00:00
envoyr	eebfe557b1	Document preferences, their scopes and order.refunded	2026-11-06 19:29:20 +00:00
envoyr	802f52ce93	Add the preferences API for apps and users	2026-11-06 19:28:23 +00:00
envoyr	90dac3a5a6	Add the order.refunded event type	2026-11-06 19:26:15 +00:00
envoyr	1b64d2822f	Add the shared preference keys and appearance values	2026-11-06 19:26:15 +00:00
envoyr	11ff83e40d	Add the preference scopes	2026-11-06 19:26:15 +00:00
envoyr	d76095cc94	Send extra request headers and throw PreconditionFailedException on 412	2026-11-06 19:25:51 +00:00