tempest-fastapi-sdk 0.78.0__tar.gz → 0.80.0__tar.gz

{tempest_fastapi_sdk-0.78.0 → tempest_fastapi_sdk-0.80.0}/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.80.0] — 2026-06-28
+
+### Added
+
+- **Web Push subscription storage + service.** The webpush module gained
+  the missing persistence layer so apps no longer hand-roll it:
+  `BaseWebPushSubscriptionModel` (abstract table, one row per user device,
+  unique `endpoint`) + `make_web_push_subscription_model(user_table=...)`
+  factory, mirroring the `BaseUserTokenModel` pattern; and
+  `WebPushSubscriptionService` (generic over the concrete model) with
+  `subscribe` (idempotent upsert keyed by endpoint), `unsubscribe`,
+  `list_for_user`, `prune`, and `notify_user` — which fans a payload out
+  to every device and **auto-prunes the ones the push service reports as
+  gone (404/410)**. The wire shape matches `PushSubscription.toJSON()`,
+  so it lines up 1:1 with `tempest-react-sdk`'s `WebPushClient`
+  `onSubscribe` / `onUnsubscribe` callbacks. Exported from
+  `tempest_fastapi_sdk`, `tempest_fastapi_sdk.webpush` and
+  `tempest_fastapi_sdk.db`.
+
+## [0.79.0] — 2026-06-27
+
+### Changed
+
+- **`BaseService` / `BaseController` `update` payload is now generically
+  typed.** Both classes gained an optional third type parameter
+  `UpdateT` (bound to `BaseSchema`, default `BaseSchema`) so `update`
+  accepts the project's own update schema instead of the bare
+  `BaseSchema`: `BaseService[Repo, Resp, MyUpdateSchema]` /
+  `BaseController[Service, Resp, MyUpdateSchema]`. The default keeps every
+  existing two-argument subclass working unchanged. Implemented with a
+  PEP 695/696 `TypeVar` default via `typing_extensions` (already present
+  through Pydantic).
+
 ## [0.78.0] — 2026-06-27
 
 ### Added

