tempest-fastapi-sdk 0.82.1__tar.gz → 0.87.0__tar.gz

{tempest_fastapi_sdk-0.82.1 → tempest_fastapi_sdk-0.87.0}/CHANGELOG.md

@@ -5,6 +5,102 @@ 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.87.0] — 2026-07-02
+
+### Added
+
+- **Configurable token delivery for the auth router.** `make_auth_router`
+  now supports three ways of handing back the JWT pair, selected by
+  `AUTH_TOKEN_DELIVERY` (or the `token_delivery=` argument):
+  - `"bearer"` (default) — tokens in the JSON body only. Unchanged,
+    fully backward-compatible behaviour.
+  - `"cookie"` — `access_token` / `refresh_token` set as `HttpOnly`
+    cookies on `/auth/login`, `/auth/refresh`, `/auth/logout`; the body
+    omits the token values (safer against XSS). `POST /auth/refresh`
+    reads the refresh token from the cookie and rotates the pair;
+    `POST /auth/logout` clears the cookies (and revokes the refresh
+    family when a `refresh_token_model` is wired).
+  - `"both"` — the bearer endpoints stay at `/auth/*` and a parallel
+    cookie set is mounted at `/auth/cookie/*`, so one backend can serve
+    web (cookie) and mobile/API (bearer) clients.
+- New `AUTH_COOKIE_SECURE`, `AUTH_COOKIE_SAMESITE`, `AUTH_COOKIE_DOMAIN`,
+  `AUTH_ACCESS_COOKIE_NAME` and `AUTH_REFRESH_COOKIE_NAME` settings tune
+  the cookie security attributes.
+- New public exports: `TokenDelivery`, `AuthCookieConfig`,
+  `apply_auth_cookies`, `clear_auth_cookies`.
+- `make_bearer_token_dependency` / `make_jwt_user_dependency` gained a
+  `cookie_name=` argument: when set, the access token is read from that
+  cookie if the `Authorization` header is absent (header still wins), so
+  the same guarded routes work in cookie mode.
+
+### Notes
+
+- Activation, signup auto-login and the MFA-verify step still return the
+  JWT pair in the body regardless of `AUTH_TOKEN_DELIVERY` — cookie
+  delivery covers the login / refresh / logout session lifecycle.
+
+## [0.86.0] — 2026-06-28
+
+### Added
+
+- **Admin rich list filters.** `list_filter` fields now auto-pick a
+  widget by column type instead of rendering a useful dropdown only for
+  booleans: **enum** columns become a member dropdown, **foreign keys**
+  (whose target has a registered `AdminModel`) become a related-row
+  dropdown, **date/datetime** columns become an inclusive date-range
+  (two date inputs → `<field>__gte` / `<field>__lte`), and any other
+  column becomes a text input (equality). Booleans keep the Yes/No
+  dropdown. All filters preserve search / sort / pagination in the URL.
+
+## [0.85.0] — 2026-06-28
+
+### Added
+
+- **Admin file / image upload fields.** `AdminModel` gained
+  `upload_fields=[...]` + `upload_storage=...`: listed String columns
+  render as file inputs in the create/edit form (which auto-switches to
+  `multipart/form-data`), the posted file is streamed to the storage
+  backend (`LocalUploadStorage` / `MinIOUploadStorage`), and the returned
+  storage key is written to the column. On edit, omitting the file keeps
+  the current value; on create, a missing file for a non-nullable column
+  is a required-field error. Registering `upload_fields` without
+  `upload_storage` raises `ValueError`.
+
+## [0.84.0] — 2026-06-28
+
+### Added
+
+- **Admin custom actions (`@admin_action`).** Beyond the three hardcoded
+  bulk operations (activate / deactivate / delete), the admin now takes
+  user-defined actions: decorate an async function with `@admin_action`
+  and register it via `AdminModel(actions=[...])`. Each renders in the
+  list view's bulk dropdown (namespaced `custom:<name>` so it can't
+  collide with the built-ins), runs on the checked rows, and flashes a
+  banner from its `AdminActionResult`. The handler receives an
+  `AdminActionContext` (selected ids, a request-scoped repository, the DB
+  session, the request, the admin session, and the acting principal) and
+  stays directly callable/testable — the decorator only attaches
+  metadata. Exported from `tempest_fastapi_sdk` and
+  `tempest_fastapi_sdk.admin` (`admin_action`, `AdminAction`,
+  `AdminActionContext`, `AdminActionResult`).
+
+## [0.83.0] — 2026-06-28
+
+### Added
+
+- **Computer-vision integration via the `[vision]` extra
+  (`ort-vision-sdk`).** New `tempest_fastapi_sdk.vision` submodule wraps
+  the ONNX Runtime inference library with the FastAPI layer it lacks:
+  Pydantic response schemas (`DetectionSchema`, `ClassificationSchema`,
+  `SegmentationSchema`, `BoundingBoxSchema`, `ClassProbabilitySchema`)
+  and mappers (`to_detection_schemas`, `to_classification_schema`,
+  `to_segmentation_schemas`) that convert a model result into them. The
+  `Detector` / `Classifier` / `Segmenter` task classes are re-exported
+  **lazily** — accessing one without the extra raises a clear
+  `ImportError` pointing at `[vision]`; the schemas and mappers carry no
+  such dependency. Like `cache` / `queue` / `tasks`, vision is
+  submodule-only (`from tempest_fastapi_sdk.vision import Detector`).
+
 ## [0.82.1] — 2026-06-28
 
 ### Fixed

