Module login_events 

Structured channel-login lifecycle events.

QR-pairing channels (WeChat, WhatsApp Web) historically surfaced login artifacts — QR payloads, pair codes, connection state — only as terminal output. Headless deployments (gateway-managed daemons, web dashboards) cannot capture stdout, so operators had no way to complete pairing remotely.

LoginEvent::emit publishes the same lifecycle as structured record! events. Each event carries an attributes.login object with a stable machine-readable shape, so gateway SSE (/api/events) consumers can render the QR code client-side and track connection state:

{
  "event": { "category": "channel", "action": "note" },
  "attributes": {
    "login": {
      "state": "qr",
      "channel": "wechat.assistant",
      "channel_type": "wechat",
      "channel_alias": "assistant",
      "qr_payload": "https://…",
      "attempt": 1,
      "max_attempts": 3
    }
  }
}

state transitions: qr / pair_code → (scanned) → connected, with expired on QR refresh, failed when the flow gives up, and logged_out when a previously linked session is revoked remotely.

Credential handling

QR payloads and pair codes are short-lived device-linking credentials. They ride as ephemeral attributes (Event::with_ephemeral_attrs): the live broadcast copy — the bearer-authenticated SSE /api/events stream, shown above — carries them so a dashboard can render the QR, but they are never serialized into the persisted JSONL trace, so /api/logs, log rotation/retention, and any log shipping or backup never capture them at rest. Persisted events keep only the lifecycle state, channel identity, and attempt counters.

Enums

LoginEvent

A point on the channel-login lifecycle. Construct the variant that matches the flow state and call LoginEvent::emit.