feat(entitlements): pro onboarding marker on the plan block

The dashboard shows the Pro tour once, the first time a plan is active and
the account has not seen it. The marker lives on the user, rides in the
plan block of /me/entitlements, and one idempotent route stamps it.

Author: Zingzy

openapi.json

@@ -8042,6 +8042,81 @@
         }
       }
     },
+    "/api/v1/me/pro-onboarding": {
+      "post": {
+        "tags": [
+          "Me"
+        ],
+        "summary": "Complete Pro Onboarding",
+        "description": "Record that this account has seen the Pro tour. Idempotent: the first\ncompletion is kept, and it is read back as `user.pro_onboarded_at` on\n`GET /auth/me`.\n\n**Authentication**: Required. 403 on the free plan.",
+        "operationId": "completeProOnboarding",
+        "responses": {
+          "204": {
+            "description": "Successful Response"
+          },
+          "400": {
+            "description": "Bad Request \u2014 invalid parameters",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized \u2014 missing or invalid credentials",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden \u2014 insufficient permissions or scope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Rate limit exceeded",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Conflict \u2014 resource already exists",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v1/me/layouts/{page}": {
       "get": {
         "tags": [
@@ -13900,6 +13975,12 @@
             "title": "Founding",
             "description": "Founding cohort member",
             "default": false
+          },
+          "renews": {
+            "type": "boolean",
+            "title": "Renews",
+            "description": "True when the term renews on its own at `until`; false when it ends",
+            "default": false
           }
         },
         "type": "object",
@@ -16712,6 +16793,18 @@
             "title": "Onboarded At",
             "description": "When the user completed onboarding (null = never)"
           },
+          "pro_onboarded_at": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Pro Onboarded At",
+            "description": "When the user completed the Pro tour (null = not yet)"
+          },
           "auth_providers": {
             "items": {
               "$ref": "#/components/schemas/AuthProviderInfo"

repositories/user_repository.py

@@ -48,6 +48,13 @@ async def find_by_id(self, user_id: ObjectId) -> UserDoc | None:
         """Find a user by ObjectId."""
         return await self._find_one({"_id": user_id})
 
+    async def mark_pro_onboarded(self, user_id: ObjectId) -> bool:
+        """Stamp the first Pro tour completion; later calls change nothing."""
+        return await self._update_modified(
+            {"_id": user_id, "pro_onboarded_at": None},
+            {"$set": {"pro_onboarded_at": datetime.now(timezone.utc)}},
+        )
+
     async def find_by_oauth_provider(
         self, provider: str, provider_user_id: str
     ) -> UserDoc | None:

routes/api_v1/me.py

@@ -1,6 +1,7 @@
 """
 DELETE /api/v1/me                — request account deletion (grace period)
 GET    /api/v1/me/entitlements   — plan, feature states, limits, version
+POST   /api/v1/me/pro-onboarding — mark the Pro tour as seen
 GET    /api/v1/me/features       — the features map alone
 GET    /api/v1/me/layouts/{page} — fetch the saved dashboard layout (null = default)
 PUT    /api/v1/me/layouts/{page} — save the layout document verbatim
@@ -30,7 +31,9 @@
     JwtUser,
     PageLayoutSvc,
     ProfilePictureSvc,
+    UserRepo,
 )
+from errors import ForbiddenError
 from middleware.openapi import AUTH_RESPONSES
 from middleware.rate_limiter import Limits, limiter
 from schemas.dto.requests.account import DeleteAccountRequest
@@ -52,7 +55,7 @@
     AvailablePicturesResponse,
     ProfilePictureMessageResponse,
 )
-from services.features.catalog import int_features
+from services.features.catalog import Plan, int_features
 
 router = APIRouter(prefix="/me", tags=["Me"])
 
@@ -161,6 +164,7 @@ async def get_my_entitlements(
             status=entitlements.status.value if entitlements.status else None,
             until=entitlements.until,
             founding=entitlements.founding,
+            renews=entitlements.renews,
         ),
         features=features,
         limits={
@@ -171,6 +175,29 @@ async def get_my_entitlements(
     )
 
 
+@router.post(
+    "/pro-onboarding",
+    status_code=204,
+    responses=AUTH_RESPONSES,
+    operation_id="completeProOnboarding",
+    summary="Complete Pro Onboarding",
+)
+@limiter.limit(Limits.DASHBOARD_WRITE)
+async def complete_pro_onboarding(
+    request: Request, user: JwtUser, user_repo: UserRepo, entitlements: Entitled
+) -> None:
+    """Record that this account has seen the Pro tour. Idempotent: the first
+    completion is kept, and it is read back as `user.pro_onboarded_at` on
+    `GET /auth/me`.
+
+    **Authentication**: Required. 403 on the free plan.
+    """
+    # Free is the only plan without the tour; self-host holds everything.
+    if entitlements.plan is Plan.FREE:
+        raise ForbiddenError("Pro plan required")
+    await user_repo.mark_pro_onboarded(user.user_id)
+
+
 # Closed set: every dashboard board the frontend actually renders. An
 # allowlist (not just a pattern) caps per-user storage and rejects junk
 # slugs. Grows in lockstep with the frontend's boards.

schemas/dto/responses/auth.py

@@ -76,6 +76,10 @@ class UserProfileResponse(ResponseBase):
         default=None,
         description="When the user completed onboarding (null = never)",
     )
+    pro_onboarded_at: UtcDatetime | None = Field(
+        default=None,
+        description="When the user completed the Pro tour (null = not yet)",
+    )
     auth_providers: list[AuthProviderInfo] = Field(description="Linked OAuth providers")
     # pfp is absent from the JSON when None (route handlers use exclude_none=True)
     pfp: UserPfp | None = Field(
@@ -97,6 +101,7 @@ def from_user(cls, user: UserDoc, *, plan: str) -> UserProfileResponse:
             plan=plan,
             password_set=user.password_set,
             onboarded_at=user.onboarded_at,
+            pro_onboarded_at=user.pro_onboarded_at,
             auth_providers=[
                 AuthProviderInfo(
                     provider=p.provider,

schemas/dto/responses/entitlements.py

@@ -20,6 +20,10 @@ class PlanBlock(ResponseBase):
         description="Term end, or the grace end while in grace; null when nothing ends",
     )
     founding: bool = Field(default=False, description="Founding cohort member")
+    renews: bool = Field(
+        default=False,
+        description="True when the term renews on its own at `until`; false when it ends",
+    )
 
 
 class LimitBlock(ResponseBase):

schemas/models/user.py

@@ -117,6 +117,8 @@ class UserDoc(MongoBaseModel):
     onboarded_at: datetime | None = None
     # HDYHAU attribution, captured once at onboarding completion.
     heard_from: str | None = None
+    # First Pro tour completion; null = not yet.
+    pro_onboarded_at: datetime | None = None
     status: UserStatus = UserStatus.ACTIVE
     # Account deletion (GDPR erasure): both set on PENDING_DELETION, both
     # cleared on restore. Null on every account that never requested deletion.

services/entitlements/resolver.py

@@ -26,6 +26,8 @@ class Resolved(BaseModel):
     status: SubscriptionStatus | None = None
     until: datetime | None = None
     founding: bool = False
+    # True only for an active recurring term; prepaid terms end, they do not renew.
+    renews: bool = False
     values: dict[str, bool | int]
     version: int
     # True when this answer came from a fallback because the stores were

services/entitlements/service.py

@@ -23,7 +23,11 @@
     EntitlementOverrideRepository,
 )
 from repositories.subscription_repository import SubscriptionRepository
-from schemas.models.subscription import SubscriptionDoc, SubscriptionStatus
+from schemas.models.subscription import (
+    SubscriptionDoc,
+    SubscriptionKind,
+    SubscriptionStatus,
+)
 from services.entitlements.over_limit import OverLimitService
 from services.entitlements.resolver import ANONYMOUS, Resolved, for_plan, resolve
 from services.entitlements.state_machine import SubscriptionEvent, next_status
@@ -100,6 +104,11 @@ async def _compute(self, user_id: ObjectId) -> tuple[Resolved, bool]:
             status=sub.status if sub else None,
             until=sub.until if sub else None,
             founding=bool(sub and sub.founding),
+            renews=bool(
+                sub
+                and sub.kind is SubscriptionKind.RECURRING
+                and sub.status is SubscriptionStatus.ACTIVE
+            ),
             values=resolve(plan, overrides),
             version=version,
         )

tests/integration/api_v1/test_billing.py

@@ -646,6 +646,7 @@ async def test_scenario_checkout_failure_recovery_cancel_grace_repurchase(self):
             "status": "active",
             "until": None,
             "founding": True,
+            "renews": True,
         }
 
         assert w.deliver("subscription_past_due").json()["outcome"] == "applied"

tests/integration/api_v1/test_me_entitlements.py

@@ -58,6 +58,7 @@ def test_free_shape():
         "status": None,
         "until": None,
         "founding": False,
+        "renews": False,
     }
     assert body["features"]["geo_targeting"] == "locked"
     assert set(body["limits"]) == {f.key for f in int_features()}
@@ -179,3 +180,45 @@ def test_over_limit_lists_paused_items_per_limit():
         body = client.get("/api/v1/me/entitlements").json()
     assert body["over_limit"] == {"webhook_endpoints_max": {"paused": ["aaa", "bbb"]}}
     assert body["limits"]["webhook_endpoints_max"] == {"max": 1, "used": 3}
+
+
+def _onboarding_client(plan: Plan) -> tuple[TestClient, AsyncMock]:
+    from dependencies import get_user_repo
+
+    user = _make_user()
+    repo = AsyncMock()
+    repo.mark_pro_onboarded = AsyncMock(return_value=True)
+    app = _build_test_app(
+        {
+            require_jwt: lambda: user,
+            get_current_user: lambda: user,
+            get_entitlements: lambda: for_plan(plan),
+            get_user_repo: lambda: repo,
+        }
+    )
+    return TestClient(app), repo
+
+
+def test_pro_account_marks_the_tour_seen():
+    client, repo = _onboarding_client(Plan.PRO)
+    with client:
+        resp = client.post("/api/v1/me/pro-onboarding")
+    assert resp.status_code == 204
+    assert resp.content == b""
+    repo.mark_pro_onboarded.assert_awaited_once()
+
+
+def test_free_account_cannot_stamp_the_pro_tour():
+    client, repo = _onboarding_client(Plan.FREE)
+    with client:
+        resp = client.post("/api/v1/me/pro-onboarding")
+    assert resp.status_code == 403
+    assert resp.json()["code"] == "forbidden"
+    repo.mark_pro_onboarded.assert_not_awaited()
+
+
+def test_selfhost_account_marks_the_tour_seen():
+    client, repo = _onboarding_client(Plan.SELFHOST)
+    with client:
+        assert client.post("/api/v1/me/pro-onboarding").status_code == 204
+    repo.mark_pro_onboarded.assert_awaited_once()