{tempest_fastapi_sdk-0.82.1 → tempest_fastapi_sdk-0.87.0}/CLAUDE.md

@@ -88,8 +88,32 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
 - **Pagination** — offset + cursor.
 - **Settings mixins** — every `*Settings` carries
   `title`/`description`/`examples` on every field.
-- **SSE** — `EventStream`, `sse_response`.
-- **Throttle** — `AttemptThrottle` (memory + Redis).
+- **SSE** — `EventStream`, `ServerSentEvent`, `sse_response`, and
+  `SSEBroker` (per-channel fan-out; in-memory single-process, or
+  multi-worker via an injected Redis pub/sub bridge — same call site).
+- **Throttle** — `AttemptThrottle` (any `ThrottleBackend`, e.g.
+  `redis.asyncio.Redis`; no in-memory backend bundled).
+- **Base CRUD layers** — `BaseService[Repo, Resp, UpdateT]` and
+  `BaseController[Service, Resp, UpdateT]` with
+  `get_by_id`/`get_or_none`/`list`/`paginate`/`count`/`exists`/`update`/
+  `delete`; `update` is partial-aware (PUT/PATCH) and `UpdateT` is an
+  optional 3rd generic (defaults to `BaseSchema`, PEP 696).
+- **Base enums** — `BaseStrEnum` / `BaseIntEnum` with
+  `values`/`keys`/`choices`/`to_dict`/`from_value`/`has_value`/`has_key`.
+- **Validated field types** — `tempest_fastapi_sdk.utils` Annotated
+  Pydantic types: `PositiveIntField`/`NonNegativeIntField`/`CentsField`/
+  `PortField`/`PositiveFloatField`/`NonNegativeFloatField`/`PercentField`/
+  `RatioField`/`LatitudeField`/`LongitudeField`/`PriceField`/
+  `NonEmptyStrField`/`SlugField`/`HexColorField`.
+- **Runtime typing** — `strict_types` / `typed` / `require_annotations`
+  decorators (over `pydantic.validate_call`); ruff `ANN` enabled in the
+  SDK and `tempest new` templates (ANN401 off — `Any` is valid); a
+  `[tool.tempest] typing_strictness` knob (`lenient`/`standard`/`strict`,
+  `--strictness` override) layered onto `tempest lint`/`fix`/`type`/`check`.
+- **Vision** (`[vision]` extra) — `tempest_fastapi_sdk.vision` wrapping
+  `ort-vision-sdk`: lazy `Detector`/`Classifier`/`Segmenter` + prediction
+  schemas + `to_detection_schemas`/`to_classification_schema`/
+  `to_segmentation_schemas` mappers.
 - **Upload** — `UploadUtils` with pluggable backends
   (`LocalUploadStorage`, `MinIOUploadStorage`), download helpers,
   presigned URLs.
@@ -99,17 +123,26 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
 - **Email** — SMTP via `EmailUtils` + Jinja2 template rendering
   with bundled defaults (`activation.html`, `password_reset.html`)
   shadowable by the project's `template_dir`.
-- **WebPush** + webhook signatures.
+- **WebPush** — `WebPushDispatcher` (`send`/`send_many`, 404/410
+  pruning), subscription storage (`BaseWebPushSubscriptionModel` +
+  `make_web_push_subscription_model`) + `WebPushSubscriptionService`
+  (`subscribe`/`unsubscribe`/`list_for_user`/`notify_user` with
+  auto-prune of gone endpoints) + `make_web_push_router` (opt-in
+  `/subscribe` + `/unsubscribe`, aligned with `tempest-react-sdk`);
+  webhook signatures.
 - **Cache** — Redis manager + `@cached`.
 - **Queue / tasks** — FastStream + TaskIQ wrappers.
-- **BR validators** — CPF/CNPJ/CEP/phone.
+- **BR validators** — CPF/CNPJ/CEP/phone, with `*Field` Pydantic types
+  (`CPFField`/`CNPJField`/`CPFOrCNPJField`/`PhoneBRField`/`CEPField`;
+  pre-0.76 unsuffixed names kept as deprecated aliases).
 - **BR localities** — `UF` (StrEnum, 27 siglas) + `Region`
   (5 macro-regiões IBGE), `StateBR`/`CityBR` schemas, offline
   dataset of 27 states + 5606 municipalities (IBGE-derived,
   DF as 36 administrative regions), `list_states`/`get_state`/
   `cities_by_uf`/`states_by_region`, `is_valid_uf`/`normalize_uf`,
   `is_valid_city`/`normalize_city` (accent/case-insensitive),
