core-framework 4.2.1__tar.gz → 4.3.0__tar.gz

{core_framework-4.2.1 → core_framework-4.3.0}/.cursor/rules/application-layer.mdc

@@ -17,10 +17,14 @@ Application services orchestrate use cases shared by API and workers. They stay
 ## Outcomes
 
 - Return plain Python/domain values: `dict`, `list[dict]`, dataclasses, primitives, `None`, or empty collections.
-- Do not return API/Pydantic `BaseModel` instances.
+- Do not return API/Pydantic `BaseModel` instances. Pydantic stays in `core_framework/api/`.
 - Signal HTTP-meaningful failures with **`application.shared.exceptions`** or plain outcomes (`None`, empty), never typed domain exceptions. Full boundary contract: **`error-boundary.mdc`**.
 
-Use a domain dataclass when one domain row matches the response shape; use a `dict` when the payload is composed from several sources.
+A fixed set of fields that crosses a layer is a dataclass: a domain row, an outcome, or a `*Update` body. Partial writes take that `*Update` type. See `docs/platform/patch-update-typed-payload.md`.
+
+- Return a domain dataclass when one domain row matches the result.
+- Return a `dict` when the value is a mapping: a payload assembled from several sources, an id-to-row lookup, or an open bag (outbox payload, action metadata).
+- Job and worker arguments stay JSON-friendly primitives: strings, numbers, booleans, `None`, lists, and dicts.
 
 ## Function shape
 

{core_framework-4.2.1 → core_framework-4.3.0}/.cursor/rules/domain-services-and-adapters.mdc

@@ -21,6 +21,12 @@ See **`docs/platform/domain-services-and-adapters.md`** for the full model. Appl
 - **Repositories** remain **Postgres-only** (SQL in repository + row mapping).
 - **Non-SQL I/O** uses **ports**, **components**, and **adapters**—not `*Repository`.
 
+## Records and mappings
+
+- Domain rows, outcomes, and `*Update` bodies are dataclasses. Partial writes take `*Update`; column assignments come from `iter_column_updates()`. See `docs/platform/patch-update-typed-payload.md`.
+- A `dict` in the domain is a mapping: an id-to-row lookup, or an open bag such as an outbox payload or action metadata.
+- Composed application return values and job arguments: **`application-layer.mdc`**.
+
 ## Multiple services per domain
 
 - Facade **`*Service`** is wired in `dependencies`; internal **`*Component`** classes wrap ports.

{core_framework-4.2.1 → core_framework-4.3.0}/.cursor/rules/strong-reads.mdc

@@ -12,6 +12,7 @@ globs:
 ## Policy
 
 - **Read-after-write** in the same HTTP request or worker job → **strong** read (required). Refetch with `strong_read_database`, `*_strong` repository methods, or service accessors that call them.
+- A **later request** after a create uses a **normal** read. Trust the replica to catch up. A miss or a stale row in that window is accepted. Do not strong-read that request only because an earlier request created the row. See **`docs/platform/architecture-decisions.md`** → *A later request after create uses the replica (Accepted)*.
 - **Decision-critical guards** where stale data can cause incorrect branching → **strong** read (required). These are reads performed to decide a branch (for example pre-write existence, role, or state checks that determine whether a write runs or which outcome is returned), even when there is no immediate prior write in the flow. See the "Read Consistency (Strong vs Normal Reads)" ADR.
 - **Accepted exception:** **`check_caller_identity`** / **`check_not_banned`** (alias) / **`get_user_detail`** (`USER_DETAIL_V2` cache + normal reads) — ban, deleted-user, and account-removal-in-progress visibility are eventually consistent by design. The removal-started fence rides that cache; do not strong-read it on every gated request. See **`docs/platform/architecture-decisions.md`** → *Ban / identity gate via cached `USER_DETAIL` is eventually consistent*. Do not flag as a strong-read defect unless that ADR is updated.
 - **Accepted exception:** account-removal media **owner listing** of avatar/banner/attachment staging-registry rows uses the **read replica**. Replica lag or swallowed per-blob staging deletes can leave orphan staging after a successful spine. See **`docs/platform/architecture-decisions.md`** → *Account-removal staging leftovers (Accepted)*. Do not flag as a must-succeed or strong-read defect unless that ADR is updated.

{core_framework-4.2.1 → core_framework-4.3.0}/.cursor/skills/implement-feature/SKILL.md

