API resources and validation

use RoundlyConsulting\Lifecycle\Http\Resources\LifecycleResource;
use RoundlyConsulting\Lifecycle\Http\Resources\TransitionRecordResource;

// One response feeds the buttons: state, freeze, expiry and every transition with its reasons
return LifecycleResource::make(Lifecycles::for($listing)->by($request->user()));

// A list: a model stands for its primary lifecycle, with the actor from auth
return LifecycleResource::collection(Listing::query()->withLifecycle()->get());
// Another lifecycle of every model in a list
return LifecycleResource::collectionFor(Order::query()->withLifecycle()->get(), 'payment_status');

// History rows (context and snapshot only on request)
return TransitionRecordResource::collection(Lifecycles::for($listing)->history());
(new TransitionRecordResource($record))->withContext();

{
  "lifecycle": "status",
  "state": "active",
  "state_label": "Active",
  "terminal": false,
  "entered_at": "2026-10-02T08:00:00+00:00",
  "version": 2,
  "frozen": {"until": "2026-10-05T08:00:00+00:00", "reason": "maintenance"},
  "expiry": {"expires_at": "2026-11-01T08:00:00+00:00", "due_at": "2026-11-04T08:00:00+00:00", "in_grace": false},
  "allowed_transitions": [
    {
      "name": "close", "label": "Close", "to": "closed", "to_label": "Closed", "allowed": false,
      "denials": [{"code": "frozen", "message": "This record is frozen.", "params": {"transition": "Close", "state": "Active"}, "retry_after": null, "errors": []}],
      "requires_reason": false, "payload_fields": [], "available_at": null
    }
  ],
  "last_transition": {
    "id": 2, "kind": "transition", "transition": "publish", "from": "draft", "to": "active",
    "actor": {"type": "App\\Models\\User", "id": 1}, "system": false, "reason": "ready",
    "occurred_at": "2026-10-02T08:00:00+00:00", "reverted": false
  }
}

use RoundlyConsulting\Lifecycle\Rules\ValidState;
use RoundlyConsulting\Lifecycle\Rules\ValidTransition;

$request->validate([
    'transition' => ['required', ValidTransition::for($listing)->by($request->user())],
    'target' => ['required', ValidTransition::for($listing, 'status')->by($request->user())->toState()],
    'status' => ['nullable', ValidState::of(Listing::class)],                 // the model's first lifecycle
    'payment' => ['nullable', ValidState::of(new Order, 'payment_status')],
    'filter' => ['nullable', ValidState::of(ListingLifecycle::class)],       // a definition class
]);

use RoundlyConsulting\Lifecycle\Exceptions\TransitionDeniedException;

// A refusal as a 422, with payload errors under their own keys ($request is a FormRequest)
try {
    Lifecycles::for($listing)->by($request->user())->with($request->validated())->apply('reopen');
} catch (TransitionDeniedException $e) {
    throw $e->toValidationException();
}