-  `UFField`/`CityNameField`.
+  `UFField`/`CityNameField`, plus `ChoiceBR` + `uf_choices`/
+  `region_choices`/`city_choices` (frontend `<select>` choices).
 - **Rate limit** — `RateLimitMiddleware` (sliding window) with
   pluggable store (`MemoryRateLimitStore` / `RedisRateLimitStore`,
   atomic Lua) and per-principal key extractors (`key_by_ip`,
@@ -131,7 +164,11 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
 - **Admin panel** — Jinja + HTMX (`AdminSite`, `AdminModel`,
   `make_admin_router`), typed theming via `AdminTheme` (colors /
   logo / favicon / font / radius / footer / dark mode /
-  `custom_css_url`, injected as `:root` overrides).
+  `custom_css_url`, injected as `:root` overrides), custom bulk actions
+  (`@admin_action` + `AdminModel(actions=[...])`, `AdminActionContext` /
+  `AdminActionResult`), file/image upload fields (`AdminModel(
+  upload_fields=[...], upload_storage=...)`), rich list filters
+  (bool/enum/FK select, date-range, text — auto by column type).
 - **CLI** — `tempest new` (scaffolds layered service +
   docker-compose + multi-stage uv `Dockerfile`/`.dockerignore`),
   `tempest generate --docker` (regen compose) / `--dockerfile`
@@ -169,41 +206,46 @@ then move it up to the covers list.
 foundation the user asked for first; the functional Tier 1 items below
 inherit the look for free. Now in the covers list.
 
+**Shipped — custom actions (v0.84.0).** `@admin_action` decorator +
+`AdminModel(actions=[...])` + `AdminActionContext`/`AdminActionResult`;
+custom entries render in the bulk dropdown (namespaced `custom:<name>`),
+run on the checked rows, and flash a banner on the list view. Now in the
+covers list.
+
+**Shipped — file / image upload field (v0.85.0).** `AdminModel(
+upload_fields=[...], upload_storage=...)` renders String columns as file
+inputs, streams the upload to `LocalUploadStorage` / `MinIOUploadStorage`,
+and stores the returned key. Now in the covers list.
+
+**Shipped — rich filters (v0.86.0).** `list_filter` fields auto-pick a
+widget by column type: bool / enum / FK → select, date/datetime →
+inclusive date-range (two inputs → `__gte`/`__lte`), other → text.
+Now in the covers list.
+
 **Tier 1 — high value, reuses an existing engine (low effort):**
 
-1. **Custom actions (NEXT)** — `@admin_action` decorator on `AdminModel`
-   for user-defined row / bulk operations (Django `actions`, Nova
-   actions). Today only 3 are hardcoded (activate / deactivate /
-   delete). This is the foundation the rest build on.
-2. **File / image upload field** — a new form widget wired to the
-   existing `UploadUtils` (`LocalUploadStorage` / `MinIOUploadStorage`).
-   Engine is already shipped; admin just needs the widget + storage
-   binding.
-3. **Rich filters** — enum / choice / FK / date-range filters in the
-   list view (today only boolean fields auto-render a filter dropdown).
-   Quick UX win.
-4. **Audit history viewer** — a per-row change timeline wired to the
+1. **Audit history viewer (NEXT)** — a per-row change timeline wired to the
    existing `BaseAuditLogModel` + `diff_snapshots`. Today the detail
    view only shows `created_by` / `updated_by` stamps, not full history.
    Engine is already shipped.
 
 **Tier 2 — high value, medium effort:**
 
-5. **Autocomplete FK fields** — HTMX search endpoint backing FK inputs,
+2. **Autocomplete FK fields** — HTMX search endpoint backing FK inputs,
    removing the 1000-row `<select>` cap and the plain-UUID fallback
    (Django `autocomplete_fields`, Nova search).
-6. **Inlines / nested relations** — edit child rows inside the parent's
+3. **Inlines / nested relations** — edit child rows inside the parent's
    detail / edit view (Django `StackedInline` / `TabularInline`).
-7. **Dashboard business metrics / charts** — value / trend / partition
+4. **Dashboard business metrics / charts** — value / trend / partition
    cards (Nova metrics), wired to the existing metrics module. Distinct
    from today's system CPU/RAM/disk panel.
 
 **Tier 3 — nice-to-have:**
 
-8. **RBAC granular** — per-model / per-action admin permissions beyond
+5. **RBAC granular** — per-model / per-action admin permissions beyond
    today's `is_admin` + `can_create` / `can_edit` / `can_delete`.
