tempest-fastapi-sdk 0.93.0__tar.gz → 0.95.0__tar.gz

{tempest_fastapi_sdk-0.93.0 → tempest_fastapi_sdk-0.95.0}/CHANGELOG.md

@@ -5,6 +5,61 @@ All notable changes to **tempest-fastapi-sdk** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.95.0] — 2026-07-05
+
+### Added
+
+- **PIX key field + helpers** (`tempest_fastapi_sdk.utils`). `PixKeyField`
+  is an `Annotated` schema type that validates any of the five BACEN PIX
+  key types (CPF, CNPJ, e-mail, E.164 phone, random UUID) in one field
+  and normalizes to a canonical form (CPF/CNPJ → digits, e-mail →
+  lowercase, phone → `+55…`, random → lowercase UUID). Companions:
+  `PixKeyType` (the enum), `detect_pix_key_type(value)` (returns the type
+  or `None`), `is_valid_pix_key(value)` and `normalize_pix_key(value)`.
+  Detection is by shape plus CPF/CNPJ check digits — all exported from the
+  package root.
+
+### Changed
+
+- The **validated-fields recipe** was expanded (both locales): a full
+  schema + route + 422 walkthrough, a "compose your own field" section,
+  common gotchas (`CentsField` vs `PriceField`, `PercentField` vs
+  `RatioField`), and the new PIX-key section.
+
+## [0.94.0] — 2026-07-05
+
+### Added
+
+- **Human-friendly cron helpers** (`tempest_fastapi_sdk.tasks`) — schedule
+  periodic tasks without writing cron syntax:
+  - `Cron` — ready-made expressions (`Cron.EVERY_WEEKDAY_9AM`,
+    `Cron.EVERY_5_MINUTES`, …).
+  - `CronOffset` — timezone offsets by place (`CronOffset.BRASILIA` =
+    `-03:00`, plus `FERNANDO_DE_NORONHA` / `MANAUS` / `ACRE` / `UTC`).
+  - `Weekday` — day-of-week tokens.
+  - Builder functions — `daily`, `weekdays`, `weekends`, `hourly`,
+    `every_minute`, `every_n_minutes`, `weekly`, `monthly` — each
+    returning a plain cron string with range validation.
+  - `@tq.cron(...)` / `AsyncTaskScheduler.cron(...)` accept these
+    directly, coercing enum members to their plain string value. The
+    module has no third-party dependency (imports without `[tasks]`).
+- **Class-based message consumers** (`tempest_fastapi_sdk.queue`) — an
+  alternative to the `@mq.on` decorator, in two explicit styles:
+  `Consumer` with a constructor `channel=` + Pydantic `schema=` (no
+  annotation-sniffing) and overridden `handle`, or grouped `@subscribe`
+  methods (one class, many channels). Wire with `MessageBroker.register`.
+- **Class-based background tasks** (`tempest_fastapi_sdk.tasks`) —
+  symmetric to consumers: `TaskDef` with an overridden `run` (name in the
+  constructor) or grouped `@task_method` methods, wired with
+  `TaskQueue.register` (returns a `Task` or a `dict[str, Task]`).
+
+### Changed
+
+- **`AsyncBrokerManager` renamed to `AsyncQueueManager`** — a clearer name
+  for the thin lifecycle wrapper around an injected broker, matching the
+  `Async*Manager` family. `AsyncBrokerManager` stays as a backward-compatible
+  alias. `MessageBroker` remains the recommended batteries-included facade.
+
 ## [0.93.0] — 2026-07-05
 
 ### Added

{tempest_fastapi_sdk-0.93.0 → tempest_fastapi_sdk-0.95.0}/CLAUDE.md

@@ -162,13 +162,23 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
   consumer, channel-first `publish(channel, message)`, `.broker` escape
   hatch) and `TaskQueue` (`.rabbitmq`/`.redis`/`.memory`, `@tq.task` →
   `Task.enqueue`/`.run`, folded `@tq.cron`/`@tq.interval` +
-  `start_scheduler`, `tq.broker`/`tq.scheduler` for the CLIs). Legacy
-  `AsyncBrokerManager`/`AsyncTaskBrokerManager`/`AsyncTaskScheduler` kept
-  as working aliases. Outbox (`BaseOutboxModel`/`OutboxRelay`/
-  `save_with_outbox`) plugs its `publish` into `MessageBroker.publish`.
+  `start_scheduler`, `tq.broker`/`tq.scheduler` for the CLIs). **Both
+  decorator and class-based styles**: `Consumer` + `@subscribe` +
+  `MessageBroker.register` (constructor form takes explicit
+  `channel`+`schema`, no magic); `TaskDef` + `@task_method` +
+  `TaskQueue.register`. **Cron without syntax**: `Cron`/`CronOffset`
+  (`BRASILIA` etc.)/`Weekday` enums + `daily`/`weekdays`/`every_n_minutes`/
+  `weekly`/`monthly`/… builders (dependency-free). `AsyncBrokerManager`
+  renamed to **`AsyncQueueManager`** (v0.94.0; old alias kept); legacy
+  `AsyncTaskBrokerManager`/`AsyncTaskScheduler` kept. Outbox
+  (`BaseOutboxModel`/`OutboxRelay`/`save_with_outbox`) plugs its `publish`
+  into `MessageBroker.publish`.
 - **BR validators** — CPF/CNPJ/CEP/phone, with `*Field` Pydantic types
   (`CPFField`/`CNPJField`/`CPFOrCNPJField`/`PhoneBRField`/`CEPField`;
-  pre-0.76 unsuffixed names kept as deprecated aliases).
+  pre-0.76 unsuffixed names kept as deprecated aliases). **PIX keys**
+  (v0.95.0): `PixKeyField` validates+normalizes any of the 5 BACEN key
+  types (CPF/CNPJ/email/E.164 phone/random UUID); `PixKeyType` +
+  `detect_pix_key_type`/`is_valid_pix_key`/`normalize_pix_key`.
 - **BR localities** — `UF` (StrEnum, 27 siglas) + `Region`
   (5 macro-regiões IBGE), `StateBR`/`CityBR` schemas, offline
   dataset of 27 states + 5606 municipalities (IBGE-derived,

{tempest_fastapi_sdk-0.93.0 → tempest_fastapi_sdk-0.95.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.93.0
+Version: 0.95.0
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
@@ -262,14 +262,14 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.cache` *(extra: `[cache]`)* | `AsyncRedisManager`, `cached` (with `namespace` / `tags`), `CacheInvalidator`, `namespace_registry_key`, `tag_registry_key` |
 | `tempest_fastapi_sdk.flags` | `FeatureFlags`, `FeatureFlagBackend`, `MemoryFeatureFlagBackend`, `EnvFeatureFlagBackend`, `RedisFeatureFlagBackend`, `CompositeFeatureFlagBackend`, `make_flag_dependency`, `coerce_flag` |
 | `tempest_fastapi_sdk.webpush` *(extra: `[webpush]`)* | `WebPushDispatcher`, `WebPushSubscriptionService`, `make_web_push_router`, `WebPushError`, `WebPushGoneError`, `WebPushSubscriptionSchema`, `WebPushKeysSchema`, `WebPushPayloadSchema` |
-| `tempest_fastapi_sdk.queue` *(extra: `[queue]`)* | `MessageBroker` (typed, transport-agnostic FastStream facade — `.rabbitmq`/`.redis`/`.kafka`/`.nats`, `@mq.on(channel)`, channel-first `publish`); `AsyncBrokerManager` (legacy lifecycle wrapper) |
+| `tempest_fastapi_sdk.queue` *(extra: `[queue]`)* | `MessageBroker` (typed, transport-agnostic FastStream facade — `.rabbitmq`/`.redis`/`.kafka`/`.nats`, `@mq.on(channel)`, channel-first `publish`); class-based consumers (`Consumer` + `@subscribe` + `MessageBroker.register`); `AsyncQueueManager` (thin lifecycle wrapper, formerly `AsyncBrokerManager`) |
 | `tempest_fastapi_sdk.storage` *(extra: `[minio]`)* | `AsyncMinIOClient`, `ObjectStat` — async MinIO/S3 facade |
 | `tempest_fastapi_sdk.utils.http_client` *(extra: `[http]`)* | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, `REQUEST_ID_HEADER` — typed httpx wrapper |
 | `tempest_fastapi_sdk.utils.storage_backends` *(extra: `[upload]`)* | `UploadStorage` protocol, `LocalUploadStorage`, `MinIOUploadStorage`, `UploadResult`, `ContentValidator` |
-| `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `TaskQueue` (typed TaskIQ facade — `.rabbitmq`/`.redis`/`.memory`, `@tq.task` → `Task.enqueue`/`.run`, `@tq.cron`/`@tq.interval`, `start_scheduler`), `Task`; `AsyncTaskBrokerManager` / `AsyncTaskScheduler` (legacy wrappers) |
+| `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `TaskQueue` (typed TaskIQ facade — `.rabbitmq`/`.redis`/`.memory`, `@tq.task` → `Task.enqueue`/`.run`, `@tq.cron`/`@tq.interval`, `start_scheduler`), `Task`; class-based tasks (`TaskDef` + `@task_method` + `TaskQueue.register`); cron helpers (`Cron` / `CronOffset` / `Weekday` + `daily`/`weekdays`/`every_n_minutes`/… builders); `AsyncTaskBrokerManager` / `AsyncTaskScheduler` (legacy wrappers) |
 | `tempest_fastapi_sdk.vision` *(extra: `[vision]`)* | `Detector`, `Classifier`, `Segmenter` (ONNX, lazy), `DetectionSchema`/`ClassificationSchema`/`SegmentationSchema`/`BoundingBoxSchema`/`ClassProbabilitySchema`, `to_detection_schemas`/`to_classification_schema`/`to_segmentation_schemas` |
 | `tempest_fastapi_sdk.ssr` *(extra: `[ssr]`)* | `Page` (typed component base), `html_response` (widget tree → `HTMLResponse`, full document or HTMX fragment), `make_htmx_router` (serves bundled HTMX locally, no CDN) |
-| `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `FileStoreUtils` — unified upload+download+presign facade *(extra: `[upload]` local / `[minio]` MinIO)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, validated field types (`PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`, `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`, `RatioField`, `LatitudeField`, `LongitudeField`, `PriceField`, `NonEmptyStrField`, `SlugField`, `HexColorField`), BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField` — old names without the suffix kept as deprecated aliases — `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `ChoiceBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `uf_choices`/`region_choices`/`city_choices`, `is_valid_uf`/`normalize_uf`, `is_valid_city`/`normalize_city`) |
+| `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `FileStoreUtils` — unified upload+download+presign facade *(extra: `[upload]` local / `[minio]` MinIO)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, validated field types (`PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`, `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`, `RatioField`, `LatitudeField`, `LongitudeField`, `PriceField`, `NonEmptyStrField`, `SlugField`, `HexColorField`), BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField`, `PixKeyField` — old names without the suffix kept as deprecated aliases — `PixKeyType`/`detect_pix_key_type`/`is_valid_pix_key`, `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `ChoiceBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `uf_choices`/`region_choices`/`city_choices`, `is_valid_uf`/`normalize_uf`, `is_valid_city`/`normalize_city`) |
 | `tempest_fastapi_sdk.cli` | `tempest` console script — `new <name>` (scaffold layered service), `lint` / `format` / `fmt-check` / `type` / `test` / `check` (run preferred quality gates), `version` / `--version` |
 
 Core primitives are re-exported from `tempest_fastapi_sdk` at the top level — `from tempest_fastapi_sdk import BaseModel, BaseRepository, AppException` always works. The extras-gated managers in `tempest_fastapi_sdk.cache`, `tempest_fastapi_sdk.queue`, `tempest_fastapi_sdk.tasks`, `tempest_fastapi_sdk.vision` and `tempest_fastapi_sdk.ssr` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import MessageBroker`).

{tempest_fastapi_sdk-0.93.0 → tempest_fastapi_sdk-0.95.0}/README.md

@@ -153,14 +153,14 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.cache` *(extra: `[cache]`)* | `AsyncRedisManager`, `cached` (with `namespace` / `tags`), `CacheInvalidator`, `namespace_registry_key`, `tag_registry_key` |
 | `tempest_fastapi_sdk.flags` | `FeatureFlags`, `FeatureFlagBackend`, `MemoryFeatureFlagBackend`, `EnvFeatureFlagBackend`, `RedisFeatureFlagBackend`, `CompositeFeatureFlagBackend`, `make_flag_dependency`, `coerce_flag` |
 | `tempest_fastapi_sdk.webpush` *(extra: `[webpush]`)* | `WebPushDispatcher`, `WebPushSubscriptionService`, `make_web_push_router`, `WebPushError`, `WebPushGoneError`, `WebPushSubscriptionSchema`, `WebPushKeysSchema`, `WebPushPayloadSchema` |
-| `tempest_fastapi_sdk.queue` *(extra: `[queue]`)* | `MessageBroker` (typed, transport-agnostic FastStream facade — `.rabbitmq`/`.redis`/`.kafka`/`.nats`, `@mq.on(channel)`, channel-first `publish`); `AsyncBrokerManager` (legacy lifecycle wrapper) |
+| `tempest_fastapi_sdk.queue` *(extra: `[queue]`)* | `MessageBroker` (typed, transport-agnostic FastStream facade — `.rabbitmq`/`.redis`/`.kafka`/`.nats`, `@mq.on(channel)`, channel-first `publish`); class-based consumers (`Consumer` + `@subscribe` + `MessageBroker.register`); `AsyncQueueManager` (thin lifecycle wrapper, formerly `AsyncBrokerManager`) |
 | `tempest_fastapi_sdk.storage` *(extra: `[minio]`)* | `AsyncMinIOClient`, `ObjectStat` — async MinIO/S3 facade |
 | `tempest_fastapi_sdk.utils.http_client` *(extra: `[http]`)* | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, `REQUEST_ID_HEADER` — typed httpx wrapper |
 | `tempest_fastapi_sdk.utils.storage_backends` *(extra: `[upload]`)* | `UploadStorage` protocol, `LocalUploadStorage`, `MinIOUploadStorage`, `UploadResult`, `ContentValidator` |
-| `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `TaskQueue` (typed TaskIQ facade — `.rabbitmq`/`.redis`/`.memory`, `@tq.task` → `Task.enqueue`/`.run`, `@tq.cron`/`@tq.interval`, `start_scheduler`), `Task`; `AsyncTaskBrokerManager` / `AsyncTaskScheduler` (legacy wrappers) |
+| `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `TaskQueue` (typed TaskIQ facade — `.rabbitmq`/`.redis`/`.memory`, `@tq.task` → `Task.enqueue`/`.run`, `@tq.cron`/`@tq.interval`, `start_scheduler`), `Task`; class-based tasks (`TaskDef` + `@task_method` + `TaskQueue.register`); cron helpers (`Cron` / `CronOffset` / `Weekday` + `daily`/`weekdays`/`every_n_minutes`/… builders); `AsyncTaskBrokerManager` / `AsyncTaskScheduler` (legacy wrappers) |
 | `tempest_fastapi_sdk.vision` *(extra: `[vision]`)* | `Detector`, `Classifier`, `Segmenter` (ONNX, lazy), `DetectionSchema`/`ClassificationSchema`/`SegmentationSchema`/`BoundingBoxSchema`/`ClassProbabilitySchema`, `to_detection_schemas`/`to_classification_schema`/`to_segmentation_schemas` |
 | `tempest_fastapi_sdk.ssr` *(extra: `[ssr]`)* | `Page` (typed component base), `html_response` (widget tree → `HTMLResponse`, full document or HTMX fragment), `make_htmx_router` (serves bundled HTMX locally, no CDN) |
-| `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `FileStoreUtils` — unified upload+download+presign facade *(extra: `[upload]` local / `[minio]` MinIO)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, validated field types (`PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`, `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`, `RatioField`, `LatitudeField`, `LongitudeField`, `PriceField`, `NonEmptyStrField`, `SlugField`, `HexColorField`), BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField` — old names without the suffix kept as deprecated aliases — `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `ChoiceBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `uf_choices`/`region_choices`/`city_choices`, `is_valid_uf`/`normalize_uf`, `is_valid_city`/`normalize_city`) |
+| `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `FileStoreUtils` — unified upload+download+presign facade *(extra: `[upload]` local / `[minio]` MinIO)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, validated field types (`PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`, `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`, `RatioField`, `LatitudeField`, `LongitudeField`, `PriceField`, `NonEmptyStrField`, `SlugField`, `HexColorField`), BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField`, `PixKeyField` — old names without the suffix kept as deprecated aliases — `PixKeyType`/`detect_pix_key_type`/`is_valid_pix_key`, `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `ChoiceBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `uf_choices`/`region_choices`/`city_choices`, `is_valid_uf`/`normalize_uf`, `is_valid_city`/`normalize_city`) |
 | `tempest_fastapi_sdk.cli` | `tempest` console script — `new <name>` (scaffold layered service), `lint` / `format` / `fmt-check` / `type` / `test` / `check` (run preferred quality gates), `version` / `--version` |
 
 Core primitives are re-exported from `tempest_fastapi_sdk` at the top level — `from tempest_fastapi_sdk import BaseModel, BaseRepository, AppException` always works. The extras-gated managers in `tempest_fastapi_sdk.cache`, `tempest_fastapi_sdk.queue`, `tempest_fastapi_sdk.tasks`, `tempest_fastapi_sdk.vision` and `tempest_fastapi_sdk.ssr` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import MessageBroker`).