@@ -43,6 +43,7 @@ After the user accepts the API layer (or if there was no API layer):
 
 - Implement the **Repository** for the domain layer (Postgres only).
 - Include the **domain model** if data is retrieved from the database.
+- Domain rows, outcomes, and `*Update` bodies are dataclasses. A `dict` in the domain is a mapping or an open bag. Follow **`domain-services-and-adapters`** (records and mappings).
 - If the feature needs non-SQL I/O (filesystem, HTTP, SSH), add **ports** in the domain and **adapter implementations** under `core_framework/infrastructure/<domain>/` per `docs/platform/domain-services-and-adapters.md` — not in the repository.
 - Wait for the user to review and accept before proceeding.
 
@@ -52,6 +53,7 @@ After the user accepts the repository (and any ports/adapters):
 
 - Implement **domain service(s)** (persistence and any port-backed collaborators); wire in `dependencies.py`.
 - Implement the **application** layer (orchestration across domains and transports — no permanent home for raw I/O libraries).
+- Follow **`application-layer`** for dataclass vs `dict`: a fixed field set that crosses a layer is a dataclass; a mapping, a composed payload, or an open bag is a `dict`; job arguments stay JSON-friendly primitives.
 - Wire everything together (replace 501 with real logic).
 - Wait for the user to review and accept before proceeding.
 

{core_framework-4.2.1 → core_framework-4.3.0}/CHANGELOG.md

@@ -4,6 +4,23 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ## [Unreleased]
 
+## [4.3.0] - 2026-10-21
+
+### Added
+
+- **Paid grant with no expiry:** `paid_grants.expires_at` may be null. Null means the grant has no end, and the tier gate treats it as active. When several active items map to one tier and any of them has no expiry, the row's expiry is null. Otherwise the row keeps the latest expiry. The row is deleted when the active list omits that tier.
+- **Standalone tiers:** a one-time hold with a stable string id, outside the numbered ladder. The webhook replace writes it in the same pass as ordered paid rows and deletes it when the active list omits it. The row stores no expiry. After configure, call **`register_standalone_tier`** on the API and the worker. **`require_standalone_tier`** gates a host route on that id. Core ships no such route. **`GET /users/me/entitlements`** adds **`standalone_items`** (always present; empty when the caller holds none). Account removal deletes standalone rows with the other grant rows. Delivery rows stay.
+- **Admin entitlement sync:** `POST /admin/users/{target_user_id}/entitlements/sync` replaces one user's ordered paid rows and standalone rows from RevenueCat. No body. An **admin** calls it. A **moderator** receives **403**. The route stays mounted while entitlements are off and then returns **404** after the identity gate, without calling RevenueCat. A held lock is **409** **Sync in progress**. An unknown entitlement id is **409** **Unknown entitlement**. An unmapped lookup key is **409** **Unmapped entitlement**. A failed fetch is **503**. A successful replace sets that user's cursor to the later of the stored cursor and the fetch start. Complimentary rows stay. There is no moderator-action row and no delivery row.
+- **Login telemetry list:** `GET /users/me/login-history` returns the caller's stored login rows, newest first: **`created_at`**, **`country_code`**, **`client_type`**, **`browser_name`**, and **`os_name`**. Writes stay on `POST /events` with `type: login`.
+
+### Changed
+
+- **Preferences:** an inbox type switch on `PATCH /users/me/preferences` must be a JSON boolean. `1`, `0`, and `null` are **422**. `theme` and `language` still clear with **`null`**.
+
+### Database
+
+- Run **`cf-alembic`** before API and worker start. **entitlement** applies **`8ef1f563ccb4`** (`paid_grants.expires_at` nullable) and **`244cc7430989`** (`standalone_grants`). **user** applies **`d438cfba40c0`** (`idx_user_login_events_user_created_at` on `(user_id, created_at desc, id desc)`).
+
 ## [4.2.1] - 2026-10-10
 
 ### Changed
@@ -819,4 +836,5 @@ First **SemVer-stable** release per **`docs/library/package-api.md`**.
 [4.1.0]: https://github.com/NepNepFFXIV/core-framework/compare/v4.0.1...v4.1.0
 [4.2.0]: https://github.com/NepNepFFXIV/core-framework/compare/v4.1.0...v4.2.0
 [4.2.1]: https://github.com/NepNepFFXIV/core-framework/compare/v4.2.0...v4.2.1