-9. **CSV import** — bulk upload counterpart to the existing export.
-10. **Lenses** — saved alternate views / queries per model (Nova).
+6. **CSV import** — bulk upload counterpart to the existing export.
+7. **Lenses** — saved alternate views / queries per model (Nova).
 
 Origin: competitor gap analysis (Django Admin, Laravel Nova, SQLAdmin,
 Starlette-Admin) run 2026-06-26. Do **not** treat the tiers as locked —

{tempest_fastapi_sdk-0.82.1 → tempest_fastapi_sdk-0.87.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.82.1
+Version: 0.87.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
@@ -49,6 +49,7 @@ Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == 'all'
 Requires-Dist: opentelemetry-instrumentation-httpx>=0.48b0; extra == 'all'
 Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.48b0; extra == 'all'
 Requires-Dist: opentelemetry-sdk>=1.27.0; extra == 'all'
+Requires-Dist: ort-vision-sdk>=0.4.0; extra == 'all'
 Requires-Dist: prometheus-client>=0.20.0; extra == 'all'
 Requires-Dist: psutil>=6.0.0; extra == 'all'
 Requires-Dist: pyjwt>=2.12.1; extra == 'all'
@@ -96,6 +97,8 @@ Requires-Dist: taskiq>=0.11.0; extra == 'tasks'
 Provides-Extra: upload
 Requires-Dist: aiofiles>=24.1.0; extra == 'upload'
 Requires-Dist: python-multipart>=0.0.12; extra == 'upload'
+Provides-Extra: vision
+Requires-Dist: ort-vision-sdk>=0.4.0; extra == 'vision'
 Provides-Extra: webpush
 Requires-Dist: cryptography>=42.0.0; extra == 'webpush'
 Requires-Dist: pywebpush>=2.0.0; extra == 'webpush'
@@ -219,6 +222,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[http]` | `httpx` | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, OAuth2 / OIDC providers |
 | `[prometheus]` | `prometheus-client` | `PrometheusMiddleware`, `make_prometheus_router`, `make_prometheus_registry` |
 | `[mfa]` | `pyotp` | `TOTPHelper` + MFA/2FA endpoints on the bundled auth flow |
+| `[vision]` | `ort-vision-sdk` | `Detector` / `Classifier` / `Segmenter` (ONNX) + prediction schemas |
 | `[otel]` | `opentelemetry-sdk` + OTLP/gRPC exporter + FastAPI/SQLAlchemy/httpx instrumentors | `setup_tracing` — distributed tracing |
 | `[sqlite]` | `aiosqlite` | SQLite async driver for `sqlite+aiosqlite://` URLs (dev default) |
 | `[postgres]` | `asyncpg` | PostgreSQL async driver for `postgresql+asyncpg://` URLs (production) |
@@ -259,10 +263,11 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `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]`)* | `AsyncTaskBrokerManager` (TaskIQ lifecycle wrapper), `AsyncTaskScheduler` (periodic / cron tasks) |
+| `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.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)*, `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.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` and `tempest_fastapi_sdk.tasks` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).
+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` and `tempest_fastapi_sdk.vision` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).
 
 ---
 

{tempest_fastapi_sdk-0.82.1 → tempest_fastapi_sdk-0.87.0}/README.md

@@ -116,6 +116,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[http]` | `httpx` | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, OAuth2 / OIDC providers |
 | `[prometheus]` | `prometheus-client` | `PrometheusMiddleware`, `make_prometheus_router`, `make_prometheus_registry` |
 | `[mfa]` | `pyotp` | `TOTPHelper` + MFA/2FA endpoints on the bundled auth flow |
+| `[vision]` | `ort-vision-sdk` | `Detector` / `Classifier` / `Segmenter` (ONNX) + prediction schemas |
 | `[otel]` | `opentelemetry-sdk` + OTLP/gRPC exporter + FastAPI/SQLAlchemy/httpx instrumentors | `setup_tracing` — distributed tracing |
 | `[sqlite]` | `aiosqlite` | SQLite async driver for `sqlite+aiosqlite://` URLs (dev default) |
 | `[postgres]` | `asyncpg` | PostgreSQL async driver for `postgresql+asyncpg://` URLs (production) |
@@ -156,10 +157,11 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `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]`)* | `AsyncTaskBrokerManager` (TaskIQ lifecycle wrapper), `AsyncTaskScheduler` (periodic / cron tasks) |
+| `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.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)*, `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.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` and `tempest_fastapi_sdk.tasks` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).
+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` and `tempest_fastapi_sdk.vision` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).
 
 ---
 

{tempest_fastapi_sdk-0.82.1 → tempest_fastapi_sdk-0.87.0}/docs/recipes/admin.en.md

@@ -1,7 +1,7 @@
 # Admin site
 
 
