Registration & invitations

'registration' => [
    'mode' => env('AUTHENTICATION_REGISTRATION', 'closed'),  // open|invite_only|closed
    'require_password' => true,          // when login.password is on
    'login_after' => true,
    'rules' => null,                     // class-string<ProvidesRegistrationRules>|null
    'creator' => CreateAccount::class,   // class-string<CreatesAccounts>
],

'invitations' => [
    'enabled' => false,
    'ttl' => 604_800,                    // 7 days
    'lock_email' => true,
    'replace_pending' => true,
    'allow_existing_email' => false,
    'resend_cooldown' => 60,
    'max_sends' => 5,
    'preview_payload_keys' => [],        // payload keys exposed by the preview endpoint
    'ability' => 'authentication.invitations.manage',  // Gate ability for management routes
],

use RoundlyConsulting\Auth\DataTransferObjects\RegistrationData;
use RoundlyConsulting\Auth\Enums\RegistrationStatus;
use RoundlyConsulting\Auth\Facades\Authentication;
use RoundlyConsulting\Auth\Http\Responses\LoginResponse;

$guard  = Authentication::guard('users');
$result = $guard->register(new RegistrationData(
    email: $request->input('email'),
    password: $request->input('password'),
    context: $guard->contextFrom($request),
    attributes: $request->input('attributes', []),
));

if ($result->status === RegistrationStatus::Authenticated) {
    return LoginResponse::make($result->login, $request);   // tokens, or a challenge
}

// VerificationRequired or Accepted — answer 202, identical for new and taken addresses

use RoundlyConsulting\Auth\Contracts\ProvidesRegistrationRules;
use RoundlyConsulting\Auth\Guards\GuardConfig;

// config: 'guards' => ['users' => ['registration' => ['rules' => ProfileRules::class]]]

final class ProfileRules implements ProvidesRegistrationRules
{
    public function rules(GuardConfig $guard): array
    {
        return ['name' => ['required', 'string', 'max:100']];
    }
}

use RoundlyConsulting\Auth\DataTransferObjects\AcceptInvitationData;
use RoundlyConsulting\Auth\DataTransferObjects\InvitationData;
use RoundlyConsulting\Auth\Facades\Authentication;

$guard       = Authentication::guard('users');
$invitations = $guard->invitations();

// Invite — payload is your own role/meta JSON, surfaced on acceptance
$link = $invitations->create(new InvitationData(
    email: '[email protected]',
    payload: ['role' => 'editor'],
    invitedBy: $admin,
    locale: 'sk',
));
$link->invitation;   // the Invitation model
$link->url;          // the plaintext link, returned once — mailed to the invitee unless send: false

// Accept — creates a verified account and logs it in, like register()
$result = $invitations->accept(new AcceptInvitationData(
    token: $request->input('token'),
    password: $request->input('password'),
    context: $guard->contextFrom($request),
));   // RegistrationResult — ->login holds the tokens or a challenge

use RoundlyConsulting\Auth\DataTransferObjects\InvitationData;
use RoundlyConsulting\Auth\Enums\InvitationStatus;
use RoundlyConsulting\Auth\Events\InvitationAccepted;
use RoundlyConsulting\Auth\Facades\Authentication;

$invitations = Authentication::guard('users')->invitations();

$invitations->paginate(InvitationStatus::Pending, 20);   // newest first
$invitations->find($id);                                 // ?Invitation of this guard
$invitations->resend($invitation);                       // InvitationLink — mails a fresh link; the previous one dies
$invitations->link($invitation);                         // a fresh copyable link, nothing mailed or counted
$invitations->revoke($invitation);                       // idempotent

// Create without mailing — deliver $link->url yourself (no send is counted)
$link = $invitations->create(new InvitationData('[email protected]', send: false));

Invitation::query()->where('guard', 'users')->withStatus(InvitationStatus::Pending)->get();

Event::listen(fn (InvitationAccepted $e) => $e->account->assignRole($e->invitation->payloadValue('role')));