-[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v4.2.1...HEAD
+[4.3.0]: https://github.com/NepNepFFXIV/core-framework/compare/v4.2.1...v4.3.0
+[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v4.3.0...HEAD

{core_framework-4.2.1 → core_framework-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: core-framework
-Version: 4.2.1
+Version: 4.3.0
 Summary: Core framework package (import as core_framework)
 Project-URL: Homepage, https://github.com/NepNepFFXIV/core-framework
 Project-URL: Repository, https://github.com/NepNepFFXIV/core-framework

core_framework-4.3.0/alembic/entitlement/alembic/versions/244cc7430989_entitlement_standalone_grants.py

@@ -0,0 +1,32 @@
+"""create standalone grants
+
+Revision ID: 244cc7430989
+Revises: 8ef1f563ccb4
+Create Date: 2026-10-18 06:26:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "244cc7430989"
+down_revision: str | Sequence[str] | None = "8ef1f563ccb4"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        create table standalone_grants (
+            user_id varchar(128) not null,
+            standalone_id varchar(64) not null,
+            synced_at timestamptz not null,
+            primary key (user_id, standalone_id),
+            constraint standalone_grants_standalone_id_not_blank check (length(trim(standalone_id)) > 0)
+        );
+    """)
+
+
+def downgrade() -> None:
+    op.execute("drop table standalone_grants;")

core_framework-4.3.0/alembic/entitlement/alembic/versions/8ef1f563ccb4_entitlement_paid_grant_nullable_expiry.py

@@ -0,0 +1,30 @@
+"""allow a paid grant to omit expires_at
+
+Revision ID: 8ef1f563ccb4
+Revises: b7ed2400e94e
+Create Date: 2026-10-18 05:50:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "8ef1f563ccb4"
+down_revision: str | Sequence[str] | None = "b7ed2400e94e"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        alter table paid_grants
+            alter column expires_at drop not null;
+    """)
+
+
+def downgrade() -> None:
+    op.execute("""
+        alter table paid_grants
+            alter column expires_at set not null;
+    """)

core_framework-4.3.0/alembic/user/alembic/versions/d438cfba40c0_user_login_events_user_created_at_index.py

@@ -0,0 +1,27 @@
+"""index user login telemetry by user, newest first
+
+Revision ID: d438cfba40c0
+Revises: 089f4398f943
+Create Date: 2026-10-13 05:44:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "d438cfba40c0"
+down_revision: str | Sequence[str] | None = "089f4398f943"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        create index if not exists idx_user_login_events_user_created_at
+            on user_login_events (user_id, created_at desc, id desc);
+    """)
+
+
+def downgrade() -> None:
+    op.execute("drop index if exists idx_user_login_events_user_created_at;")

core_framework-4.3.0/core_framework/api/admin/entitlements/router.py

@@ -0,0 +1,74 @@
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, HTTPException, Path, status
+
+from core_framework.api.dependencies import RequiredUserID, check_admin_role
+from core_framework.api.entitlements.schemas import (
+    EntitlementItemResponse,
+    EntitlementsResponse,
+    StandaloneEntitlementItemResponse,
+)
+from core_framework.api.users.shared.schemas import validate_user_id
+from core_framework.application.entitlement.grant_service import grant_complimentary_tier, remove_complimentary_tier
+from core_framework.application.entitlement.registry import entitlements_enabled
+from core_framework.application.entitlement.sync_service import sync_user_paid_entitlements
+from core_framework.core.exception_handlers.common import GENERIC_NOT_FOUND_DETAIL
+
+router = APIRouter(
+    prefix="/users",
+    tags=["entitlements - admin"],
+    dependencies=[Depends(check_admin_role)],
+)
+
+
+@router.put("/{target_user_id}/entitlements/{tier_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def put_complimentary_entitlement(
+    actor_id: RequiredUserID,
+    target_user_id: str,
+    tier_id: Annotated[int, Path(ge=1)],
+) -> None:
+    validated_target_user_id = validate_user_id(user_id=target_user_id)
+    await grant_complimentary_tier(
+        actor_id=actor_id,
+        target_user_id=validated_target_user_id,
+        tier_id=tier_id,
+    )
+
+
+@router.delete("/{target_user_id}/entitlements/{tier_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_complimentary_entitlement(
+    actor_id: RequiredUserID,
+    target_user_id: str,
+    tier_id: Annotated[int, Path(ge=1)],
+) -> None:
+    validated_target_user_id = validate_user_id(user_id=target_user_id)
+    await remove_complimentary_tier(
+        actor_id=actor_id,
+        target_user_id=validated_target_user_id,
+        tier_id=tier_id,
+    )
+
+
+@router.post("/{target_user_id}/entitlements/sync", response_model=EntitlementsResponse)
+async def sync_user_entitlements(actor_id: RequiredUserID, target_user_id: str) -> Any:
+    if not entitlements_enabled():
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=GENERIC_NOT_FOUND_DETAIL)
+    validated_target_user_id = validate_user_id(user_id=target_user_id)
+    items, standalone_items = await sync_user_paid_entitlements(
+        actor_id=actor_id,
+        target_user_id=validated_target_user_id,
+    )
+    return EntitlementsResponse(
+        items=[
+            EntitlementItemResponse(tier_id=item.tier_id, identifier=item.identifier, expires_at=item.expires_at)
+            for item in items
+        ],
+        standalone_items=[
+            StandaloneEntitlementItemResponse(
+                standalone_id=item.standalone_id,
+                identifier=item.identifier,
+                expires_at=item.expires_at,
+            )
+            for item in standalone_items
+        ],
+    )