-Django-style management UI mounted under `/admin`. Operators sign in with a user row from the database (no separate admin password store) and browse every registered model from the browser, so the database port can stay closed on private networks. The panel is feature-complete (Django-admin parity): a list view with search / per-field filters / sortable columns, full CRUD (create / edit / delete), bulk actions, CSV/JSON export, FK-select widgets, a dashboard with live row counts + system metrics, optional TOTP MFA at login, and an audit trail stamping `created_by` / `updated_by`. Still on the roadmap: file upload and inline/related editing.
+Django-style management UI mounted under `/admin`. Operators sign in with a user row from the database (no separate admin password store) and browse every registered model from the browser, so the database port can stay closed on private networks. The panel is feature-complete (Django-admin parity): a list view with search / rich per-field filters (enum / FK / date-range) / sortable columns, full CRUD (create / edit / delete), bulk actions, CSV/JSON export, FK-select widgets, a dashboard with live row counts + system metrics, optional TOTP MFA at login, file/image upload fields, and an audit trail stamping `created_by` / `updated_by`. Still on the roadmap: inline/related editing.
 
 Requires the `[admin]` extra:
 
@@ -88,6 +88,14 @@ site.register(AdminModel(
 
 Every field reference also accepts a plain string (`list_display=["email", ...]`) for dynamic configuration, and `ordering` accepts a column (ascending), `desc(column)` / `asc(column)`, or a Django-style `"-created_at"` string. `register` returns the instance and raises `ValueError` on a duplicate slug. Slugs default to the model's `__tablename__` so URLs and database tables stay in sync.
 
+!!! info "Filters auto-pick a widget per column type"
+    Each `list_filter` field renders the right widget by column type:
+    **boolean** → Yes/No dropdown; **enum** → dropdown of the members;
+    **FK** (whose target has a registered `AdminModel`) → dropdown of the
+    related rows (labelled via `search_fields`); **date/datetime** → two
+    date inputs (from/to, inclusive range); any other column → a text
+    input (equality). All preserve search/sort/pagination in the URL.
+
 !!! tip "Centered, customizable brand"
     The name shown in the center of the header comes from `brand`
     (optional). Without it, it falls back to `title` — so existing sites
@@ -178,7 +186,7 @@ app.include_router(
 - `GET  /admin/logs` — **application logs** (when `show_logs=True`): reads the structured JSON files written by `configure_logging(log_dir=…)`, with source filter (`?source=`), free-text search (`?q=`) and pagination. Color-coded level badges. Renders an empty state when no log files exist yet.
 - `GET  /admin/m/{slug}/` — list view with pagination + free-text search (`?q=`) + per-field filters (`?filter_<field>=value`) + clickable **column sorting** (`?sort=<column>&dir=asc|desc`).
 - `GET  /admin/m/{slug}/export.csv` / `export.json` — **export** the current result set (honoring search/filters/sort) as CSV or JSON. Row cap via `make_admin_router(export_max_rows=…)` (default 5000).
-- `POST /admin/m/{slug}/bulk` — **bulk actions** (delete / activate / deactivate) on the selected rows.
+- `POST /admin/m/{slug}/bulk` — **bulk actions** (delete / activate / deactivate + your **custom actions**) on the selected rows.
 - `GET/POST /admin/m/{slug}/new` — **create** a record (when `can_create`).
 - `GET  /admin/m/{slug}/{identity}` — detail view with Edit/Delete controls.
 - `GET/POST /admin/m/{slug}/{identity}/edit` — **edit** a record (when `can_edit`).
@@ -196,7 +204,82 @@ app.include_router(
 
     **Audit trail**: create/edit through the admin stamps `created_by`/`updated_by` (from `AuditMixin`) with the acting admin's id; the detail view shows an **Audit** panel with timestamps and — when the model has the audit columns — the actor (UUID resolved to a display name via the auth backend). Models without `AuditMixin` show timestamps only.
 
-    Not yet included (later roadmap phases): file upload, inline/related editing.
+    Not yet included (later roadmap phases): inline/related editing.
+
+## Custom actions (`@admin_action`)
+
+Beyond the 3 built-ins (activate / deactivate / delete), you register
+**your own actions** — an async function decorated with `@admin_action`
+and passed to `AdminModel(actions=[...])`. Each becomes an option in the
+bulk-action dropdown, operating on the checked rows.
+
+```python
+from tempest_fastapi_sdk import (
+    AdminActionContext,
+    AdminActionResult,
+    AdminModel,
+    admin_action,
+)
+
+
+@admin_action(label="Send welcome")
+async def send_welcome(ctx: AdminActionContext) -> AdminActionResult:
+    """Runs on the selected rows; the message is shown on the list view."""
+    users = await ctx.repository.list(filters={"id": ctx.ids})
+    for user in users:
+        await mailer.send_welcome(user.email)
+    return AdminActionResult(f"Sent {len(users)} emails.")
+
+
+site.register(AdminModel(model=UserModel, actions=[send_welcome]))
+```
+
+The handler receives an `AdminActionContext`:
+
+| Field | What it is |
+| --- | --- |
+| `ids` | Identities of the checked rows. |
+| `repository` | The model's `BaseRepository`, on the request session. |
+| `db_session` | The DB session (for work beyond the repository). |
+| `request` | The inbound request. |
+| `session` | The authenticated admin session. |
+| `principal` | The admin user row that triggered the action. |
+
+Return an `AdminActionResult(message, category="success"|"error"|"warning")`
+to flash a banner on the list view (or `None` for no banner). The
+function stays **directly callable/testable** — the decorator only
+attaches metadata. Use `name=` to pin the identifier (default: the
+function name) and `dangerous=True` to mark a destructive action.
+
+## File / image upload field
+
+A `String` column that stores a file's path/key can render as a **file
+input** on the form. List the column in `upload_fields` and pass an
+`upload_storage` (the SDK's existing backends — `LocalUploadStorage` /
+`MinIOUploadStorage`). On submit the file is saved to storage and the
+**returned key** is written to the column.
+
+```python
+from tempest_fastapi_sdk import AdminModel
+from tempest_fastapi_sdk.utils import LocalUploadStorage
+
+
+site.register(AdminModel(
+    model=DocumentModel,
+    upload_fields=[DocumentModel.attachment],   # String column holding the key
+    upload_storage=LocalUploadStorage("media/"),  # or MinIOUploadStorage(...)
+))
+```
+
+- The form becomes `multipart/form-data` automatically when `upload_fields` is set.
+- **Create**: a file is required only when the column is `NOT NULL` with no default.
+- **Edit**: no new file → keeps the current value (shows "Current: …"); a file → replaces it.
+- The column stores the storage **key** (`<slug>/<field>/<uuid>.<ext>`); use `upload_storage` (or `UploadUtils`) to serve/download it later.
+
+!!! warning "`upload_fields` requires `upload_storage`"
+    Registering `upload_fields` without `upload_storage` raises
+    `ValueError` at `AdminModel` construction — without storage there's
+    nowhere to write the file.
 
 !!! tip "Sidebar + burger navigation"
     Every authenticated page has a persistent **sidebar**: Dashboard, one
@@ -230,6 +313,30 @@ app.include_router(
 - Per-session CSRF token is generated at login and required by every form POST (login, logout, create, edit, delete, bulk actions).
 - `secret_key` must be at least 32 bytes — short keys raise `ValueError` at construction time.
 
+!!! danger "Login looping? It's the cookie `Secure` flag over plain HTTP"
+    If `POST /admin/login` returns `303` (looks like success), but the following
+    `GET /admin/` redirects back to the login — forever — the session cookie is
+    **not coming back**. Almost-certain cause: `cookie_secure=True` while the
+    admin is served over **plain HTTP** (no TLS terminator in front). The browser
+    refuses to store a `Secure` cookie on a non-HTTPS connection, so no session
+    ever persists.
+
+    ```python
+    # ❌ Tied to DEBUG: in production DEBUG=false → cookie_secure=True,
+    #    but with no HTTPS in front the login loops.
+    make_admin_router(..., cookie_secure=not settings.DEBUG)
+
+    # ✅ Dedicated toggle, independent of DEBUG:
+    make_admin_router(..., cookie_secure=settings.ADMIN_COOKIE_SECURE)
+    ```
+
+    **Right fix:** put HTTPS in front (nginx/Caddy terminating TLS) and keep
+    `cookie_secure=True` — the admin session cookie must not travel in the clear.
+    **Stopgap** only when the admin genuinely runs over HTTP (intranet, MVP):
+    `cookie_secure=False`, aware the session ships without `Secure`. Don't tie
+    this flag to `DEBUG` — turning debug on in production is worse than the
+    original problem.
+
 #### 5. Plug in a custom auth backend
 
 `AdminAuthBackend` is an ABC, so swap the default for LDAP / OAuth / external IAM by subclassing:

{tempest_fastapi_sdk-0.82.1 → tempest_fastapi_sdk-0.87.0}/docs/recipes/admin.md

@@ -1,7 +1,7 @@
 # Painel admin
 
 
-UI de gerenciamento no estilo Django montada sob `/admin`. Operadores entram com uma linha de usuário do banco (sem store de senha de admin separado) e navegam por todo modelo registrado pelo navegador, então a porta do banco pode ficar fechada em redes privadas. O painel é completo (paridade com o Django admin): list view com busca / filtros por campo / colunas ordenáveis, CRUD completo (criar / editar / excluir), ações em massa, export CSV/JSON, widgets FK-select, dashboard com contagens de linhas + métricas de sistema, MFA TOTP opcional no login, e trilha de auditoria carimbando `created_by` / `updated_by`. Ainda no roadmap: upload de arquivo e edição inline/relacionada.
+UI de gerenciamento no estilo Django montada sob `/admin`. Operadores entram com uma linha de usuário do banco (sem store de senha de admin separado) e navegam por todo modelo registrado pelo navegador, então a porta do banco pode ficar fechada em redes privadas. O painel é completo (paridade com o Django admin): list view com busca / filtros ricos por campo (enum / FK / range de data) / colunas ordenáveis, CRUD completo (criar / editar / excluir), ações em massa, export CSV/JSON, widgets FK-select, dashboard com contagens de linhas + métricas de sistema, MFA TOTP opcional no login, campos de upload de arquivo/imagem, e trilha de auditoria carimbando `created_by` / `updated_by`. Ainda no roadmap: edição inline/relacionada.
 
 Requer o extra `[admin]`:
 
@@ -88,6 +88,15 @@ site.register(AdminModel(
 
 Toda referência a campo também aceita uma string simples (`list_display=["email", ...]`) para configuração dinâmica, e `ordering` aceita uma coluna (ascendente), `desc(column)` / `asc(column)`, ou uma string no estilo Django `"-created_at"`. `register` retorna a instância e levanta `ValueError` em slug duplicado. Os slugs derivam por padrão do `__tablename__` do modelo, para que URLs e tabelas do banco fiquem em sincronia.
 
+!!! info "Filtros automáticos por tipo de coluna"
+    Cada campo em `list_filter` vira o widget certo conforme o tipo da
+    coluna: **boolean** → dropdown Sim/Não; **enum** → dropdown com os
+    membros; **FK** (cujo destino tem `AdminModel` registrado) → dropdown
+    das linhas relacionadas (label pelo `search_fields`); **date/datetime**
+    → dois inputs de data (de/até, range inclusivo); qualquer outra coluna
+    → input de texto (igualdade). Tudo preserva busca/ordenação/paginação
+    na URL.
+
 !!! tip "Marca centralizada e customizável"
     O nome exibido no centro do header vem de `brand` (opcional). Sem ele, cai no `title` — então sites existentes não mudam. Use `brand` para mostrar um nome distinto (ex.: `"servus-backend-admin"`) centralizado no topo de toda página. A sidebar é fixa e **sobrepõe header e footer** no desktop (z-index maior) — comportamento automático do CSS embutido, sem config.
 
@@ -160,7 +169,7 @@ app.include_router(
 - `GET  /admin/logs` — **logs da aplicação** (quando `show_logs=True`): lê os arquivos JSON estruturados escritos pelo `configure_logging(log_dir=…)`, com filtro por fonte (`?source=`), busca em texto (`?q=`) e paginação. Badges coloridos por nível. Quando ainda não há arquivos de log, mostra um estado vazio.
 - `GET  /admin/m/{slug}/` — list view com paginação + busca em texto livre (`?q=`) + filtros por campo (`?filter_<field>=value`) + **ordenação por coluna** clicável (`?sort=<coluna>&dir=asc|desc`).
 - `GET  /admin/m/{slug}/export.csv` / `export.json` — **exporta** o resultado atual (respeitando busca/filtros/ordenação) como CSV ou JSON. Limite de linhas via `make_admin_router(export_max_rows=…)` (default 5000).
-- `POST /admin/m/{slug}/bulk` — **ações em massa** (delete / activate / deactivate) nas linhas selecionadas.
+- `POST /admin/m/{slug}/bulk` — **ações em massa** (delete / activate / deactivate + suas **ações customizadas**) nas linhas selecionadas.
 - `GET/POST /admin/m/{slug}/new` — **criar** registro (quando `can_create`).
 - `GET  /admin/m/{slug}/{identity}` — detail view com botões Edit/Delete.
 - `GET/POST /admin/m/{slug}/{identity}/edit` — **editar** registro (quando `can_edit`).
@@ -178,7 +187,81 @@ app.include_router(
 
     **Audit trail**: create/edit pelo admin carimba `created_by`/`updated_by` (do `AuditMixin`) com o id do admin atuante; o detail mostra um painel **Audit** com timestamps e — quando o modelo tem as colunas de auditoria — o ator (UUID resolvido para nome via o auth backend). Modelos sem `AuditMixin` mostram só os timestamps.
 
-    Ainda **não** incluídos (fases futuras do roadmap): upload de arquivo, inline/related editing.
+    Ainda **não** incluídos (fases futuras do roadmap): inline/related editing.
+
+## Ações customizadas (`@admin_action`)
+
+Além das 3 fixas (activate / deactivate / delete), você registra **ações
+próprias** — uma função async decorada com `@admin_action` e passada em
+`AdminModel(actions=[...])`. Cada uma vira uma opção no dropdown de ações
+em massa, operando nas linhas marcadas.
+
+```python
+from tempest_fastapi_sdk import (
+    AdminActionContext,
+    AdminActionResult,
+    AdminModel,
+    admin_action,
+)
+
+
+@admin_action(label="Enviar boas-vindas")
+async def send_welcome(ctx: AdminActionContext) -> AdminActionResult:
+    """Roda nas linhas selecionadas; a mensagem é exibida na list view."""
+    users = await ctx.repository.list(filters={"id": ctx.ids})
+    for user in users:
+        await mailer.send_welcome(user.email)
+    return AdminActionResult(f"{len(users)} e-mails enviados.")
+
+
+site.register(AdminModel(model=UserModel, actions=[send_welcome]))
+```
+
+O handler recebe um `AdminActionContext` com:
+
+| Campo | O que é |
+| --- | --- |
+| `ids` | Identidades das linhas marcadas. |
+| `repository` | `BaseRepository` do modelo, na sessão do request. |
+| `db_session` | A sessão DB (pra trabalho além do repositório). |
+| `request` | O request inbound. |
+| `session` | A sessão do admin autenticado. |
+| `principal` | A linha do usuário admin que disparou a ação. |
+
+Retorne um `AdminActionResult(message, category="success"|"error"|"warning")`
+pra exibir um banner na list view (ou `None` pra não mostrar nada). A
+função fica **diretamente chamável/testável** — o decorator só anexa
+metadados. Use `name=` pra fixar o identificador (default: nome da função)
+e `dangerous=True` pra marcar ação destrutiva.
+
+## Campo de upload de arquivo / imagem
+
+Uma coluna `String` que guarda o caminho/chave de um arquivo pode virar um
+**input de upload** no formulário. Liste a coluna em `upload_fields` e
+passe um `upload_storage` (os backends que o SDK já tem —
+`LocalUploadStorage` / `MinIOUploadStorage`). No submit, o arquivo é
+salvo no storage e a **chave retornada** é gravada na coluna.
+
+```python
+from tempest_fastapi_sdk import AdminModel
+from tempest_fastapi_sdk.utils import LocalUploadStorage
+
+
+site.register(AdminModel(
+    model=DocumentModel,
+    upload_fields=[DocumentModel.attachment],   # coluna String que guarda a chave
+    upload_storage=LocalUploadStorage("media/"),  # ou MinIOUploadStorage(...)
+))
+```
+
+- O form vira `multipart/form-data` automaticamente quando há `upload_fields`.
+- **Create**: arquivo obrigatório só se a coluna for `NOT NULL` e sem default.
+- **Edit**: sem arquivo novo → mantém o valor atual (mostra "Current: …"); com arquivo → substitui.
+- A coluna guarda a **chave** do storage (`<slug>/<campo>/<uuid>.<ext>`); use o `upload_storage` (ou `UploadUtils`) pra servir/baixar depois.
+
+!!! warning "`upload_fields` exige `upload_storage`"
+    Registrar `upload_fields` sem `upload_storage` levanta `ValueError` na
+    construção do `AdminModel` — sem storage não há onde gravar o arquivo.
 
 !!! tip "Navegação por sidebar + burger"
     Toda página autenticada tem uma **sidebar** persistente: Dashboard, um
@@ -212,6 +295,28 @@ app.include_router(
 - Um token CSRF por sessão é gerado no login e exigido por todo POST de formulário (login, logout, criar, editar, excluir, ações em massa).
 - `secret_key` deve ter ao menos 32 bytes — chaves curtas levantam `ValueError` no momento da construção.
 
+!!! danger "Login em loop? É o `Secure` do cookie sobre HTTP puro"
+    Se o `POST /admin/login` responde `303` (parece sucesso), mas o `GET /admin/`
+    seguinte redireciona de volta pro login — repetindo pra sempre — o cookie de
+    sessão **não está voltando**. Causa quase certa: `cookie_secure=True` enquanto
+    o admin é servido por **HTTP puro** (sem TLS na frente). O browser recusa
+    gravar um cookie `Secure` em conexão não-HTTPS, então nenhuma sessão persiste.
+
+    ```python
+    # ❌ Atado a DEBUG: em produção DEBUG=false → cookie_secure=True,
+    #    mas se não houver HTTPS na frente, o login entra em loop.
+    make_admin_router(..., cookie_secure=not settings.DEBUG)
+
+    # ✅ Controle dedicado, independente de DEBUG:
+    make_admin_router(..., cookie_secure=settings.ADMIN_COOKIE_SECURE)
+    ```
+
+    **Correção certa:** ponha HTTPS na frente (nginx/Caddy terminando TLS) e
+    deixe `cookie_secure=True` — o cookie da sessão admin não deve trafegar em
+    claro. **Paliativo** só quando o admin roda mesmo em HTTP (intranet, MVP):
+    `cookie_secure=False`, ciente de que a sessão vai sem `Secure`. Não amarre
+    esse flag ao `DEBUG` — ligar debug em produção é pior que o problema original.
+
 #### 5. Plugue um backend de auth customizado
 
 `AdminAuthBackend` é uma ABC, então troque o default por LDAP / OAuth / IAM externo subclasseando: