Domain events

Motivation

The host needs to react to invite lifecycle transitions — grant perks, send a welcome email, update
its own projections — without the engine knowing anything about the host. Domain events are the seam:
the engine fires, the host listens. The community’s #1 gap in competing packages is no events; this
package fires one on every meaningful transition.

The events

All three are plain, immutable value objects with constructor‑promoted public readonly properties.

The fire‑once contract

CodeRedeemed carries $already, but the engine only dispatches it on a fresh claim (already
is false at dispatch). Listener side effects — perks, welcome mail, projection updates — therefore
run exactly once per genuine redemption, never on a double‑click or a retried request.

Listening

use Illuminate\Support\Facades\Event;
use Padosoft\Invitations\Events\CodeRedeemed;

Event::listen(function (CodeRedeemed $e) {
    // $e->redemption->redeemer_id, ->code_id, ->tenant_id
    GrantWelcomeBonus::dispatch($e->redemption->redeemer_id);
});

Or a dedicated listener class registered in your EventServiceProvider.

ADR

Worked example — grant a referrer bonus on a qualified referral

Event::listen(function (CodeRedeemed $e) {
    $referral = $e->redemption->referral; // null if un-attributable
    if ($referral !== null) {
        // Qualify later when the referee activates; rewards grant on qualification.
        QueueActivationCheck::dispatch($referral->id);
    }
});