{tempest_fastapi_sdk-0.93.0 → tempest_fastapi_sdk-0.95.0}/docs/recipes/auth-flow.en.md

@@ -2,12 +2,32 @@
 
 Since v0.31.0 the SDK ships the full local-account lifecycle — email + password signup, link-based activation, JWT-pair login, password reset — via `UserAuthService` + `make_auth_router`. **Endpoints ready to mount** (including `POST /auth/refresh` since v0.65.0), Jinja2 templates bundled, settings flags decide whether the link is emailed or returned in the response body, and four pre-thought modes for dev / staging / production / CI.
 
+!!! tip "Jump straight to your case"
+    The table below maps **what the user wants to do** → the section and
+    endpoints. Start at your case; come back to [setup](#minimum-setup)
+    only when you need to wire the pieces.
+
+    | I want to… | Logged in? | Section | Endpoints |
+    | --- | --- | --- | --- |
+    | Create account + activate by email | — | [Setup](#minimum-setup) | `signup` → `activate/{token}` |
+    | Log in | — | [Endpoints](#endpoints) | `login` |
+    | **I forgot my password** | ❌ no | **[Password recovery](#password-recovery)** | `password-reset/request` → `password-reset/confirm` |
+    | Change my password | ✅ yes | [Change password logged in](#change-your-password-logged-in) | `password-change` |
+    | Change my email | ✅ yes | [Change email](#change-email-logged-in) | `email-change/request` → `email-change/confirm` |
+    | Re-verify my current email | ✅ yes | [Re-verify email](#re-verify-the-current-email) | `email-verify/request` → `email-verify/confirm` |
+    | **I lost access to my email** | ❌ no | **[Email recovery](#email-recovery)** | `email-recovery/request` → `email-change/confirm` |
+    | My session expired | — | [Refresh](#renewing-the-session-with-the-refresh-token) | `refresh` |
+
+    **The two "I forgot"**: lost password → [Password recovery](#password-recovery); lost mailbox → [Email recovery](#email-recovery).
+
 ## Recipe contents
 
 1. **[Minimum setup](#minimum-setup)** — extras install + wiring four objects (`AsyncDatabaseManager`, `EmailUtils`, `UserAuthService`, `make_auth_router`).
 2. **[Concrete UserTokenModel](#concrete-usertokenmodel)** — `BaseUserTokenModel` is abstract, your project owns the concrete table.
-3. **[Endpoints](#endpoints)** — table of the 5 endpoints + payload + behavior.
-4. **[Settings — environment variables](#settings-environment-variables)** — env vars in **six groups** (JWT, password policy, email flow, TTL, URLs/templates, backend pages) — each in a typed table, not one blob.
+3. **[Endpoints](#endpoints)** — table of all endpoints + payload + behavior.
+4. **[Password recovery](#password-recovery)** — the "forgot password" flow, step by step, plus changing the password while logged in.
+5. **[Email change and recovery](#email-change-and-recovery)** — change email logged in, re-verify, and recover when the mailbox is lost.
+6. **[Settings — environment variables](#settings-environment-variables)** — env vars in **groups** (JWT, password policy, email flow, TTL, URLs/templates, backend pages) — each in a typed table, not one blob.
 5. **[Email anatomy: how link, template and URL fit together](#email-anatomy)** — disambiguates the three concepts that confuse readers the most.
 6. **[Five operating modes](#five-operating-modes)** — production, dev with local SMTP (Mailhog / smtp4dev), dev without SMTP, CI without activation, and **backend-only** (links and pages served directly by the backend).
 7. **[Mailhog vs smtp4dev — which to pick for local dev](#mailhog-vs-smtp4dev)** — comparison + copy-paste docker-compose snippets.
@@ -150,43 +170,164 @@ uv run tempest db upgrade
       `current_password`. No email or reset token involved. Returns
       **204** and the current tokens stay valid.
 
-## Email change, verification and recovery (v0.92.0+)
+## Password recovery
 
-Mirrors the password flow, but for the account **email**. Three cases:
+The classic "I forgot my password". The user is **not logged in** and
+proves identity with a **single-use token** delivered by email. Two steps.
 
-- **Change email (logged in)** — like `password-change`: the user is
-  logged in, confirms `current_password` and supplies `new_email`. A
-  confirmation link goes to the **new** address; the email only changes
-  once that link is confirmed. On confirmation a security notice is sent
-  to the **old** address (the banks/Google pattern).
-- **Re-verify the current email** — re-send a verification link to the
-  current address (useful when the activation email was lost).
-- **Recovery (lost mailbox access)** — an **unauthenticated** endpoint,
-  opt-in via `AUTH_EMAIL_RECOVERY_ENABLED`. Proves identity with the
-  password **and a valid MFA code when TOTP is enrolled**, then emails the
-  link to the new address.
+### Base case (SPA / JSON)
 
-```python
-# Change email (logged in) — token comes in the body in dev (mode C)
-resp = await client.post(
-    "/auth/email-change/request",
-    json={"new_email": "new@example.com", "current_password": "current-pass"},
-    headers={"Authorization": f"Bearer {access_token}"},
-)
-confirm_url: str | None = resp.json()["confirm_url"]  # None in prod (goes by email)
+**Step 1 — request the link.** The user types their email; the backend
+always answers **202** with the same generic message (it never leaks
+whether the email exists):
+
+```bash
+curl -X POST localhost:8000/auth/password-reset/request \
+  -H "Content-Type: application/json" \
+  -d '{"email": "ana@example.com"}'
+```
+
+```json
+{ "message": "If the email exists, we sent a link.", "reset_url": null }
+```
+
+**Step 2 — set the new password.** The user opens the emailed link; the
+front-end reads the `token` from the URL and sends it with the new
+password. On success the password is replaced **and the user is logged
+in** (a JWT pair comes back):
+
+```bash
+curl -X POST localhost:8000/auth/password-reset/confirm \
+  -H "Content-Type: application/json" \
+  -d '{"token": "abc123…", "new_password": "new-strong-pass-12"}'
+```
+
+```json
+{
+  "user_id": "7d8e4d5a-…",
+  "access_token": "eyJhbGciOi…",
+  "refresh_token": "eyJhbGciOi…",
+  "mfa_required": false,
+  "mfa_token": null
+}
+```
+
+!!! check "Errors you'll see"
+    - Unknown / already-used / expired token → **400**.
+    - `new_password` violates `AUTH_PASSWORD_MIN_LENGTH` / complexity → **422**.
+    - `request` **never** errors on a missing email — always **202**.
+
+!!! note "Dev mode: link in the body (no SMTP)"
+    Without the `[email]` extra, or with `AUTH_RETURN_TOKEN_IN_RESPONSE=True`,
+    the `reset_url` comes back **in the `request` body** instead of by
+    email — you can drive the whole flow with no inbox. In production it
+    stays `null`.
+
+??? note "No front-end? Backend-rendered HTML pages (Mode E)"
+    With `AUTH_BACKEND_LINKS=True` the SDK mounts **GET/POST**
+    `/auth/password-reset/{token}`: the emailed link points at the
+    backend, which renders an HTML form, validates it and shows a
+    success/error page — no front-end route at all. See
+    [Five operating modes](#five-operating-modes) (Mode E).
+
+### Change your password (logged in)
+
+Different from a reset: here the user **remembers** their password and
+**is logged in**. No token, no email — they send the `access_token` in
+the header and re-confirm their `current_password`:
 
-# ...user opens the link; the front extracts the token and confirms:
-await client.post("/auth/email-change/confirm", json={"token": token})
+```bash
+curl -X POST localhost:8000/auth/password-change \
+  -H "Authorization: Bearer eyJhbGciOi…" \
+  -H "Content-Type: application/json" \
+  -d '{"current_password": "current-pass", "new_password": "new-strong-pass-12"}'
+```
+
+Returns **204**; current tokens stay valid (this endpoint doesn't revoke
+sessions). Wrong `current_password` → **401**.
+
+!!! tip "Reset vs change — which is which?"
+    - **Forgot** the password, not logged in → **[Password recovery](#password-recovery)** (`password-reset/request` → `confirm`, prove with an emailed token).
+    - **Remembers** the password, logged in → **change password** (`password-change`, prove with the current password in the header).
+
+## Email change and recovery
+
+The mirror of the password flow, but for the account **email** (v0.92.0+).
+Three distinct cases — start at yours.
+
+### Change email (logged in)
+
+The base case: the user **is logged in** and wants to change their own
+email. They confirm `current_password` and supply `new_email`; a
+confirmation link goes to the **new** address. The email only changes
+once that link is confirmed.
+
+```bash
+# Step 1 — request the change (authenticated). Always 202.
+curl -X POST localhost:8000/auth/email-change/request \
+  -H "Authorization: Bearer eyJhbGciOi…" \
+  -H "Content-Type: application/json" \
+  -d '{"new_email": "new@example.com", "current_password": "current-pass"}'
+
+# Step 2 — confirm (the front reads the token from the link sent to the new email).
+curl -X POST localhost:8000/auth/email-change/confirm \
+  -H "Content-Type: application/json" \
+  -d '{"token": "abc123…"}'
+```
+
+On confirmation, if `AUTH_EMAIL_CHANGE_NOTIFY_OLD=True` (default) a
+**security notice goes to the old address** — the banks/Google pattern,
+so a hijacked account still alerts its owner.
+
+!!! check "Errors"
+    - Wrong current password → **401**.
+    - `new_email` already in use (at request **or** confirm — a race) → **409**.
+    - Invalid / expired / used token → **400**.
+
+### Re-verify the current email
+
+Re-sends a verification link to the **current address** — useful when the
+activation email was lost. Authenticated, changes nothing; confirming the
+link marks the account active.
+
+```bash
+curl -X POST localhost:8000/auth/email-verify/request \
+  -H "Authorization: Bearer eyJhbGciOi…"
+# then: POST /auth/email-verify/confirm  {"token": "…"}
+```
+
+### Email recovery
+
+The "I forgot / lost access to my email". An **unauthenticated** and
+**opt-in** endpoint — only mounted with `AUTH_EMAIL_RECOVERY_ENABLED=True`.
+The user proves identity with their **password** (and an **MFA code** when
+TOTP is enrolled) and supplies the new address; the confirmation link goes
+to the **new** email and reuses the same `email-change/confirm`.
+
+```bash
+# Only exists if AUTH_EMAIL_RECOVERY_ENABLED=True. Always 202 (anti-enumeration).
+curl -X POST localhost:8000/auth/email-recovery/request \
+  -H "Content-Type: application/json" \
+  -d '{
+        "email": "old@example.com",
+        "new_email": "new@example.com",
+        "current_password": "current-pass",
+        "mfa_code": "123456"
+      }'
+# then: POST /auth/email-change/confirm  {"token": "…"}  (link went to the new email)
 ```
 
 !!! danger "Recovery is sensitive — enable it deliberately"
-    `POST /auth/email-recovery/request` lets whoever has the password move
-    the account to another email **without** accessing the old mailbox. It
-    is only mounted with `AUTH_EMAIL_RECOVERY_ENABLED=True`. It always
-    answers a generic **202** (no account enumeration) and, when TOTP is
-    enrolled, requires a valid `mfa_code`. Keep
-    `AUTH_EMAIL_CHANGE_NOTIFY_OLD=True` so the old address is always
-    alerted.
+    This endpoint lets whoever has the **password** move the account to
+    another email **without** accessing the old mailbox — an account-takeover
+    vector if the password leaked. Rules:
+
+    - **Opt-in**: off until `AUTH_EMAIL_RECOVERY_ENABLED=True`.
+    - Always a generic **202** for every soft failure (unknown email,
+      wrong password, missing/invalid `mfa_code`) — no account enumeration.
+    - When TOTP is enrolled, a valid `mfa_code` is required.
+    - Keep `AUTH_EMAIL_CHANGE_NOTIFY_OLD=True` so the old email is always
+      alerted of the change.
 
 !!! info "Where the new email is stored"
     The pending address travels in the token's `payload` column

{tempest_fastapi_sdk-0.93.0 → tempest_fastapi_sdk-0.95.0}/docs/recipes/auth-flow.md

@@ -2,12 +2,32 @@
 
 Desde v0.31.0 o SDK fornece o ciclo completo de conta local — signup com email/senha, ativação por link, login com JWT pair, reset de senha — via `UserAuthService` + `make_auth_router`. **Endpoints prontos pra mount** (incluindo `POST /auth/refresh` desde v0.65.0), templates Jinja2 bundled, settings flags controlando se o link sai por e-mail ou no body da resposta, e quatro modos pré-pensados pra dev / staging / produção / CI.
 
+!!! tip "Vá direto ao seu caso"
+    A tabela abaixo mapeia **o que o usuário quer fazer** → a seção e os
+    endpoints. Comece pelo seu caso; volte ao [setup](#setup-minimo) só
+    quando precisar ligar as peças.
+
+    | Quero… | Está logado? | Seção | Endpoints |
+    | --- | --- | --- | --- |
+    | Criar conta + ativar por e-mail | — | [Setup](#setup-minimo) | `signup` → `activate/{token}` |
+    | Entrar | — | [Endpoints](#endpoints) | `login` |
+    | **Esqueci minha senha** | ❌ não | **[Recuperação de senha](#recuperacao-de-senha)** | `password-reset/request` → `password-reset/confirm` |
+    | Trocar minha senha | ✅ sim | [Trocar senha logado](#trocar-a-senha-logado) | `password-change` |
+    | Trocar meu e-mail | ✅ sim | [Trocar e-mail](#trocar-e-mail-logado) | `email-change/request` → `email-change/confirm` |
+    | Re-verificar meu e-mail atual | ✅ sim | [Re-verificar e-mail](#re-verificar-o-e-mail-atual) | `email-verify/request` → `email-verify/confirm` |
+    | **Perdi acesso ao meu e-mail** | ❌ não | **[Recuperação de e-mail](#recuperacao-de-e-mail)** | `email-recovery/request` → `email-change/confirm` |
+    | Minha sessão expirou | — | [Refresh](#renovando-a-sessao-com-o-refresh-token) | `refresh` |
+
+    **Os dois "esqueci"**: senha perdida → [Recuperação de senha](#recuperacao-de-senha); caixa de e-mail perdida → [Recuperação de e-mail](#recuperacao-de-e-mail).
+
 ## Conteúdo da receita
 
 1. **[Setup mínimo](#setup-minimo)** — instalação dos extras + wiring de quatro objetos (`AsyncDatabaseManager`, `EmailUtils`, `UserAuthService`, `make_auth_router`).
 2. **[UserTokenModel concreto](#usertokenmodel-concreto)** — `BaseUserTokenModel` é abstrato, projeto cria a tabela final.
-3. **[Endpoints](#endpoints)** — tabela dos 5 endpoints + payload + comportamento.
-4. **[Settings — variáveis de ambiente](#settings-variaveis-de-ambiente)** — env vars em **seis grupos** (JWT, política de senha, fluxo de e-mail, TTL, URLs/templates, páginas backend) — cada uma em tabela tipada, não num blob.
+3. **[Endpoints](#endpoints)** — tabela de todos os endpoints + payload + comportamento.
+4. **[Recuperação de senha](#recuperacao-de-senha)** — o fluxo "esqueci a senha", passo a passo, mais trocar a senha logado.
+5. **[Troca e recuperação de e-mail](#troca-e-recuperacao-de-e-mail)** — trocar e-mail logado, re-verificar, e recuperar quando a caixa se perdeu.
+6. **[Settings — variáveis de ambiente](#settings-variaveis-de-ambiente)** — env vars em **grupos** (JWT, política de senha, fluxo de e-mail, TTL, URLs/templates, páginas backend) — cada uma em tabela tipada, não num blob.
 5. **[Anatomia de um e-mail: como link, template e URL se encaixam](#anatomia-de-um-e-mail)** — desambigua os três conceitos que mais confundem.
 6. **[Cinco modos de operação](#cinco-modos-de-operacao)** — produção, dev com SMTP local (Mailhog / smtp4dev), dev sem SMTP, CI sem ativação e **backend-only** (links e páginas servidas direto pelo backend).
 7. **[Mailhog vs smtp4dev — qual escolher pra dev local](#mailhog-vs-smtp4dev)** — comparativo + receitas docker-compose copy-paste.
@@ -149,42 +169,163 @@ uv run tempest db upgrade
       nem token de reset. Retorna **204** e os tokens atuais continuam
       válidos.
 
-## Troca, verificação e recuperação de e-mail (v0.92.0+)
+## Recuperação de senha
 
-Espelha o fluxo de senha, mas pro **e-mail** da conta. Três cenários:
+O clássico "esqueci minha senha". O usuário **não está logado** e prova
+identidade com um **token de uso único** que chega por e-mail. São dois
+passos.
 
-- **Trocar e-mail (logado)** — como `password-change`: o usuário está
-  logado, confirma a `current_password` e informa o `new_email`. Um link
-  de confirmação vai pro **novo** endereço; o e-mail só muda quando esse
-  link é confirmado. Ao confirmar, um aviso de segurança vai pro endereço
-  **antigo** (padrão de bancos/Google).
-- **Re-verificar o e-mail atual** — reenvia um link de verificação pro
-  endereço atual (útil quando o e-mail de ativação se perdeu).
-- **Recuperação (perdeu acesso ao e-mail)** — endpoint **não
-  autenticado**, opt-in via `AUTH_EMAIL_RECOVERY_ENABLED`. Prova
-  identidade com a senha **e um código MFA quando o TOTP está inscrito**,
-  e manda o link pro novo endereço.
+### Caso base (SPA / JSON)
 
-```python
-# Trocar e-mail (logado) — pega o token no body em dev (modo C)
-resp = await client.post(
-    "/auth/email-change/request",
-    json={"new_email": "nova@example.com", "current_password": "senha-atual"},
-    headers={"Authorization": f"Bearer {access_token}"},
-)
-confirm_url: str | None = resp.json()["confirm_url"]  # None em produção (vai por e-mail)
+**Passo 1 — pedir o link.** O usuário digita o e-mail; o backend sempre
+responde **202** com a mesma mensagem genérica (não vaza se o e-mail
+existe):
+
+```bash
+curl -X POST localhost:8000/auth/password-reset/request \
+  -H "Content-Type: application/json" \
+  -d '{"email": "ana@example.com"}'
+```
+
+```json
+{ "message": "Se o e-mail existir, enviamos um link.", "reset_url": null }
+```
+
+**Passo 2 — trocar a senha.** O usuário abre o link do e-mail; o
+front-end lê o `token` da URL e o envia com a nova senha. Em caso de
+sucesso a senha é trocada **e o usuário já sai logado** (vem um JWT pair):
+
+```bash
+curl -X POST localhost:8000/auth/password-reset/confirm \
+  -H "Content-Type: application/json" \
+  -d '{"token": "abc123…", "new_password": "nova-senha-forte-12"}'
+```
+
+```json
+{
+  "user_id": "7d8e4d5a-…",
+  "access_token": "eyJhbGciOi…",
+  "refresh_token": "eyJhbGciOi…",
+  "mfa_required": false,
+  "mfa_token": null
+}
+```
+
+!!! check "Erros que você vai ver"
+    - Token desconhecido / já usado / expirado → **400**.
+    - `new_password` viola `AUTH_PASSWORD_MIN_LENGTH` / complexidade → **422**.
+    - `request` **nunca** erra por e-mail inexistente — sempre **202**.
+
+!!! note "Modo dev: link no body (sem SMTP)"
+    Sem o extra `[email]`, ou com `AUTH_RETURN_TOKEN_IN_RESPONSE=True`, o
+    `reset_url` volta **no corpo** do `request` em vez de ir por e-mail —
+    você dispara o fluxo inteiro sem inbox. Em produção ele fica `null`.
+
+??? note "Sem front-end? Páginas HTML pelo backend (Modo E)"
+    Com `AUTH_BACKEND_LINKS=True` o SDK monta **GET/POST**
+    `/auth/password-reset/{token}`: o link do e-mail aponta pro backend,
+    que renderiza um formulário HTML, valida e mostra uma página de
+    sucesso/erro — sem nenhuma rota no front-end. Veja
+    [Cinco modos de operação](#cinco-modos-de-operacao) (Modo E).
+
+### Trocar a senha (logado)
+
+Diferente do reset: aqui o usuário **lembra** a senha e **está logado**.
+Não há token nem e-mail — ele manda o `access_token` no header e
+reconfirma a `current_password`:
 
-# ...usuário abre o link; o front extrai o token e confirma:
-await client.post("/auth/email-change/confirm", json={"token": token})
+```bash
+curl -X POST localhost:8000/auth/password-change \
+  -H "Authorization: Bearer eyJhbGciOi…" \
+  -H "Content-Type: application/json" \
+  -d '{"current_password": "senha-atual", "new_password": "nova-senha-forte-12"}'
+```
+
+Retorna **204**; os tokens atuais continuam válidos (este endpoint não
+revoga sessões). `current_password` errada → **401**.
+
+!!! tip "Reset vs change — qual é qual?"
+    - **Esqueceu** a senha, não está logado → **[Recuperação de senha](#recuperacao-de-senha)** (`password-reset/request` → `confirm`, prova com token de e-mail).
+    - **Lembra** a senha, está logado → **trocar a senha** (`password-change`, prova com a senha atual no header).
+
+## Troca e recuperação de e-mail
+
+O espelho do fluxo de senha, mas pro **e-mail** da conta (v0.92.0+). Três
+cenários distintos — comece pelo seu.
+
+### Trocar e-mail (logado)
+
+O caso base: o usuário **está logado** e quer mudar o próprio e-mail.
+Confirma a `current_password` e informa o `new_email`; um link de
+confirmação vai pro **novo** endereço. O e-mail só muda quando esse link
+é confirmado.
+
+```bash
+# Passo 1 — pedir a troca (autenticado). Sempre 202.
+curl -X POST localhost:8000/auth/email-change/request \
+  -H "Authorization: Bearer eyJhbGciOi…" \
+  -H "Content-Type: application/json" \
+  -d '{"new_email": "nova@example.com", "current_password": "senha-atual"}'
+
+# Passo 2 — confirmar (o front lê o token do link enviado ao novo e-mail).
+curl -X POST localhost:8000/auth/email-change/confirm \
+  -H "Content-Type: application/json" \
+  -d '{"token": "abc123…"}'
+```
+
+Ao confirmar, se `AUTH_EMAIL_CHANGE_NOTIFY_OLD=True` (padrão) um **aviso
+de segurança vai pro endereço antigo** — o padrão de bancos/Google, pra
+uma conta sequestrada ainda alertar o dono.
+
+!!! check "Erros"
+    - Senha atual errada → **401**.
+    - `new_email` já em uso (no pedido **ou** na confirmação — corrida) → **409**.
+    - Token inválido / expirado / usado → **400**.
+
+### Re-verificar o e-mail atual
+
+Reenvia um link de verificação pro **endereço atual** — útil quando o
+e-mail de ativação se perdeu. Autenticado, sem trocar nada; confirmar o
+link marca a conta ativa.
+
+```bash
+curl -X POST localhost:8000/auth/email-verify/request \
+  -H "Authorization: Bearer eyJhbGciOi…"
+# depois: POST /auth/email-verify/confirm  {"token": "…"}
+```
+
+### Recuperação de e-mail
+
+O "esqueci / perdi acesso ao meu e-mail". Endpoint **não autenticado** e
+**opt-in** — só é montado com `AUTH_EMAIL_RECOVERY_ENABLED=True`. O
+usuário prova identidade com a **senha** (e um **código MFA** quando o
+TOTP está inscrito) e informa o novo endereço; o link de confirmação vai
+pro **novo** e-mail e reusa o mesmo `email-change/confirm`.
+
+```bash
+# Só existe se AUTH_EMAIL_RECOVERY_ENABLED=True. Sempre 202 (anti-enumeração).
+curl -X POST localhost:8000/auth/email-recovery/request \
+  -H "Content-Type: application/json" \
+  -d '{
+        "email": "antigo@example.com",
+        "new_email": "novo@example.com",
+        "current_password": "senha-atual",
+        "mfa_code": "123456"
+      }'
+# depois: POST /auth/email-change/confirm  {"token": "…"}  (link foi pro novo e-mail)
 ```
 
 !!! danger "Recuperação é sensível — ligue com cuidado"
-    `POST /auth/email-recovery/request` deixa quem tem a senha mover a
-    conta pra outro e-mail **sem** acessar a caixa antiga. Só é montado
-    com `AUTH_EMAIL_RECOVERY_ENABLED=True`. Sempre responde **202**
-    genérico (não enumera contas) e, se o TOTP estiver inscrito, exige um
-    `mfa_code` válido. Mantenha `AUTH_EMAIL_CHANGE_NOTIFY_OLD=True` pra o
-    endereço antigo sempre ser avisado.
+    Esse endpoint deixa quem tem a **senha** mover a conta pra outro
+    e-mail **sem** acessar a caixa antiga — vetor de account takeover se a
+    senha vazou. Regras:
+
+    - **Opt-in**: fica desligado até `AUTH_EMAIL_RECOVERY_ENABLED=True`.
+    - Sempre **202** genérico pra toda falha leve (e-mail desconhecido,
+      senha errada, `mfa_code` faltando/errado) — não enumera contas.
+    - Se o TOTP estiver inscrito, exige um `mfa_code` válido.
+    - Mantenha `AUTH_EMAIL_CHANGE_NOTIFY_OLD=True` pra o e-mail antigo
+      sempre ser avisado da troca.
 
 !!! info "Onde o novo e-mail fica guardado"
     O endereço pendente viaja na coluna `payload` do token