core_framework-4.3.0/core_framework/api/entitlements/dependencies.py

@@ -0,0 +1,44 @@
+from typing import Annotated
+
+from fastapi import Depends
+
+from core_framework.api.dependencies import RequiredUserID, check_caller_identity
+from core_framework.application.entitlement.grant_service import require_caller_standalone_tier, require_caller_tier
+from core_framework.application.entitlement.registry import note_standalone_gate, note_tier_gate
+
+
+def require_tier(tier_id: int):
+    """Route dependency for one tier id. Allows the route while entitlements are off."""
+    if tier_id < 1:
+        raise ValueError("tier_id must be at least 1")
+    note_tier_gate(tier_id)
+
+    async def gate(
+        user_id: RequiredUserID,
+        _: Annotated[None, Depends(check_caller_identity)],
+    ) -> None:
+        del _
+        await require_caller_tier(user_id=user_id, tier_id=tier_id)
+
+    return gate
+
+
+def require_standalone_tier(standalone_id: str):
+    """Route dependency for one standalone id. Allows the route while entitlements are off."""
+    cleaned_id = standalone_id.strip()
+    if not cleaned_id:
+        raise ValueError("standalone tier id must be non-blank")
+    if "\r" in cleaned_id or "\n" in cleaned_id:
+        raise ValueError("standalone tier id must not contain a carriage return or line feed")
+    if len(cleaned_id) > 64:
+        raise ValueError("standalone tier id must be at most 64 characters")
+    note_standalone_gate(cleaned_id)
+
+    async def gate(
+        user_id: RequiredUserID,
+        _: Annotated[None, Depends(check_caller_identity)],
+    ) -> None:
+        del _
+        await require_caller_standalone_tier(user_id=user_id, standalone_id=cleaned_id)
+
+    return gate

{core_framework-4.2.1 → core_framework-4.3.0}/core_framework/api/entitlements/router.py

@@ -3,8 +3,15 @@ from typing import Any
 from fastapi import APIRouter, Depends, Request
 
 from core_framework.api.dependencies import RequiredUserID, check_caller_identity
-from core_framework.api.entitlements.schemas import EntitlementItemResponse, EntitlementsResponse
-from core_framework.application.entitlement.grant_service import list_caller_entitlements
+from core_framework.api.entitlements.schemas import (
+    EntitlementItemResponse,
+    EntitlementsResponse,
+    StandaloneEntitlementItemResponse,
+)
+from core_framework.application.entitlement.grant_service import (
+    list_caller_entitlements,
+    list_caller_standalone_entitlements,
+)
 from core_framework.application.entitlement.webhook_service import handle_revenuecat_webhook
 
 webhook_router = APIRouter(tags=["entitlements"])
@@ -25,9 +32,18 @@ async def post_revenuecat_webhook(request: Request) -> None:
 )
 async def get_my_entitlements(user_id: RequiredUserID) -> Any:
     items = await list_caller_entitlements(user_id=user_id)