{tempest_fastapi_sdk-0.78.0 → tempest_fastapi_sdk-0.80.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.78.0
+Version: 0.80.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
@@ -210,7 +210,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[email]` | `aiosmtplib`, `jinja2` | `EmailUtils` + `render_template()` |
 | `[upload]` | `aiofiles`, `python-multipart` | `UploadUtils`, `LocalUploadStorage`, `MinIOUploadStorage` (when combined with `[minio]`) |
 | `[cache]` | `redis` | `AsyncRedisManager` |
-| `[webpush]` | `pywebpush`, `cryptography` | `WebPushDispatcher` |
+| `[webpush]` | `pywebpush`, `cryptography` | `WebPushDispatcher`, `WebPushSubscriptionService`, `BaseWebPushSubscriptionModel` |
 | `[metrics]` | `psutil`, `nvidia-ml-py` | `MetricsUtils` |
 | `[queue]` | `faststream[rabbit]` | `AsyncBrokerManager` (FastStream) |
 | `[tasks]` | `taskiq`, `taskiq-aio-pika` | `AsyncTaskBrokerManager` (TaskIQ) |
@@ -241,7 +241,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | Module | Exports |
 | --- | --- |
 | `tempest_fastapi_sdk.schemas` | `BaseSchema`, `BaseResponseSchema`, `BasePaginationFilterSchema`, `BasePaginationSchema[T]`, `CursorPaginationFilterSchema`, `CursorPaginationSchema`, `LogEntrySchema`, `encode_cursor`, `decode_cursor`, `build_pagination_link_header` |
-| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `TenantScopedRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper` (+ `safe_upgrade`), `DestructiveMigrationError`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks`, `SlowQueryLogger`, `BaseOutboxModel`, `OutboxRelay`, `OutboxStatus`, `BaseRepository.save_with_outbox`, audit trail (`BaseAuditLogModel`, `AuditAction`, `snapshot_model`, `diff_snapshots`, `BaseRepository.add_audited` / `update_audited` / `delete_audited`) |
+| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `TenantScopedRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper` (+ `safe_upgrade`), `DestructiveMigrationError`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks`, `SlowQueryLogger`, `BaseOutboxModel`, `OutboxRelay`, `OutboxStatus`, `BaseRepository.save_with_outbox`, audit trail (`BaseAuditLogModel`, `AuditAction`, `snapshot_model`, `diff_snapshots`, `BaseRepository.add_audited` / `update_audited` / `delete_audited`), `BaseWebPushSubscriptionModel` + `make_web_push_subscription_model` |
 | `tempest_fastapi_sdk.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException`, i18n (`MessageCatalog`, `default_message_catalog`, `parse_accept_language`, `DEFAULT_LOCALE`) |
 | `tempest_fastapi_sdk.settings` | `BaseAppSettings`, `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
 | `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware` (+ `RateLimitStore`/`MemoryRateLimitStore`/`RedisRateLimitStore`/`RateLimitResult` and `key_by_ip`/`key_by_jwt_subject`/`key_by_jwt_claim`/`key_by_header`), `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `GracefulShutdownMiddleware`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck`, `setup_tracing` *(extra: `[otel]`)* |
@@ -253,7 +253,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.sse` | `EventStream`, `ServerSentEvent`, `sse_response` |
 | `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`, `WebPushError`, `WebPushGoneError`, `WebPushSubscriptionSchema`, `WebPushKeysSchema`, `WebPushPayloadSchema` |
+| `tempest_fastapi_sdk.webpush` *(extra: `[webpush]`)* | `WebPushDispatcher`, `WebPushSubscriptionService`, `WebPushError`, `WebPushGoneError`, `WebPushSubscriptionSchema`, `WebPushKeysSchema`, `WebPushPayloadSchema` |
 | `tempest_fastapi_sdk.queue` *(extra: `[queue]`)* | `AsyncBrokerManager` (FastStream lifecycle wrapper) |
 | `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 |
@@ -2126,7 +2126,7 @@ Each mixin owns its own env-var prefix — pick only the ones the service needs:
 
 `BaseService[RepositoryT, ResponseT]` and `BaseController[ServiceT, ResponseT]` are generic skeletons matching the SDK layering (router → controller → service → repository). They expose pass-through CRUD methods so simple endpoints can subclass them without overriding anything; you override only methods that need orchestration.
 
-What you inherit by subclassing `BaseService[RepositoryT, ResponseT]`:
+`BaseService[RepositoryT, ResponseT]` accepts an optional third type argument — `BaseService[RepositoryT, ResponseT, UpdateT]` — that types the `update` payload (defaults to `BaseSchema`, so the two-argument form keeps working). What you inherit by subclassing it:
 
 | Method | Returns | Notes |
 | --- | --- | --- |
@@ -2136,7 +2136,7 @@ What you inherit by subclassing `BaseService[RepositoryT, ResponseT]`:
 | `paginate(filters=None, order_by=None, page=1, page_size=20, ascending=True)` | `dict` with mapped `items` + `total`/`page`/`size`/`pages`. | Offset pagination via `repository.paginate`. |
 | `count(filters=None)` | `int` | Pass-through to `repository.count`. |
 | `exists(filters)` | `bool` | Pass-through to `repository.exists`. |
-| `update(id, data)` | `ResponseT` | Fetch by id, copy the fields present in `data` (a `BaseSchema`) onto the row, persist, map. `to_dict()` drops unset/`None`, so it serves PUT and PATCH alike. |
+| `update(id, data)` | `ResponseT` | Fetch by id, copy the fields present in `data` (typed `UpdateT`, the optional 3rd generic param — defaults to `BaseSchema`) onto the row, persist, map. `to_dict()` drops unset/`None`, so it serves PUT and PATCH alike. |
 | `delete(id)` | `None` | Hard delete via `repository.delete`. |
 
 `map_to_response` is `await`-ed when it returns a coroutine, so async mappers work transparently — no method override needed.
@@ -2149,7 +2149,7 @@ What you inherit by subclassing `BaseController[ServiceT, ResponseT]`:
 | `list(filters, order_by, ascending)` | `service.list` | Same. |
 | `paginate(filters, order_by, page, page_size, ascending)` | `service.paginate` | Same. |
 | `count(filters)` | `service.count` | Same. |
-| `update(id, data)` | `service.update` | Same. |
+| `update(id, data)` | `service.update` | `data` typed by the optional 3rd generic param `UpdateT` (defaults to `BaseSchema`). |
 | `delete(id)` | `service.delete` | Same. |
 
 When a use case needs domain rules, override the inherited method in the service. When a use case needs to coordinate more than one service, override the inherited method (or add a new one) in the controller. The router never grows — it only depends on the controller.

{tempest_fastapi_sdk-0.78.0 → tempest_fastapi_sdk-0.80.0}/README.md

@@ -107,7 +107,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[email]` | `aiosmtplib`, `jinja2` | `EmailUtils` + `render_template()` |
 | `[upload]` | `aiofiles`, `python-multipart` | `UploadUtils`, `LocalUploadStorage`, `MinIOUploadStorage` (when combined with `[minio]`) |
 | `[cache]` | `redis` | `AsyncRedisManager` |
-| `[webpush]` | `pywebpush`, `cryptography` | `WebPushDispatcher` |
+| `[webpush]` | `pywebpush`, `cryptography` | `WebPushDispatcher`, `WebPushSubscriptionService`, `BaseWebPushSubscriptionModel` |
 | `[metrics]` | `psutil`, `nvidia-ml-py` | `MetricsUtils` |
 | `[queue]` | `faststream[rabbit]` | `AsyncBrokerManager` (FastStream) |
 | `[tasks]` | `taskiq`, `taskiq-aio-pika` | `AsyncTaskBrokerManager` (TaskIQ) |
@@ -138,7 +138,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | Module | Exports |
 | --- | --- |
 | `tempest_fastapi_sdk.schemas` | `BaseSchema`, `BaseResponseSchema`, `BasePaginationFilterSchema`, `BasePaginationSchema[T]`, `CursorPaginationFilterSchema`, `CursorPaginationSchema`, `LogEntrySchema`, `encode_cursor`, `decode_cursor`, `build_pagination_link_header` |
-| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `TenantScopedRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper` (+ `safe_upgrade`), `DestructiveMigrationError`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks`, `SlowQueryLogger`, `BaseOutboxModel`, `OutboxRelay`, `OutboxStatus`, `BaseRepository.save_with_outbox`, audit trail (`BaseAuditLogModel`, `AuditAction`, `snapshot_model`, `diff_snapshots`, `BaseRepository.add_audited` / `update_audited` / `delete_audited`) |
+| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `TenantScopedRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper` (+ `safe_upgrade`), `DestructiveMigrationError`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks`, `SlowQueryLogger`, `BaseOutboxModel`, `OutboxRelay`, `OutboxStatus`, `BaseRepository.save_with_outbox`, audit trail (`BaseAuditLogModel`, `AuditAction`, `snapshot_model`, `diff_snapshots`, `BaseRepository.add_audited` / `update_audited` / `delete_audited`), `BaseWebPushSubscriptionModel` + `make_web_push_subscription_model` |
 | `tempest_fastapi_sdk.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException`, i18n (`MessageCatalog`, `default_message_catalog`, `parse_accept_language`, `DEFAULT_LOCALE`) |
 | `tempest_fastapi_sdk.settings` | `BaseAppSettings`, `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
 | `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware` (+ `RateLimitStore`/`MemoryRateLimitStore`/`RedisRateLimitStore`/`RateLimitResult` and `key_by_ip`/`key_by_jwt_subject`/`key_by_jwt_claim`/`key_by_header`), `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `GracefulShutdownMiddleware`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck`, `setup_tracing` *(extra: `[otel]`)* |
@@ -150,7 +150,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.sse` | `EventStream`, `ServerSentEvent`, `sse_response` |
 | `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`, `WebPushError`, `WebPushGoneError`, `WebPushSubscriptionSchema`, `WebPushKeysSchema`, `WebPushPayloadSchema` |
+| `tempest_fastapi_sdk.webpush` *(extra: `[webpush]`)* | `WebPushDispatcher`, `WebPushSubscriptionService`, `WebPushError`, `WebPushGoneError`, `WebPushSubscriptionSchema`, `WebPushKeysSchema`, `WebPushPayloadSchema` |
 | `tempest_fastapi_sdk.queue` *(extra: `[queue]`)* | `AsyncBrokerManager` (FastStream lifecycle wrapper) |
 | `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 |
@@ -2023,7 +2023,7 @@ Each mixin owns its own env-var prefix — pick only the ones the service needs:
 
 `BaseService[RepositoryT, ResponseT]` and `BaseController[ServiceT, ResponseT]` are generic skeletons matching the SDK layering (router → controller → service → repository). They expose pass-through CRUD methods so simple endpoints can subclass them without overriding anything; you override only methods that need orchestration.
 
-What you inherit by subclassing `BaseService[RepositoryT, ResponseT]`:
+`BaseService[RepositoryT, ResponseT]` accepts an optional third type argument — `BaseService[RepositoryT, ResponseT, UpdateT]` — that types the `update` payload (defaults to `BaseSchema`, so the two-argument form keeps working). What you inherit by subclassing it:
 
 | Method | Returns | Notes |
 | --- | --- | --- |
@@ -2033,7 +2033,7 @@ What you inherit by subclassing `BaseService[RepositoryT, ResponseT]`:
 | `paginate(filters=None, order_by=None, page=1, page_size=20, ascending=True)` | `dict` with mapped `items` + `total`/`page`/`size`/`pages`. | Offset pagination via `repository.paginate`. |
 | `count(filters=None)` | `int` | Pass-through to `repository.count`. |
 | `exists(filters)` | `bool` | Pass-through to `repository.exists`. |
-| `update(id, data)` | `ResponseT` | Fetch by id, copy the fields present in `data` (a `BaseSchema`) onto the row, persist, map. `to_dict()` drops unset/`None`, so it serves PUT and PATCH alike. |
+| `update(id, data)` | `ResponseT` | Fetch by id, copy the fields present in `data` (typed `UpdateT`, the optional 3rd generic param — defaults to `BaseSchema`) onto the row, persist, map. `to_dict()` drops unset/`None`, so it serves PUT and PATCH alike. |
 | `delete(id)` | `None` | Hard delete via `repository.delete`. |
 
 `map_to_response` is `await`-ed when it returns a coroutine, so async mappers work transparently — no method override needed.
@@ -2046,7 +2046,7 @@ What you inherit by subclassing `BaseController[ServiceT, ResponseT]`:
 | `list(filters, order_by, ascending)` | `service.list` | Same. |
 | `paginate(filters, order_by, page, page_size, ascending)` | `service.paginate` | Same. |
 | `count(filters)` | `service.count` | Same. |
-| `update(id, data)` | `service.update` | Same. |
+| `update(id, data)` | `service.update` | `data` typed by the optional 3rd generic param `UpdateT` (defaults to `BaseSchema`). |
 | `delete(id)` | `service.delete` | Same. |
 
 When a use case needs domain rules, override the inherited method in the service. When a use case needs to coordinate more than one service, override the inherited method (or add a new one) in the controller. The router never grows — it only depends on the controller.

{tempest_fastapi_sdk-0.78.0 → tempest_fastapi_sdk-0.80.0}/docs/architecture.en.md

@@ -147,7 +147,7 @@ What you inherit by subclassing `BaseService[RepositoryT, ResponseT]`:
 | `paginate(filters=None, order_by=None, page=1, page_size=20, ascending=True)` | `dict` with mapped `items` + `total`/`page`/`page_size`/`pages`. | Offset pagination via `repository.paginate`. |
 | `count(filters=None)` | `int` | Pass-through to `repository.count`. |
 | `exists(filters)` | `bool` | Pass-through to `repository.exists`. |
-| `update(id, data)` | `ResponseT` | Fetch by id, copy the fields present in `data` (a `BaseSchema`) onto the row, persist, map. `to_dict()` drops unset/`None`, so it serves PUT and PATCH. |
+| `update(id, data)` | `ResponseT` | Fetch by id, copy the fields present in `data` (typed by `UpdateT`, the optional 3rd generic param — defaults to `BaseSchema`) onto the row, persist, map. `to_dict()` drops unset/`None`, so it serves PUT and PATCH. |
 | `delete(id)` | `None` | Hard delete via `repository.delete`. |
 
 `map_to_response` is `await`-ed when it returns a coroutine, so async mappers work transparently — no method override needed.

{tempest_fastapi_sdk-0.78.0 → tempest_fastapi_sdk-0.80.0}/docs/architecture.md

@@ -147,7 +147,7 @@ O que você herda ao subclassear `BaseService[RepositoryT, ResponseT]`:
 | `paginate(filters=None, order_by=None, page=1, page_size=20, ascending=True)` | `dict` com `items` mapeados + `total`/`page`/`page_size`/`pages`. | Paginação por offset via `repository.paginate`. |
 | `count(filters=None)` | `int` | Pass-through para `repository.count`. |
 | `exists(filters)` | `bool` | Pass-through para `repository.exists`. |
-| `update(id, data)` | `ResponseT` | Busca por id, copia os campos presentes em `data` (um `BaseSchema`) na instância, persiste e mapeia. `to_dict()` descarta unset/`None`, então serve PUT e PATCH. |
+| `update(id, data)` | `ResponseT` | Busca por id, copia os campos presentes em `data` (tipado por `UpdateT`, o 3º parâmetro genérico opcional — default `BaseSchema`) na instância, persiste e mapeia. `to_dict()` descarta unset/`None`, então serve PUT e PATCH. |
 | `delete(id)` | `None` | Hard delete via `repository.delete`. |
 
 `map_to_response` é aguardado com `await` quando retorna uma coroutine, então mappers async funcionam de forma transparente — sem precisar sobrescrever o método.

tempest_fastapi_sdk-0.80.0/docs/recipes/webpush.en.md

@@ -0,0 +1,189 @@
+# Web Push
+
+VAPID-signed Web Push notifications to browsers via `WebPushDispatcher`.
+It wraps the synchronous `pywebpush` library in `asyncio.to_thread` and
+surfaces the two errors the application actually handles:
+`WebPushGoneError` (HTTP 404/410 — delete the subscription) and
+`WebPushError` (any other failure). Requires the `[webpush]` extra
+(`pywebpush` + `cryptography`).
+
+## VAPID configuration
+
+`WebPushSettings` ships `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`, and
+`VAPID_SUBJECT`. The **public** key goes to the frontend (in
+`pushManager.subscribe`); the **private** key signs each push on the
+backend. The `sub` must be a `mailto:` or `https:` URI.
+
+```python
+# src/services/notifications.py
+from tempest_fastapi_sdk import WebPushDispatcher
+
+from src.core.settings import settings
+
+
+# settings.webpush_kwargs() -> vapid_private_key + vapid_subject + ttl_seconds
+dispatcher = WebPushDispatcher(**settings.webpush_kwargs())
+```
+
+## Table + service (recommended)
+
+To store the user's devices and deliver with automatic pruning, the SDK
+ships the **base table** `BaseWebPushSubscriptionModel` (one row per
+device, unique `endpoint`) and the **base service**
+`WebPushSubscriptionService` (saves, removes and sends, pruning dead ones
+itself). Like the auth pattern, the SDK provides the abstract row and the
+project creates the concrete table with the FK to its `UserModel`:
+
+```python
+# src/db/models/web_push_subscription.py
+from sqlalchemy import ForeignKey
+from sqlalchemy.orm import Mapped, mapped_column
+from uuid import UUID
+
+from tempest_fastapi_sdk import BaseWebPushSubscriptionModel
+
+
+class WebPushSubscriptionModel(BaseWebPushSubscriptionModel):
+    """A user device's Web Push subscription."""
+
+    __tablename__ = "web_push_subscriptions"
+
+    user_id: Mapped[UUID] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+```
+
+Build the service from a `BaseRepository` over the table + the VAPID
+dispatcher:
+
+```python
+# src/api/dependencies/resources.py
+from tempest_fastapi_sdk import BaseRepository, WebPushSubscriptionService
+
+from src.core.settings import settings
+from src.db.models import WebPushSubscriptionModel
+
+
+def get_push_service(session: AsyncSession) -> WebPushSubscriptionService:
+    repo = BaseRepository(session, model=WebPushSubscriptionModel)
+    dispatcher = WebPushDispatcher(**settings.webpush_kwargs())
+    return WebPushSubscriptionService(repo, dispatcher)
+```
+
+The service exposes:
+
+| Method | What it does |
+| --- | --- |
+| `subscribe(user_id, subscription, *, user_agent=None)` | Persist the subscription, **idempotent by `endpoint`** — re-subscribe updates, never duplicates. |
+| `unsubscribe(endpoint)` | Remove the subscription (no-op when absent). |
+| `list_for_user(user_id)` | List the user's devices. |
+| `notify_user(user_id, payload)` | Send to every device and **prune the dead ones** (404/410) before returning. Returns how many received it. |
+
+## Aligned with tempest-react-sdk
+
+`tempest-react-sdk`'s [`WebPushClient`](https://github.com/mauriciobenjamin700/tempest-react-sdk)
+calls `onSubscribe(subscription)` / `onUnsubscribe(subscription)` with the
+raw `PushSubscription.toJSON()`. That JSON *is* the
+`WebPushSubscriptionSchema` (it aliases `expiration_time` ↔
+`expirationTime`), so the frontend hits these endpoints directly:
+
+```python
+# src/api/routers/push.py
+from fastapi import APIRouter, Depends, status
+
+from tempest_fastapi_sdk import WebPushSubscriptionSchema, WebPushSubscriptionService
+
+router = APIRouter(prefix="/api/push", tags=["push"])
+
+
+@router.post("/subscribe", status_code=status.HTTP_201_CREATED)
+async def subscribe(
+    subscription: WebPushSubscriptionSchema,
+    user: CurrentUser,                       # your auth dependency
+    service: WebPushSubscriptionService = Depends(get_push_service),
+) -> dict[str, str]:
+    """Receive the WebPushClient onSubscribe and persist the device."""
+    await service.subscribe(user.id, subscription)
+    return {"status": "subscribed"}
+
+
+@router.post("/unsubscribe", status_code=status.HTTP_200_OK)
+async def unsubscribe(
+    subscription: WebPushSubscriptionSchema,
+    service: WebPushSubscriptionService = Depends(get_push_service),
+) -> dict[str, str]:
+    """Receive the onUnsubscribe and remove the device."""
+    await service.unsubscribe(subscription.endpoint)
+    return {"status": "unsubscribed"}
+```
+
+Notify a user (all devices, automatic pruning built in):
+
+```python
+delivered: int = await service.notify_user(
+    user.id,
+    {"title": "Payment confirmed", "body": "Order approved."},
+)
+```
+
+## Send a notification (dispatcher directly)
+
+The `payload` accepts `WebPushPayloadSchema`, `dict`, `str`, or `bytes`
+(models and dicts are JSON-encoded). Handle `WebPushGoneError` to prune
+the dead subscription from your store.
+
+```python
+from tempest_fastapi_sdk import (
+    WebPushGoneError,
+    WebPushPayloadSchema,
+    WebPushSubscriptionSchema,
+)
+
+
+async def notify_order_paid(
+    subscription: WebPushSubscriptionSchema,
+    order_id: str,
+) -> None:
+    payload = WebPushPayloadSchema(
+        title="Payment confirmed",
+        body=f"Order {order_id} approved.",
+        icon="/static/icons/order.png",
+        data={"orderId": order_id, "url": f"/orders/{order_id}"},
+    )
+    try:
+        await dispatcher.send(subscription, payload)
+    except WebPushGoneError:
+        await subscriptions_repo.delete_by_endpoint(subscription.endpoint)
+```
+
+## Broadcast with automatic pruning
+
+`send_many()` fans out the same payload concurrently (`asyncio.gather`)
+and **returns the dead endpoints** (404/410) for you to remove — other
+failures are logged, not raised.
+
+```python
+async def broadcast(
+    subs: list[WebPushSubscriptionSchema],
+    payload: WebPushPayloadSchema,
+) -> None:
+    gone: list[str] = await dispatcher.send_many(subs, payload)
+    if gone:
+        await subscriptions_repo.delete_by_endpoints(gone)
+```
+
+!!! warning "Always prune dead subscriptions"
+    Subscriptions expire when the user changes device or revokes the
+    permission. Ignoring `WebPushGoneError` / the `send_many` return value
+    piles up zombie endpoints and wastes dispatch. Delete them as soon as
+    the push service answers 404/410.
+
+## Recap
+
+- Install `[webpush]` and configure `WebPushSettings` (VAPID keys).
+- Public key → frontend; private key → signs the pushes on the backend.
+- `BaseWebPushSubscriptionModel` table (one row per device, unique `endpoint`) + `WebPushSubscriptionService` (`subscribe`/`unsubscribe`/`notify_user`) — the recommended path, with automatic pruning.
+- The `WebPushClient` JSON (tempest-react-sdk) *is* the `WebPushSubscriptionSchema` — `subscribe`/`unsubscribe` map directly.
+- Low-level path: `send()` for one target, `send_many()` for broadcast (returns the dead ones); handle `WebPushGoneError` (404/410) by pruning the store.

tempest_fastapi_sdk-0.80.0/docs/recipes/webpush.md

@@ -0,0 +1,188 @@
+# Web Push
+
+Notificações Web Push (assinadas com VAPID) para navegadores via
+`WebPushDispatcher`. Embrulha o `pywebpush` síncrono em
+`asyncio.to_thread` e expõe os dois erros que a aplicação realmente
+trata: `WebPushGoneError` (HTTP 404/410 — apague a inscrição) e
+`WebPushError` (qualquer outra falha). Requer o extra `[webpush]`
+(`pywebpush` + `cryptography`).
+
+## Configuração VAPID
+
+`WebPushSettings` traz `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY` e
+`VAPID_SUBJECT`. A chave **pública** vai para o frontend (no
+`pushManager.subscribe`); a **privada** assina cada push no backend. O
+`sub` deve ser um URI `mailto:` ou `https:`.
+
+```python
+# src/services/notifications.py
+from tempest_fastapi_sdk import WebPushDispatcher
+
+from src.core.settings import settings
+
+
+# settings.webpush_kwargs() -> vapid_private_key + vapid_subject + ttl_seconds
+dispatcher = WebPushDispatcher(**settings.webpush_kwargs())
+```
+
+## Tabela + serviço (recomendado)
+
+Para guardar os aparelhos do usuário e entregar com poda automática, o
+SDK traz a **tabela base** `BaseWebPushSubscriptionModel` (uma linha por
+device, `endpoint` único) e o **serviço base** `WebPushSubscriptionService`
+(salva, remove e envia, podando as mortas sozinho). Igual ao padrão de
+auth, o SDK fornece a linha abstrata e o projeto cria a tabela concreta
+com a FK pro seu `UserModel`:
+
+```python
+# src/db/models/web_push_subscription.py
+from sqlalchemy import ForeignKey
+from sqlalchemy.orm import Mapped, mapped_column
+from uuid import UUID
+
+from tempest_fastapi_sdk import BaseWebPushSubscriptionModel
+
+
+class WebPushSubscriptionModel(BaseWebPushSubscriptionModel):
+    """Inscrição Web Push de um device do usuário."""
+
+    __tablename__ = "web_push_subscriptions"
+
+    user_id: Mapped[UUID] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+```
+
+Monte o serviço com um `BaseRepository` da tabela + o dispatcher VAPID:
+
+```python
+# src/api/dependencies/resources.py
+from tempest_fastapi_sdk import BaseRepository, WebPushSubscriptionService
+
+from src.core.settings import settings
+from src.db.models import WebPushSubscriptionModel
+
+
+def get_push_service(session: AsyncSession) -> WebPushSubscriptionService:
+    repo = BaseRepository(session, model=WebPushSubscriptionModel)
+    dispatcher = WebPushDispatcher(**settings.webpush_kwargs())
+    return WebPushSubscriptionService(repo, dispatcher)
+```
+
+O serviço expõe:
+
+| Método | O que faz |
+| --- | --- |
+| `subscribe(user_id, subscription, *, user_agent=None)` | Salva a inscrição, **idempotente por `endpoint`** — re-subscribe atualiza, não duplica. |
+| `unsubscribe(endpoint)` | Remove a inscrição (no-op se não existe). |
+| `list_for_user(user_id)` | Lista os devices do usuário. |
+| `notify_user(user_id, payload)` | Envia pra todos os devices e **poda os mortos** (404/410) antes de retornar. Devolve quantos receberam. |
+
+## Alinhado com o tempest-react-sdk
+
+O `WebPushClient` do [`tempest-react-sdk`](https://github.com/mauriciobenjamin700/tempest-react-sdk)
+chama `onSubscribe(subscription)` e `onUnsubscribe(subscription)` com o
+`PushSubscription.toJSON()` cru. Esse JSON é exatamente o
+`WebPushSubscriptionSchema` (aliasa `expiration_time` ↔ `expirationTime`),
+então o front bate direto nos endpoints abaixo:
+
+```python
+# src/api/routers/push.py
+from fastapi import APIRouter, Depends, status
+
+from tempest_fastapi_sdk import WebPushSubscriptionSchema, WebPushSubscriptionService
+
+router = APIRouter(prefix="/api/push", tags=["push"])
+
+
+@router.post("/subscribe", status_code=status.HTTP_201_CREATED)
+async def subscribe(
+    subscription: WebPushSubscriptionSchema,
+    user: CurrentUser,                       # sua dependency de auth
+    service: WebPushSubscriptionService = Depends(get_push_service),
+) -> dict[str, str]:
+    """Recebe o onSubscribe do WebPushClient e persiste o device."""
+    await service.subscribe(user.id, subscription)
+    return {"status": "subscribed"}
+
+
+@router.post("/unsubscribe", status_code=status.HTTP_200_OK)
+async def unsubscribe(
+    subscription: WebPushSubscriptionSchema,
+    service: WebPushSubscriptionService = Depends(get_push_service),
+) -> dict[str, str]:
+    """Recebe o onUnsubscribe e remove o device."""
+    await service.unsubscribe(subscription.endpoint)
+    return {"status": "unsubscribed"}
+```
+
+Enviar pra um usuário (todos os devices, poda automática embutida):
+
+```python
+delivered: int = await service.notify_user(
+    user.id,
+    {"title": "Pagamento confirmado", "body": "Pedido aprovado."},
+)
+```
+
+## Enviar uma notificação (dispatcher direto)
+
+O `payload` aceita `WebPushPayloadSchema`, `dict`, `str` ou `bytes`
+(models e dicts viram JSON). Trate `WebPushGoneError` para podar a
+inscrição morta do seu store.
+
+```python
+from tempest_fastapi_sdk import (
+    WebPushGoneError,
+    WebPushPayloadSchema,
+    WebPushSubscriptionSchema,
+)
+
+
+async def notify_order_paid(
+    subscription: WebPushSubscriptionSchema,
+    order_id: str,
+) -> None:
+    payload = WebPushPayloadSchema(
+        title="Pagamento confirmado",
+        body=f"Pedido {order_id} aprovado.",
+        icon="/static/icons/order.png",
+        data={"orderId": order_id, "url": f"/orders/{order_id}"},
+    )
+    try:
+        await dispatcher.send(subscription, payload)
+    except WebPushGoneError:
+        await subscriptions_repo.delete_by_endpoint(subscription.endpoint)
+```
+
+## Broadcast com poda automática
+
+`send_many()` dispara o mesmo payload concorrentemente
+(`asyncio.gather`) e **retorna os endpoints mortos** (404/410) para você
+remover — outras falhas são logadas, não levantadas.
+
+```python
+async def broadcast(
+    subs: list[WebPushSubscriptionSchema],
+    payload: WebPushPayloadSchema,
+) -> None:
+    gone: list[str] = await dispatcher.send_many(subs, payload)
+    if gone:
+        await subscriptions_repo.delete_by_endpoints(gone)
+```
+
+!!! warning "Sempre pode as inscrições mortas"
+    Inscrições expiram quando o usuário troca de device ou revoga a
+    permissão. Ignorar `WebPushGoneError` / o retorno do `send_many`
+    acumula endpoints zumbis e desperdiça dispatch. Apague-os assim que
+    o push service responder 404/410.
+
+## Recap
+
+- Instale `[webpush]` e configure `WebPushSettings` (chaves VAPID).
+- Chave pública → frontend; privada → assina os pushes no backend.
+- Tabela `BaseWebPushSubscriptionModel` (1 linha por device, `endpoint` único) + `WebPushSubscriptionService` (`subscribe`/`unsubscribe`/`notify_user`) — o caminho recomendado, com poda automática.
+- O JSON do `WebPushClient` (tempest-react-sdk) é o próprio `WebPushSubscriptionSchema` — `subscribe`/`unsubscribe` batem direto.
+- Caminho baixo nível: `send()` para um destino, `send_many()` para broadcast (retorna mortos); trate `WebPushGoneError` (404/410) podando o store.

{tempest_fastapi_sdk-0.78.0 → tempest_fastapi_sdk-0.80.0}/docs/reference.md

@@ -252,6 +252,8 @@ Gerada automaticamente a partir das docstrings do SDK via [`mkdocstrings`](https
 ### `tempest_fastapi_sdk.webpush`
 
 ::: tempest_fastapi_sdk.webpush.dispatcher.WebPushDispatcher
+::: tempest_fastapi_sdk.webpush.service.WebPushSubscriptionService
+::: tempest_fastapi_sdk.db.webpush_subscription_model.BaseWebPushSubscriptionModel
 ::: tempest_fastapi_sdk.webpush.schemas.WebPushSubscriptionSchema
 ::: tempest_fastapi_sdk.webpush.schemas.WebPushPayloadSchema
 

{tempest_fastapi_sdk-0.78.0 → tempest_fastapi_sdk-0.80.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.78.0"
+version = "0.80.0"
 description = "Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects."
 readme = "README.md"
 requires-python = ">=3.11"

{tempest_fastapi_sdk-0.78.0 → tempest_fastapi_sdk-0.80.0}/tempest_fastapi_sdk/__init__.py

@@ -133,6 +133,7 @@ from tempest_fastapi_sdk.db import (
     BaseUserRecoveryCodeModel,
     BaseUserRefreshTokenModel,
     BaseUserTokenModel,
+    BaseWebPushSubscriptionModel,
     DatabaseBackup,
     DestructiveMigrationError,
     MFAMixin,
@@ -149,6 +150,7 @@ from tempest_fastapi_sdk.db import (
     make_user_recovery_code_model,
     make_user_refresh_token_model,
     make_user_token_model,
+    make_web_push_subscription_model,
     reorder_base_columns_first,
     snapshot_model,
 )
@@ -334,6 +336,7 @@ from tempest_fastapi_sdk.webpush import (
     WebPushKeysSchema,
     WebPushPayloadSchema,
     WebPushSubscriptionSchema,
+    WebPushSubscriptionService,
 )
 from tempest_fastapi_sdk.websockets import (
     WebSocketConnection,
@@ -342,7 +345,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
 
-__version__: str = "0.78.0"
+__version__: str = "0.80.0"
 
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",
@@ -398,6 +401,7 @@ __all__: list[str] = [
     "BaseUserRecoveryCodeModel",
     "BaseUserRefreshTokenModel",
     "BaseUserTokenModel",
+    "BaseWebPushSubscriptionModel",
     "BodySizeLimitMiddleware",
     "CEPField",
     "CNPJField",
@@ -561,6 +565,7 @@ __all__: list[str] = [
     "WebPushPayloadSchema",
     "WebPushSettings",
     "WebPushSubscriptionSchema",
+    "WebPushSubscriptionService",
     "WebSocketConnection",
     "WebSocketHub",
     "WebSocketSettings",
@@ -626,6 +631,7 @@ __all__: list[str] = [
     "make_user_recovery_code_model",
     "make_user_refresh_token_model",
     "make_user_token_model",
+    "make_web_push_subscription_model",
     "make_websocket_router",
     "modify_dict",
     "negotiate_locale",