+    standalone_items = await list_caller_standalone_entitlements(user_id=user_id)
     return EntitlementsResponse(
         items=[
             EntitlementItemResponse(tier_id=item.tier_id, identifier=item.identifier, expires_at=item.expires_at)
             for item in items
-        ]
+        ],
+        standalone_items=[
+            StandaloneEntitlementItemResponse(
+                standalone_id=item.standalone_id,
+                identifier=item.identifier,
+                expires_at=item.expires_at,
+            )
+            for item in standalone_items
+        ],
     )

{core_framework-4.2.1 → core_framework-4.3.0}/core_framework/api/entitlements/schemas.py

@@ -9,5 +9,12 @@ class EntitlementItemResponse(BaseModel):
     expires_at: datetime | None
 
 
+class StandaloneEntitlementItemResponse(BaseModel):
+    standalone_id: str = Field(min_length=1, max_length=64)
+    identifier: str = Field(min_length=1)
+    expires_at: datetime | None
+
+
 class EntitlementsResponse(BaseModel):
     items: list[EntitlementItemResponse]
+    standalone_items: list[StandaloneEntitlementItemResponse]

{core_framework-4.2.1 → core_framework-4.3.0}/core_framework/api/users/authenticated/router.py

@@ -34,6 +34,7 @@ from core_framework.api.users.authenticated.schemas import (
     BlockedUserResponse,
     FollowUserResponse,
     FriendUserResponse,
+    LoginHistoryItemResponse,
     MyAppealsResponse,
     PreferencesResponse,
     PreferencesUpdateRequest,
@@ -79,6 +80,7 @@ from core_framework.application.users.authenticated_service import (
     retrieve_my_followers,
     retrieve_my_following,
     retrieve_my_friends,
+    retrieve_my_login_telemetry,
     retrieve_my_preferences,
     retrieve_my_profile,
     retrieve_my_username_suggestions,
@@ -93,6 +95,7 @@ from core_framework.application.users.authenticated_service import (
 )
 from core_framework.application.users.user_deletion_service import accept_delete_my_content
 from core_framework.core import RateLimitKey
+from core_framework.core.exceptions import InvalidPageTokenError
 from core_framework.domains.media import (
     AVATAR_INGEST_MAX_BYTES,
     AVATAR_INGEST_UPLOAD_CHUNK_BYTES,
@@ -333,6 +336,37 @@ async def get_my_ratings(
     )
 
 
+@router.get(
+    "/me/login-history",
+    response_model=PaginationResponse[LoginHistoryItemResponse],
+    dependencies=[Depends(check_caller_identity)],
+)
+async def get_my_login_history(
+    request: Request,
+    user_id: RequiredUserID,
+    pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+) -> Any:
+    cursor_id: int | None = None
+    if pagination_params.cursor_string_id is not None:
+        try:
+            cursor_id = int(pagination_params.cursor_string_id)
+        except ValueError:
+            raise InvalidPageTokenError() from None
+        if cursor_id < 1 or cursor_id > 2**63 - 1:
+            raise InvalidPageTokenError()
+    items = await retrieve_my_login_telemetry(
+        user_id=user_id,
+        cursor_created_at=pagination_params.cursor if cursor_id is not None else None,
+        cursor_id=cursor_id,
+        limit=pagination_params.limit,
+    )
+    return paginate_datetime_id_cursor(
+        request=request,
+        items=items,
+        pagination_params=pagination_params,
+    )
+
+
 @router.get(
     "/me/preferences",
     response_model=PreferencesResponse,

{core_framework-4.2.1 → core_framework-4.3.0}/core_framework/api/users/authenticated/schemas.py

@@ -49,6 +49,14 @@ class FriendUserResponse(BaseModel):
     accepted_at: datetime
 
 
+class LoginHistoryItemResponse(BaseModel):
+    created_at: datetime
+    country_code: str | None
+    client_type: str | None
+    browser_name: str | None
+    os_name: str | None
+
+
 class ProfileResponse(AvatarMixin, BannerMixin):
     display_name: DisplayName | None
     bio: Bio | None
@@ -111,6 +119,8 @@ class PreferencesResponse(BaseModel):
     group_invites: bool = True
 
 
+_StrictBool = Annotated[bool, Field(strict=True)]
+
 _SWITCH_FIELDS: Final[frozenset[str]] = frozenset(
     {"comments", "replies", "mentions", "follows", "friend_requests", "group_invites"}
 )
@@ -119,12 +129,12 @@ _SWITCH_FIELDS: Final[frozenset[str]] = frozenset(
 class PreferencesUpdateRequest(BasePatchRequest):
     theme: Theme | None = None
     language: Annotated[str | None, Field(default=None, max_length=10)]
-    comments: bool | None = None
-    replies: bool | None = None
-    mentions: bool | None = None
-    follows: bool | None = None
-    friend_requests: bool | None = None
-    group_invites: bool | None = None
+    comments: _StrictBool | None = None
+    replies: _StrictBool | None = None
+    mentions: _StrictBool | None = None
+    follows: _StrictBool | None = None
+    friend_requests: _StrictBool | None = None
+    group_invites: _StrictBool | None = None
 
     @model_validator(mode="after")
     def reject_null_switches(self) -> PreferencesUpdateRequest:

{core_framework-4.2.1 → core_framework-4.3.0}/core_framework/application/email/registry.py

@@ -78,25 +78,29 @@ def render_entitlement_grant_refused(context: Mapping[str, Any]) -> tuple[str, s
     lookup_key = context.get("lookup_key")
     lookup_line = f"Lookup key: {lookup_key}\n" if lookup_key is not None else ""
     lookup_html = f"<p>Lookup key: {escape(str(lookup_key))}</p>" if lookup_key is not None else ""
-    subject = "Entitlement grant refused"
+    subject = "Entitlement grant refused: ordered tier map or standalone map"
     plain_text_body = (
-        "A paid grant was refused and needs attention.\n\n"
+        "An entitlement grant was refused and needs attention. "
+        "Paid rows and standalone rows were left unchanged.\n\n"
         f"Reason: {reason}\n"
         f"Entitlement id: {entitlement_id}\n"
         f"{lookup_line}"
         f"User id: {user_id}\n"
         f"Event id: {event_id}\n\n"
-        "Fix the tier map or the RevenueCat entitlement, restart the API after an entitlement change, "
+        "Fix the ordered tier map or the standalone map, or the RevenueCat entitlement, "
+        "restart the API after an entitlement change, "
         "and resend this event from the RevenueCat dashboard.\n"
     )
     html_body = (
-        "<p>A paid grant was refused and needs attention.</p>"
+        "<p>An entitlement grant was refused and needs attention. "
+        "Paid rows and standalone rows were left unchanged.</p>"
         f"<p>Reason: {escape(reason)}</p>"
         f"<p>Entitlement id: {escape(entitlement_id)}</p>"
         f"{lookup_html}"
         f"<p>User id: {escape(user_id)}</p>"
         f"<p>Event id: {escape(event_id)}</p>"
-        "<p>Fix the tier map or the RevenueCat entitlement, restart the API after an entitlement change, "
+        "<p>Fix the ordered tier map or the standalone map, or the RevenueCat entitlement, "
+        "restart the API after an entitlement change, "
         "and resend this event from the RevenueCat dashboard.</p>"
     )
     return subject, html_body, plain_text_body

core_framework-4.3.0/core_framework/application/entitlement/core_user.py

@@ -0,0 +1,24 @@
+import asyncpg
+
+import core_framework.domains.user.dependencies as user_deps
+from core_framework.domains.user import RESERVED_USER_IDS, UserIdentity
+
+
+async def is_core_user(*, user_id: str) -> bool:
+    """Return whether this id is a core user whose account removal has not started."""
+    if user_id in RESERVED_USER_IDS:
+        return False
+    identity = await user_deps.user_service.retrieve_user_identity_strong(user_id=user_id)
+    if identity == UserIdentity.DEFAULT:
+        return False
+    return not await user_deps.user_service.retrieve_account_removal_in_progress_strong(user_id=user_id)
+
+
+async def is_core_user_on_connection(*, connection: asyncpg.Connection, user_id: str) -> bool:
+    """Return whether this id is a core user on a primary session already checked out."""
+    if user_id in RESERVED_USER_IDS:
+        return False
+    return await user_deps.user_service.retrieve_user_removal_not_started_on_connection(
+        connection=connection,
+        user_id=user_id,
+    )

{core_framework-4.2.1 → core_framework-4.3.0}/core_framework/application/entitlement/grant_service.py

@@ -3,15 +3,19 @@ from datetime import UTC, datetime
 
 import core_framework.domains.entitlement.dependencies as entitlement_deps
 import core_framework.domains.moderation.dependencies as moderation_deps
-import core_framework.domains.user.dependencies as user_deps
-from core_framework.application.entitlement.registry import entitlements_enabled, tier_identifier, tier_is_registered
+from core_framework.application.entitlement.core_user import is_core_user
+from core_framework.application.entitlement.registry import (
+    entitlements_enabled,
+    standalone_identifier,
+    tier_identifier,
+    tier_is_registered,
+)
 from core_framework.application.shared.exceptions import (
     EntitlementRequiredException,
     UnprocessableEntityException,
     UserNotFoundException,
 )
 from core_framework.domains.moderation import ModerationActionType
-from core_framework.domains.user import RESERVED_USER_IDS, UserIdentity
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
@@ -21,6 +25,13 @@ class CallerEntitlement:
     expires_at: datetime | None
 
 
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CallerStandaloneEntitlement:
+    standalone_id: str
+    identifier: str
+    expires_at: datetime | None
+
+
 async def list_caller_entitlements(*, user_id: str) -> list[CallerEntitlement]:
     """Return this caller's active tiers with each tier's identifier."""
     tiers = await entitlement_deps.entitlement_service.list_active_tiers(user_id=user_id)
@@ -33,6 +44,18 @@ async def list_caller_entitlements(*, user_id: str) -> list[CallerEntitlement]:
     return items
 
 
+async def list_caller_standalone_entitlements(*, user_id: str) -> list[CallerStandaloneEntitlement]:
+    """Return this caller's standalone holds with each id's lookup key."""
+    standalone_ids = await entitlement_deps.entitlement_service.list_standalone_ids(user_id=user_id)
+    items: list[CallerStandaloneEntitlement] = []
+    for standalone_id in standalone_ids:
+        identifier = standalone_identifier(standalone_id)
+        if identifier is None:
+            continue
+        items.append(CallerStandaloneEntitlement(standalone_id=standalone_id, identifier=identifier, expires_at=None))
+    return items
+
+
 async def caller_holds_tier(*, user_id: str, tier_id: int) -> bool:
     """Return whether the caller holds an active tier at or above the gate. Off means yes."""
     if not entitlements_enabled():
@@ -47,11 +70,27 @@ async def require_caller_tier(*, user_id: str, tier_id: int) -> None:
         raise EntitlementRequiredException()
 
 
+async def caller_holds_standalone_tier(*, user_id: str, standalone_id: str) -> bool:
+    """Return whether the caller holds that standalone id. Off means yes."""
+    if not entitlements_enabled():
+        return True
+    return await entitlement_deps.entitlement_service.standalone_grant_exists(
+        user_id=user_id,
+        standalone_id=standalone_id,
+    )
+
+
+async def require_caller_standalone_tier(*, user_id: str, standalone_id: str) -> None:
+    """Raise when entitlements are on and the caller does not hold that standalone id."""
+    if not await caller_holds_standalone_tier(user_id=user_id, standalone_id=standalone_id):
+        raise EntitlementRequiredException()
+
+
 async def grant_complimentary_tier(*, actor_id: str, target_user_id: str, tier_id: int) -> None:
     """Grant a complimentary tier. Unknown tier is 422. A missing or removing target is 404."""
     if not tier_is_registered(tier_id):
         raise UnprocessableEntityException()
-    if not await _is_core_user(user_id=target_user_id):
+    if not await is_core_user(user_id=target_user_id):
         raise UserNotFoundException()
     inserted = await entitlement_deps.entitlement_service.insert_complimentary_grant(
         user_id=target_user_id,
@@ -85,12 +124,3 @@ async def remove_complimentary_tier(*, actor_id: str, target_user_id: str, tier_
         target_user_id=target_user_id,
         action_metadata={"tier_id": tier_id},
     )
-
-
-async def _is_core_user(*, user_id: str) -> bool:
-    if user_id in RESERVED_USER_IDS:
-        return False
-    identity = await user_deps.user_service.retrieve_user_identity_strong(user_id=user_id)
-    if identity == UserIdentity.DEFAULT:
-        return False
-    return not await user_deps.user_service.retrieve_account_removal_in_progress_strong(user_id=user_id)