# BIO.RE Developer Portal (/docs)





The BIO.RE Developer Portal documents every client-facing endpoint of the [BIO.RE](https://bio.re) creator monetization platform. **19 modules, 175 endpoint pages** — every claim cited back to the backend code (`path:line`), every response shape derived from a real DTO, every error code traced to the exception that throws it.

Use the sidebar to browse, the search bar to find a specific endpoint, or the module cards below to jump straight to a section.

## Browse by module [#browse-by-module]

<Cards>
  <Card title="🔐 Authentication" href="/docs/auth/register" description="Register, login, 2FA, OAuth, password reset, OTP, sessions — 29 endpoints covering the full identity lifecycle." />

  <Card title="👤 User" href="/docs/user/profile" description="Profile, settings, avatar, username, email change, blocking, attribution, deactivation, GDPR export/delete — 26 endpoints." />

  <Card title="✨ Creator" href="/docs/creator/dashboard" description="Bio page, links, social accounts, KYC, payout settings, Stripe Connect, vacation mode, newsletter — 37 endpoints." />

  <Card title="💬 Messages" href="/docs/message/list" description="Send, list, search, conversations, reply, reject, rate — 9 endpoints." />

  <Card title="🔔 Notifications" href="/docs/notification/list" description="Inbox, preferences, web push, mark read, unsubscribe — 12 endpoints." />

  <Card title="💳 Payment" href="/docs/payment/wallet-balance" description="Wallet balance, load, packages, transaction activity — 4 endpoints." />

  <Card title="💰 Payout" href="/docs/payout/request" description="Creator payout request + monthly report — 2 endpoints." />

  <Card title="🔍 Discover" href="/docs/discover/search" description="Search, trending, featured, category, recently-viewed history — 7 endpoints." />

  <Card title="📈 Analytics" href="/docs/analytics/track" description="Event tracking + anonymous session/pageview/heartbeat lifecycle — 6 user-facing endpoints." />

  <Card title="📊 Creator Analytics" href="/docs/creator-analytics/overview" description="Creator dashboard reads — overview, traffic, geo, devices, trend, sessions, links + CSV export — 8 endpoints." />

  <Card title="📰 Content" href="/docs/content/pages-list" description="CMS pages, blog (RSS/Atom), help center, FAQ, contact, cookie policy — 15 endpoints." />

  <Card title="🌍 i18n" href="/docs/i18n/locales" description="Locale catalog + translation bundle delivery (full + namespace) — 3 endpoints." />

  <Card title="🎟️ Referral" href="/docs/referral/link" description="Referral link, click tracking, dashboard, coupon apply — 4 endpoints." />

  <Card title="🎫 Support" href="/docs/support/list" description="User-facing tickets — list, create, detail, reply, reopen — 5 endpoints." />

  <Card title="📤 Upload" href="/docs/upload/presign" description="Pre-signed direct-to-storage upload URLs (avatar / media / document) — 1 endpoint." />

  <Card title="🎨 Theme" href="/docs/theme/list" description="Public theme presets for client-web theming — 2 endpoints." />

  <Card title="📡 Presence" href="/docs/presence/last-seen" description="Last-seen + isOnline read for any user — 1 endpoint." />

  <Card title="📊 Platform" href="/docs/platform/stats" description="Public aggregate counters — total creators / messages / earned — 1 endpoint." />

  <Card title="⚖️ Legal" href="/docs/legal/privacy" description="Privacy policy + Terms of service — 2 endpoints." />
</Cards>

## Quick start by use case [#quick-start-by-use-case]

| If you are building...               | Start here                                                                                                                                                                                                                         |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sign-up + login flow**             | [Register](/docs/auth/register) → [Verify Email](/docs/auth/verify-email) → [Login](/docs/auth/login)                                                                                                                              |
| **Forgotten password flow**          | [Forgot Password](/docs/auth/forgot-password) → [Reset Password](/docs/auth/reset-password)                                                                                                                                        |
| **Two-factor authentication**        | [Setup 2FA](/docs/auth/2fa-setup) → [Verify](/docs/auth/2fa-verify) → [Login with 2FA](/docs/auth/login-2fa)                                                                                                                       |
| **OAuth (Google, etc.)**             | [List Providers](/docs/auth/oauth-providers) → [OAuth Login](/docs/auth/oauth-login) → [Link to Account](/docs/auth/oauth-link)                                                                                                    |
| **Creator onboarding**               | [Upgrade to Creator](/docs/creator/upgrade) → [Update Bio](/docs/creator/bio-page-update) → [Add Bio Links](/docs/creator/bio-link-add) → [Stripe Connect](/docs/creator/stripe-connect-initiate) → [KYC](/docs/creator/kyc-start) |
| **Send + receive messages**          | [Send Message](/docs/message/send) → [List Conversations](/docs/message/conversations) → [Reply](/docs/message/reply)                                                                                                              |
| **Wallet top-up**                    | [Wallet Packages](/docs/payment/wallet-packages) → [Load Wallet](/docs/payment/wallet-load) → [Activity](/docs/payment/wallet-activity)                                                                                            |
| **Bio page traffic instrumentation** | [Create Session](/docs/analytics/session-create) → [Record Pageview](/docs/analytics/pageview) → [Heartbeat](/docs/analytics/session-heartbeat) → [Page Leave](/docs/analytics/pageview-leave)                                     |
| **Creator analytics dashboard**      | [Overview](/docs/creator-analytics/overview) → [Traffic](/docs/creator-analytics/traffic) → [Trend](/docs/creator-analytics/trend) → [Links](/docs/creator-analytics/links) → [CSV Export](/docs/creator-analytics/export)         |
| **Notification preferences UI**      | [List Notifications](/docs/notification/list) → [Preferences](/docs/notification/preferences) → [Update Preferences](/docs/notification/preferences-update) → [Web Push Subscribe](/docs/notification/webpush-subscribe)           |
| **GDPR data export / delete**        | [Request Export](/docs/user/gdpr-export) → [Check Status](/docs/user/gdpr-export-status) → [Download](/docs/user/gdpr-export-download) → [Request Delete](/docs/user/gdpr-delete)                                                  |
| **Localization**                     | [List Locales](/docs/i18n/locales) → [Bundle](/docs/i18n/bundle) → [Namespace Bundle](/docs/i18n/namespace)                                                                                                                        |
| **Support ticketing**                | [List My Tickets](/docs/support/list) → [Create](/docs/support/create) → [Reply](/docs/support/reply)                                                                                                                              |

## How to read an endpoint page [#how-to-read-an-endpoint-page]

Every endpoint page follows the same shape:

1. **Header** — method + path + scope badge (🌐 Public / 🔑 Bearer / 👤 Admin) + rate limit.
2. **Callouts** — non-obvious behavior, gotchas, kill switches, vendor abstraction notes.
3. **Request** — path / query / body / header tables, with `class-validator` rules preserved.
4. **Response** — success envelope + every error code with `i18nKey`.
5. **Side effects** — DB writes, queued jobs, audit log entries, kill-switch gates, cache invalidations.
6. **Code samples** — `curl` + `TypeScript fetch` + `TanStack Query` hook (copy-paste ready).
7. **Try it** — interactive playground with auto-generated cURL/JS/Go/Python/Java/C# samples.
8. **Source** — `path:line` references back to the backend code (5-source verify: controller + DTO + service + Prisma + cache/util).

## Conventions across the API [#conventions-across-the-api]

* **Response envelope** — every successful response is `{ "success": true, "data": T }`. Errors are `{ "success": false, "error": { code, message, i18nKey?, details?, correlationId } }`.
* **Refresh tokens** — set as `httpOnly`, `secure`, `SameSite=Strict` cookie scoped to `.bio.re`. Browsers send + receive automatically; mobile clients can pass via body.
* **Idempotency** — mutating endpoints accept `Idempotency-Key` header where supported; the side-effects table notes which writes are atomic.
* **Locales** — 20 active locales, error responses include `i18nKey` for UI mapping.
* **Admin-managed providers** — every external integration (email, SMS, push, captcha, KYC, payment, OAuth, storage) is selected by admin at runtime. The portal **never names the active vendor** (e.g., "SendGrid" / "Twilio"); endpoints reference the abstraction (`external.email.active_provider`, etc.). Frontend reads the abstract token; the backend resolves to whichever vendor is currently active. Stripe is the lone exception — load-bearing infra, not a swappable vendor.
* **Two databases** — most endpoints write to the main Postgres (`@biore/prisma`). Analytics tracking endpoints write to a separate Analytics DB (`@biore/prisma-analytics`) — joins between the two happen in application code.

## Machine-readable surfaces [#machine-readable-surfaces]

| Surface                 | URL                                            | Purpose                                                                            |
| ----------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------- |
| **OpenAPI spec**        | [`/openapi/full.json`](/openapi/full.json)     | Full Swagger spec — feeds the "Try it" playground on every endpoint page (945 KB). |
| **Public-only OpenAPI** | [`/openapi/public.json`](/openapi/public.json) | Public endpoints only.                                                             |
| **User-auth OpenAPI**   | [`/openapi/user.json`](/openapi/user.json)     | Public + JWT-bearer endpoints.                                                     |
| **Admin OpenAPI**       | [`/openapi/admin.json`](/openapi/admin.json)   | Admin-scope endpoints.                                                             |
| **Sitemap**             | [`/sitemap.xml`](/sitemap.xml)                 | Every URL on this site (179 entries).                                              |
| **`llms.txt`**          | [`/llms.txt`](/llms.txt)                       | Compact module + endpoint index for LLMs.                                          |
| **`llms-full.txt`**     | [`/llms-full.txt`](/llms-full.txt)             | Full content of every endpoint page in one file (1.4 MB) for LLM consumption.      |
| **Per-page Markdown**   | `/llms.mdx/docs/<path>/content.md`             | Raw MDX of any individual page.                                                    |


# Record Page Leave (/docs/analytics/pageview-leave)



`PATCH /api/v1/analytics/pageview/:id/leave` — 🌐 **Public** · Rate limit: **10 req / minute**

Finalizes the duration and scroll depth of a single pageview. Earlier pageviews in the same session get their `duration` back-filled automatically by the next [`POST /pageview`](/docs/analytics/pageview), so this endpoint really only matters for the **last** pageview of a session — the one followed by a tab close, navigation away, or full app exit.



<Callout type="info">
  **Use `navigator.sendBeacon` from `pagehide` / `beforeunload`.** A regular `fetch` from those handlers usually gets cancelled by the browser. `sendBeacon` is queued by the browser and delivered after the page unloads. The body is JSON; the server will accept it.
</Callout>

<Callout type="warn">
  **`duration` is capped at 3600s server-side.** `Math.min(duration, 3600)&#x60; — anything you pass over an hour gets clamped. &#x2A;*`scrollDepth` is clamped to `[0, 100]`** before write — pass percentages, not pixel values.
</Callout>

<Callout type="warn">
  **Silent failures.** `update.catch(() => {})` — if the pageview id is wrong or the row's been pruned, you still get `200 { ok: true }` and no error.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param | Type          | Required | Notes                                                                                                                                |
| ----- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `id`  | string (UUID) | ✓        | The pageview row id from [`POST /analytics/pageview`](/docs/analytics/pageview). Not validated server-side — bad ids no-op silently. |

### Body — `PageLeaveDto` [#body--pageleavedto]

| Field         | Type             | Required | Validation                  | Notes                                                                                                                                            |
| ------------- | ---------------- | -------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `duration`    | number (seconds) | ✓        | `IsNumber Min(0) Max(3600)` | Whole or fractional seconds the page was visible. DTO validates `[0, 3600]`; service additionally `Math.min(duration, 3600)` as belt-and-braces. |
| `scrollDepth` | number (percent) | optional | `IsNumber Min(0) Max(100)`  | Furthest scroll position as a 0-100 percentage. DTO validates the range; service additionally `Math.min(Math.max(value, 0), 100)`.               |

### Headers [#headers]

| Header                           | Required | Notes                                                                                                                                                                       |
| -------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type: application/json` | ✓        | `sendBeacon` will send `application/x-www-form-urlencoded` or `Blob` mime-type by default — wrap your JSON in a typed `Blob` to keep it `application/json`. See the sample. |

No auth.

## Response [#response]

### `200 OK` — `ApiResponseOf<PageLeaveResultDto>` [#200-ok--apiresponseofpageleaveresultdto]

```json
{ "success": true, "data": { "ok": true } }
```

Same caveats as heartbeat — `ok: true` is "request reached service," not "row was updated."

### Errors [#errors]

| HTTP  | Reason                                                                                                 |
| ----- | ------------------------------------------------------------------------------------------------------ |
| `400` | DTO validation (`duration` outside `[0, 3600]`, `scrollDepth` outside `[0, 100]`, missing `duration`). |
| `429` | Over 10 req/min from this IP.                                                                          |

## Side effects [#side-effects]

1. `ThrottleGuard` (10 req / 60s).
2. `analyticsDb.analyticsPageView.update({ where: { id }, data: { duration: Math.min(data.duration, 3600), scrollDepth: clamped(0..100) ?? null } }).catch(() => {})`. Single SQL UPDATE; mis-id silently swallowed.
3. Return `{ ok: true }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'sendBeacon (recommended)']">
  <Tab value="curl">
    ```bash
    curl -X PATCH https://api.bio.re/api/v1/analytics/pageview/pv-uuid/leave \
      -H 'Content-Type: application/json' \
      -d '{ "duration": 47, "scrollDepth": 65 }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function pageLeave(
      pageViewId: string,
      data: { duration: number; scrollDepth?: number },
    ): Promise<void> {
      await fetch(`https://api.bio.re/api/v1/analytics/pageview/${pageViewId}/leave`, {
        method: 'PATCH',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data),
      }).catch(() => {});
    }
    ```
  </Tab>

  <Tab value="sendBeacon (recommended)">
    ```ts
    // Fires reliably during page unload — fetch usually gets cancelled in unload handlers.
    function leaveBeacon(
      pageViewId: string,
      data: { duration: number; scrollDepth?: number },
    ): boolean {
      const url = `/api/v1/analytics/pageview/${pageViewId}/leave`;
      const blob = new Blob([JSON.stringify(data)], { type: 'application/json' });
      return navigator.sendBeacon(url, blob);
    }

    // Wire it up — pagehide is more reliable than beforeunload on mobile Safari.
    window.addEventListener('pagehide', () => {
      if (!lastPageViewId) return;
      const duration = Math.floor((Date.now() - mountedAt) / 1000);
      const scrollDepth = Math.round(
        (window.scrollY + window.innerHeight) / document.documentElement.scrollHeight * 100,
      );
      leaveBeacon(lastPageViewId, { duration, scrollDepth });
    });
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/analytics/pageview/{id}/leave', method: 'patch' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                       | Lines                                                                    |
| -------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/analytics/analytics.controller.ts`              | `168–177` (`pageLeave`)                                                  |
| DTO (request)  | `apps/api-core/src/modules/analytics/dto/tracking.dto.ts`                  | `38–41` (`PageLeaveDto`)                                                 |
| DTO (response) | `apps/api-core/src/modules/analytics/dto/analytics-client-response.dto.ts` | `43–46` (`PageLeaveResultDto`)                                           |
| Service        | `apps/api-core/src/modules/analytics/traffic-tracking.service.ts`          | `205–213` (`pageLeave` — duration cap + scrollDepth clamp + silent fail) |
| Prisma model   | `packages/prisma-analytics/prisma/schema.prisma`                           | `AnalyticsPageView.duration / scrollDepth` lines `112–113`               |


# Record Page View (/docs/analytics/pageview)



`POST /api/v1/analytics/pageview` — 🌐 **Public** · Rate limit: **30 req / minute**

Records one pageview against an existing analytics session. Each successful call does three things in the database — creates the pageview row, atomically increments the parent session's counter (and flips the `bounced` flag from `true` → `false` on the second view), and back-fills `duration` on the previous pageview. All three are best-effort: failures are swallowed and the response is `200 { id: null }` so client instrumentation never errors out a page render.



<Callout type="info">
  **Atomic counter update prevents the bounce-flag race.** The session's `pageViews` increment and the `bounced` flag flip happen in a single SQL `UPDATE ... SET pageViews = pageViews + 1, bounced = CASE WHEN pageViews + 1 >= 2 THEN false ELSE true END`. Earlier read-then-write versions had a race where two concurrent pageviews could both observe `pageViews = 1` and incorrectly set `bounced = true`.
</Callout>

<Callout type="info">
  **Previous pageview's `duration` is back-filled here, not on `pageLeave`.** When this endpoint runs, it looks up the user's most-recent prior pageview in the same session and sets its `duration = (this.enteredAt - prev.enteredAt) / 1000`, **capped 0–3600s** (anything outside that range is silently dropped). The dedicated [`pageLeave`](/docs/analytics/pageview-leave) endpoint is only needed to capture duration on the *last* view in a session (no follow-up pageview will ever back-fill it).
</Callout>

<Callout type="warn">
  **Silent failures.** If the session doesn't exist (expired / cleaned up / wrong id), the page-view insert may fail or the session UPDATE will simply match zero rows. Either way the endpoint returns `200 { id: null }` (or `{ id }` from the new row even when the session update no-ops). **Don't treat a non-null `id` as proof the session counter advanced** — the row itself can land while the session UPDATE matches nothing.
</Callout>

## Request [#request]

### Body — `RecordPageViewDto` [#body--recordpageviewdto]

| Field         | Type          | Required | Validation | Notes                                                                                                                                                              |
| ------------- | ------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sessionId`   | string (UUID) | ✓        | `IsString` | The session id from [`POST /analytics/session`](/docs/analytics/session-create). Server doesn't validate it exists — non-matching ids land an orphan pageview row. |
| `url`         | string        | ✓        | `IsString` | Full URL of the viewed page. Stored verbatim and used as the session's `exitPage`.                                                                                 |
| `path`        | string        | ✓        | `IsString` | Normalized path (e.g. `/creators/alice`, `/messages`).                                                                                                             |
| `title`       | string        | optional | `IsString` | `document.title`.                                                                                                                                                  |
| `bioPageId`   | string (UUID) | optional | `IsString` | The bio page being viewed (if applicable).                                                                                                                         |
| `linkClicked` | string (UUID) | optional | `IsString` | If this view was triggered by a bio link click, the id of that link. Use to reconstruct the click flow.                                                            |

### Headers [#headers]

| Header                           | Required | Notes     |
| -------------------------------- | -------- | --------- |
| `Content-Type: application/json` | ✓        | Standard. |

No auth — endpoint is `@Public()`.

## Response [#response]

### `200 OK` — `ApiResponseOf<PageViewCreatedDto>` [#200-ok--apiresponseofpageviewcreateddto]

```json
{
  "success": true,
  "data": {
    "id": "pv-uuid-...",
    "enteredAt": "2026-04-30T10:00:01.123Z"
  }
}
```

| Field       | Type                  | Notes                                                                       |
| ----------- | --------------------- | --------------------------------------------------------------------------- |
| `id`        | string (UUID) \| null | New pageview row id, or `null` when the row insert threw (caught + logged). |
| `enteredAt` | string (ISO 8601)     | When the row was created (DB `now()`). Only present when `id` is non-null.  |

### Errors [#errors]

| HTTP  | Reason                                                 |
| ----- | ------------------------------------------------------ |
| `400` | DTO validation (missing `sessionId` / `url` / `path`). |
| `429` | Over 30 req/min from this IP.                          |

DB / session-not-found failures are **not** errors — they become `200 { id: null }`.

## Side effects [#side-effects]

1. `ThrottleGuard` (30 req / 60s).
2. `analyticsDb.analyticsPageView.create({ data: { id: randomUUID(), sessionId, url, path, title, bioPageId, linkClicked } })`.
3. **Atomic session update** via `analyticsDb.$executeRaw`:
   ```sql
   UPDATE "AnalyticsSession"
   SET "pageViews" = "pageViews" + 1,
       "exitPage" = $url,
       "lastActivityAt" = NOW(),
       "bounced" = CASE WHEN "pageViews" + 1 >= 2 THEN false ELSE true END
   WHERE id = $sessionId::uuid
   ```
   `.catch(() => {})` — failures swallowed.
4. **Back-fill prev `duration`**: `findFirst({ sessionId, id: NOT this.id, orderBy: enteredAt desc })` → if found, `update prev.duration = (this.enteredAt - prev.enteredAt) / 1000` when `0 < duration < 3600`. Out-of-range or query failure → silently skipped.
5. Return `{ id, enteredAt }` (or `{ id: null }` on row-create exception).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'SPA route-change hook']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/analytics/pageview \
      -H 'Content-Type: application/json' \
      -d '{
        "sessionId": "ses-uuid-from-create",
        "url": "https://bio.re/alice",
        "path": "/alice",
        "title": "Alice on bio.re",
        "bioPageId": "11111111-2222-3333-4444-555555555555"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type RecordPageViewInput = {
      sessionId: string;
      url: string;
      path: string;
      title?: string;
      bioPageId?: string;
      linkClicked?: string;
    };

    type PageViewResult = { id: string | null; enteredAt?: string };

    async function recordPageView(input: RecordPageViewInput): Promise<PageViewResult> {
      const res = await fetch('https://api.bio.re/api/v1/analytics/pageview', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      return json.data;
    }
    ```
  </Tab>

  <Tab value="SPA route-change hook">
    ```ts
    // React Router / Next.js example — fire one pageview per route change.
    let lastPageViewId: string | null = null;

    useEffect(() => {
      if (!sessionId) return;

      // Fire-and-forget; capture id so pageLeave can finalize duration when leaving.
      recordPageView({
        sessionId,
        url: location.href,
        path: location.pathname,
        title: document.title,
      }).then(({ id }) => { lastPageViewId = id; });
    }, [pathname]);

    // On unmount / before route change, send the leave event for accurate last-view duration:
    useEffect(() => {
      return () => {
        if (lastPageViewId) {
          const duration = Math.floor((Date.now() - mountedAt.current) / 1000);
          pageLeave(lastPageViewId, { duration, scrollDepth: getScrollPercent() });
        }
      };
    }, []);
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/analytics/pageview', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                       | Lines                                                                                                           |
| -------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/analytics/analytics.controller.ts`              | `146–155` (`recordPageView`)                                                                                    |
| DTO (request)  | `apps/api-core/src/modules/analytics/dto/tracking.dto.ts`                  | `29–36` (`RecordPageViewDto`)                                                                                   |
| DTO (response) | `apps/api-core/src/modules/analytics/dto/analytics-client-response.dto.ts` | `24–32` (`PageViewCreatedDto`)                                                                                  |
| Service        | `apps/api-core/src/modules/analytics/traffic-tracking.service.ts`          | `139–193` (`recordPageView` — atomic UPDATE, prev-duration back-fill)                                           |
| Prisma model   | `packages/prisma-analytics/prisma/schema.prisma`                           | `AnalyticsPageView` lines `102–119`, `AnalyticsSession.pageViews / bounced / exitPage / lastActivityAt` `46–96` |


# Create Analytics Session (/docs/analytics/session-create)



`POST /api/v1/analytics/session` — 🌐 **Public** · Rate limit: **10 req / minute**

Opens a new analytics session — the parent record for subsequent pageviews and heartbeats. Public so the SSR shell can call it before any login. The server augments the request with **server-side UA parsing** and **GeoIP lookup**, hashes the supplied visitorId, then writes the row to the **separate Analytics DB**.



<Callout type="warn">
  **This endpoint silently rejects four kinds of requests with `200 { id: null }`:** (1) bot user-agents (UA matched against a regex of common crawler tokens), (2) requests where `consentAnalytics !== 'granted'` (GDPR gate), (3) requests with `bioPageId` but no valid HMAC tracking token, and (4) DB write failures (caught, logged, swallowed). Always check `data.id` — `null` means "tracking did not happen, don't bother sending pageviews against this session."
</Callout>

<Callout type="warn">
  **HMAC tracking token required when `bioPageId` is set.** The token is generated server-side as `HMAC-SHA256(TRACKING_HMAC_SECRET, '<bioPageId>:<5min-bucket>')[:32]`, embedded in the SSR-rendered bio page, and validated against the current and previous 5-minute bucket (10-min validity). **There is no public endpoint to obtain this token** — it lives in the SSR HTML. Custom integrations that don't render through the platform SSR should omit `bioPageId` (you can still track the session, but it won't be linked to a bio page).
</Callout>

<Callout type="info">
  **Server-side UA + GeoIP win over client-supplied values.** Client may send `device`, `browser`, `os`, `osVersion`, `timezone` — but the server runs `UAParser` on the request `User-Agent` header and overrides those fields when it can parse them. GeoIP is derived from the request IP (`cf-connecting-ip` > `x-forwarded-for[0]` > `req.ip`). **The IP itself is never persisted** — only the derived `country / city / region / continent / timezone` columns land in the row.
</Callout>

<Callout type="info">
  **`visitorId` is one-way hashed before write.** Client supplies its anonymous localStorage UUID; server runs `SHA256(visitorId)` and stores the hash (per GDPR Article 4(5) on pseudonymization). Joins across sessions still work because the hash is deterministic, but the original visitorId never reaches the DB.
</Callout>

## Request [#request]

### Body — `CreateSessionDto` [#body--createsessiondto]

| Field                                                                | Type          | Required       | Validation                               | Notes                                                                                                                                       |
| -------------------------------------------------------------------- | ------------- | -------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `visitorId`                                                          | string        | ✓              | `IsString`                               | Anonymous client-side UUID (e.g. from `localStorage`). Hashed before write.                                                                 |
| `landingPage`                                                        | string        | ✓              | `IsString`                               | First URL the user landed on (full URL).                                                                                                    |
| `consentAnalytics`                                                   | string        | ✓ for tracking | `IsString` `MaxLength(50)`               | **Must be `'granted'`** for the row to land. Anything else → `200 { id: null }`.                                                            |
| `bioPageId`                                                          | string (UUID) | optional       | `IsString`                               | When set, **also** requires a valid `trackingToken` — otherwise the session is rejected.                                                    |
| `creatorId`                                                          | string (UUID) | optional       | `IsString`                               | Denormalized creator id (for fast creator analytics joins). No FK validation — application-level link to the main DB.                       |
| `referrer`                                                           | string        | optional       | `IsString`                               | Document.referrer. Server extracts `referrerDomain` from this (`new URL(referrer).hostname.replace('www.', '')`); falls back to `'direct'`. |
| `utmSource` / `utmMedium` / `utmCampaign` / `utmTerm` / `utmContent` | string        | optional       | `IsString`                               | Standard UTM params from the URL query string. Stored verbatim.                                                                             |
| `device` / `browser` / `os` / `osVersion`                            | string        | optional       | `IsString` (`osVersion` `MaxLength(20)`) | **Overridden by server-side UA parse when possible** — see callout.                                                                         |
| `screenWidth` / `screenHeight`                                       | integer       | optional       | `Min(0) Max(7680)`                       | From `window.screen.*`.                                                                                                                     |
| `connectionType`                                                     | string        | optional       | `MaxLength(20)`                          | From `navigator.connection.effectiveType` (e.g. `'4g'`, `'wifi'`).                                                                          |
| `timezone`                                                           | string        | optional       | `MaxLength(50)`                          | Client timezone. Server overrides with GeoIP timezone if available.                                                                         |
| `language`                                                           | string        | optional       | `IsString`                               | `navigator.language`.                                                                                                                       |
| `trackingToken`                                                      | string        | optional\*     | `IsString`                               | **Required when `bioPageId` is present**, otherwise ignored. See HMAC callout.                                                              |

### Headers [#headers]

| Header                                                                | Required      | Notes                                                                                      |
| --------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------ |
| `User-Agent`                                                          | (always sent) | Server runs the bot regex AND `UAParser` on this header.                                   |
| `cf-connecting-ip` / `x-forwarded-for` / `cf-ipcountry` / `cf-ipcity` | optional      | Used as the IP source for GeoIP and as fallback country/city when the GeoIP DB has no row. |
| `Content-Type: application/json`                                      | ✓             | Standard.                                                                                  |

No `Authorization` — endpoint is `@Public()`.

## Response [#response]

### `200 OK` — `ApiResponseOf<SessionCreatedDto>` [#200-ok--apiresponseofsessioncreateddto]

```json
{
  "success": true,
  "data": {
    "id": "ses-uuid-...",
    "createdAt": "2026-04-30T10:00:00.000Z"
  }
}
```

When tracking is rejected:

```json
{ "success": true, "data": { "id": null } }
```

| Field       | Type                  | Notes                                                                                   |
| ----------- | --------------------- | --------------------------------------------------------------------------------------- |
| `id`        | string (UUID) \| null | Session id. **`null` is a soft no-op** — see warn callout for the four rejection paths. |
| `createdAt` | string (ISO 8601)     | Only present when `id` is non-null. The server timestamp the row got.                   |

Hold on to `id` and pass it to subsequent pageview / heartbeat / identify calls.

### Errors [#errors]

| HTTP  | Code                      | Reason                                                                        |
| ----- | ------------------------- | ----------------------------------------------------------------------------- |
| `400` | (DTO validation)          | Missing `visitorId` or `landingPage`; `screenWidth/Height` out of range; etc. |
| `429` | `THROTTLE_LIMIT_EXCEEDED` | Over 10 req/min from this IP.                                                 |

This endpoint **never returns 403/404/500 on tracking rejection** — those become `200 { id: null }` to keep the client UX simple. Real failures (validation, throttle) still bubble up.

## Side effects [#side-effects]

1. `ThrottleGuard` increments `throttle:<ip>:POST:/api/v1/analytics/session` (10-req / 60s).
2. **Bot filter**: regex against `User-Agent` (`/bot|crawl|spider|slurp|baidu|yandex|bing|google|facebook|twitter|linkedin|whatsapp|telegram|preview|fetch|curl|wget|python|java|php|ruby|go-http/i`). Match → return `{ id: null }`.
3. **GDPR gate**: `consentAnalytics !== 'granted'` → return `{ id: null }`.
4. **UA parse**: `UAParser(userAgent)` → derive `device` (`mobile` / `tablet` / `desktop`), `browser`, `os`, `osVersion`. These override the client's values (with a fall-through to the client value when UA parse can't determine it).
5. **GeoIP** (scoped inside `try/catch` so the raw IP **never** leaks to error logs):
   * Resolve client IP: `cf-connecting-ip` > `x-forwarded-for[0].trim()` > `req.ip`.
   * `geoipService.lookup(ip)` → `country, city, region, continent, timezone`.
   * Fall-through: `country` and `city` use `cf-ipcountry` / `cf-ipcity` headers if GeoIP has no row.
   * On exception → silent catch, all geo fields stay `null`. &#x2A;*The raw IP is never persisted, never logged.**
6. **HMAC tracking token check** (only when `bioPageId` is set): rebuild HMAC against current and previous 5-min bucket; mismatch → log debug `'rejected as spam'`, return `null`.
7. **Hash visitorId**: `SHA256(visitorId).hex` — replaces the original.
8. Extract `referrerDomain` from `referrer`: `new URL(referrer).hostname.replace('www.', '')`; URL-parse failure → `'direct'`; missing referrer → `'direct'`.
9. **Write row to Analytics DB**: `analyticsDb.analyticsSession.create({ data: {...} })`. On exception → log error, return `{ id: null }`.
10. Return `{ id, createdAt }` (or `{ id: null }`).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'Bootstrap example (full flow)']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/analytics/session \
      -H 'Content-Type: application/json' \
      -d '{
        "visitorId": "anon-localStorage-uuid",
        "landingPage": "https://bio.re/alice",
        "consentAnalytics": "granted",
        "referrer": "https://www.instagram.com/alice",
        "utmSource": "instagram",
        "utmMedium": "story",
        "utmCampaign": "spring-launch",
        "screenWidth": 390,
        "screenHeight": 844,
        "language": "en-US",
        "bioPageId": "11111111-2222-3333-4444-555555555555",
        "trackingToken": "<32-hex-from-SSR-html>"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type CreateSessionInput = {
      visitorId: string;
      landingPage: string;
      consentAnalytics: 'granted' | 'denied' | string;  // must be 'granted'
      bioPageId?: string;
      creatorId?: string;
      referrer?: string;
      utmSource?: string;
      utmMedium?: string;
      utmCampaign?: string;
      utmTerm?: string;
      utmContent?: string;
      trackingToken?: string;
      device?: string;
      browser?: string;
      os?: string;
      osVersion?: string;
      screenWidth?: number;
      screenHeight?: number;
      connectionType?: string;
      timezone?: string;
      language?: string;
    };

    type CreateSessionResult = { id: string | null; createdAt?: string };

    async function createSession(input: CreateSessionInput): Promise<CreateSessionResult> {
      const res = await fetch('https://api.bio.re/api/v1/analytics/session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      return json.data; // { id: string | null, createdAt? }
    }
    ```
  </Tab>

  <Tab value="Bootstrap example (full flow)">
    ```ts
    // 1. Read consent state from your cookie banner / preference store.
    const consent = readAnalyticsConsent(); // 'granted' | 'denied'

    // 2. Stable anonymous id from localStorage.
    const visitorId = (() => {
      let v = localStorage.getItem('bre.vid');
      if (!v) {
        v = crypto.randomUUID();
        localStorage.setItem('bre.vid', v);
      }
      return v;
    })();

    // 3. Open the session — `id: null` is a soft no-op, don't surface as an error.
    const { id: sessionId } = await createSession({
      visitorId,
      landingPage: location.href,
      consentAnalytics: consent,
      referrer: document.referrer || undefined,
      utmSource: new URL(location.href).searchParams.get('utm_source') || undefined,
      bioPageId: window.__BIO_PAGE_ID__,                  // injected by SSR
      trackingToken: window.__TRACKING_TOKEN__,           // injected by SSR
      screenWidth: screen.width,
      screenHeight: screen.height,
      language: navigator.language,
      timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
    });

    // 4. If we got an id, instrument the rest of the page lifecycle.
    if (sessionId) {
      recordPageView({ sessionId, url: location.href, path: location.pathname });
      setInterval(() => sessionHeartbeat(sessionId), 30_000);
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/analytics/session', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                       | Lines                                                                                                                                         |       |        |                  |
| -------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ---------------- |
| Controller     | `apps/api-core/src/modules/analytics/analytics.controller.ts`              | `82–144` (`createSession` — bot, GDPR, UA, GeoIP, IP-source priority)                                                                         |       |        |                  |
| Bot regex      | `apps/api-core/src/modules/analytics/analytics.controller.ts`              | `190–193` (`isBot` — \`bot                                                                                                                    | crawl | spider | ...\` UA tokens) |
| DTO (request)  | `apps/api-core/src/modules/analytics/dto/tracking.dto.ts`                  | `5–27` (`CreateSessionDto`)                                                                                                                   |       |        |                  |
| DTO (response) | `apps/api-core/src/modules/analytics/dto/analytics-client-response.dto.ts` | `12–20` (`SessionCreatedDto`)                                                                                                                 |       |        |                  |
| Service        | `apps/api-core/src/modules/analytics/traffic-tracking.service.ts`          | `52–137` (`createSession` — token check, hash, referrerDomain, DB write), `6–8` (`hashVisitorId` — SHA256), `21–50` (HMAC token gen + verify) |       |        |                  |
| GeoIP package  | `@biore/geoip`                                                             | `GeoIPService.lookup()` (returns `{ country, city, region, continent, timezone }`)                                                            |       |        |                  |
| Prisma model   | `packages/prisma-analytics/prisma/schema.prisma`                           | `AnalyticsSession` lines `46–96` (Analytics DB — separate from main DB)                                                                       |       |        |                  |


# Session Heartbeat (/docs/analytics/session-heartbeat)



`PATCH /api/v1/analytics/session/:id/heartbeat` — 🌐 **Public** · Rate limit: **5 req / 30 s**

Marks the session as still active and adds 30 seconds to its rolling `duration` counter. Call once every \~30 seconds while the user has the page in the foreground; stop when they background the tab or close the page. **The endpoint hard-codes a `+30` increment** regardless of how long it's actually been since the last beat, so don't call it more often than once per 30s — you'll over-count time on session.



<Callout type="warn">
  **`duration` is incremented by a hard-coded 30s per call.** The server does NOT measure the elapsed wall-clock time between heartbeats. Two beats in 1 second still add 60s to `duration`. The throttle (`@Throttle(5, 30)` — 5 req per 30s) is what protects against accidental spam, but you should still pace your client to one beat per \~30s.
</Callout>

<Callout type="info">
  **Failures are silent.** Service does `update.catch(() => {})` — if the session id doesn't exist or DB is unhappy, you still get `200 { ok: true }`. No way for the client to detect that the session is gone via this endpoint; only the session-create response's `null` id signals real rejection.
</Callout>

<Callout type="info">
  **Pair with the Page Visibility API.** The right cadence is "every 30 seconds while `document.visibilityState === 'visible'`." Sending heartbeats from a backgrounded tab inflates active-time metrics. See the code sample.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param | Type   | Required | Notes                                                                                                                                                         |
| ----- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`  | string | ✓        | Session id from [`POST /analytics/session`](/docs/analytics/session-create). **Not** validated by `ParseUUIDPipe` — any string is accepted; mismatches no-op. |

### Headers [#headers]

| Header                           | Required | Notes          |
| -------------------------------- | -------- | -------------- |
| `Content-Type: application/json` | optional | Body is empty. |

No body, no auth.

## Response [#response]

### `200 OK` — `ApiResponseOf<HeartbeatResultDto>` [#200-ok--apiresponseofheartbeatresultdto]

```json
{ "success": true, "data": { "ok": true } }
```

`ok: true` means "request reached the service" — not "DB write succeeded" (see warn callout).

### Errors [#errors]

| HTTP  | Reason                                                                                                 |
| ----- | ------------------------------------------------------------------------------------------------------ |
| `429` | Over 5 req / 30s from this IP. (Throttle is per-IP, not per-session — multiple tabs share the budget.) |

## Side effects [#side-effects]

1. `ThrottleGuard` (5 req / 30s).
2. `analyticsDb.analyticsSession.update({ where: { id }, data: { lastActivityAt: new Date(), duration: { increment: 30 } } }).catch(() => {})`. **Single SQL UPDATE**, no read-then-write.
3. Return `{ ok: true }` regardless of whether any row was matched.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'Visibility-aware loop']">
  <Tab value="curl">
    ```bash
    curl -X PATCH https://api.bio.re/api/v1/analytics/session/ses-uuid/heartbeat
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function sessionHeartbeat(sessionId: string): Promise<void> {
      await fetch(`https://api.bio.re/api/v1/analytics/session/${sessionId}/heartbeat`, {
        method: 'PATCH',
      }).catch(() => {}); // never throw from instrumentation
    }
    ```
  </Tab>

  <Tab value="Visibility-aware loop">
    ```ts
    // Fire a heartbeat every 30s, but only while the tab is visible.
    // Pauses on visibilitychange = 'hidden', resumes on 'visible'.
    function startHeartbeat(sessionId: string): () => void {
      let timer: number | null = null;

      const start = () => {
        if (timer != null) return;
        timer = window.setInterval(() => sessionHeartbeat(sessionId), 30_000);
      };
      const stop = () => {
        if (timer != null) { clearInterval(timer); timer = null; }
      };

      const onVisibility = () => {
        if (document.visibilityState === 'visible') start(); else stop();
      };

      document.addEventListener('visibilitychange', onVisibility);
      if (document.visibilityState === 'visible') start();

      // Return cleanup
      return () => {
        document.removeEventListener('visibilitychange', onVisibility);
        stop();
      };
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/analytics/session/{id}/heartbeat', method: 'patch' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                       | Lines                                                           |
| -------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/analytics/analytics.controller.ts`              | `157–166` (`sessionHeartbeat`)                                  |
| DTO (response) | `apps/api-core/src/modules/analytics/dto/analytics-client-response.dto.ts` | `36–39` (`HeartbeatResultDto`)                                  |
| Service        | `apps/api-core/src/modules/analytics/traffic-tracking.service.ts`          | `195–203` (`heartbeat` — fixed `+30` increment, silent failure) |
| Prisma model   | `packages/prisma-analytics/prisma/schema.prisma`                           | `AnalyticsSession.duration / lastActivityAt` lines `53–54`      |


# Identify Session After Login (/docs/analytics/session-identify)



`PATCH /api/v1/analytics/session/:id/identify` — 🔑 **Bearer**

Sets `AnalyticsSession.userId` for an existing session. Call this **once, right after login or signup completes** — the session was created anonymously (likely before the user authenticated), and this pulls the user identity onto it so all the prior pageviews in that session can be attributed correctly.



<Callout type="info">
  **Idempotent and overwrite-friendly.** The service does a flat `update({ where: { id }, data: { userId } })` — calling it twice with the same userId is a no-op. Calling it with a different userId overwrites the previous one, so don't share session ids across users (a logout-then-login on the same anonymous session would reattribute prior views to the second user).
</Callout>

<Callout type="warn">
  **No 404 / 401 cross-checks.** The service silently swallows `update` failures (`update.catch(() => {})`). If the session id doesn't exist or the DB rejects the write, the response is still `200 { ok: true }` — you can't programmatically detect a bad id. The auth check (`@CurrentUser('id')` requires a valid bearer) is the only real gate.
</Callout>

<Callout type="info">
  **`userId` comes from the JWT, not the body.** The endpoint reads `userId` via `@CurrentUser('id')` — there is no way to identify a session as someone else. To unbind, you'd need a separate endpoint (none today). To re-identify after logout, the new session should be created fresh.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param | Type          | Required | Notes                                                                                                                   |
| ----- | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `id`  | string (UUID) | ✓        | Session id from [`POST /analytics/session`](/docs/analytics/session-create). Not validated server-side — bad ids no-op. |

### Headers [#headers]

| Header                                | Required | Notes                                                                    |
| ------------------------------------- | -------- | ------------------------------------------------------------------------ |
| `Authorization: Bearer <accessToken>` | ✓        | Global `JwtAuthGuard`. The user from this token is bound to the session. |

No body.

## Response [#response]

### `200 OK` — `ApiResponseOf<IdentifySessionResultDto>` [#200-ok--apiresponseofidentifysessionresultdto]

```json
{ "success": true, "data": { "ok": true } }
```

### Errors [#errors]

| HTTP  | Reason                          |
| ----- | ------------------------------- |
| `401` | Missing / invalid bearer token. |

The endpoint has no documented `404` or `400` paths — bad session ids and DB failures collapse to a successful response.

## Side effects [#side-effects]

1. Decode bearer (global `JwtAuthGuard`); `userId = req.user.id`.
2. `analyticsDb.analyticsSession.update({ where: { id }, data: { userId } }).catch(() => {})`. Single SQL UPDATE; failures swallowed.
3. Return `{ ok: true }`.

**No throttle on this endpoint.** The class registers `@UseGuards(ThrottleGuard)` but this handler has no `@Throttle()` decorator and the guard returns `true` when no decorator is present. In practice clients should call it at most once per session (right after auth completes), so a missing throttle is fine.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'On-login hook']">
  <Tab value="curl">
    ```bash
    curl -X PATCH https://api.bio.re/api/v1/analytics/session/ses-uuid/identify \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function identifySession(
      accessToken: string,
      sessionId: string,
    ): Promise<void> {
      await fetch(`https://api.bio.re/api/v1/analytics/session/${sessionId}/identify`, {
        method: 'PATCH',
        headers: { Authorization: `Bearer ${accessToken}` },
      }).catch(() => {});
    }
    ```
  </Tab>

  <Tab value="On-login hook">
    ```ts
    // Run this once, immediately after a successful login/signup.
    // The session was started anonymously when the page first loaded.
    async function onLoginSuccess(accessToken: string) {
      const sessionId = window.__ANALYTICS_SESSION_ID__; // captured from createSession()
      if (!sessionId) return;
      await identifySession(accessToken, sessionId);
      // No need to re-fire; the binding persists for the lifetime of the session.
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/analytics/session/{id}/identify', method: 'patch' }]" hasHead="false" />

## Source [#source]

| Source            | Path                                                                       | Lines                                                                      |
| ----------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Controller        | `apps/api-core/src/modules/analytics/analytics.controller.ts`              | `179–188` (`identifySession`)                                              |
| DTO (response)    | `apps/api-core/src/modules/analytics/dto/analytics-client-response.dto.ts` | `50–53` (`IdentifySessionResultDto`)                                       |
| Service           | `apps/api-core/src/modules/analytics/traffic-tracking.service.ts`          | `215–220` (`identifyUser` — single UPDATE, silent fail)                    |
| Prisma model      | `packages/prisma-analytics/prisma/schema.prisma`                           | `AnalyticsSession.userId` line `49` (application-level FK to main DB User) |
| Throttle behavior | `apps/api-core/src/common/guards/throttle.guard.ts`                        | `43–48` (no decorator → `return true`)                                     |


# Track Event (/docs/analytics/track)



`POST /api/v1/analytics/track` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Records a named event (signup step, action, button click, …) attributed to the current user. This endpoint coexists with the public session-tracking endpoints — but **`track` writes to the main database** (`FunnelEvent` row in `@biore/prisma`), not the separate Analytics DB. Use it for funnel events that must be reliably joined to the user table; use [`POST /analytics/session`](/docs/analytics/session-create) + [`POST /analytics/pageview`](/docs/analytics/pageview) for traffic instrumentation.



<Callout type="info">
  **Killable from admin config.** The service reads `analytics.tracking_enabled` (string, default `'true'`). When set to anything other than `'true'`, the endpoint returns `200 { tracked: true }` without writing — clients see success but no row lands. Useful for kill-switching analytics during incidents without redeploying.
</Callout>

<Callout type="warn">
  **`properties` payload is size-capped.** Server reads `analytics.max_event_data_bytes` (default `10000`) and runs `validateEventData(properties, max)`. Anything over the cap throws `400 analytics.event.invalid_data`. Keep payloads small; for large analytics blobs use a dedicated endpoint or batch.
</Callout>

<Callout type="info">
  **Two databases, one module.** This endpoint writes to `prisma.funnelEvent` (main `@biore/prisma` Postgres). The session/pageview endpoints write to `analyticsDb` (`@biore/prisma-analytics` — a separate Postgres on the Analytics DB service). Funnel events are joinable to the User table; session events are not. Plan your queries accordingly.
</Callout>

## Request [#request]

### Body — `TrackEventDto` [#body--trackeventdto]

| Field        | Type   | Required | Validation | Notes                                                                                                                                                                                                                                         |
| ------------ | ------ | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event`      | string | ✓        | `IsString` | Event name (e.g. `signup_step_complete`, `bio_link_click`). No enum — free-form.                                                                                                                                                              |
| `sessionId`  | string | optional | `IsString` | Optional join key — typically the analytics session id from [`POST /session`](/docs/analytics/session-create) so funnel events can be correlated with traffic state. Stored verbatim — server doesn't validate it exists.                     |
| `deviceType` | string | optional | `IsString` | Free-form (`mobile` / `desktop` / `tablet`). Stored as-is on `FunnelEvent.eventData`? **No** — the column is dropped from persistence (only `event`, `userId`, `sessionId`, `eventData` are written). Pass it for API symmetry; it's ignored. |
| `locale`     | string | optional | `IsString` | Same as `deviceType` — accepted by the DTO but the service drops it from the write.                                                                                                                                                           |
| `properties` | object | optional | `IsObject` | Arbitrary JSON. Persisted as `FunnelEvent.eventData`. **Size-capped** (see warn callout).                                                                                                                                                     |

### Headers [#headers]

| Header                                | Required | Notes                                                                                   |
| ------------------------------------- | -------- | --------------------------------------------------------------------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | Global `JwtAuthGuard`. `userId` is forwarded from the JWT — clients cannot impersonate. |
| `Content-Type: application/json`      | ✓        | Standard.                                                                               |

## Response [#response]

### `200 OK` — `ApiResponseOf<TrackingResultDto>` [#200-ok--apiresponseoftrackingresultdto]

```json
{
  "success": true,
  "data": { "tracked": true }
}
```

| Field     | Type    | Notes                                                                                                                                                                                                                                                                             |
| --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tracked` | boolean | Always `true` when the request reaches the service. **Does not** signal that the row landed — both the kill switch (`analytics.tracking_enabled !== 'true'`) and a swallowed-DB-write path can produce `tracked: true` with no DB effect. Treat as a "request accepted" ack only. |

The controller hard-codes `@HttpCode(200)` so you don't get the framework default `201`.

### Errors [#errors]

| HTTP  | Code / `i18nKey`               | Reason                                                                                              |
| ----- | ------------------------------ | --------------------------------------------------------------------------------------------------- |
| `400` | `analytics.event.invalid_data` | `properties` failed `validateEventData` (size cap or invalid shape). Payload may include the limit. |
| `400` | (DTO validation)               | `event` missing / non-string.                                                                       |
| `401` | (guard)                        | Missing / invalid bearer token.                                                                     |
| `429` | `THROTTLE_LIMIT_EXCEEDED`      | Over 60 req/min from this IP. `retryAfter` (seconds) included in the response.                      |

## Side effects [#side-effects]

1. Decode bearer (global `JwtAuthGuard`); `userId = req.user.id`.
2. `ThrottleGuard` increments `throttle:<ip>:POST:/api/v1/analytics/track` in Redis cache (60-req / 60s window).
3. Read kill switch — `configService.getWithDefault('analytics.tracking_enabled', 'true')`. If not `'true'` → return `{ tracked: true }` with no further work.
4. Read size cap — `configService.getNumberWithDefault('analytics.max_event_data_bytes', 10000)`. Run `validateEventData(properties, max)`. Failure → throw `400`.
5. Build event row: `{ id: randomUUID(), userId, sessionId, eventType: event, eventData: properties ?? {} }`.
6. `prisma.funnelEvent.create({ data })` — **direct write to the main DB**, no queue. (A historical Redis-queued path was removed because the module never imported `RedisModule`.)
7. Increment `analyticsEventTrackedTotal` Prometheus counter.
8. Log `[analytics] Event tracked: <event> for user <userId>` (debug level).
9. Return `{ tracked: true }` (controller wraps as `{ success: true, data: { tracked: true } }`).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query (mutation)']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/analytics/track \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "event": "bio_link_click",
        "sessionId": "session-uuid-from-create",
        "properties": { "linkId": "abc-123", "position": 2 }
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type TrackInput = {
      event: string;
      sessionId?: string;
      properties?: Record<string, unknown>;
    };

    async function track(accessToken: string, input: TrackInput): Promise<void> {
      const res = await fetch('https://api.bio.re/api/v1/analytics/track', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      if (!res.ok) {
        const json = await res.json().catch(() => null);
        throw Object.assign(new Error(json?.error?.message ?? 'Track failed'), {
          code: json?.error?.code,
        });
      }
      // Don't await success — fire-and-forget at the call site if you don't care.
    }
    ```
  </Tab>

  <Tab value="TanStack Query (mutation)">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useTrackEvent() {
      return useMutation({
        mutationFn: async (input: TrackInput) => {
          const res = await fetch('/api/v1/analytics/track', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          if (!res.ok) {
            // Don't surface to the user — instrumentation failures shouldn't be UX errors.
            return;
          }
        },
        // Don't retry — duplicates are worse than missing one event.
        retry: false,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/analytics/track', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                       | Lines                                                                                                          |
| -------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/analytics/analytics.controller.ts`              | `52–59` (class), `68–78` (`track`)                                                                             |
| DTO (request)  | `apps/api-core/src/modules/analytics/dto/index.ts`                         | `9–15` (`TrackEventDto`)                                                                                       |
| DTO (response) | `apps/api-core/src/modules/analytics/dto/analytics-client-response.dto.ts` | `5–8` (`TrackingResultDto`)                                                                                    |
| Service        | `apps/api-core/src/modules/analytics/analytics.service.ts`                 | `23–46` (`trackEvent` — kill switch, size cap, direct DB write)                                                |
| Validation     | `apps/api-core/src/common/json-validators.ts`                              | `validateEventData` (size cap enforcement)                                                                     |
| Config keys    | (admin-managed)                                                            | `analytics.tracking_enabled` (string, kill switch), `analytics.max_event_data_bytes` (number, default `10000`) |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                                     | `FunnelEvent` lines `1681–1695` (main DB — NOT analytics DB)                                                   |


# Get Active Announcements (/docs/content/announcements)



`GET /api/v1/public/announcements` — 🌐 **Public** · Rate limit: **60 req / minute**

Returns active announcements — site-wide banners / notices admin-managed. Filter is `active: true AND startsAt <= now (or null) AND endsAt >= now (or null)`. **Cap is 50** (server-side `take: 50`). Each item's `content` is sanitized via the same helper as CMS pages (`<script>`, `<style>`, `<iframe>`, inline `on*` event handlers stripped). **Cache window is shorter than other content endpoints** (60s s-maxage, no SWR) — announcements need fresher reads (e.g. urgent maintenance notices).



<Callout type="info">
  **Time window is open-ended.** `startsAt: null` means "active from forever ago", `endsAt: null` means "active forever". Both sides nullable, both sides matched. A row with both null is "active until admin disables it".
</Callout>

<Callout type="warn">
  **Sanitization is defensive, not exhaustive.** Same caveat as `GET /public/pages/:slug` — strips obvious XSS but admin authors are still ultimately trusted. Use client-side sanitization for additional defense.
</Callout>

## Request [#request]

No body, no params, no headers required.

## Response headers [#response-headers]

| Header          | Value                 |
| --------------- | --------------------- |
| `Cache-Control` | `public, s-maxage=60` |

Note: shorter cache than other content endpoints (60s, no stale-while-revalidate). Urgent announcements should propagate quickly.

## Response [#response]

### `200 OK` — `ArrayApiResponseOf<PublicAnnouncementDto>` [#200-ok--arrayapiresponseofpublicannouncementdto]

```json
{
  "success": true,
  "data": [
    {
      "title": "Scheduled Maintenance",
      "content": "<p>We will be down for maintenance...</p>",
      "type": "MAINTENANCE",
      "locale": "en",
      "startsAt": "2026-05-01T00:00:00.000Z",
      "endsAt": "2026-05-01T02:00:00.000Z"
    },
    {
      "title": "Welcome to BIO.RE",
      "content": "<p>Thanks for joining...</p>",
      "type": "INFO",
      "locale": null,
      "startsAt": null,
      "endsAt": null
    }
  ]
}
```

### Item fields [#item-fields]

| Field      | Type                      | Notes                                                                                              |
| ---------- | ------------------------- | -------------------------------------------------------------------------------------------------- |
| `title`    | string                    | Announcement title                                                                                 |
| `content`  | string                    | Server-side sanitized HTML body                                                                    |
| `type`     | string                    | `INFO` / `WARNING` / `CRITICAL` / `MAINTENANCE` (admin-set; clients branch on this for color/icon) |
| `locale`   | string \| null            | Locale code; `null` means the announcement is locale-agnostic (shown to all locales)               |
| `startsAt` | string (ISO 8601) \| null | When the announcement becomes active. `null` = active from beginning.                              |
| `endsAt`   | string (ISO 8601) \| null | When it stops being active. `null` = no end date.                                                  |

### Stripped fields [#stripped-fields]

`id`, `active` (always true here, filter excludes false), `publishedBy`, `createdAt`, `updatedAt`, internal metadata — all excluded.

### Ordering [#ordering]

Server returns up to 50 rows ordered by `createdAt DESC` (newest first). There is no priority field exposed; admins control display order via timing.

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `429` | (throttle)         | Rate limit exceeded (60 req/min) |

## Side effects [#side-effects]

1. `prisma.announcement.findMany({ where: { active: true, OR: [startsAt null OR <= now], AND: [endsAt null OR >= now] }, orderBy: createdAt desc, take: 50 })`.
2. Map each row → strip internal fields, sanitize `content` via `sanitizeHtml()`.
3. Return the array. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/public/announcements
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type AnnouncementType = 'INFO' | 'WARNING' | 'CRITICAL' | 'MAINTENANCE';

    type PublicAnnouncement = {
      title: string;
      content: string;
      type: AnnouncementType | string;
      locale: string | null;
      startsAt: string | null;
      endsAt: string | null;
    };

    async function getActiveAnnouncements(): Promise<PublicAnnouncement[]> {
      const res = await fetch('https://api.bio.re/api/v1/public/announcements');
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Announcements fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const contentKeys = {
      announcements: () => ['content', 'announcements'] as const,
    };

    export function useActiveAnnouncements() {
      return useQuery({
        queryKey: contentKeys.announcements(),
        queryFn: async () => {
          const res = await fetch('/api/v1/public/announcements');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Announcements fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as PublicAnnouncement[];
        },
        // Match the shorter cache window — announcements need fresh reads
        staleTime: 60_000,
        refetchOnWindowFocus: true,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/public/announcements', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source              | Path                                                                   | Lines                                                          |
| ------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------- |
| Controller          | `apps/api-core/src/modules/content/public-content.controller.ts`       | `269–285` (`getActiveAnnouncements`), `29–36` (`sanitizeHtml`) |
| DTO (response item) | `apps/api-core/src/modules/content/dto/content-public-response.dto.ts` | `146–164` (`PublicAnnouncementDto`)                            |
| Service             | `apps/api-core/src/modules/content/content.service.ts`                 | `389–400` (`getActiveAnnouncements`)                           |
| Prisma model        | `packages/prisma/prisma/schema.prisma`                                 | `Announcement` (filter `active = true` + time window)          |


# Blog Atom Feed (/docs/content/blog-feed-atom)



`GET /api/v1/public/blog/feed.atom` — 🌐 **Public** · Rate limit: **30 req / minute**

Returns the last 20 published blog posts as an **Atom XML feed** — same data as `GET /public/blog/feed` (RSS 2.0) in Atom format. Use this for clients that prefer Atom (more strict spec, ISO 8601 timestamps).



<Callout type="info">
  **Same data, different format.** RSS and Atom present the same 20 posts — pick whichever your reader prefers. Most modern feed readers handle both. Atom is generally preferred for new clients (cleaner spec, ISO 8601 timestamps), RSS for compatibility with older readers.
</Callout>

<Callout type="warn">
  **Different response shape from the rest of the portal.** Returns raw XML with `Content-Type: application/atom+xml; charset=utf-8` — NOT the standard JSON envelope. Same caveat as the RSS feed.
</Callout>

## Request [#request]

No body, no params, no headers required.

## Response headers [#response-headers]

| Header          | Value                                               |
| --------------- | --------------------------------------------------- |
| `Content-Type`  | `application/atom+xml; charset=utf-8`               |
| `Cache-Control` | `public, s-maxage=900, stale-while-revalidate=1800` |

## Response [#response]

### `200 OK` — Atom XML [#200-ok--atom-xml]

```xml
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>BIO.RE Blog</title>
  <link href="https://bio.re/blog" rel="alternate"/>
  <link href="https://bio.re/api/v1/public/blog/feed.atom" rel="self"/>
  <id>https://bio.re/blog</id>
  <updated>2026-04-29T20:00:00.000Z</updated>
  <entry>
    <title>Introducing BIO.RE</title>
    <link href="https://bio.re/blog/introducing-biore"/>
    <id>https://bio.re/blog/introducing-biore</id>
    <updated>2026-04-29T20:00:00.000Z</updated>
    <summary><![CDATA[A short excerpt of the post...]]></summary>
  </entry>
</feed>
```

### XML elements [#xml-elements]

| Element                                                     | Source    | Notes                                                                  |
| ----------------------------------------------------------- | --------- | ---------------------------------------------------------------------- |
| `feed.title`                                                | hardcoded | `BIO.RE Blog`                                                          |
| `feed.link[rel=alternate]`                                  | hardcoded | `https://bio.re/blog` (the human-readable blog)                        |
| `feed.link[rel=self]`                                       | hardcoded | This feed's URL                                                        |
| `feed.id`                                                   | hardcoded | `https://bio.re/blog`                                                  |
| `feed.updated`                                              | computed  | The most recent `publishedAt` of any item, formatted as ISO 8601 (UTC) |
| `entry.title` / `entry.link` / `entry.id` / `entry.updated` | per post  | Individual post metadata. Title is XML-escaped server-side.            |
| `entry.summary`                                             | per post  | The post's `excerpt` (or empty), wrapped in `CDATA[]`                  |

Note: Atom feed does **not** include `<category>` elements (RSS-only). If you need category data, use the JSON `GET /public/blog` list.

### Errors [#errors]

| HTTP  | Reason                           |
| ----- | -------------------------------- |
| `429` | Rate limit exceeded (30 req/min) |

## Side effects [#side-effects]

1. `getBlogFeedItems()` — same call as the RSS feed (last 20 published, same selection).
2. Build Atom XML string by concatenation. Each user-controllable field passes through `xmlEscape()`.
3. Set `Content-Type: application/atom+xml; charset=utf-8` + cache header on the raw response.
4. Return the XML body. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'Feed reader (URL)', 'Server-side parse (Node)']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/public/blog/feed.atom
    ```
  </Tab>

  <Tab value="Feed reader (URL)">
    ```
    https://api.bio.re/api/v1/public/blog/feed.atom
    ```

    Paste this URL into a feed reader that supports Atom (most modern ones — NetNewsWire, Feedly, Reeder, Inoreader).
  </Tab>

  <Tab value="Server-side parse (Node)">
    ```ts
    // Server-side — fetch + parse with rss-parser (handles Atom too)
    import Parser from 'rss-parser';

    const parser = new Parser();

    async function fetchBlogAtomFeed() {
      const feed = await parser.parseURL('https://api.bio.re/api/v1/public/blog/feed.atom');
      for (const item of feed.items) {
        console.log(item.title, item.link, item.isoDate);
      }
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/public/blog/feed.atom', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source             | Path                                                                  | Lines                                                                           |
| ------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Controller         | `apps/api-core/src/modules/content/public-content.controller.ts`      | `224–237` (`getBlogAtomFeed`), `145–147` (`xmlEscape`), `181–207` (`buildAtom`) |
| Service            | `apps/api-core/src/modules/content/content.service.ts`                | `578–...` (`getBlogFeedItems` — shared with RSS feed)                           |
| Prisma model       | `packages/prisma/prisma/schema.prisma`                                | `BlogPost` (filter `status = PUBLISHED`)                                        |
| Bot detection skip | `apps/api-core/src/common/decorators/skip-bot-detection.decorator.ts` | `@SkipBotDetection()`                                                           |


# Blog RSS Feed (/docs/content/blog-feed-rss)



`GET /api/v1/public/blog/feed` — 🌐 **Public** · Rate limit: **30 req / minute**

Returns the last 20 published blog posts as an **RSS 2.0 XML feed** for feed readers (NetNewsWire, Feedly, Reeder, etc). **Bot-detection is skipped** (`@SkipBotDetection()`) — feed readers are bot-like and shouldn't be challenged. Cached 15min at the CDN with 30min stale-while-revalidate.



<Callout type="warn">
  **Different response shape from the rest of the portal.** This endpoint returns **raw XML** with `Content-Type: application/rss+xml; charset=utf-8` — NOT the standard JSON `{ success, data }` envelope. Consume with an XML parser (or just hand to your feed reader). The standard error envelope still applies for 4xx/5xx, but the success path is XML.
</Callout>

<Callout type="info">
  **Cap is 20 (lower than the regular list).** Feeds are designed for "what's new" — the last 20 posts is plenty. The regular `/public/blog` endpoint serves up to 50 per page with full pagination if you need older posts.
</Callout>

## Request [#request]

No body, no params, no headers required.

## Response headers [#response-headers]

| Header          | Value                                               |
| --------------- | --------------------------------------------------- |
| `Content-Type`  | `application/rss+xml; charset=utf-8`                |
| `Cache-Control` | `public, s-maxage=900, stale-while-revalidate=1800` |

## Response [#response]

### `200 OK` — RSS 2.0 XML [#200-ok--rss-20-xml]

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
  <title>BIO.RE Blog</title>
  <link>https://bio.re/blog</link>
  <description>Latest posts from the BIO.RE blog</description>
  <language>en</language>
  <lastBuildDate>Wed, 29 Apr 2026 20:00:00 GMT</lastBuildDate>
  <atom:link href="https://bio.re/api/v1/public/blog/feed" rel="self" type="application/rss+xml"/>
  <item>
    <title>Introducing BIO.RE</title>
    <link>https://bio.re/blog/introducing-biore</link>
    <guid isPermaLink="true">https://bio.re/blog/introducing-biore</guid>
    <description><![CDATA[A short excerpt of the post...]]></description>
    <pubDate>Wed, 29 Apr 2026 20:00:00 GMT</pubDate>
    <category>Product Updates</category>
  </item>
</channel>
</rss>
```

### XML elements [#xml-elements]

| Element                                                   | Source            | Notes                                                                    |
| --------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------ |
| `channel.title`                                           | hardcoded         | `BIO.RE Blog`                                                            |
| `channel.link`                                            | hardcoded         | `https://bio.re/blog`                                                    |
| `channel.description`                                     | hardcoded         | `Latest posts from the BIO.RE blog`                                      |
| `channel.language`                                        | hardcoded         | `en`                                                                     |
| `channel.lastBuildDate`                                   | computed          | The most recent `publishedAt` of any item, formatted as RFC 822 (UTC)    |
| `channel.atom:link`                                       | hardcoded         | Self-link to this feed                                                   |
| `item.title` / `item.link` / `item.guid` / `item.pubDate` | per post          | Individual post metadata. Title is XML-escaped server-side.              |
| `item.description`                                        | per post          | The post's `excerpt` (or empty), wrapped in `CDATA[]`                    |
| `item.category`                                           | per post category | One `<category>` element per associated `BlogCategory.name`, XML-escaped |

### Errors [#errors]

| HTTP  | Reason                                                        |
| ----- | ------------------------------------------------------------- |
| `429` | Rate limit exceeded (30 req/min — tighter than the JSON list) |

## Side effects [#side-effects]

1. `getBlogFeedItems()` — `prisma.blogPost.findMany({ where: status PUBLISHED, orderBy publishedAt desc, take: 20, select: slug+title+excerpt+publishedAt+categories })`.
2. Build XML string by concatenation. Each user-controllable field passes through `xmlEscape()` (replaces `&`, `<`, `>`, `"`, `'` with entities).
3. Set `Content-Type: application/rss+xml; charset=utf-8` + cache header on the raw response (`@Res()` mode — bypasses the standard interceptor).
4. Return the XML body. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'Feed reader (URL)', 'Server-side parse (Node)']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/public/blog/feed
    ```
  </Tab>

  <Tab value="Feed reader (URL)">
    ```
    https://api.bio.re/api/v1/public/blog/feed
    ```

    Paste this URL into NetNewsWire / Feedly / Reeder / Inoreader. Most feed readers will auto-detect the format and start polling.
  </Tab>

  <Tab value="Server-side parse (Node)">
    ```ts
    // Server-side — fetch + parse with rss-parser
    import Parser from 'rss-parser';

    const parser = new Parser();

    async function fetchBlogFeed() {
      const feed = await parser.parseURL('https://api.bio.re/api/v1/public/blog/feed');
      for (const item of feed.items) {
        console.log(item.title, item.link, item.pubDate);
      }
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/public/blog/feed', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source             | Path                                                                  | Lines                                                                                       |
| ------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Controller         | `apps/api-core/src/modules/content/public-content.controller.ts`      | `209–222` (`getBlogRssFeed`), `145–147` (`xmlEscape`), `149–179` (`buildRss2`)              |
| Service            | `apps/api-core/src/modules/content/content.service.ts`                | `578–...` (`getBlogFeedItems` — slug+title+excerpt+publishedAt+categories slice)            |
| Prisma model       | `packages/prisma/prisma/schema.prisma`                                | `BlogPost` (filter `status = PUBLISHED`), `BlogCategory` (joined for `<category>` elements) |
| Bot detection skip | `apps/api-core/src/common/decorators/skip-bot-detection.decorator.ts` | `@SkipBotDetection()`                                                                       |


# List Blog Posts (/docs/content/blog-list)



`GET /api/v1/public/blog` — 🌐 **Public** · Rate limit: **60 req / minute**

Returns a paginated list of published blog posts. **PUBLISHED-only filter** server-side. Each item carries the slug + title + excerpt + featured image + publishedAt + embedded categories — **no body** (use `GET /public/blog/:slug` for the full content). Optional `?category=<slug>` filter.



<Callout type="info">
  **Lightweight by design.** The list intentionally excludes the full HTML body — keeps the payload small for index pages with many posts. Render the excerpt + featured image in the card; lazy-load the full content via `GET /public/blog/:slug` on click.
</Callout>

<Callout type="warn">
  **Limit clamped at 50.** Server enforces `min(max(limit, 1), 50)`. The default is 20.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param      | Type   | Default | Validation                                  | Notes                                                                 |
| ---------- | ------ | ------- | ------------------------------------------- | --------------------------------------------------------------------- |
| `page`     | number | `1`     | `ParseIntPipe`, server-clamped to `>= 1`    | 1-based page index                                                    |
| `limit`    | number | `20`    | `ParseIntPipe`, server-clamped to `[1, 50]` | Items per page                                                        |
| `category` | string | —       | —                                           | Filter by `BlogCategory.slug` (e.g. `product-updates`, `engineering`) |

No headers required.

## Response headers [#response-headers]

| Header          | Value                                              |
| --------------- | -------------------------------------------------- |
| `Cache-Control` | `public, s-maxage=300, stale-while-revalidate=600` |

## Response [#response]

### `200 OK` — `ApiResponseOf<PublicBlogListDataDto>` [#200-ok--apiresponseofpublicbloglistdatadto]

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "slug": "introducing-biore",
        "title": "Introducing BIO.RE",
        "excerpt": "A short excerpt of the post...",
        "featuredImage": "https://cdn.bio.re/blog/cover.jpg",
        "publishedAt": "2026-04-29T20:00:00.000Z",
        "categories": [
          { "name": "Product Updates", "slug": "product-updates" }
        ]
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}
```

### Item fields [#item-fields]

| Field           | Type                      | Notes                                                                    |
| --------------- | ------------------------- | ------------------------------------------------------------------------ |
| `slug`          | string                    | Pass to `GET /public/blog/:slug` for the body                            |
| `title`         | string                    | Display title                                                            |
| `excerpt`       | string \| null            | Short summary for cards                                                  |
| `featuredImage` | string \| null            | Cover image URL                                                          |
| `publishedAt`   | string (ISO 8601) \| null | When the post was published                                              |
| `categories`    | array                     | `{ name, slug }` pairs — categories embedded for filter UI / breadcrumbs |

### Top-level fields [#top-level-fields]

| Field                           | Type   | Notes                                              |
| ------------------------------- | ------ | -------------------------------------------------- |
| `items`                         | array  | Up to `limit` posts, ordered by `publishedAt DESC` |
| `total`                         | number | Total matching the filter                          |
| `page` / `limit` / `totalPages` | number | Echoed pagination metadata                         |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `429` | (throttle)         | Rate limit exceeded (60 req/min) |

## Side effects [#side-effects]

1. Clamp `page = max(page, 1)`, `limit = min(max(limit, 1), 50)`.
2. Build `where` — `status = PUBLISHED`, plus optional `categories: { some: { category: { slug: categorySlug } } }` filter when `category` provided.
3. **In parallel**: `blogPost.findMany({ where, orderBy: publishedAt desc, include: { categories: { include: { category: true } } }, skip, take })` + `count({ where })`.
4. Map each row → strip internal fields, project category embed to `{ name, slug }`.
5. Return paginated envelope. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    # All blog posts
    curl 'https://api.bio.re/api/v1/public/blog?page=1&limit=20'

    # Filtered by category
    curl 'https://api.bio.re/api/v1/public/blog?category=product-updates'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type BlogCategoryEmbed = {
      name: string;
      slug: string;
    };

    type BlogListItem = {
      slug: string;
      title: string;
      excerpt: string | null;
      featuredImage: string | null;
      publishedAt: string | null;
      categories: BlogCategoryEmbed[];
    };

    type BlogListData = {
      items: BlogListItem[];
      total: number;
      page: number;
      limit: number;
      totalPages: number;
    };

    async function listBlogPosts(
      filter: { page?: number; limit?: number; category?: string } = {},
    ): Promise<BlogListData> {
      const url = new URL('https://api.bio.re/api/v1/public/blog');
      if (filter.page) url.searchParams.set('page', String(filter.page));
      if (filter.limit) url.searchParams.set('limit', String(filter.limit));
      if (filter.category) url.searchParams.set('category', filter.category);
      const res = await fetch(url);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Blog list fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery, keepPreviousData } from '@tanstack/react-query';

    export const contentKeys = {
      blogList: (filter: { page?: number; limit?: number; category?: string }) =>
        ['content', 'blog', 'list', filter] as const,
    };

    export function useBlogList(filter: { page?: number; limit?: number; category?: string } = {}) {
      return useQuery({
        queryKey: contentKeys.blogList(filter),
        queryFn: async () => {
          const url = new URL('/api/v1/public/blog', window.location.origin);
          if (filter.page) url.searchParams.set('page', String(filter.page));
          if (filter.limit) url.searchParams.set('limit', String(filter.limit));
          if (filter.category) url.searchParams.set('category', filter.category);
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Blog list fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as BlogListData;
        },
        placeholderData: keepPreviousData, // smooth pagination
        staleTime: 5 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/public/blog', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                                                         |
| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/content/public-content.controller.ts`       | `101–136` (`listBlogPosts`)                                                                                   |
| DTO (response) | `apps/api-core/src/modules/content/dto/content-public-response.dto.ts` | `96–111` (`PublicBlogListDataDto`), `73–91` (`PublicBlogListItemDto`), `61–67` (`PublicBlogCategoryEmbedDto`) |
| Service        | `apps/api-core/src/modules/content/content.service.ts`                 | `551–572` (`listPublishedBlogPosts`)                                                                          |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                                 | `BlogPost` (filter `status = PUBLISHED`), `BlogCategory` (embedded via join), `enum ContentStatus`            |


# Get Blog Post (by slug) (/docs/content/blog-post)



`GET /api/v1/public/blog/:slug` — 🌐 **Public** · Rate limit: **60 req / minute**

Returns a single blog post by slug. **PUBLISHED-only** — DRAFT / ARCHIVED slugs return `404`. The HTML body is **server-side sanitized** (same `sanitizeHtml()` helper as CMS pages — strips `<script>`, `<style>`, `<iframe>`, inline `on*` event handlers).



<Callout type="info">
  **Route order matters.** The controller declares `/blog/feed` and `/blog/feed.atom` BEFORE `/blog/:slug` — without that ordering, NestJS would match `feed` and `feed.atom` as slug parameters and 404 the actual feed lookups. From a client perspective this is invisible, but reserved slugs `feed` and `feed.atom` will never resolve to a post here.
</Callout>

<Callout type="warn">
  **Sanitization is defensive, not exhaustive.** Same caveat as `GET /public/pages/:slug` — strips obvious XSS but admin authors are still ultimately trusted. Use client-side sanitization (DOMPurify) for additional defense.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param  | Type   | Notes                                                                                                                               |
| ------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `slug` | string | Blog post slug (e.g. `introducing-biore`). Reserved values `feed` and `feed.atom` are intercepted by the feed routes (see callout). |

No body, no headers required.

## Response headers [#response-headers]

| Header          | Value                                              |
| --------------- | -------------------------------------------------- |
| `Cache-Control` | `public, s-maxage=300, stale-while-revalidate=600` |

## Response [#response]

### `200 OK` — `ApiResponseOf<PublicBlogPostDto>` [#200-ok--apiresponseofpublicblogpostdto]

```json
{
  "success": true,
  "data": {
    "slug": "introducing-biore",
    "title": "Introducing BIO.RE",
    "excerpt": "A short excerpt of the post...",
    "content": "<p>Sanitized HTML content</p>",
    "featuredImage": "https://cdn.bio.re/blog/cover.jpg",
    "publishedAt": "2026-04-29T20:00:00.000Z",
    "categories": [
      { "name": "Product Updates", "slug": "product-updates" }
    ]
  }
}
```

| Field           | Type                      | Notes                                                     |
| --------------- | ------------------------- | --------------------------------------------------------- |
| `slug`          | string                    | Echoes the path param                                     |
| `title`         | string                    | Post title                                                |
| `excerpt`       | string \| null            | Short summary (also shown in the list endpoint)           |
| `content`       | string                    | Server-side sanitized HTML body                           |
| `featuredImage` | string \| null            | Cover image URL                                           |
| `publishedAt`   | string (ISO 8601) \| null | When the post was published                               |
| `categories`    | array                     | `{ name, slug }` pairs for breadcrumbs / related-posts UI |

### Stripped fields [#stripped-fields]

`id`, `status`, `publishedBy`, `authorId`, `createdAt`, `updatedAt` — all internal-only, excluded.

### Errors [#errors]

| HTTP  | `code` / `i18nKey`             | Reason                                                |
| ----- | ------------------------------ | ----------------------------------------------------- |
| `404` | `error.content.blog_not_found` | No `BlogPost` matches `slug` AND `status = PUBLISHED` |
| `429` | (throttle)                     | Rate limit exceeded (60 req/min)                      |

## Side effects [#side-effects]

1. `prisma.blogPost.findFirst({ where: { slug, status: PUBLISHED }, include: { categories: { include: { category: true } } } })`.
2. Missing → throw `blog_not_found` (404).
3. **HTML sanitization** — `sanitizeHtml(post.content)` (same helper as CMS pages — script/style/iframe/on\* strips).
4. Map categories from join shape `{ category: { name, slug } }` to flat `{ name, slug }`.
5. Return assembled object. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/public/blog/introducing-biore
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type BlogPost = {
      slug: string;
      title: string;
      excerpt: string | null;
      content: string;
      featuredImage: string | null;
      publishedAt: string | null;
      categories: { name: string; slug: string }[];
    };

    async function getBlogPost(slug: string): Promise<BlogPost> {
      const res = await fetch(`https://api.bio.re/api/v1/public/blog/${encodeURIComponent(slug)}`);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Blog post fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const contentKeys = {
      blogPost: (slug: string) => ['content', 'blog', 'post', slug] as const,
    };

    export function useBlogPost(slug: string) {
      return useQuery({
        queryKey: contentKeys.blogPost(slug),
        queryFn: async () => {
          const res = await fetch(`/api/v1/public/blog/${encodeURIComponent(slug)}`);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Blog post fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as BlogPost;
        },
        enabled: Boolean(slug),
        staleTime: 5 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/public/blog/{slug}', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                                       |
| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/content/public-content.controller.ts`       | `239–263` (`getBlogPost`), `29–36` (`sanitizeHtml`)                                         |
| DTO (response) | `apps/api-core/src/modules/content/dto/content-public-response.dto.ts` | `117–138` (`PublicBlogPostDto`), `61–67` (`PublicBlogCategoryEmbedDto`)                     |
| Service        | `apps/api-core/src/modules/content/content.service.ts`                 | `547–549` (`getBlogPost`)                                                                   |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                                 | `BlogPost` (filter `status = PUBLISHED`), `BlogCategory` (joined via `categories` relation) |


# Submit Contact Form (/docs/content/contact)



`POST /api/v1/public/contact` — 🌐 **Public** · Rate limit: **3 req / hour** · CaptchaGuard

Public contact form submission. &#x2A;*Hard rate limit (3/hour)** — designed for legitimate use, not bulk submissions. **Captcha-gated** via the active captcha provider (admin-managed via `external.captcha.active_provider`). The server captures `User-Agent` + IP from the request headers, persists a `ContactMessage` row, and fires a fire-and-forget admin notification.



<Callout type="warn">
  **Captcha required**: include `captchaToken` in the body (the token from the active captcha provider's widget on the client). The `CaptchaGuard` validates it server-side via the active provider's verify endpoint. Vendor identity stays server-side — clients use whatever captcha widget the platform serves; no need to know which provider is active.
</Callout>

<Callout type="info">
  **`turnstileToken` is deprecated**: kept for 1-sprint backwards compatibility — accepts the same value as `captchaToken`. New clients should use `captchaToken` only. The deprecated alias may be removed in a future iteration.
</Callout>

<Callout type="warn">
  **IP capture is privacy-aware**: the server resolves the client IP with priority `cf-connecting-ip` style CDN header → first entry of `x-forwarded-for` → `req.ip`. The IP is **stored** on the `ContactMessage` row for support / abuse tracking but never exposed in any read endpoint. Same pattern as the bio analytics tracking endpoint.
</Callout>

## Request [#request]

### Body — `SubmitContactDto` [#body--submitcontactdto]

| Field            | Type   | Required              | Validation                                    | Notes                                                                                                                       |
| ---------------- | ------ | --------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `name`           | string | optional              | `MaxLength(100)`                              | Sender's name. Stored as null when omitted.                                                                                 |
| `email`          | string | ✓                     | `IsEmail()`, lowercased + trimmed server-side | Sender's email                                                                                                              |
| `subject`        | string | ✓                     | `MinLength(3)`, `MaxLength(200)`              | Subject line                                                                                                                |
| `message`        | string | ✓                     | `MinLength(10)`, `MaxLength(5000)`            | Free-form message body                                                                                                      |
| `captchaToken`   | string | conditional           | `IsString()`                                  | Captcha token from the active provider. &#x2A;*Required by `CaptchaGuard`** unless skip-captcha is enabled in admin config. |
| `turnstileToken` | string | optional (deprecated) | `IsString()`                                  | Deprecated alias for `captchaToken` — accepted for 1 sprint backwards compat.                                               |

No headers required (other than the implicit `User-Agent` which the server reads).

## Response [#response]

### `200 OK` [#200-ok]

```json
{
  "success": true,
  "data": {
    "message": "Thank you for your message. We will respond shortly."
  }
}
```

The controller uses `@HttpCode(HttpStatus.OK)` (not the default `201` for POST). The service returns `{ message }`; the platform's response interceptor wraps it in `{ success: true, data: ... }`.

| Field     | Type   | Notes                                                    |
| --------- | ------ | -------------------------------------------------------- |
| `message` | string | Localizable confirmation message — render under the form |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                                                                                   |
| ----- | ------------------ | ---------------------------------------------------------------------------------------- |
| `400` | (DTO validation)   | Missing required fields; `email` not a valid format; subject/message length out of range |
| `400` | (CaptchaGuard)     | Missing or invalid `captchaToken` (specific code from the active provider)               |
| `429` | (throttle)         | Rate limit exceeded (3 req/hour)                                                         |

## Side effects [#side-effects]

1. **CaptchaGuard** runs first — verifies `captchaToken` (or `turnstileToken` legacy alias) against the active provider's verify API. Failure → 400.
2. Resolve client IP with priority: `cf-connecting-ip` style CDN header → first entry of `x-forwarded-for` → `req.ip`.
3. `prisma.contactMessage.create({ id: randomUUID(), name: input.name ?? null, email: input.email, subject, message, userAgent: req.headers['user-agent'] ?? null, ipAddress: <resolved IP> ?? null })`.
4. **Fire-and-forget admin notification** — `notificationService.send({ eventKey: 'contact_form_submission', userId: 'system', variables: { name (or 'Anonymous'), email, subject, message: <first 500 chars> } })`. Failure is logged at error level but does NOT fail the request.
5. Audit log: `[contact] Contact form submitted: <email> — <subject>`.
6. Return `{ message: 'Thank you for your message. We will respond shortly.' }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/public/contact \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "John Doe",
        "email": "john@example.com",
        "subject": "Feature Request",
        "message": "I would like to suggest a new feature for the platform.",
        "captchaToken": "<token-from-active-captcha-widget>"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type SubmitContactInput = {
      name?: string;
      email: string;
      subject: string;
      message: string;
      captchaToken?: string;
    };

    async function submitContact(input: SubmitContactInput): Promise<string> {
      const res = await fetch('https://api.bio.re/api/v1/public/contact', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Contact submit failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.message as string;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useSubmitContact() {
      return useMutation({
        mutationFn: async (input: SubmitContactInput) => {
          const res = await fetch('/api/v1/public/contact', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Contact submit failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.message as string;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/public/contact', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source                | Path                                                             | Lines                                                                                  |
| --------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Controller            | `apps/api-core/src/modules/content/public-content.controller.ts` | `400–413` (`submitContact`)                                                            |
| DTO (request)         | `apps/api-core/src/modules/content/dto/submit-contact.dto.ts`    | `5–36` (`SubmitContactDto`)                                                            |
| Service               | `apps/api-core/src/modules/content/content.service.ts`           | `901–...` (`submitContact`)                                                            |
| Captcha guard         | `apps/api-core/src/common/guards/captcha.guard.ts`               | `CaptchaGuard` (active provider, admin-managed via `external.captcha.active_provider`) |
| Notification pipeline | `apps/api-core/src/modules/notification/notification.service.ts` | `send({ eventKey: 'contact_form_submission' })` (fire-and-forget)                      |
| Prisma model          | `packages/prisma/prisma/schema.prisma`                           | `ContactMessage` (stores `userAgent`, `ipAddress` server-side; never exposed in reads) |


# Get Cookie Policy (/docs/content/cookie-policy)



`GET /api/v1/consent/cookies/policy` — 🌐 **Public**

Returns the cookie consent policy — the **4 cookie categories** with their localized name/description and the `required` flag (only `essential` is required). The catalog is currently **hardcoded server-side** (`COOKIE_CATEGORIES` constant in the controller); admin configurability would require a CMS-managed migration.



<Callout type="info">
  **Localization is hardcoded to `en` + `tr`.** The `name` and `description` fields are fixed objects with `en` and `tr` keys; no other locales are returned. To add a locale, the server-side constant needs to be expanded — the API contract supports adding more keys to the same object shape, but the response will still be a single object containing every supported locale (clients pick the locale they need).
</Callout>

<Callout type="warn">
  **`required: true` for essential cookies.** Render the essential category as non-toggleable in the consent banner — the user can't opt out. The `POST /consent/cookies` body only accepts `analytics`, `marketing`, `functional` flags; the essential set is always on.
</Callout>

## Request [#request]

No body, no params, no headers required.

## Response [#response]

### `200 OK` — `ApiResponseOf<CookiePolicyDto>` [#200-ok--apiresponseofcookiepolicydto]

```json
{
  "success": true,
  "data": {
    "categories": [
      {
        "id": "essential",
        "required": true,
        "name": { "en": "Essential", "tr": "Zorunlu" },
        "description": { "en": "Required for the site to function", "tr": "Sitenin çalışması için gerekli" }
      },
      {
        "id": "functional",
        "required": false,
        "name": { "en": "Functional", "tr": "İşlevsel" },
        "description": { "en": "Enhanced functionality", "tr": "Gelişmiş işlevsellik" }
      },
      {
        "id": "analytics",
        "required": false,
        "name": { "en": "Analytics", "tr": "Analitik" },
        "description": { "en": "Anonymous usage statistics", "tr": "Anonim kullanım istatistikleri" }
      },
      {
        "id": "marketing",
        "required": false,
        "name": { "en": "Marketing", "tr": "Pazarlama" },
        "description": { "en": "Personalized content", "tr": "Kişiselleştirilmiş içerik" }
      }
    ]
  }
}
```

### Item fields [#item-fields]

| Field                               | Type    | Notes                                                                      |
| ----------------------------------- | ------- | -------------------------------------------------------------------------- |
| `id`                                | string  | Stable identifier — `essential` / `functional` / `analytics` / `marketing` |
| `required`                          | boolean | `true` only for `essential`. Render non-toggleable in the banner.          |
| `name.en` / `name.tr`               | string  | Localized display name                                                     |
| `description.en` / `description.tr` | string  | Localized short description                                                |

### Errors [#errors]

This endpoint has no documented errors — no throttle, no kill switch. Always 200.

## Side effects [#side-effects]

1. Return the hardcoded `COOKIE_CATEGORIES` constant array. &#x2A;*No DB read, no mutations, no per-user state.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/consent/cookies/policy
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type LocalizedText = {
      en: string;
      tr: string;
    };

    type CookieCategory = {
      id: 'essential' | 'functional' | 'analytics' | 'marketing';
      required: boolean;
      name: LocalizedText;
      description: LocalizedText;
    };

    type CookiePolicy = {
      categories: CookieCategory[];
    };

    async function getCookiePolicy(): Promise<CookiePolicy> {
      const res = await fetch('https://api.bio.re/api/v1/consent/cookies/policy');
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Cookie policy fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const consentKeys = {
      cookiePolicy: () => ['consent', 'cookies', 'policy'] as const,
    };

    export function useCookiePolicy() {
      return useQuery({
        queryKey: consentKeys.cookiePolicy(),
        queryFn: async () => {
          const res = await fetch('/api/v1/consent/cookies/policy');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Cookie policy fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as CookiePolicy;
        },
        // Hardcoded constant — cache aggressively
        staleTime: Infinity,
        gcTime: 24 * 60 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/consent/cookies/policy', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                                               |
| -------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/content/cookie-consent.controller.ts`       | `50–56` (`getPolicy`), `22–43` (`COOKIE_CATEGORIES` hardcoded constant)                             |
| DTO (response) | `apps/api-core/src/modules/content/dto/content-public-response.dto.ts` | `346–349` (`CookiePolicyDto`), `329–341` (`CookieCategoryDto`), `318–324` (`CookieCategoryNameDto`) |


# Save Cookie Consent (/docs/content/cookie-save)



`POST /api/v1/consent/cookies` — 🌐 **Public** · Rate limit: **10 req / minute**

Saves the user's cookie consent choices to a new `ConsentRecord` row. **Works for both anonymous and authenticated users** — the bearer is optional; anonymous saves get `userId: null`. The version stored is the current `legal.privacy_version` config (so `GET /consent/cookies/status` will return `requiresReConsent: false` immediately after).



<Callout type="warn">
  **GDPR-aware IP capture**: the user's IP is ONLY persisted when they explicitly consent to analytics (`body.analytics === true`). When analytics consent is `false`, the row is created with `ipAddress: null` regardless of what the request actually carried. The user-agent is always captured (less identifying).
</Callout>

<Callout type="info">
  **No "essential" toggle in the body.** The 4-category policy returns `essential` as `required: true` — but the body only accepts `analytics`, `marketing`, `functional`. Essential cookies are always enabled and don't need an opt-in flag.
</Callout>

<Callout type="warn">
  **Append-only — no upsert.** Each call creates a new `ConsentRecord` row. Re-running consent doesn't replace the previous row; it appends. The `GET /consent/cookies/status` endpoint reads the **most recent** row (`orderBy createdAt desc`), so the newest consent wins.
</Callout>

## Request [#request]

### Body — `CookieConsentDto` [#body--cookieconsentdto]

| Field        | Type    | Required | Validation    | Notes                                                          |
| ------------ | ------- | -------- | ------------- | -------------------------------------------------------------- |
| `analytics`  | boolean | ✓        | `IsBoolean()` | True = analytics cookies allowed AND IP gets stored on the row |
| `marketing`  | boolean | ✓        | `IsBoolean()` | True = marketing/personalization cookies allowed               |
| `functional` | boolean | ✓        | `IsBoolean()` | True = functional cookies allowed                              |

| Header                                | Required | Notes                                                                                                     |
| ------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `Authorization: Bearer <accessToken>` | optional | When present, the row is tied to `userId`. When absent, the row's `userId` is `null` (anonymous consent). |

## Response [#response]

### `200 OK` — `ApiResponseOf<ConsentSavedDto>` [#200-ok--apiresponseofconsentsaveddto]

```json
{
  "success": true,
  "data": {
    "saved": true
  }
}
```

| Field   | Type    | Notes                |
| ------- | ------- | -------------------- |
| `saved` | boolean | Always `true` on 200 |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `400` | (DTO validation)   | Missing fields; not a boolean    |
| `429` | (throttle)         | Rate limit exceeded (10 req/min) |

## Side effects [#side-effects]

1. Resolve client IP — priority `cf-connecting-ip` style CDN header → first entry of `x-forwarded-for` → `req.ip`. (May be undefined if none of those resolve.)
2. Read `legal.privacy_version` from `ConfigService` (default `'1.0'`).
3. `prisma.consentRecord.create({ id: randomUUID(), userId: userId ?? null, documentType: 'COOKIE_CONSENT', documentVersion: <currentVersion>, accepted: true, preferences: { analytics, marketing, functional }, ipAddress: body.analytics ? clientIp : null, userAgent: req.headers['user-agent'] ?? null })`.
4. **`accepted` is always `true`** on this row — the act of submitting consent IS acceptance (regardless of which categories the user toggled on/off; rejecting analytics is still "I made a choice and saved it"). The granular `preferences` JSON captures the per-category choices.
5. Return `{ saved: true }`.

## Code samples [#code-samples]



<Tabs items="['curl (anonymous)', 'curl (authenticated)', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl (anonymous)">
    ```bash
    curl -X POST https://api.bio.re/api/v1/consent/cookies \
      -H 'Content-Type: application/json' \
      -d '{
        "analytics": true,
        "marketing": false,
        "functional": true
      }'
    ```
  </Tab>

  <Tab value="curl (authenticated)">
    ```bash
    curl -X POST https://api.bio.re/api/v1/consent/cookies \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"analytics": true, "marketing": true, "functional": true}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type CookieConsentChoices = {
      analytics: boolean;
      marketing: boolean;
      functional: boolean;
    };

    async function saveCookieConsent(
      choices: CookieConsentChoices,
      accessToken?: string,
    ): Promise<void> {
      const headers: Record<string, string> = { 'Content-Type': 'application/json' };
      if (accessToken) headers.Authorization = `Bearer ${accessToken}`;
      const res = await fetch('https://api.bio.re/api/v1/consent/cookies', {
        method: 'POST',
        headers,
        body: JSON.stringify(choices),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Save consent failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useSaveCookieConsent() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (choices: CookieConsentChoices) => {
          // Browser auto-attaches the auth cookie/token via shared fetch wrapper
          const res = await fetch('/api/v1/consent/cookies', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(choices),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Save consent failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          // Invalidate status — banner should disappear after save
          qc.invalidateQueries({ queryKey: ['consent', 'cookies', 'status'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/consent/cookies', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                                                                    |
| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/content/cookie-consent.controller.ts`       | `87–120` (`saveConsent`), `15–19` (`CookieConsentDto` inline class)                                                      |
| DTO (response) | `apps/api-core/src/modules/content/dto/content-public-response.dto.ts` | `356–359` (`ConsentSavedDto`)                                                                                            |
| Config         | (admin-managed via `ConfigService`)                                    | `legal.privacy_version` (default `'1.0'`)                                                                                |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                                 | `ConsentRecord` (`documentType: 'COOKIE_CONSENT'`, `preferences` JSON, `ipAddress` GDPR-conditional, `userAgent` always) |


# Get Cookie Consent Status (/docs/content/cookie-status)



`GET /api/v1/consent/cookies/status` — 🌐 **Public** · Rate limit: **10 req / minute**

Drives the cookie banner. **Works for both anonymous and authenticated users** — the bearer token is optional. Returns the current platform privacy version (`legal.privacy_version` admin config, default `'1.0'`), the user's last-saved consent version (or `null` if anonymous / never consented), and `requiresReConsent: true` when the banner should be shown.



<Callout type="info">
  **Banner display rule**: `requiresReConsent === true` in three cases:

  1. Anonymous request (no bearer) → always.
  2. Authenticated user, never consented → `userVersion = null`.
  3. Authenticated user consented to an older version (`userVersion !== currentVersion`) → policy bumped.

  When admin updates `legal.privacy_version`, every existing user's `userVersion !== currentVersion` until they re-consent.
</Callout>

<Callout type="warn">
  **Tied to privacy policy version**, not cookie-specific. The `documentVersion` stored on `ConsentRecord` is the same `legal.privacy_version` config used by `AuthService` at registration. Cookie consent and privacy consent share a version axis — if you bump the privacy policy, the cookie banner re-shows too. (Designed this way: cookies are a substantive part of the privacy policy.)
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                                                                                                                |
| ------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `Authorization: Bearer <accessToken>` | optional | When present, fetches the user's saved consent. When absent, treats as anonymous (always `requiresReConsent: true`). |

## Response [#response]

### `200 OK` [#200-ok]

```json
{
  "success": true,
  "data": {
    "currentVersion": "1.2",
    "userVersion": "1.0",
    "requiresReConsent": true
  }
}
```

(Not strongly DTO-typed — controller returns the bare object; the response interceptor wraps it in `{ success, data }`.)

| Field               | Type           | Notes                                                                                                                                               |
| ------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `currentVersion`    | string         | Current platform privacy version from admin config `legal.privacy_version` (default `'1.0'`)                                                        |
| `userVersion`       | string \| null | The user's last-saved `ConsentRecord.documentVersion` for `documentType = 'COOKIE_CONSENT'`. `null` for anonymous OR authenticated-never-consented. |
| `requiresReConsent` | boolean        | `userVersion !== currentVersion` — true when the banner should be shown                                                                             |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `429` | (throttle)         | Rate limit exceeded (10 req/min) |

## Side effects [#side-effects]

1. Read `legal.privacy_version` from `ConfigService` (default `'1.0'`).
2. **Anonymous** (no `userId`) → `userVersion = null`. &#x2A;*Skip DB lookup.**
3. **Authenticated** — `consentRecord.findFirst({ where: { userId, documentType: 'COOKIE_CONSENT' }, orderBy: createdAt desc, select: { documentVersion } })`. Use `latest?.documentVersion ?? null`.
4. Compute `requiresReConsent = (userVersion !== currentVersion)`.
5. Return `{ currentVersion, userVersion, requiresReConsent }`. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl (anonymous)', 'curl (authenticated)', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl (anonymous)">
    ```bash
    curl https://api.bio.re/api/v1/consent/cookies/status
    # → requiresReConsent always true for anonymous
    ```
  </Tab>

  <Tab value="curl (authenticated)">
    ```bash
    curl https://api.bio.re/api/v1/consent/cookies/status \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type CookieConsentStatus = {
      currentVersion: string;
      userVersion: string | null;
      requiresReConsent: boolean;
    };

    async function getCookieStatus(accessToken?: string): Promise<CookieConsentStatus> {
      const headers: Record<string, string> = {};
      if (accessToken) headers.Authorization = `Bearer ${accessToken}`;
      const res = await fetch('https://api.bio.re/api/v1/consent/cookies/status', { headers });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Status fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const consentKeys = {
      cookieStatus: (signedIn: boolean) => ['consent', 'cookies', 'status', signedIn] as const,
    };

    export function useCookieStatus(signedIn: boolean) {
      return useQuery({
        queryKey: consentKeys.cookieStatus(signedIn),
        queryFn: async () => {
          // Browser auto-attaches the auth cookie/token via shared fetch wrapper
          const res = await fetch('/api/v1/consent/cookies/status');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Status fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as CookieConsentStatus;
        },
        // Refresh on focus — admin may have bumped the policy version
        staleTime: 60_000,
        refetchOnWindowFocus: true,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/consent/cookies/status', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source       | Path                                                             | Lines                                                                                   |
| ------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Controller   | `apps/api-core/src/modules/content/cookie-consent.controller.ts` | `58–85` (`getStatus`)                                                                   |
| Config       | (admin-managed via `ConfigService`)                              | `legal.privacy_version` (default `'1.0'`)                                               |
| Prisma model | `packages/prisma/prisma/schema.prisma`                           | `ConsentRecord` (filter `documentType = 'COOKIE_CONSENT'`, ordered by `createdAt desc`) |


# Get FAQ (/docs/content/faq)



`GET /api/v1/public/faq` — 🌐 **Public** · Rate limit: **60 req / minute**

Returns FAQ groups (categories) with their **published items** nested inside. Group order is admin-set (`FaqCategory.sortOrder ASC`); item order inside each group follows `FaqItem.sortOrder ASC`. Optional `?locale=` filter; otherwise returns groups across all locales.



<Callout type="info">
  **Items are PUBLISHED-only; groups are not filtered.** The category-level filter only applies to items (`status = PUBLISHED`). Categories themselves are returned regardless of any "active" flag — but a category with zero published items will still appear with `items: []`. Frontend should hide empty groups if that's the desired UX.
</Callout>

<Callout type="warn">
  **Answer body is sanitized.** Each item's `answer` field passes through `sanitizeHtml()` — strips `<script>`, `<style>`, `<iframe>`, inline `on*` event handlers. Same caveat as the rest of the content module: admin authors are trusted, sanitization is defense-in-depth.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param    | Type   | Default | Notes                                                 |
| -------- | ------ | ------- | ----------------------------------------------------- |
| `locale` | string | —       | Filter by `FaqCategory.locale`. Omit for all locales. |

No headers required.

## Response headers [#response-headers]

| Header          | Value                                              |
| --------------- | -------------------------------------------------- |
| `Cache-Control` | `public, s-maxage=300, stale-while-revalidate=600` |

## Response [#response]

### `200 OK` — `ArrayApiResponseOf<PublicFaqGroupDto>` [#200-ok--arrayapiresponseofpublicfaqgroupdto]

```json
{
  "success": true,
  "data": [
    {
      "slug": "account",
      "name": "Account",
      "items": [
        {
          "question": "How do I reset my password?",
          "answer": "<p>Click Forgot Password on the login screen...</p>"
        },
        {
          "question": "How do I change my email?",
          "answer": "<p>Go to Settings...</p>"
        }
      ]
    },
    {
      "slug": "payments",
      "name": "Payments",
      "items": []
    }
  ]
}
```

### Group fields [#group-fields]

| Field   | Type   | Notes                                                                              |
| ------- | ------ | ---------------------------------------------------------------------------------- |
| `slug`  | string | `FaqCategory.slug` (use as anchor / nav target)                                    |
| `name`  | string | Display name                                                                       |
| `items` | array  | Published items in this group, ordered by `FaqItem.sortOrder ASC`. Possibly empty. |

### Item fields [#item-fields]

| Field      | Type   | Notes                                                   |
| ---------- | ------ | ------------------------------------------------------- |
| `question` | string | Plain text question (not sanitized — admin-typed plain) |
| `answer`   | string | Server-side sanitized HTML answer                       |

### Stripped fields [#stripped-fields]

`id`, `categoryId`, `status` (always PUBLISHED here), `sortOrder` (used for ordering, not exposed), `createdAt`, `updatedAt`, `locale` (used for filter, not exposed) — all internal-only, excluded.

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `429` | (throttle)         | Rate limit exceeded (60 req/min) |

## Side effects [#side-effects]

1. `prisma.faqCategory.findMany({ where: locale ? { locale } : {}, orderBy: sortOrder asc, include: { items: { where: { status: PUBLISHED }, orderBy: sortOrder asc } } })`.
2. Map each group → strip internal fields, sanitize each item's `answer` via `sanitizeHtml()`.
3. Return the array. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/public/faq
    curl 'https://api.bio.re/api/v1/public/faq?locale=tr'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type FaqItem = {
      question: string;
      answer: string;
    };

    type FaqGroup = {
      slug: string;
      name: string;
      items: FaqItem[];
    };

    async function getFaq(locale?: string): Promise<FaqGroup[]> {
      const url = new URL('https://api.bio.re/api/v1/public/faq');
      if (locale) url.searchParams.set('locale', locale);
      const res = await fetch(url);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'FAQ fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const contentKeys = {
      faq: (locale?: string) => ['content', 'faq', locale ?? 'all'] as const,
    };

    export function useFaq(locale?: string) {
      return useQuery({
        queryKey: contentKeys.faq(locale),
        queryFn: async () => {
          const url = new URL('/api/v1/public/faq', window.location.origin);
          if (locale) url.searchParams.set('locale', locale);
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'FAQ fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as FaqGroup[];
        },
        staleTime: 5 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/public/faq', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source              | Path                                                                   | Lines                                                                                 |
| ------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Controller          | `apps/api-core/src/modules/content/public-content.controller.ts`       | `379–394` (`listPublishedFaq`), `29–36` (`sanitizeHtml`)                              |
| DTO (response item) | `apps/api-core/src/modules/content/dto/content-public-response.dto.ts` | `302–311` (`PublicFaqGroupDto`), `291–297` (`PublicFaqItemDto`)                       |
| Service             | `apps/api-core/src/modules/content/content.service.ts`                 | `877–888` (`listPublishedFaq`)                                                        |
| Prisma models       | `packages/prisma/prisma/schema.prisma`                                 | `FaqCategory` (admin-ordered), `FaqItem` (filter `status = PUBLISHED`, admin-ordered) |


# Get Help Article (by slug) (/docs/content/help-article)



`GET /api/v1/public/help/articles/:slug` — 🌐 **Public** · Rate limit: **60 req / minute**

Returns a single published help article by slug. **PUBLISHED-only** — DRAFT slugs return `404`. The HTML `content` is **server-side sanitized** (same `sanitizeHtml()` helper as CMS pages — strips `<script>`, `<style>`, `<iframe>`, inline `on*` event handlers).



<Callout type="warn">
  **Sanitization is defensive, not exhaustive.** Same caveat as `GET /public/pages/:slug` and `GET /public/blog/:slug` — strips obvious XSS but admin authors are still ultimately trusted. Use client-side sanitization (DOMPurify) for additional defense.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param  | Type   | Notes                                      |
| ------ | ------ | ------------------------------------------ |
| `slug` | string | Help article slug (e.g. `how-to-withdraw`) |

No body, no query params, no headers required.

## Response headers [#response-headers]

| Header          | Value                                              |
| --------------- | -------------------------------------------------- |
| `Cache-Control` | `public, s-maxage=300, stale-while-revalidate=600` |

## Response [#response]

### `200 OK` — `ApiResponseOf<PublicHelpArticleDto>` [#200-ok--apiresponseofpublichelparticledto]

```json
{
  "success": true,
  "data": {
    "slug": "how-to-withdraw",
    "title": "How to Withdraw Funds",
    "content": "<p>Sanitized HTML content...</p>",
    "excerpt": "Step-by-step guide to withdrawing earnings.",
    "icon": "wallet",
    "readTimeMinutes": 5,
    "publishedAt": "2026-04-29T20:00:00.000Z",
    "category": { "name": "Payments & Billing", "slug": "payments" }
  }
}
```

| Field             | Type                      | Notes                                         |
| ----------------- | ------------------------- | --------------------------------------------- |
| `slug`            | string                    | Echoes the path param                         |
| `title`           | string                    | Article title                                 |
| `content`         | string                    | Server-side sanitized HTML body               |
| `excerpt`         | string \| null            | Short summary                                 |
| `icon`            | string \| null            | Icon identifier                               |
| `readTimeMinutes` | number \| null            | Estimated read time                           |
| `publishedAt`     | string (ISO 8601) \| null | When published                                |
| `category`        | object                    | `{ name, slug }` of the parent `HelpCategory` |

### Notable absence [#notable-absence]

The list endpoint returns `isFeatured` but the single-article endpoint does **not** — the featured flag is a list-discovery concern, not relevant when you're already viewing the article.

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                     | Reason                                                   |
| ----- | -------------------------------------- | -------------------------------------------------------- |
| `404` | `error.content.help_article_not_found` | No `HelpArticle` matches `slug` AND `status = PUBLISHED` |
| `429` | (throttle)                             | Rate limit exceeded (60 req/min)                         |

## Side effects [#side-effects]

1. `prisma.helpArticle.findFirst({ where: { slug, status: PUBLISHED }, include: { category: true } })`.
2. Missing → throw `help_article_not_found` (404).
3. **HTML sanitization** — `sanitizeHtml(article.content)` (same helper as CMS pages and blog posts).
4. Project category to `{ name, slug }`.
5. Return assembled object. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/public/help/articles/how-to-withdraw
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type HelpArticle = {
      slug: string;
      title: string;
      content: string;
      excerpt: string | null;
      icon: string | null;
      readTimeMinutes: number | null;
      publishedAt: string | null;
      category: { name: string; slug: string };
    };

    async function getHelpArticle(slug: string): Promise<HelpArticle> {
      const res = await fetch(`https://api.bio.re/api/v1/public/help/articles/${encodeURIComponent(slug)}`);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Help article fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const contentKeys = {
      helpArticle: (slug: string) => ['content', 'help', 'article', slug] as const,
    };

    export function useHelpArticle(slug: string) {
      return useQuery({
        queryKey: contentKeys.helpArticle(slug),
        queryFn: async () => {
          const res = await fetch(`/api/v1/public/help/articles/${encodeURIComponent(slug)}`);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Help article fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as HelpArticle;
        },
        enabled: Boolean(slug),
        staleTime: 5 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/public/help/articles/{slug}', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                        |
| -------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/content/public-content.controller.ts`       | `352–373` (`getHelpArticle`), `29–36` (`sanitizeHtml`)                       |
| DTO (response) | `apps/api-core/src/modules/content/dto/content-public-response.dto.ts` | `260–284` (`PublicHelpArticleDto`), `202–208` (`PublicHelpCategoryEmbedDto`) |
| Service        | `apps/api-core/src/modules/content/content.service.ts`                 | `778–783` (`getPublishedHelpArticle`)                                        |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                                 | `HelpArticle` (`status = PUBLISHED`), `HelpCategory` (joined)                |


# List Help Articles (/docs/content/help-articles)



`GET /api/v1/public/help/articles` — 🌐 **Public** · Rate limit: **60 req / minute**

Paginated list of published help articles. Supports four filters: `?category=<slug>`, `?search=<term>` (case-insensitive substring match across title + content + excerpt), `?featured=true` (featured articles only), `?locale=<code>`. Each item is the lightweight projection (no full body) plus the embedded category (`{ name, slug }`).



<Callout type="info">
  **Search is substring, not full-text.** `?search=billing` matches "Billing FAQ" and "How to handle billing disputes". The match runs as `ILIKE` over `title`, `content`, and `excerpt` (any of the three) with `mode: 'insensitive'`. No tokenization, no ranking — substring contains.
</Callout>

<Callout type="warn">
  **`?featured=true` requires the literal string `'true'`.** Anything else (including `'1'`, `'yes'`) falls back to "no featured filter". The check is `featured === 'true'`. Pass case-sensitive `true`.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param      | Type   | Default | Validation                                  | Notes                                                              |
| ---------- | ------ | ------- | ------------------------------------------- | ------------------------------------------------------------------ |
| `page`     | number | `1`     | `ParseIntPipe`, server-clamped to `>= 1`    | 1-based page index                                                 |
| `limit`    | number | `20`    | `ParseIntPipe`, server-clamped to `[1, 50]` | Items per page                                                     |
| `category` | string | —       | —                                           | Filter by `HelpCategory.slug`                                      |
| `search`   | string | —       | —                                           | Case-insensitive substring across title/content/excerpt            |
| `featured` | string | —       | —                                           | Pass literal `'true'` for featured-only; anything else = no filter |
| `locale`   | string | —       | —                                           | Filter by locale (e.g. `en`, `tr`)                                 |

No headers required.

## Response headers [#response-headers]

| Header          | Value                                              |
| --------------- | -------------------------------------------------- |
| `Cache-Control` | `public, s-maxage=300, stale-while-revalidate=600` |

## Response [#response]

### `200 OK` — `ApiResponseOf<PublicHelpArticleListDataDto>` [#200-ok--apiresponseofpublichelparticlelistdatadto]

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "slug": "how-to-withdraw",
        "title": "How to Withdraw Funds",
        "excerpt": "Step-by-step guide to withdrawing earnings.",
        "icon": "wallet",
        "readTimeMinutes": 5,
        "isFeatured": true,
        "publishedAt": "2026-04-29T20:00:00.000Z",
        "category": { "name": "Payments & Billing", "slug": "payments" }
      }
    ],
    "total": 30,
    "page": 1,
    "limit": 20,
    "totalPages": 2
  }
}
```

### Item fields [#item-fields]

| Field             | Type                      | Notes                                                  |
| ----------------- | ------------------------- | ------------------------------------------------------ |
| `slug`            | string                    | Pass to `GET /public/help/articles/:slug` for the body |
| `title`           | string                    | Display title                                          |
| `excerpt`         | string \| null            | Short summary for cards                                |
| `icon`            | string \| null            | Icon identifier                                        |
| `readTimeMinutes` | number \| null            | Estimated read time                                    |
| `isFeatured`      | boolean                   | Whether the article is in the "featured" set           |
| `publishedAt`     | string (ISO 8601) \| null | When published                                         |
| `category`        | object                    | `{ name, slug }` of the parent `HelpCategory`          |

### Top-level fields [#top-level-fields]

| Field                           | Type   | Notes                                                 |
| ------------------------------- | ------ | ----------------------------------------------------- |
| `items`                         | array  | Up to `limit` articles, ordered by `publishedAt DESC` |
| `total`                         | number | Total matching the filter                             |
| `page` / `limit` / `totalPages` | number | Echoed pagination metadata                            |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `429` | (throttle)         | Rate limit exceeded (60 req/min) |

## Side effects [#side-effects]

1. Clamp `page = max(page, 1)`, `limit = min(max(limit, 1), 50)`.
2. Build `where`:
   * `status: PUBLISHED` (always).
   * `?category` → `{ category: { slug: categorySlug } }`.
   * `?featured === 'true'` → `{ isFeatured: true }`.
   * `?locale` → `{ locale }`.
   * `?search` → `OR: [{ title: { contains: search, mode: 'insensitive' } }, { content: { contains } }, { excerpt: { contains } }]`.
3. **In parallel**: `helpArticle.findMany({ where, orderBy: publishedAt desc, include: category, skip, take })` + `count({ where })`.
4. Project category to `{ name, slug }`.
5. Return paginated envelope. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    # Featured articles in payments category
    curl 'https://api.bio.re/api/v1/public/help/articles?category=payments&featured=true&limit=20'

    # Search for "withdraw"
    curl 'https://api.bio.re/api/v1/public/help/articles?search=withdraw'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type HelpCategoryEmbed = { name: string; slug: string };

    type HelpArticleListItem = {
      slug: string;
      title: string;
      excerpt: string | null;
      icon: string | null;
      readTimeMinutes: number | null;
      isFeatured: boolean;
      publishedAt: string | null;
      category: HelpCategoryEmbed;
    };

    type HelpArticleListData = {
      items: HelpArticleListItem[];
      total: number;
      page: number;
      limit: number;
      totalPages: number;
    };

    async function listHelpArticles(filter: {
      page?: number;
      limit?: number;
      category?: string;
      search?: string;
      featured?: boolean;
      locale?: string;
    } = {}): Promise<HelpArticleListData> {
      const url = new URL('https://api.bio.re/api/v1/public/help/articles');
      if (filter.page) url.searchParams.set('page', String(filter.page));
      if (filter.limit) url.searchParams.set('limit', String(filter.limit));
      if (filter.category) url.searchParams.set('category', filter.category);
      if (filter.search) url.searchParams.set('search', filter.search);
      if (filter.featured) url.searchParams.set('featured', 'true');
      if (filter.locale) url.searchParams.set('locale', filter.locale);
      const res = await fetch(url);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Help articles fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery, keepPreviousData } from '@tanstack/react-query';

    export const contentKeys = {
      helpArticles: (filter: Record<string, unknown>) =>
        ['content', 'help', 'articles', filter] as const,
    };

    export function useHelpArticles(filter: {
      page?: number;
      limit?: number;
      category?: string;
      search?: string;
      featured?: boolean;
      locale?: string;
    } = {}) {
      return useQuery({
        queryKey: contentKeys.helpArticles(filter),
        queryFn: async () => {
          const url = new URL('/api/v1/public/help/articles', window.location.origin);
          if (filter.page) url.searchParams.set('page', String(filter.page));
          if (filter.limit) url.searchParams.set('limit', String(filter.limit));
          if (filter.category) url.searchParams.set('category', filter.category);
          if (filter.search) url.searchParams.set('search', filter.search);
          if (filter.featured) url.searchParams.set('featured', 'true');
          if (filter.locale) url.searchParams.set('locale', filter.locale);
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Help articles fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as HelpArticleListData;
        },
        placeholderData: keepPreviousData,
        staleTime: 5 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/public/help/articles', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                                                                 |
| -------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/content/public-content.controller.ts`       | `310–350` (`listPublishedHelpArticles`)                                                                               |
| DTO (response) | `apps/api-core/src/modules/content/dto/content-public-response.dto.ts` | `239–254` (`PublicHelpArticleListDataDto`), `210–234` (`PublicHelpArticleListItemDto` + `PublicHelpCategoryEmbedDto`) |
| Service        | `apps/api-core/src/modules/content/content.service.ts`                 | `751–776` (`listPublishedHelpArticles`)                                                                               |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                                 | `HelpArticle` (`status = PUBLISHED`, optional `isFeatured` filter), `HelpCategory` (joined)                           |


# List Help Categories (/docs/content/help-categories)



`GET /api/v1/public/help/categories` — 🌐 **Public** · Rate limit: **60 req / minute**

Returns published help center categories — the top-level groupings shown on the help center landing page. Each category includes the **count of published articles** within it (so the UI can render "Payments (12)" without a second query). Optional `?locale=` filter; otherwise returns categories across all locales.



<Callout type="info">
  **Article count is published-only.** The `articleCount` field counts only `HelpArticle` rows where `status = PUBLISHED`. Draft / archived articles aren't counted, so the number matches what the user will actually see when clicking into a category.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param    | Type   | Default | Notes                                                     |
| -------- | ------ | ------- | --------------------------------------------------------- |
| `locale` | string | —       | Filter by locale (e.g. `en`, `tr`). Omit for all locales. |

No headers required.

## Response headers [#response-headers]

| Header          | Value                                              |
| --------------- | -------------------------------------------------- |
| `Cache-Control` | `public, s-maxage=300, stale-while-revalidate=600` |

## Response [#response]

### `200 OK` — `ArrayApiResponseOf<PublicHelpCategoryDto>` [#200-ok--arrayapiresponseofpublichelpcategorydto]

```json
{
  "success": true,
  "data": [
    {
      "id": "hc1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "slug": "payments",
      "name": "Payments & Billing",
      "description": "Wallet, payouts, refunds",
      "icon": "credit-card",
      "iconBackground": "#F0F4FF",
      "sortOrder": 1,
      "articleCount": 12
    }
  ]
}
```

### Item fields [#item-fields]

| Field            | Type           | Notes                                                                           |
| ---------------- | -------------- | ------------------------------------------------------------------------------- |
| `id`             | string (UUID)  | `HelpCategory.id`                                                               |
| `slug`           | string         | Pass to `GET /public/help/articles?category=<slug>` to drill in                 |
| `name`           | string         | Display name                                                                    |
| `description`    | string \| null | Short description for the category card                                         |
| `icon`           | string \| null | Icon identifier (your design system maps this to a glyph)                       |
| `iconBackground` | string \| null | Hex color for the icon background tile                                          |
| `sortOrder`      | number         | Admin-set ordering — server returns rows ordered `sortOrder ASC`                |
| `articleCount`   | number         | Count of `HelpArticle` rows where `categoryId` matches AND `status = PUBLISHED` |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `429` | (throttle)         | Rate limit exceeded (60 req/min) |

## Side effects [#side-effects]

1. Build `where = { status: PUBLISHED, ...(locale ? { locale } : {}) }`.
2. `prisma.helpCategory.findMany({ where, orderBy: sortOrder asc, include: { _count: { select: { articles: { where: { status: PUBLISHED } } } } } })`.
3. Project the `_count.articles` aggregate into the flat `articleCount` field.
4. Return the array. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/public/help/categories
    curl 'https://api.bio.re/api/v1/public/help/categories?locale=tr'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type PublicHelpCategory = {
      id: string;
      slug: string;
      name: string;
      description: string | null;
      icon: string | null;
      iconBackground: string | null;
      sortOrder: number;
      articleCount: number;
    };

    async function listHelpCategories(locale?: string): Promise<PublicHelpCategory[]> {
      const url = new URL('https://api.bio.re/api/v1/public/help/categories');
      if (locale) url.searchParams.set('locale', locale);
      const res = await fetch(url);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Help categories fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const contentKeys = {
      helpCategories: (locale?: string) =>
        ['content', 'help', 'categories', locale ?? 'all'] as const,
    };

    export function useHelpCategories(locale?: string) {
      return useQuery({
        queryKey: contentKeys.helpCategories(locale),
        queryFn: async () => {
          const url = new URL('/api/v1/public/help/categories', window.location.origin);
          if (locale) url.searchParams.set('locale', locale);
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Help categories fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as PublicHelpCategory[];
        },
        staleTime: 5 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/public/help/categories', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source              | Path                                                                   | Lines                                                                                       |
| ------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Controller          | `apps/api-core/src/modules/content/public-content.controller.ts`       | `291–308` (`listPublishedHelpCategories`)                                                   |
| DTO (response item) | `apps/api-core/src/modules/content/dto/content-public-response.dto.ts` | `172–196` (`PublicHelpCategoryDto`)                                                         |
| Service             | `apps/api-core/src/modules/content/content.service.ts`                 | `740–749` (`listPublishedHelpCategories`)                                                   |
| Prisma model        | `packages/prisma/prisma/schema.prisma`                                 | `HelpCategory` (filter `status = PUBLISHED`), `HelpArticle` (joined for `_count` aggregate) |


# Get CMS Page (by slug) (/docs/content/page-by-slug)



`GET /api/v1/public/pages/:slug` — 🌐 **Public** · Rate limit: **60 req / minute**

Returns a single CMS page by slug. **PUBLISHED-only** — DRAFT / ARCHIVED slugs return `404`. The HTML body is **server-side sanitized** before return: `<script>`, `<style>`, `<iframe>` tags + `on*` event handlers are stripped (defense-in-depth — admin authors are trusted, but the sanitizer protects against operator mistakes).



<Callout type="warn">
  **Sanitization is defensive, not exhaustive.** The server strips obvious XSS vectors (`<script>`, `<style>`, `<iframe>`, inline event handlers like `onclick`). Other dangerous patterns (CSS expressions, data URIs in `<img src>`, etc) are NOT stripped — render the content with `dangerouslySetInnerHTML` only if you trust the admin authors. For belt-and-suspenders safety, run client-side sanitization (e.g. DOMPurify) on top.
</Callout>

<Callout type="info">
  **Locale-keyed lookup**: each `(slug, locale)` pair is a separate row. Default locale is `en`. Pass `?locale=tr` to fetch the Turkish version. **Missing locale → 404, NOT fallback to English** — you must list available locales via `GET /public/pages` and pick from there.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param  | Type   | Notes                                  |
| ------ | ------ | -------------------------------------- |
| `slug` | string | Page slug (e.g. `about-us`, `careers`) |

### Query parameters [#query-parameters]

| Param    | Type   | Default | Notes       |
| -------- | ------ | ------- | ----------- |
| `locale` | string | `en`    | Locale code |

No headers required.

## Response headers [#response-headers]

| Header          | Value                                              |
| --------------- | -------------------------------------------------- |
| `Cache-Control` | `public, s-maxage=300, stale-while-revalidate=600` |

## Response [#response]

### `200 OK` — `ApiResponseOf<PublicCmsPageDto>` [#200-ok--apiresponseofpubliccmspagedto]

```json
{
  "success": true,
  "data": {
    "slug": "about-us",
    "title": "About Us",
    "content": "<p>Sanitized HTML content</p>",
    "locale": "en",
    "publishedAt": "2026-04-29T20:00:00.000Z"
  }
}
```

| Field         | Type                      | Notes                                                    |
| ------------- | ------------------------- | -------------------------------------------------------- |
| `slug`        | string                    | Echoes the path param                                    |
| `title`       | string                    | Page title                                               |
| `content`     | string                    | Server-side sanitized HTML body                          |
| `locale`      | string                    | Locale of the matched row (matches the `?locale` filter) |
| `publishedAt` | string (ISO 8601) \| null | When the page transitioned to PUBLISHED                  |

### Stripped fields [#stripped-fields]

`id`, `status`, `publishedBy`, `authorId`, `createdAt`, `updatedAt` — all internal-only, excluded from this response.

### Errors [#errors]

| HTTP  | `code` / `i18nKey`             | Reason                                                         |
| ----- | ------------------------------ | -------------------------------------------------------------- |
| `404` | `error.content.page_not_found` | No `CMSPage` matches `(slug, locale)` AND `status = PUBLISHED` |
| `429` | (throttle)                     | Rate limit exceeded (60 req/min)                               |

## Side effects [#side-effects]

1. `prisma.cMSPage.findFirst({ where: { slug, locale: locale ?? 'en', status: PUBLISHED } })`.
2. Missing → throw `page_not_found` (404).
3. **HTML sanitization** — `sanitizeHtml(page.content)` strips:
   * `<script>...</script>` blocks (regex with greedy minimum match).
   * `<style>...</style>` blocks (same pattern).
   * Inline event handlers — any attribute starting with `on` followed by a word (e.g. `onclick="..."`, `onerror='...'`).
   * `<iframe>` opening AND closing tags (kept content between, but tags stripped — effectively unwraps).
4. Return `{ slug, title, content: <sanitized>, locale, publishedAt }`. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    # Default locale (en)
    curl https://api.bio.re/api/v1/public/pages/about-us

    # Specific locale
    curl 'https://api.bio.re/api/v1/public/pages/about-us?locale=tr'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type PublicCmsPage = {
      slug: string;
      title: string;
      content: string;
      locale: string;
      publishedAt: string | null;
    };

    async function getCmsPage(slug: string, locale = 'en'): Promise<PublicCmsPage> {
      const url = new URL(`https://api.bio.re/api/v1/public/pages/${encodeURIComponent(slug)}`);
      if (locale !== 'en') url.searchParams.set('locale', locale);
      const res = await fetch(url);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Page fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const contentKeys = {
      page: (slug: string, locale: string) => ['content', 'pages', slug, locale] as const,
    };

    export function useCmsPage(slug: string, locale = 'en') {
      return useQuery({
        queryKey: contentKeys.page(slug, locale),
        queryFn: async () => {
          const url = new URL(`/api/v1/public/pages/${encodeURIComponent(slug)}`, window.location.origin);
          if (locale !== 'en') url.searchParams.set('locale', locale);
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Page fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as PublicCmsPage;
        },
        enabled: Boolean(slug),
        staleTime: 5 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/public/pages/{slug}', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                            |
| -------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/content/public-content.controller.ts`       | `72–95` (`getPage`), `29–36` (`sanitizeHtml`)                    |
| DTO (response) | `apps/api-core/src/modules/content/dto/content-public-response.dto.ts` | `17–32` (`PublicCmsPageDto`)                                     |
| Service        | `apps/api-core/src/modules/content/content.service.ts`                 | `73–77` (`getPage`)                                              |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                                 | `CMSPage` (filter `status = PUBLISHED`, `(slug, locale)` lookup) |


# List CMS Pages (/docs/content/pages-list)



`GET /api/v1/public/pages` — 🌐 **Public** · Rate limit: **60 req / minute**

Returns the admin-managed CMS page catalog as a **lightweight list** — slug + title + locale + publishedAt only. The full HTML body is served by `GET /public/pages/:slug`. **PUBLISHED-only filter** is enforced server-side: `DRAFT` and `ARCHIVED` pages never leak. Internal fields (`publishedBy`, `authorId`, internal IDs, `status`) are stripped from the response.



<Callout type="info">
  **Use for footer/sitemap discovery.** This is the right endpoint for building a "static pages" navigation menu or a sitemap — small payload (no body), fast to load, CDN-cacheable. To render the actual page content, follow up with `GET /public/pages/:slug` per slug.
</Callout>

<Callout type="warn">
  **Cap is 500.** The server takes at most 500 pages per request. There is no pagination — if your platform has more than 500 published pages, only the most recently updated 500 are returned. (`orderBy: updatedAt desc`.)
</Callout>

## Request [#request]

No body, no params, no headers required.

## Response headers [#response-headers]

| Header          | Value                                              |
| --------------- | -------------------------------------------------- |
| `Cache-Control` | `public, s-maxage=300, stale-while-revalidate=600` |

## Response [#response]

### `200 OK` — `ArrayApiResponseOf<PublicCmsPageListItemDto>` [#200-ok--arrayapiresponseofpubliccmspagelistitemdto]

```json
{
  "success": true,
  "data": [
    {
      "slug": "about-us",
      "title": "About Us",
      "locale": "en",
      "publishedAt": "2026-04-29T20:00:00.000Z"
    },
    {
      "slug": "careers",
      "title": "Careers",
      "locale": "en",
      "publishedAt": "2026-04-15T10:00:00.000Z"
    }
  ]
}
```

### Item fields [#item-fields]

| Field         | Type                      | Notes                                                                               |
| ------------- | ------------------------- | ----------------------------------------------------------------------------------- |
| `slug`        | string                    | Pass to `GET /public/pages/:slug` to fetch the body                                 |
| `title`       | string                    | Display title                                                                       |
| `locale`      | string                    | Locale code (e.g. `en`, `tr`) — there can be multiple rows per slug, one per locale |
| `publishedAt` | string (ISO 8601) \| null | When the page transitioned to PUBLISHED                                             |

### Stripped fields [#stripped-fields]

The following exist on the underlying `CMSPage` model but are **excluded** from this response: `id`, `content`, `status`, `publishedBy`, `authorId`, `createdAt`, `updatedAt`. They're either internal-only (security) or too heavy (`content` HTML body served separately).

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `429` | (throttle)         | Rate limit exceeded (60 req/min) |

## Side effects [#side-effects]

1. `prisma.cMSPage.findMany({ where: { status: PUBLISHED }, select: { slug, title, locale, publishedAt }, orderBy: { updatedAt: 'desc' }, take: 500 })`.
2. Return the array as-is. **No mutations**, no auth, no per-user state.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/public/pages
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type PublicCmsPageListItem = {
      slug: string;
      title: string;
      locale: string;
      publishedAt: string | null;
    };

    async function listCmsPages(): Promise<PublicCmsPageListItem[]> {
      const res = await fetch('https://api.bio.re/api/v1/public/pages');
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Pages list fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const contentKeys = {
      pagesList: () => ['content', 'pages', 'list'] as const,
    };

    export function useCmsPagesList() {
      return useQuery({
        queryKey: contentKeys.pagesList(),
        queryFn: async () => {
          const res = await fetch('/api/v1/public/pages');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Pages list fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as PublicCmsPageListItem[];
        },
        // CDN cache window
        staleTime: 5 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/public/pages', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source              | Path                                                                   | Lines                                                         |
| ------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------- |
| Controller          | `apps/api-core/src/modules/content/public-content.controller.ts`       | `63–70` (`listPages`)                                         |
| DTO (response item) | `apps/api-core/src/modules/content/dto/content-public-response.dto.ts` | `42–54` (`PublicCmsPageListItemDto`)                          |
| Service             | `apps/api-core/src/modules/content/content.service.ts`                 | `97–104` (`listPublicPages`)                                  |
| Prisma model        | `packages/prisma/prisma/schema.prisma`                                 | `CMSPage` (filter `status = PUBLISHED`, `enum ContentStatus`) |


# Update Bank Details (/docs/creator/bank-details)



`PATCH /api/v1/creators/bank-details` — 🔑 **Bearer** · Rate limit: **10 req / hour**

Sparse update of the creator's bank-transfer details. Validates IBAN format (`^[A-Z]{2}[0-9]{2}[A-Z0-9]{4,30}$`), SWIFT/BIC format (`^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$`), and ISO 3166-1 alpha-2 country code. &#x2A;*Any change to a bank field (`iban` / `bankName` / `accountHolderName` / `swiftCode` / `bankCountry`) resets `bankAccountVerified` to `false`** — the bank record must be re-verified by admin before `BANK_TRANSFER` becomes a usable payout method again.



<Callout type="warn">
  **Verification reset semantics.** Submitting `preferredPayoutMethod` alone (no bank field changes) does **not** reset `bankAccountVerified`. Only changes to the five bank fields above flip verification off. Plan UX accordingly: a "switch preferred method" button is safe; a "edit bank details" button warns of pending re-verification.
</Callout>

<Callout type="info">
  The endpoint accepts updates **even when verification is currently in flight or already passed**. There is no idempotency / conflict gate — the rule is simply "any write resets verification". If you want to gate the UI on verification state, read it from `GET /creators/payout-settings` first.
</Callout>

## Request [#request]

### Body — `UpdateBankDetailsDto` [#body--updatebankdetailsdto]

All fields optional. Send only what you want to change.

| Field                   | Type                  | Validation                                                   | Notes                                                                                     |
| ----------------------- | --------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `iban`                  | string                | `MaxLength(34)`, regex `^[A-Z]{2}[0-9]{2}[A-Z0-9]{4,30}$`    | Bank account                                                                              |
| `bankName`              | string                | `MaxLength(100)`                                             | Display name                                                                              |
| `accountHolderName`     | string                | `MaxLength(200)`                                             | Legal account holder                                                                      |
| `swiftCode`             | string                | `MaxLength(11)`, regex `^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$` | SWIFT/BIC                                                                                 |
| `bankCountry`           | string                | `MaxLength(2)`, regex `^[A-Z]{2}$`                           | ISO 3166-1 alpha-2                                                                        |
| `preferredPayoutMethod` | enum (`PayoutMethod`) | `IsEnum(PayoutMethod)`                                       | One of: `STRIPE_CONNECT` / `BANK_TRANSFER`. Setting this **does not** reset verification. |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                                                                                                                                                       |
| --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `success` | boolean | Always `true` on 200. Re-fetch via `GET /creators/payout-settings` to read the post-write state (including the reset `verified: false` flag if applicable). |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`         | Reason                                                                                         |
| ----- | -------------------------- | ---------------------------------------------------------------------------------------------- |
| `400` | (DTO validation)           | IBAN / SWIFT / country regex fail; field length over cap; invalid `preferredPayoutMethod` enum |
| `401` | (guard)                    | Missing / invalid bearer token                                                                 |
| `404` | `creator.payout.not_found` | No `CreatorProfile` for this user                                                              |
| `429` | (throttle)                 | Rate limit exceeded (10 req/hour)                                                              |

## Side effects [#side-effects]

1. Lookup `CreatorProfile.id` by `userId`; throw `not_found` if missing.
2. Build sparse `data` object from defined keys (the 5 bank fields + `preferredPayoutMethod`).
3. **Verification reset gate** — compute `bankFieldChanged = (iban|bankName|accountHolderName|swiftCode|bankCountry) supplied`. If `true`:
   * `data.bankAccountVerified = false`.
   * `data.bankVerifiedAt = null`.
4. `prisma.creatorProfile.update({ where: { id }, data })`.
5. Audit log: `[payout] Bank details updated for creator {id} (verified reset: <bool>)`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X PATCH https://api.bio.re/api/v1/creators/bank-details \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "iban": "TR000000000000000000000000",
        "bankName": "Example Bank",
        "accountHolderName": "John Doe",
        "swiftCode": "EXAMPTRIS",
        "bankCountry": "TR"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type UpdateBankDetailsInput = {
      iban?: string;
      bankName?: string;
      accountHolderName?: string;
      swiftCode?: string;
      bankCountry?: string;
      preferredPayoutMethod?: 'STRIPE_CONNECT' | 'BANK_TRANSFER';
    };

    async function updateBankDetails(accessToken: string, input: UpdateBankDetailsInput): Promise<void> {
      const res = await fetch('https://api.bio.re/api/v1/creators/bank-details', {
        method: 'PATCH',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Update bank details failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useUpdateBankDetails() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (input: UpdateBankDetailsInput) => {
          const res = await fetch('/api/v1/creators/bank-details', {
            method: 'PATCH',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Update bank details failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          // verified flag may have flipped to false — refresh the consolidated read
          qc.invalidateQueries({ queryKey: ['creators', 'payout-settings'] });
          qc.invalidateQueries({ queryKey: ['creators', 'profile'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/bank-details', method: 'patch' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                      | Lines                                             |
| -------------- | --------------------------------------------------------- | ------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts` | `264–274` (`updateBankDetails`)                   |
| DTO (request)  | `apps/api-core/src/modules/creator/dto/creator.dto.ts`    | `136–160` (`UpdateBankDetailsDto`)                |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts`     | `SuccessOnlyResponseDto`                          |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`    | `904–930` (`updateBankDetails`)                   |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                    | `CreatorProfile` bank fields, `enum PayoutMethod` |


# Get Bio Analytics (/docs/creator/bio-analytics)



`GET /api/v1/bio/:bioPageId/analytics` — 🔑 **Bearer**

Returns aggregated analytics for a `BioPage` over a configurable window. **Ownership-checked** — `bioPage.creator.userId` must match the bearer's subject; otherwise 403. Aggregates run from a 10,000-row sample of recent `BioPageView` records — sufficient for typical dashboards, with a documented ceiling for very high-volume creators.



<Callout type="info">
  **Sampling cap.** The aggregator pulls at most **10,000 most-recent views** within the window for breakdowns (referrer / device / country). `totalViews` is the **true count** (separate query); only the breakdown buckets are derived from the sample. For creators with >10k views per window, the breakdown distributions are accurate but absolute counts in each bucket are sample-scoped.
</Callout>

<Callout type="warn">
  **Top-list caps**: `topReferrers` and `countryBreakdown` are sliced to the top 20 entries (sorted by count DESC). `deviceBreakdown` is not sliced — the long tail of devices is small.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param       | Type          | Validation      | Notes                     |
| ----------- | ------------- | --------------- | ------------------------- |
| `bioPageId` | string (UUID) | `ParseUUIDPipe` | The bio page to aggregate |

### Query parameters [#query-parameters]

| Param  | Type   | Default | Validation                               | Notes                               |
| ------ | ------ | ------- | ---------------------------------------- | ----------------------------------- |
| `days` | number | `30`    | `parseInt`, server-clamped to `[1, 365]` | Window length looking back from now |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<CreatorAnalyticsDto>` [#200-ok--apiresponseofcreatoranalyticsdto]

```json
{
  "success": true,
  "data": {
    "totalViews": 1500,
    "uniqueVisitors": 800,
    "topReferrers": [
      { "referrer": "direct", "count": 612 },
      { "referrer": "https://twitter.com", "count": 304 }
    ],
    "deviceBreakdown": [
      { "device": "mobile", "count": 980 },
      { "device": "desktop", "count": 420 },
      { "device": "tablet", "count": 100 }
    ],
    "countryBreakdown": [
      { "country": "US", "count": 540 },
      { "country": "TR", "count": 380 }
    ],
    "viewsByDay": [
      { "date": "2026-04-15", "views": 42 },
      { "date": "2026-04-16", "views": 51 }
    ]
  }
}
```

### Top-level fields [#top-level-fields]

| Field              | Type   | Notes                                                                                                                                                                |
| ------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `totalViews`       | number | True count from `count(BioPageView where bioPageId AND createdAt >= since)` (not sample-scoped)                                                                      |
| `uniqueVisitors`   | number | Distinct `visitorId` values across the **sample** (rows where `visitorId` is null are excluded)                                                                      |
| `topReferrers`     | array  | `{ referrer, count }` — sorted DESC, top 20. Empty / null `referrer` is bucketed as `'direct'`.                                                                      |
| `deviceBreakdown`  | array  | `{ device, count }` — not sliced. Empty / null `device` is bucketed as `'unknown'`.                                                                                  |
| `countryBreakdown` | array  | `{ country, count }` — sorted DESC, top 20. Empty / null `country` is bucketed as `'unknown'`.                                                                       |
| `viewsByDay`       | array  | `{ date, views }` — `date` is `YYYY-MM-DD` (server-local PostgreSQL date), sorted ASC. Computed from a separate raw SQL query (`COUNT(*) GROUP BY DATE(createdAt)`). |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`      | Reason                                  |
| ----- | ----------------------- | --------------------------------------- |
| `400` | (validation)            | `bioPageId` not UUID                    |
| `401` | (guard)                 | Missing / invalid bearer token          |
| `403` | `creator.bio.not_owner` | `bioPage.creator.userId !== bearer.sub` |
| `404` | `creator.bio.not_found` | `BioPage` row missing                   |

## Side effects [#side-effects]

1. **Ownership lookup** — `prisma.bioPage.findUnique({ where: { id }, select: { creator: { select: { userId: true } } } })`. Missing → 404. Mismatch → 403.
2. **Clamp `days`** — `Math.max(1, Math.min(365, parseInt(days) || 30))`. Default 30.
3. **Three queries in parallel**:
   * `count(BioPageView)` → `totalViews` (true count, not sampled).
   * `findMany(BioPageView, take: 10000, select: visitorId/referrer/device/country)` → sample for breakdown buckets.
   * `getViewsByDay()` — raw SQL `SELECT DATE(createdAt), COUNT(*) GROUP BY DATE` ordered ASC.
4. **In-memory aggregation** of the sample:
   * `uniqueVisitors = Set(views.filter(v => v.visitorId).map(v => v.visitorId)).size`.
   * Build `referrerMap`, `deviceMap`, `countryMap` (null/empty bucketed as `'direct'` / `'unknown'`).
   * Sort + slice top 20 for referrers and countries.
5. Return assembled object. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/bio/b1a2b3c4-d5e6-7890-abcd-ef1234567890/analytics?days=30' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type ReferrerItem = { referrer: string; count: number };
    type DeviceItem = { device: string; count: number };
    type CountryItem = { country: string; count: number };
    type ViewsByDayItem = { date: string; views: number };

    type CreatorAnalytics = {
      totalViews: number;
      uniqueVisitors: number;
      topReferrers: ReferrerItem[];
      deviceBreakdown: DeviceItem[];
      countryBreakdown: CountryItem[];
      viewsByDay: ViewsByDayItem[];
    };

    async function getBioAnalytics(accessToken: string, bioPageId: string, days = 30): Promise<CreatorAnalytics> {
      const url = new URL(`https://api.bio.re/api/v1/bio/${bioPageId}/analytics`);
      url.searchParams.set('days', String(days));
      const res = await fetch(url, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Analytics fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const bioKeys = {
      analytics: (bioPageId: string, days: number) =>
        ['bio', bioPageId, 'analytics', days] as const,
    };

    export function useBioAnalytics(bioPageId: string, days = 30) {
      return useQuery({
        queryKey: bioKeys.analytics(bioPageId, days),
        queryFn: async () => {
          const url = new URL(`/api/v1/bio/${bioPageId}/analytics`, window.location.origin);
          url.searchParams.set('days', String(days));
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Analytics fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as CreatorAnalytics;
        },
        enabled: Boolean(bioPageId),
        staleTime: 5 * 60_000, // 5min — analytics is event-sourced and changes incrementally
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/bio/{bioPageId}/analytics', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                            | Lines                                                           |
| -------------- | --------------------------------------------------------------- | --------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/bio-analytics.controller.ts` | `126–142` (`getAnalytics`)                                      |
| DTO (response) | `apps/api-core/src/modules/creator/dto/creator-response.dto.ts` | `385–403` (`CreatorAnalyticsDto`), `349–379` (nested item DTOs) |
| Service        | `apps/api-core/src/modules/creator/bio-analytics.service.ts`    | `247–301` (`getAnalytics`), `229–242` (`getViewsByDay`)         |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                          | `BioPageView`, `BioPage` (relation chain for ownership)         |


# Get Embeddable Bio Page (/docs/creator/bio-embed)



`GET /api/v1/bio/embed/:username` — 🌐 **Public** · Rate limit: **120 req / minute**

Same payload as `GET /bio/:username`, gated by `BioPage.embedEnabled === true`. Sets `X-Frame-Options: ALLOWALL` so the response can be rendered inside third-party `<iframe>` tags. CDN-cached `s-maxage=60, stale-while-revalidate=300` (same as the public render).



<Callout type="info">
  **Embed is opt-in per creator.** Creators flip `embedEnabled` via `PATCH /creators/:creatorId/bio { embedEnabled: true }`. When `false`, this endpoint returns `403 creator.bio.embed_disabled` even if the underlying bio page is otherwise public via `GET /bio/:username`.
</Callout>

<Callout type="warn">
  **`X-Frame-Options: ALLOWALL` is intentional.** The whole purpose of this endpoint is iframe embedding. The non-embed render (`GET /bio/:username`) does **not** set this header, so it inherits the platform default (clickjacking-protected). Use the right endpoint for the right context.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param      | Type   | Notes                                           |
| ---------- | ------ | ----------------------------------------------- |
| `username` | string | Lowercased server-side; case-insensitive lookup |

No body, no headers required.

## Response headers [#response-headers]

| Header            | Value                                             |
| ----------------- | ------------------------------------------------- |
| `Cache-Control`   | `public, s-maxage=60, stale-while-revalidate=300` |
| `X-Frame-Options` | `ALLOWALL`                                        |

## Response [#response]

### `200 OK` — `ApiResponseOf<PublicBioPageResponseDto>` [#200-ok--apiresponseofpublicbiopageresponsedto]

Same shape as `GET /bio/:username`. See [Get Public Bio Page](/docs/creator/bio-public) for the full field reference.

### Errors [#errors]

| HTTP  | `code` / `i18nKey`           | Reason                                                                            |
| ----- | ---------------------------- | --------------------------------------------------------------------------------- |
| `403` | `creator.bio.embed_disabled` | `BioPage.embedEnabled === false`                                                  |
| `404` | `creator.bio.not_found`      | Same status filter as the public render: user / creator / `published` checks fail |
| `429` | (throttle)                   | Rate limit exceeded (120 req/min)                                                 |

## Side effects [#side-effects]

1. **Cache hit / miss path** — identical to `GET /bio/:username`. Reuses the same `getCachedBioPage()` payload (no separate cache key).
2. After resolution, &#x2A;*assert `bioPage.embedEnabled === true`**. If not → throw `embed_disabled` (403).
3. Return the cached / freshly built payload.

## Code samples [#code-samples]



<Tabs items="['curl', 'iframe (HTML)', 'TypeScript fetch']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/bio/embed/johndoe
    ```
  </Tab>

  <Tab value="iframe (HTML)">
    ```html
    <!-- Embed a creator's bio page in your site -->
    <iframe
      src="https://bio.re/embed/johndoe"
      width="400"
      height="600"
      frameborder="0"
      loading="lazy"
    ></iframe>
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function getEmbedBioPage(username: string): Promise<unknown> {
      const res = await fetch(`https://api.bio.re/api/v1/bio/embed/${encodeURIComponent(username)}`);
      if (res.status === 403) {
        throw new Error('Embedding is not enabled for this bio page');
      }
      if (res.status === 404) return null;
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Embed fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/bio/embed/{username}', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                  | Lines                                                            |
| -------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/bio-analytics.controller.ts`       | `26–43` (`getEmbedBioPage`)                                      |
| DTO (response) | `apps/api-core/src/modules/creator/dto/bio-analytics-response.dto.ts` | `152–206` (`PublicBioPageResponseDto`)                           |
| Service        | `apps/api-core/src/modules/creator/bio-analytics.service.ts`          | `52–158` (`getCachedBioPage` — shared with `GET /bio/:username`) |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                                | `BioPage.embedEnabled`                                           |


# Add Bio Link (/docs/creator/bio-link-add)



`POST /api/v1/creators/:creatorId/links` — 🔑 **Bearer** · Rate limit: **30 req / hour**

Appends a `BioLink` to the creator's `BioPage`. Validates the URL (`http(s)://` only, `javascript:` blocked), strips HTML from the title, runs the title through trust-safety moderation, auto-detects embed type (YouTube / Spotify / TikTok / SoundCloud / Twitch / Apple Music) when not explicitly supplied, and respects the admin-managed `bio.max_links` cap with a row-locked count check.



<Callout type="warn">
  **Manual social links require DM-off.** When `isSocial: true` AND the creator has `dmActive: true`, the request is rejected with `400 social_dm_active`. The platform's design choice: while DM is active, social presence must come from OAuth-verified `SocialAccount` rows (via `POST /creators/social/connect`), not manual links — so fan trust signals stay tied to platform-verified ownership.
</Callout>

<Callout type="info">
  **Embed auto-detection** runs only when `embedType` is not supplied. Detected types: `YOUTUBE` (with `videoId` in meta), `SPOTIFY` (with `contentType` + `contentId`), `TIKTOK`, `SOUNDCLOUD`, `TWITCH`, `APPLE_MUSIC`. Custom embeds via explicit `embedType: 'CUSTOM'` + `embedMeta`.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param       | Type          | Validation      | Notes                                                       |
| ----------- | ------------- | --------------- | ----------------------------------------------------------- |
| `creatorId` | string (UUID) | `ParseUUIDPipe` | Must match the bearer's `CreatorProfile.id` (otherwise 403) |

### Body — `CreateBioLinkDto` [#body--createbiolinkdto]

| Field            | Type              | Required    | Validation                                                                          | Notes                                                                                                                                                                               |
| ---------------- | ----------------- | ----------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`          | string            | ✓           | `MaxLength(100)`                                                                    | HTML-stripped server-side, then moderation-checked                                                                                                                                  |
| `url`            | string            | ✓           | `IsUrl()`                                                                           | Server validates scheme — `javascript:` rejected as `creator.links.invalid_url`                                                                                                     |
| `icon`           | string            | optional    | `MaxLength(50)`                                                                     | Free-form icon identifier (your design system)                                                                                                                                      |
| `sortOrder`      | number            | optional    | `IsInt`, `Min(0)`, `Max(1000)`                                                      | Defaults to current link count (appended at end)                                                                                                                                    |
| `active`         | boolean           | optional    | —                                                                                   | Default `true`                                                                                                                                                                      |
| `embedType`      | enum              | optional    | `IsIn(['YOUTUBE','SPOTIFY','TIKTOK','SOUNDCLOUD','TWITCH','APPLE_MUSIC','CUSTOM'])` | Skipped → server auto-detects from URL                                                                                                                                              |
| `embedMeta`      | object            | optional    | `IsObject`                                                                          | Free-form, e.g. `{ videoId: '...' }`                                                                                                                                                |
| `scheduledStart` | string (ISO 8601) | optional    | `IsDateString`                                                                      | Schedule visibility window start                                                                                                                                                    |
| `scheduledEnd`   | string (ISO 8601) | optional    | `IsDateString`                                                                      | Must be **after** `scheduledStart`                                                                                                                                                  |
| `isSocial`       | boolean           | optional    | —                                                                                   | When `true`, DM must be off and `platform` is required                                                                                                                              |
| `platform`       | string            | conditional | `MaxLength(30)`                                                                     | Required when `isSocial: true`. Whitelist: `instagram`, `x`, `youtube`, `tiktok`, `github`, `linkedin`, `facebook`, `kick`, `twitch`, `snapchat`, `threads`, `pinterest`, `discord` |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `201 Created` — `ApiResponseOf<AddLinkResponseDto>` [#201-created--apiresponseofaddlinkresponsedto]

```json
{
  "success": true,
  "data": {
    "id": "l1a2b3c4-d5e6-7890-abcd-ef1234567890"
  }
}
```

| Field | Type          | Notes                                                                                               |
| ----- | ------------- | --------------------------------------------------------------------------------------------------- |
| `id`  | string (UUID) | The new `BioLink.id` — pass to `PATCH /creators/links/:linkId` and `DELETE /creators/links/:linkId` |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`               | Reason                                                                                              |
| ----- | -------------------------------- | --------------------------------------------------------------------------------------------------- |
| `400` | `creator.links.schedule_invalid` | `scheduledEnd <= scheduledStart`                                                                    |
| `400` | `creator.links.social_dm_active` | `isSocial: true` AND creator has `dmActive: true`                                                   |
| `400` | `creator.links.invalid_platform` | `isSocial: true` AND `platform` missing or not in whitelist                                         |
| `400` | `creator.links.content_flagged`  | Moderation flagged the title                                                                        |
| `400` | `creator.links.invalid_url`      | URL not `http(s)://` OR contains `javascript:`                                                      |
| `400` | `creator.links.max_links`        | Existing link count `>= bio.max_links` (admin-managed, default 20). Carries `{ maxLinks }` payload. |
| `400` | (DTO validation)                 | Field length / type / enum failures                                                                 |
| `401` | (guard)                          | Missing / invalid bearer token                                                                      |
| `403` | (`verifyCreatorOwnership`)       | `creatorId` does not belong to the bearer's user                                                    |
| `404` | `creator.bio.not_found`          | `BioPage` row missing for this creator                                                              |
| `429` | (throttle)                       | Rate limit exceeded (30 req/hour)                                                                   |

## Side effects [#side-effects]

1. **Ownership check** — `verifyCreatorOwnership(creatorId, userId)` → 403 on mismatch.
2. Lookup `BioPage` by `creatorId`; throw `not_found` if missing.
3. **Schedule validation** — if both bounds present, reject when `end <= start`.
4. **Social-link gate** — if `isSocial: true`: lookup `creator.dmActive`, reject when `true`; then platform whitelist check.
5. **Moderation gate** (when `title` supplied) — `trustSafetyService.checkContent(input.title)`; flag → reject.
6. Read `bio.max_links` (admin-managed, default 20). Generate `id = randomUUID()`. Compute `embed = detectEmbedType(input.url)`.
7. **Inside one transaction** with row-lock:
   * `SELECT ... FOR UPDATE` on the `BioPage` row to prevent concurrent appends racing past the cap.
   * `count(BioLink where bioPageId)` ≥ `maxLinks` → throw `max_links` (with `{ maxLinks }` payload).
   * `validateUrl(input.url)` (re-asserts `http(s)://` + `javascript:` block).
   * `stripHtmlTags(input.title)`.
   * `bioLink.create` with assembled fields. `sortOrder` defaults to current `linkCount` (appended). Embed type/meta default to auto-detected if neither supplied.
8. **Cache invalidation** — `invalidateBioCache(creatorId)`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/creators/c1a2b3c4-d5e6-7890-abcd-ef1234567890/links \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "title": "Watch on YouTube",
        "url": "https://youtube.com/watch?v=dQw4w9WgXcQ"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type EmbedType = 'YOUTUBE' | 'SPOTIFY' | 'TIKTOK' | 'SOUNDCLOUD' | 'TWITCH' | 'APPLE_MUSIC' | 'CUSTOM';

    type CreateBioLinkInput = {
      title: string;
      url: string;
      icon?: string;
      sortOrder?: number;
      active?: boolean;
      embedType?: EmbedType;
      embedMeta?: Record<string, unknown>;
      scheduledStart?: string;
      scheduledEnd?: string;
      isSocial?: boolean;
      platform?: string; // required when isSocial: true
    };

    async function addBioLink(accessToken: string, creatorId: string, input: CreateBioLinkInput): Promise<string> {
      const res = await fetch(`https://api.bio.re/api/v1/creators/${creatorId}/links`, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Add link failed'), {
          code: json?.error?.code,
          maxLinks: json?.error?.maxLinks, // present on 'creator.links.max_links'
        });
      }
      return json.data.id as string;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useAddBioLink(creatorId: string) {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (input: CreateBioLinkInput) => {
          const res = await fetch(`/api/v1/creators/${creatorId}/links`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Add link failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
              maxLinks: json?.error?.maxLinks,
            });
          }
          return json.data.id as string;
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['creators', creatorId, 'bio'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/{creatorId}/links', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                           |
| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`              | `151–161` (`addLink`)                                                           |
| DTO (request)  | `apps/api-core/src/modules/creator/dto/creator.dto.ts`                 | `47–80` (`CreateBioLinkDto`)                                                    |
| DTO (response) | `apps/api-core/src/modules/creator/dto/creator-client-response.dto.ts` | `451–454` (`AddLinkResponseDto`)                                                |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`                 | `333–391` (`addLink`), `42–50` (`validateUrl`), `1065–1081` (`detectEmbedType`) |
| Moderation     | `apps/api-core/src/modules/trust-safety/trust-safety.service.ts`       | `checkContent()`                                                                |
| Config keys    | `apps/api-core/src/modules/config/config.service.ts`                   | `bio.max_links` (admin-managed)                                                 |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                                 | `BioPage`, `BioLink`, `CreatorProfile.dmActive`                                 |


# Delete Bio Link (/docs/creator/bio-link-delete)



`DELETE /api/v1/creators/links/:linkId` — 🔑 **Bearer** · Rate limit: **30 req / hour**

Hard-deletes a `BioLink` row. Ownership is checked via the link's bio page → creator → user chain. The owning `creatorId` is **fetched before the delete** so the public bio cache can be invalidated even after the row is gone — failures of that pre-lookup are swallowed and the delete proceeds.



<Callout type="warn">
  **Hard delete, not soft.** Use `PATCH /creators/links/:linkId` with `active: false` if you want a temporarily-hidden link the creator can re-enable. There's no recycle bin or undo flow on this endpoint.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param    | Type          | Validation      | Notes                                                |
| -------- | ------------- | --------------- | ---------------------------------------------------- |
| `linkId` | string (UUID) | `ParseUUIDPipe` | Must belong to a bio page owned by the bearer's user |

No body.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                                                                                                                                                                                                    |
| --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `success` | boolean | Always `true` on 200. The link no longer exists; sortOrder of remaining links is **not** automatically compacted (call `POST /creators/:creatorId/links/reorder` if your UI requires gap-free ordering). |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`        | Reason                                      |
| ----- | ------------------------- | ------------------------------------------- |
| `400` | (validation)              | `linkId` not a valid UUID                   |
| `401` | (guard)                   | Missing / invalid bearer token              |
| `403` | `creator.links.not_owner` | Link's bio page belongs to a different user |
| `404` | `creator.links.not_found` | `BioLink` row missing                       |
| `429` | (throttle)                | Rate limit exceeded (30 req/hour)           |

## Side effects [#side-effects]

1. **Ownership check** — `verifyLinkOwnership(linkId, userId)` → 403 on mismatch.
2. **Pre-fetch creatorId** — read the link's `bioPage.creatorId` while the row still exists (failures are caught and ignored — the delete still proceeds).
3. `prisma.bioLink.delete({ where: { id: linkId } })`.
4. If the pre-fetch succeeded: `invalidateBioCache(creatorId)`. Otherwise the cache will expire naturally.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X DELETE https://api.bio.re/api/v1/creators/links/l1a2b3c4-d5e6-7890-abcd-ef1234567890 \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function deleteBioLink(accessToken: string, linkId: string): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/creators/links/${linkId}`, {
        method: 'DELETE',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Delete link failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useDeleteBioLink(creatorId: string) {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (linkId: string) => {
          const res = await fetch(`/api/v1/creators/links/${linkId}`, { method: 'DELETE' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Delete link failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['creators', creatorId, 'bio'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/links/{linkId}', method: 'delete' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                      | Lines                                                       |
| -------------- | --------------------------------------------------------- | ----------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts` | `176–187` (`deleteLink`), `107–114` (`verifyLinkOwnership`) |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts`     | `SuccessOnlyResponseDto`                                    |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`    | `444–462` (`deleteLink`)                                    |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                    | `BioLink`, `BioPage` (relation chain for ownership)         |


# Update Bio Link (/docs/creator/bio-link-update)



`PATCH /api/v1/creators/links/:linkId` — 🔑 **Bearer** · Rate limit: **30 req / hour**

Sparse update of a single `BioLink`. Ownership is checked via the link's bio page → creator → user chain. URL changes re-validate (`http(s)://` only, `javascript:` blocked) and re-trigger embed auto-detection. Title changes run through trust-safety moderation. Schedule bounds are validated when both are present.



<Callout type="info">
  **Embed re-detection on URL change**: when you update `url` without explicitly setting `embedType` / `embedMeta`, the server re-runs `detectEmbedType()` and writes the freshly detected values. To **clear** an auto-detected embed without changing the URL, set `embedType: 'CUSTOM'` with `embedMeta: {}` explicitly.
</Callout>

<Callout type="warn">
  **Cache invalidation is best-effort.** After the DB write, the server tries to look up the owning `creatorId` to purge the public bio page cache. If that lookup fails (e.g. transient DB issue), the cache will expire naturally on its TTL — the update itself is not rolled back.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param    | Type          | Validation      | Notes                                                |
| -------- | ------------- | --------------- | ---------------------------------------------------- |
| `linkId` | string (UUID) | `ParseUUIDPipe` | Must belong to a bio page owned by the bearer's user |

### Body — `UpdateBioLinkDto` [#body--updatebiolinkdto]

All fields optional. Send only what you want to change.

| Field            | Type              | Validation                                                                          | Notes                                                                                          |
| ---------------- | ----------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `title`          | string            | `MaxLength(100)`                                                                    | HTML-stripped + moderation-checked                                                             |
| `url`            | string            | `IsUrl()`                                                                           | Re-validated; auto-detected embed gets re-applied unless `embedType`/`embedMeta` also supplied |
| `icon`           | string            | `MaxLength(50)`                                                                     | —                                                                                              |
| `sortOrder`      | number            | `IsInt`, `Min(0)`, `Max(1000)`                                                      | —                                                                                              |
| `active`         | boolean           | —                                                                                   | —                                                                                              |
| `embedType`      | enum              | `IsIn(['YOUTUBE','SPOTIFY','TIKTOK','SOUNDCLOUD','TWITCH','APPLE_MUSIC','CUSTOM'])` | Wins over auto-detection                                                                       |
| `embedMeta`      | object            | `IsObject`                                                                          | Wins over auto-detected meta                                                                   |
| `scheduledStart` | string (ISO 8601) | `IsDateString`                                                                      | Pass `null` semantically by sending `undefined` (omit) — no explicit clear-to-null in DTO      |
| `scheduledEnd`   | string (ISO 8601) | `IsDateString`                                                                      | Must be after `scheduledStart` (when both present)                                             |
| `isSocial`       | boolean           | —                                                                                   | —                                                                                              |
| `platform`       | string            | `MaxLength(30)`                                                                     | Lowercased server-side; `null` clears                                                          |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                                                                                       |
| --------- | ------- | ------------------------------------------------------------------------------------------- |
| `success` | boolean | Always `true` on 200. Re-fetch via `GET /creators/:creatorId/bio` for the post-write state. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`               | Reason                                         |
| ----- | -------------------------------- | ---------------------------------------------- |
| `400` | `creator.links.schedule_invalid` | `scheduledEnd <= scheduledStart`               |
| `400` | `creator.links.content_flagged`  | Moderation flagged the new title               |
| `400` | `creator.links.invalid_url`      | URL not `http(s)://` OR contains `javascript:` |
| `400` | (DTO validation)                 | Field length / type / enum failures            |
| `401` | (guard)                          | Missing / invalid bearer token                 |
| `403` | `creator.links.not_owner`        | Link's bio page belongs to a different user    |
| `404` | `creator.links.not_found`        | `BioLink` row missing                          |
| `429` | (throttle)                       | Rate limit exceeded (30 req/hour)              |

## Side effects [#side-effects]

1. **Ownership check** — `verifyLinkOwnership(linkId, userId)` traverses `BioLink → BioPage → CreatorProfile.userId`; mismatch → 403.
2. Schedule bounds validation when both supplied.
3. Build sparse `data` object:
   * `title` → `stripHtmlTags()`.
   * `url` → `validateUrl()`. **If supplied AND `embedType`/`embedMeta` not supplied**, re-run `detectEmbedType()` and inject `embedType` + `embedMeta`.
   * `platform` → lowercased (or `null` to clear).
   * `scheduledStart` / `scheduledEnd` → ISO string parsed to `Date` (or `null`).
4. **Moderation gate** (when `title` supplied) — flag → reject.
5. `prisma.bioLink.update({ where: { id: linkId }, data })`.
6. **Best-effort cache invalidation** — try to look up the link's `creatorId`; if found, `invalidateBioCache(creatorId)`. Failures are swallowed (cache will expire naturally).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X PATCH https://api.bio.re/api/v1/creators/links/l1a2b3c4-d5e6-7890-abcd-ef1234567890 \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "title": "Updated title",
        "active": false
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type UpdateBioLinkInput = {
      title?: string;
      url?: string;
      icon?: string;
      sortOrder?: number;
      active?: boolean;
      embedType?: EmbedType;
      embedMeta?: Record<string, unknown>;
      scheduledStart?: string;
      scheduledEnd?: string;
      isSocial?: boolean;
      platform?: string;
    };

    async function updateBioLink(accessToken: string, linkId: string, input: UpdateBioLinkInput): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/creators/links/${linkId}`, {
        method: 'PATCH',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Update link failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useUpdateBioLink(creatorId: string) {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (vars: { linkId: string; input: UpdateBioLinkInput }) => {
          const res = await fetch(`/api/v1/creators/links/${vars.linkId}`, {
            method: 'PATCH',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(vars.input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Update link failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['creators', creatorId, 'bio'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/links/{linkId}', method: 'patch' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                             | Lines                                                                              |
| -------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`        | `163–174` (`updateLink`), `107–114` (`verifyLinkOwnership`)                        |
| DTO (request)  | `apps/api-core/src/modules/creator/dto/creator.dto.ts`           | `82–115` (`UpdateBioLinkDto`)                                                      |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts`            | `SuccessOnlyResponseDto`                                                           |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`           | `393–442` (`updateLink`), `42–50` (`validateUrl`), `1065–1081` (`detectEmbedType`) |
| Moderation     | `apps/api-core/src/modules/trust-safety/trust-safety.service.ts` | `checkContent()`                                                                   |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                           | `BioLink`, `BioPage` (relation chain for ownership)                                |


# Reorder Bio Links (/docs/creator/bio-links-reorder)



`POST /api/v1/creators/:creatorId/links/reorder` — 🔑 **Bearer** · Rate limit: **30 req / hour**

Atomic reorder. Submit the **full ordered list** of `linkIds`; the server sets `sortOrder = index` for each, all inside a single Prisma transaction. The server verifies every submitted id belongs to the creator's bio page before writing — partial / cross-creator id sets are rejected wholesale.



<Callout type="warn">
  **Submit the full list — not a delta.** If you omit a link's id from the array, its `sortOrder` is **not** changed. There is no implicit "leave others alone" — your client must always send the complete current ordering as you'd like it persisted.
</Callout>

<Callout type="info">
  **Cross-creator id rejection.** The service runs `findMany({ where: { bioPageId, id: { in: linkIds } } })` and compares lengths — any id that doesn't belong to this creator's bio page causes the whole call to fail with `400 not_owned`. No partial writes leak.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param       | Type          | Validation      | Notes                                                       |
| ----------- | ------------- | --------------- | ----------------------------------------------------------- |
| `creatorId` | string (UUID) | `ParseUUIDPipe` | Must match the bearer's `CreatorProfile.id` (otherwise 403) |

### Body — `ReorderLinksDto` [#body--reorderlinksdto]

| Field     | Type      | Required | Validation                   | Notes                                                                        |
| --------- | --------- | -------- | ---------------------------- | ---------------------------------------------------------------------------- |
| `linkIds` | string\[] | ✓        | `IsArray()`, `ArrayUnique()` | The full ordered set of link ids. Position in the array becomes `sortOrder`. |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                                                                                           |
| --------- | ------- | ----------------------------------------------------------------------------------------------- |
| `success` | boolean | Always `true` on 200. Re-fetch via `GET /creators/:creatorId/bio` to read the post-write order. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`         | Reason                                                                    |
| ----- | -------------------------- | ------------------------------------------------------------------------- |
| `400` | (DTO validation)           | `linkIds` not unique / not an array                                       |
| `400` | `creator.links.not_owned`  | At least one submitted `linkId` doesn't belong to this creator's bio page |
| `401` | (guard)                    | Missing / invalid bearer token                                            |
| `403` | (`verifyCreatorOwnership`) | `creatorId` does not belong to the bearer's user                          |
| `404` | `creator.bio.not_found`    | `BioPage` row missing for this creator                                    |
| `429` | (throttle)                 | Rate limit exceeded (30 req/hour)                                         |

## Side effects [#side-effects]

1. **Ownership check** — `verifyCreatorOwnership(creatorId, userId)` → 403 on mismatch.
2. Lookup `BioPage` by `creatorId`; throw `not_found` if missing.
3. **Cross-creator id verification** — `bioLink.findMany({ where: { bioPageId, id: { in: linkIds } } })` (max 100). If `result.length !== linkIds.length` → throw `not_owned`. **No writes occur**.
4. **Atomic write** — build N `bioLink.update({ where: { id }, data: { sortOrder: index } })` operations and run them inside a single `prisma.$transaction(updates)` so all positions land or none do.
5. **Cache invalidation** — `invalidateBioCache(creatorId)`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/creators/c1a2b3c4-d5e6-7890-abcd-ef1234567890/links/reorder \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "linkIds": [
          "l3a2b3c4-d5e6-7890-abcd-ef1234567890",
          "l1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "l2a2b3c4-d5e6-7890-abcd-ef1234567890"
        ]
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function reorderBioLinks(accessToken: string, creatorId: string, linkIds: string[]): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/creators/${creatorId}/links/reorder`, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ linkIds }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Reorder failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useReorderBioLinks(creatorId: string) {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (linkIds: string[]) => {
          const res = await fetch(`/api/v1/creators/${creatorId}/links/reorder`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ linkIds }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Reorder failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        // Optimistic UI: locally re-sort, then call mutation; on error revert
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['creators', creatorId, 'bio'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/{creatorId}/links/reorder', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                          | Lines                          |
| -------------- | ------------------------------------------------------------- | ------------------------------ |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`     | `189–200` (`reorderLinks`)     |
| DTO (request)  | `apps/api-core/src/modules/creator/dto/creator-social.dto.ts` | `35–38` (`ReorderLinksDto`)    |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts`         | `SuccessOnlyResponseDto`       |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`        | `464–483` (`reorderLinks`)     |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                        | `BioPage`, `BioLink.sortOrder` |


# Update Bio Page (/docs/creator/bio-page-update)



`PATCH /api/v1/creators/:creatorId/bio` — 🔑 **Bearer** · Rate limit: **30 req / hour**

Sparse update — only fields present in the body are written. **`bio` is HTML-stripped*&#x2A;, **`customCss` is XSS-sanitized** (`expression(...)`, `javascript:`, non-https `url(...)&#x60; removed), and **`bio` content runs through the trust-safety moderation gate** before persistence. On success, the cached public bio page for this creator is invalidated.



<Callout type="warn">
  **XSS sanitization is destructive.** Submitted `<script>` / `<img onerror=...>` etc. will be silently stripped — the response shape (`{ success: true }`) doesn't tell you what was removed. Validate client-side too if you want to surface "we removed N tags" UI.
</Callout>

<Callout type="info">
  **Content moderation gate (no NSFW).** When `bio` is supplied, it is run through `trustSafetyService.checkContent()`. If the moderation flags it, the entire request fails with `400 creator.bio.content_flagged` and **no fields are written** (the moderation check runs after sparse-data assembly but before the DB write).
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param       | Type          | Validation      | Notes                                                       |
| ----------- | ------------- | --------------- | ----------------------------------------------------------- |
| `creatorId` | string (UUID) | `ParseUUIDPipe` | Must match the bearer's `CreatorProfile.id` (otherwise 403) |

### Body — `UpdateBioPageDto` [#body--updatebiopagedto]

All fields optional. Send only what you want to change.

| Field                    | Type                    | Validation                    | Notes                                                                     |
| ------------------------ | ----------------------- | ----------------------------- | ------------------------------------------------------------------------- |
| `bio`                    | string                  | `MaxLength(5000)`             | HTML-stripped server-side AND moderation-checked                          |
| `templateId`             | string (UUID) \| `null` | `IsUUID('4')` (when not null) | Set to `null` to clear                                                    |
| `themeOverride`          | object                  | —                             | Free-form JSON; not sanitized — keep design tokens, don't smuggle scripts |
| `customCss`              | string                  | `MaxLength(10000)`            | XSS-sanitized (see above)                                                 |
| `embedEnabled`           | boolean                 | —                             | Gates `GET /bio/embed/:username`                                          |
| `published`              | boolean                 | —                             | When `false`, public render returns 404                                   |
| `emailCollectionEnabled` | boolean                 | —                             | Gates `POST /creators/:bioPageId/subscribe`                               |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                                                                                          |
| --------- | ------- | ---------------------------------------------------------------------------------------------- |
| `success` | boolean | Always `true` on 200. Re-fetch via `GET /creators/:creatorId/bio` to see the post-write state. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`            | Reason                                                     |
| ----- | ----------------------------- | ---------------------------------------------------------- |
| `400` | (DTO validation)              | `bio > 5000`, `customCss > 10000`, `templateId` not a UUID |
| `400` | `creator.bio.content_flagged` | Moderation flagged the submitted `bio`                     |
| `401` | (guard)                       | Missing / invalid bearer token                             |
| `403` | (`verifyCreatorOwnership`)    | `creatorId` does not belong to the bearer's user           |
| `404` | `creator.bio.not_found`       | `BioPage` row missing for this creator                     |
| `429` | (throttle)                    | Rate limit exceeded (30 req/hour)                          |

## Side effects [#side-effects]

1. **Ownership check** — `verifyCreatorOwnership(creatorId, userId)` → 403 on mismatch.
2. Build sparse `data` object from defined keys only.
3. **Sanitize**:
   * `bio` → `stripHtmlTags()` (regex `/<[^>]*>/g`).
   * `customCss` → `sanitizeCss()` (blocks `expression(...)`, `javascript:`, non-https/data `url(...)` rewritten to `url(about:blank`, plus tag strip).
4. **Moderation gate** (only when `bio` is supplied): `trustSafetyService.checkContent(input.bio)`. If `flagged`, throw `content_flagged` — **no DB write occurs**.
5. `prisma.bioPage.update({ where: { creatorId }, data })`.
6. Audit log: `[bio] Updated for creator {creatorId}`.
7. **Cache invalidation** — `invalidateBioCache(creatorId)` purges the public-render cache for this creator's username so the next `GET /bio/:username` re-builds from DB.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X PATCH https://api.bio.re/api/v1/creators/c1a2b3c4-d5e6-7890-abcd-ef1234567890/bio \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "bio": "Designer & creator",
        "published": true,
        "emailCollectionEnabled": true
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type UpdateBioPageInput = {
      bio?: string;
      templateId?: string | null;
      themeOverride?: Record<string, unknown>;
      customCss?: string;
      embedEnabled?: boolean;
      published?: boolean;
      emailCollectionEnabled?: boolean;
    };

    async function updateBioPage(accessToken: string, creatorId: string, input: UpdateBioPageInput): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/creators/${creatorId}/bio`, {
        method: 'PATCH',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Bio page update failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useUpdateBioPage(creatorId: string) {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (input: UpdateBioPageInput) => {
          const res = await fetch(`/api/v1/creators/${creatorId}/bio`, {
            method: 'PATCH',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Bio page update failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['creators', creatorId, 'bio'] });
          qc.invalidateQueries({ queryKey: ['creators', 'profile'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/{creatorId}/bio', method: 'patch' }]" hasHead="false" />

## Source [#source]

| Source          | Path                                                             | Lines                                                                                                                      |
| --------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Controller      | `apps/api-core/src/modules/creator/creator.controller.ts`        | `136–148` (`updateBioPage`)                                                                                                |
| DTO (request)   | `apps/api-core/src/modules/creator/dto/creator.dto.ts`           | `21–45` (`UpdateBioPageDto`)                                                                                               |
| DTO (response)  | `apps/api-core/src/common/dto/common-response.dto.ts`            | `SuccessOnlyResponseDto`                                                                                                   |
| Service         | `apps/api-core/src/modules/creator/creator.service.ts`           | `306–327` (`updateBioPage`), `30–32` (`stripHtmlTags`), `34–40` (`sanitizeCss`)                                            |
| Moderation gate | `apps/api-core/src/modules/trust-safety/trust-safety.service.ts` | `checkContent()`                                                                                                           |
| Cache           | `apps/api-core/src/modules/creator/bio-analytics.service.ts`     | `invalidateCache()` (in-memory bio page cache)                                                                             |
| Prisma model    | `packages/prisma/prisma/schema.prisma`                           | `BioPage` (`bio` / `templateId` / `themeOverride` / `customCss` / `embedEnabled` / `published` / `emailCollectionEnabled`) |


# Get Bio Page (Editor) (/docs/creator/bio-page)



`GET /api/v1/creators/:creatorId/bio` — 🔑 **Bearer**

Returns the **creator-owned** view of the `BioPage` for a `creatorId`, including all `BioLink` rows (ordered by `sortOrder ASC`) and the joined `BioTemplate`. **Ownership is enforced** — the bearer's user id must match `CreatorProfile.userId`; otherwise 403.



<Callout type="info">
  **Editor path, not render path.** This endpoint returns the raw editable record (including `customCss`, `themeOverride`, `published` flag) — render the public view via `GET /bio/:username` (cached, scope-filtered). Use this only inside the creator dashboard.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param       | Type          | Validation      | Notes                                                       |
| ----------- | ------------- | --------------- | ----------------------------------------------------------- |
| `creatorId` | string (UUID) | `ParseUUIDPipe` | Must match the bearer's `CreatorProfile.id` (otherwise 403) |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<BioPageResponseDto>` [#200-ok--apiresponseofbiopageresponsedto]

```json
{
  "success": true,
  "data": {
    "id": "b1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "creatorId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "templateId": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "bio": "Designer & creator",
    "themeOverride": null,
    "customCss": null,
    "embedEnabled": false,
    "published": true,
    "emailCollectionEnabled": false,
    "links": [
      {
        "id": "l1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "title": "My Site",
        "url": "https://example.com",
        "icon": "globe",
        "sortOrder": 0,
        "active": true,
        "isSocial": false,
        "platform": null,
        "embedType": null,
        "embedMeta": null,
        "scheduledStart": null,
        "scheduledEnd": null
      }
    ],
    "template": { /* BioTemplate row when templateId is set */ }
  }
}
```

### Top-level fields [#top-level-fields]

| Field                    | Type                  | Notes                                                                                                                         |
| ------------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `id`                     | string (UUID)         | `BioPage.id`                                                                                                                  |
| `creatorId`              | string (UUID)         | Owning `CreatorProfile.id`                                                                                                    |
| `templateId`             | string (UUID) \| null | Selected template (null when none)                                                                                            |
| `bio`                    | string \| null        | Body — stored sanitized (HTML tags stripped at write time)                                                                    |
| `themeOverride`          | object \| null        | Free-form JSON theme override                                                                                                 |
| `customCss`              | string \| null        | Custom CSS — stored sanitized (`expression(...)`, `javascript:`, non-https `url(...)` stripped at write time)                 |
| `embedEnabled`           | boolean               | When `true`, third-party sites may embed via iframe (also gates `GET /bio/embed/:username`)                                   |
| `published`              | boolean               | When `false`, public render endpoint returns 404                                                                              |
| `emailCollectionEnabled` | boolean               | When `true`, `POST /creators/:bioPageId/subscribe` accepts emails                                                             |
| `links`                  | array                 | All `BioLink` rows (ordered by `sortOrder ASC`) — includes inactive / scheduled-future links (the public render filters them) |
| `template`               | object \| null        | Joined `BioTemplate` when `templateId` is set                                                                                 |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`         | Reason                                           |
| ----- | -------------------------- | ------------------------------------------------ |
| `400` | (validation)               | `creatorId` not a valid UUID                     |
| `401` | (guard)                    | Missing / invalid bearer token                   |
| `403` | (`verifyCreatorOwnership`) | `creatorId` does not belong to the bearer's user |
| `404` | `creator.bio.not_found`    | `BioPage` row missing for this creator           |

## Side effects [#side-effects]

1. **Ownership check** — `verifyCreatorOwnership(creatorId, userId)` reads `CreatorProfile.userId` and throws 403 on mismatch.
2. `prisma.bioPage.findUnique({ where: { creatorId }, include: { links: { orderBy: { sortOrder: 'asc' } }, template: true } })`.
3. Throw `not_found` if missing.
4. Return the row. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/creators/c1a2b3c4-d5e6-7890-abcd-ef1234567890/bio \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function getBioPage(accessToken: string, creatorId: string): Promise<unknown> {
      const res = await fetch(`https://api.bio.re/api/v1/creators/${creatorId}/bio`, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Bio page fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data; // BioPageResponseDto with .links and .template
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const creatorKeys = {
      bioPage: (creatorId: string) => ['creators', creatorId, 'bio'] as const,
    };

    export function useBioPage(creatorId: string) {
      return useQuery({
        queryKey: creatorKeys.bioPage(creatorId),
        queryFn: async () => {
          const res = await fetch(`/api/v1/creators/${creatorId}/bio`);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Bio page fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data;
        },
        enabled: Boolean(creatorId),
        staleTime: 30_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/{creatorId}/bio', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                                                             |
| -------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`              | `125–134` (`getBioPage`)                                                                                          |
| DTO (response) | `apps/api-core/src/modules/creator/dto/creator-client-response.dto.ts` | `105–180` (`BioPageResponseDto`)                                                                                  |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`                 | `297–304` (`getBioPage`), ownership helper `verifyCreatorOwnership`                                               |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                                 | `BioPage`, `BioLink` (relation `links`), `BioTemplate` (relation `template`), `CreatorProfile.userId` (ownership) |


# Get Public Bio Page (Fan-side) (/docs/creator/bio-public)



`GET /api/v1/bio/:username` — 🌐 **Public** · Rate limit: **120 req / minute**

The **canonical fan-side bio page render** — by username, no auth. Returns the visible payload only: profile basics, the published `BioPage` with **scheduling-filtered active links**, the active client theme preset, public DM packages, verified social accounts, and (when enabled) the "Powered by BIO.RE" referral badge. **Cached** in-memory and at the CDN edge (`s-maxage=60, stale-while-revalidate=300`).



<Callout type="warn">
  **Status filter — these all return 404, not 403**:

  * User not `ACTIVE` (`SUSPENDED` / `BANNED` / `DELETED` / `DEACTIVATED`)
  * Creator not `ACTIVE` (creator-side `SUSPENDED` / `BANNED` / `DEACTIVATED`)
  * `BioPage.published === false`

  The 404 is intentional — refusing to confirm an account exists when it shouldn't be visible. Don't try to disambiguate "doesn't exist" vs "hidden" client-side.
</Callout>

<Callout type="info">
  **Link filter is server-side**: only `active = true` links with `scheduledStart <= now <= scheduledEnd` (or null bounds) are returned. The creator-side editor (`GET /creators/:creatorId/bio`) returns ALL links so the editor can show inactive / future ones.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param      | Type   | Notes                                           |
| ---------- | ------ | ----------------------------------------------- |
| `username` | string | Lowercased server-side; case-insensitive lookup |

No body, no headers required.

## Response headers [#response-headers]

| Header          | Value                                             |
| --------------- | ------------------------------------------------- |
| `Cache-Control` | `public, s-maxage=60, stale-while-revalidate=300` |

## Response [#response]

### `200 OK` — `ApiResponseOf<PublicBioPageResponseDto>` [#200-ok--apiresponseofpublicbiopageresponsedto]

```json
{
  "success": true,
  "data": {
    "userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "username": "johndoe",
    "displayName": "John Doe",
    "bio": "Designer & creator",
    "avatarUrl": "https://cdn.bio.re/avatars/abc.webp",
    "level": "BRONZE",
    "dmType": "SINGLE_PAY",
    "dmPrice": "5.00",
    "dmActive": true,
    "vacationMode": false,
    "avgRating": "4.5",
    "ratingCount": 42,
    "userStatus": "ACTIVE",
    "bioPage": {
      "id": "b1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "bio": "Designer & creator",
      "templateId": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "themeOverride": null,
      "customCss": null,
      "embedEnabled": false,
      "published": true,
      "emailCollectionEnabled": true,
      "links": [
        { "id": "l1...", "title": "My Site", "url": "https://example.com", "icon": "globe", "isSocial": false, "platform": null, "embedType": null, "embedMeta": null }
      ],
      "template": { "name": "Minimal Dark", "tokens": { /* design tokens */ } }
    },
    "socialAccounts": [
      { "platform": "INSTAGRAM", "platformUsername": "johndoe" }
    ],
    "dmPackages": [
      { "id": "d1...", "dmType": "SINGLE_PAY", "price": "5.00" }
    ],
    "themePreset": {
      "slug": "midnight",
      "name": "Midnight",
      "lightTokens": {},
      "darkTokens": {},
      "typography": {},
      "layout": {}
    },
    "referralBadge": {
      "enabled": true,
      "referralCode": "ABC123",
      "url": "https://bio.re/r/ABC123"
    }
  }
}
```

### Top-level fields [#top-level-fields]

| Field                               | Type                          | Notes                                                                                                                                  |
| ----------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `userId`                            | string (UUID)                 | The creator's user id                                                                                                                  |
| `username`                          | string                        | Lowercased echo of the path param                                                                                                      |
| `displayName` / `bio` / `avatarUrl` | string \| null                | Profile basics from `User`                                                                                                             |
| `level`                             | enum                          | `BRONZE` / `SILVER` / `GOLD` / `PLATINUM`                                                                                              |
| `dmType` / `dmPrice`                | enum \| null / string \| null | DM pricing snapshot                                                                                                                    |
| `dmActive`                          | boolean                       | **Computed** — `creatorProfile.dmActive && !vacationMode` (vacation forces DMs off in the public view even if creator left them on)    |
| `vacationMode`                      | boolean                       | `CreatorProfile.vacationMode`                                                                                                          |
| `avgRating` / `ratingCount`         | string \| null / number       | Aggregate rating                                                                                                                       |
| `userStatus`                        | enum                          | Always `ACTIVE` here — non-active users 404                                                                                            |
| `bioPage`                           | object \| null                | The published page (links scheduling-filtered server-side)                                                                             |
| `socialAccounts`                    | array                         | Verified social accounts (`verified = true`), max 50, sorted by oldest connection                                                      |
| `dmPackages`                        | array                         | Active `DMPackage` rows for this creator (max 10)                                                                                      |
| `themePreset`                       | object \| null                | Currently-active CLIENT theme preset (status `PUBLISHED`, `isActive: true`) — admin-managed                                            |
| `referralBadge`                     | object \| undefined           | Present only when the referral service successfully resolved a link — failures fall back to undefined (the badge is hidden gracefully) |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`      | Reason                                                                             |
| ----- | ----------------------- | ---------------------------------------------------------------------------------- |
| `404` | `creator.bio.not_found` | User unknown / not ACTIVE / creator status blocked / `BioPage.published === false` |
| `429` | (throttle)              | Rate limit exceeded (120 req/min)                                                  |

## Side effects [#side-effects]

1. **In-memory cache hit path** — if the bio page for this username is in the in-memory cache and not expired, return the cached payload directly (LRU touch on access). TTL = `analytics.bio_cache_ttl_minutes` (admin-managed, default 5).
2. **Cache miss** — `prisma.user.findUnique({ where: { username: lowercased } })` selecting (`id`, `displayName`, `bio`, `avatarUrl`, `status`). If missing OR `status !== ACTIVE` → return null → 404.
3. Read `CreatorProfile` joined with `BioPage` (with scheduling-filtered links + template).
4. **Status filter** — if `creator.creatorStatus IN (SUSPENDED, BANNED, DEACTIVATED)` → 404.
5. **Published filter** — if `bioPage.published !== true` → 404.
6. **In parallel**: read verified `SocialAccount` rows, the active CLIENT `ThemePreset`, active `DMPackage` rows, and the referral link (failure-safe — bad referral lookups don't break the page).
7. Compute `dmActive = creator.dmActive && !vacationMode`.
8. Cache the assembled payload (LRU eviction at 10,000 entries) and return it.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/bio/johndoe
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function getPublicBioPage(username: string): Promise<unknown> {
      const res = await fetch(`https://api.bio.re/api/v1/bio/${encodeURIComponent(username)}`);
      if (res.status === 404) return null; // Treat hidden / unknown identically per security note
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Bio page fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data; // PublicBioPageResponseDto
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const bioKeys = {
      public: (username: string) => ['bio', 'public', username.toLowerCase()] as const,
    };

    export function usePublicBioPage(username: string) {
      return useQuery({
        queryKey: bioKeys.public(username),
        queryFn: async () => {
          const res = await fetch(`/api/v1/bio/${encodeURIComponent(username)}`);
          if (res.status === 404) return null;
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Bio page fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data;
        },
        enabled: Boolean(username),
        // Match the CDN cache window
        staleTime: 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/bio/{username}', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                  | Lines                                                                                                                                                 |
| -------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/bio-analytics.controller.ts`       | `57–70` (`getPublicBioPage`)                                                                                                                          |
| DTO (response) | `apps/api-core/src/modules/creator/dto/bio-analytics-response.dto.ts` | `152–202` (`PublicBioPageResponseDto`), nested DTOs `30–144`                                                                                          |
| Service        | `apps/api-core/src/modules/creator/bio-analytics.service.ts`          | `52–158` (`getCachedBioPage`), `163–167` (`invalidateCache`)                                                                                          |
| Cache config   | `apps/api-core/src/modules/config/config.service.ts`                  | `analytics.bio_cache_ttl_minutes` (admin-managed)                                                                                                     |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                                | `User`, `CreatorProfile`, `BioPage`, `BioLink` (scheduling), `BioTemplate`, `SocialAccount`, `DMPackage`, `ThemePreset` (CLIENT, PUBLISHED, isActive) |


# List Bio Templates (/docs/creator/bio-templates)



`GET /api/v1/bio/templates` — 🌐 **Public** · Rate limit: **60 req / minute**

Returns all `BioTemplate` rows where `active = true`, ordered by `sortOrder ASC`. Public — no auth required because templates are part of the visible product catalog. **CDN-cached** with `Cache-Control: public, s-maxage=300, stale-while-revalidate=600` (5min fresh, 10min stale-allowed).



<Callout type="info">
  The catalog is admin-managed — templates are created / activated / sorted via the admin dashboard. This endpoint is the read side; clients should call it on creator-editor mount and re-use the response throughout the session.
</Callout>

## Request [#request]

No body, no params, no headers required.

## Response headers [#response-headers]

| Header          | Value                                              | Notes                                   |
| --------------- | -------------------------------------------------- | --------------------------------------- |
| `Cache-Control` | `public, s-maxage=300, stale-while-revalidate=600` | 5min fresh + 10min stale window for CDN |

## Response [#response]

### `200 OK` — `ArrayApiResponseOf<BioTemplateListItemDto>` [#200-ok--arrayapiresponseofbiotemplatelistitemdto]

```json
{
  "success": true,
  "data": [
    {
      "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "Minimal Dark",
      "description": "Clean and minimal dark theme",
      "tokens": { "color": { "bg": "#000", "text": "#fff" } },
      "thumbnail": "https://cdn.bio.re/templates/minimal-dark.png"
    }
  ]
}
```

### Item fields [#item-fields]

| Field         | Type           | Notes                                                                       |
| ------------- | -------------- | --------------------------------------------------------------------------- |
| `id`          | string (UUID)  | `BioTemplate.id` — pass to `PATCH /creators/:creatorId/bio` as `templateId` |
| `name`        | string         | Display name                                                                |
| `description` | string \| null | Optional short description                                                  |
| `tokens`      | object         | Theme token JSON — design system payload (colors, spacing, typography)      |
| `thumbnail`   | string \| null | CDN URL of the template preview image                                       |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `429` | (throttle)         | Rate limit exceeded (60 req/min) |

## Side effects [#side-effects]

1. `prisma.bioTemplate.findMany({ where: { active: true }, orderBy: { sortOrder: 'asc' }, select: { id, name, description, tokens, thumbnail } })`.
2. Return the array. **No mutations**, no auth, no per-user state.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/bio/templates
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type BioTemplateListItem = {
      id: string;
      name: string;
      description: string | null;
      tokens: unknown;
      thumbnail: string | null;
    };

    async function listBioTemplates(): Promise<BioTemplateListItem[]> {
      const res = await fetch('https://api.bio.re/api/v1/bio/templates');
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Templates fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const bioKeys = {
      templates: () => ['bio', 'templates'] as const,
    };

    export function useBioTemplates() {
      return useQuery({
        queryKey: bioKeys.templates(),
        queryFn: async () => {
          const res = await fetch('/api/v1/bio/templates');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Templates fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as BioTemplateListItem[];
        },
        // Catalog rarely changes within a session — match the CDN cache window
        staleTime: 5 * 60_000,
        gcTime: 60 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/bio/templates', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source              | Path                                                                  | Lines                                 |
| ------------------- | --------------------------------------------------------------------- | ------------------------------------- |
| Controller          | `apps/api-core/src/modules/creator/bio-analytics.controller.ts`       | `45–55` (`listTemplates`)             |
| DTO (response item) | `apps/api-core/src/modules/creator/dto/bio-analytics-response.dto.ts` | `11–26` (`BioTemplateListItemDto`)    |
| Service             | `apps/api-core/src/modules/creator/bio-analytics.service.ts`          | `37–43` (`listTemplates`)             |
| Prisma model        | `packages/prisma/prisma/schema.prisma`                                | `BioTemplate` (`active`, `sortOrder`) |


# Track Bio Link Click (/docs/creator/bio-track-click)



`POST /api/v1/bio/:bioPageId/click` — 🌐 **Public** · Rate limit: **60 req / minute**

Records a click on a bio link. Two writes run **in parallel**:

1. `BioLink.clickCount += 1` (silently swallows errors — analytics is non-critical)
2. Append a `BioPageView` row with `linkClicked = linkId`

Both are best-effort fire-and-forget — a non-existent `linkId` won't fail the request; the view row is still inserted (with `linkClicked` referencing the bad id) for forensic visibility.



<Callout type="info">
  The endpoint records the click on the **bio page** scope, not the link scope — that's why `bioPageId` is the path param and `linkId` is in the body. A single page can hold many links, and the analytics table tracks everything against the page so the breakdowns aggregate cleanly.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param       | Type          | Validation      | Notes                             |
| ----------- | ------------- | --------------- | --------------------------------- |
| `bioPageId` | string (UUID) | `ParseUUIDPipe` | The page hosting the clicked link |

### Body — `TrackClickDto` [#body--trackclickdto]

| Field       | Type          | Required | Validation   | Notes                                                                                                              |
| ----------- | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------ |
| `linkId`    | string (UUID) | ✓        | `IsUUID()`   | The link that was clicked. A bad id silently no-ops the `clickCount` increment but the view row is still recorded. |
| `visitorId` | string        | optional | `IsString()` | Stable client-generated id (cookie / localStorage UUID) for unique-visitor de-duplication                          |

The DTO does **not** carry `referrer` — the controller passes it as `undefined` to the service and the row is inserted without it.

No headers required.

## Response [#response]

### `200 OK` — `ApiResponseOf<TrackResponseDto>` [#200-ok--apiresponseoftrackresponsedto]

```json
{
  "success": true,
  "data": {
    "tracked": true
  }
}
```

| Field     | Type    | Notes                |
| --------- | ------- | -------------------- |
| `tracked` | boolean | Always `true` on 200 |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                                             |
| ----- | ------------------ | -------------------------------------------------- |
| `400` | (DTO validation)   | `bioPageId` not UUID; `linkId` missing or not UUID |
| `429` | (throttle)         | Rate limit exceeded (60 req/min)                   |

## Side effects [#side-effects]

**In parallel** (`Promise.all`):

1. `prisma.bioLink.update({ where: { id: linkId }, data: { clickCount: { increment: 1 } } })` — wrapped in `.catch(() => {})` so a non-existent or already-deleted link doesn't fail the request.
2. `prisma.bioPageView.create({ id: randomUUID(), bioPageId, visitorId, referrer: undefined, linkClicked: linkId })`.

Both writes are independent — failure of one doesn't roll back the other.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST 'https://api.bio.re/api/v1/bio/b1a2b3c4-d5e6-7890-abcd-ef1234567890/click' \
      -H 'Content-Type: application/json' \
      -d '{
        "linkId": "l1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "visitorId": "cookie-uuid-12345"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type TrackClickInput = {
      linkId: string;
      visitorId?: string;
    };

    async function trackBioClick(bioPageId: string, input: TrackClickInput): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/bio/${bioPageId}/click`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(input),
      });
      if (!res.ok) {
        console.warn('Bio click tracking failed:', res.status);
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useTrackBioClick() {
      return useMutation({
        mutationFn: async (vars: { bioPageId: string; input: TrackClickInput }) => {
          await fetch(`/api/v1/bio/${vars.bioPageId}/click`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(vars.input),
          });
          // Don't throw — analytics failures must not block the actual link navigation
        },
        retry: false,
      });
    }

    // Usage: fire the mutation in onClick, then perform the navigation immediately
    // (don't await — the click should happen even if tracking is slow)
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/bio/{bioPageId}/click', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                  | Lines                                                                    |
| -------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/creator/bio-analytics.controller.ts`       | `113–124` (`trackClick`)                                                 |
| DTO (request)  | `apps/api-core/src/modules/creator/dto/bio-analytics.dto.ts`          | `14–17` (`TrackClickDto`)                                                |
| DTO (response) | `apps/api-core/src/modules/creator/dto/bio-analytics-response.dto.ts` | `214–217` (`TrackResponseDto`)                                           |
| Service        | `apps/api-core/src/modules/creator/bio-analytics.service.ts`          | `207–224` (`trackLinkClick`)                                             |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                                | `BioLink.clickCount` (counter), `BioPageView` (with `linkClicked` field) |


# Track Bio Page View (/docs/creator/bio-track-view)



`POST /api/v1/bio/:bioPageId/view` — 🌐 **Public** · Rate limit: **60 req / minute**

Appends a `BioPageView` row for analytics. Public — no auth required (the bio page itself is public). The server **always re-derives `userAgent` from the request header** (client-supplied is ignored), and falls back to **server-side UA parsing** for `device` / `browser` and **GeoIP + CDN-header lookup** for `country` when the client doesn't supply them.



<Callout type="warn">
  **Server-side override semantics:**

  * `userAgent` — **always** from the request header. The `userAgent` field in the body is read but immediately overwritten.
  * `device` / `browser` — body wins when present; otherwise UAParser-derived from the request UA header.
  * `country` — body wins when present; otherwise GeoIP lookup against the resolved client IP, falling back to the platform CDN's country header (e.g. `cf-ipcountry` style header).

  Don't rely on tampered values to be persisted — the server treats the request headers as truth for things it can derive itself.
</Callout>

<Callout type="info">
  **IP handling is privacy-preserving.** The raw client IP is resolved (priority: `cf-connecting-ip` style CDN header → first entry of `x-forwarded-for` → `req.ip`), used **only** for the GeoIP lookup, and never persisted or logged on failure paths. The `BioPageView` row stores `country` (a 2-letter code), not the IP.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param       | Type          | Validation      | Notes                 |
| ----------- | ------------- | --------------- | --------------------- |
| `bioPageId` | string (UUID) | `ParseUUIDPipe` | The page being viewed |

### Body — `TrackViewDto` [#body--trackviewdto]

All fields optional. Send what your client knows; the server fills the rest.

| Field       | Type    | Validation    | Notes                                                                                                 |
| ----------- | ------- | ------------- | ----------------------------------------------------------------------------------------------------- |
| `visitorId` | string  | `IsString()`  | Stable client-generated id (e.g. cookie / localStorage UUID) — used to de-duplicate "unique visitors" |
| `referrer`  | string  | `IsString()`  | The referring URL the client navigated from                                                           |
| `userAgent` | string  | `IsString()`  | **Ignored — server overwrites from request header**                                                   |
| `country`   | string  | `IsString()`  | 2-letter country code; if absent, server resolves via GeoIP / CDN header                              |
| `device`    | string  | `IsString()`  | `mobile` / `tablet` / `desktop`; if absent, server derives from UA                                    |
| `browser`   | string  | `IsString()`  | Browser name; if absent, server derives from UA                                                       |
| `isEmbed`   | boolean | `IsBoolean()` | Set to `true` when fired from inside the iframe embed (so analytics can split embed vs direct)        |

No headers required.

## Response [#response]

### `200 OK` — `ApiResponseOf<TrackResponseDto>` [#200-ok--apiresponseoftrackresponsedto]

```json
{
  "success": true,
  "data": {
    "tracked": true
  }
}
```

| Field     | Type    | Notes                                      |
| --------- | ------- | ------------------------------------------ |
| `tracked` | boolean | Always `true` on 200 — the row was created |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                                              |
| ----- | ------------------ | --------------------------------------------------- |
| `400` | (validation)       | `bioPageId` not a valid UUID; field type mismatches |
| `429` | (throttle)         | Rate limit exceeded (60 req/min)                    |

## Side effects [#side-effects]

1. **Server UA derivation**: read `req.headers['user-agent']`; parse via UAParser:
   * `device = body.device ?? (parsed.device.type === 'mobile' ? 'mobile' : 'tablet' if tablet else 'desktop')`.
   * `browser = body.browser ?? parsed.browser.name`.
2. **Country resolution** (when `body.country` absent):
   * Resolve client IP: prefer `cf-connecting-ip` style CDN header, fall back to first entry of `x-forwarded-for`, fall back to `req.ip`.
   * GeoIP lookup against the resolved IP (failures swallowed — raw IP never logged).
   * Fallback: read the platform CDN's country header (e.g. `cf-ipcountry` style) when GeoIP returned nothing.
3. `prisma.bioPageView.create({ id, bioPageId, visitorId, referrer, userAgent, country, device, browser, isEmbed: false })` — `isEmbed` defaults to `false` if omitted.
4. Return `{ tracked: true }`. **No mutations** beyond the single insert.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST 'https://api.bio.re/api/v1/bio/b1a2b3c4-d5e6-7890-abcd-ef1234567890/view' \
      -H 'Content-Type: application/json' \
      -d '{
        "visitorId": "cookie-uuid-12345",
        "referrer": "https://twitter.com/johndoe",
        "isEmbed": false
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type TrackViewInput = {
      visitorId?: string;
      referrer?: string;
      country?: string;       // server resolves if absent
      device?: string;        // server derives from UA if absent
      browser?: string;       // server derives from UA if absent
      isEmbed?: boolean;
      // userAgent: omit — server always uses request header
    };

    async function trackBioView(bioPageId: string, input: TrackViewInput = {}): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/bio/${bioPageId}/view`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(input),
      });
      // Fire-and-forget pattern is safe — analytics shouldn't block UI
      if (!res.ok) {
        console.warn('Bio view tracking failed:', res.status);
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useTrackBioView() {
      return useMutation({
        mutationFn: async (vars: { bioPageId: string; input?: TrackViewInput }) => {
          await fetch(`/api/v1/bio/${vars.bioPageId}/view`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(vars.input ?? {}),
          });
          // Don't throw — analytics failures should not surface to the user
        },
        retry: false, // Already a fire-and-forget — don't double-count on retry
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/bio/{bioPageId}/view', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                  | Lines                                                  |
| -------------- | --------------------------------------------------------------------- | ------------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/creator/bio-analytics.controller.ts`       | `72–111` (`trackView` — UA + GeoIP + CDN header logic) |
| DTO (request)  | `apps/api-core/src/modules/creator/dto/bio-analytics.dto.ts`          | `4–12` (`TrackViewDto`)                                |
| DTO (response) | `apps/api-core/src/modules/creator/dto/bio-analytics-response.dto.ts` | `214–217` (`TrackResponseDto`)                         |
| Service        | `apps/api-core/src/modules/creator/bio-analytics.service.ts`          | `180–202` (`trackView`)                                |
| GeoIP          | `packages/geoip/`                                                     | `GeoIPService.lookup()`                                |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                                | `BioPageView`                                          |


# Get Recent Activity (/docs/creator/dashboard-activity)



`GET /api/v1/creators/dashboard/activity` — 🔑 **Bearer**

Returns a merged activity feed of the creator's **recent messages received**, **processed payouts**, and **new confirmed bio-page email subscribers**. Each source pulls up to `limit` items independently; the union is sorted by timestamp descending and sliced to `limit`. Default limit is `10`, server clamps to `[1, 20]`.



<Callout type="info">
  **Why bio-email subscribers stand in for "followers".** There is no dedicated `Follow` model today — the closest signal of "someone newly engaged with this creator" is a confirmed `BioEmailSubscriber`. That choice keeps the activity feed populated for new creators without inventing data. If a `Follow` model is added later, this endpoint will gain a new activity type rather than replacing this one.
</Callout>

<Callout type="warn">
  **Limit clamps server-side.** `?limit=0` becomes `1`, `?limit=999` becomes `20`. Pagination beyond 20 isn't exposed — design the UI for "recent activity glance" not full history.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param   | Type   | Default | Validation                                  | Notes                                |
| ------- | ------ | ------- | ------------------------------------------- | ------------------------------------ |
| `limit` | number | `10`    | `ParseIntPipe`, server-clamped to `[1, 20]` | How many items to return after merge |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<ActivityResponseDto>` [#200-ok--apiresponseofactivityresponsedto]

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "type": "message_received",
        "title": "New message from @johndoe",
        "timestamp": "2026-04-29T20:04:00.000Z",
        "meta": { "messageId": "m1a2b3c4-d5e6-7890-abcd-ef1234567890" }
      },
      {
        "type": "payout_processed",
        "title": "Payout of 250.00 processed",
        "timestamp": "2026-04-29T19:50:00.000Z",
        "meta": { "payoutId": "p1a2y3o4-u5t6-7890-abcd-ef1234567890", "amount": "250.00" }
      },
      {
        "type": "follower_new",
        "title": "Alice subscribed to your bio",
        "timestamp": "2026-04-29T19:30:00.000Z",
        "meta": { "subscriberId": "s1u2b3c4-d5e6-7890-abcd-ef1234567890" }
      }
    ]
  }
}
```

### Activity types [#activity-types]

| `type`             | Source                                                            | `title` template                                                      | `meta`                                                          |
| ------------------ | ----------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------- |
| `message_received` | `Message where receiverId = userId`                               | `New message from <senderDisplayName ?? senderUsername ?? 'Someone'>` | `{ messageId }`                                                 |
| `payout_processed` | `PayoutRequest where creatorId AND status = PROCESSED`            | `Payout of <amount> processed`                                        | `{ payoutId, amount }` (amount as string for decimal precision) |
| `follower_new`     | `BioEmailSubscriber where bioPage.creatorId AND confirmed = true` | `<name ?? 'Someone'> subscribed to your bio`                          | `{ subscriberId }`                                              |

### Item fields [#item-fields]

| Field       | Type              | Notes                                                                                                                         |
| ----------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `type`      | string            | One of the three values above. Render-by-type, not text parsing.                                                              |
| `title`     | string            | Server-rendered English. Localize client-side off `type` + `meta` if needed.                                                  |
| `timestamp` | string (ISO 8601) | Source-specific timestamp: `Message.createdAt` / `PayoutRequest.processedAt ?? createdAt` / `BioEmailSubscriber.subscribedAt` |
| `meta`      | object            | Type-dependent extras (see table). Optional — absent in the rare case of no extras.                                           |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`           | Reason                            |
| ----- | ---------------------------- | --------------------------------- |
| `401` | (guard)                      | Missing / invalid bearer token    |
| `404` | `creator.activity.not_found` | No `CreatorProfile` for this user |

## Side effects [#side-effects]

1. Lookup `CreatorProfile.id` by `userId`; throw `not_found` if missing.
2. Clamp `limit` to `[1, 20]` (`safeLimit`).
3. **In parallel** (`Promise.all`):
   * `Message.findMany({ where: receiverId, orderBy createdAt desc, take safeLimit, select id + createdAt + sender { displayName, username } })`.
   * `PayoutRequest.findMany({ where creatorId AND status PROCESSED, orderBy processedAt desc, take safeLimit, select id + amount + processedAt + createdAt })`.
   * `BioEmailSubscriber.findMany({ where bioPage.creatorId AND confirmed, orderBy subscribedAt desc, take safeLimit, select id + name + subscribedAt })`.
4. Normalize all rows to the common `{ type, title, timestamp, meta? }` shape.
5. Sort by `timestamp DESC`; slice to `safeLimit`.
6. Convert `Date` timestamps to ISO 8601 strings; return `{ items }`. No mutations.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/creators/dashboard/activity?limit=10' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type ActivityType = 'message_received' | 'payout_processed' | 'follower_new';

    type ActivityItem = {
      type: ActivityType;
      title: string;
      timestamp: string;
      meta?: Record<string, unknown>;
    };

    async function getActivity(accessToken: string, limit = 10): Promise<ActivityItem[]> {
      const url = new URL('https://api.bio.re/api/v1/creators/dashboard/activity');
      url.searchParams.set('limit', String(limit));
      const res = await fetch(url, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Activity fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.items;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const creatorKeys = {
      activity: (limit: number) => ['creators', 'dashboard', 'activity', limit] as const,
    };

    export function useActivity(limit = 10) {
      return useQuery({
        queryKey: creatorKeys.activity(limit),
        queryFn: async () => {
          const url = new URL('/api/v1/creators/dashboard/activity', window.location.origin);
          url.searchParams.set('limit', String(limit));
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Activity fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.items as ActivityItem[];
        },
        staleTime: 30_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/dashboard/activity', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                                                                                                              |
| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`              | `112–122` (`getActivity`)                                                                                                                                          |
| DTO (response) | `apps/api-core/src/modules/creator/dto/creator-client-response.dto.ts` | `437–440` (`ActivityResponseDto`), `423–435` (nested `ActivityItemDto`)                                                                                            |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`                 | `982–1059` (`getActivity`)                                                                                                                                         |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                                 | `Message` (with `User` join via `sender`), `PayoutRequest` (status `PROCESSED`), `BioEmailSubscriber` (`confirmed = true`), `BioPage` (relation), `CreatorProfile` |


# Get Setup Checklist (/docs/creator/dashboard-checklist)



`GET /api/v1/creators/dashboard/checklist` — 🔑 **Bearer**

Returns the **6-item creator onboarding checklist** with `completed` flags computed live across `User`, `BioPage`, `BioLink`, `CreatorProfile`, and `SocialAccount`. The set of items is static today — keys are stable, future items would be additions, never renames.



<Callout type="info">
  The checklist's `key` is the stable identifier — render UI / icons / deep-links by `key`, not by array index. The `label` is server-rendered English; localize on the client by mapping `key` to your i18n strings if needed.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<ChecklistResponseDto>` [#200-ok--apiresponseofchecklistresponsedto]

```json
{
  "success": true,
  "data": {
    "items": [
      { "key": "avatar",    "completed": true,  "label": "Upload profile photo" },
      { "key": "bio",       "completed": true,  "label": "Write your bio" },
      { "key": "links",     "completed": false, "label": "Add at least one link" },
      { "key": "dm_config", "completed": true,  "label": "Configure DM pricing" },
      { "key": "kyc",       "completed": false, "label": "Complete identity verification" },
      { "key": "social",    "completed": true,  "label": "Connect a social account" }
    ],
    "completedCount": 4,
    "totalCount": 6
  }
}
```

### Items [#items]

| `key`       | Completion rule                              | Source           |
| ----------- | -------------------------------------------- | ---------------- |
| `avatar`    | `User.avatarUrl IS NOT NULL`                 | `User`           |
| `bio`       | `BioPage.bio` non-empty after `.trim()`      | `BioPage`        |
| `links`     | `count(BioLink where bioPage.creatorId) > 0` | `BioLink`        |
| `dm_config` | `CreatorProfile.dmActive === true`           | `CreatorProfile` |
| `kyc`       | `CreatorProfile.kycStatus === 'APPROVED'`    | `CreatorProfile` |
| `social`    | `count(SocialAccount where userId) > 0`      | `SocialAccount`  |

### Top-level fields [#top-level-fields]

| Field            | Type   | Notes                                                               |
| ---------------- | ------ | ------------------------------------------------------------------- |
| `items`          | array  | 6 items in the order shown above (stable)                           |
| `completedCount` | number | Number of items with `completed: true`                              |
| `totalCount`     | number | Always `6` today — render progress as `completedCount / totalCount` |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`            | Reason                                                                  |
| ----- | ----------------------------- | ----------------------------------------------------------------------- |
| `401` | (guard)                       | Missing / invalid bearer token                                          |
| `404` | `creator.checklist.not_found` | No `CreatorProfile` for this user — call `POST /creators/upgrade` first |

## Side effects [#side-effects]

1. Lookup `CreatorProfile` (`id`, `dmActive`, `kycStatus`); throw `not_found` if missing.
2. **In parallel** (`Promise.all`): read `User.avatarUrl`, read `BioPage.bio`, count `BioLink`, count `SocialAccount`.
3. Build the items array using the rules above.
4. `completedCount = items.filter(i => i.completed).length`.
5. Return `{ items, completedCount, totalCount: items.length }`. No mutations.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/creators/dashboard/checklist \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type ChecklistKey = 'avatar' | 'bio' | 'links' | 'dm_config' | 'kyc' | 'social';

    type ChecklistItem = {
      key: ChecklistKey;
      completed: boolean;
      label: string;
    };

    type Checklist = {
      items: ChecklistItem[];
      completedCount: number;
      totalCount: number;
    };

    async function getChecklist(accessToken: string): Promise<Checklist> {
      const res = await fetch('https://api.bio.re/api/v1/creators/dashboard/checklist', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Checklist fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const creatorKeys = {
      checklist: () => ['creators', 'dashboard', 'checklist'] as const,
    };

    export function useChecklist() {
      return useQuery({
        queryKey: creatorKeys.checklist(),
        queryFn: async () => {
          const res = await fetch('/api/v1/creators/dashboard/checklist');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Checklist fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as Checklist;
        },
        staleTime: 30_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/dashboard/checklist', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                                                              |
| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`              | `103–110` (`getChecklist`)                                                                                         |
| DTO (response) | `apps/api-core/src/modules/creator/dto/creator-client-response.dto.ts` | `408–417` (`ChecklistResponseDto`), `397–406` (nested `ChecklistItemDto`)                                          |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`                 | `936–976` (`getChecklist`)                                                                                         |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                                 | `CreatorProfile.dmActive`, `CreatorProfile.kycStatus`, `User.avatarUrl`, `BioPage.bio`, `BioLink`, `SocialAccount` |


# Get Creator Dashboard (/docs/creator/dashboard)



`GET /api/v1/creators/dashboard` — 🔑 **Bearer**

Returns the full creator dashboard payload — level + commission rate, lifetime totals, wallet balance + frozen flag, pending payouts count, DM config, response rate (computed from message statuses), next-level progress + remaining requirements, and `hasSocialAccounts` flag for the onboarding nudge. Heavy aggregate read — call once on dashboard mount and cache.



<Callout type="info">
  **`commissionRate` is admin-managed.** Per-level commission rates are stored in `ConfigService` keys (`creator.commission_bronze`, `creator.commission_silver`, etc) with a 20% default. The response includes the **rate that applies to this creator's current level** — not a list of all rates.
</Callout>

<Callout type="warn">
  **Response rate semantics.** `responseRate = round((COMPLETED + REPLIED) / (COMPLETED + REPLIED + REJECTED + EXPIRED) * 100)`. Pending / in-flight messages are not counted because the creator hasn't yet had a chance to act. Returns `100` when there are zero resolvable messages (so a brand-new creator doesn't start at 0%).
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<DashboardResponseDto>` [#200-ok--apiresponseofdashboardresponsedto]

```json
{
  "success": true,
  "data": {
    "level": "BRONZE",
    "commissionRate": 20,
    "totalMessages": 47,
    "totalEarnings": "1250.00",
    "walletBalance": "350.00",
    "walletFrozen": false,
    "pendingPayouts": 1,
    "dmActive": true,
    "dmType": "SINGLE_PAY",
    "dmPrice": "5.00",
    "responseRate": 95,
    "nextLevel": "SILVER",
    "nextLevelProgress": 47,
    "nextLevelRequirements": {
      "messages": { "current": 47, "required": 100 },
      "earnings": { "current": 1250, "required": 5000 }
    },
    "hasSocialAccounts": true,
    "avatarUrl": "https://cdn.bio.re/avatars/abc.webp"
  }
}
```

### Fields [#fields]

| Field                             | Type                                    | Notes                                                                                                           |
| --------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `level`                           | enum                                    | `BRONZE` / `SILVER` / `GOLD` / `PLATINUM`                                                                       |
| `commissionRate`                  | number                                  | Percentage (e.g. `20` = 20%). Pulled from `creator.commission_<level>` admin config; defaults to `20` if unset. |
| `totalMessages`                   | number                                  | Lifetime message count (`CreatorProfile.totalMessages`)                                                         |
| `totalEarnings`                   | string (decimal)                        | Lifetime earnings (decimal as string for precision)                                                             |
| `walletBalance`                   | string (decimal) \| number              | From `Wallet.balance` where `type = CREATOR`; falls back to `0` if no wallet row exists                         |
| `walletFrozen`                    | boolean                                 | `Wallet.frozen` — `true` blocks payout requests                                                                 |
| `pendingPayouts`                  | string \| number                        | Count of `PayoutRequest` rows with `status = PENDING` for this creator                                          |
| `dmActive` / `dmType` / `dmPrice` | boolean / enum \| null / string \| null | Mirrors `CreatorProfile.dm*` fields                                                                             |
| `responseRate`                    | number                                  | Integer 0–100 (see Response rate callout above)                                                                 |
| `nextLevel`                       | enum \| null                            | One step above `level`; `null` when already `PLATINUM`                                                          |
| `nextLevelProgress`               | number                                  | Integer 0–100. Computed as `min(messageProgress, earningsProgress)` — both gates must be met.                   |
| `nextLevelRequirements`           | object \| null                          | `{ messages: { current, required }, earnings: { current, required } }`. `null` when `nextLevel` is null.        |
| `hasSocialAccounts`               | boolean                                 | `true` if `count(SocialAccount where userId) > 0`                                                               |
| `avatarUrl`                       | string \| null                          | Mirror of `User.avatarUrl`                                                                                      |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`            | Reason                                                                  |
| ----- | ----------------------------- | ----------------------------------------------------------------------- |
| `401` | (guard)                       | Missing / invalid bearer token                                          |
| `404` | `creator.dashboard.not_found` | No `CreatorProfile` for this user — call `POST /creators/upgrade` first |

## Side effects [#side-effects]

1. Lookup `CreatorProfile` by `userId`; throw `not_found` if missing.
2. **In parallel** (`Promise.all`): read `Wallet`, count `PayoutRequest PENDING`, read `User.avatarUrl`, count `SocialAccount`, count messages with `status IN (COMPLETED, REPLIED)` ("responded"), count messages with `status IN (COMPLETED, REPLIED, REJECTED, EXPIRED)` ("resolvable").
3. Read `creator.commission_<level>` from `ConfigService` (default 20).
4. Compute `responseRate = totalResolvable > 0 ? round(responded / totalResolvable * 100) : 100`.
5. Compute `nextLevel` + `nextLevelProgress` + `nextLevelRequirements` via `calculateLevelProgress()`:
   * Reads `creator.<nextLevel>_min_messages` + `creator.<nextLevel>_min_earnings` from `ConfigService` (with built-in defaults per level).
   * Progress = `min(messageProgress, earningsProgress)` (both gates).
6. Return assembled object. **No mutations** — pure read.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/creators/dashboard \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type CreatorLevel = 'BRONZE' | 'SILVER' | 'GOLD' | 'PLATINUM';

    type LevelRequirementDetail = {
      current: number;
      required: number;
    };

    type Dashboard = {
      level: CreatorLevel;
      commissionRate: number;
      totalMessages: number;
      totalEarnings: string;
      walletBalance: string | number;
      walletFrozen: boolean;
      pendingPayouts: string | number;
      dmActive: boolean;
      dmType: 'FREE' | 'SINGLE_PAY' | 'PER_MESSAGE' | null;
      dmPrice: string | null;
      responseRate: number;
      nextLevel: CreatorLevel | null;
      nextLevelProgress: number;
      nextLevelRequirements: { messages: LevelRequirementDetail; earnings: LevelRequirementDetail } | null;
      hasSocialAccounts: boolean;
      avatarUrl: string | null;
    };

    async function getDashboard(accessToken: string): Promise<Dashboard> {
      const res = await fetch('https://api.bio.re/api/v1/creators/dashboard', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Dashboard fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const creatorKeys = {
      dashboard: () => ['creators', 'dashboard'] as const,
    };

    export function useDashboard() {
      return useQuery({
        queryKey: creatorKeys.dashboard(),
        queryFn: async () => {
          const res = await fetch('/api/v1/creators/dashboard');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Dashboard fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as Dashboard;
        },
        staleTime: 30_000, // 30s — dashboard is action-driven
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/dashboard', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                                                                                           |
| -------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`              | `94–101` (`getDashboard`)                                                                                                                       |
| DTO (response) | `apps/api-core/src/modules/creator/dto/creator-client-response.dto.ts` | `343–391` (`DashboardResponseDto`), `321–339` (nested `LevelRequirementDetailDto`, `NextLevelRequirementsDto`)                                  |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`                 | `750–812` (`getCreatorDashboard`), `818–858` (`calculateLevelProgress`)                                                                         |
| Config keys    | `apps/api-core/src/modules/config/config.service.ts`                   | `creator.commission_<level>`, `creator.<level>_min_messages`, `creator.<level>_min_earnings` (admin-managed)                                    |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                                 | `CreatorProfile`, `Wallet`, `PayoutRequest`, `Message` (statuses `COMPLETED`/`REPLIED`/`REJECTED`/`EXPIRED`), `SocialAccount`, `User.avatarUrl` |


# Update DM Config (/docs/creator/dm-config-update)



`PATCH /api/v1/creators/:creatorId/dm-config` — 🔑 **Bearer** · Rate limit: **30 req / hour**

Atomic DM configuration write. Updates `CreatorProfile.{dmType, dmPrice, dmActive}`, syncs the active `DMPackage` row to match, and **flips the visibility of manual social bio links** on DM ON↔OFF transitions (because manual social links are forbidden while DM is active — see [`POST /creators/:creatorId/links`](/docs/creator/bio-link-add)).



<Callout type="info">
  **Price range is admin-managed.** Min / max are read from `dm.min_price` (default `1`) and `dm.max_price` (default `500`). The 5000 cap in the DTO `@Max` is a hard safety ceiling — actual enforced bounds come from ConfigService.
</Callout>

<Callout type="warn">
  **Social link side effects (transitional, not idempotent across runs):**

  * **OFF → ON**: every `BioLink` with `isSocial: true AND active: true` in the creator's bio page is flipped to `active: false` (so manual social links don't show alongside OAuth-verified ones while DM accepts paid messages).
  * **ON → OFF**: every `BioLink` with `isSocial: true AND active: false` is flipped back to `active: true`.

  These mirrors run inside the same transaction as the DM update. They do NOT discriminate "links the user themselves disabled" — if a creator manually deactivated a social link before turning DM on, it gets re-activated when DM turns off again.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param       | Type          | Validation      | Notes                                                       |
| ----------- | ------------- | --------------- | ----------------------------------------------------------- |
| `creatorId` | string (UUID) | `ParseUUIDPipe` | Must match the bearer's `CreatorProfile.id` (otherwise 403) |

### Body — `DMConfigDto` [#body--dmconfigdto]

| Field      | Type    | Required    | Validation                                                 | Notes                                                                                                                                                                           |
| ---------- | ------- | ----------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dmType`   | enum    | ✓           | `IsEnum(DmType)`                                           | One of `FREE` / `SINGLE_PAY` / `PER_MESSAGE`                                                                                                                                    |
| `dmPrice`  | number  | conditional | `IsNumber({ maxDecimalPlaces: 2 })`, `Min(0)`, `Max(5000)` | **Required** when `dmType !== 'FREE'` AND `dmActive: true`. Server enforces `dm.min_price` ≤ value ≤ `dm.max_price` (admin-managed). Stored as `null` when `dmType === 'FREE'`. |
| `dmActive` | boolean | ✓           | `IsBoolean()`                                              | Whether the creator currently accepts DMs                                                                                                                                       |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                                                                                                                                                                                                                                                                                                 |
| --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `success` | boolean | Always `true` on 200. The service computes `deactivatedSocialLinks` / `reactivatedSocialLinks` counts internally for telemetry, but **the controller does not surface them in the response** — re-fetch the creator profile via `GET /creators/profile` if you need the post-write social-link state. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`         | Reason                                                                                                                                           |
| ----- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400` | `creator.dm.price_range`   | `dmActive: true` AND `dmType !== 'FREE'` AND `dmPrice` outside `[dm.min_price, dm.max_price]` (or missing). Message includes the current bounds. |
| `400` | (DTO validation)           | Invalid `dmType` enum, `dmPrice` outside `[0, 5000]` hard ceiling, missing fields                                                                |
| `401` | (guard)                    | Missing / invalid bearer token                                                                                                                   |
| `403` | (`verifyCreatorOwnership`) | `creatorId` does not belong to the bearer's user                                                                                                 |
| `429` | (throttle)                 | Rate limit exceeded (30 req/hour)                                                                                                                |

## Side effects [#side-effects]

1. **Ownership check** — `verifyCreatorOwnership(creatorId, userId)` → 403 on mismatch.
2. **Price gate** — when `dmType !== 'FREE'` AND `dmActive: true`: read `dm.min_price` / `dm.max_price` (admin defaults 1 / 500); reject if `dmPrice` missing or outside range.
3. Read current `creator.dmActive` (for transition detection: `wasActive` vs `willBeActive`).
4. **Inside one transaction**:
   * `creatorProfile.update({ dmType, dmPrice: dmType === 'FREE' ? null : dmPrice, dmActive })`.
   * **DMPackage sync**:
     * When `dmType !== 'FREE' AND dmActive`: find the active package; same type → update price; different type → deactivate old + create new; none → create new.
     * When `FREE` or `dmActive: false`: deactivate every active package (`updateMany active=false`).
   * **Social link transition** (only fires on flip, no-op if `wasActive === willBeActive`):
     * **OFF→ON**: `bioLink.updateMany({ where: bioPageId AND isSocial AND active, data: { active: false } })`. Count → `deactivatedSocialLinks`.
     * **ON→OFF**: `bioLink.updateMany({ where: bioPageId AND isSocial AND NOT active, data: { active: true } })`. Count → `reactivatedSocialLinks`.
5. Audit log: `[dm] Config set for creator {id}: {dmType} active={dmActive} (deactivated=N, reactivated=N)`.
6. **Cache invalidation** — `invalidateBioCache(creatorId)`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X PATCH https://api.bio.re/api/v1/creators/c1a2b3c4-d5e6-7890-abcd-ef1234567890/dm-config \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "dmType": "SINGLE_PAY",
        "dmPrice": 5,
        "dmActive": true
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type SetDMConfigInput = {
      dmType: 'FREE' | 'SINGLE_PAY' | 'PER_MESSAGE';
      dmPrice?: number; // required when dmType !== 'FREE' && dmActive
      dmActive: boolean;
    };

    async function setDMConfig(accessToken: string, creatorId: string, input: SetDMConfigInput): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/creators/${creatorId}/dm-config`, {
        method: 'PATCH',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Update DM config failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useSetDMConfig(creatorId: string) {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (input: SetDMConfigInput) => {
          const res = await fetch(`/api/v1/creators/${creatorId}/dm-config`, {
            method: 'PATCH',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Update DM config failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['creators', creatorId, 'dm-config'] });
          // Bio links may have been toggled — refetch the editor view too
          qc.invalidateQueries({ queryKey: ['creators', creatorId, 'bio'] });
          qc.invalidateQueries({ queryKey: ['creators', 'profile'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/{creatorId}/dm-config', method: 'patch' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                      | Lines                                                                    |
| -------------- | --------------------------------------------------------- | ------------------------------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts` | `213–224` (`setDMConfig`)                                                |
| DTO (request)  | `apps/api-core/src/modules/creator/dto/creator.dto.ts`    | `117–126` (`DMConfigDto`)                                                |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts`     | `SuccessOnlyResponseDto`                                                 |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`    | `489–563` (`setDMConfig`)                                                |
| Config keys    | `apps/api-core/src/modules/config/config.service.ts`      | `dm.min_price` (default 1), `dm.max_price` (default 500) — admin-managed |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                    | `CreatorProfile.dm*`, `DMPackage`, `BioLink.isSocial`, `BioLink.active`  |


# Get DM Config (/docs/creator/dm-config)



`GET /api/v1/creators/:creatorId/dm-config` — 🔑 **Bearer**

Returns the calling creator's DM configuration: pricing type (`FREE` / `SINGLE_PAY` / `PER_MESSAGE`), the price (decimal, null when `FREE`), and the active flag. Ownership-checked — `creatorId` must match the bearer's `CreatorProfile.id`.



<Callout type="info">
  For a public read of just the DM-related fields (along with `dmActive` already adjusted for vacation mode), look at the `dmType` / `dmPrice` / `dmActive` fields on `GET /bio/:username`. This endpoint is the editor-side raw read.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param       | Type          | Validation      | Notes                                                       |
| ----------- | ------------- | --------------- | ----------------------------------------------------------- |
| `creatorId` | string (UUID) | `ParseUUIDPipe` | Must match the bearer's `CreatorProfile.id` (otherwise 403) |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<DMConfigResponseDto>` [#200-ok--apiresponseofdmconfigresponsedto]

```json
{
  "success": true,
  "data": {
    "dmType": "SINGLE_PAY",
    "dmPrice": "5.00",
    "dmActive": true
  }
}
```

| Field      | Type           | Notes                                                                                                                                                                                        |
| ---------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dmType`   | enum \| null   | `FREE` / `SINGLE_PAY` / `PER_MESSAGE`, or `null` if never configured                                                                                                                         |
| `dmPrice`  | string \| null | Decimal as string for precision; `null` when `dmType === 'FREE'` or unconfigured                                                                                                             |
| `dmActive` | boolean        | Raw value from `CreatorProfile.dmActive`. The public-render `dmActive` (in `GET /bio/:username`) is computed as `dmActive && !vacationMode` — this endpoint returns the unadjusted raw flag. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`         | Reason                                           |
| ----- | -------------------------- | ------------------------------------------------ |
| `400` | (validation)               | `creatorId` not a valid UUID                     |
| `401` | (guard)                    | Missing / invalid bearer token                   |
| `403` | (`verifyCreatorOwnership`) | `creatorId` does not belong to the bearer's user |
| `404` | `creator.dm.not_found`     | `CreatorProfile` row missing                     |

## Side effects [#side-effects]

1. **Ownership check** — `verifyCreatorOwnership(creatorId, userId)` → 403 on mismatch.
2. `prisma.creatorProfile.findUnique({ where: { id: creatorId }, select: { dmType, dmPrice, dmActive } })`.
3. Throw `not_found` if missing.
4. Return the row. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/creators/c1a2b3c4-d5e6-7890-abcd-ef1234567890/dm-config \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type DMConfig = {
      dmType: 'FREE' | 'SINGLE_PAY' | 'PER_MESSAGE' | null;
      dmPrice: string | null;
      dmActive: boolean;
    };

    async function getDMConfig(accessToken: string, creatorId: string): Promise<DMConfig> {
      const res = await fetch(`https://api.bio.re/api/v1/creators/${creatorId}/dm-config`, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'DM config fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const creatorKeys = {
      dmConfig: (creatorId: string) => ['creators', creatorId, 'dm-config'] as const,
    };

    export function useDMConfig(creatorId: string) {
      return useQuery({
        queryKey: creatorKeys.dmConfig(creatorId),
        queryFn: async () => {
          const res = await fetch(`/api/v1/creators/${creatorId}/dm-config`);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'DM config fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as DMConfig;
        },
        enabled: Boolean(creatorId),
        staleTime: 30_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/{creatorId}/dm-config', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                        |
| -------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`              | `203–211` (`getDMConfig`)                                                    |
| DTO (response) | `apps/api-core/src/modules/creator/dto/creator-client-response.dto.ts` | `460–469` (`DMConfigResponseDto`)                                            |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`                 | `565–572` (`getDMConfig`)                                                    |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                                 | `CreatorProfile.dmType`, `CreatorProfile.dmPrice`, `CreatorProfile.dmActive` |


# Start KYC Verification (/docs/creator/kyc-start)



`POST /api/v1/creators/kyc/start` — 🔑 **Bearer** · Rate limit: **5 req / hour**

Starts an identity verification session with the **active KYC provider** (admin-managed via `external.kyc.active_provider`; failover handled server-side). Returns a hosted-flow `redirectUrl` plus opaque `sessionId` and `provider` identifier — the client opens the URL, the user completes verification on the provider's site, and the provider notifies us via webhook.



<Callout type="warn">
  **Admin kill switch.** When the `KYC` kill switch is active (admin-managed), every call returns `503 features.kyc_disabled` regardless of state. Surface a "verification temporarily unavailable" UI when you see that response.
</Callout>

<Callout type="info">
  The `provider` field in the response is the **active provider's identifier string** (e.g. `"<provider-id>"`). It's opaque to clients — don't branch on its value, don't display it. It exists for support / debugging trails. Vendor identity stays in admin; this endpoint guarantees a session via whichever provider is active.
</Callout>

## Request [#request]

No body, no params. Identity comes from the bearer token.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `201 Created` — `ApiResponseOf<KycStartResponseDto>` [#201-created--apiresponseofkycstartresponsedto]

```json
{
  "success": true,
  "data": {
    "redirectUrl": "https://provider.example.com/verify?session=...",
    "sessionId": "sess_...",
    "provider": "<provider-id>"
  }
}
```

| Field         | Type   | Notes                                                                                                                    |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| `redirectUrl` | string | Open this URL in a popup or full-page redirect. The user completes ID upload + biometrics on the provider's hosted flow. |
| `sessionId`   | string | The provider's session id — useful only for support tickets.                                                             |
| `provider`    | string | Identifier of the active KYC provider (admin-managed). Treat as opaque.                                                  |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`        | Reason                                                                  |
| ----- | ------------------------- | ----------------------------------------------------------------------- |
| `400` | (KYC service)             | Already approved or in-progress (provider-specific message)             |
| `401` | (guard)                   | Missing / invalid bearer token                                          |
| `404` | `error.creator.not_found` | No `CreatorProfile` for this user — call `POST /creators/upgrade` first |
| `429` | (throttle)                | Rate limit exceeded (5 req/hour)                                        |
| `503` | `features.kyc_disabled`   | Admin kill switch `KYC` is active                                       |

## Side effects [#side-effects]

1. **Kill switch check** (`@RequireKillSwitch('KYC')`) — if active, throw `503 features.kyc_disabled` before reaching the service.
2. Lookup `CreatorProfile` by `userId`; throw `not_found` if missing.
3. Delegate to `creatorLevelService.startKYC(creator.id)` → `kycService.startVerification(creator.id)`:
   * Resolve the active KYC provider from admin config.
   * Create a verification session via the provider's API (server-to-server).
   * Persist `kycProvider` + `kycProviderId` + flip `kycStatus` to `PENDING` on `CreatorProfile`.
   * Return `{ redirectUrl, sessionId, provider }`.
4. The user completes verification out-of-band; the provider's webhook (handled by `webhooks/kyc/*`, internal scope) flips `kycStatus` to `APPROVED` / `REJECTED` and sets `kycCompletedAt`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/creators/kyc/start \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type KycStart = {
      redirectUrl: string;
      sessionId: string;
      provider: string;
    };

    async function startKyc(accessToken: string): Promise<KycStart> {
      const res = await fetch('https://api.bio.re/api/v1/creators/kyc/start', {
        method: 'POST',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'KYC start failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }

    // Usage: open redirectUrl in a popup or full-page redirect
    function launchKyc(redirectUrl: string) {
      window.location.assign(redirectUrl);
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useStartKyc() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/creators/kyc/start', { method: 'POST' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'KYC start failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as KycStart;
        },
        onSuccess: () => {
          // Status will flip to PENDING server-side
          qc.invalidateQueries({ queryKey: ['creators', 'kyc', 'status'] });
          qc.invalidateQueries({ queryKey: ['creators', 'profile'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/kyc/start', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                                                       |
| -------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`              | `277–291` (`startKyc`)                                                                                      |
| DTO (response) | `apps/api-core/src/modules/creator/dto/creator-client-response.dto.ts` | `547–556` (`KycStartResponseDto`)                                                                           |
| Service        | `apps/api-core/src/modules/creator/creator-level.service.ts`           | `150–152` (`startKYC` — delegates to KycService)                                                            |
| KYC service    | `apps/api-core/src/modules/creator/kyc/kyc.service.ts`                 | `startVerification()` (provider abstraction)                                                                |
| Kill switch    | `apps/api-core/src/common/guards/kill-switch.guard.ts`                 | `RequireKillSwitch('KYC')`                                                                                  |
| Config         | (admin-managed)                                                        | `external.kyc.active_provider` ConfigService key                                                            |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                                 | `CreatorProfile.kycStatus` (`enum KycStatus`), `CreatorProfile.kycProvider`, `CreatorProfile.kycProviderId` |


# Get KYC Status (/docs/creator/kyc-status)



`GET /api/v1/creators/kyc/status` — 🔑 **Bearer**

Returns the calling creator's current KYC state, the active provider identifier (opaque), the provider-side session id (for support trails), and the completion timestamp.



<Callout type="info">
  **Status lifecycle.** Created accounts start at `NOT_STARTED`. After `POST /creators/kyc/start`, the status flips to `PENDING` (or sometimes provider-side `IN_REVIEW` mapped to `PENDING`). The provider's webhook (handled internally) then flips it to `APPROVED` / `REJECTED` / `EXPIRED`. There is no client-driven path back to `NOT_STARTED` once started — re-running `POST /creators/kyc/start` after an expired or rejected session will start a new attempt with a fresh `kycProviderId`.
</Callout>

## Request [#request]

No body, no params. Identity comes from the bearer token.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<CreatorKycStatusDto>` [#200-ok--apiresponseofcreatorkycstatusdto]

```json
{
  "success": true,
  "data": {
    "status": "APPROVED",
    "provider": "<provider-id>",
    "providerId": "...",
    "completedAt": "2026-04-29T20:00:00.000Z"
  }
}
```

| Field         | Type                      | Notes                                                                                                                                                                           |
| ------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`      | enum                      | One of `NOT_STARTED` / `PENDING` / `APPROVED` / `REJECTED` / `EXPIRED`                                                                                                          |
| `provider`    | string \| null            | Active KYC provider identifier (admin-managed via `external.kyc.active_provider`). Treat as **opaque** — don't branch on it, don't display it. `null` until first `/kyc/start`. |
| `providerId`  | string \| null            | The provider's session id. `null` until first `/kyc/start`.                                                                                                                     |
| `completedAt` | string (ISO 8601) \| null | When status flipped to `APPROVED` / `REJECTED` / `EXPIRED`. `null` while `NOT_STARTED` / `PENDING`.                                                                             |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`        | Reason                                                                  |
| ----- | ------------------------- | ----------------------------------------------------------------------- |
| `401` | (guard)                   | Missing / invalid bearer token                                          |
| `404` | `error.creator.not_found` | No `CreatorProfile` for this user — call `POST /creators/upgrade` first |

## Side effects [#side-effects]

1. Lookup `CreatorProfile` by `userId`; throw `not_found` if missing.
2. Delegate to `creatorLevelService.getKYCStatus(creator.id)` → `kycService.getStatus(creator.id)`:
   * Read `CreatorProfile.kycStatus` + `kycProvider` + `kycProviderId` + `kycCompletedAt`.
   * Return as-is. **No mutations** — provider state changes happen via webhook, not on read.

## Polling guidance [#polling-guidance]

* Poll while `status === 'PENDING'` (every 5–10s while a verification dialog is open).
* Stop polling once `status` is `APPROVED` / `REJECTED` / `EXPIRED`.
* Don't poll forever — if a session sits `PENDING` for hours, surface a "still pending — refresh later" message rather than a tight loop.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/creators/kyc/status \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type KycStatus = {
      status: 'NOT_STARTED' | 'PENDING' | 'APPROVED' | 'REJECTED' | 'EXPIRED';
      provider: string | null;
      providerId: string | null;
      completedAt: string | null;
    };

    async function getKycStatus(accessToken: string): Promise<KycStatus> {
      const res = await fetch('https://api.bio.re/api/v1/creators/kyc/status', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'KYC status fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const creatorKeys = {
      kycStatus: () => ['creators', 'kyc', 'status'] as const,
    };

    export function useKycStatus() {
      return useQuery({
        queryKey: creatorKeys.kycStatus(),
        queryFn: async () => {
          const res = await fetch('/api/v1/creators/kyc/status');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'KYC status fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as KycStatus;
        },
        // Poll while PENDING, stop once terminal
        refetchInterval: (query) => {
          const data = query.state.data;
          if (!data) return 5_000;
          return data.status === 'PENDING' ? 5_000 : false;
        },
        staleTime: 30_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/kyc/status', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source                             | Path                                                                       | Lines                                                                                                                     |
| ---------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Controller                         | `apps/api-core/src/modules/creator/creator.controller.ts`                  | `293–303` (`getKycStatus`)                                                                                                |
| DTO (response)                     | `apps/api-core/src/modules/creator/dto/creator-kyc-status-response.dto.ts` | `7–19` (`CreatorKycStatusDto`)                                                                                            |
| Service                            | `apps/api-core/src/modules/creator/creator-level.service.ts`               | `157–159` (`getKYCStatus` — delegates to KycService)                                                                      |
| KYC service                        | `apps/api-core/src/modules/creator/kyc/kyc.service.ts`                     | `getStatus()`                                                                                                             |
| Webhook (status flips happen here) | `apps/api-core/src/modules/creator/kyc/kyc-webhook.controller.ts`          | (internal scope, not in this portal)                                                                                      |
| Config                             | (admin-managed)                                                            | `external.kyc.active_provider` ConfigService key                                                                          |
| Prisma model                       | `packages/prisma/prisma/schema.prisma`                                     | `CreatorProfile.kycStatus`, `CreatorProfile.kycProvider`, `CreatorProfile.kycProviderId`, `CreatorProfile.kycCompletedAt` |


# Get Payout Settings (/docs/creator/payout-settings)



`GET /api/v1/creators/payout-settings` — 🔑 **Bearer**

Returns the current creator's payout configuration in a single call: bank details (with `verified` flag), Stripe Connect snapshot, the preferred method enum, and a derived `availableMethods` bitmap (`STRIPE_CONNECT` true when Stripe is connected AND `payoutsEnabled`; `BANK_TRANSFER` true when the bank account is admin-verified).



<Callout type="info">
  The `availableMethods` bitmap is the **source of truth** for which payout buttons to render. `preferredPayoutMethod` is just the user's stated preference — render the actual options off `availableMethods` so disabled methods don't ghost the UI.
</Callout>

## Request [#request]

No body, no params. Identity comes from the bearer token.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<PayoutSettingsResponseDto>` [#200-ok--apiresponseofpayoutsettingsresponsedto]

```json
{
  "success": true,
  "data": {
    "bankDetails": {
      "iban": "TR000000000000000000000000",
      "bankName": "Example Bank",
      "accountHolderName": "John Doe",
      "swiftCode": "EXAMPTRIS",
      "bankCountry": "TR",
      "verified": false,
      "verifiedAt": null
    },
    "stripeConnect": {
      "connected": true,
      "payoutsEnabled": true
    },
    "preferredPayoutMethod": "STRIPE_CONNECT",
    "availableMethods": {
      "STRIPE_CONNECT": true,
      "BANK_TRANSFER": false
    }
  }
}
```

### Top-level fields [#top-level-fields]

| Field                                                                                   | Type                      | Notes                                                                                                                                                           |
| --------------------------------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bankDetails`                                                                           | object                    | All bank-related fields plus `verified` flag and `verifiedAt` timestamp                                                                                         |
| `bankDetails.iban` / `.bankName` / `.accountHolderName` / `.swiftCode` / `.bankCountry` | string \| null            | Mirror of `CreatorProfile` columns                                                                                                                              |
| `bankDetails.verified`                                                                  | boolean                   | True when admin has verified the bank record. **Resets to `false` on any bank field change** (see [`PATCH /creators/bank-details`](/docs/creator/bank-details)) |
| `bankDetails.verifiedAt`                                                                | string (ISO 8601) \| null | When admin verified                                                                                                                                             |
| `stripeConnect`                                                                         | object                    | Snapshot of stored Stripe Connect state (live state from the payment provider is on `/creators/stripe-connect/status`)                                          |
| `stripeConnect.connected`                                                               | boolean                   | `true` when `CreatorProfile.stripeAccountId` is non-null                                                                                                        |
| `stripeConnect.payoutsEnabled`                                                          | boolean                   | Mirror of `CreatorProfile.stripePayoutsEnabled`                                                                                                                 |
| `preferredPayoutMethod`                                                                 | enum \| null              | `STRIPE_CONNECT` / `BANK_TRANSFER`, or `null`                                                                                                                   |
| `availableMethods.STRIPE_CONNECT`                                                       | boolean                   | Computed: `stripeAccountId != null && stripePayoutsEnabled`                                                                                                     |
| `availableMethods.BANK_TRANSFER`                                                        | boolean                   | Computed: `bankAccountVerified === true`                                                                                                                        |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`         | Reason                                                                  |
| ----- | -------------------------- | ----------------------------------------------------------------------- |
| `401` | (guard)                    | Missing / invalid bearer token                                          |
| `404` | `creator.payout.not_found` | No `CreatorProfile` for this user — call `POST /creators/upgrade` first |

## Side effects [#side-effects]

1. `prisma.creatorProfile.findUnique({ where: { userId }, select: { iban, bankName, accountHolderName, swiftCode, bankCountry, bankAccountVerified, bankVerifiedAt, preferredPayoutMethod, stripeAccountId, stripePayoutsEnabled } })`.
2. Throw `not_found` if missing.
3. Compute `availableMethods` bitmap from the loaded fields.
4. Return assembled object. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/creators/payout-settings \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type PayoutMethod = 'STRIPE_CONNECT' | 'BANK_TRANSFER';

    type PayoutSettings = {
      bankDetails: {
        iban: string | null;
        bankName: string | null;
        accountHolderName: string | null;
        swiftCode: string | null;
        bankCountry: string | null;
        verified: boolean;
        verifiedAt: string | null;
      };
      stripeConnect: {
        connected: boolean;
        payoutsEnabled: boolean;
      };
      preferredPayoutMethod: PayoutMethod | null;
      availableMethods: {
        STRIPE_CONNECT: boolean;
        BANK_TRANSFER: boolean;
      };
    };

    async function getPayoutSettings(accessToken: string): Promise<PayoutSettings> {
      const res = await fetch('https://api.bio.re/api/v1/creators/payout-settings', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Payout settings fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const creatorKeys = {
      payoutSettings: () => ['creators', 'payout-settings'] as const,
    };

    export function usePayoutSettings() {
      return useQuery({
        queryKey: creatorKeys.payoutSettings(),
        queryFn: async () => {
          const res = await fetch('/api/v1/creators/payout-settings');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Payout settings fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as PayoutSettings;
        },
        staleTime: 30_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/payout-settings', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                    |
| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`              | `255–262` (`getPayoutSettings`)                                          |
| DTO (response) | `apps/api-core/src/modules/creator/dto/creator-client-response.dto.ts` | `529–541` (`PayoutSettingsResponseDto`), `490–527` (nested DTOs)         |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`                 | `864–902` (`getPayoutSettings`)                                          |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                                 | `CreatorProfile` (bank fields + Stripe fields + `preferredPayoutMethod`) |


# Get Creator Profile (/docs/creator/profile)



`GET /api/v1/creators/profile` — 🔑 **Bearer**

Returns the rich `CreatorProfile` row for the user resolved from the bearer token, joined with their `BioPage` (including ordered links and template), all `CreatorCategory` rows, and all `active = true` `DmPackage` rows. Heavy read — call once on dashboard load and cache.



<Callout type="info">
  This is the **canonical creator dashboard payload**. For a lighter read of a specific slice (e.g. just the bio page or just payout settings), see `GET /creators/:creatorId/bio` and `GET /creators/payout-settings` respectively.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<CreatorProfileResponseDto>` [#200-ok--apiresponseofcreatorprofileresponsedto]

```json
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userId": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
    "level": "BRONZE",
    "kycStatus": "NOT_STARTED",
    "kycProvider": null,
    "kycProviderId": null,
    "kycCompletedAt": null,
    "dmType": "FREE",
    "dmPrice": null,
    "dmActive": true,
    "creatorStatus": "ACTIVE",
    "vacationMode": false,
    "vacationStart": null,
    "vacationEnd": null,
    "totalEarnings": "0.00",
    "totalMessages": 0,
    "totalFollowers": 0,
    "avgRating": null,
    "ratingCount": 0,
    "stripeAccountId": null,
    "stripeAccountStatus": "NOT_STARTED",
    "stripeChargesEnabled": false,
    "stripePayoutsEnabled": false,
    "iban": null,
    "bankName": null,
    "accountHolderName": null,
    "swiftCode": null,
    "bankCountry": null,
    "bankAccountVerified": false,
    "bankVerifiedAt": null,
    "preferredPayoutMethod": null,
    "autoPayoutEnabled": false,
    "createdAt": "2026-04-29T20:00:00.000Z",
    "updatedAt": "2026-04-29T20:00:00.000Z",
    "deletedAt": null,
    "bioPage": { /* BioPageResponseDto with .links and .template */ },
    "categories": [],
    "dmPackages": []
  }
}
```

### Top-level fields [#top-level-fields]

| Field                                                                                                                                                              | Type                                      | Notes                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------- |
| `id`                                                                                                                                                               | string (UUID)                             | `CreatorProfile.id`                                                                           |
| `userId`                                                                                                                                                           | string (UUID)                             | Owning `User.id`                                                                              |
| `level`                                                                                                                                                            | enum                                      | `BRONZE` / `SILVER` / `GOLD` / `PLATINUM`                                                     |
| `kycStatus`                                                                                                                                                        | enum                                      | `NOT_STARTED` / `PENDING` / `APPROVED` / `REJECTED` / `EXPIRED`                               |
| `kycProvider` / `kycProviderId` / `kycCompletedAt`                                                                                                                 | string \| null                            | KYC bookkeeping (vendor identity hidden — admin-managed via `external.kyc.active_provider`)   |
| `dmType`                                                                                                                                                           | enum \| null                              | `FREE` / `SINGLE_PAY` / `PER_MESSAGE`                                                         |
| `dmPrice`                                                                                                                                                          | string (decimal) \| null                  | Decimal as string to preserve precision                                                       |
| `dmActive`                                                                                                                                                         | boolean                                   | True if creator currently accepts DMs                                                         |
| `creatorStatus`                                                                                                                                                    | enum                                      | `ACTIVE` / `VACATION` / `SUSPENDED` / `BANNED` / `DEACTIVATED`                                |
| `vacationMode` / `vacationStart` / `vacationEnd`                                                                                                                   | boolean / string \| null                  | Vacation block — see `/creators/:creatorId/vacation`                                          |
| `totalEarnings`                                                                                                                                                    | string (decimal)                          | Lifetime payouts (decimal as string)                                                          |
| `totalMessages` / `totalFollowers`                                                                                                                                 | number                                    | Counters                                                                                      |
| `avgRating` / `ratingCount`                                                                                                                                        | string \| null / number                   | Aggregate rating                                                                              |
| `stripeAccountId` / `stripeAccountStatus` / `stripeChargesEnabled` / `stripePayoutsEnabled`                                                                        | string \| null / enum / boolean / boolean | Stripe Connect snapshot (live status from Stripe API is on `/creators/stripe-connect/status`) |
| `iban` / `bankName` / `accountHolderName` / `swiftCode` / `bankCountry` / `bankAccountVerified` / `bankVerifiedAt` / `preferredPayoutMethod` / `autoPayoutEnabled` | various                                   | Bank transfer details — managed via `PATCH /creators/bank-details`                            |
| `createdAt` / `updatedAt` / `deletedAt`                                                                                                                            | timestamp / timestamp / timestamp \| null | Lifecycle timestamps                                                                          |

### Joined fields [#joined-fields]

| Field        | Type                         | Notes                                                                                                 |
| ------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `bioPage`    | `BioPageResponseDto` \| null | Includes `links` (ordered by `sortOrder asc`) and `template`. See [Bio Page](/docs/creator/bio-page). |
| `categories` | array                        | All `CreatorCategory` rows linked to this creator                                                     |
| `dmPackages` | array                        | Only rows where `active = true`                                                                       |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`          | Reason                                                                  |
| ----- | --------------------------- | ----------------------------------------------------------------------- |
| `401` | (guard)                     | Missing / invalid bearer token                                          |
| `404` | `creator.profile.not_found` | No `CreatorProfile` for this user — call `POST /creators/upgrade` first |

## Side effects [#side-effects]

1. `prisma.creatorProfile.findUnique({ where: { userId }, include: { bioPage: { include: { links: orderBy sortOrder asc, template } }, categories: true, dmPackages: where active=true } })`.
2. Throw `not_found` if missing.
3. Return the row. No mutations.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/creators/profile \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function getCreatorProfile(accessToken: string): Promise<unknown> {
      const res = await fetch('https://api.bio.re/api/v1/creators/profile', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Profile fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data; // CreatorProfileResponseDto — see Response section above for shape
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const creatorKeys = {
      profile: () => ['creators', 'profile'] as const,
    };

    export function useCreatorProfile() {
      return useQuery({
        queryKey: creatorKeys.profile(),
        queryFn: async () => {
          const res = await fetch('/api/v1/creators/profile');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Profile fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data;
        },
        staleTime: 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/profile', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                                                                                                                                 |
| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`              | `52–59` (`getProfile`)                                                                                                                                                                |
| DTO (response) | `apps/api-core/src/modules/creator/dto/creator-client-response.dto.ts` | `183–297` (`CreatorProfileResponseDto`), `105–180` (`BioPageResponseDto`)                                                                                                             |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`                 | `185–196` (`getProfile`)                                                                                                                                                              |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                                 | `CreatorProfile`, `BioPage`, `BioLink`, `BioTemplate`, `CreatorCategory`, `DmPackage`, enums `CreatorLevel`/`KycStatus`/`DmType`/`CreatorStatus`/`StripeAccountStatus`/`PayoutMethod` |


# Connect Social Account (/docs/creator/social-connect)



`POST /api/v1/creators/social/connect` — 🔑 **Bearer** · Rate limit: **30 req / hour**

Verifies the creator actually owns the social account they're connecting by exchanging the OAuth `code` (and PKCE `codeVerifier` for X/Twitter) for the platform's identity. On success, persists the link in `SocialAccount` (with stored OAuth tokens for future platform calls), creates an initial `SocialMetrics` row, and recomputes `CreatorProfile.totalFollowers` across all linked accounts.



<Callout type="info">
  The `code` and `redirectUri` come from the platform's OAuth callback — your frontend / mobile redirects the user to the platform's auth screen, the platform redirects back with `?code=...&#x60;, and you pass that here. **`codeVerifier` is required for X/Twitter** (PKCE flow) — generate it client-side, store in session storage, send the `code_challenge` derived from it on the initial auth request, and submit the verifier here.
</Callout>

<Callout type="warn">
  **One social account per `(platform, platformUserId)` pair.** If the same social account is already linked to a different bio.re creator, the call fails with `409 account_linked_elsewhere` — not silently overwritten.
</Callout>

## Request [#request]

### Body — `ConnectSocialDto` [#body--connectsocialdto]

| Field          | Type   | Required | Validation   | Notes                                                                                                         |
| -------------- | ------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------- |
| `platform`     | string | ✓        | `IsString()` | Platform identifier (e.g. `instagram`, `x`, `youtube`, `tiktok`) — server uses this to pick the OAuth handler |
| `code`         | string | ✓        | `IsString()` | OAuth authorization code from the platform's callback                                                         |
| `redirectUri`  | string | ✓        | `IsString()` | The same redirect URI used in the auth request — platforms re-validate it                                     |
| `codeVerifier` | string | optional | `IsString()` | **Required for X/Twitter** (PKCE). Other platforms ignore it.                                                 |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `201 Created` — `SuccessOnlyResponseDto` [#201-created--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                                                                                                   |
| --------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `success` | boolean | Always `true` on 201. Read the connected list back via `GET /creators/social` to render the updated UI. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                        | Reason                                                                                          |
| ----- | ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `400` | `creator.social.verification_failed`      | OAuth verification failed (bad `code`, expired, redirect mismatch, missing PKCE verifier for X) |
| `400` | (DTO validation)                          | Missing required fields                                                                         |
| `401` | (guard)                                   | Missing / invalid bearer token                                                                  |
| `409` | `creator.social.already_connected`        | The same `(platform, platformUserId)` is already linked to **this** creator                     |
| `409` | `creator.social.account_linked_elsewhere` | The same `(platform, platformUserId)` is linked to a **different** creator                      |
| `429` | (throttle)                                | Rate limit exceeded (30 req/hour)                                                               |

## Side effects [#side-effects]

1. Call the social verification handler for `platform` with `(code, redirectUri, codeVerifier)`. This is a server-to-platform OAuth token exchange + identity probe.
2. If `verified === false` or no `platformUserId` returned → `verification_failed`.
3. Lookup `SocialAccount` by `(platform, platformUserId)`. If found and same user → `already_connected`. If found and different user → `account_linked_elsewhere`.
4. **Inside one transaction**:
   * `SocialAccount.create({ id, userId, platform, platformUserId, platformUsername, verified: true, connectedAt: now(), accessToken?, refreshToken?, tokenExpiresAt? })` — OAuth tokens stored when the platform returned them.
   * `SocialMetrics.create({ id, socialAccountId, followerCount, lastSyncedAt: now() })` — initial follower count from the verification probe.
   * Sum every `SocialMetrics.followerCount` row for this user → `CreatorProfile.totalFollowers`.
5. Audit log: `[social] Connected {platform} for user {userId} (followers: <count>)`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/creators/social/connect \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "platform": "instagram",
        "code": "AQBx8...",
        "redirectUri": "https://bio.re/auth/callback/instagram"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type ConnectSocialInput = {
      platform: string;
      code: string;
      redirectUri: string;
      codeVerifier?: string; // required for X/Twitter (PKCE)
    };

    async function connectSocial(accessToken: string, input: ConnectSocialInput): Promise<void> {
      const res = await fetch('https://api.bio.re/api/v1/creators/social/connect', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Social connect failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useConnectSocial() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (input: ConnectSocialInput) => {
          const res = await fetch('/api/v1/creators/social/connect', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Social connect failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['creators', 'social'] });
          qc.invalidateQueries({ queryKey: ['creators', 'profile'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/social/connect', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                          | Lines                                                                              |
| -------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`     | `62–71` (`connectSocial`)                                                          |
| DTO (request)  | `apps/api-core/src/modules/creator/dto/creator-social.dto.ts` | `4–16` (`ConnectSocialDto`)                                                        |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts`         | `SuccessOnlyResponseDto`                                                           |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`        | `203–263` (`connectSocialVerified` + `connectSocial`)                              |
| OAuth verifier | `apps/api-core/src/modules/creator/social/`                   | `socialVerification.verify()` (per-platform OAuth token exchange + identity probe) |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                        | `SocialAccount`, `SocialMetrics`, `CreatorProfile.totalFollowers`                  |


# Disconnect Social Account (/docs/creator/social-disconnect)



`POST /api/v1/creators/social/disconnect` — 🔑 **Bearer** · Rate limit: **30 req / hour**

Deletes the `SocialAccount` row matching `(userId, platform)`. Prisma's relational cascade drops the linked `SocialMetrics` row at the same time. After deletion, `CreatorProfile.totalFollowers` is recomputed from the remaining `SocialMetrics` rows so the dashboard counter stays accurate.



<Callout type="info">
  **Disconnect is by `platform`, not by social account id.** A creator can only have one connected account per platform — that's enforced at connect time — so the platform identifier is sufficient to select the row. The OAuth tokens stored at connect time are dropped along with the row.
</Callout>

## Request [#request]

### Body — `DisconnectSocialDto` [#body--disconnectsocialdto]

| Field      | Type   | Required | Validation   | Notes                                                                            |
| ---------- | ------ | -------- | ------------ | -------------------------------------------------------------------------------- |
| `platform` | string | ✓        | `IsString()` | Same platform identifier used at connect time (e.g. `instagram`, `x`, `youtube`) |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                |
| --------- | ------- | -------------------- |
| `success` | boolean | Always `true` on 200 |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`         | Reason                                                |
| ----- | -------------------------- | ----------------------------------------------------- |
| `400` | (DTO validation)           | Missing `platform`                                    |
| `401` | (guard)                    | Missing / invalid bearer token                        |
| `404` | `creator.social.not_found` | No `SocialAccount` exists for this user/platform pair |
| `429` | (throttle)                 | Rate limit exceeded (30 req/hour)                     |

## Side effects [#side-effects]

1. `prisma.socialAccount.findFirst({ where: { userId, platform } })`. If absent → `not_found`.
2. `prisma.socialAccount.delete({ where: { id } })` — cascade drops the linked `SocialMetrics` row.
3. Sum every remaining `SocialMetrics.followerCount` for this user → `CreatorProfile.totalFollowers` (recompute).
4. Audit log: `[social] Disconnected {platform} for user {userId}`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/creators/social/disconnect \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"platform": "instagram"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function disconnectSocial(accessToken: string, platform: string): Promise<void> {
      const res = await fetch('https://api.bio.re/api/v1/creators/social/disconnect', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ platform }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Social disconnect failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useDisconnectSocial() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (platform: string) => {
          const res = await fetch('/api/v1/creators/social/disconnect', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ platform }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Social disconnect failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['creators', 'social'] });
          qc.invalidateQueries({ queryKey: ['creators', 'profile'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/social/disconnect', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                          | Lines                                                                       |
| -------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`     | `73–83` (`disconnectSocial`)                                                |
| DTO (request)  | `apps/api-core/src/modules/creator/dto/creator-social.dto.ts` | `30–33` (`DisconnectSocialDto`)                                             |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts`         | `SuccessOnlyResponseDto`                                                    |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`        | `265–282` (`disconnectSocial`)                                              |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                        | `SocialAccount`, `SocialMetrics` (cascade), `CreatorProfile.totalFollowers` |


# List Connected Social Accounts (/docs/creator/social-list)



`GET /api/v1/creators/social` — 🔑 **Bearer**

Returns up to **50 connected social accounts** for the calling user, ordered by `connectedAt ASC` (oldest first). Each row exposes only the public-safe fields — the OAuth tokens stored at connect time are kept server-side and never returned.



<Callout type="info">
  The 50-cap is enforced server-side. In practice creators link 2–6 platforms; the cap exists to bound payload size for unusual cases. Pagination is not exposed.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ArrayApiResponseOf<SocialAccountItemDto>` [#200-ok--arrayapiresponseofsocialaccountitemdto]

```json
{
  "success": true,
  "data": [
    {
      "platform": "instagram",
      "platformUsername": "johndoe",
      "verified": true,
      "connectedAt": "2026-04-29T20:00:00.000Z"
    },
    {
      "platform": "x",
      "platformUsername": "@johndoe",
      "verified": true,
      "connectedAt": "2026-04-29T20:00:00.000Z"
    }
  ]
}
```

| Field              | Type              | Notes                                                                                                                                               |
| ------------------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `platform`         | string            | Platform identifier as recorded at connect time                                                                                                     |
| `platformUsername` | string \| null    | Public handle on the platform (may be null if the platform's API didn't return one)                                                                 |
| `verified`         | boolean           | `true` for OAuth-verified connections (always `true` for accounts created via `POST /creators/social/connect` — admin-injected accounts may differ) |
| `connectedAt`      | string (ISO 8601) | When the row was created                                                                                                                            |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                         |
| ----- | ------------------ | ------------------------------ |
| `401` | (guard)            | Missing / invalid bearer token |

## Side effects [#side-effects]

1. `prisma.socialAccount.findMany({ where: { userId }, select: { platform, platformUsername, verified, connectedAt }, orderBy: { connectedAt: 'asc' }, take: 50 })`.
2. Return the array. **`accessToken`, `refreshToken`, `tokenExpiresAt`, `platformUserId` are excluded from the select** — they are server-only.
3. No mutations.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/creators/social \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type SocialAccountItem = {
      platform: string;
      platformUsername: string | null;
      verified: boolean;
      connectedAt: string;
    };

    async function getConnectedSocialAccounts(accessToken: string): Promise<SocialAccountItem[]> {
      const res = await fetch('https://api.bio.re/api/v1/creators/social', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Social list fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const creatorKeys = {
      social: () => ['creators', 'social'] as const,
    };

    export function useConnectedSocialAccounts() {
      return useQuery({
        queryKey: creatorKeys.social(),
        queryFn: async () => {
          const res = await fetch('/api/v1/creators/social');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Social list fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as SocialAccountItem[];
        },
        staleTime: 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/social', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source              | Path                                                                   | Lines                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Controller          | `apps/api-core/src/modules/creator/creator.controller.ts`              | `85–91` (`getSocialAccounts`)                                                                                                |
| DTO (response item) | `apps/api-core/src/modules/creator/dto/creator-client-response.dto.ts` | `303–315` (`SocialAccountItemDto`)                                                                                           |
| Service             | `apps/api-core/src/modules/creator/creator.service.ts`                 | `284–291` (`getSocialAccounts`)                                                                                              |
| Prisma model        | `packages/prisma/prisma/schema.prisma`                                 | `SocialAccount` (server-only fields excluded from select: `accessToken`, `refreshToken`, `tokenExpiresAt`, `platformUserId`) |


# Get Dashboard Login Link (/docs/creator/stripe-connect-dashboard-link)



`POST /api/v1/creators/stripe-connect/dashboard-link` — 🔑 **Bearer** · Rate limit: **10 req / hour**

Returns a **single-use Stripe Express dashboard login URL** for the creator. Use to deep-link from the platform UI into the creator's Stripe dashboard (where they manage payouts, view balances, update payment methods, etc.) without making them log in to Stripe directly.



<Callout type="warn">
  **Active-only.** Dashboard links are gated on `stripeAccountStatus === 'ACTIVE'`. Pending / restricted / disabled accounts can't access the dashboard yet — show the user the onboarding flow instead. Surface "Finish setting up your account" UI when you see `creator.stripe.not_active`.
</Callout>

<Callout type="info">
  **Single-use.** Stripe login links work for one redirect — fetch a new one every time the user clicks "Manage payouts" rather than caching the URL. The URL becomes invalid after first use or after a short timeout.
</Callout>

## Request [#request]

No body, no params. Identity comes from the bearer token.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<StripeConnectDashboardLinkResponseDto>` [#200-ok--apiresponseofstripeconnectdashboardlinkresponsedto]

```json
{
  "success": true,
  "data": {
    "url": "https://connect.stripe.com/express/..."
  }
}
```

| Field | Type   | Notes                                                                                                                     |
| ----- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| `url` | string | One-shot Stripe Express dashboard login URL. Render into a button click handler that immediately redirects — don't store. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                   | Reason                                                                      |
| ----- | ------------------------------------ | --------------------------------------------------------------------------- |
| `400` | `creator.stripe.account_not_found`   | No `stripeAccountId` on the creator                                         |
| `400` | `creator.stripe.not_active`          | `stripeAccountStatus !== 'ACTIVE'` — account hasn't finished onboarding yet |
| `400` | `creator.stripe.service_unavailable` | Stripe SDK is not configured                                                |
| `401` | (guard)                              | Missing / invalid bearer token                                              |
| `404` | `creator.stripe.not_creator`         | No `CreatorProfile` for this user                                           |
| `429` | (throttle)                           | Rate limit exceeded (10 req/hour)                                           |

## Side effects [#side-effects]

1. Lookup `CreatorProfile`; throw `not_creator` if missing.
2. Assert `stripeAccountId` is non-null; otherwise `account_not_found`.
3. Assert `stripeAccountStatus === ACTIVE`; otherwise `not_active`.
4. Call `stripe.accounts.createLoginLink(stripeAccountId)`.
5. Return `{ url: loginLink.url }`. **No DB writes**.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/creators/stripe-connect/dashboard-link \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function getDashboardLink(accessToken: string): Promise<string> {
      const res = await fetch('https://api.bio.re/api/v1/creators/stripe-connect/dashboard-link', {
        method: 'POST',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Dashboard link failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.url as string;
    }

    // Usage: fetch on-demand, redirect immediately
    async function openStripeDashboard(accessToken: string) {
      const url = await getDashboardLink(accessToken);
      window.location.assign(url);
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useGetDashboardLink() {
      // Mutation, not query — single-use URL, never cache
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/creators/stripe-connect/dashboard-link', { method: 'POST' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Dashboard link failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.url as string;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/stripe-connect/dashboard-link', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source          | Path                                                                   | Lines                                                                                                      |
| --------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Controller      | `apps/api-core/src/modules/creator/stripe-connect.controller.ts`       | `44–51` (`dashboardLink`)                                                                                  |
| DTO (response)  | `apps/api-core/src/modules/creator/dto/stripe-connect-response.dto.ts` | `48–51` (`StripeConnectDashboardLinkResponseDto`)                                                          |
| Service         | `apps/api-core/src/modules/creator/stripe-connect.service.ts`          | `183–207` (`getDashboardLink`)                                                                             |
| Stripe provider | `apps/api-core/src/modules/payment/stripe.provider.ts`                 | `requireStripe()`                                                                                          |
| Prisma model    | `packages/prisma/prisma/schema.prisma`                                 | `CreatorProfile.stripeAccountId`, `CreatorProfile.stripeAccountStatus` (`enum StripeAccountStatus.ACTIVE`) |


# Initiate Stripe Connect (/docs/creator/stripe-connect-initiate)



`POST /api/v1/creators/stripe-connect/initiate` — 🔑 **Bearer** · Rate limit: **10 req / hour**

Creates a Stripe Connect Express account for the calling creator and returns a fresh onboarding link. &#x2A;*KYC must be `APPROVED`** before this endpoint will work — the platform requires identity verification before opening up payouts. Idempotent: if the creator already has a Stripe account, a new onboarding link is generated against it (no duplicate account creation).



<Callout type="warn">
  **KYC gate is hard.** A creator with `kycStatus !== 'APPROVED'` can't initiate Stripe Connect — call `POST /creators/kyc/start` first and wait for the webhook to flip status to `APPROVED`. Surface "Complete identity verification first" UI when you see `creator.stripe.kyc_required`.
</Callout>

<Callout type="info">
  **Race-safe via atomic claim.** Concurrent calls don't create duplicate Stripe accounts — the first call wins via `updateMany({ where: stripeAccountId: null })`; subsequent racers either find the freshly-set id and return a fresh link, or fail with `connect_in_progress` if they slip between the claim and the persist.
</Callout>

## Request [#request]

No body, no params. Identity comes from the bearer token.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `201 Created` — `ApiResponseOf<StripeConnectInitiateResponseDto>` [#201-created--apiresponseofstripeconnectinitiateresponsedto]

```json
{
  "success": true,
  "data": {
    "accountId": "acct_...",
    "onboardingUrl": "https://connect.stripe.com/express/onboarding/..."
  }
}
```

| Field           | Type   | Notes                                                                                                                                                                        |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accountId`     | string | Stripe Express account id (saved on `CreatorProfile.stripeAccountId`). Treat as opaque — pass back to `/refresh-link` and `/dashboard-link` only via the platform endpoints. |
| `onboardingUrl` | string | Fresh hosted onboarding URL. Open in a new tab or full-page redirect. **Single-use, time-limited** — fetch a new one via `/refresh-link` if it expires.                      |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                   | Reason                                                                                                    |
| ----- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `400` | `creator.stripe.kyc_required`        | `kycStatus !== 'APPROVED'` — complete KYC first                                                           |
| `400` | `creator.stripe.connect_in_progress` | Concurrent call won the atomic claim before this one persisted                                            |
| `400` | `creator.stripe.service_unavailable` | Stripe SDK is not configured (server-side env / config issue) — surface "payment temporarily unavailable" |
| `401` | (guard)                              | Missing / invalid bearer token                                                                            |
| `404` | `creator.stripe.not_creator`         | No `CreatorProfile` for this user — call `POST /creators/upgrade` first                                   |
| `429` | (throttle)                           | Rate limit exceeded (10 req/hour)                                                                         |

## Side effects [#side-effects]

1. Lookup `CreatorProfile` (with `user.email`); throw `not_creator` if missing.
2. **KYC gate**: assert `kycStatus === APPROVED`; otherwise `kyc_required`.
3. **Idempotent path** — if `stripeAccountId` already set: skip account creation, just call `createAccountLink(stripeAccountId)` and return.
4. **Atomic claim** — `updateMany({ where: { userId, stripeAccountId: null }, data: { stripeAccountStatus: PENDING } })`. Zero rows touched → another concurrent request beat us; re-read and either return its result or throw `connect_in_progress`.
5. **Stripe SDK creates the Express account** — `accounts.create({ type: 'express', country: <stripe.connect_country admin-managed, default 'US'>, email: user.email, metadata: { creatorId, userId, platform: 'biore' }, capabilities: { transfers: { requested: true } } })`.
6. Persist `stripeAccountId` (`update({ stripeAccountId })`).
7. Audit log: `[stripe-connect] Account created: {accountId} for creator {creatorId}`.
8. Generate the onboarding URL via `createAccountLink(accountId)` (Stripe `accountLinks.create`).
9. Return `{ accountId, onboardingUrl }`.
10. **Webhook updates status fields** — Stripe's `account.updated` webhook flips `stripeChargesEnabled` / `stripePayoutsEnabled` / `stripeAccountStatus` server-side as the creator completes onboarding (handled by an internal webhook controller, not this portal).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/creators/stripe-connect/initiate \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type StripeConnectInitiate = {
      accountId: string;
      onboardingUrl: string;
    };

    async function initiateStripeConnect(accessToken: string): Promise<StripeConnectInitiate> {
      const res = await fetch('https://api.bio.re/api/v1/creators/stripe-connect/initiate', {
        method: 'POST',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Stripe Connect initiate failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }

    // Usage: redirect to onboardingUrl in a new tab
    function openOnboarding(onboardingUrl: string) {
      window.location.assign(onboardingUrl);
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useInitiateStripeConnect() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/creators/stripe-connect/initiate', { method: 'POST' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Stripe Connect initiate failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as StripeConnectInitiate;
        },
        onSuccess: () => {
          // Status flipped to PENDING server-side
          qc.invalidateQueries({ queryKey: ['creators', 'stripe-connect', 'status'] });
          qc.invalidateQueries({ queryKey: ['creators', 'payout-settings'] });
          qc.invalidateQueries({ queryKey: ['creators', 'profile'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/stripe-connect/initiate', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source                | Path                                                                   | Lines                                                                                                                                                       |
| --------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Controller            | `apps/api-core/src/modules/creator/stripe-connect.controller.ts`       | `19–25` (`initiate`)                                                                                                                                        |
| DTO (response)        | `apps/api-core/src/modules/creator/dto/stripe-connect-response.dto.ts` | `9–15` (`StripeConnectInitiateResponseDto`)                                                                                                                 |
| Service               | `apps/api-core/src/modules/creator/stripe-connect.service.ts`          | `25–98` (`initiateConnect`)                                                                                                                                 |
| Stripe provider       | `apps/api-core/src/modules/payment/stripe.provider.ts`                 | `getStripe()`, `requireStripe()`                                                                                                                            |
| Config                | `apps/api-core/src/modules/config/config.service.ts`                   | `stripe.connect_country` (admin-managed, default `'US'`)                                                                                                    |
| Webhook (status sync) | `apps/api-core/src/modules/payment/`                                   | Stripe `account.updated` handler (internal scope)                                                                                                           |
| Prisma model          | `packages/prisma/prisma/schema.prisma`                                 | `CreatorProfile.stripeAccountId`, `CreatorProfile.stripeAccountStatus` (`enum StripeAccountStatus`), `CreatorProfile.kycStatus` (`enum KycStatus.APPROVED`) |


# Refresh Onboarding Link (/docs/creator/stripe-connect-refresh-link)



`POST /api/v1/creators/stripe-connect/refresh-link` — 🔑 **Bearer** · Rate limit: **10 req / hour**

Generates a fresh hosted onboarding link for the existing Stripe Connect account. Use when the previously-issued link expired (Stripe links are short-lived) or the user closed the tab mid-onboarding and you need to resume.



<Callout type="info">
  This is **not** the same as `/initiate` — it requires an existing account (`stripeAccountId` already set). If the creator hasn't started onboarding yet, call `/initiate` instead. Both endpoints return the same `onboardingUrl` shape.
</Callout>

## Request [#request]

No body, no params. Identity comes from the bearer token.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<StripeConnectRefreshLinkResponseDto>` [#200-ok--apiresponseofstripeconnectrefreshlinkresponsedto]

```json
{
  "success": true,
  "data": {
    "onboardingUrl": "https://connect.stripe.com/express/onboarding/..."
  }
}
```

| Field           | Type   | Notes                                                                                                             |
| --------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `onboardingUrl` | string | Fresh hosted onboarding URL. Same characteristics as the link returned by `/initiate` — single-use, time-limited. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                 | Reason                                                                                    |
| ----- | ---------------------------------- | ----------------------------------------------------------------------------------------- |
| `400` | `creator.stripe.account_not_found` | No `stripeAccountId` on the creator — call `POST /creators/stripe-connect/initiate` first |
| `401` | (guard)                            | Missing / invalid bearer token                                                            |
| `404` | `creator.stripe.not_creator`       | No `CreatorProfile` for this user                                                         |
| `429` | (throttle)                         | Rate limit exceeded (10 req/hour)                                                         |

## Side effects [#side-effects]

1. Lookup `CreatorProfile`; throw `not_creator` if missing.
2. Assert `stripeAccountId` is non-null; otherwise `account_not_found`.
3. Call `createAccountLink(stripeAccountId)` (Stripe `accountLinks.create`).
4. Return `{ onboardingUrl }`. **No DB writes** — this endpoint only generates a link.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/creators/stripe-connect/refresh-link \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function refreshOnboardingLink(accessToken: string): Promise<string> {
      const res = await fetch('https://api.bio.re/api/v1/creators/stripe-connect/refresh-link', {
        method: 'POST',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Refresh link failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.onboardingUrl as string;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useRefreshOnboardingLink() {
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/creators/stripe-connect/refresh-link', { method: 'POST' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Refresh link failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.onboardingUrl as string;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/stripe-connect/refresh-link', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                     |
| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/stripe-connect.controller.ts`       | `35–42` (`refreshLink`)                                                   |
| DTO (response) | `apps/api-core/src/modules/creator/dto/stripe-connect-response.dto.ts` | `40–43` (`StripeConnectRefreshLinkResponseDto`)                           |
| Service        | `apps/api-core/src/modules/creator/stripe-connect.service.ts`          | `167–178` (`refreshLink`), `createAccountLink()` (Stripe link generation) |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                                 | `CreatorProfile.stripeAccountId`                                          |


# Get Stripe Connect Status (/docs/creator/stripe-connect-status)



`GET /api/v1/creators/stripe-connect/status` — 🔑 **Bearer** · Rate limit: **10 req / hour**

Returns the current Stripe Connect account state. **Pulls fresh from Stripe** when an account exists — and **syncs the result back to the database** before returning, so the next read of `CreatorProfile.stripe*` fields is up-to-date even if the webhook is delayed. Falls back to stored DB values if Stripe SDK isn't configured or the API call fails.



<Callout type="info">
  **`detailsSubmitted` is not stored in our DB.** It comes only from the live Stripe API call. When the Stripe call fails (or no account is connected yet), the fallback path returns `detailsSubmitted: false` — that's "we don't know" rather than a definitive "no". Read `chargesEnabled` / `payoutsEnabled` for the actual gate decisions.
</Callout>

<Callout type="warn">
  **This endpoint mutates the DB on success.** Every successful read also writes back `stripeAccountStatus` / `stripeChargesEnabled` / `stripePayoutsEnabled` from Stripe. Don't call it in tight loops; use `/creators/payout-settings` for the cached read and call this only when you need fresh-from-Stripe data.
</Callout>

## Request [#request]

No body, no params. Identity comes from the bearer token.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<StripeConnectStatusResponseDto>` [#200-ok--apiresponseofstripeconnectstatusresponsedto]

```json
{
  "success": true,
  "data": {
    "stripeAccountId": "acct_...",
    "stripeAccountStatus": "ACTIVE",
    "chargesEnabled": true,
    "payoutsEnabled": true,
    "detailsSubmitted": true
  }
}
```

| Field                 | Type           | Notes                                                                                                                                      |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `stripeAccountId`     | string \| null | Stripe Express account id; `null` until `/initiate` runs                                                                                   |
| `stripeAccountStatus` | enum           | One of `NOT_STARTED` / `PENDING` / `ACTIVE` / `RESTRICTED` / `DISABLED` (resolved by `resolveAccountStatus()` from Stripe's account flags) |
| `chargesEnabled`      | boolean        | `true` once Stripe has approved charges. Required for marketplace flows.                                                                   |
| `payoutsEnabled`      | boolean        | `true` once Stripe has approved payouts. Required to actually receive money.                                                               |
| `detailsSubmitted`    | boolean        | `true` once the account holder has submitted all required onboarding details. **Live-only field**; fallback returns `false`.               |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`           | Reason                            |
| ----- | ---------------------------- | --------------------------------- |
| `401` | (guard)                      | Missing / invalid bearer token    |
| `404` | `creator.stripe.not_creator` | No `CreatorProfile` for this user |
| `429` | (throttle)                   | Rate limit exceeded (10 req/hour) |

## Side effects [#side-effects]

1. Lookup `CreatorProfile`; throw `not_creator` if missing.
2. **No Stripe account yet** (`stripeAccountId === null`) — short-circuit return: stored `stripeAccountStatus` from DB (typically `NOT_STARTED`), all booleans `false`, `stripeAccountId: null`. **No mutations**, no Stripe call.
3. **Account exists** — try `stripe.accounts.retrieve(stripeAccountId)`:
   * **Success path**: compute `status = resolveAccountStatus(account)` (maps Stripe flags to our enum), `update CreatorProfile { stripeAccountStatus, stripeChargesEnabled = account.charges_enabled, stripePayoutsEnabled = account.payouts_enabled }` (DB sync), return live values.
   * **Failure path** (Stripe SDK unavailable, network failure, API error): log warning, return stored DB values with `detailsSubmitted: false`. **No DB write** in this path.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/creators/stripe-connect/status \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type StripeAccountStatus = 'NOT_STARTED' | 'PENDING' | 'ACTIVE' | 'RESTRICTED' | 'DISABLED';

    type StripeConnectStatus = {
      stripeAccountId: string | null;
      stripeAccountStatus: StripeAccountStatus;
      chargesEnabled: boolean;
      payoutsEnabled: boolean;
      detailsSubmitted: boolean;
    };

    async function getStripeConnectStatus(accessToken: string): Promise<StripeConnectStatus> {
      const res = await fetch('https://api.bio.re/api/v1/creators/stripe-connect/status', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Stripe Connect status fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const creatorKeys = {
      stripeConnectStatus: () => ['creators', 'stripe-connect', 'status'] as const,
    };

    export function useStripeConnectStatus() {
      return useQuery({
        queryKey: creatorKeys.stripeConnectStatus(),
        queryFn: async () => {
          const res = await fetch('/api/v1/creators/stripe-connect/status');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Stripe Connect status fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as StripeConnectStatus;
        },
        // Live API call — keep stale window long; refetch only on explicit user action
        staleTime: 5 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/stripe-connect/status', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source          | Path                                                                   | Lines                                                                                                                                                       |
| --------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Controller      | `apps/api-core/src/modules/creator/stripe-connect.controller.ts`       | `27–33` (`status`)                                                                                                                                          |
| DTO (response)  | `apps/api-core/src/modules/creator/dto/stripe-connect-response.dto.ts` | `20–35` (`StripeConnectStatusResponseDto`)                                                                                                                  |
| Service         | `apps/api-core/src/modules/creator/stripe-connect.service.ts`          | `103–162` (`getStatus`), `resolveAccountStatus()` (status mapping helper)                                                                                   |
| Stripe provider | `apps/api-core/src/modules/payment/stripe.provider.ts`                 | `getStripe()` (returns null if not configured)                                                                                                              |
| Prisma model    | `packages/prisma/prisma/schema.prisma`                                 | `CreatorProfile.stripeAccountId`, `CreatorProfile.stripeAccountStatus` (enum), `CreatorProfile.stripeChargesEnabled`, `CreatorProfile.stripePayoutsEnabled` |


# Confirm Subscription (/docs/creator/subscribe-confirm)



`GET /api/v1/creators/subscribe/confirm` — 🌐 **Public** · Rate limit: **10 req / minute**

Activates a pending subscription using the opaque token from the confirmation email. **Single-use**: the token is consumed (`confirmToken = null`) and `confirmed` flips to `true`. Already-confirmed and unknown tokens both return `404 token_invalid` (no enumeration leak).



<Callout type="info">
  The confirmation link is built by the subscribe endpoint as `<seo.canonical_base_url>/subscribe/confirm?token=...`. Your frontend should expose a route at that path that calls this API, then renders a success / failure message.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param   | Type   | Required | Notes                                               |
| ------- | ------ | -------- | --------------------------------------------------- |
| `token` | string | ✓        | Opaque single-use token from the confirmation email |

No body, no headers required.

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                                                                                           |
| --------- | ------- | ----------------------------------------------------------------------------------------------- |
| `success` | boolean | Always `true` on 200. The subscription is now active and will receive future newsletter emails. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                | Reason                                                                                               |
| ----- | --------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `404` | `creator.subscribe.token_invalid` | Token missing, unknown, or already-consumed. **Same code for all three** to avoid enumeration leaks. |
| `429` | (throttle)                        | Rate limit exceeded (10 req/min)                                                                     |

## Side effects [#side-effects]

1. Reject empty `token` → `token_invalid`.
2. `bioEmailSubscriber.findUnique({ where: { confirmToken: token } })`.
3. **If subscriber missing OR already `confirmed`** → throw `token_invalid` (the same code, on purpose).
4. `bioEmailSubscriber.update({ where: { id: subscriber.id }, data: { confirmed: true, confirmToken: null } })`.
5. Return `{ success: true }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/creators/subscribe/confirm?token=abc123-from-email'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function confirmSubscription(token: string): Promise<void> {
      const url = new URL('https://api.bio.re/api/v1/creators/subscribe/confirm');
      url.searchParams.set('token', token);
      const res = await fetch(url);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Confirmation failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export function useConfirmSubscription(token: string) {
      // Use a one-shot useQuery rather than a mutation — the page lifecycle is "open link, confirm, render result"
      return useQuery({
        queryKey: ['subscribe', 'confirm', token],
        queryFn: async () => {
          const url = new URL('/api/v1/creators/subscribe/confirm', window.location.origin);
          url.searchParams.set('token', token);
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Confirmation failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return true;
        },
        enabled: Boolean(token),
        retry: false, // Single-shot — bad token shouldn't retry
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/subscribe/confirm', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                      | Lines                                                             |
| -------------- | --------------------------------------------------------- | ----------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts` | `309–317` (`confirmSubscription`)                                 |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts`     | `SuccessOnlyResponseDto`                                          |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`    | `662–677` (`confirmSubscription`)                                 |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                    | `BioEmailSubscriber.confirmToken`, `BioEmailSubscriber.confirmed` |


# Resend Confirmation Email (/docs/creator/subscribe-resend)



`POST /api/v1/creators/subscribe/resend` — 🌐 **Public** · Rate limit: **3 req / hour**

If an unconfirmed subscription exists for the submitted email, generates a new `confirmToken` and re-sends the confirmation email through the **active email provider** (admin-managed via `external.email.active_provider`). **Always returns the same safe message** — successfully or not — so the endpoint can't be abused for email enumeration.



<Callout type="warn">
  **No enumeration possible.** Whether the email is registered, confirmed, or unknown, the response is identical. Don't try to disambiguate states client-side.
</Callout>

## Request [#request]

### Body — `ResendConfirmationDto` [#body--resendconfirmationdto]

| Field   | Type   | Required | Validation  | Notes                                              |
| ------- | ------ | -------- | ----------- | -------------------------------------------------- |
| `email` | string | ✓        | `IsEmail()` | The email to resend to. Server lowercases + trims. |

No headers required.

## Response [#response]

### `200 OK` — `ApiResponseOf<MessageResponseDto>` [#200-ok--apiresponseofmessageresponsedto]

```json
{
  "success": true,
  "data": {
    "message": "If an unconfirmed subscription exists, a confirmation email has been sent."
  }
}
```

| Field     | Type   | Notes                                                                 |
| --------- | ------ | --------------------------------------------------------------------- |
| `message` | string | Always the same safe phrase, regardless of whether anything was sent. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `400` | (DTO validation)   | Email format failure             |
| `429` | (throttle)         | Rate limit exceeded (3 req/hour) |

## Side effects [#side-effects]

1. Normalize email: `.toLowerCase().trim()`.
2. Lookup `BioEmailSubscriber` where `email = normalizedEmail AND confirmed = false`.
3. **If absent** — return the safe message. **No mutations**, no email sent.
4. **If found**:
   * Generate `newToken = randomUUID()`.
   * `bioEmailSubscriber.update({ where: { id }, data: { confirmToken: newToken } })`.
   * Build confirm URL with the new token (`<seo.canonical_base_url>/subscribe/confirm?token=<newToken>`).
   * **Fire-and-forget** dispatch via `notificationService.send({ eventKey: 'email_subscription_confirm', userId: 'system', variables: { confirmUrl, email } })`. Failure is logged.
   * Return the safe message.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/creators/subscribe/resend \
      -H 'Content-Type: application/json' \
      -d '{"email": "fan@example.com"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function resendSubscriptionConfirmation(email: string): Promise<string> {
      const res = await fetch('https://api.bio.re/api/v1/creators/subscribe/resend', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Resend failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.message as string;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useResendSubscriptionConfirmation() {
      return useMutation({
        mutationFn: async (email: string) => {
          const res = await fetch('/api/v1/creators/subscribe/resend', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ email }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Resend failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.message as string;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/subscribe/resend', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                               | Lines                                                             |
| -------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`          | `319–327` (`resendSubscriptionConfirmation`)                      |
| DTO (request)  | `apps/api-core/src/modules/creator/dto/resend-confirmation.dto.ts` | `4–8` (`ResendConfirmationDto`)                                   |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts`              | `MessageResponseDto`                                              |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`             | `679–712` (`resendSubscriptionConfirmation`)                      |
| Email provider | (admin-managed)                                                    | `external.email.active_provider`                                  |
| Config         | `apps/api-core/src/modules/config/config.service.ts`               | `seo.canonical_base_url` (admin-managed)                          |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                             | `BioEmailSubscriber.confirmToken`, `BioEmailSubscriber.confirmed` |


# Subscribe to Bio Page (/docs/creator/subscribe)



`POST /api/v1/creators/:bioPageId/subscribe` — 🌐 **Public** · Rate limit: **5 req / hour**

Adds a fan email to a creator's bio page mailing list. **Double-opt-in** — the row is created with `confirmed: false`, a `confirmToken` is generated, and a confirmation email is dispatched via the **active email provider** (admin-managed via `external.email.active_provider`). The subscription only becomes "active" once the user clicks the link in the email, which calls `GET /creators/subscribe/confirm`.



<Callout type="info">
  **Email collection must be enabled** on the bio page for this endpoint to work. The creator opts in via `PATCH /creators/:creatorId/bio { emailCollectionEnabled: true }`. Otherwise the call fails with `400 not_enabled`.
</Callout>

<Callout type="warn">
  **Per-bio-page uniqueness.** A given email can subscribe to the same bio page only once — Prisma `P2002` (unique constraint) is mapped to `409 already_subscribed`. Different bio pages don't conflict.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param       | Type          | Validation      | Notes                                 |
| ----------- | ------------- | --------------- | ------------------------------------- |
| `bioPageId` | string (UUID) | `ParseUUIDPipe` | The bio page hosting the mailing list |

### Body — `SubscribeToBioDto` [#body--subscribetobiodto]

| Field   | Type   | Required | Validation       | Notes                                                                                          |
| ------- | ------ | -------- | ---------------- | ---------------------------------------------------------------------------------------------- |
| `email` | string | ✓        | `IsEmail()`      | Fan's email address. Server lowercases + trims before storing.                                 |
| `name`  | string | optional | `MaxLength(100)` | Display name. **HTML-stripped server-side** to avoid stored XSS via subscriber list rendering. |

No headers required.

## Response [#response]

### `200 OK` — `ApiResponseOf<MessageResponseDto>` [#200-ok--apiresponseofmessageresponsedto]

```json
{
  "success": true,
  "data": {
    "message": "Please check your email to confirm subscription"
  }
}
```

| Field     | Type   | Notes                                                        |
| --------- | ------ | ------------------------------------------------------------ |
| `message` | string | Localizable confirmation prompt — surface as a toast/banner. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                     | Reason                                                                                        |
| ----- | -------------------------------------- | --------------------------------------------------------------------------------------------- |
| `400` | `creator.subscribe.not_enabled`        | `BioPage.emailCollectionEnabled !== true`                                                     |
| `400` | (DTO validation)                       | Invalid email format; `name` exceeds 100 chars; `bioPageId` not a UUID                        |
| `409` | `creator.subscribe.already_subscribed` | This email is already in the `BioEmailSubscriber` table for this bio page (Prisma P2002 race) |
| `429` | (throttle)                             | Rate limit exceeded (5 req/hour)                                                              |

## Side effects [#side-effects]

1. Lookup `BioPage`; if `emailCollectionEnabled !== true` → throw `not_enabled`.
2. Normalize email: `.toLowerCase().trim()`.
3. Sanitize `name`: `stripHtmlTags(name)`.
4. Generate `confirmToken = randomUUID()`.
5. `bioEmailSubscriber.create({ bioPageId, email, name, confirmToken })` — Prisma `P2002` mapped to `already_subscribed`.
6. Build confirm URL: `<seo.canonical_base_url>/subscribe/confirm?token=<confirmToken>` (admin-managed base URL).
7. **Fire-and-forget** dispatch via `notificationService.send({ eventKey: 'email_subscription_confirm', userId: 'system', variables: { confirmUrl, email } })` — failure is logged, request still succeeds.
8. Return the safe message. **Subscription is still pending** — see `GET /creators/subscribe/confirm` for the activation step.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST 'https://api.bio.re/api/v1/creators/b1a2b3c4-d5e6-7890-abcd-ef1234567890/subscribe' \
      -H 'Content-Type: application/json' \
      -d '{
        "email": "fan@example.com",
        "name": "Fan Doe"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type SubscribeToBioInput = {
      email: string;
      name?: string;
    };

    async function subscribeToBio(bioPageId: string, input: SubscribeToBioInput): Promise<string> {
      const res = await fetch(`https://api.bio.re/api/v1/creators/${bioPageId}/subscribe`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Subscribe failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.message as string;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useSubscribeToBio(bioPageId: string) {
      return useMutation({
        mutationFn: async (input: SubscribeToBioInput) => {
          const res = await fetch(`/api/v1/creators/${bioPageId}/subscribe`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Subscribe failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.message as string;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/{bioPageId}/subscribe', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source                | Path                                                             | Lines                                                                                   |
| --------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Controller            | `apps/api-core/src/modules/creator/creator.controller.ts`        | `339–349` (`subscribe`)                                                                 |
| DTO (request)         | `apps/api-core/src/modules/creator/dto/creator.dto.ts`           | `128–134` (`SubscribeToBioDto`)                                                         |
| DTO (response)        | `apps/api-core/src/common/dto/common-response.dto.ts`            | `MessageResponseDto`                                                                    |
| Service               | `apps/api-core/src/modules/creator/creator.service.ts`           | `631–660` (`subscribeToBioPage`)                                                        |
| Notification pipeline | `apps/api-core/src/modules/notification/notification.service.ts` | `send()` (active email provider, admin-managed)                                         |
| Config                | `apps/api-core/src/modules/config/config.service.ts`             | `seo.canonical_base_url` (admin-managed)                                                |
| Email provider        | (admin-managed)                                                  | `external.email.active_provider`                                                        |
| Prisma model          | `packages/prisma/prisma/schema.prisma`                           | `BioPage.emailCollectionEnabled`, `BioEmailSubscriber` (`@@unique([bioPageId, email])`) |


# List Subscribers (Creator) (/docs/creator/subscribers)



`GET /api/v1/creators/subscribers` — 🔑 **Bearer**

Lists the calling creator's mailing-list subscribers — only those who **confirmed** their subscription AND have **not unsubscribed**. Owner-only: the creator's bio page is resolved server-side from the bearer's user id; you don't pass a `bioPageId`. Pagination via `?page` / `?limit`, server-clamped to `[1, 100]` per page.



<Callout type="warn">
  **Sensitive field exposure (known issue).** Each item currently includes `confirmToken` — a server-side comment in the DTO marks this as a TODO to omit/mask in a future iteration. Until then, **do not log the response** in any client-side observability tool, and treat the field as if it weren't there. It will likely become `null` on confirmed subscribers anyway (the confirm endpoint sets `confirmToken: null`), but unconfirmed-then-unsubscribed edge cases may surface real tokens.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param   | Type   | Default | Validation                                   | Notes                |
| ------- | ------ | ------- | -------------------------------------------- | -------------------- |
| `page`  | number | `1`     | `ParseIntPipe`, server-clamped to `>= 1`     | Page index (1-based) |
| `limit` | number | `50`    | `ParseIntPipe`, server-clamped to `[1, 100]` | Items per page       |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<SubscribersResponseDto>` [#200-ok--apiresponseofsubscribersresponsedto]

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "s1u2b3c4-d5e6-7890-abcd-ef1234567890",
        "bioPageId": "b1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "email": "fan@example.com",
        "name": "Fan Doe",
        "subscribedAt": "2026-04-29T20:00:00.000Z",
        "unsubscribedAt": null,
        "confirmed": true,
        "confirmToken": null,
        "source": "bio_page",
        "createdAt": "2026-04-29T20:00:00.000Z"
      }
    ],
    "total": 42
  }
}
```

### Item fields [#item-fields]

| Field            | Type                      | Notes                                                                          |
| ---------------- | ------------------------- | ------------------------------------------------------------------------------ |
| `id`             | string (UUID)             | `BioEmailSubscriber.id` — pass to the unsubscribe link                         |
| `bioPageId`      | string (UUID)             | The bio page this subscription belongs to                                      |
| `email`          | string                    | Lowercased email                                                               |
| `name`           | string \| null            | HTML-stripped at write time                                                    |
| `subscribedAt`   | string (ISO 8601)         | When the row was created (subscription start)                                  |
| `unsubscribedAt` | string (ISO 8601) \| null | Always `null` here (filter excludes non-null)                                  |
| `confirmed`      | boolean                   | Always `true` here (filter requires confirmation)                              |
| `confirmToken`   | string \| null            | **Sensitive — see callout above.** Typically `null` for confirmed subscribers. |
| `source`         | string \| null            | Acquisition source tag (e.g. `bio_page`)                                       |
| `createdAt`      | string (ISO 8601)         | DB row creation timestamp                                                      |

### Top-level fields [#top-level-fields]

| Field   | Type   | Notes                                                                    |
| ------- | ------ | ------------------------------------------------------------------------ |
| `items` | array  | Up to `limit` items, ordered by `subscribedAt DESC`                      |
| `total` | number | Total count of confirmed + active subscribers (matching the same filter) |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`      | Reason                                |
| ----- | ----------------------- | ------------------------------------- |
| `400` | (validation)            | `page` / `limit` not parseable as int |
| `401` | (guard)                 | Missing / invalid bearer token        |
| `404` | `creator.bio.not_found` | No `BioPage` for this creator         |

## Side effects [#side-effects]

1. Resolve `creatorId` from the bearer's `userId` via `prisma.creatorProfile.findUnique({ where: { userId }, select: { id: true } })`.
2. Lookup `BioPage` by `creatorId`; throw `not_found` if missing.
3. Clamp pagination: `safePage = max(page, 1)`, `safeLimit = min(max(limit, 1), 100)`.
4. **Two queries in parallel**:
   * `findMany({ where: { bioPageId, confirmed: true, unsubscribedAt: null }, skip, take, orderBy: { subscribedAt: 'desc' } })`.
   * `count({ where: <same filter> })`.
5. Return `{ items, total }`. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/creators/subscribers?page=1&limit=50' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type SubscriberItem = {
      id: string;
      bioPageId: string;
      email: string;
      name: string | null;
      subscribedAt: string;
      unsubscribedAt: string | null;
      confirmed: boolean;
      confirmToken: string | null;
      source: string | null;
      createdAt: string;
    };

    type SubscribersResponse = {
      items: SubscriberItem[];
      total: number;
    };

    async function getSubscribers(accessToken: string, page = 1, limit = 50): Promise<SubscribersResponse> {
      const url = new URL('https://api.bio.re/api/v1/creators/subscribers');
      url.searchParams.set('page', String(page));
      url.searchParams.set('limit', String(limit));
      const res = await fetch(url, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Subscribers fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const creatorKeys = {
      subscribers: (page: number, limit: number) => ['creators', 'subscribers', page, limit] as const,
    };

    export function useSubscribers(page = 1, limit = 50) {
      return useQuery({
        queryKey: creatorKeys.subscribers(page, limit),
        queryFn: async () => {
          const url = new URL('/api/v1/creators/subscribers', window.location.origin);
          url.searchParams.set('page', String(page));
          url.searchParams.set('limit', String(limit));
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Subscribers fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as SubscribersResponse;
        },
        staleTime: 30_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/subscribers', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                        |
| -------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`              | `351–361` (`getSubscribers`)                                                 |
| DTO (response) | `apps/api-core/src/modules/creator/dto/creator-client-response.dto.ts` | `595–601` (`SubscribersResponseDto`), `562–593` (`SubscriberItemDto`)        |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`                 | `731–744` (`getSubscribers`)                                                 |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                                 | `BioEmailSubscriber` (filtered `confirmed = true AND unsubscribedAt = null`) |


# Unsubscribe (/docs/creator/unsubscribe)



`GET /api/v1/creators/unsubscribe` — 🌐 **Public** · Rate limit: **10 req / minute**

Soft-unsubscribes a fan from a bio page mailing list. **Soft-delete**: sets `unsubscribedAt = now()` rather than removing the row, so the audit trail (when did this person sign up, when did they leave) stays intact. The row is excluded from `GET /creators/subscribers` (which filters `unsubscribedAt IS NULL`) and from future newsletter dispatches.



<Callout type="info">
  The unsubscribe link in newsletter emails is built with the subscriber's `id` (not email) as the query param — anyone with the link can unsubscribe that subscriber. This is standard mailing-list UX and intentional.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param | Type   | Required | Notes                                                                         |
| ----- | ------ | -------- | ----------------------------------------------------------------------------- |
| `id`  | string | ✓        | The `BioEmailSubscriber.id` from the unsubscribe link in the newsletter email |

No body, no headers required.

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                |
| --------- | ------- | -------------------- |
| `success` | boolean | Always `true` on 200 |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`            | Reason                                              |
| ----- | ----------------------------- | --------------------------------------------------- |
| `404` | `creator.subscribe.not_found` | `id` missing or no `BioEmailSubscriber` row matches |
| `429` | (throttle)                    | Rate limit exceeded (10 req/min)                    |

## Side effects [#side-effects]

1. Reject empty `id` → `not_found`.
2. `bioEmailSubscriber.findUnique({ where: { id: subscriberId } })`. Missing → `not_found`.
3. `bioEmailSubscriber.update({ where: { id }, data: { unsubscribedAt: new Date() } })`.
4. Return `{ success: true }`. The row is NOT deleted; it's just timestamped as unsubscribed.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/creators/unsubscribe?id=s1u2b3c4-d5e6-7890-abcd-ef1234567890'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function unsubscribe(subscriberId: string): Promise<void> {
      const url = new URL('https://api.bio.re/api/v1/creators/unsubscribe');
      url.searchParams.set('id', subscriberId);
      const res = await fetch(url);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Unsubscribe failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useUnsubscribe() {
      return useMutation({
        mutationFn: async (subscriberId: string) => {
          const url = new URL('/api/v1/creators/unsubscribe', window.location.origin);
          url.searchParams.set('id', subscriberId);
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Unsubscribe failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/unsubscribe', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                      | Lines                               |
| -------------- | --------------------------------------------------------- | ----------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts` | `329–337` (`unsubscribe`)           |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts`     | `SuccessOnlyResponseDto`            |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`    | `714–729` (`unsubscribe`)           |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                    | `BioEmailSubscriber.unsubscribedAt` |


# Upgrade to Creator (/docs/creator/upgrade)



`POST /api/v1/creators/upgrade` — 🔑 **Bearer** · Rate limit: **30 req / hour**

Converts a fan account into a creator. **Atomic**: in one transaction, creates a `CreatorProfile` (level `BRONZE`, `kycStatus = NOT_STARTED`), creates a `BioPage` (published), and updates `User.intent = CREATOR` (also sets `displayName` / `username` if supplied). Returns the new `creatorId` and the public `bioPageUrl`.



<Callout type="info">
  **Username is mandatory.** If the user already has a `username` on their `User` row, you can omit it from the body — it will be reused. If the user has never set a username, the body **must** include one (lowercase alphanumeric + `._-`, max 100 chars). Reserved usernames (e.g. system-protected) are rejected with `409`.
</Callout>

<Callout type="warn">
  **Admin kill switch.** When the `CREATOR_UPGRADE` kill switch is active (admin-managed), every call returns `503 features.creator_upgrade_disabled` regardless of body. Surface a "creator signups are paused" UI when you see that response.
</Callout>

## Request [#request]

### Body — `OnboardingDto` [#body--onboardingdto]

All fields optional except `username` is conditionally required (see callout).

| Field         | Type   | Validation                               | Notes                                                                                     |
| ------------- | ------ | ---------------------------------------- | ----------------------------------------------------------------------------------------- |
| `displayName` | string | `MaxLength(100)`                         | Optional — overrides `User.displayName` if present                                        |
| `bio`         | string | `MaxLength(500)`                         | Initial bio for the new `BioPage`. Falls back to `User.displayName` (or empty) if absent. |
| `themeId`     | string | `MaxLength(50)`                          | Optional — sets `BioPage.templateId` to this id                                           |
| `username`    | string | regex `^[a-z0-9._-]+$`, `MaxLength(100)` | **Required if `User.username` is null.** Lowercased + trimmed server-side.                |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `201 Created` — `ApiResponseOf<UpgradeToCreatorResponseDto>` [#201-created--apiresponseofupgradetocreatorresponsedto]

```json
{
  "success": true,
  "data": {
    "creatorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "bioPageUrl": "bio.re/johndoe"
  }
}
```

| Field        | Type          | Notes                                                                |
| ------------ | ------------- | -------------------------------------------------------------------- |
| `creatorId`  | string (UUID) | `CreatorProfile.id` — pass to all `/creators/:creatorId/*` endpoints |
| `bioPageUrl` | string        | `bio.re/<resolved-username>` — render as the public bio link         |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                     | Reason                                                                             |
| ----- | -------------------------------------- | ---------------------------------------------------------------------------------- |
| `400` | `creator.upgrade.username_required`    | Body has no `username` AND `User.username` is null                                 |
| `400` | (DTO validation)                       | `username` regex / length fail; `displayName > 100`; `bio > 500`                   |
| `401` | (guard)                                | Missing / invalid bearer token                                                     |
| `404` | `creator.upgrade.user_not_found`       | Token decoded but user row missing                                                 |
| `409` | `creator.upgrade.already_creator`      | A `CreatorProfile` already exists for this user (also raised on Prisma P2002 race) |
| `409` | `creator.upgrade.username_unavailable` | Username matches a row in `ReservedUsername`                                       |
| `503` | `features.creator_upgrade_disabled`    | Admin kill switch `CREATOR_UPGRADE` is active                                      |

## Side effects [#side-effects]

1. Reject if `CreatorProfile` already exists for this user (`already_creator`).
2. Resolve `username`: from body (lowercased + trimmed) or fall back to `User.username`. If both are null → `username_required`.
3. Reject if username matches a `ReservedUsername` row.
4. **Inside one transaction** (atomic):
   * `CreatorProfile.create({ id: randomUUID(), userId, level: BRONZE, kycStatus: NOT_STARTED })`.
   * `BioPage.create({ id: randomUUID(), creatorId, bio: input.bio ?? user.displayName ?? '', templateId: input.themeId ?? null, published: true })`.
   * `User.update({ intent: CREATOR, [+ displayName if supplied, + username if changed] })`.
   * On Prisma `P2002` (concurrent upgrade race), throw `already_creator`.
5. Audit log: `[creator] Upgraded user {userId} → creator {creatorId}`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/creators/upgrade \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "displayName": "Jane Doe",
        "bio": "Designer & creator",
        "username": "janedoe"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type UpgradeInput = {
      displayName?: string;
      bio?: string;
      themeId?: string;
      username?: string; // required if User.username is null
    };

    type UpgradeResponse = {
      creatorId: string;
      bioPageUrl: string;
    };

    async function upgradeToCreator(accessToken: string, input: UpgradeInput): Promise<UpgradeResponse> {
      const res = await fetch('https://api.bio.re/api/v1/creators/upgrade', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Upgrade failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useUpgradeToCreator() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (input: UpgradeInput) => {
          const res = await fetch('/api/v1/creators/upgrade', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Upgrade failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as UpgradeResponse;
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['users', 'profile'] });
          qc.invalidateQueries({ queryKey: ['auth', 'me'] });
          qc.invalidateQueries({ queryKey: ['creators', 'profile'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/upgrade', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source                | Path                                                                   | Lines                                                                                                                                           |
| --------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Controller            | `apps/api-core/src/modules/creator/creator.controller.ts`              | `39–50` (`upgradeToCreator`)                                                                                                                    |
| DTO (request)         | `apps/api-core/src/modules/creator/dto/creator.dto.ts`                 | `5–19` (`OnboardingDto`)                                                                                                                        |
| DTO (response)        | `apps/api-core/src/modules/creator/dto/creator-client-response.dto.ts` | `7–13` (`UpgradeToCreatorResponseDto`)                                                                                                          |
| Service               | `apps/api-core/src/modules/creator/creator.service.ts`                 | `120–183` (`upgradeToCreator`)                                                                                                                  |
| Kill switch decorator | `apps/api-core/src/common/guards/kill-switch.guard.ts`                 | `RequireKillSwitch('CREATOR_UPGRADE')`                                                                                                          |
| Prisma models         | `packages/prisma/prisma/schema.prisma`                                 | `CreatorProfile`, `BioPage`, `User.intent` (`UserIntent.CREATOR`), `ReservedUsername`, `enum CreatorLevel.BRONZE`, `enum KycStatus.NOT_STARTED` |


# Set Vacation Mode (/docs/creator/vacation-update)



`PATCH /api/v1/creators/:creatorId/vacation` — 🔑 **Bearer** · Rate limit: **30 req / hour**

Toggles `CreatorProfile.vacationMode` and updates the optional `vacationStart` / `vacationEnd` window. Atomically syncs the canonical `creatorStatus` enum: `ACTIVE → VACATION` when enabling, `VACATION → ACTIVE&#x60; when disabling. **`SUSPENDED` / `BANNED` / `DEACTIVATED` accounts are protected** — the status enum is left untouched (only the legacy `vacationMode` boolean updates).



<Callout type="warn">
  **Status protection is a safety guard**, not a feature gap. A vacation toggle can never accidentally un-suspend or un-ban an account. If you're seeing `vacationMode: true` while `creatorStatus !== 'VACATION'`, the account is in a moderated state — direct the user to support, not to a vacation toggle.
</Callout>

<Callout type="info">
  **Public-render impact**: while `vacationMode: true`, the public bio page (`GET /bio/:username`) returns `dmActive: false` (computed as `dmActive && !vacationMode`) regardless of the raw `dmActive` flag. The bio still renders — only the DM accept-state flips off.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param       | Type          | Validation      | Notes                                                       |
| ----------- | ------------- | --------------- | ----------------------------------------------------------- |
| `creatorId` | string (UUID) | `ParseUUIDPipe` | Must match the bearer's `CreatorProfile.id` (otherwise 403) |

### Body — `SetVacationDto` [#body--setvacationdto]

| Field       | Type              | Required | Validation       | Notes                                                                                     |
| ----------- | ----------------- | -------- | ---------------- | ----------------------------------------------------------------------------------------- |
| `enabled`   | boolean           | ✓        | `IsBoolean()`    | `true` to enter vacation mode, `false` to exit                                            |
| `startDate` | string (ISO 8601) | optional | `IsDateString()` | Defaults to `now()` when `enabled: true` and not supplied                                 |
| `endDate`   | string (ISO 8601) | optional | `IsDateString()` | Open-ended (`null`) when not supplied. Must be **after** `startDate` (when both present). |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                                                                                            |
| --------- | ------- | ------------------------------------------------------------------------------------------------ |
| `success` | boolean | Always `true` on 200. Re-fetch via `GET /creators/:creatorId/vacation` for the post-write state. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                    | Reason                                                             |
| ----- | ------------------------------------- | ------------------------------------------------------------------ |
| `400` | `creator.vacation.invalid_date_range` | `enabled: true` AND both dates supplied AND `endDate <= startDate` |
| `400` | (DTO validation)                      | `enabled` missing; date strings malformed                          |
| `401` | (guard)                               | Missing / invalid bearer token                                     |
| `403` | (`verifyCreatorOwnership`)            | `creatorId` does not belong to the bearer's user                   |
| `429` | (throttle)                            | Rate limit exceeded (30 req/hour)                                  |

## Side effects [#side-effects]

1. **Ownership check** — `verifyCreatorOwnership(creatorId, userId)` → 403 on mismatch.
2. **Date range validation** — when `enabled: true` AND both dates present AND `endDate <= startDate` → throw `invalid_date_range`.
3. Read current `creatorStatus`. Compute the safe transition:
   * `enabled: true AND status === ACTIVE` → flip to `VACATION`.
   * `enabled: false AND status === VACATION` → flip to `ACTIVE`.
   * **Any other status** (`SUSPENDED` / `BANNED` / `DEACTIVATED`) → status stays unchanged.
4. **Single atomic update** of `CreatorProfile`:
   * `vacationMode = enabled`.
   * `vacationStart = enabled ? (startDate ?? now()) : null`.
   * `vacationEnd = enabled ? (endDate ?? null) : null`.
   * `creatorStatus` written **only** for the safe ACTIVE↔VACATION transitions above.
5. Audit log: `[vacation] Enabled/Disabled for creator {id} (status→VACATION | status unchanged — protected)`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X PATCH https://api.bio.re/api/v1/creators/c1a2b3c4-d5e6-7890-abcd-ef1234567890/vacation \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "enabled": true,
        "startDate": "2026-07-01T00:00:00Z",
        "endDate": "2026-07-15T00:00:00Z"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type SetVacationInput = {
      enabled: boolean;
      startDate?: string;
      endDate?: string;
    };

    async function setVacationMode(accessToken: string, creatorId: string, input: SetVacationInput): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/creators/${creatorId}/vacation`, {
        method: 'PATCH',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Vacation update failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useSetVacationMode(creatorId: string) {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (input: SetVacationInput) => {
          const res = await fetch(`/api/v1/creators/${creatorId}/vacation`, {
            method: 'PATCH',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Vacation update failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['creators', creatorId, 'vacation'] });
          // creatorStatus may have flipped — refresh profile views
          qc.invalidateQueries({ queryKey: ['creators', 'profile'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/{creatorId}/vacation', method: 'patch' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                          | Lines                                                                                                                                              |
| -------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`     | `237–252` (`setVacation`)                                                                                                                          |
| DTO (request)  | `apps/api-core/src/modules/creator/dto/creator-social.dto.ts` | `40–49` (`SetVacationDto`)                                                                                                                         |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts`         | `SuccessOnlyResponseDto`                                                                                                                           |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`        | `582–613` (`setVacationMode` — handles status protection)                                                                                          |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                        | `CreatorProfile.vacationMode`, `CreatorProfile.vacationStart`, `CreatorProfile.vacationEnd`, `CreatorProfile.creatorStatus` (`enum CreatorStatus`) |


# Get Vacation Status (/docs/creator/vacation)



`GET /api/v1/creators/:creatorId/vacation` — 🔑 **Bearer**

Returns `vacationMode` (boolean) plus the optional `vacationStart` / `vacationEnd` timestamps. Ownership-checked — `creatorId` must match the bearer's `CreatorProfile.id`.



<Callout type="info">
  The `creatorStatus` enum on `CreatorProfile` is the canonical source of truth (`ACTIVE` / `VACATION` / `SUSPENDED` / `BANNED` / `DEACTIVATED`). `vacationMode` is a legacy boolean mirror that this endpoint returns directly. The two are kept in sync server-side; for client display, prefer `creatorStatus` from `GET /creators/profile` and use this endpoint only when you need the start/end window.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param       | Type          | Validation      | Notes                                                       |
| ----------- | ------------- | --------------- | ----------------------------------------------------------- |
| `creatorId` | string (UUID) | `ParseUUIDPipe` | Must match the bearer's `CreatorProfile.id` (otherwise 403) |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<VacationStatusResponseDto>` [#200-ok--apiresponseofvacationstatusresponsedto]

```json
{
  "success": true,
  "data": {
    "vacationMode": true,
    "vacationStart": "2026-07-01T00:00:00.000Z",
    "vacationEnd": "2026-07-15T00:00:00.000Z"
  }
}
```

| Field           | Type                      | Notes                                                                                                                 |
| --------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `vacationMode`  | boolean                   | Mirror of `CreatorProfile.vacationMode`                                                                               |
| `vacationStart` | string (ISO 8601) \| null | `null` when vacation is off OR enabled-without-explicit-start (server defaults to `now()` when enabled with no start) |
| `vacationEnd`   | string (ISO 8601) \| null | `null` when vacation is off OR open-ended                                                                             |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`           | Reason                                           |
| ----- | ---------------------------- | ------------------------------------------------ |
| `400` | (validation)                 | `creatorId` not a valid UUID                     |
| `401` | (guard)                      | Missing / invalid bearer token                   |
| `403` | (`verifyCreatorOwnership`)   | `creatorId` does not belong to the bearer's user |
| `404` | `creator.vacation.not_found` | `CreatorProfile` row missing                     |

## Side effects [#side-effects]

1. **Ownership check** — `verifyCreatorOwnership(creatorId, userId)` → 403 on mismatch.
2. `prisma.creatorProfile.findUnique({ where: { id: creatorId }, select: { vacationMode, vacationStart, vacationEnd } })`.
3. Throw `not_found` if missing.
4. Return the row. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/creators/c1a2b3c4-d5e6-7890-abcd-ef1234567890/vacation \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type VacationStatus = {
      vacationMode: boolean;
      vacationStart: string | null;
      vacationEnd: string | null;
    };

    async function getVacationStatus(accessToken: string, creatorId: string): Promise<VacationStatus> {
      const res = await fetch(`https://api.bio.re/api/v1/creators/${creatorId}/vacation`, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Vacation status fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const creatorKeys = {
      vacation: (creatorId: string) => ['creators', creatorId, 'vacation'] as const,
    };

    export function useVacationStatus(creatorId: string) {
      return useQuery({
        queryKey: creatorKeys.vacation(creatorId),
        queryFn: async () => {
          const res = await fetch(`/api/v1/creators/${creatorId}/vacation`);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Vacation status fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as VacationStatus;
        },
        enabled: Boolean(creatorId),
        staleTime: 30_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/{creatorId}/vacation', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                                                                                          |
| -------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/creator/creator.controller.ts`              | `227–235` (`getVacation`)                                                                                                                      |
| DTO (response) | `apps/api-core/src/modules/creator/dto/creator-client-response.dto.ts` | `475–484` (`VacationStatusResponseDto`)                                                                                                        |
| Service        | `apps/api-core/src/modules/creator/creator.service.ts`                 | `618–625` (`getVacationStatus`)                                                                                                                |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                                 | `CreatorProfile.vacationMode`, `CreatorProfile.vacationStart`, `CreatorProfile.vacationEnd`, `CreatorProfile.creatorStatus` (canonical source) |


# Creator Device Breakdown (/docs/creator-analytics/devices)



`GET /api/v1/creators/analytics/devices` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Returns all device types observed for sessions on the creator's bio page within the window — typically `mobile`, `desktop`, `tablet`, plus `unknown` for sessions where UA parsing didn't land on a definite type. &#x2A;*No `LIMIT`** — all distinct buckets are returned (typically 3-4 rows).



<Callout type="info">
  **Device value comes from server-side UA parse.** Set at session-create time by `UAParser` on the request `User-Agent`: `'mobile'` / `'tablet'` / fallback `'desktop'`. Sessions where parsing yielded no device type are `null`, and the SQL `COALESCE(device, 'unknown')` puts them in an `"unknown"` bucket.
</Callout>

<Callout type="info">
  **No `LIMIT` and no top-N cap.** The SQL just `GROUP BY device ORDER BY count DESC` — every distinct device value lands in the response. In practice this is 3-4 rows, but if a future UA parse introduces new buckets they'll show up here.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param  | Type    | Default | Notes                             |
| ------ | ------- | ------- | --------------------------------- |
| `days` | integer | `30`    | Lookback window. Capped at `365`. |

### Headers [#headers]

| Header                                | Required | Notes           |
| ------------------------------------- | -------- | --------------- |
| `Authorization: Bearer <accessToken>` | ✓        | `JwtAuthGuard`. |

## Response [#response]

### `200 OK` — `ApiResponseOf<CreatorDevicesDto>` [#200-ok--apiresponseofcreatordevicesdto]

```json
{
  "success": true,
  "data": {
    "segments": [
      { "name": "mobile",  "count": 1200, "percentage": 67 },
      { "name": "desktop", "count": 480,  "percentage": 27 },
      { "name": "tablet",  "count": 90,   "percentage": 5 },
      { "name": "unknown", "count": 30,   "percentage": 2 }
    ]
  }
}
```

### Item fields (`segments[]`) [#item-fields-segments]

| Field        | Type   | Notes                                                      |
| ------------ | ------ | ---------------------------------------------------------- |
| `name`       | string | Device type — `mobile` / `tablet` / `desktop` / `unknown`. |
| `count`      | number | Session count.                                             |
| `percentage` | number | Whole-number percentage of total.                          |

### Errors [#errors]

Same as [overview](/docs/creator-analytics/overview#errors).

## Side effects [#side-effects]

1. `JwtAuthGuard` + `ThrottleGuard`.
2. `getBioPageId(userId)`.
3. `analyticsDb.$queryRaw`:
   ```sql
   SELECT COALESCE(device, 'unknown') as name,
          COUNT(*)::int as count
   FROM "AnalyticsSession"
   WHERE "bioPageId" = $bioPageId::uuid
     AND "startedAt" >= $since
   GROUP BY device
   ORDER BY count DESC
   ```
4. Compute `percentage` per row; return.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/creators/analytics/devices?days=30' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type DeviceSegment = { name: string; count: number; percentage: number };

    async function getDevices(accessToken: string, days = 30): Promise<{ segments: DeviceSegment[] }> {
      const res = await fetch(
        `https://api.bio.re/api/v1/creators/analytics/devices?days=${days}`,
        { headers: { Authorization: `Bearer ${accessToken}` } },
      );
      const json = await res.json();
      if (!res.ok || !json.success) throw new Error(json?.error?.message ?? 'Failed');
      return json.data;
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/analytics/devices', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                       | Lines                                                                              |
| -------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/analytics/creator-analytics.controller.ts`      | `100–116` (`devices`)                                                              |
| DTO (response) | `apps/api-core/src/modules/analytics/dto/analytics-client-response.dto.ts` | `129–132` (`CreatorDevicesDto`), `116–125` (item shape)                            |
| Prisma model   | `packages/prisma-analytics/prisma/schema.prisma`                           | `AnalyticsSession.device` (line `72`), index `@@index([device, startedAt])` (`94`) |


# Export Creator Analytics (CSV) (/docs/creator-analytics/export)



`GET /api/v1/creators/analytics/export` — 🔑 **Bearer** · Rate limit: **60 req / minute** · `Content-Type: text/csv`

Returns a CSV file derived from one of three other endpoints — pick via `?type=overview` / `?type=traffic` / `?type=links`. The body **is the raw CSV** (not JSON-wrapped) and the response carries `Content-Disposition: attachment; filename=biore-analytics-<type>-<YYYY-MM-DD>.csv` so a browser will download it.



<Callout type="info">
  **`type` is one of three.** Only `overview`, `traffic`, `links` are supported. Anything else returns a CSV body of `error\nInvalid export type. Use: overview, traffic, or links.` (still `200`, still `text/csv`). Validate client-side before calling.
</Callout>

<Callout type="info">
  **Internally re-uses the same JSON endpoints.** The export handler calls `this.overview(userId, days)`, `this.traffic(userId, days)`, or `this.links(userId, days)` and serializes the result. So the data is the same as the JSON endpoints — only the wire format and the field flattening differ.
</Callout>

<Callout type="warn">
  **CSV injection is mitigated server-side.** Every value runs through `sanitizeCSVValue`: leading `=`, `+`, `-`, `@`, `\t`, `\r` get prefixed with `'` (single quote) so spreadsheet apps don't parse the cell as a formula. Double quotes are escaped (`""`); cells containing commas, quotes, or newlines are wrapped in double quotes. **Do not** double-sanitize on the client.
</Callout>

<Callout type="warn">
  **Filename has the current UTC date, not the window range.** The suffix is `new Date().toISOString().slice(0, 10)` — today's date, not "from-X-to-Y." If you save several exports the same day they'll collide; rename client-side if you need to disambiguate.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param  | Type    | Required                | Notes                                                             |
| ------ | ------- | ----------------------- | ----------------------------------------------------------------- |
| `type` | enum    | ✓                       | `overview` / `traffic` / `links`. Anything else → error CSV body. |
| `days` | integer | optional (default `30`) | Lookback window. Capped at `365`.                                 |

### Headers [#headers]

| Header                                | Required | Notes           |
| ------------------------------------- | -------- | --------------- |
| `Authorization: Bearer <accessToken>` | ✓        | `JwtAuthGuard`. |

## Response [#response]

### `200 OK` — `text/csv` [#200-ok--textcsv]

**Important: this endpoint does NOT return the JSON envelope.** The body is raw CSV bytes. Use `res.text()` (not `res.json()`).

| Header                | Value                                                          |
| --------------------- | -------------------------------------------------------------- |
| `Content-Type`        | `text/csv`                                                     |
| `Content-Disposition` | `attachment; filename=biore-analytics-<type>-<YYYY-MM-DD>.csv` |

### CSV shapes [#csv-shapes]

**`?type=overview`** — 5 rows, two columns:

```csv
metric,value
total_views,4200
unique_visitors,1800
total_clicks,320
ctr,7.62
days,30
```

**`?type=traffic`** — header + one row per traffic source:

```csv
source,visits,percentage
instagram.com,600,35
direct,280,16
youtube.com,150,9
```

**`?type=links`** — header + one row per link with clicks:

```csv
id,title,url,clicks,ctr
link-uuid-1,My Portfolio,https://example.com,120,4.8
link-uuid-deleted,Unknown,,6,0.24
```

**Invalid `type`** — single error row, still `200 OK`:

```csv
error
Invalid export type. Use: overview, traffic, or links.
```

### Errors [#errors]

| HTTP  | Reason                                                                                                                 |
| ----- | ---------------------------------------------------------------------------------------------------------------------- |
| `401` | Missing / invalid bearer token.                                                                                        |
| `404` | `error.creator.not_found` / `error.creator.bio_not_found` (raised inside the underlying overview/traffic/links calls). |
| `429` | Throttle.                                                                                                              |

There is **no** `400` for invalid `type` — instead the body becomes the error CSV described above.

## Side effects [#side-effects]

1. `JwtAuthGuard` + `ThrottleGuard`.
2. Compute `d = Math.min(parseInt(days ?? '30'), 365)`.
3. Switch on `type`:
   * `overview` → call `this.overview(userId, String(d))` → 5-row metric/value CSV.
   * `traffic` → call `this.traffic(userId, String(d))` → header + per-source rows.
   * `links` → call `this.links(userId, String(d))` → header + per-link rows.
   * Anything else → static `error\nInvalid export type. ...\n` body.
4. Run every value through `sanitizeCSVValue` (formula-prefix, quote-escape, comma/newline-wrap).
5. `res.setHeader('Content-Disposition', ...)`; `res.send(csv)` (raw text body).

## Code samples [#code-samples]



<Tabs items="['curl (download)', 'TypeScript fetch (download to disk)', 'Browser anchor click']">
  <Tab value="curl (download)">
    ```bash
    # Saves the file using the server-suggested filename
    curl -OJ \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      'https://api.bio.re/api/v1/creators/analytics/export?type=overview&days=30'
    ```
  </Tab>

  <Tab value="TypeScript fetch (download to disk)">
    ```ts
    async function exportCsv(
      accessToken: string,
      type: 'overview' | 'traffic' | 'links',
      days = 30,
    ): Promise<{ csv: string; filename: string }> {
      const res = await fetch(
        `https://api.bio.re/api/v1/creators/analytics/export?type=${type}&days=${days}`,
        { headers: { Authorization: `Bearer ${accessToken}` } },
      );
      if (!res.ok) throw new Error(`Export failed: ${res.status}`);

      const csv = await res.text(); // NOT .json() — body is raw CSV
      const dispo = res.headers.get('Content-Disposition') ?? '';
      const match = /filename=([^;]+)/.exec(dispo);
      const filename = match?.[1]?.trim() ?? `biore-analytics-${type}.csv`;
      return { csv, filename };
    }
    ```
  </Tab>

  <Tab value="Browser anchor click">
    ```ts
    async function downloadExport(
      type: 'overview' | 'traffic' | 'links',
      days = 30,
    ) {
      const res = await fetch(
        `/api/v1/creators/analytics/export?type=${type}&days=${days}`,
      );
      if (!res.ok) return;

      const blob = await res.blob();
      const url = URL.createObjectURL(blob);
      const a = document.createElement('a');
      a.href = url;
      a.download = `biore-analytics-${type}-${new Date().toISOString().slice(0, 10)}.csv`;
      a.click();
      URL.revokeObjectURL(url);
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/analytics/export', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source           | Path                                                                  | Lines                                                                                       |
| ---------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Controller       | `apps/api-core/src/modules/analytics/creator-analytics.controller.ts` | `206–246` (`exportAnalytics` — type switch, sanitization, attachment header)                |
| CSV sanitizer    | `apps/api-core/src/common/utils/sanitize-csv.ts`                      | `6–25` (`sanitizeCSVValue` — formula prefix `'`, double-quote escaping, comma/newline wrap) |
| Re-used handlers | `apps/api-core/src/modules/analytics/creator-analytics.controller.ts` | `45–62` (`overview`), `64–80` (`traffic`), `165–204` (`links`)                              |


# Creator Geo Distribution (/docs/creator-analytics/geo)



`GET /api/v1/creators/analytics/geo` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Top 20 countries by session count for the creator's bio page. The `country` value was set at session-create time from a GeoIP lookup on the request IP (the IP itself is **never** stored — see [Create Analytics Session](/docs/analytics/session-create#side-effects)).



<Callout type="info">
  **`"Unknown"` for sessions with no country.** GeoIP can fail (private IPs in dev, blocked geo db, etc.) — those sessions have `country = null`, and the SQL `COALESCE(country, 'Unknown')` collapses them into a single `"Unknown"` bucket. There's no separate null-vs-empty distinction in the response.
</Callout>

<Callout type="info">
  **Top 20 only, percentage rounded to whole numbers.** Same ranking + rounding contract as [traffic sources](/docs/creator-analytics/traffic) — `LIMIT 20`, `ORDER BY visits DESC`, `percentage = Math.round((visits / total) * 100)`.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param  | Type    | Default | Notes                             |
| ------ | ------- | ------- | --------------------------------- |
| `days` | integer | `30`    | Lookback window. Capped at `365`. |

### Headers [#headers]

| Header                                | Required | Notes           |
| ------------------------------------- | -------- | --------------- |
| `Authorization: Bearer <accessToken>` | ✓        | `JwtAuthGuard`. |

## Response [#response]

### `200 OK` — `ApiResponseOf<CreatorGeoDto>` [#200-ok--apiresponseofcreatorgeodto]

```json
{
  "success": true,
  "data": {
    "locations": [
      { "country": "Turkey",  "visits": 400, "percentage": 22 },
      { "country": "United States", "visits": 250, "percentage": 14 },
      { "country": "Unknown", "visits": 50,  "percentage": 3 }
    ]
  }
}
```

### Item fields (`locations[]`) [#item-fields-locations]

| Field        | Type   | Notes                                                                        |
| ------------ | ------ | ---------------------------------------------------------------------------- |
| `country`    | string | Country name from GeoIP (e.g. `"Turkey"`, `"United States"`) or `"Unknown"`. |
| `visits`     | number | Session count.                                                               |
| `percentage` | number | Whole-number percentage of total.                                            |

### Errors [#errors]

Same as [overview](/docs/creator-analytics/overview#errors).

## Side effects [#side-effects]

1. `JwtAuthGuard` + `ThrottleGuard`.
2. `getBioPageId(userId)`.
3. `analyticsDb.$queryRaw`:
   ```sql
   SELECT COALESCE(country, 'Unknown') as country,
          COUNT(*)::int as visits
   FROM "AnalyticsSession"
   WHERE "bioPageId" = $bioPageId::uuid
     AND "startedAt" >= $since
   GROUP BY country
   ORDER BY visits DESC
   LIMIT 20
   ```
4. Compute `percentage` per row; return.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/creators/analytics/geo?days=30' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type GeoLocation = { country: string; visits: number; percentage: number };

    async function getGeo(accessToken: string, days = 30): Promise<{ locations: GeoLocation[] }> {
      const res = await fetch(
        `https://api.bio.re/api/v1/creators/analytics/geo?days=${days}`,
        { headers: { Authorization: `Bearer ${accessToken}` } },
      );
      const json = await res.json();
      if (!res.ok || !json.success) throw new Error(json?.error?.message ?? 'Failed');
      return json.data;
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/analytics/geo', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                       | Lines                                                                                |
| -------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/analytics/creator-analytics.controller.ts`      | `82–98` (`geo`)                                                                      |
| DTO (response) | `apps/api-core/src/modules/analytics/dto/analytics-client-response.dto.ts` | `109–112` (`CreatorGeoDto`), `96–105` (item shape)                                   |
| Prisma model   | `packages/prisma-analytics/prisma/schema.prisma`                           | `AnalyticsSession.country` (line `67`), index `@@index([country, startedAt])` (`89`) |


# Creator Link Performance (/docs/creator-analytics/links)



`GET /api/v1/creators/analytics/links` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Returns every bio link that received at least one click in the window, with click count and click-through rate. **This endpoint joins across both databases** — the click counts come from the Analytics DB (`AnalyticsPageView WHERE linkClicked IS NOT NULL`), and the link titles/URLs come from the main DB (`prisma.bioLink.findMany`).



<Callout type="info">
  **Cross-DB join — done in application code, not SQL.** Step 1: aggregate clicks per `linkClicked` UUID in Analytics DB. Step 2: pull link details for the resulting ids from the main DB's `BioLink` table. Step 3: stitch them together in JS. There's no foreign-key constraint between the two databases.
</Callout>

<Callout type="warn">
  **Deleted/renamed links may appear as "Unknown".** When the main-DB lookup misses (link was deleted after the click was recorded), the row still appears in the response with `title: 'Unknown'` and `url: ''`. Don't filter these out server-side — historical click data has no other surface.
</Callout>

<Callout type="info">
  **`ctr` is per-link / per-bio-page-views.** `(link.clicks / totalViews) * 100`, 2-decimal. The denominator is **total bio-page pageviews in the window** (the same number `overview.totalViews` returns), not "views of the link." Two links can have CTRs that don't sum to the bio page's overall click-through rate from [`overview`](/docs/creator-analytics/overview).
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param  | Type    | Default | Notes                             |
| ------ | ------- | ------- | --------------------------------- |
| `days` | integer | `30`    | Lookback window. Capped at `365`. |

### Headers [#headers]

| Header                                | Required | Notes           |
| ------------------------------------- | -------- | --------------- |
| `Authorization: Bearer <accessToken>` | ✓        | `JwtAuthGuard`. |

## Response [#response]

### `200 OK` — `ApiResponseOf<CreatorLinksDto>` [#200-ok--apiresponseofcreatorlinksdto]

```json
{
  "success": true,
  "data": {
    "links": [
      {
        "id": "link-uuid-1",
        "title": "My Portfolio",
        "url": "https://example.com",
        "clicks": 120,
        "ctr": 4.8
      },
      {
        "id": "link-uuid-deleted",
        "title": "Unknown",
        "url": "",
        "clicks": 6,
        "ctr": 0.24
      }
    ],
    "totalViews": 2500
  }
}
```

### Top-level fields [#top-level-fields]

| Field        | Type   | Notes                                                                      |
| ------------ | ------ | -------------------------------------------------------------------------- |
| `links`      | array  | Sorted by `clicks DESC`. Empty when no link clicks happened in the window. |
| `totalViews` | number | Total pageviews of the bio page in the window. CTR denominator.            |

### Item fields (`links[]`) [#item-fields-links]

| Field    | Type          | Notes                                                                                                  |
| -------- | ------------- | ------------------------------------------------------------------------------------------------------ |
| `id`     | string (UUID) | `BioLink.id` from main DB. May reference a now-deleted link (see warn).                                |
| `title`  | string        | `BioLink.title` or `"Unknown"` when the link no longer exists.                                         |
| `url`    | string        | `BioLink.url` or `""` (empty string) when the link no longer exists.                                   |
| `clicks` | number        | Pageviews where `linkClicked = link.id`.                                                               |
| `ctr`    | number        | `Math.round((clicks / totalViews) * 10000) / 100` — 2-decimal percentage. `0` when `totalViews === 0`. |

### Errors [#errors]

Same as [overview](/docs/creator-analytics/overview#errors).

## Side effects [#side-effects]

1. `JwtAuthGuard` + `ThrottleGuard`.
2. `getBioPageId(userId)`.
3. **Step 1 (Analytics DB)** — click counts grouped by link id:
   ```sql
   SELECT "linkClicked" as link_id, COUNT(*)::int as clicks
   FROM "AnalyticsPageView"
   WHERE "bioPageId" = $bioPageId::uuid
     AND "linkClicked" IS NOT NULL
     AND "enteredAt" >= $since
   GROUP BY "linkClicked"
   ORDER BY clicks DESC
   ```
4. **Step 2 (main DB)** — fetch link metadata:
   * `prisma.bioLink.findMany({ where: { id: { in: linkIds } }, select: { id, title, url } })`.
   * Only runs if Step 1 returned at least one row.
5. **Step 3 (Analytics DB)** — total views denominator:
   * `analyticsDb.analyticsPageView.count({ where: { bioPageId, enteredAt: { gte: since } } })`.
6. **Step 4 (memory)** — stitch the two lists by `id`. Missing main-DB rows fall back to `{ title: 'Unknown', url: '' }`.
7. Return `{ links, totalViews }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/creators/analytics/links?days=30' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type LinkPerf = { id: string; title: string; url: string; clicks: number; ctr: number };

    async function getLinks(
      accessToken: string,
      days = 30,
    ): Promise<{ links: LinkPerf[]; totalViews: number }> {
      const res = await fetch(
        `https://api.bio.re/api/v1/creators/analytics/links?days=${days}`,
        { headers: { Authorization: `Bearer ${accessToken}` } },
      );
      const json = await res.json();
      if (!res.ok || !json.success) throw new Error(json?.error?.message ?? 'Failed');
      return json.data;
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/analytics/links', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source                   | Path                                                                       | Lines                                                                     |
| ------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Controller               | `apps/api-core/src/modules/analytics/creator-analytics.controller.ts`      | `165–204` (`links` — cross-DB join in JS)                                 |
| DTO (response)           | `apps/api-core/src/modules/analytics/dto/analytics-client-response.dto.ts` | `194–200` (`CreatorLinksDto`), `175–190` (item shape)                     |
| Prisma model (main)      | `packages/prisma/prisma/schema.prisma`                                     | `BioLink.id / title / url` (lines `455–474`)                              |
| Prisma model (analytics) | `packages/prisma-analytics/prisma/schema.prisma`                           | `AnalyticsPageView.linkClicked / bioPageId / enteredAt` (lines `109–111`) |


# Creator Analytics Overview (/docs/creator-analytics/overview)



`GET /api/v1/creators/analytics/overview` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Four headline metrics for the current creator's bio page over a configurable window. The endpoint resolves the bio page from the JWT subject — there is **no creator/userId path or query parameter**, so a creator can only ever see their own numbers.



<Callout type="info">
  **Owner-scoped via JWT, no cross-creator reads.** All eight creator-analytics endpoints follow the same pattern: `getBioPageId(userId)` looks up `CreatorProfile` then `BioPage` from the main DB, throws `404` if either is missing. The Analytics DB queries that follow always filter by that resolved `bioPageId`. &#x2A;*There is no way to spoof another creator's analytics through this controller.**
</Callout>

<Callout type="info">
  **`uniqueVisitors` counts distinct hashed visitor ids.** The visitor key was SHA256-hashed at session-create time (see [Create Analytics Session](/docs/analytics/session-create)) — the count here is `groupBy(visitorId)` over those hashes, so it's a privacy-preserving distinct-count, not a raw distinct user count.
</Callout>

<Callout type="warn">
  **`days` is capped at 365.** `Math.min(parseInt(days ?? '30'), 365)` — anything larger is silently clamped. Out-of-range strings (`?days=abc`) become `NaN` then default to `30` (since `Math.min(NaN, 365) === NaN` falls through to default). Prefer to send a clean integer.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param  | Type    | Default | Notes                                          |
| ------ | ------- | ------- | ---------------------------------------------- |
| `days` | integer | `30`    | Lookback window in days. Server caps at `365`. |

### Headers [#headers]

| Header                                | Required | Notes                                                          |
| ------------------------------------- | -------- | -------------------------------------------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | `JwtAuthGuard` (explicit on this controller, not just global). |

## Response [#response]

### `200 OK` — `ApiResponseOf<CreatorAnalyticsOverviewDto>` [#200-ok--apiresponseofcreatoranalyticsoverviewdto]

```json
{
  "success": true,
  "data": {
    "totalViews": 4200,
    "uniqueVisitors": 1800,
    "totalClicks": 320,
    "ctr": 7.62,
    "days": 30
  }
}
```

| Field            | Type   | Notes                                                                                                                                  |
| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `totalViews`     | number | `count(AnalyticsPageView WHERE bioPageId = ? AND enteredAt >= since)`. Counts every pageview, including link-click pageviews.          |
| `uniqueVisitors` | number | Distinct hashed `visitorId` over `AnalyticsSession` rows in the window.                                                                |
| `totalClicks`    | number | `count(AnalyticsPageView WHERE linkClicked IS NOT NULL ...)`. A view counts as a "click" when the URL navigation came from a bio link. |
| `ctr`            | number | `Math.round((totalClicks / totalViews) * 10000) / 100` — 2-decimal percentage. `0` when there are no views.                            |
| `days`           | number | Echo of the effective window (after defaulting + capping).                                                                             |

### Errors [#errors]

| HTTP  | Code / `i18nKey`              | Reason                                          |
| ----- | ----------------------------- | ----------------------------------------------- |
| `401` | (guard)                       | Missing / invalid bearer token.                 |
| `404` | `error.creator.not_found`     | The authenticated user has no `CreatorProfile`. |
| `404` | `error.creator.bio_not_found` | Creator exists but has no `BioPage`.            |
| `429` | Throttle                      | Over 60 req/min from this IP.                   |

## Side effects [#side-effects]

1. `JwtAuthGuard`. `ThrottleGuard` (60 req / 60s).
2. `getBioPageId(userId)` — main DB:
   * `prisma.creatorProfile.findFirst({ where: { userId }, select: { id } })` → 404 if missing.
   * `prisma.bioPage.findFirst({ where: { creatorId }, select: { id } })` → 404 if missing.
3. Compute `since = new Date(Date.now() - d * 86400000)`.
4. **Three parallel queries against the Analytics DB**:
   * `analyticsDb.analyticsPageView.count({ where: { bioPageId, enteredAt: { gte: since } } })`
   * `analyticsDb.analyticsSession.groupBy({ by: ['visitorId'], where: { bioPageId, startedAt: { gte: since } } }).then(r => r.length)` — distinct visitors
   * `analyticsDb.analyticsPageView.count({ where: { bioPageId, linkClicked: { not: null }, enteredAt: { gte: since } } })`
5. Compute `ctr` and return. &#x2A;*No DB writes.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/creators/analytics/overview?days=30' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type CreatorOverview = {
      totalViews: number;
      uniqueVisitors: number;
      totalClicks: number;
      ctr: number;        // 2-decimal percentage
      days: number;
    };

    async function getOverview(
      accessToken: string,
      days = 30,
    ): Promise<CreatorOverview> {
      const res = await fetch(
        `https://api.bio.re/api/v1/creators/analytics/overview?days=${days}`,
        { headers: { Authorization: `Bearer ${accessToken}` } },
      );
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Overview failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const creatorAnalyticsKeys = {
      overview: (days: number) => ['creator-analytics', 'overview', days] as const,
    };

    export function useCreatorOverview(days = 30) {
      return useQuery({
        queryKey: creatorAnalyticsKeys.overview(days),
        queryFn: async () => {
          const res = await fetch(`/api/v1/creators/analytics/overview?days=${days}`);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Overview failed'), {
              code: json?.error?.code,
            });
          }
          return json.data as CreatorOverview;
        },
        staleTime: 5 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/analytics/overview', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source                   | Path                                                                       | Lines                                                                                                         |
| ------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Controller               | `apps/api-core/src/modules/analytics/creator-analytics.controller.ts`      | `23–28` (class), `45–62` (`overview`)                                                                         |
| Owner-scope helper       | `apps/api-core/src/modules/analytics/creator-analytics.controller.ts`      | `30–43` (`getBioPageId` — main DB lookups)                                                                    |
| DTO (response)           | `apps/api-core/src/modules/analytics/dto/analytics-client-response.dto.ts` | `57–72` (`CreatorAnalyticsOverviewDto`)                                                                       |
| Prisma model (main)      | `packages/prisma/prisma/schema.prisma`                                     | `CreatorProfile.userId` (`315–317`), `BioPage.creatorId` (`426–443`)                                          |
| Prisma model (analytics) | `packages/prisma-analytics/prisma/schema.prisma`                           | `AnalyticsSession.visitorId` (line `48`), `AnalyticsPageView.bioPageId / linkClicked / enteredAt` (`102–119`) |


# Creator Session Metrics (/docs/creator-analytics/sessions)



`GET /api/v1/creators/analytics/sessions` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Four headline session metrics. Use this for the dashboard "engagement" tile — bounces, attention time, and how many pages a typical visitor opens.



<Callout type="info">
  **`bounceRate` is integer percentage.** `Math.round((bounced / total) * 100)` — 0 decimals. A session is `bounced` until its second pageview lands (the [`POST /pageview`](/docs/analytics/pageview) atomic UPDATE flips the flag) — single-pageview visits are bounces.
</Callout>

<Callout type="warn">
  **`avgDuration` excludes zero-duration sessions.** The aggregate filters `where: { duration: { gt: 0 } }` — sessions that never received a heartbeat or pageleave (so still have `duration = 0`) are dropped before averaging. This biases the number upward vs a naïve `AVG(duration)`. Don't multiply `avgDuration * totalSessions` to get total time.
</Callout>

<Callout type="info">
  **`pagesPerSession` is rounded to 1 decimal.** `Math.round(avg * 10) / 10` — `2.5`, not `2.51`. `avgDuration` is rounded to whole seconds (`Math.round(avg)`).
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param  | Type    | Default | Notes                             |
| ------ | ------- | ------- | --------------------------------- |
| `days` | integer | `30`    | Lookback window. Capped at `365`. |

### Headers [#headers]

| Header                                | Required | Notes           |
| ------------------------------------- | -------- | --------------- |
| `Authorization: Bearer <accessToken>` | ✓        | `JwtAuthGuard`. |

## Response [#response]

### `200 OK` — `ApiResponseOf<CreatorSessionsDto>` [#200-ok--apiresponseofcreatorsessionsdto]

```json
{
  "success": true,
  "data": {
    "totalSessions": 1800,
    "bounceRate": 42,
    "avgDuration": 145,
    "pagesPerSession": 1.8
  }
}
```

| Field             | Type   | Notes                                                                                                                                        |
| ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `totalSessions`   | number | All sessions in the window for this bio page.                                                                                                |
| `bounceRate`      | number | Whole-number percentage of `totalSessions` that ended with `bounced = true` (i.e. had only one pageview).                                    |
| `avgDuration`     | number | Average session `duration` in seconds, rounded to integer, &#x2A;*only over sessions with `duration > 0`**. `0` when no qualifying sessions. |
| `pagesPerSession` | number | Average `pageViews` per session across **all** sessions, rounded to 1 decimal. `0` when no sessions.                                         |

### Errors [#errors]

Same as [overview](/docs/creator-analytics/overview#errors).

## Side effects [#side-effects]

1. `JwtAuthGuard` + `ThrottleGuard`.
2. `getBioPageId(userId)`.
3. **Four parallel queries against the Analytics DB**:
   * `count({ where: { bioPageId, startedAt: { gte: since } } })` → `total`.
   * `count({ where: { bioPageId, startedAt: { gte: since }, bounced: true } })` → `bounced`.
   * `aggregate({ where: { bioPageId, startedAt: { gte: since }, duration: { gt: 0 } }, _avg: { duration } })` → `avgDur`.
   * `aggregate({ where: { bioPageId, startedAt: { gte: since } }, _avg: { pageViews } })` → `avgPv`.
4. Compute the four metrics, round per the rules above, return.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/creators/analytics/sessions?days=30' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type SessionMetrics = {
      totalSessions: number;
      bounceRate: number;
      avgDuration: number;
      pagesPerSession: number;
    };

    async function getSessions(accessToken: string, days = 30): Promise<SessionMetrics> {
      const res = await fetch(
        `https://api.bio.re/api/v1/creators/analytics/sessions?days=${days}`,
        { headers: { Authorization: `Bearer ${accessToken}` } },
      );
      const json = await res.json();
      if (!res.ok || !json.success) throw new Error(json?.error?.message ?? 'Failed');
      return json.data;
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/analytics/sessions', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                       | Lines                                                                                                           |
| -------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/analytics/creator-analytics.controller.ts`      | `141–163` (`sessions`)                                                                                          |
| DTO (response) | `apps/api-core/src/modules/analytics/dto/analytics-client-response.dto.ts` | `159–171` (`CreatorSessionsDto`)                                                                                |
| Prisma model   | `packages/prisma-analytics/prisma/schema.prisma`                           | `AnalyticsSession.bounced / duration / pageViews` (lines `54–57`), index `@@index([bounced, startedAt])` (`92`) |


# Creator Traffic Sources (/docs/creator-analytics/traffic)



`GET /api/v1/creators/analytics/traffic` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Returns the top 15 referrer domains driving traffic to the creator's bio page, plus each one's share of total visits. `referrerDomain` was extracted at session-create time (`URL.hostname.replace('www.', '')`); sessions with no referrer or an unparseable one show up under `'direct'`.



<Callout type="info">
  **Always 15 rows max.** The SQL is `LIMIT 15` — there's no `?limit=` knob. If you need a longer tail, fall back to the admin `traffic-sources` endpoint or aggregate client-side from the [overview](/docs/creator-analytics/overview) + [trend](/docs/creator-analytics/trend) data.
</Callout>

<Callout type="info">
  **`direct` is the catch-all.** Any session with `referrer === null` or a referrer that didn't parse as a URL became `'direct'` at write-time. You'll always see it as a row when there's any direct traffic — there's no separate "unknown" bucket.
</Callout>

<Callout type="warn">
  **`percentage` is rounded to whole integers.** `Math.round((visits / total) * 100)` — no decimals. The sum across rows can drift a percent or two from 100 due to rounding; don't render it as "100% pie" without normalizing client-side.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param  | Type    | Default | Notes                             |
| ------ | ------- | ------- | --------------------------------- |
| `days` | integer | `30`    | Lookback window. Capped at `365`. |

### Headers [#headers]

| Header                                | Required | Notes           |
| ------------------------------------- | -------- | --------------- |
| `Authorization: Bearer <accessToken>` | ✓        | `JwtAuthGuard`. |

## Response [#response]

### `200 OK` — `ApiResponseOf<CreatorTrafficDto>` [#200-ok--apiresponseofcreatortrafficdto]

```json
{
  "success": true,
  "data": {
    "sources": [
      { "source": "instagram.com", "visits": 600, "percentage": 35 },
      { "source": "direct",        "visits": 280, "percentage": 16 },
      { "source": "youtube.com",   "visits": 150, "percentage": 9 }
    ]
  }
}
```

### Item fields (`sources[]`) [#item-fields-sources]

| Field        | Type   | Notes                                                                                         |
| ------------ | ------ | --------------------------------------------------------------------------------------------- |
| `source`     | string | Referrer domain (e.g. `"instagram.com"`) or `"direct"`.                                       |
| `visits`     | number | Session count where `referrerDomain` matched (or was null/unparseable, mapped to `"direct"`). |
| `percentage` | number | Whole-number percentage of total visits. Rows are sorted by `visits DESC`.                    |

### Errors [#errors]

Same as [overview](/docs/creator-analytics/overview#errors) — `401` / `404 error.creator.not_found` / `404 error.creator.bio_not_found` / `429`.

## Side effects [#side-effects]

1. `JwtAuthGuard` + `ThrottleGuard`.
2. `getBioPageId(userId)` (main DB → 404 if missing creator/bio page).
3. `analyticsDb.$queryRaw` (Analytics DB):
   ```sql
   SELECT COALESCE("referrerDomain", 'direct') as source,
          COUNT(*)::int as visits
   FROM "AnalyticsSession"
   WHERE "bioPageId" = $bioPageId::uuid
     AND "startedAt" >= $since
   GROUP BY "referrerDomain"
   ORDER BY visits DESC
   LIMIT 15
   ```
4. Compute `total = sum(visits)`, then map each row to add `percentage = Math.round((visits / total) * 100)`. `0` when total is zero.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/creators/analytics/traffic?days=30' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type TrafficSource = { source: string; visits: number; percentage: number };

    async function getTraffic(
      accessToken: string,
      days = 30,
    ): Promise<{ sources: TrafficSource[] }> {
      const res = await fetch(
        `https://api.bio.re/api/v1/creators/analytics/traffic?days=${days}`,
        { headers: { Authorization: `Bearer ${accessToken}` } },
      );
      const json = await res.json();
      if (!res.ok || !json.success) throw new Error(json?.error?.message ?? 'Failed');
      return json.data;
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/analytics/traffic', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                       | Lines                                                                                              |
| -------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/analytics/creator-analytics.controller.ts`      | `64–80` (`traffic`)                                                                                |
| DTO (response) | `apps/api-core/src/modules/analytics/dto/analytics-client-response.dto.ts` | `89–92` (`CreatorTrafficDto`), `76–85` (item shape)                                                |
| Prisma model   | `packages/prisma-analytics/prisma/schema.prisma`                           | `AnalyticsSession.referrerDomain` (line `59`), index `@@index([referrerDomain, startedAt])` (`91`) |


# Creator Daily Trend (/docs/creator-analytics/trend)



`GET /api/v1/creators/analytics/trend` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Daily time series of pageviews and link clicks for the creator's bio page. The bucketing is done server-side with Postgres `date_trunc('day', "enteredAt")`, so each row is a single calendar day in the database server's time zone.



<Callout type="warn">
  **Days with zero traffic are MISSING from the array.** The SQL `GROUP BY date_trunc('day', enteredAt)` only emits rows that actually have pageviews. To plot a continuous line/bar chart, **fill missing dates client-side** with `views: 0, clicks: 0`. Don't assume `daily.length === days`.
</Callout>

<Callout type="warn">
  **`day` is bucketed in the database server's time zone.** The grouping key is `date_trunc('day', "enteredAt")` without a timezone argument, so it uses the Postgres server's TZ. Two visits at `2026-04-30T23:30Z` and `2026-05-01T00:30Z` may or may not fall in the same day depending on server TZ. **Render `day` as a UTC date** in your client and accept that day boundaries follow the DB, not the user.
</Callout>

<Callout type="info">
  **`clicks` is filtered, not separately counted.** The SQL uses `COUNT(*) FILTER (WHERE "linkClicked" IS NOT NULL)` — same scan, same window, just a conditional aggregate. So `clicks ≤ views` always holds for the same row.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param  | Type    | Default | Notes                             |
| ------ | ------- | ------- | --------------------------------- |
| `days` | integer | `30`    | Lookback window. Capped at `365`. |

### Headers [#headers]

| Header                                | Required | Notes           |
| ------------------------------------- | -------- | --------------- |
| `Authorization: Bearer <accessToken>` | ✓        | `JwtAuthGuard`. |

## Response [#response]

### `200 OK` — `ApiResponseOf<CreatorTrendDto>` [#200-ok--apiresponseofcreatortrenddto]

```json
{
  "success": true,
  "data": {
    "days": 30,
    "daily": [
      { "day": "2026-04-01T00:00:00.000Z", "views": 145, "clicks": 12 },
      { "day": "2026-04-02T00:00:00.000Z", "views": 132, "clicks": 8 }
    ]
  }
}
```

### Top-level fields [#top-level-fields]

| Field   | Type   | Notes                                                        |
| ------- | ------ | ------------------------------------------------------------ |
| `days`  | number | Echo of the effective window after defaulting + capping.     |
| `daily` | array  | One row per calendar day **that had at least one pageview**. |

### Item fields (`daily[]`) [#item-fields-daily]

| Field    | Type              | Notes                                                                                     |
| -------- | ----------------- | ----------------------------------------------------------------------------------------- |
| `day`    | string (ISO 8601) | Postgres `date_trunc('day', enteredAt)` serialized — midnight of the day in DB server TZ. |
| `views`  | number            | Pageview count for that day.                                                              |
| `clicks` | number            | Subset of `views` where `linkClicked IS NOT NULL`.                                        |

### Errors [#errors]

Same as [overview](/docs/creator-analytics/overview#errors).

## Side effects [#side-effects]

1. `JwtAuthGuard` + `ThrottleGuard`.
2. `getBioPageId(userId)`.
3. `analyticsDb.$queryRaw`:
   ```sql
   SELECT
     date_trunc('day', "enteredAt") as day,
     COUNT(*)::int as views,
     COUNT(*) FILTER (WHERE "linkClicked" IS NOT NULL)::int as clicks
   FROM "AnalyticsPageView"
   WHERE "bioPageId" = $bioPageId::uuid
     AND "enteredAt" >= $since
   GROUP BY date_trunc('day', "enteredAt")
   ORDER BY day ASC
   ```
4. Return `{ days, daily }`. **No client-side gap-filling** — empty days are omitted.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch (with gap fill)']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/creators/analytics/trend?days=30' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch (with gap fill)">
    ```ts
    type DailyPoint = { day: string; views: number; clicks: number };

    async function getTrend(
      accessToken: string,
      days = 30,
    ): Promise<{ days: number; daily: DailyPoint[] }> {
      const res = await fetch(
        `https://api.bio.re/api/v1/creators/analytics/trend?days=${days}`,
        { headers: { Authorization: `Bearer ${accessToken}` } },
      );
      const json = await res.json();
      if (!res.ok || !json.success) throw new Error(json?.error?.message ?? 'Failed');
      return json.data;
    }

    // Server omits zero days — fill the gaps client-side for chart rendering.
    function fillGaps(daily: DailyPoint[], windowDays: number): DailyPoint[] {
      const map = new Map(daily.map(d => [d.day.slice(0, 10), d]));
      const out: DailyPoint[] = [];
      for (let i = windowDays - 1; i >= 0; i--) {
        const d = new Date(Date.now() - i * 86_400_000);
        const key = d.toISOString().slice(0, 10);
        out.push(map.get(key) ?? { day: `${key}T00:00:00.000Z`, views: 0, clicks: 0 });
      }
      return out;
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/creators/analytics/trend', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                       | Lines                                                                                                    |
| -------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/analytics/creator-analytics.controller.ts`      | `118–139` (`trend`)                                                                                      |
| DTO (response) | `apps/api-core/src/modules/analytics/dto/analytics-client-response.dto.ts` | `149–155` (`CreatorTrendDto`), `136–145` (item shape)                                                    |
| Prisma model   | `packages/prisma-analytics/prisma/schema.prisma`                           | `AnalyticsPageView.enteredAt / linkClicked` (`110–111`), index `@@index([bioPageId, enteredAt])` (`117`) |


# Get Translation Bundle (/docs/i18n/bundle)



`GET /api/v1/translations/:locale` — 🌐 **Public** · Rate limit: **60 req / minute**

Returns every APPROVED translation for `:locale` as a single flat key-value map. Keys are formatted `<namespace>.<key>` (e.g. `auth.login.title` or `common.button.save`); values are the raw translated strings. &#x2A;*DRAFT translations never leak through this endpoint.**



<Callout type="info">
  **Three-layer cache + 304 short-circuit.** L1 = in-process map (60s), L2 = Redis (5 min), L3 = HTTP CDN (`Cache-Control` header). On top of all that, the response carries an `ETag` of the form `"i18n-<locale>-<version>"`. Send the same value back in `If-None-Match` and the server returns `304 Not Modified` with no body — your existing bundle in client memory is still valid.
</Callout>

<Callout type="info">
  **Pin the version with `?v=N` to get a 1-year immutable cache.** When you read `versions[locale]` from `GET /locales`, pass the same number as `?v=N` here. If the server's current version matches, the response carries `Cache-Control: public, max-age=31536000, immutable` — the CDN and the browser will never re-validate this URL until you change `N`. Without `?v`, the server sends `public, max-age=60, stale-while-revalidate=300` (short cache + revalidation).
</Callout>

<Callout type="warn">
  **APPROVED-only filter.** The Prisma query is `where: { languageCode, status: 'APPROVED' }`. Translations in `DRAFT` status are excluded entirely — they exist only in the admin tooling. **A missing key does not throw**: clients should fall back to the default locale's value (or to the key itself) when a lookup misses.
</Callout>

<Callout type="warn">
  **Unknown locale returns an empty bundle, not `404`.** The server doesn't validate that `:locale` exists in the `Language` table — it just runs the WHERE clause and gets zero rows. If you `GET /api/v1/translations/zz`, you get `200 OK` with `{}` and a version of `0`. Validate locale codes client-side against `GET /locales` before issuing the bundle fetch.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param    | Type   | Required | Notes                                                                                                                   |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `locale` | string | ✓        | ISO 639-1 code from `GET /locales` (e.g. `en`, `tr`). Not validated server-side — unknown codes return an empty bundle. |

### Query parameters [#query-parameters]

| Param | Type    | Default | Notes                                                                                                                                                                                                                                    |
| ----- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `v`   | integer | —       | The expected version (from `versions[locale]` in `GET /locales`). When it matches the current server version, response gets the **1-year immutable** cache header instead of the short SWR header. Mismatch = ignored, short cache used. |

### Headers [#headers]

| Header          | Required | Notes                                                                                                |
| --------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `If-None-Match` | optional | Pass the previous response's `ETag` value verbatim. On match, the server returns `304` with no body. |

No body, no auth required.

## Response [#response]

### `200 OK` — `Record<string, string>` (flat map) [#200-ok--recordstring-string-flat-map]

The body is **not** wrapped in the standard `{ success, data }` envelope — this endpoint returns the bundle directly so it can be consumed by mobile clients and SSR layers without unwrap boilerplate.

```json
{
  "auth.login.title": "Sign in to your account",
  "auth.login.button": "Sign in",
  "common.button.save": "Save",
  "common.button.cancel": "Cancel",
  "errors.invalid_credentials": "Invalid email or password"
}
```

### `304 Not Modified` [#304-not-modified]

Returned when `If-None-Match` matches the current `ETag`. &#x2A;*No body.**

### Response headers (always) [#response-headers-always]

| Header          | Value                                                                                         | Notes                                                    |
| --------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `ETag`          | `"i18n-<locale>-<version>"`                                                                   | Use this on the next request as `If-None-Match`.         |
| `Cache-Control` | `public, max-age=31536000, immutable` **OR** `public, max-age=60, stale-while-revalidate=300` | Immutable variant only when `?v=N` was sent and matched. |

### Errors [#errors]

| HTTP  | Reason                                                                                  |
| ----- | --------------------------------------------------------------------------------------- |
| `429` | Rate limit exceeded (60 req/min — but you should hit the CDN for almost every request). |

No other documented error paths. Unknown `:locale` returns `200` + empty `{}`.

## Side effects [#side-effects]

1. `cache.getVersion(locale)` — reads `i18n:version:<locale>` from Redis. Returns `0` if Redis cache is unavailable.
2. Build ETag = `"i18n-<locale>-<version>"`. If `If-None-Match === ETag` → `res.status(304); return` (no body, no further work).
3. `translationService.getBundle(locale)` — multi-layer cache lookup:
   * L1 (in-process map, 60s TTL) → if hit, return.
   * L2 (Redis, key `i18n:bundle:<locale>`, 5 min TTL) → if hit, promote to L1, return.
   * On miss: `prisma.translation.findMany({ where: { languageCode: locale, status: 'APPROVED' }, include: { translationKey: { select: { namespace, key } } } })`.
4. Project to flat map: each row becomes `<namespace>.<key>: <value>`.
5. Write the map to L2 (Redis, 5 min) and L1 (60s).
6. Set `ETag` header. Set `Cache-Control` based on whether `?v=<currentVersion>` was sent (immutable) or not (60s + 300s SWR).
7. Return the bundle. &#x2A;*No DB writes.**

### Cache invalidation (write-side, not part of this endpoint) [#cache-invalidation-write-side-not-part-of-this-endpoint]

When an admin updates / approves / deletes a translation, `i18n-cache.service.ts:invalidateLocale(locale)` runs:

* Clear L1 entries for the locale.
* DELETE Redis L2 keys (`i18n:bundle:<locale>` plus every `i18n:bundle:<locale>:<namespace>`).
* INCR Redis `i18n:version:<locale>` — bumps the integer in `versions[locale]` returned by `GET /locales`.
* PUBLISH `{ locale }` to the `i18n:invalidate` channel — every other api-core instance subscribed to it clears its in-process L1 for that locale.

## Code samples [#code-samples]



<Tabs items="['curl (no version)', 'curl (version-pinned)', 'curl (conditional GET)', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl (no version)">
    ```bash
    curl -i https://api.bio.re/api/v1/translations/en
    # ETag: "i18n-en-42"
    # Cache-Control: public, max-age=60, stale-while-revalidate=300
    ```
  </Tab>

  <Tab value="curl (version-pinned)">
    ```bash
    # When you already know version=42 from GET /locales, lock the cache:
    curl -i 'https://api.bio.re/api/v1/translations/en?v=42'
    # ETag: "i18n-en-42"
    # Cache-Control: public, max-age=31536000, immutable
    ```
  </Tab>

  <Tab value="curl (conditional GET)">
    ```bash
    curl -i https://api.bio.re/api/v1/translations/en \
      -H 'If-None-Match: "i18n-en-42"'
    # HTTP/1.1 304 Not Modified  (no body)
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type TranslationBundle = Record<string, string>;

    async function getBundle(
      locale: string,
      opts?: { version?: number; ifNoneMatch?: string },
    ): Promise<{ bundle: TranslationBundle | null; etag: string | null; status: 200 | 304 }> {
      const url = new URL(`https://api.bio.re/api/v1/translations/${locale}`);
      if (opts?.version != null) url.searchParams.set('v', String(opts.version));

      const headers: Record<string, string> = {};
      if (opts?.ifNoneMatch) headers['If-None-Match'] = opts.ifNoneMatch;

      const res = await fetch(url, { headers });
      const etag = res.headers.get('ETag');

      if (res.status === 304) {
        return { bundle: null, etag, status: 304 };
      }
      if (!res.ok) {
        throw new Error(`Bundle fetch failed: ${res.status}`);
      }
      return { bundle: (await res.json()) as TranslationBundle, etag, status: 200 };
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    // Pair this hook with useLocales(). When versions[locale] changes upstream,
    // the queryKey changes too — TanStack treats it as a fresh cache entry.
    export function useTranslationBundle(locale: string, version: number) {
      return useQuery({
        queryKey: ['i18n', 'bundle', locale, version],
        queryFn: async () => {
          const url = `/api/v1/translations/${locale}?v=${version}`;
          const res = await fetch(url);
          if (!res.ok) throw new Error(`Bundle fetch failed: ${res.status}`);
          return (await res.json()) as Record<string, string>;
        },
        enabled: version > 0,        // skip while version is unknown
        staleTime: Infinity,         // version-pinned URL → never stales until version bumps
        gcTime: 60 * 60_000,         // keep prior versions around 1h for back-nav
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/translations/{locale}', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source                 | Path                                                       | Lines                                                                                                                                                    |
| ---------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Controller             | `apps/api-core/src/modules/i18n/public-i18n.controller.ts` | `60–92` (`getBundle` — ETag, `?v=` cache pinning, SWR fallback)                                                                                          |
| Service (bundle build) | `apps/api-core/src/modules/i18n/translation.service.ts`    | `301–336` (`getBundle` — APPROVED-only filter, `<namespace>.<key>` flat map)                                                                             |
| Cache layers           | `apps/api-core/src/modules/i18n/i18n-cache.service.ts`     | `70–89` (`getBundle` / `setBundle`), `8–9` (TTL constants), `189–219` (L1+L2 lookup)                                                                     |
| Versioning             | `apps/api-core/src/modules/i18n/i18n-cache.service.ts`     | `93–110` (`getVersion`/`incrementVersion`), `124–148` (`invalidateLocale` — INCR + PUBLISH)                                                              |
| Prisma model           | `packages/prisma/prisma/schema.prisma`                     | `Translation` lines `2417–2434` (filter: `languageCode = ?` AND `status = 'APPROVED'`); `TranslationKey` lines `2400–2415` (provides `namespace`, `key`) |


# List Locales (/docs/i18n/locales)



`GET /api/v1/locales` — 🌐 **Public** · Rate limit: **60 req / minute**

Returns the **active** languages currently served by the platform plus a `versions` map (one integer per locale code). The version is incremented every time the server invalidates a locale's translation bundle — clients keep this map and refetch the matching `/translations/:locale` only when its version changes.



<Callout type="info">
  **No top-level `/i18n/` prefix.** This controller registers at the **root** under the global `/api/v1` prefix — so the path is `/api/v1/locales`, **not** `/api/v1/i18n/locales`. Same goes for the translation endpoints (`/api/v1/translations/:locale`, etc.). The grouping in this docs sidebar is purely editorial.
</Callout>

<Callout type="info">
  **Sanitized output.** Internal fields (`fallbackCode`, `sortOrder`, `active`, `createdAt`, `updatedAt`) are stripped. The list contains only languages where `active = true`, sorted by `sortOrder ASC`. To bring up a new locale, an admin sets `active = true` server-side; this list reflects that within \~60s (L1) / \~5 min (L2) of the change due to cache layers.
</Callout>

<Callout type="warn">
  **`versions[code]` is `0` on cold cache.** The version counter lives in Redis (key `i18n:version:<code>`, incremented on every invalidation). If Redis is unreachable when this endpoint runs, `getVersion()` returns `0` for every locale — your ETag/`?v=` checks against bundles will then look like "version 0," which is fine for cache-busting but **not safe to combine with the immutable cache hint** (you'd pin a stale bundle for a year). Keep version handling defensive: only treat `version > 0` as authoritative.
</Callout>

## Request [#request]

No body, no query params, no headers required.

## Response [#response]

### `200 OK` — `ApiResponseOf<LocaleListResponseDto>` [#200-ok--apiresponseoflocalelistresponsedto]

```json
{
  "success": true,
  "data": {
    "locales": [
      {
        "code": "en",
        "name": "English",
        "nativeName": "English",
        "isRtl": false,
        "isDefault": true
      },
      {
        "code": "tr",
        "name": "Turkish",
        "nativeName": "Türkçe",
        "isRtl": false,
        "isDefault": false
      }
    ],
    "versions": {
      "en": 42,
      "tr": 15
    }
  }
}
```

### Item fields (`locales[]`) [#item-fields-locales]

| Field        | Type    | Notes                                                                                                   |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------- |
| `code`       | string  | ISO 639-1 code (2-5 lowercase chars). Use as the path param for `/api/v1/translations/:locale`.         |
| `name`       | string  | English display name (e.g. `"Turkish"`). Use in admin pickers, not end-user UI.                         |
| `nativeName` | string  | Native display name (e.g. `"Türkçe"`). Render this in the locale switcher.                              |
| `isRtl`      | boolean | Set `<html dir="rtl">` (or equivalent) when true.                                                       |
| `isDefault`  | boolean | The fallback locale used when a translation is missing. Exactly one row in the list will have this set. |

### `versions` map [#versions-map]

| Field      | Type                     | Notes                                                                                                                                                                                                                                                                 |
| ---------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `versions` | `Record<string, number>` | Keyed by locale `code`. Each value is the current bundle version for that locale — bumped on **every translation update or language metadata change**. Use it to invalidate your client-side bundle cache. `0` means "cold Redis cache" — see the warn callout above. |

### Stripped fields [#stripped-fields]

`fallbackCode`, `sortOrder`, `active`, `createdAt`, `updatedAt` — internal, not returned.

### Errors [#errors]

| HTTP  | Reason                            |
| ----- | --------------------------------- |
| `429` | Rate limit exceeded (60 req/min). |

This endpoint has no other documented error paths.

## Side effects [#side-effects]

1. `languageService.listActive()` — reads from cache (L1 60s → L2 Redis 5min → DB). On DB miss/cold start: `prisma.language.findMany({ orderBy: { sortOrder: 'asc' } })`, then filters `active = true` in memory.
2. For each active language, read `i18n:version:<code>` from Redis (`cache.getVersion(code)`). Returns `0` if Redis is unreachable.
3. Project to the sanitized 5-field shape.
4. Return `{ locales, versions }`. &#x2A;*No DB writes, no logs, no side channels.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query (with version-aware bundle refetch)']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/locales
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type Locale = {
      code: string;
      name: string;
      nativeName: string;
      isRtl: boolean;
      isDefault: boolean;
    };

    type LocaleListResponse = {
      locales: Locale[];
      versions: Record<string, number>;
    };

    async function listLocales(): Promise<LocaleListResponse> {
      const res = await fetch('https://api.bio.re/api/v1/locales');
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Locales fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query (with version-aware bundle refetch)">
    ```ts
    import { useQuery, useQueryClient } from '@tanstack/react-query';

    export const i18nKeys = {
      locales: () => ['i18n', 'locales'] as const,
      bundle: (locale: string, version: number) =>
        ['i18n', 'bundle', locale, version] as const,
    };

    // Refresh the locale list every 5 min — matches the L2 Redis TTL.
    // When `versions[locale]` changes, downstream useBundle queries with the
    // same locale but a new version will be fresh cache misses (different key).
    export function useLocales() {
      return useQuery({
        queryKey: i18nKeys.locales(),
        queryFn: async () => {
          const res = await fetch('/api/v1/locales');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Locales fetch failed'), {
              code: json?.error?.code,
            });
          }
          return json.data as LocaleListResponse;
        },
        staleTime: 5 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/locales', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source              | Path                                                       | Lines                                                                              |
| ------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Controller          | `apps/api-core/src/modules/i18n/public-i18n.controller.ts` | `23–34` (class), `36–58` (`getLocales`)                                            |
| DTO (response)      | `apps/api-core/src/modules/i18n/dto/i18n.dto.ts`           | `296–311` (`LocaleDto`), `317–328` (`LocaleListResponseDto`)                       |
| Service (languages) | `apps/api-core/src/modules/i18n/language.service.ts`       | `16–25` (`list` — cache then DB), `27–30` (`listActive` — filter active)           |
| Service (versions)  | `apps/api-core/src/modules/i18n/i18n-cache.service.ts`     | `93–101` (`getVersion`), `103–110` (`incrementVersion`)                            |
| Cache layers        | `apps/api-core/src/modules/i18n/i18n-cache.service.ts`     | `8–9` (`L1_TTL_MS = 60_000`, `L2_TTL_SECONDS = 300`), `189–219` (L1+L2 read/write) |
| Prisma model        | `packages/prisma/prisma/schema.prisma`                     | `Language` lines `2385–2398` (filter: `active = true`, sort: `sortOrder ASC`)      |


# Get Namespace Bundle (/docs/i18n/namespace)



`GET /api/v1/translations/:locale/:namespace` — 🌐 **Public** · Rate limit: **60 req / minute**

Returns the APPROVED translations for a single namespace inside a locale. Use this when you want to lazy-load (`auth` namespace on the auth screen, `chat` namespace inside the chat surface) instead of pulling the entire bundle up-front. Cache semantics, ETag shape, and `?v=N` immutable pinning behave the same as [`GET /api/v1/translations/:locale`](/docs/i18n/bundle) — the only differences are the path, the ETag (which embeds the namespace), and the response key shape.



<Callout type="info">
  **Keys are NOT prefixed in this response.** When you pull the full bundle the keys look like `auth.login.title`. When you pull a namespace bundle the same key is just `login.title` — the namespace is implied by the URL, so the prefix is dropped. Don't apply a `<namespace>.` prefix on the client when you call this endpoint.
</Callout>

<Callout type="info">
  **ETag includes the namespace.** Format is `"i18n-<locale>-<namespace>-<version>"`. The version itself is per-locale (not per-namespace) — bumping any translation in any namespace under a locale invalidates **every** namespace bundle for that locale. There's currently no per-namespace versioning.
</Callout>

<Callout type="warn">
  **Unknown namespace returns an empty bundle, not `404`.** Same behavior as the full-bundle endpoint with an unknown locale — the WHERE clause produces zero rows and the server happily returns `200 OK` with `{}`. There's no list-namespaces public endpoint to validate against; the canonical client-side approach is to harden against missing keys (fall back to the key itself).
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param       | Type   | Required | Notes                                                                                                                            |
| ----------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `locale`    | string | ✓        | ISO 639-1 code (e.g. `en`, `tr`).                                                                                                |
| `namespace` | string | ✓        | Namespace identifier (e.g. `auth`, `chat`, `common`). Defined by the admin tooling — there is no list endpoint exposed publicly. |

### Query parameters [#query-parameters]

| Param | Type    | Default | Notes                                                                                                                 |
| ----- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `v`   | integer | —       | Same as the full-bundle endpoint. Pass `versions[locale]` from `GET /locales` to opt into the 1-year immutable cache. |

### Headers [#headers]

| Header          | Required | Notes                                                                                                                 |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `If-None-Match` | optional | Send the previous response's `ETag` (`"i18n-<locale>-<namespace>-<version>"`) for a `304 Not Modified` short-circuit. |

No body, no auth required.

## Response [#response]

### `200 OK` — `Record<string, string>` (flat map, no namespace prefix) [#200-ok--recordstring-string-flat-map-no-namespace-prefix]

```json
{
  "login.title": "Sign in to your account",
  "login.button": "Sign in",
  "signup.cta": "Create account",
  "errors.invalid_credentials": "Invalid email or password"
}
```

### `304 Not Modified` [#304-not-modified]

Returned when `If-None-Match` matches the current `ETag`. No body.

### Response headers (always) [#response-headers-always]

| Header          | Value                                                                                         | Notes                                                      |
| --------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `ETag`          | `"i18n-<locale>-<namespace>-<version>"`                                                       | Embeds the namespace — distinct from the full-bundle ETag. |
| `Cache-Control` | `public, max-age=31536000, immutable` **OR** `public, max-age=60, stale-while-revalidate=300` | Immutable when `?v=N` matches; SWR fallback otherwise.     |

### Errors [#errors]

| HTTP  | Reason               |
| ----- | -------------------- |
| `429` | Rate limit exceeded. |

No other documented errors. Unknown `:locale` or `:namespace` → `200` + empty `{}`.

## Side effects [#side-effects]

1. `cache.getVersion(locale)` — read `i18n:version:<locale>` from Redis (returns `0` if unavailable).
2. Build ETag = `"i18n-<locale>-<namespace>-<version>"`. If `If-None-Match === ETag` → `res.status(304); return`.
3. `translationService.getBundle(locale, namespace)` — multi-layer cache lookup:
   * L1 (`bundle:<locale>:<namespace>`, 60s) → if hit, return.
   * L2 (Redis, `i18n:bundle:<locale>:<namespace>`, 5 min) → if hit, promote to L1, return.
   * On miss: `prisma.translation.findMany({ where: { languageCode, status: 'APPROVED', translationKey: { namespace } } })`.
4. Project to flat map. &#x2A;*The key is just `translation.translationKey.key`** — no `<namespace>.` prefix (because the namespace is implied by the URL).
5. Write to L2 + L1.
6. Set `ETag` header. Set `Cache-Control` based on `?v=` match.
7. Return the bundle.

### Invalidation note [#invalidation-note]

The write-side `invalidateLocale(locale)` clears **all** namespace bundles for that locale (it loops through known namespaces and `DEL`s each Redis key). There's no narrower per-namespace invalidation today.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query (per-route lazy)']">
  <Tab value="curl">
    ```bash
    curl -i 'https://api.bio.re/api/v1/translations/en/auth?v=42' \
      -H 'If-None-Match: "i18n-en-auth-42"'
    # 304 if version matches and ETag matches; else 200 + JSON body.
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type NamespaceBundle = Record<string, string>;

    async function getNamespaceBundle(
      locale: string,
      namespace: string,
      version: number,
    ): Promise<NamespaceBundle> {
      const url = `https://api.bio.re/api/v1/translations/${locale}/${namespace}?v=${version}`;
      const res = await fetch(url);
      if (!res.ok) throw new Error(`Bundle fetch failed: ${res.status}`);
      return (await res.json()) as NamespaceBundle;
    }

    // Usage in an auth screen — the `auth` namespace is the only thing this view needs:
    const auth = await getNamespaceBundle('en', 'auth', 42);
    const title = auth['login.title'] ?? 'Sign in';
    ```
  </Tab>

  <Tab value="TanStack Query (per-route lazy)">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export function useNamespaceBundle(locale: string, namespace: string, version: number) {
      return useQuery({
        queryKey: ['i18n', 'bundle', locale, namespace, version],
        queryFn: async () => {
          const res = await fetch(`/api/v1/translations/${locale}/${namespace}?v=${version}`);
          if (!res.ok) throw new Error(`Bundle fetch failed: ${res.status}`);
          return (await res.json()) as Record<string, string>;
        },
        enabled: version > 0,
        staleTime: Infinity,
        gcTime: 60 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/translations/{locale}/{namespace}', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source                 | Path                                                       | Lines                                                                                                                                               |
| ---------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Controller             | `apps/api-core/src/modules/i18n/public-i18n.controller.ts` | `94–126` (`getNamespaceBundle` — ETag with namespace, `?v=` pinning, SWR fallback)                                                                  |
| Service (bundle build) | `apps/api-core/src/modules/i18n/translation.service.ts`    | `301–336` (`getBundle` with optional `namespace` arg — when set, key is `translationKey.key` without prefix; line `328`)                            |
| Cache layers           | `apps/api-core/src/modules/i18n/i18n-cache.service.ts`     | `70–89` (`getBundle`/`setBundle` — namespace-aware key), `124–148` (`invalidateLocale` clears every namespace under a locale)                       |
| Prisma model           | `packages/prisma/prisma/schema.prisma`                     | `Translation` lines `2417–2434` (filter: `languageCode = ?` AND `status = 'APPROVED'`); `TranslationKey` lines `2400–2415` (filter `namespace = ?`) |


# Browse by Category / Platform (/docs/discover/category)



`GET /api/v1/discover/category/:platform` — 🌐 **Public** · Rate limit: **60 req / minute** · Kill-switched

Browse creators filtered by **social platform** (path param — they have a verified linked account on that platform) AND optionally by **content category** (`?category=`) AND by **DM type** (`?dmType=`). Three sort modes: `recent` (default), `popular` (totalMessages), `rating` (avgRating). Cursor-based pagination — same shape as `/search`.



<Callout type="info">
  **`platform` is the social network filter, not the content category.** The path param picks creators with at least one &#x2A;*verified `SocialAccount`** on that platform (e.g. `/discover/category/instagram` returns creators who linked Instagram via OAuth). The `?category` query param is a separate filter on `CreatorCategory.category` — that's the content niche (`fitness`, `music`, `tech`, ...).
</Callout>

<Callout type="warn">
  **Server-side platform filter is uppercase.** The path param `:platform` is `.toUpperCase()`-d before the `SocialAccount` lookup. `Instagram`, `instagram`, `INSTAGRAM` all hit the same row set. Pass any case the user input.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param      | Type   | Notes                                                                                                                                                                             |
| ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `platform` | string | Free-form platform identifier (`instagram`, `x`, `youtube`, `tiktok`, etc). Server uppercases before matching `SocialAccount.platform`. Empty platform set returns empty results. |

### Query parameters — `DiscoverDto` [#query-parameters--discoverdto]

| Param      | Type   | Default                                  | Validation                           | Notes                                                                                                 |
| ---------- | ------ | ---------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `category` | string | —                                        | `IsString()`                         | Content category (e.g. `fitness`, `music`). Lowercased before matching `CreatorCategory.category`.    |
| `sort`     | string | `recent`                                 | `IsString()`                         | `popular` (totalMessages DESC), `rating` (avgRating DESC), or `recent` (updatedAt DESC; also default) |
| `dmType`   | enum   | —                                        | `IsEnum(DmType)`                     | `FREE` / `SINGLE_PAY` / `PER_MESSAGE`                                                                 |
| `cursor`   | string | —                                        | `IsString()`                         | Opaque cursor (last result id)                                                                        |
| `limit`    | number | `discover.page_size` (admin, default 20) | `Min(1)`, `Max(50)`, `@Type(Number)` | Server-additionally clamps to `min(limit, 100)`                                                       |

No headers required.

## Response [#response]

### `200 OK` — `ApiResponseOf<CursorPaginatedCreatorsDto>` [#200-ok--apiresponseofcursorpaginatedcreatorsdto]

Same shape as [`GET /discover/search`](/docs/discover/search) — `{ results: CreatorCardDto[], nextCursor, hasMore }`.

```json
{
  "success": true,
  "data": {
    "results": [
      {
        "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "username": "fitness-creator",
        "displayName": "Fitness Creator",
        "avatarUrl": "https://cdn.bio.re/avatars/abc.webp",
        "level": "SILVER",
        "dmActive": true,
        "totalFollowers": 25000
      }
    ],
    "nextCursor": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "hasMore": true
  }
}
```

### Errors [#errors]

| HTTP  | `code` / `i18nKey`           | Reason                                           |
| ----- | ---------------------------- | ------------------------------------------------ |
| `400` | (DTO validation)             | `dmType` invalid enum, `limit` outside `[1, 50]` |
| `429` | (throttle)                   | Rate limit exceeded (60 req/min)                 |
| `503` | `features.discover_disabled` | Admin kill switch `DISCOVER` is active           |

## Side effects [#side-effects]

1. Resolve `pageSize = min(limit ?? config.discover.page_size ?? 20, 100)`.
2. **Platform pre-filter** — `socialAccount.findMany({ platform: <upper>, verified: true, take: 1000 })` to get the `userIds` set.
3. **Empty platform set** → return `{ results: [], nextCursor: null, hasMore: false }`.
4. Build `where = { ...activeCreatorFilter, userId IN <set> }`.
5. Optional `dmType` filter applied to `where.dmType`.
6. **Optional `category` filter** — `creatorCategory.findMany({ category: <lower>, take: 1000 })` → category creator IDs. Empty → return empty results. Else add `where.id IN <categoryIds>`.
7. Resolve `orderBy` from `sort` switch (default `updatedAt desc`).
8. `creatorProfile.findMany({ where, include: user, take: pageSize+1, orderBy, [optional cursor + skip:1] })`.
9. Compute `hasMore = creators.length > pageSize`; trim, assemble `nextCursor`, map to cards, return.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    # All Instagram creators (default recent sort)
    curl 'https://api.bio.re/api/v1/discover/category/instagram'

    # Popular fitness creators on TikTok with paid DMs
    curl 'https://api.bio.re/api/v1/discover/category/tiktok?category=fitness&sort=popular&dmType=SINGLE_PAY&limit=20'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type BrowseFilter = {
      platform: string;
      category?: string;
      sort?: 'recent' | 'popular' | 'rating';
      dmType?: 'FREE' | 'SINGLE_PAY' | 'PER_MESSAGE';
      cursor?: string;
      limit?: number;
    };

    async function browseByCategory(f: BrowseFilter): Promise<CursorPage<CreatorCard>> {
      const url = new URL(`https://api.bio.re/api/v1/discover/category/${encodeURIComponent(f.platform)}`);
      if (f.category) url.searchParams.set('category', f.category);
      if (f.sort) url.searchParams.set('sort', f.sort);
      if (f.dmType) url.searchParams.set('dmType', f.dmType);
      if (f.cursor) url.searchParams.set('cursor', f.cursor);
      if (f.limit) url.searchParams.set('limit', String(f.limit));
      const res = await fetch(url);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Browse failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useInfiniteQuery } from '@tanstack/react-query';

    export const discoverKeys = {
      byCategory: (f: Omit<BrowseFilter, 'cursor'>) => ['discover', 'category', f] as const,
    };

    export function useByCategoryInfinite(f: Omit<BrowseFilter, 'cursor'>) {
      return useInfiniteQuery({
        queryKey: discoverKeys.byCategory(f),
        initialPageParam: undefined as string | undefined,
        queryFn: async ({ pageParam }) => {
          const url = new URL(`/api/v1/discover/category/${encodeURIComponent(f.platform)}`, window.location.origin);
          if (f.category) url.searchParams.set('category', f.category);
          if (f.sort) url.searchParams.set('sort', f.sort);
          if (f.dmType) url.searchParams.set('dmType', f.dmType);
          if (f.limit) url.searchParams.set('limit', String(f.limit));
          if (pageParam) url.searchParams.set('cursor', pageParam);
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Browse failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as CursorPage<CreatorCard>;
        },
        getNextPageParam: (last) => (last.hasMore ? last.nextCursor ?? undefined : undefined),
        enabled: Boolean(f.platform),
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/discover/category/{platform}', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                              | Lines                                                                                                                        |
| -------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/discover/discover.controller.ts`       | `57–68` (`byCategory`)                                                                                                       |
| DTO (request)  | `apps/api-core/src/modules/discover/dto/index.ts`                 | `21–37` (`DiscoverDto`)                                                                                                      |
| DTO (response) | `apps/api-core/src/modules/discover/dto/discover-response.dto.ts` | `37–46` (`CursorPaginatedCreatorsDto`)                                                                                       |
| Service        | `apps/api-core/src/modules/discover/discover.service.ts`          | `298–361` (`getByCategory`)                                                                                                  |
| Config         | `apps/api-core/src/modules/config/config.service.ts`              | `discover.page_size` (admin-managed default 20)                                                                              |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                            | `SocialAccount` (platform pre-filter), `CreatorProfile` (active + dmType + sort), `CreatorCategory` (optional content niche) |


# Get Featured Creators (/docs/discover/featured)



`GET /api/v1/discover/featured` — 🌐 **Public** · Rate limit: **60 req / minute** · Kill-switched

Returns the **admin-curated featured creator list**. Reads `FeaturedCreator` rows where the current time falls inside the `startsAt`/`endsAt` window (open-ended on either side is allowed), then loads the matching `CreatorProfile` rows and filters out inactive / suspended / vacationing creators. Ordered by `position ASC`.



<Callout type="info">
  **Admin-managed catalog.** The featured list is curated via admin endpoints — clients can't add/remove. Empty list = no current featured slots (or all currently-featured creators are inactive). Cap is 100 (server-side `take: 100` on both queries).
</Callout>

## Request [#request]

No body, no params, no headers required.

## Response headers [#response-headers]

| Header          | Value                                              |
| --------------- | -------------------------------------------------- |
| `Cache-Control` | `public, s-maxage=300, stale-while-revalidate=600` |

## Response [#response]

### `200 OK` — `ApiResponseOf<CreatorListDto>` [#200-ok--apiresponseofcreatorlistdto]

```json
{
  "success": true,
  "data": {
    "creators": [
      {
        "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "username": "featured-creator",
        "displayName": "Featured Creator",
        "avatarUrl": "https://cdn.bio.re/avatars/abc.webp",
        "level": "PLATINUM",
        "dmActive": true,
        "totalFollowers": 100000
      }
    ]
  }
}
```

| Field      | Type               | Notes                                                                               |
| ---------- | ------------------ | ----------------------------------------------------------------------------------- |
| `creators` | `CreatorCardDto[]` | Currently-featured + currently-active creators, ordered by admin-set `position ASC` |

See [Search](/docs/discover/search) for the full `CreatorCardDto` field reference.

### Errors [#errors]

| HTTP  | `code` / `i18nKey`           | Reason                                 |
| ----- | ---------------------------- | -------------------------------------- |
| `429` | (throttle)                   | Rate limit exceeded (60 req/min)       |
| `503` | `features.discover_disabled` | Admin kill switch `DISCOVER` is active |

## Side effects [#side-effects]

1. `featuredCreator.findMany({ where: { startsAt <= now (or null), endsAt >= now (or null) }, orderBy: position asc, take: 100 })`.
2. **Empty list** → return `{ creators: [] }` (no second query).
3. `creatorProfile.findMany({ where: id IN featured.ids AND active filter (status ACTIVE, creatorStatus ACTIVE, vacationMode false) })` with the user join.
4. Map rows → `toCard()` and return.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/discover/featured
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function getFeaturedCreators(): Promise<CreatorCard[]> {
      const res = await fetch('https://api.bio.re/api/v1/discover/featured');
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Featured fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.creators;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const discoverKeys = {
      featured: () => ['discover', 'featured'] as const,
    };

    export function useFeatured() {
      return useQuery({
        queryKey: discoverKeys.featured(),
        queryFn: async () => {
          const res = await fetch('/api/v1/discover/featured');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Featured fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.creators as CreatorCard[];
        },
        staleTime: 5 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/discover/featured', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                              | Lines                                                                                                 |
| -------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/discover/discover.controller.ts`       | `51–55` (`featured`)                                                                                  |
| DTO (response) | `apps/api-core/src/modules/discover/dto/discover-response.dto.ts` | `52–55` (`CreatorListDto`)                                                                            |
| Service        | `apps/api-core/src/modules/discover/discover.service.ts`          | `277–296` (`getFeatured`)                                                                             |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                            | `FeaturedCreator` (admin-managed: `startsAt`, `endsAt`, `position`), `CreatorProfile` (active filter) |


# Clear Recently Viewed (/docs/discover/history-clear)



`DELETE /api/v1/discover/history` — 🔑 **Bearer** · Kill-switched

Hard-deletes every `RecentlyViewed` row for the calling user via a single `deleteMany`. Returns the number of rows actually removed (zero is a normal result if the user has never viewed anyone).



<Callout type="warn">
  **Hard delete, no undo.** Once gone, the rows are gone — there's no recycle bin or "deleted" flag. The user's recommendations / "you visited" UI restarts from empty after this call.
</Callout>

## Request [#request]

No body, no params. Identity comes from the bearer token.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` [#200-ok]

```json
{
  "success": true,
  "data": {
    "deleted": 7
  }
}
```

The controller returns the service result `{ deleted: count }` directly. The platform's response interceptor wraps it in `{ success: true, data: ... }` per the standard envelope.

| Field     | Type   | Notes                                                                    |
| --------- | ------ | ------------------------------------------------------------------------ |
| `deleted` | number | Count of `RecentlyViewed` rows actually removed. `0` is a normal result. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`           | Reason                                 |
| ----- | ---------------------------- | -------------------------------------- |
| `401` | (guard)                      | Missing / invalid bearer token         |
| `503` | `features.discover_disabled` | Admin kill switch `DISCOVER` is active |

## Side effects [#side-effects]

1. `prisma.recentlyViewed.deleteMany({ where: { userId } })`.
2. Return `{ deleted: result.count }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X DELETE https://api.bio.re/api/v1/discover/history \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function clearRecentlyViewed(accessToken: string): Promise<number> {
      const res = await fetch('https://api.bio.re/api/v1/discover/history', {
        method: 'DELETE',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Clear history failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.deleted as number;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useClearRecentlyViewed() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/discover/history', { method: 'DELETE' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Clear history failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.deleted as number;
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['discover', 'history'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/discover/history', method: 'delete' }]" hasHead="false" />

## Source [#source]

| Source       | Path                                                        | Lines                             |
| ------------ | ----------------------------------------------------------- | --------------------------------- |
| Controller   | `apps/api-core/src/modules/discover/discover.controller.ts` | `98–105` (`clearHistory`)         |
| Service      | `apps/api-core/src/modules/discover/discover.service.ts`    | `389–392` (`clearRecentlyViewed`) |
| Prisma model | `packages/prisma/prisma/schema.prisma`                      | `RecentlyViewed`                  |


# Get Recently Viewed (/docs/discover/history-list)



`GET /api/v1/discover/history` — 🔑 **Bearer** · Kill-switched

Returns the calling user's recently viewed creators, ordered by `viewedAt DESC`. **Active-creator filter** is applied on the read — even if the user previously viewed a creator who later went inactive / suspended / vacationing, that row is silently dropped from the response (the underlying `RecentlyViewed` row stays, but the join filters it out).



<Callout type="info">
  **The list can be shorter than `limit`.** If, say, you ask for 10 and 3 of them have gone inactive since you viewed them, you'll get 7 cards. There's no automatic top-up — the active filter runs on the join, not on the cursor pull.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param   | Type   | Default                                              | Validation                           | Notes                                          |
| ------- | ------ | ---------------------------------------------------- | ------------------------------------ | ---------------------------------------------- |
| `limit` | number | `discover.recently_viewed_count` (admin, default 10) | `Min(1)`, `Max(50)`, `@Type(Number)` | Server-additionally clamps to `min(limit, 50)` |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<CreatorListDto>` [#200-ok--apiresponseofcreatorlistdto]

```json
{
  "success": true,
  "data": {
    "creators": [
      {
        "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "username": "recent-creator",
        "displayName": "Recent Creator",
        "avatarUrl": "https://cdn.bio.re/avatars/abc.webp",
        "level": "BRONZE",
        "dmActive": true,
        "totalFollowers": 1500
      }
    ]
  }
}
```

| Field      | Type               | Notes                                                                                                                             |
| ---------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `creators` | `CreatorCardDto[]` | Up to `limit` cards, ordered by recency. &#x2A;*May be shorter than `limit`** when previously-viewed creators have gone inactive. |

See [Search](/docs/discover/search) for the full `CreatorCardDto` field reference.

### Errors [#errors]

| HTTP  | `code` / `i18nKey`           | Reason                                 |
| ----- | ---------------------------- | -------------------------------------- |
| `400` | (DTO validation)             | `limit` outside `[1, 50]`              |
| `401` | (guard)                      | Missing / invalid bearer token         |
| `503` | `features.discover_disabled` | Admin kill switch `DISCOVER` is active |

## Side effects [#side-effects]

1. Resolve `effectiveLimit = min(limit ?? config.discover.recently_viewed_count ?? 10, 50)`.
2. `recentlyViewed.findMany({ where: { userId }, orderBy: viewedAt desc, take: effectiveLimit })`.
3. Empty list → return `{ creators: [] }`.
4. `creatorProfile.findMany({ where: { id IN recent.ids AND active filter }, include: user })` — note this **drops inactive rows silently**.
5. Map to cards, return. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/discover/history \
      -H "Authorization: Bearer $ACCESS_TOKEN"

    curl 'https://api.bio.re/api/v1/discover/history?limit=20' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function getRecentlyViewed(accessToken: string, limit?: number): Promise<CreatorCard[]> {
      const url = new URL('https://api.bio.re/api/v1/discover/history');
      if (limit) url.searchParams.set('limit', String(limit));
      const res = await fetch(url, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'History fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.creators;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const discoverKeys = {
      history: (limit?: number) => ['discover', 'history', limit ?? 'default'] as const,
    };

    export function useRecentlyViewed(limit?: number) {
      return useQuery({
        queryKey: discoverKeys.history(limit),
        queryFn: async () => {
          const url = new URL('/api/v1/discover/history', window.location.origin);
          if (limit) url.searchParams.set('limit', String(limit));
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'History fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.creators as CreatorCard[];
        },
        staleTime: 30_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/discover/history', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                              | Lines                                                       |
| -------------- | ----------------------------------------------------------------- | ----------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/discover/discover.controller.ts`       | `90–96` (`getHistory`)                                      |
| DTO (request)  | `apps/api-core/src/modules/discover/dto/index.ts`                 | `46–49` (`HistoryQueryDto`)                                 |
| DTO (response) | `apps/api-core/src/modules/discover/dto/discover-response.dto.ts` | `52–55` (`CreatorListDto`)                                  |
| Service        | `apps/api-core/src/modules/discover/discover.service.ts`          | `375–387` (`getRecentlyViewed`)                             |
| Config         | `apps/api-core/src/modules/config/config.service.ts`              | `discover.recently_viewed_count` (admin-managed default 10) |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                            | `RecentlyViewed`, `CreatorProfile` (active filter)          |


# Record Profile View (/docs/discover/history-record)



`POST /api/v1/discover/history/:creatorId` — 🔑 **Bearer** · Kill-switched

Records that the calling user viewed a creator's profile. **Upsert** semantics: first view creates the row, subsequent visits update the `viewedAt` timestamp (move-to-front behavior in the recently-viewed list). The body is empty — `userId` comes from the bearer token, `creatorId` from the path.



<Callout type="info">
  **Move-to-front, not append.** A repeat view of the same creator doesn't insert a duplicate row — it bumps the existing row's `viewedAt` so it surfaces at the top of `GET /discover/history`. The compound unique key `(userId, creatorId)` makes this safe.
</Callout>

<Callout type="warn">
  **Validates the creator exists.** The server checks `creatorProfile.findUnique` for the supplied `creatorId` before upserting; missing → `404 creator_not_found`. There's no inactive-creator filter here — even suspended / vacationing creators can be recorded as viewed (the active-only filter applies on the read side, see `GET /discover/history`).
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param       | Type   | Notes                                                           |
| ----------- | ------ | --------------------------------------------------------------- |
| `creatorId` | string | The `CreatorProfile.id` being viewed (raw string, no UUID pipe) |

No body.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<RecordViewResultDto>` [#200-ok--apiresponseofrecordviewresultdto]

```json
{
  "success": true,
  "data": {
    "recorded": true
  }
}
```

| Field      | Type    | Notes                                                           |
| ---------- | ------- | --------------------------------------------------------------- |
| `recorded` | boolean | Always `true` on 200 — both create and update paths return this |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`           | Reason                                 |
| ----- | ---------------------------- | -------------------------------------- |
| `401` | (guard)                      | Missing / invalid bearer token         |
| `404` | `discover.creator_not_found` | No `CreatorProfile` with this id       |
| `503` | `features.discover_disabled` | Admin kill switch `DISCOVER` is active |

## Side effects [#side-effects]

1. `prisma.creatorProfile.findUnique({ where: { id: creatorId }, select: { id: true } })`. Missing → throw `creator_not_found`.
2. `prisma.recentlyViewed.upsert({ where: { userId_creatorId }, update: { viewedAt: new Date() }, create: { id, userId, creatorId } })`.
3. Return `{ recorded: true }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/discover/history/c1a2b3c4-d5e6-7890-abcd-ef1234567890 \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function recordCreatorView(accessToken: string, creatorId: string): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/discover/history/${creatorId}`, {
        method: 'POST',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Record view failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useRecordCreatorView() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (creatorId: string) => {
          const res = await fetch(`/api/v1/discover/history/${creatorId}`, { method: 'POST' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Record view failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['discover', 'history'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/discover/history/{creatorId}', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                              | Lines                                                                                     |
| -------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/discover/discover.controller.ts`       | `80–88` (`recordView`)                                                                    |
| DTO (response) | `apps/api-core/src/modules/discover/dto/discover-response.dto.ts` | `60–63` (`RecordViewResultDto`)                                                           |
| Service        | `apps/api-core/src/modules/discover/discover.service.ts`          | `364–373` (`recordView`)                                                                  |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                            | `RecentlyViewed` (compound unique `userId_creatorId`), `CreatorProfile` (existence check) |


# Search Creators (/docs/discover/search)



`GET /api/v1/discover/search` — 🌐 **Public** · Rate limit: **60 req / minute** · Kill-switched

Public creator search. Uses PostgreSQL FTS (`to_tsvector` over `username + displayName + bio`, ranked by `ts_rank`) when available, falls back to a substring `ILIKE` query when the FTS engine fails or the parsed query is invalid. **Active-creator filter** is enforced server-side: `User.status = ACTIVE`, `CreatorProfile.creatorStatus = ACTIVE`, `vacationMode = false`. Cursor-based pagination — clients pass `nextCursor` from the previous response.



<Callout type="info">
  **Cursor pagination, not offset.** Pass `?cursor=<lastResultId>` from the previous response — the server uses Prisma's `cursor + skip: 1` to continue from the right place. There's no `page` param. Cursor values are opaque (currently the row id of the last result) and tied to the same query / sort.
</Callout>

<Callout type="warn">
  **FTS fallback is silent.** When the FTS query parser rejects the input (e.g. unsupported operators) the server falls back to ILIKE without telling the client. Result ranking + ordering may differ subtly between the two paths. **The minimum query length is 2 chars** (DTO `MinLength(2)`); calls below that fail validation, not search.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param      | Type   | Required | Validation                           | Notes                                                                                                                                                                          |
| ---------- | ------ | -------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `query`    | string | ✓        | `MinLength(2)`, `MaxLength(200)`     | Search input. FTS-friendly chars stripped (angle brackets, colon, parens, ampersand, pipe, exclamation, asterisk, quotes); whitespace tokens joined with the FTS AND operator. |
| `platform` | string | optional | `IsString()`                         | Reserved DTO field — currently NOT used by the search service. Pass for forward compat or skip.                                                                                |
| `cursor`   | string | optional | `IsString()`                         | Opaque next-page cursor (last result id).                                                                                                                                      |
| `limit`    | number | optional | `Min(1)`, `Max(50)`, `@Type(Number)` | Server-clamped further to `min(limit, 100)` AND `discover.page_size` (admin-managed default 20) when not supplied.                                                             |

No headers required.

## Response headers [#response-headers]

| Header          | Value                                              |
| --------------- | -------------------------------------------------- |
| `Cache-Control` | `public, s-maxage=300, stale-while-revalidate=600` |

## Response [#response]

### `200 OK` — `ApiResponseOf<CursorPaginatedCreatorsDto>` [#200-ok--apiresponseofcursorpaginatedcreatorsdto]

```json
{
  "success": true,
  "data": {
    "results": [
      {
        "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "username": "johndoe",
        "displayName": "John Doe",
        "avatarUrl": "https://cdn.bio.re/avatars/abc.webp",
        "level": "BRONZE",
        "dmActive": true,
        "totalFollowers": 1500
      }
    ],
    "nextCursor": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "hasMore": true
  }
}
```

### Item fields (`CreatorCardDto`) [#item-fields-creatorcarddto]

| Field                                    | Type                       | Notes                                                    |
| ---------------------------------------- | -------------------------- | -------------------------------------------------------- |
| `id`                                     | string                     | `CreatorProfile.id` — pass to bio render / DM send paths |
| `userId`                                 | string (UUID) \| undefined | The owning `User.id`                                     |
| `username` / `displayName` / `avatarUrl` | string \| undefined        | Profile basics                                           |
| `level`                                  | enum \| undefined          | `BRONZE` / `SILVER` / `GOLD` / `PLATINUM`                |
| `dmActive`                               | boolean                    | DM-accepting flag (raw — not vacation-adjusted)          |
| `totalFollowers`                         | number                     | Sum of follower counts across linked social accounts     |

### Top-level fields [#top-level-fields]

| Field        | Type           | Notes                                                                      |
| ------------ | -------------- | -------------------------------------------------------------------------- |
| `results`    | array          | Up to `limit` cards, ordered by FTS rank (or `updatedAt DESC` on fallback) |
| `nextCursor` | string \| null | Pass back as `?cursor=` for the next page; `null` when no more results     |
| `hasMore`    | boolean        | True when there's at least one more page                                   |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`           | Reason                                                                          |
| ----- | ---------------------------- | ------------------------------------------------------------------------------- |
| `400` | (DTO validation)             | `query` shorter than 2 chars / longer than 200; `limit` outside `[1, 50]`; etc. |
| `429` | (throttle)                   | Rate limit exceeded (60 req/min)                                                |
| `503` | `features.discover_disabled` | Admin kill switch `DISCOVER` is active                                          |

## Side effects [#side-effects]

1. Resolve `pageSize = min(limit ?? config.discover.page_size ?? 20, 100)`.
2. **FTS path**: build `tsQuery` (strip risky chars, join tokens with `&`); raw SQL against `to_tsvector(username + displayName + bio)`, ordered by `ts_rank`. Returns IDs only (defense-in-depth — second `findMany` fetches the full rows with `creatorInclude`). Preserve FTS rank ordering in-memory.
3. **Fallback (FTS fail)**: `creatorProfile.findMany` with `ILIKE` over `user.username` and `user.displayName`, `orderBy updatedAt desc`, with optional cursor.
4. Compute `hasMore = creators.length > pageSize`; trim and assemble `nextCursor`.
5. Map each row → `toCard()` (the `CreatorCardDto` shape).
6. Return `{ results, nextCursor, hasMore }`. **No mutations**, no auth.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/discover/search?query=fitness&limit=20'

    # Next page
    curl 'https://api.bio.re/api/v1/discover/search?query=fitness&limit=20&cursor=c1a2b3c4-d5e6-7890-abcd-ef1234567890'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type CreatorCard = {
      id: string;
      userId?: string;
      username?: string;
      displayName?: string;
      avatarUrl?: string;
      level?: 'BRONZE' | 'SILVER' | 'GOLD' | 'PLATINUM';
      dmActive: boolean;
      totalFollowers: number;
    };

    type CursorPage<T> = {
      results: T[];
      nextCursor: string | null;
      hasMore: boolean;
    };

    async function searchCreators(
      query: string,
      options: { cursor?: string; limit?: number } = {},
    ): Promise<CursorPage<CreatorCard>> {
      const url = new URL('https://api.bio.re/api/v1/discover/search');
      url.searchParams.set('query', query);
      if (options.cursor) url.searchParams.set('cursor', options.cursor);
      if (options.limit) url.searchParams.set('limit', String(options.limit));
      const res = await fetch(url);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Search failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useInfiniteQuery } from '@tanstack/react-query';

    export const discoverKeys = {
      search: (query: string, limit: number) => ['discover', 'search', query, limit] as const,
    };

    export function useSearchInfinite(query: string, limit = 20) {
      return useInfiniteQuery({
        queryKey: discoverKeys.search(query, limit),
        initialPageParam: undefined as string | undefined,
        queryFn: async ({ pageParam }) => {
          const url = new URL('/api/v1/discover/search', window.location.origin);
          url.searchParams.set('query', query);
          url.searchParams.set('limit', String(limit));
          if (pageParam) url.searchParams.set('cursor', pageParam);
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Search failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as CursorPage<CreatorCard>;
        },
        getNextPageParam: (last) => (last.hasMore ? last.nextCursor ?? undefined : undefined),
        enabled: query.trim().length >= 2,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/discover/search', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                              | Lines                                                                                       |
| -------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/discover/discover.controller.ts`       | `35–41` (`search`)                                                                          |
| DTO (request)  | `apps/api-core/src/modules/discover/dto/index.ts`                 | `6–18` (`SearchDto`)                                                                        |
| DTO (response) | `apps/api-core/src/modules/discover/dto/discover-response.dto.ts` | `37–46` (`CursorPaginatedCreatorsDto`), `7–31` (`CreatorCardDto`)                           |
| Service        | `apps/api-core/src/modules/discover/discover.service.ts`          | `33–94` (`search` — FTS + ILIKE fallback)                                                   |
| Config         | `apps/api-core/src/modules/config/config.service.ts`              | `discover.page_size` (admin-managed default 20)                                             |
| Kill switch    | `apps/api-core/src/common/guards/kill-switch.guard.ts`            | `RequireKillSwitch('DISCOVER')` (class-level)                                               |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                            | `CreatorProfile` (active filter), `User` (status, deletedAt), FTS via raw SQL `to_tsvector` |


# Get Trending Creators (/docs/discover/trending)



`GET /api/v1/discover/trending` — 🌐 **Public** · Rate limit: **60 req / minute** · Kill-switched

Returns the platform's trending creators. **Cached in Redis** (15min TTL) so reads are constant-time after the first warm. Underlying scoring is a multi-factor signal computed over a 7-day window; on scoring-engine failure, the endpoint falls back to a simple `totalMessages DESC` sort.



<Callout type="info">
  **Cached ranking is preserved on read.** When the cache hits, the server fetches the listed `creatorProfile` rows by id and re-sorts in-memory to match the cached ranking. This means even if a creator's stats changed since the cache was warmed, their position in `trending` reflects the snapshot at warm-time — not the live state.
</Callout>

<Callout type="warn">
  **`limit` clamps to admin-managed default**. When `?limit` is absent, the server reads `discover.trending_count` (default 10). When supplied, the value still goes through `Min(1)` / `Max(50)` validation.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param   | Type   | Default                                       | Validation                           | Notes                                 |
| ------- | ------ | --------------------------------------------- | ------------------------------------ | ------------------------------------- |
| `limit` | number | `discover.trending_count` (admin, default 10) | `Min(1)`, `Max(50)`, `@Type(Number)` | Number of trending creators to return |

No headers required.

## Response headers [#response-headers]

| Header          | Value                                              |
| --------------- | -------------------------------------------------- |
| `Cache-Control` | `public, s-maxage=300, stale-while-revalidate=600` |

## Response [#response]

### `200 OK` — `ApiResponseOf<CreatorListDto>` [#200-ok--apiresponseofcreatorlistdto]

```json
{
  "success": true,
  "data": {
    "creators": [
      {
        "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "username": "topcreator",
        "displayName": "Top Creator",
        "avatarUrl": "https://cdn.bio.re/avatars/abc.webp",
        "level": "GOLD",
        "dmActive": true,
        "totalFollowers": 50000
      }
    ]
  }
}
```

| Field      | Type               | Notes                                                                           |
| ---------- | ------------------ | ------------------------------------------------------------------------------- |
| `creators` | `CreatorCardDto[]` | Up to `limit` cards, ordered by trending rank (cached snapshot or live scoring) |

See [Search](/docs/discover/search) for the full `CreatorCardDto` field reference.

### Errors [#errors]

| HTTP  | `code` / `i18nKey`           | Reason                                 |
| ----- | ---------------------------- | -------------------------------------- |
| `400` | (DTO validation)             | `limit` outside `[1, 50]`              |
| `429` | (throttle)                   | Rate limit exceeded (60 req/min)       |
| `503` | `features.discover_disabled` | Admin kill switch `DISCOVER` is active |

## Side effects [#side-effects]

1. Resolve `count = limit ?? config.discover.trending_count ?? 10`.
2. **Cache lookup** — `redis.cacheGet('discover:trending:<count>')`. Hit:
   * Fetch `creatorProfile.findMany({ where: id IN cached.ids AND active filter })`.
   * In-memory re-sort to match cached id order.
   * Return.
3. **Cache miss**: try multi-factor scoring (`computeTrending`). On failure: log warn + fallback to `totalMessages DESC`.
4. Map rows → `toCard()` and return.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/discover/trending
    curl 'https://api.bio.re/api/v1/discover/trending?limit=20'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function getTrendingCreators(limit?: number): Promise<CreatorCard[]> {
      const url = new URL('https://api.bio.re/api/v1/discover/trending');
      if (limit) url.searchParams.set('limit', String(limit));
      const res = await fetch(url);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Trending fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.creators;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const discoverKeys = {
      trending: (limit?: number) => ['discover', 'trending', limit ?? 'default'] as const,
    };

    export function useTrending(limit?: number) {
      return useQuery({
        queryKey: discoverKeys.trending(limit),
        queryFn: async () => {
          const url = new URL('/api/v1/discover/trending', window.location.origin);
          if (limit) url.searchParams.set('limit', String(limit));
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Trending fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.creators as CreatorCard[];
        },
        staleTime: 5 * 60_000, // match the CDN s-maxage
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/discover/trending', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                              | Lines                                                                                             |
| -------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/discover/discover.controller.ts`       | `43–49` (`trending`)                                                                              |
| DTO (request)  | `apps/api-core/src/modules/discover/dto/index.ts`                 | `41–44` (`TrendingQueryDto`)                                                                      |
| DTO (response) | `apps/api-core/src/modules/discover/dto/discover-response.dto.ts` | `52–55` (`CreatorListDto`)                                                                        |
| Service        | `apps/api-core/src/modules/discover/discover.service.ts`          | `98–124` (`getTrending`), `computeTrending` (scoring), `getTrendingFallback` (totalMessages sort) |
| Config         | `apps/api-core/src/modules/config/config.service.ts`              | `discover.trending_count` (admin-managed default 10)                                              |
| Cache          | Redis                                                             | `discover:trending:<count>` key, 15min TTL                                                        |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                            | `CreatorProfile` (active filter)                                                                  |


# Get Privacy Policy (/docs/legal/privacy)



`GET /api/v1/legal/privacy` — 🌐 **Public**

Returns the platform's privacy policy as a single document. **Content is admin-managed** via the `legal.privacy_policy` ConfigService key — when the admin updates the policy, the next read serves the new content. The `lastUpdated` timestamp comes from the config definition's `updatedAt` field, so the client can show "Last updated: ..." in the UI.



<Callout type="info">
  **Admin-managed catalog.** The policy text lives in `ConfigService` (admin → "Legal docs" pane). Versioning + change-tracking are platform concerns; this endpoint is read-only and always serves the current version. To track user consent across versions, see `POST /users/consent` (in the [User](/docs/user/consent-record) module).
</Callout>

<Callout type="warn">
  **Default fallback when unconfigured.** If the admin has never set `legal.privacy_policy`, the response carries `content: 'Privacy policy not yet published.'` and `lastUpdated: null`. Treat null `lastUpdated` as "no policy on file" and gate behavior accordingly (e.g. don't show the consent gate until a real policy exists).
</Callout>

## Request [#request]

No body, no params, no headers required.

## Response [#response]

### `200 OK` — `ApiResponseOf<LegalDocumentDto>` [#200-ok--apiresponseoflegaldocumentdto]

```json
{
  "success": true,
  "data": {
    "content": "<p>Privacy Policy content...</p>",
    "lastUpdated": "2026-04-29T20:00:00.000Z"
  }
}
```

| Field         | Type                      | Notes                                                                                                                                                                                     |
| ------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content`     | string                    | HTML body of the policy. Render with sanitization (e.g. DOMPurify) if untrusted-author surface is a concern; the platform admins are the only authors here, but defense-in-depth is fine. |
| `lastUpdated` | string (ISO 8601) \| null | Timestamp of the most recent admin update, derived from `ConfigService.getEffective(key).definition.updatedAt`. `null` when the config key has never been written.                        |

### Errors [#errors]

This endpoint has no documented error responses beyond HTTP infrastructure failures (5xx). No 4xx — even unconfigured keys return 200 with the default fallback.

## Side effects [#side-effects]

1. `configService.getWithDefault('legal.privacy_policy', 'Privacy policy not yet published.')`.
2. `configService.getEffective('legal.privacy_policy')`. If the result has `definition.updatedAt`, format as ISO; otherwise `lastUpdated = null` (with a warn log).
3. Return `{ content, lastUpdated }`. &#x2A;*No mutations, no auth, no per-user state.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/legal/privacy
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type LegalDocument = {
      content: string;
      lastUpdated: string | null;
    };

    async function getPrivacyPolicy(): Promise<LegalDocument> {
      const res = await fetch('https://api.bio.re/api/v1/legal/privacy');
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Privacy policy fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const legalKeys = {
      privacy: () => ['legal', 'privacy'] as const,
    };

    export function usePrivacyPolicy() {
      return useQuery({
        queryKey: legalKeys.privacy(),
        queryFn: async () => {
          const res = await fetch('/api/v1/legal/privacy');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Privacy policy fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as LegalDocument;
        },
        // Policies change rarely — cache aggressively
        staleTime: 60 * 60_000, // 1 hour
        gcTime: 24 * 60 * 60_000, // 1 day
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/legal/privacy', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                        | Lines                                                                                  |
| -------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/legal/legal.controller.ts`       | `14–19` (`getPrivacyPolicy`)                                                           |
| DTO (response) | `apps/api-core/src/modules/legal/dto/legal-response.dto.ts` | `7–13` (`LegalDocumentDto`)                                                            |
| Service        | `apps/api-core/src/modules/legal/legal.service.ts`          | `10–20` (`getPrivacyPolicy`), `34–43` (`getLastUpdated`)                               |
| Config keys    | (admin-managed via `ConfigService`)                         | `legal.privacy_policy` (string content; default `'Privacy policy not yet published.'`) |


# Get Terms of Service (/docs/legal/terms)



`GET /api/v1/legal/terms` — 🌐 **Public**

Returns the platform's terms of service as a single document. **Content is admin-managed** via the `legal.terms_of_service` ConfigService key. Same response shape as `GET /legal/privacy`.



<Callout type="info">
  **Identical shape, different key.** This endpoint is the terms-of-service twin of `GET /legal/privacy`. Same response (`{ content, lastUpdated }`), same fallback semantics, same caching guidance — only the underlying config key differs (`legal.terms_of_service` vs `legal.privacy_policy`). Frontend can share a single hook with the key as a parameter.
</Callout>

<Callout type="warn">
  **Default fallback when unconfigured.** If the admin has never set `legal.terms_of_service`, the response carries `content: 'Terms of service not yet published.'` and `lastUpdated: null`.
</Callout>

## Request [#request]

No body, no params, no headers required.

## Response [#response]

### `200 OK` — `ApiResponseOf<LegalDocumentDto>` [#200-ok--apiresponseoflegaldocumentdto]

```json
{
  "success": true,
  "data": {
    "content": "<p>Terms of Service content...</p>",
    "lastUpdated": "2026-04-29T20:00:00.000Z"
  }
}
```

| Field         | Type                      | Notes                                        |
| ------------- | ------------------------- | -------------------------------------------- |
| `content`     | string                    | HTML body of the terms                       |
| `lastUpdated` | string (ISO 8601) \| null | Last admin update; `null` when never written |

### Errors [#errors]

No documented 4xx — unconfigured keys return 200 with default fallback.

## Side effects [#side-effects]

1. `configService.getWithDefault('legal.terms_of_service', 'Terms of service not yet published.')`.
2. `configService.getEffective('legal.terms_of_service')` → ISO-format `definition.updatedAt` or `null`.
3. Return `{ content, lastUpdated }`. &#x2A;*No mutations, no auth, no per-user state.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/legal/terms
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function getTermsOfService(): Promise<LegalDocument> {
      const res = await fetch('https://api.bio.re/api/v1/legal/terms');
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Terms fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const legalKeys = {
      terms: () => ['legal', 'terms'] as const,
    };

    export function useTermsOfService() {
      return useQuery({
        queryKey: legalKeys.terms(),
        queryFn: async () => {
          const res = await fetch('/api/v1/legal/terms');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Terms fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as LegalDocument;
        },
        staleTime: 60 * 60_000,
        gcTime: 24 * 60 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/legal/terms', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                        | Lines                                                                                      |
| -------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/legal/legal.controller.ts`       | `21–26` (`getTermsOfService`)                                                              |
| DTO (response) | `apps/api-core/src/modules/legal/dto/legal-response.dto.ts` | `7–13` (`LegalDocumentDto`)                                                                |
| Service        | `apps/api-core/src/modules/legal/legal.service.ts`          | `22–32` (`getTermsOfService`), `34–43` (`getLastUpdated`)                                  |
| Config keys    | (admin-managed via `ConfigService`)                         | `legal.terms_of_service` (string content; default `'Terms of service not yet published.'`) |


# Get Wallet Activity (/docs/payment/wallet-activity)



`GET /api/v1/wallet/activity` — 🔑 **Bearer** · Kill-switched

Returns the calling user's wallet transaction feed — `CREDIT` / `DEBIT` / `EXPIRY` / `CHARGEBACK` rows, optionally filtered by `type`. Each item carries `balanceBefore` / `balanceAfter` for an audit-friendly trail. Pagination via `?page` / `?limit`, server-clamped to `[1, 20]` per page.



<Callout type="info">
  **No wallet → empty page (not 404).** Users without a wallet row yet get `{ items: [], total: 0, page: 1, limit: 20, totalPages: 0 }`. The wallet is created lazily on first `POST /wallet/load` — until then this endpoint is the safe "show me my history" endpoint that doesn't bootstrap a row.
</Callout>

<Callout type="warn">
  **`PAYOUT` is a service-side type, not a user-facing one.** The DTO's enum lists `PAYOUT` (creator-side payout records) but the controller's filter validation only accepts `CREDIT` / `DEBIT` / `EXPIRY` / `CHARGEBACK`. Don't pass `?type=PAYOUT` — it's silently ignored (server falls back to "no type filter"). Creator payouts live elsewhere (the payout module, separate scope).
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param   | Type   | Default | Validation                                       | Notes                                                                    |
| ------- | ------ | ------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
| `type`  | enum   | —       | `IsIn(['CREDIT','DEBIT','EXPIRY','CHARGEBACK'])` | Server-side allowlist. Invalid values silently fall back to "no filter". |
| `page`  | number | `1`     | `parseInt`, server-clamped to `>= 1`             | 1-based page index                                                       |
| `limit` | number | `20`    | `parseInt`, server-clamped to `[1, 20]`          | Items per page                                                           |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `PaginatedApiResponseOf<WalletActivityItemDto>` [#200-ok--paginatedapiresponseofwalletactivityitemdto]

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "walletId": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "type": "CREDIT",
        "amount": "25.00",
        "balanceBefore": "100.00",
        "balanceAfter": "125.00",
        "referenceType": "STRIPE_CHECKOUT",
        "referenceId": "cs_test_...",
        "description": "Balance loaded: $25.00",
        "createdAt": "2026-04-29T20:00:00.000Z"
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}
```

### Item fields [#item-fields]

| Field                            | Type              | Notes                                                                                                                                                                     |
| -------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                             | string (UUID)     | `WalletTransaction.id`                                                                                                                                                    |
| `walletId`                       | string (UUID)     | The wallet this transaction belongs to                                                                                                                                    |
| `type`                           | enum              | One of `CREDIT` / `DEBIT` / `EXPIRY` / `CHARGEBACK` / `PAYOUT` (PAYOUT not filterable here — see callout)                                                                 |
| `amount`                         | string (decimal)  | Decimal as string (always 2 decimals for display; raw db precision may be higher)                                                                                         |
| `balanceBefore` / `balanceAfter` | string (decimal)  | Snapshot for audit. `balanceAfter - balanceBefore` will not always equal `amount` for special types (e.g. `EXPIRY` may not change balance — read service logic per type). |
| `referenceType`                  | string            | What kind of object this transaction references (e.g. `STRIPE_CHECKOUT`, `MESSAGE_PAYMENT`, `BALANCE_PACKAGE`)                                                            |
| `referenceId`                    | string            | The id of the referenced object — passed by the upstream caller; opaque to clients                                                                                        |
| `description`                    | string            | Server-rendered free-form description (e.g. `"Balance loaded: $25.00"`)                                                                                                   |
| `createdAt`                      | string (ISO 8601) | Transaction timestamp                                                                                                                                                     |

### Top-level fields [#top-level-fields]

| Field        | Type   | Notes                                                   |
| ------------ | ------ | ------------------------------------------------------- |
| `items`      | array  | Up to `limit` transactions, ordered by `createdAt DESC` |
| `total`      | number | Total transactions matching the filter                  |
| `page`       | number | Echoed page index (1-based)                             |
| `limit`      | number | Echoed effective per-page limit (post-clamp)            |
| `totalPages` | number | `Math.ceil(total / limit)`                              |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`          | Reason                                |
| ----- | --------------------------- | ------------------------------------- |
| `401` | (guard)                     | Missing / invalid bearer token        |
| `503` | `features.payment_disabled` | Admin kill switch `PAYMENT` is active |

## Side effects [#side-effects]

1. Lookup `Wallet` for `(userId, type=FAN)`.
2. **No wallet** — short-circuit return empty page (`items: []`, `total: 0`, `page: 1`, `limit: 20`, `totalPages: 0`). **No mutations**, no DB writes.
3. Validate / clamp `type` (allowlist `CREDIT|DEBIT|EXPIRY|CHARGEBACK` — `PAYOUT` and unknown values fall back to no-filter).
4. Clamp `page = max(1, page)`, `limit = min(max(1, limit), 20)`.
5. **Two queries in parallel**:
   * `walletTransaction.findMany({ where: { walletId, ...(type && { type }) }, orderBy: { createdAt: 'desc' }, skip, take })`.
   * `walletTransaction.count({ where })`.
6. Return paginated envelope.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/wallet/activity?page=1&limit=20&type=CREDIT' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type WalletTransactionType = 'CREDIT' | 'DEBIT' | 'EXPIRY' | 'CHARGEBACK';

    type WalletActivityItem = {
      id: string;
      walletId: string;
      type: WalletTransactionType | 'PAYOUT';
      amount: string;
      balanceBefore: string;
      balanceAfter: string;
      referenceType: string;
      referenceId: string;
      description: string;
      createdAt: string;
    };

    type WalletActivity = {
      items: WalletActivityItem[];
      total: number;
      page: number;
      limit: number;
      totalPages: number;
    };

    async function getWalletActivity(
      accessToken: string,
      filter: { type?: WalletTransactionType; page?: number; limit?: number } = {},
    ): Promise<WalletActivity> {
      const url = new URL('https://api.bio.re/api/v1/wallet/activity');
      if (filter.type) url.searchParams.set('type', filter.type);
      if (filter.page) url.searchParams.set('page', String(filter.page));
      if (filter.limit) url.searchParams.set('limit', String(filter.limit));
      const res = await fetch(url, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Wallet activity fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery, keepPreviousData } from '@tanstack/react-query';

    export const walletKeys = {
      activity: (filter: { type?: string; page?: number; limit?: number }) =>
        ['wallet', 'activity', filter] as const,
    };

    export function useWalletActivity(filter: {
      type?: WalletTransactionType;
      page?: number;
      limit?: number;
    } = {}) {
      return useQuery({
        queryKey: walletKeys.activity(filter),
        queryFn: async () => {
          const url = new URL('/api/v1/wallet/activity', window.location.origin);
          if (filter.type) url.searchParams.set('type', filter.type);
          if (filter.page) url.searchParams.set('page', String(filter.page));
          if (filter.limit) url.searchParams.set('limit', String(filter.limit));
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Wallet activity fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as WalletActivity;
        },
        placeholderData: keepPreviousData, // smooth pagination UX
        staleTime: 30_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/wallet/activity', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source              | Path                                                           | Lines                                                                                                                            |
| ------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Controller          | `apps/api-core/src/modules/payment/wallet.controller.ts`       | `54–73` (`getActivity`)                                                                                                          |
| DTO (response item) | `apps/api-core/src/modules/payment/dto/wallet-response.dto.ts` | `58–94` (`WalletActivityItemDto`)                                                                                                |
| Service             | `apps/api-core/src/modules/payment/wallet.service.ts`          | `331–348` (`getActivityFeed`)                                                                                                    |
| Prisma model        | `packages/prisma/prisma/schema.prisma`                         | `Wallet`, `WalletTransaction` (`enum WalletTransactionType`), `LedgerEntry` (double-entry, written by service-layer transaction) |


# Get Wallet Balance (/docs/payment/wallet-balance)



`GET /api/v1/wallet/balance` — 🔑 **Bearer**

Returns the calling user's FAN-type wallet balance (decimal as string, fixed 2 places) and the `frozen` flag. **If no wallet row exists yet, returns `{ balance: '0.00', frozen: false }` without creating one** — the wallet is auto-created lazily on first load (`POST /wallet/load`).



<Callout type="info">
  **`frozen: true` blocks debits.** When admin / fraud detection freezes a wallet, debits (e.g. paying for a DM) are rejected, but the balance is still readable. Surface a banner on `frozen: true` so the user understands why their next payment fails.
</Callout>

<Callout type="warn">
  **Decimal as string.** Balance is returned as a string (`"25.00"`, not `25.00`) to preserve precision across JS clients. Parse with `Number(s)` or a decimal library — never compare two balance strings with `===` after arithmetic.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<WalletBalanceResponseDto>` [#200-ok--apiresponseofwalletbalanceresponsedto]

```json
{
  "success": true,
  "data": {
    "balance": "25.00",
    "frozen": false
  }
}
```

| Field     | Type             | Notes                                                                                 |
| --------- | ---------------- | ------------------------------------------------------------------------------------- |
| `balance` | string (decimal) | Always 2 decimal places. `"0.00"` when no wallet row exists yet.                      |
| `frozen`  | boolean          | `true` when admin / fraud detection has frozen the wallet (blocks debits, not reads). |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`          | Reason                                |
| ----- | --------------------------- | ------------------------------------- |
| `401` | (guard)                     | Missing / invalid bearer token        |
| `503` | `features.payment_disabled` | Admin kill switch `PAYMENT` is active |

## Side effects [#side-effects]

1. `prisma.wallet.findUnique({ where: { userId_type: { userId, type: 'FAN' } } })`.
2. **Wallet missing** — short-circuit return `{ balance: '0.00', frozen: false }`. **No row creation**, no mutations.
3. **Wallet exists** — return `{ balance: <Prisma.Decimal>.toFixed(2), frozen: wallet.frozen }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/wallet/balance \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type WalletBalance = {
      balance: string; // decimal as string, e.g. "25.00"
      frozen: boolean;
    };

    async function getWalletBalance(accessToken: string): Promise<WalletBalance> {
      const res = await fetch('https://api.bio.re/api/v1/wallet/balance', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Wallet balance fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const walletKeys = {
      balance: () => ['wallet', 'balance'] as const,
    };

    export function useWalletBalance() {
      return useQuery({
        queryKey: walletKeys.balance(),
        queryFn: async () => {
          const res = await fetch('/api/v1/wallet/balance');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Wallet balance fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as WalletBalance;
        },
        // Balance changes via /load (user action) and via webhook (server-side). Refresh on focus.
        staleTime: 30_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/wallet/balance', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                           | Lines                                                           |
| -------------- | -------------------------------------------------------------- | --------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/payment/wallet.controller.ts`       | `30–36` (`getBalance`)                                          |
| DTO (response) | `apps/api-core/src/modules/payment/dto/wallet-response.dto.ts` | `30–37` (`WalletBalanceResponseDto`)                            |
| Service        | `apps/api-core/src/modules/payment/wallet.service.ts`          | `59–65` (`getBalance`)                                          |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                         | `Wallet` (compound unique `userId_type`), `enum WalletType.FAN` |


# Create Wallet Load Session (/docs/payment/wallet-load)



`POST /api/v1/wallet/load` — 🔑 **Bearer** + **VelocityCheckGuard** · Kill-switched

Creates a **Stripe Checkout session** for a wallet top-up and returns the `sessionId` plus a `checkoutUrl` to redirect the user to. **Validates the amount** against admin-managed `wallet.min_load` / `wallet.max_load` / `wallet.max_balance` (per-account ceiling). **Idempotency-Key header is recommended** — both the server cache and Stripe's idempotency layer use it to prevent double-charges on retry.



<Callout type="warn">
  **The balance is NOT credited by this endpoint.** This endpoint only creates the Stripe Checkout session. After the user completes the payment on Stripe's hosted page, Stripe sends a webhook to the platform; that webhook handler is what actually increments the wallet balance (in a row-locked transaction with double-entry ledger). Your client must poll `/wallet/balance` (or refetch on `success_url` redirect) to see the new balance — there's no synchronous "balance after load" return value.
</Callout>

<Callout type="info">
  **`Idempotency-Key` header is two-layered.** When supplied, the server caches the resulting `{ sessionId, checkoutUrl }` in Redis (TTL = `wallet.idempotency_ttl_seconds`, capped 24h) AND passes it to Stripe. Subsequent calls with the same key return the cached pair without creating a new session. **Always send a stable, request-scoped key** (e.g. UUID per submit) to avoid creating multiple sessions on a network retry.
</Callout>

<Callout type="warn">
  **Velocity-checked.** `VelocityCheckGuard` rate-limits per-user beyond the global throttle. Hitting it returns `429` — back off and retry rather than spamming.
</Callout>

## Request [#request]

### Body — `WalletLoadDto` [#body--walletloaddto]

| Field    | Type   | Required | Validation                | Notes                                                                                                                                                                            |
| -------- | ------ | -------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount` | string | ✓        | regex `^\d+(\.\d{1,2})?$` | Decimal as string (e.g. `"25.00"`). Server validates against `wallet.min_load` / `wallet.max_load` AND the account's remaining headroom (`wallet.max_balance - currentBalance`). |

### Headers [#headers]

| Header                                | Required    | Notes                                                                                                                                                                                                                                               |
| ------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization: Bearer <accessToken>` | ✓           | JWT from `POST /auth/login`                                                                                                                                                                                                                         |
| `Idempotency-Key: <uuid>`             | recommended | Stable retry key. Cached server-side (Redis, TTL ≤ 24h) AND forwarded to Stripe. **Without it**, the server falls back to a per-minute auto-key (`wallet_load_<userId>_<cents>_<minute>`) — safe enough but not as tight as a client-supplied UUID. |

## Response [#response]

### `200 OK` — `ApiResponseOf<WalletLoadSessionResponseDto>` [#200-ok--apiresponseofwalletloadsessionresponsedto]

```json
{
  "success": true,
  "data": {
    "sessionId": "cs_test_...",
    "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_..."
  }
}
```

| Field         | Type   | Notes                                                                                                                                                                                                        |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sessionId`   | string | Stripe Checkout session id. Useful for support trails; not required by the client.                                                                                                                           |
| `checkoutUrl` | string | Redirect URL. Open in a new tab or full-page redirect. The user completes payment on Stripe's hosted flow and is redirected back to `success_url` / `cancel_url` (set server-side via the `CLIENT_URL` env). |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                            | Payload                | Reason                                                                                                                     |
| ----- | --------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `400` | `payment.wallet.error.min_load`               | `{ minLen → minLoad }` | Amount below `wallet.min_load`                                                                                             |
| `400` | `payment.wallet.error.max_load`               | `{ maxLoad }`          | Amount above `wallet.max_load`                                                                                             |
| `400` | `payment.wallet.error.max_balance`            | `{ maxCanLoad }`       | Loading this amount would push balance past `wallet.max_balance`. Payload tells the client how much they could still load. |
| `400` | `payment.wallet.error.service_not_configured` | —                      | Stripe SDK missing — server-side env / config issue. Surface "payment temporarily unavailable".                            |
| `400` | (DTO validation)                              | —                      | Amount string doesn't match the regex                                                                                      |
| `401` | (guard)                                       | —                      | Missing / invalid bearer token                                                                                             |
| `429` | (velocity / throttle)                         | —                      | Per-user velocity limit exhausted                                                                                          |
| `503` | `features.payment_disabled`                   | —                      | Admin kill switch `PAYMENT` is active                                                                                      |

## Side effects [#side-effects]

1. **Idempotency cache hit** — if `Idempotency-Key` supplied AND Redis has a cached `{ sessionId, checkoutUrl }` for that key: return it immediately. **No Stripe call**, no DB write.
2. **Validate amount** — read `wallet.min_load` / `wallet.max_load` / `wallet.max_balance` (admin-managed). Reject below min, above max, or if `currentBalance + amount > maxBalance`.
3. **Lazy wallet create** — `getOrCreateWallet(userId)` creates the FAN wallet row if missing.
4. **Resolve idempotency key**: client-supplied OR auto-generated `wallet_load_<userId>_<cents>_<minuteEpoch>`. Forward to Stripe SDK.
5. **Create Stripe Checkout session** — `stripe.checkout.sessions.create({ mode: 'payment', payment_method_types: ['card'], line_items: [{ price_data: { currency, product_data: { name: 'BIO.RE Wallet Load — <symbol><amount>' }, unit_amount: <cents> }, quantity: 1 }], metadata: { userId, walletLoad: 'true', amount }, client_reference_id: userId, success_url, cancel_url })`.
6. **Cache result** if client supplied `Idempotency-Key` (Redis, capped 24h to match Stripe's window).
7. Audit log + Prometheus counters (`walletLoadTotal`, `walletLoadDurationMs`).
8. Return `{ sessionId, checkoutUrl }`. **The wallet balance is NOT updated yet** — that happens in the Stripe webhook handler after the user completes payment.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/wallet/load \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{"amount": "25.00"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type WalletLoadSession = {
      sessionId: string;
      checkoutUrl: string;
    };

    async function createWalletLoadSession(
      accessToken: string,
      amount: string,
      idempotencyKey: string,
    ): Promise<WalletLoadSession> {
      const res = await fetch('https://api.bio.re/api/v1/wallet/load', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': idempotencyKey,
        },
        body: JSON.stringify({ amount }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Wallet load failed'), {
          code: json?.error?.code,
          maxCanLoad: json?.error?.maxCanLoad, // present on 'max_balance'
        });
      }
      return json.data;
    }

    // Usage: redirect on success
    async function startLoad(accessToken: string, amount: string) {
      const session = await createWalletLoadSession(accessToken, amount, crypto.randomUUID());
      window.location.assign(session.checkoutUrl);
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useCreateWalletLoadSession() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (vars: { amount: string; idempotencyKey: string }) => {
          const res = await fetch('/api/v1/wallet/load', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              'Idempotency-Key': vars.idempotencyKey,
            },
            body: JSON.stringify({ amount: vars.amount }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Wallet load failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
              maxCanLoad: json?.error?.maxCanLoad,
            });
          }
          return json.data as WalletLoadSession;
        },
        // After redirect-back from Stripe, refetch balance — webhook may have credited it
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['wallet', 'balance'] });
          qc.invalidateQueries({ queryKey: ['wallet', 'activity'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/wallet/load', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source          | Path                                                             | Lines                                                                                                        |
| --------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Controller      | `apps/api-core/src/modules/payment/wallet.controller.ts`         | `38–52` (`loadWallet`)                                                                                       |
| DTO (request)   | `apps/api-core/src/modules/payment/dto/index.ts`                 | `4–7` (`WalletLoadDto`)                                                                                      |
| DTO (response)  | `apps/api-core/src/modules/payment/dto/wallet-response.dto.ts`   | `45–51` (`WalletLoadSessionResponseDto`)                                                                     |
| Service         | `apps/api-core/src/modules/payment/wallet.service.ts`            | `72–147` (`createLoadSession`)                                                                               |
| Webhook handler | `apps/api-core/src/modules/payment/stripe-webhook.controller.ts` | (internal scope, not in this portal) — credits the wallet on payment success                                 |
| Stripe provider | `apps/api-core/src/modules/payment/stripe.provider.ts`           | `getStripe()`                                                                                                |
| Config keys     | `apps/api-core/src/modules/config/config.service.ts`             | `wallet.min_load`, `wallet.max_load`, `wallet.max_balance`, `wallet.idempotency_ttl_seconds` (admin-managed) |
| Velocity guard  | `apps/api-core/src/common/guards/velocity-check.guard.ts`        | `VelocityCheckGuard`                                                                                         |
| Kill switch     | `apps/api-core/src/common/guards/kill-switch.guard.ts`           | `RequireKillSwitch('PAYMENT')` (class-level)                                                                 |
| Prisma model    | `packages/prisma/prisma/schema.prisma`                           | `Wallet`, `BalancePackage` (FIFO consumption tracking, written by webhook)                                   |


# Get Load Packages (/docs/payment/wallet-packages)



`GET /api/v1/wallet/packages` — 🌐 **Public**

Returns the suggested wallet load amounts (e.g. `[5, 10, 25]`) plus the absolute `min` / `max` limits and the active currency code. Drives the chip / button picker in the wallet load screen — the user can pick a suggested amount or type a custom one within the bounds.



<Callout type="info">
  **Admin-managed catalog.** `wallet.load_packages` (default `[5, 10, 25]`), `wallet.min_load` (default `5`), `wallet.max_load` (default `500`) are all admin-managed via `ConfigService`. The currency comes from the platform's default-currency resolver (which reads from the same admin layer).
</Callout>

<Callout type="warn">
  **Kill switch on the controller.** `@RequireKillSwitch('PAYMENT')` is applied at the controller level, so this endpoint also returns `503 features.payment_disabled` when admin disables payments. Surface a "wallet is temporarily unavailable" UI when you see that response.
</Callout>

## Request [#request]

No body, no params, no headers required.

## Response [#response]

### `200 OK` — `ApiResponseOf<WalletPackagesResponseDto>` [#200-ok--apiresponseofwalletpackagesresponsedto]

```json
{
  "success": true,
  "data": {
    "packages": [5, 10, 25],
    "min": 5,
    "max": 500,
    "currency": "USD"
  }
}
```

| Field      | Type      | Notes                                                                                                                                                                                   |
| ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `packages` | number\[] | Suggested load amounts (in major units, e.g. dollars). Render as picker chips.                                                                                                          |
| `min`      | number    | Absolute minimum load amount. Reject custom inputs below this client-side.                                                                                                              |
| `max`      | number    | Absolute maximum **per-load** amount. There's also a `wallet.max_balance` ceiling enforced server-side at load time (returned as `max_balance` error if a single load would exceed it). |
| `currency` | string    | ISO 4217 currency code (e.g. `USD`). Reflects the active platform currency.                                                                                                             |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`          | Reason                                |
| ----- | --------------------------- | ------------------------------------- |
| `503` | `features.payment_disabled` | Admin kill switch `PAYMENT` is active |

## Side effects [#side-effects]

1. Read `wallet.load_packages` JSON config (default `[5, 10, 25]`).
2. Read `wallet.min_load` config (default `5`).
3. Read `wallet.max_load` config (default `500`).
4. Resolve the active default currency from the platform layer.
5. Return `{ packages, min, max, currency }`. **No mutations**, no auth, no per-user state.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/wallet/packages
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type WalletPackages = {
      packages: number[];
      min: number;
      max: number;
      currency: string;
    };

    async function getWalletPackages(): Promise<WalletPackages> {
      const res = await fetch('https://api.bio.re/api/v1/wallet/packages');
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Wallet packages fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const walletKeys = {
      packages: () => ['wallet', 'packages'] as const,
    };

    export function useWalletPackages() {
      return useQuery({
        queryKey: walletKeys.packages(),
        queryFn: async () => {
          const res = await fetch('/api/v1/wallet/packages');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Wallet packages fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as WalletPackages;
        },
        // Catalog rarely changes within a session
        staleTime: 5 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/wallet/packages', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                           | Lines                                                                                              |
| -------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/payment/wallet.controller.ts`       | `21–28` (`getPackages`)                                                                            |
| DTO (response) | `apps/api-core/src/modules/payment/dto/wallet-response.dto.ts` | `9–22` (`WalletPackagesResponseDto`)                                                               |
| Service        | `apps/api-core/src/modules/payment/wallet.service.ts`          | `34–40` (`getLoadPackages`)                                                                        |
| Config keys    | `apps/api-core/src/modules/config/config.service.ts`           | `wallet.load_packages`, `wallet.min_load`, `wallet.max_load`, `wallet.max_balance` (admin-managed) |
| Kill switch    | `apps/api-core/src/common/guards/kill-switch.guard.ts`         | `RequireKillSwitch('PAYMENT')` (class-level)                                                       |


# Get Payout Report (/docs/payout/report)



`GET /api/v1/payouts/report` — 🔑 **Bearer**

Returns the creator's own payout history for the lifetime of the account or for a specific month. The response includes the raw rows (newest first, capped at 500), a sum of amounts as a number, and a count of rows returned. &#x2A;*Every payout — regardless of status (`PENDING` / `APPROVED` / `PROCESSING` / `PROCESSED` / `FAILED` / `CANCELLED` / `REJECTED`) — is included in `total`.**



<Callout type="warn">
  **`total` sums ALL statuses, not just successfully paid out.** The aggregate is `payouts.reduce((sum, p) => sum + p.amount, 0)` over the **unfiltered** result set — `REJECTED` and `CANCELLED` rows count toward the sum. If you want "actually paid out," filter by `status === 'PROCESSED'` client-side and sum yourself.
</Callout>

<Callout type="warn">
  **Hard cap of 500 rows.** `take: 500` — no pagination. If a creator has more than 500 payouts in the queried window, the older rows are silently dropped. In practice this is unlikely for an individual creator, but for `?month=` queries you'll get every row in the month up to 500.
</Callout>

<Callout type="info">
  **`month` is strictly validated.** Format must match `^\d{4}-(0[1-9]|1[0-2])$` — e.g. `2026-04`. Anything else (`?month=2026/04`, `?month=2026-13`, `?month=April`) → `400 payment.payout.error.invalid_month`. Without `?month`, the report covers all-time.
</Callout>

<Callout type="warn">
  **Kill-switchable.** Class is decorated with `@RequireKillSwitch('PAYOUT')` — when admin engages the `kill_switch.PAYOUT` config, this read endpoint returns `503` too (the switch is class-wide, not per-handler).
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param   | Type   | Required | Notes                                                                                                                                    |
| ------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `month` | string | optional | `YYYY-MM` format (e.g. `2026-04`). Strictly validated server-side; mismatch → `400`. Filters `createdAt >= 2026-04-01 AND < 2026-05-01`. |

### Headers [#headers]

| Header                                | Required | Notes                                                   |
| ------------------------------------- | -------- | ------------------------------------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | Global `JwtAuthGuard`. Creator identity comes from JWT. |

## Response [#response]

### `200 OK` — `ApiResponseOf<PayoutReportResponseDto>` [#200-ok--apiresponseofpayoutreportresponsedto]

```json
{
  "success": true,
  "data": {
    "payouts": [
      {
        "id": "po-uuid-1",
        "creatorId": "cr-uuid-1",
        "amount": "50.00",
        "method": "STRIPE_CONNECT",
        "status": "PROCESSED",
        "createdAt": "2026-04-20T09:00:00.000Z",
        "approvedAt": "2026-04-20T11:00:00.000Z",
        "processedAt": "2026-04-21T08:00:00.000Z",
        "stripePayoutId": "po_1ABC...",
        "commissionRate": 20,
        "commissionAmount": "10.00",
        "netAmount": "40.00"
      }
    ],
    "total": 50,
    "count": 1
  }
}
```

### Top-level fields [#top-level-fields]

| Field     | Type   | Notes                                                                                                          |
| --------- | ------ | -------------------------------------------------------------------------------------------------------------- |
| `payouts` | array  | Up to 500 rows, newest first. `PayoutRequest` shape (see below).                                               |
| `total`   | number | Sum of `payouts[].amount` as JS `number` (via `Decimal.toNumber()`). **Sums every status** — see warn callout. |
| `count`   | number | `payouts.length`. Capped at 500 — equals length, not "total matching rows in DB."                              |

### Item fields (`payouts[]`) [#item-fields-payouts]

| Field              | Type                      | Notes                                                                                             |
| ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------- |
| `id`               | string (UUID)             | `PayoutRequest.id`.                                                                               |
| `creatorId`        | string (UUID)             | `CreatorProfile.id` — always your own.                                                            |
| `amount`           | string                    | `Decimal(10, 2)` serialized as a string (e.g. `"50.00"`). Parse with `Number()` or a decimal lib. |
| `method`           | enum                      | `STRIPE_CONNECT` / `BANK_TRANSFER`.                                                               |
| `status`           | enum                      | `PENDING` / `APPROVED` / `PROCESSING` / `PROCESSED` / `FAILED` / `CANCELLED` / `REJECTED`.        |
| `createdAt`        | string (ISO 8601)         | When the request was made.                                                                        |
| `approvedAt`       | string (ISO 8601) \| null | When admin approved. `null` for `PENDING` / `REJECTED`.                                           |
| `processedAt`      | string (ISO 8601) \| null | When the actual payout cleared. `null` until `PROCESSED`.                                         |
| `stripePayoutId`   | string \| null            | Stripe payout id (only for `STRIPE_CONNECT` payouts that reached `PROCESSING+`).                  |
| `commissionRate`   | number \| null            | Commission percentage applied (e.g. `20` = 20%). Persisted at approval time for audit.            |
| `commissionAmount` | string \| null            | `Decimal(10, 2)` as string — commission deducted.                                                 |
| `netAmount`        | string \| null            | `Decimal(10, 2)` as string — `amount - commissionAmount`.                                         |

### Errors [#errors]

| HTTP  | `i18nKey`                                | When                                                                                                  |              |
| ----- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------ |
| `400` | `payment.payout.error.invalid_month`     | `?month=...` doesn't match \`^\d{4}-(0\[1-9]                                                          | 1\[0-2])$\`. |
| `401` | (guard)                                  | Missing / invalid bearer token.                                                                       |              |
| `404` | `payment.payout.error.profile_not_found` | The authenticated user has no `CreatorProfile` (controller resolves this before calling the service). |              |
| `503` | (kill switch)                            | `kill_switch.PAYOUT` is engaged.                                                                      |              |

## Side effects [#side-effects]

1. `KillSwitchGuard` (`PAYOUT` system); engaged → `503`.
2. `JwtAuthGuard` (global). `userId = req.user.id`.
3. **Controller** resolves the creator: `prisma.creatorProfile.findUnique({ where: { userId } })`. Missing → `404 profile_not_found`.
4. **Service** `getPayoutReport(creator.id, month?)`:
   * If `month` set, validate regex; build `where.createdAt = { gte: firstDayOfMonth, lt: firstDayOfNextMonth }`. (Boundaries computed in the API server's local time zone via `new Date(year, m - 1, 1)`.)
   * `prisma.payoutRequest.findMany({ where, orderBy: { createdAt: 'desc' }, take: 500 })`.
   * `total = sum(amount)` as `Decimal.toNumber()`.
5. Return `{ payouts, total, count: payouts.length }`. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl (all-time)', 'curl (by month)', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl (all-time)">
    ```bash
    curl https://api.bio.re/api/v1/payouts/report \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="curl (by month)">
    ```bash
    curl 'https://api.bio.re/api/v1/payouts/report?month=2026-04' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type PayoutStatus =
      | 'PENDING' | 'APPROVED' | 'PROCESSING' | 'PROCESSED'
      | 'FAILED' | 'CANCELLED' | 'REJECTED';

    type PayoutReportItem = {
      id: string;
      creatorId: string;
      amount: string;            // Decimal as string
      method: 'STRIPE_CONNECT' | 'BANK_TRANSFER';
      status: PayoutStatus;
      createdAt: string;
      approvedAt: string | null;
      processedAt: string | null;
      stripePayoutId: string | null;
      commissionRate: number | null;
      commissionAmount: string | null;
      netAmount: string | null;
    };

    type PayoutReport = {
      payouts: PayoutReportItem[];
      total: number;             // sums ALL statuses
      count: number;
    };

    async function getPayoutReport(
      accessToken: string,
      month?: string,            // YYYY-MM
    ): Promise<PayoutReport> {
      const url = new URL('https://api.bio.re/api/v1/payouts/report');
      if (month) url.searchParams.set('month', month);

      const res = await fetch(url, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Report failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }

    // "Actually paid out" — server's `total` includes rejected/cancelled, so derive yourself:
    function actuallyPaid(report: PayoutReport): number {
      return report.payouts
        .filter(p => p.status === 'PROCESSED')
        .reduce((s, p) => s + Number(p.netAmount ?? p.amount), 0);
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const payoutKeys = {
      report: (month?: string) => ['payout', 'report', month ?? 'all'] as const,
    };

    export function usePayoutReport(month?: string) {
      return useQuery({
        queryKey: payoutKeys.report(month),
        queryFn: async () => {
          const url = new URL('/api/v1/payouts/report', location.origin);
          if (month) url.searchParams.set('month', month);
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Report failed'), {
              code: json?.error?.code,
            });
          }
          return json.data as PayoutReport;
        },
        staleTime: 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/payouts/report', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                 | Lines                                                                                           |
| -------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/payout/payout.controller.ts`              | `43–53` (`getReport` — creator lookup + month forwarding)                                       |
| DTO (response) | `apps/api-core/src/modules/payout/dto/payout-client-response.dto.ts` | `15–65` (`PayoutReportResponseDto`, `PayoutReportItemDto`)                                      |
| Service        | `apps/api-core/src/modules/payout/payout.service.ts`                 | `524–537` (`getPayoutReport` — month regex validation, 500-row cap, total sum)                  |
| Kill switch    | `apps/api-core/src/common/guards/kill-switch.guard.ts`               | `17–33` (`@RequireKillSwitch`)                                                                  |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                               | `PayoutRequest` lines `1183–1210`, `PayoutStatus` enum `772–781`, `PayoutMethod` enum `783–786` |


# Request a Payout (/docs/payout/request)



`POST /api/v1/payouts/request` — 🔑 **Bearer**

Initiates a payout from the authenticated creator's wallet. The endpoint runs a long chain of pre-conditions before writing — KYC + tax form must be approved, the chosen payout method must be ready, the wallet must have enough headroom (balance minus any outstanding requests), and the per-creator cooldown must have elapsed. **All checks happen on the request path** — by the time `201` returns, the row is in the DB at `PENDING`.



<Callout type="warn">
  **12 pre-conditions before any DB write.** This is a high-stakes financial endpoint, so the service refuses to create the `PayoutRequest` row until every check passes. Read the [Errors](#errors) table — each `i18nKey` corresponds to one specific check, and the order they fire is documented in [Side effects](#side-effects). Surface the right localized message per code; "insufficient balance" is the wrong copy for "KYC required."
</Callout>

<Callout type="warn">
  **Kill-switchable.** Class is decorated with `@RequireKillSwitch('PAYOUT')`. When the admin flips the `kill_switch.PAYOUT` config, this endpoint returns `503` (no request even reaches the service) — show "Payouts temporarily unavailable" on the user side. Same applies to `GET /payouts/report` — the kill switch is class-wide.
</Callout>

<Callout type="warn">
  **Outstanding payouts are subtracted from your available balance.** Server-side aggregate of `PENDING + APPROVED` payouts for this creator is deducted from `wallet.balance` before the amount check. Two requests for `$100` against a `$150` wallet won't both succeed — the second sees `availableBalance = $50`. `PROCESSING` is excluded because the wallet has already been debited at that stage.
</Callout>

<Callout type="info">
  **Cooldown is the effective frequency cap.** `payout.cooldown_days` (admin-managed, default `7`) — the next request after a non-`REJECTED` payout fails with `frequency_limit` until that many days elapse. There's a `VelocityCheckGuard` on this endpoint as well (config keys `fraud.payout_window_days` / `fraud.max_weekly_payouts`); when it rejects, the response carries `error.guard.payout_limit`. &#x2A;*Show the right copy for whichever fires.**
</Callout>

## Request [#request]

### Body — `RequestPayoutDto` [#body--requestpayoutdto]

| Field    | Type   | Required | Validation                                                  | Notes                                                                                                                              |
| -------- | ------ | -------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `amount` | string | ✓        | Regex `^\d+(\.\d{1,2})?$`                                   | Decimal as string (e.g. `"50.00"`). Server parses with `Prisma.Decimal`. &#x2A;*Must be ≥ `$1`** (separately enforced in service). |
| `method` | enum   | ✓        | `IsEnum(PayoutMethod)` — `STRIPE_CONNECT` / `BANK_TRANSFER` | Determines which payout-method checks run (see Side effects steps 4–5).                                                            |

### Headers [#headers]

| Header                                | Required | Notes                                                                  |
| ------------------------------------- | -------- | ---------------------------------------------------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | Global `JwtAuthGuard`. Creator identity comes from JWT — not the body. |
| `Content-Type: application/json`      | ✓        | Standard.                                                              |

## Response [#response]

### `201 Created` — `ApiResponseOf<RequestPayoutResponseDto>` [#201-created--apiresponseofrequestpayoutresponsedto]

```json
{
  "success": true,
  "data": {
    "payoutId": "po-uuid-..."
  }
}
```

| Field      | Type          | Notes                                                                                                                                                                         |
| ---------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payoutId` | string (UUID) | Server-generated `randomUUID()`. Use it to look the request up in [`GET /payouts/report`](/docs/payout/report) — the row is at `status: 'PENDING'` until an admin acts on it. |

After `201`:

* A `PayoutRequest` row exists at `PENDING`. It will move to `APPROVED` → `PROCESSING` → `PROCESSED` (or `FAILED` / `REJECTED`) via admin action.
* A fire-and-forget `payout_requested` notification is queued for the creator. Failures are logged, not surfaced.
* The creator's available balance for **subsequent** requests is reduced by this amount (still in their wallet — but counted against future requests).

### Errors [#errors]

| HTTP  | `i18nKey`                                      | When                                                                                                                                   |
| ----- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `payment.payout.error.kyc_required`            | `creator.kycStatus !== APPROVED`.                                                                                                      |
| `400` | `payment.payout.error.tax_form_required`       | No `TaxForm` row with `status = APPROVED` for this creator.                                                                            |
| `400` | `payment.payout.error.stripe_not_connected`    | `method = STRIPE_CONNECT` and creator has no `stripeAccountId`.                                                                        |
| `400` | `payment.payout.error.stripe_not_active`       | Stripe account exists but `stripeAccountStatus !== ACTIVE`.                                                                            |
| `400` | `payment.payout.error.stripe_payouts_disabled` | Stripe account active but `stripePayoutsEnabled = false`.                                                                              |
| `400` | `payment.payout.error.bank_iban_required`      | `method = BANK_TRANSFER` and creator has no `iban`.                                                                                    |
| `400` | `payment.payout.error.bank_holder_required`    | Bank transfer but no `accountHolderName`.                                                                                              |
| `400` | `payment.payout.error.bank_not_verified`       | Bank fields set but `bankAccountVerified = false`.                                                                                     |
| `400` | `payment.payout.error.wallet_frozen`           | Creator wallet has `frozen = true`.                                                                                                    |
| `400` | `payment.payout.error.wallet_in_debt`          | Wallet `balance < 0`. Payload: `{ debt }` (absolute value).                                                                            |
| `400` | `payment.payout.error.minimum_amount`          | Wallet balance below `payout.min_amount` config (default `10`) **OR** request amount below `$1`. Payload: `{ minPayout }`.             |
| `400` | `payment.payout.error.insufficient_balance`    | `amount > balance − sum(PENDING+APPROVED outstanding)`.                                                                                |
| `400` | `payment.payout.error.frequency_limit`         | Last non-`REJECTED` payout was less than `payout.cooldown_days` (default `7`) ago.                                                     |
| `400` | `error.guard.payout_limit`                     | `VelocityCheckGuard` rejected. Reads `fraud.payout_window_days` / `fraud.max_weekly_payouts`. &#x2A;*Also creates a `FraudFlag` row.** |
| `400` | (DTO validation)                               | `amount` regex mismatch, `method` not in enum.                                                                                         |
| `401` | (guard)                                        | Missing / invalid bearer token.                                                                                                        |
| `404` | `payment.payout.error.profile_not_found`       | The authenticated user has no `CreatorProfile`.                                                                                        |
| `404` | `payment.payout.error.wallet_not_found`        | Creator profile exists but the `CREATOR`-type wallet doesn't (data integrity issue).                                                   |
| `503` | (kill switch)                                  | `kill_switch.PAYOUT` is engaged.                                                                                                       |

## Side effects [#side-effects]

In order — first failing check throws, no later check runs, **no DB write happens until step 13**:

1. `KillSwitchGuard` reads `kill_switch.PAYOUT` from admin config; engaged → `503`.
2. `JwtAuthGuard` (global). `userId = req.user.id`.
3. `VelocityCheckGuard`: count non-`REJECTED` payouts in the last `fraud.payout_window_days`; if ≥ `fraud.max_weekly_payouts`, **create a `FraudFlag` row** and throw `400 error.guard.payout_limit`.
4. Resolve `CreatorProfile` by `userId` → `404 profile_not_found`.
5. **KYC check**: `kycStatus === APPROVED` → else `400 kyc_required`.
6. **Tax form check**: at least one `TaxForm` with `status = APPROVED` for this creator → else `400 tax_form_required`.
7. **Method-specific readiness**:
   * `STRIPE_CONNECT`: `stripeAccountId` set, `stripeAccountStatus = ACTIVE`, `stripePayoutsEnabled = true` (3 separate checks, distinct error codes).
   * `BANK_TRANSFER`: `iban` set, `accountHolderName` set, `bankAccountVerified = true` (3 separate checks).
8. Resolve `CREATOR`-type wallet by `userId` → `404 wallet_not_found`.
9. **Wallet status**: `frozen === false` → else `400 wallet_frozen`. `balance >= 0` → else `400 wallet_in_debt`.
10. **Minimum balance**: `balance >= payout.min_amount` (admin config, default `10`) → else `400 minimum_amount`.
11. **Minimum amount**: `amount >= 1` → else `400 minimum_amount`.
12. **Available balance**: aggregate `sum(amount)` of this creator's payouts in `[PENDING, APPROVED]` (NOT `PROCESSING`); compute `available = balance - outstanding`; require `amount <= available` → else `400 insufficient_balance`.
13. **Cooldown**: read most recent non-`REJECTED` payout; if `(createdAt + cooldown_days) > now` → `400 frequency_limit`.
14. **Write**: `prisma.payoutRequest.create({ data: { id: randomUUID(), creatorId, amount: Decimal(amount), method, status: 'PENDING' } })`.
15. **Fire-and-forget notification**: `notificationService.send({ eventKey: 'payout_requested', userId, variables: { amount, method } })` — failures logged.
16. Increment `payoutRequestedTotal` Prometheus counter.
17. Return `{ payoutId }`.

## Code samples [#code-samples]



<Tabs items="['curl (Stripe)', 'curl (bank transfer)', 'TypeScript fetch', 'TanStack Query (mutation)']">
  <Tab value="curl (Stripe)">
    ```bash
    curl -X POST https://api.bio.re/api/v1/payouts/request \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "amount": "50.00",
        "method": "STRIPE_CONNECT"
      }'
    ```
  </Tab>

  <Tab value="curl (bank transfer)">
    ```bash
    curl -X POST https://api.bio.re/api/v1/payouts/request \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "amount": "100.00",
        "method": "BANK_TRANSFER"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type PayoutMethod = 'STRIPE_CONNECT' | 'BANK_TRANSFER';

    async function requestPayout(
      accessToken: string,
      amount: string,                  // e.g. "50.00"
      method: PayoutMethod,
    ): Promise<{ payoutId: string }> {
      const res = await fetch('https://api.bio.re/api/v1/payouts/request', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ amount, method }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        // Discriminate per i18nKey for correct user-facing copy.
        throw Object.assign(new Error(json?.error?.message ?? 'Payout failed'), {
          code: json?.error?.code,
          i18nKey: json?.error?.i18nKey,
          status: res.status,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query (mutation)">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useRequestPayout() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (input: { amount: string; method: PayoutMethod }) => {
          const res = await fetch('/api/v1/payouts/request', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Payout failed'), {
              i18nKey: json?.error?.i18nKey,
              status: res.status,
            });
          }
          return json.data as { payoutId: string };
        },
        onSuccess: () => {
          // The new PENDING payout shifts the available-balance math —
          // refetch the wallet view AND the report so both reflect reality.
          qc.invalidateQueries({ queryKey: ['payout', 'report'] });
          qc.invalidateQueries({ queryKey: ['wallet'] });
        },
        // Don't auto-retry — the user needs to see the rejection reason.
        retry: false,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/payouts/request', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                 | Lines                                                                                                                                                                                                                                                          |
| -------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/payout/payout.controller.ts`              | `24–54` (class), `32–41` (`requestPayout`)                                                                                                                                                                                                                     |
| DTO (request)  | `apps/api-core/src/modules/payout/dto/index.ts`                      | `6–12` (`RequestPayoutDto`)                                                                                                                                                                                                                                    |
| DTO (response) | `apps/api-core/src/modules/payout/dto/payout-client-response.dto.ts` | `8–11` (`RequestPayoutResponseDto`)                                                                                                                                                                                                                            |
| Service        | `apps/api-core/src/modules/payout/payout.service.ts`                 | `32–111` (`requestPayout` — full pre-condition chain)                                                                                                                                                                                                          |
| Velocity guard | `apps/api-core/src/common/guards/velocity-check.guard.ts`            | `19–74` (`checkPayoutVelocity`)                                                                                                                                                                                                                                |
| Kill switch    | `apps/api-core/src/common/guards/kill-switch.guard.ts`               | `17–33` (`@RequireKillSwitch` + guard)                                                                                                                                                                                                                         |
| Config keys    | (admin-managed via `ConfigService`)                                  | `payout.min_amount` (default `10`), `payout.cooldown_days` (default `7`), `fraud.payout_window_days` (default `7`), `fraud.max_weekly_payouts` (default `3`), `kill_switch.PAYOUT`                                                                             |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                               | `PayoutRequest` lines `1183–1210`, `PayoutStatus` enum `772–781`, `PayoutMethod` enum `783–786`, `CreatorProfile.kycStatus / stripeAccountStatus / iban / bankAccountVerified` (`315–351`), `Wallet` (frozen/balance fields), `TaxForm` (status APPROVED gate) |


# Clear Read Notifications (/docs/notification/clear-read)



`DELETE /api/v1/notifications/clear-read` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Bulk-deletes **every read notification** (`read = true`) for the calling user via a single `deleteMany`. Unread rows are untouched. Returns the count actually deleted (zero is a normal result if nothing was read yet).



<Callout type="warn">
  **Hard delete, no undo.** This is the bulk equivalent of `DELETE /notifications/:id` for read items. Once deleted, the rows are gone — no recycle bin. If you want to keep a "see all" feed, don't expose this as a one-click action; gate it behind a confirm dialog.
</Callout>

<Callout type="info">
  **No filtering parameters.** This endpoint deletes **all read** notifications. There is no "delete read older than N days" or "delete read for event X". For scoped deletes, iterate `DELETE /:id` per item from the filtered list.
</Callout>

## Request [#request]

No body, no params. Identity comes from the bearer token.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<ClearReadResponseDto>` [#200-ok--apiresponseofclearreadresponsedto]

```json
{
  "success": true,
  "data": {
    "deleted": 12
  }
}
```

| Field     | Type   | Notes                                                        |
| --------- | ------ | ------------------------------------------------------------ |
| `deleted` | number | Count of read rows actually removed. `0` is a normal result. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `401` | (guard)            | Missing / invalid bearer token   |
| `429` | (throttle)         | Rate limit exceeded (60 req/min) |

## Side effects [#side-effects]

1. `prisma.notification.deleteMany({ where: { userId, read: true } })`.
2. Return `{ deleted: result.count }`.
3. **Unread rows are not touched** (filter excludes them).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X DELETE https://api.bio.re/api/v1/notifications/clear-read \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function clearReadNotifications(accessToken: string): Promise<number> {
      const res = await fetch('https://api.bio.re/api/v1/notifications/clear-read', {
        method: 'DELETE',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Clear read failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.deleted as number;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useClearReadNotifications() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/notifications/clear-read', { method: 'DELETE' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Clear read failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.deleted as number;
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['notifications'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/notifications/clear-read', method: 'delete' }]" hasHead="false" />

## Source [#source]

| Source                   | Path                                                                             | Lines                                                           |
| ------------------------ | -------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Controller (inline impl) | `apps/api-core/src/modules/notification/user-notification.controller.ts`         | `184–193` (`clearReadNotifications` — direct Prisma deleteMany) |
| DTO (response)           | `apps/api-core/src/modules/notification/dto/notification-client-response.dto.ts` | `87–90` (`ClearReadResponseDto`)                                |
| Prisma model             | `packages/prisma/prisma/schema.prisma`                                           | `Notification`                                                  |


# Delete Notification (/docs/notification/delete)



`DELETE /api/v1/notifications/:id` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Hard-deletes a single notification row. **Ownership is enforced** via `findFirst({ id, userId })`; missing or cross-user lookups return `404 not_found` (same code — no enumeration leak).



<Callout type="warn">
  **Hard delete, no undo.** Once gone, the row is gone — there's no recycle bin or "deleted" flag. To bulk-clear notifications you've already read, use `DELETE /notifications/clear-read` instead (covered in Batch 2).
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param | Type          | Validation      | Notes                      |
| ----- | ------------- | --------------- | -------------------------- |
| `id`  | string (UUID) | `ParseUUIDPipe` | The notification to delete |

No body.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                |
| --------- | ------- | -------------------- |
| `success` | boolean | Always `true` on 200 |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`             | Reason                                                                       |
| ----- | ------------------------------ | ---------------------------------------------------------------------------- |
| `400` | (validation)                   | `id` not a valid UUID                                                        |
| `401` | (guard)                        | Missing / invalid bearer token                                               |
| `404` | `error.notification.not_found` | Notification not found OR belongs to a different user (same code on purpose) |
| `429` | (throttle)                     | Rate limit exceeded (60 req/min)                                             |

## Side effects [#side-effects]

1. **Ownership-aware lookup** — `prisma.notification.findFirst({ where: { id, userId } })`. Returns `null` for missing OR cross-user → throw `not_found`.
2. `prisma.notification.delete({ where: { id } })`.
3. Return `{ success: true }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X DELETE https://api.bio.re/api/v1/notifications/n1a2b3c4-d5e6-7890-abcd-ef1234567890 \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function deleteNotification(accessToken: string, notificationId: string): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/notifications/${notificationId}`, {
        method: 'DELETE',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Delete failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useDeleteNotification() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (notificationId: string) => {
          const res = await fetch(`/api/v1/notifications/${notificationId}`, { method: 'DELETE' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Delete failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['notifications'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/notifications/{id}', method: 'delete' }]" hasHead="false" />

## Source [#source]

| Source                   | Path                                                                     | Lines                                                                       |
| ------------------------ | ------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| Controller (inline impl) | `apps/api-core/src/modules/notification/user-notification.controller.ts` | `196–210` (`deleteNotification` — direct Prisma, ownership-aware findFirst) |
| DTO (response)           | `apps/api-core/src/common/dto/common-response.dto.ts`                    | `SuccessOnlyResponseDto`                                                    |
| Prisma model             | `packages/prisma/prisma/schema.prisma`                                   | `Notification`                                                              |


# List Notifications (/docs/notification/list)



`GET /api/v1/notifications` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Paginated list of the calling user's in-app notifications, ordered by `createdAt DESC`. Optional `?read=true|false` filter. Each item includes the structured `data` payload (e.g. `messageId`, `deepLink`) so the UI can render contextual actions without an extra round-trip.



<Callout type="info">
  **Notifications are dispatched server-side per event** (e.g. `new_message_creator`, `payout_processed`, `message_replied_fan`, `email_subscription_confirm`). The `data` payload shape varies per `eventKey` — frontend should branch on `eventKey` (not on `data` field presence) when deciding what to render.
</Callout>

<Callout type="warn">
  **No service layer.** This endpoint is implemented directly in the controller via Prisma — no separate service method. Performance is bound by the indexed `(userId, createdAt DESC)` query.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param   | Type   | Default | Validation                                                                              | Notes                         |
| ------- | ------ | ------- | --------------------------------------------------------------------------------------- | ----------------------------- |
| `read`  | string | —       | accepts `'true'` or `'false'` literal strings (anything else falls back to "no filter") | Filter to read or unread only |
| `page`  | number | `1`     | `parseInt`, server-clamped to `>= 1`                                                    | 1-based page index            |
| `limit` | number | `20`    | `parseInt`, server-clamped to `[1, 50]`                                                 | Items per page                |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `PaginatedApiResponseOf<NotificationItemDto>` [#200-ok--paginatedapiresponseofnotificationitemdto]

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "n1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "eventKey": "new_message_creator",
        "title": "New message from John",
        "body": "Hey, loved your latest post!",
        "data": {
          "messageId": "m1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "senderName": "John",
          "dmType": "SINGLE_PAY",
          "deepLink": "/messages/s1a2b3c4-d5e6-7890-abcd-ef1234567890"
        },
        "read": false,
        "readAt": null,
        "createdAt": "2026-04-29T20:00:00.000Z"
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}
```

### Item fields [#item-fields]

| Field       | Type                      | Notes                                                                                                                                                                                                 |
| ----------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | string (UUID)             | `Notification.id`                                                                                                                                                                                     |
| `eventKey`  | string                    | Event identifier (e.g. `new_message_creator`, `message_replied_fan`, `payout_processed`, `message_rejected_refunded`, `message_expired`, `email_subscription_confirm`). Branch on this for rendering. |
| `title`     | string                    | Server-rendered title (localized server-side via the notification template)                                                                                                                           |
| `body`      | string                    | Server-rendered body (localized server-side; may include placeholders pre-filled via `variables`)                                                                                                     |
| `data`      | object \| null            | Free-form JSON payload — shape varies per `eventKey`. Common keys: `messageId`, `deepLink`, `creatorName`, `amount`. **Do not assume any field is present**; check before use.                        |
| `read`      | boolean                   | Read state                                                                                                                                                                                            |
| `readAt`    | string (ISO 8601) \| null | When marked read; `null` while unread                                                                                                                                                                 |
| `createdAt` | string (ISO 8601)         | Notification creation timestamp                                                                                                                                                                       |

### Top-level fields [#top-level-fields]

| Field                           | Type   | Notes                                                    |
| ------------------------------- | ------ | -------------------------------------------------------- |
| `items`                         | array  | Up to `limit` notifications, ordered by `createdAt DESC` |
| `total`                         | number | Total matching the read filter                           |
| `page` / `limit` / `totalPages` | number | Echoed pagination metadata                               |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `401` | (guard)            | Missing / invalid bearer token   |
| `429` | (throttle)         | Rate limit exceeded (60 req/min) |

## Side effects [#side-effects]

1. Build `where = { userId }` + optional `read: true|false` filter.
2. **In parallel**: `notification.findMany({ where, skip, take, orderBy createdAt desc })` + `notification.count({ where })`.
3. Map rows to plain objects (avoid Prisma runtime types leaking) with the 8-field client-facing slice.
4. Return paginated envelope. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    # All notifications
    curl 'https://api.bio.re/api/v1/notifications?page=1&limit=20' \
      -H "Authorization: Bearer $ACCESS_TOKEN"

    # Unread only
    curl 'https://api.bio.re/api/v1/notifications?read=false' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type NotificationItem = {
      id: string;
      eventKey: string;
      title: string;
      body: string;
      data: Record<string, unknown> | null;
      read: boolean;
      readAt: string | null;
      createdAt: string;
    };

    type Paginated<T> = {
      items: T[];
      total: number;
      page: number;
      limit: number;
      totalPages: number;
    };

    async function listNotifications(
      accessToken: string,
      filter: { read?: boolean; page?: number; limit?: number } = {},
    ): Promise<Paginated<NotificationItem>> {
      const url = new URL('https://api.bio.re/api/v1/notifications');
      if (filter.read !== undefined) url.searchParams.set('read', String(filter.read));
      if (filter.page) url.searchParams.set('page', String(filter.page));
      if (filter.limit) url.searchParams.set('limit', String(filter.limit));
      const res = await fetch(url, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Notifications fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery, keepPreviousData } from '@tanstack/react-query';

    export const notificationKeys = {
      list: (filter: { read?: boolean; page?: number; limit?: number }) =>
        ['notifications', 'list', filter] as const,
    };

    export function useNotifications(filter: {
      read?: boolean;
      page?: number;
      limit?: number;
    } = {}) {
      return useQuery({
        queryKey: notificationKeys.list(filter),
        queryFn: async () => {
          const url = new URL('/api/v1/notifications', window.location.origin);
          if (filter.read !== undefined) url.searchParams.set('read', String(filter.read));
          if (filter.page) url.searchParams.set('page', String(filter.page));
          if (filter.limit) url.searchParams.set('limit', String(filter.limit));
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Notifications fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as Paginated<NotificationItem>;
        },
        placeholderData: keepPreviousData,
        staleTime: 10_000, // refresh frequently — server pushes events constantly
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/notifications', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source                   | Path                                                                             | Lines                                                  |
| ------------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------ |
| Controller (inline impl) | `apps/api-core/src/modules/notification/user-notification.controller.ts`         | `41–77` (`list` — direct Prisma, no service)           |
| DTO (response item)      | `apps/api-core/src/modules/notification/dto/notification-client-response.dto.ts` | `8–32` (`NotificationItemDto`)                         |
| Prisma model             | `packages/prisma/prisma/schema.prisma`                                           | `Notification` (composite index `(userId, createdAt)`) |


# Mark Notification Read (/docs/notification/mark-read)



`PATCH /api/v1/notifications/:id/read` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Marks a single notification as read. **Ownership is enforced** via `findFirst({ id, userId })`; missing or cross-user lookups return `404 not_found` (same code — no enumeration leak between "doesn't exist" and "not yours").



<Callout type="info">
  **Idempotent re-read.** Re-marking an already-read notification refreshes the `readAt` timestamp to the new "read again" moment. The `read` flag stays `true`. If you only want to mark unread→read once, gate client-side off the existing `read: true` value before issuing the call.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param | Type          | Validation      | Notes                         |
| ----- | ------------- | --------------- | ----------------------------- |
| `id`  | string (UUID) | `ParseUUIDPipe` | The notification to mark read |

No body.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                                                                                                                     |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `success` | boolean | Always `true` on 200. Re-fetch the list / unread count to see the post-write state, or update local cache optimistically. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`             | Reason                                                                       |
| ----- | ------------------------------ | ---------------------------------------------------------------------------- |
| `400` | (validation)                   | `id` not a valid UUID                                                        |
| `401` | (guard)                        | Missing / invalid bearer token                                               |
| `404` | `error.notification.not_found` | Notification not found OR belongs to a different user (same code on purpose) |
| `429` | (throttle)                     | Rate limit exceeded (60 req/min)                                             |

## Side effects [#side-effects]

1. **Ownership-aware lookup** — `prisma.notification.findFirst({ where: { id, userId } })`. Returns `null` for missing OR cross-user → throw `not_found`.
2. `prisma.notification.update({ where: { id }, data: { read: true, readAt: new Date() } })`.
3. Return `{ success: true }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X PATCH https://api.bio.re/api/v1/notifications/n1a2b3c4-d5e6-7890-abcd-ef1234567890/read \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function markNotificationRead(accessToken: string, notificationId: string): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/notifications/${notificationId}/read`, {
        method: 'PATCH',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Mark read failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useMarkNotificationRead() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (notificationId: string) => {
          const res = await fetch(`/api/v1/notifications/${notificationId}/read`, {
            method: 'PATCH',
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Mark read failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        // Optimistic UI: flip local state, invalidate on success
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['notifications'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/notifications/{id}/read', method: 'patch' }]" hasHead="false" />

## Source [#source]

| Source                   | Path                                                                     | Lines                                                            |
| ------------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| Controller (inline impl) | `apps/api-core/src/modules/notification/user-notification.controller.ts` | `90–104` (`markRead` — direct Prisma, ownership-aware findFirst) |
| DTO (response)           | `apps/api-core/src/common/dto/common-response.dto.ts`                    | `SuccessOnlyResponseDto`                                         |
| Prisma model             | `packages/prisma/prisma/schema.prisma`                                   | `Notification.read`, `Notification.readAt`                       |


# Update Notification Preference (/docs/notification/preferences-update)



`PATCH /api/v1/notifications/preferences/:eventKey` — 🔑 **Bearer** · Rate limit: **30 req / minute**

Upserts the user's `NotificationPreference` row for a single `eventKey`. Only the channel booleans you supply are touched (sparse update); on first write, missing channels default to `true`. The server validates that `eventKey` exists in the admin-managed `NotificationDefault` catalog (else `404 event_not_found`).



<Callout type="warn">
  **`true` is the create default.** When this is the user's first save for an `eventKey` (no override row yet), every channel you don't explicitly send defaults to `true`. To opt-out of every channel except email, you must explicitly send `push: false, inApp: false, webPush: false, sms: false` — sending only `email: true` would leave the others enabled.
</Callout>

<Callout type="info">
  **Subsequent updates are sparse.** Once an override row exists, only the channels you send are written. Omitted channels keep their stored values. The asymmetry between "first save = `true` defaults" and "subsequent save = preserve" is a Prisma `upsert` consequence — the `update` branch only touches supplied keys, the `create` branch fills the rest.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param      | Type   | Validation                  | Notes                                                                                                      |
| ---------- | ------ | --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `eventKey` | string | (no UUID pipe — raw string) | Must match a row in `NotificationDefault` (server checks). E.g. `new_message_creator`, `payout_processed`. |

### Body [#body]

A loose object — server uses `class-validator`-free pass-through, but the schema documents 5 boolean channel fields.

| Field     | Type    | Required | Notes                |
| --------- | ------- | -------- | -------------------- |
| `email`   | boolean | optional | Email channel toggle |
| `push`    | boolean | optional | Native push toggle   |
| `inApp`   | boolean | optional | In-app feed toggle   |
| `webPush` | boolean | optional | Web push toggle      |
| `sms`     | boolean | optional | SMS toggle           |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                                                                                                                                           |
| --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `success` | boolean | Always `true` on 200. Re-fetch `GET /notifications/preferences` to read the merged post-write state (the row will now have `customized: true`). |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                   | Reason                                                                |
| ----- | ------------------------------------ | --------------------------------------------------------------------- |
| `401` | (guard)                              | Missing / invalid bearer token                                        |
| `404` | `error.notification.event_not_found` | `eventKey` doesn't match any `NotificationDefault` row (catalog gate) |
| `429` | (throttle)                           | Rate limit exceeded (30 req/min — tighter than other endpoints)       |

## Side effects [#side-effects]

1. **Catalog gate** — `notificationDefault.findUnique({ where: { eventKey } })`. Missing → throw `event_not_found`.
2. **Upsert** — `notificationPreference.upsert({ where: { userId_eventKey }, update: <body>, create: <body with true defaults for unset channels> })`.
3. Return `{ success: true }`. **No notification dispatch effects** — preference takes effect on the NEXT event fired.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    # Disable email for new-message-creator events
    curl -X PATCH https://api.bio.re/api/v1/notifications/preferences/new_message_creator \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"email": false}'

    # Opt-out of every channel except in-app (first save — must be explicit)
    curl -X PATCH https://api.bio.re/api/v1/notifications/preferences/payout_processed \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"email": false, "push": false, "webPush": false, "sms": false, "inApp": true}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type ChannelToggles = {
      email?: boolean;
      push?: boolean;
      inApp?: boolean;
      webPush?: boolean;
      sms?: boolean;
    };

    async function updateNotificationPreference(
      accessToken: string,
      eventKey: string,
      channels: ChannelToggles,
    ): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/notifications/preferences/${eventKey}`, {
        method: 'PATCH',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(channels),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Preference update failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useUpdateNotificationPreference() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (vars: { eventKey: string; channels: ChannelToggles }) => {
          const res = await fetch(`/api/v1/notifications/preferences/${vars.eventKey}`, {
            method: 'PATCH',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(vars.channels),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Preference update failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['notifications', 'preferences'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/notifications/preferences/{eventKey}', method: 'patch' }]" hasHead="false" />

## Source [#source]

| Source                   | Path                                                                     | Lines                                                                                              |
| ------------------------ | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| Controller (inline impl) | `apps/api-core/src/modules/notification/user-notification.controller.ts` | `151–181` (`updatePreference` — catalog gate + Prisma upsert)                                      |
| DTO (response)           | `apps/api-core/src/common/dto/common-response.dto.ts`                    | `SuccessOnlyResponseDto`                                                                           |
| Prisma models            | `packages/prisma/prisma/schema.prisma`                                   | `NotificationDefault` (catalog gate), `NotificationPreference` (compound unique `userId_eventKey`) |


# Get Notification Preferences (/docs/notification/preferences)



`GET /api/v1/notifications/preferences` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Returns the **merged preference matrix** for the calling user. The server reads two tables in parallel — `NotificationDefault` (the admin-managed system defaults for every `eventKey`) and `NotificationPreference` (per-user overrides) — and merges them: each row's per-channel boolean is `userPref ?? defaultPref`. The `customized` flag tells the UI whether the user has saved an explicit override for that `eventKey`.



<Callout type="info">
  **Default-driven catalog.** The set of `eventKey` rows returned is **the union of `NotificationDefault.eventKey` values** (admin-managed). New event types appear here automatically when admin adds them to defaults. The user-prefs table is only used for overrides.
</Callout>

<Callout type="warn">
  **`customized: false` means "uses defaults".** When the user has no `NotificationPreference` row for that `eventKey`, all 5 channel booleans come from the default. When they save an override (via `PATCH /preferences/:eventKey`), `customized` flips to `true` and the channels reflect the override. There's no "reset to defaults" endpoint; manually delete the override row server-side or just save the same values as the defaults.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ArrayApiResponseOf<NotificationPreferenceItemDto>` [#200-ok--arrayapiresponseofnotificationpreferenceitemdto]

```json
{
  "success": true,
  "data": [
    {
      "eventKey": "new_message_creator",
      "email": true,
      "push": true,
      "inApp": true,
      "webPush": true,
      "sms": false,
      "customized": false
    },
    {
      "eventKey": "payout_processed",
      "email": true,
      "push": false,
      "inApp": true,
      "webPush": true,
      "sms": true,
      "customized": true
    }
  ]
}
```

### Item fields [#item-fields]

| Field        | Type    | Notes                                                                                                                                      |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `eventKey`   | string  | Identifier of the notification event (e.g. `new_message_creator`, `message_replied_fan`, `payout_processed`, `email_subscription_confirm`) |
| `email`      | boolean | Email channel enabled (user override or default)                                                                                           |
| `push`       | boolean | Native mobile push channel                                                                                                                 |
| `inApp`      | boolean | In-app feed (the inbox shown by `GET /notifications`)                                                                                      |
| `webPush`    | boolean | Browser web-push channel (subscriptions managed via `/notifications/webpush/*`)                                                            |
| `sms`        | boolean | SMS channel                                                                                                                                |
| `customized` | boolean | `true` when the user has a `NotificationPreference` row for this event (override saved); `false` when the row reflects pure defaults       |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `401` | (guard)            | Missing / invalid bearer token   |
| `429` | (throttle)         | Rate limit exceeded (60 req/min) |

## Side effects [#side-effects]

1. **In parallel**: `notificationPreference.findMany({ where: { userId }, orderBy: eventKey asc })` + `notificationDefault.findMany({ orderBy: eventKey asc })`.
2. Iterate `defaults`: for each, find the matching pref by `eventKey` and merge — `userPref?.channel ?? def.channel` for every channel boolean.
3. `customized = !!pref` (true only when an override row exists).
4. Return the merged array. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/notifications/preferences \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type NotificationPreferenceItem = {
      eventKey: string;
      email: boolean;
      push: boolean;
      inApp: boolean;
      webPush: boolean;
      sms: boolean;
      customized: boolean;
    };

    async function getNotificationPreferences(accessToken: string): Promise<NotificationPreferenceItem[]> {
      const res = await fetch('https://api.bio.re/api/v1/notifications/preferences', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Preferences fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const notificationKeys = {
      preferences: () => ['notifications', 'preferences'] as const,
    };

    export function useNotificationPreferences() {
      return useQuery({
        queryKey: notificationKeys.preferences(),
        queryFn: async () => {
          const res = await fetch('/api/v1/notifications/preferences');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Preferences fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as NotificationPreferenceItem[];
        },
        staleTime: 60_000, // catalog rarely changes within a session
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/notifications/preferences', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source                   | Path                                                                             | Lines                                                                                                               |
| ------------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Controller (inline impl) | `apps/api-core/src/modules/notification/user-notification.controller.ts`         | `121–148` (`getPreferences` — direct Prisma, parallel reads + merge)                                                |
| DTO (response item)      | `apps/api-core/src/modules/notification/dto/notification-client-response.dto.ts` | `59–80` (`NotificationPreferenceItemDto`)                                                                           |
| Prisma models            | `packages/prisma/prisma/schema.prisma`                                           | `NotificationDefault` (admin catalog), `NotificationPreference` (user overrides, compound unique `userId_eventKey`) |


# Mark All Notifications Read (/docs/notification/read-all)



`POST /api/v1/notifications/read-all` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Bulk-marks **all** of the calling user's unread notifications as read in a single `updateMany`. Returns the number of rows actually updated. Server-scopes the update to `userId = caller AND read = false`, so already-read rows are untouched and no other user's data is affected.



<Callout type="info">
  **No filtering parameters.** This endpoint marks **everything unread → read**. There is no "mark by event type" or "mark by date range". If you need scoped clearing, iterate over `PATCH /:id/read` per item from the filtered list.
</Callout>

## Request [#request]

No body, no params. Identity comes from the bearer token.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<MarkAllReadResponseDto>` [#200-ok--apiresponseofmarkallreadresponsedto]

```json
{
  "success": true,
  "data": {
    "updated": 12
  }
}
```

| Field     | Type   | Notes                                                                                                             |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `updated` | number | Count of rows actually flipped from unread → read. `0` is a normal result when there are no unread notifications. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `401` | (guard)            | Missing / invalid bearer token   |
| `429` | (throttle)         | Rate limit exceeded (60 req/min) |

## Side effects [#side-effects]

1. `prisma.notification.updateMany({ where: { userId, read: false }, data: { read: true, readAt: new Date() } })`.
2. Return `{ updated: result.count }`. The same `readAt` timestamp is applied to every row in the batch.
3. **Already-read rows are not touched** (filter excludes them, so their original `readAt` is preserved).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/notifications/read-all \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function markAllNotificationsRead(accessToken: string): Promise<number> {
      const res = await fetch('https://api.bio.re/api/v1/notifications/read-all', {
        method: 'POST',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Mark all read failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.updated as number;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useMarkAllNotificationsRead() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/notifications/read-all', { method: 'POST' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Mark all read failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.updated as number;
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['notifications'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/notifications/read-all', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source                   | Path                                                                             | Lines                                                |
| ------------------------ | -------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Controller (inline impl) | `apps/api-core/src/modules/notification/user-notification.controller.ts`         | `107–118` (`markAllRead` — direct Prisma updateMany) |
| DTO (response)           | `apps/api-core/src/modules/notification/dto/notification-client-response.dto.ts` | `49–52` (`MarkAllReadResponseDto`)                   |
| Prisma model             | `packages/prisma/prisma/schema.prisma`                                           | `Notification.read`, `Notification.readAt`           |


# Unread Notification Count (/docs/notification/unread-count)



`GET /api/v1/notifications/unread-count` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Returns a single integer — the total **unread notifications** for the calling user (`Notification.read = false`). Use to drive navigation / app-icon badges.



<Callout type="info">
  This is the **notification-system** unread count, not the **message** unread count. The two are separate counters on separate tables (`Notification` vs `Message`) — render them as separate badges if you surface both. See [`GET /messages/unread-count`](/docs/message/unread-count) for the message-thread counter.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<UnreadNotificationCountResponseDto>` [#200-ok--apiresponseofunreadnotificationcountresponsedto]

```json
{
  "success": true,
  "data": {
    "count": 5
  }
}
```

| Field   | Type   | Notes                                                              |
| ------- | ------ | ------------------------------------------------------------------ |
| `count` | number | Total `Notification` rows where `userId = caller AND read = false` |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `401` | (guard)            | Missing / invalid bearer token   |
| `429` | (throttle)         | Rate limit exceeded (60 req/min) |

## Side effects [#side-effects]

1. Single `prisma.notification.count({ where: { userId, read: false } })`.
2. Return `{ count }`. &#x2A;*No mutations.**

## Polling guidance [#polling-guidance]

* Refresh on app focus + after marking notifications read.
* Don't tight-loop poll — the badge updates rarely (only when a server-side notification fires or the user marks one read).
* A 30s background refresh covers WebSocket-disconnected sessions.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/notifications/unread-count \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function getUnreadNotificationCount(accessToken: string): Promise<number> {
      const res = await fetch('https://api.bio.re/api/v1/notifications/unread-count', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Unread count fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.count as number;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const notificationKeys = {
      unreadCount: () => ['notifications', 'unread-count'] as const,
    };

    export function useUnreadNotificationCount() {
      return useQuery({
        queryKey: notificationKeys.unreadCount(),
        queryFn: async () => {
          const res = await fetch('/api/v1/notifications/unread-count');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Unread count fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.count as number;
        },
        staleTime: 30_000,
        refetchOnWindowFocus: true,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/notifications/unread-count', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source                   | Path                                                                             | Lines                                          |
| ------------------------ | -------------------------------------------------------------------------------- | ---------------------------------------------- |
| Controller (inline impl) | `apps/api-core/src/modules/notification/user-notification.controller.ts`         | `80–87` (`unreadCount`)                        |
| DTO (response)           | `apps/api-core/src/modules/notification/dto/notification-client-response.dto.ts` | `39–42` (`UnreadNotificationCountResponseDto`) |
| Prisma model             | `packages/prisma/prisma/schema.prisma`                                           | `Notification.read`, `Notification.userId`     |


# Email Unsubscribe (Public) (/docs/notification/unsubscribe)



`GET /api/v1/notifications/unsubscribe` — 🌐 **Public** · Rate limit: **10 req / hour**

Public unsubscribe link target. Reachable from email footers without login. Validates a server-signed HMAC token (`sha256` over the email address, truncated to 32 hex chars), then **adds the email to the suppression list** and **flips `email: false` in every notification preference** for the matching user.



<Callout type="warn">
  **HMAC signature is the auth.** The token must equal `sha256(UNSUBSCRIBE_HMAC_SECRET + email).slice(0,32)` (server-side env). An incorrect token returns `200 OK` with `success: false` (NOT a 403/404 — to avoid email-enumeration via timing).
</Callout>

<Callout type="info">
  **Two-pass effect on success**:

  1. Insert into `EmailSuppressionList` (idempotent — `findUnique` first to skip duplicates) with `reason: 'user_unsubscribe'`. The email-dispatch pipeline checks this list before sending — once suppressed, no future emails go out for that address.
  2. **For every `eventKey` in `NotificationDefault`**, upsert the user's `NotificationPreference` row with `email: false` and other channels defaulting to `true` (on first save). This means the user can still receive in-app / push / SMS — only email is suppressed.

  If no `User` is found for the email (e.g. email-only subscriber), only step 1 runs.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param   | Type   | Required    | Notes                                                                                                           |
| ------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------- |
| `email` | string | conditional | The email being unsubscribed. **Without it, the response is the friendly "go to settings" message** (no error). |
| `token` | string | conditional | HMAC signature. &#x2A;*Without it, same friendly fallback message.**                                            |

No body, no headers required.

## Response [#response]

### `200 OK` — `ApiResponseOf<UnsubscribeResponseDto>` [#200-ok--apiresponseofunsubscriberesponsedto]

**Three response shapes** depending on input + validity:

#### Missing `email` or `token` (link without params) [#missing-email-or-token-link-without-params]

```json
{
  "success": true,
  "data": {
    "message": "Please visit your account settings to manage notification preferences."
  }
}
```

#### Invalid token (HMAC mismatch) [#invalid-token-hmac-mismatch]

```json
{
  "success": true,
  "data": {
    "success": false,
    "message": "Invalid or expired unsubscribe link."
  }
}
```

#### Valid token [#valid-token]

```json
{
  "success": true,
  "data": {
    "success": true,
    "message": "You have been unsubscribed from email notifications."
  }
}
```

| Field     | Type                 | Notes                                                                     |
| --------- | -------------------- | ------------------------------------------------------------------------- |
| `success` | boolean \| undefined | Present in valid + invalid-token paths; absent in the missing-params path |
| `message` | string               | Human-friendly localized message                                          |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                                                                                                           |
| ----- | ------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `429` | (throttle)         | Rate limit exceeded (10 req/hour — tighter for the public endpoint)                                              |
| `500` | (env)              | `UNSUBSCRIBE_HMAC_SECRET` not set in production (server-side config error — surfaces as generic 500 to the user) |

The endpoint **does not return 4xx** for missing or invalid params — it always returns 200 with a tailored message body. This is deliberate: email links can't enumerate addresses or distinguish "wrong token" from "wrong address".

## Side effects [#side-effects]

1. **Missing `email`/`token`** → return friendly fallback message. &#x2A;*No mutations.**
2. **Compute expected token** — `createHmac('sha256', UNSUBSCRIBE_HMAC_SECRET).update(email).digest('hex').slice(0, 32)`. In dev mode, falls back to `'dev-unsubscribe-secret'` if env var is unset.
3. **Token mismatch** → return `{ success: false, message: 'Invalid or expired unsubscribe link.' }`. &#x2A;*No mutations.**
4. **Token valid** — two-pass mutation:
   * **Suppress email** — `emailSuppressionList.findUnique({ where: { email } })`; if missing, create with `reason: 'user_unsubscribe'`, `provider: null`. Idempotent.
   * **Disable email channel for the user** — `prisma.user.findUnique({ where: { email } })` to resolve `userId`; if found, iterate every `notificationDefault.findMany` row and `notificationPreference.upsert({ update: { email: false }, create: { email: false, push: true, inApp: true, webPush: true, sms: true } })` for each `eventKey`.
5. Return `{ success: true, message: 'You have been unsubscribed from email notifications.' }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'HTML link (email footer)']">
  <Tab value="curl">
    ```bash
    # Direct call (server-generated token)
    curl 'https://api.bio.re/api/v1/notifications/unsubscribe?email=fan@example.com&token=abc123def456...32chars'

    # Missing-params fallback (returns friendly message)
    curl 'https://api.bio.re/api/v1/notifications/unsubscribe'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type UnsubscribeResponse = {
      success?: boolean;
      message: string;
    };

    async function unsubscribeFromEmail(email: string, token: string): Promise<UnsubscribeResponse> {
      const url = new URL('https://api.bio.re/api/v1/notifications/unsubscribe');
      url.searchParams.set('email', email);
      url.searchParams.set('token', token);
      const res = await fetch(url);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Unsubscribe failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="HTML link (email footer)">
    ```html
    <!-- Generated by the email template — token computed server-side via HMAC -->
    <a href="https://bio.re/unsubscribe?email=fan@example.com&token=ab12cd34...">
      Unsubscribe
    </a>
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/notifications/unsubscribe', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source                   | Path                                                                             | Lines                                                                                                 |
| ------------------------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Controller (inline impl) | `apps/api-core/src/modules/notification/user-notification.controller.ts`         | `213–274` (`unsubscribe` — HMAC validate + suppression + per-event email-off upsert)                  |
| DTO (response)           | `apps/api-core/src/modules/notification/dto/notification-client-response.dto.ts` | `98–104` (`UnsubscribeResponseDto`)                                                                   |
| HMAC                     | Node.js `crypto`                                                                 | `createHmac('sha256', secret).update(email).digest('hex').slice(0, 32)`                               |
| Env                      | server config                                                                    | `UNSUBSCRIBE_HMAC_SECRET` (production-required; dev fallback `'dev-unsubscribe-secret'`)              |
| Prisma models            | `packages/prisma/prisma/schema.prisma`                                           | `EmailSuppressionList` (`@@unique([email])`), `NotificationDefault`, `NotificationPreference`, `User` |


# Subscribe to Web Push (/docs/notification/webpush-subscribe)



`POST /api/v1/notifications/webpush/subscribe` — 🔑 **Bearer**

Registers a W3C `PushSubscription` (the object returned by `pushManager.subscribe()` in the browser ServiceWorker). **Endpoint-keyed upsert**: if the same `endpoint` already exists in the DB, the keys are updated and (if the user changed) the row is **reassigned to the new user**. This handles two real-world cases — (1) the browser regenerated the keypair, (2) a different user logged in on the same browser/device.



<Callout type="info">
  **Browser side: get a subscription first.** This endpoint expects fields produced by `serviceWorkerRegistration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: <vapid-public-key> })`. The platform's VAPID public key is delivered through a separate config / env channel — clients embed it at build time. The server doesn't return it from this endpoint.
</Callout>

<Callout type="warn">
  **Cross-user reassignment is intentional.** If the same physical device hosts two user logins over time, the browser generates one push subscription endpoint per browser profile. When user B subscribes on a browser where user A already had a subscription with the same `endpoint`, the row's `userId` is **silently reassigned** from A to B (with fresh `p256dh` / `auth` keys). User A no longer receives notifications on that device — they need to re-subscribe from their own profile.
</Callout>

## Request [#request]

### Body — `WebPushSubscribeDto` [#body--webpushsubscribedto]

| Field       | Type   | Required | Validation     | Notes                                                                      |
| ----------- | ------ | -------- | -------------- | -------------------------------------------------------------------------- |
| `endpoint`  | string | ✓        | `IsNotEmpty()` | The `subscription.endpoint` URL (provider-specific — varies by browser/OS) |
| `p256dh`    | string | ✓        | `IsNotEmpty()` | Base64-encoded public key from `subscription.getKey('p256dh')`             |
| `auth`      | string | ✓        | `IsNotEmpty()` | Base64-encoded auth secret from `subscription.getKey('auth')`              |
| `userAgent` | string | optional | `IsString()`   | Browser/OS UA string for support trails (helps "which device is this?")    |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` [#200-ok]

```json
{
  "success": true,
  "subscriptionId": "ws1a2b3c4-d5e6-7890-abcd-ef1234567890"
}
```

| Field            | Type          | Notes                                                                |
| ---------------- | ------------- | -------------------------------------------------------------------- |
| `success`        | boolean       | Always `true` on 200                                                 |
| `subscriptionId` | string (UUID) | The `WebPushSubscription.id` (existing-and-updated OR newly-created) |

Note: the response is **not** wrapped in `ApiResponseOf<T>` — the controller returns the object directly. The shape above is what you actually get.

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                                 |
| ----- | ------------------ | -------------------------------------- |
| `400` | (DTO validation)   | Missing `endpoint` / `p256dh` / `auth` |
| `401` | (guard)            | Missing / invalid bearer token         |

## Side effects [#side-effects]

1. `prisma.webPushSubscription.findUnique({ where: { endpoint } })`.
2. **Existing row** — `update({ id: existing.id, data: { userId, p256dh, auth, userAgent, active: true } })&#x60;. **`userId` is overwritten** even if it differs (cross-user reassignment).
3. **New row** — `create({ id: randomUUID(), userId, endpoint, p256dh, auth, userAgent, active: true })`.
4. Audit log: `[webpush] Updated/Created subscription <id> for user <userId>`.
5. Return `{ success: true, subscriptionId: id }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'Browser ServiceWorker (full)']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/notifications/webpush/subscribe \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "endpoint": "https://push.example.com/abc123...",
        "p256dh": "BHV1...",
        "auth": "8Pgv...",
        "userAgent": "Mozilla/5.0 ..."
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type WebPushSubscribeInput = {
      endpoint: string;
      p256dh: string;
      auth: string;
      userAgent?: string;
    };

    async function subscribeWebPush(
      accessToken: string,
      input: WebPushSubscribeInput,
    ): Promise<string> {
      const res = await fetch('https://api.bio.re/api/v1/notifications/webpush/subscribe', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw new Error(json?.error?.message ?? 'Web push subscribe failed');
      }
      return json.subscriptionId as string;
    }
    ```
  </Tab>

  <Tab value="Browser ServiceWorker (full)">
    ```ts
    // 1. Register service worker (typically in app boot)
    const registration = await navigator.serviceWorker.register('/sw.js');

    // 2. Request notification permission
    const permission = await Notification.requestPermission();
    if (permission !== 'granted') {
      throw new Error('Notification permission denied');
    }

    // 3. Subscribe to push (VAPID public key from your platform config)
    const VAPID_PUBLIC_KEY = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!;

    function urlBase64ToUint8Array(base64String: string): Uint8Array {
      const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
      const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
      const raw = atob(base64);
      return Uint8Array.from(raw, (c) => c.charCodeAt(0));
    }

    const subscription = await registration.pushManager.subscribe({
      userVisibleOnly: true,
      applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY),
    });

    // 4. Extract keys + send to platform
    function arrayBufferToBase64(buffer: ArrayBuffer | null): string {
      if (!buffer) return '';
      const bytes = new Uint8Array(buffer);
      let binary = '';
      for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
      return btoa(binary);
    }

    const subscriptionId = await subscribeWebPush(accessToken, {
      endpoint: subscription.endpoint,
      p256dh: arrayBufferToBase64(subscription.getKey('p256dh')),
      auth: arrayBufferToBase64(subscription.getKey('auth')),
      userAgent: navigator.userAgent,
    });

    console.log('Web push subscription registered:', subscriptionId);
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/notifications/webpush/subscribe', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source        | Path                                                           | Lines                                                                                             |
| ------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Controller    | `apps/api-core/src/modules/notification/webpush.controller.ts` | `37–53` (`subscribe`)                                                                             |
| DTO (request) | `apps/api-core/src/modules/notification/webpush.controller.ts` | `7–19` (`WebPushSubscribeDto` — inline in controller file)                                        |
| Service       | `apps/api-core/src/modules/notification/webpush.service.ts`    | `16–52` (`subscribe` — endpoint-keyed upsert with cross-user reassignment)                        |
| Prisma model  | `packages/prisma/prisma/schema.prisma`                         | `WebPushSubscription` (`@@unique([endpoint])`, `userId`, `p256dh`, `auth`, `userAgent`, `active`) |
| W3C spec      | —                                                              | [Push API](https://www.w3.org/TR/push-api/) — `pushManager.subscribe()`                           |


# List Web Push Subscriptions (/docs/notification/webpush-subscriptions)



`GET /api/v1/notifications/webpush/subscriptions` — 🔑 **Bearer**

Returns the calling user's **active** `WebPushSubscription` rows (`active: true`), ordered by `createdAt DESC`, capped at 100. Each row exposes only the public-safe slice (`id`, `endpoint`, `createdAt`) — the `p256dh` / `auth` keys are kept server-side and never returned.



<Callout type="info">
  Use this to drive a "Connected devices" UI in account settings: render one row per subscription, optionally show a label derived from the `endpoint`'s provider host (e.g. "Chrome on macOS" can't be inferred reliably — only an opaque endpoint URL is available; the original `userAgent` was captured at subscribe time but is **not exposed** by this endpoint).
</Callout>

<Callout type="warn">
  **Inactive subscriptions are excluded.** Rows with `active: false` (after unsubscribe) are not returned. To see them you'd need an admin endpoint or direct DB access — there's no client-facing "show inactive" toggle.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` [#200-ok]

```json
{
  "subscriptions": [
    {
      "id": "ws1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "endpoint": "https://push.example.com/abc123...",
      "createdAt": "2026-04-29T20:00:00.000Z"
    }
  ]
}
```

(Not wrapped in `ApiResponseOf<T>` — the controller returns the bare object.)

### Item fields [#item-fields]

| Field       | Type              | Notes                                                                                                         |
| ----------- | ----------------- | ------------------------------------------------------------------------------------------------------------- |
| `id`        | string (UUID)     | `WebPushSubscription.id` — pass to subscription-specific server-side ops (none currently exposed client-side) |
| `endpoint`  | string            | The provider-specific push endpoint URL (provider varies by browser; treat as opaque)                         |
| `createdAt` | string (ISO 8601) | When the subscription row was created                                                                         |

### Excluded fields [#excluded-fields]

The following are stored server-side but **never returned** by this endpoint:

* `p256dh` / `auth` — cryptographic keys (server-only; required for dispatch but never re-exposed)
* `userAgent` — captured at subscribe time, kept for support trails but not surfaced

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                         |
| ----- | ------------------ | ------------------------------ |
| `401` | (guard)            | Missing / invalid bearer token |

## Side effects [#side-effects]

1. `prisma.webPushSubscription.findMany({ where: { userId, active: true }, select: { id, endpoint, createdAt }, orderBy: createdAt desc, take: 100 })`.
2. Return `{ subscriptions }`. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/notifications/webpush/subscriptions \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type WebPushSubscriptionItem = {
      id: string;
      endpoint: string;
      createdAt: string;
    };

    async function listWebPushSubscriptions(accessToken: string): Promise<WebPushSubscriptionItem[]> {
      const res = await fetch('https://api.bio.re/api/v1/notifications/webpush/subscriptions', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok) {
        throw new Error('Subscriptions fetch failed');
      }
      return json.subscriptions as WebPushSubscriptionItem[];
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const notificationKeys = {
      webpushSubscriptions: () => ['notifications', 'webpush', 'subscriptions'] as const,
    };

    export function useWebPushSubscriptions() {
      return useQuery({
        queryKey: notificationKeys.webpushSubscriptions(),
        queryFn: async () => {
          const res = await fetch('/api/v1/notifications/webpush/subscriptions');
          if (!res.ok) throw new Error('Subscriptions fetch failed');
          const json = await res.json();
          return json.subscriptions as WebPushSubscriptionItem[];
        },
        staleTime: 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/notifications/webpush/subscriptions', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source       | Path                                                           | Lines                                                                                          |
| ------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Controller   | `apps/api-core/src/modules/notification/webpush.controller.ts` | `68–75` (`listSubscriptions`)                                                                  |
| Service      | `apps/api-core/src/modules/notification/webpush.service.ts`    | `69–76` (`getActiveSubscriptions`)                                                             |
| Prisma model | `packages/prisma/prisma/schema.prisma`                         | `WebPushSubscription` (server-only fields excluded from select: `p256dh`, `auth`, `userAgent`) |


# Unsubscribe Web Push (/docs/notification/webpush-unsubscribe)



`POST /api/v1/notifications/webpush/unsubscribe` — 🔑 **Bearer**

Soft-deactivates a single `WebPushSubscription` by `endpoint`. **Ownership-checked** — `subscription.userId === bearer.sub`; otherwise `404 subscription_not_found` (same code for missing OR cross-user — no enumeration leak). The row is NOT deleted: `active` is set to `false` so the dispatch pipeline skips it but the row stays for audit / re-subscribe detection.



<Callout type="info">
  **Soft-delete, not hard-delete.** The row stays in the DB with `active: false`. If the user re-subscribes from the same browser later, the existing row is reactivated (via the upsert in `POST /webpush/subscribe`). This avoids accumulating duplicate rows across the subscribe/unsubscribe cycle.
</Callout>

<Callout type="warn">
  **Browser-side cleanup is your responsibility.** This endpoint only flips the server-side flag. The actual browser-level subscription stays alive until your code calls `subscription.unsubscribe()` on the `PushSubscription` object. Run both calls in sequence — server first (so dispatches stop), then browser (so the keys are released).
</Callout>

## Request [#request]

### Body — `WebPushUnsubscribeDto` [#body--webpushunsubscribedto]

| Field      | Type   | Required | Validation     | Notes                                                       |
| ---------- | ------ | -------- | -------------- | ----------------------------------------------------------- |
| `endpoint` | string | ✓        | `IsNotEmpty()` | The same `subscription.endpoint` URL used at subscribe time |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` [#200-ok]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                |
| --------- | ------- | -------------------- |
| `success` | boolean | Always `true` on 200 |

(Not wrapped in `ApiResponseOf<T>` — the controller returns the bare object.)

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                            | Reason                                                                  |
| ----- | --------------------------------------------- | ----------------------------------------------------------------------- |
| `400` | (DTO validation)                              | Missing `endpoint`                                                      |
| `401` | (guard)                                       | Missing / invalid bearer token                                          |
| `404` | `notification.webpush.subscription_not_found` | No row for this endpoint OR row belongs to a different user (same code) |

## Side effects [#side-effects]

1. `prisma.webPushSubscription.findUnique({ where: { endpoint } })`.
2. Missing OR `userId !== caller` → throw `subscription_not_found`.
3. `prisma.webPushSubscription.update({ where: { id }, data: { active: false } })`.
4. Audit log: `[webpush] Deactivated subscription <id> for user <userId>`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'Browser ServiceWorker (full)']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/notifications/webpush/unsubscribe \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"endpoint": "https://push.example.com/abc123..."}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function unsubscribeWebPush(accessToken: string, endpoint: string): Promise<void> {
      const res = await fetch('https://api.bio.re/api/v1/notifications/webpush/unsubscribe', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ endpoint }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw new Error(json?.error?.message ?? 'Web push unsubscribe failed');
      }
    }
    ```
  </Tab>

  <Tab value="Browser ServiceWorker (full)">
    ```ts
    // Two-step unsubscribe: server first, then browser
    async function fullyUnsubscribeWebPush(accessToken: string) {
      const registration = await navigator.serviceWorker.ready;
      const subscription = await registration.pushManager.getSubscription();
      if (!subscription) return; // already unsubscribed

      // 1. Tell the platform to stop dispatching
      await unsubscribeWebPush(accessToken, subscription.endpoint);

      // 2. Release the browser-side subscription
      await subscription.unsubscribe();
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/notifications/webpush/unsubscribe', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source        | Path                                                           | Lines                                                         |
| ------------- | -------------------------------------------------------------- | ------------------------------------------------------------- |
| Controller    | `apps/api-core/src/modules/notification/webpush.controller.ts` | `55–66` (`unsubscribe`)                                       |
| DTO (request) | `apps/api-core/src/modules/notification/webpush.controller.ts` | `21–24` (`WebPushUnsubscribeDto` — inline in controller file) |
| Service       | `apps/api-core/src/modules/notification/webpush.service.ts`    | `54–67` (`unsubscribe` — soft-delete, ownership-aware)        |
| Prisma model  | `packages/prisma/prisma/schema.prisma`                         | `WebPushSubscription.active` (soft-delete flag)               |


# List Conversations (/docs/message/conversations)



`GET /api/v1/messages/conversations` — 🔑 **Bearer** · Rate limit: **60 req / minute** · Kill-switched

Returns the user's `ChatSession` rows (where they're either `fanId` or `creatorId`), enriched with the **other party's profile slice**, the **last message preview** (with content as `'[encrypted]'` placeholder), per-session **unread count**, and **bidirectional block flags** (`isBlocked` = you blocked them; `isBlockedBy` = they blocked you).



<Callout type="warn">
  **Last message content is `'[encrypted]'` literal.** The conversations list does NOT decrypt the last message body — performance bound (one decryption per row × pagination would dominate cost). The string `'[encrypted]'` is a sentinel; render a generic preview (e.g. `"New message from <displayName>"`) rather than displaying it. To get the actual content, fetch the full message via `GET /messages/:id` or the inbox via `GET /messages?sessionId=...`.
</Callout>

<Callout type="info">
  **Block flags are bidirectional and computed in the same query batch.** The frontend uses these to toggle the chat into read-only mode without an extra round-trip. `isBlocked: true` → you blocked them (you can unblock); `isBlockedBy: true` → they blocked you (no action available).
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param   | Type   | Default | Validation                              | Notes                                                                                                        |
| ------- | ------ | ------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `page`  | number | `1`     | `parseInt`, server-clamped to `>= 1`    | 1-based page index                                                                                           |
| `limit` | number | `20`    | `parseInt`, server-clamped to `[1, 50]` | Items per page (smaller cap than other list endpoints — conversation rows are joined, expensive to assemble) |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<ConversationListResponseDto>` [#200-ok--apiresponseofconversationlistresponsedto]

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "sessionId": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "otherParty": {
          "id": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "username": "johndoe",
          "displayName": "John Doe"
        },
        "lastMessage": {
          "id": "m1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "content": "[encrypted]",
          "dmType": "SINGLE_PAY",
          "status": "REPLIED",
          "createdAt": "2026-04-29T20:00:00.000Z",
          "senderId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890"
        },
        "unreadCount": 3,
        "lastMessageAt": "2026-04-29T20:00:00.000Z",
        "isBlocked": false,
        "isBlockedBy": false
      }
    ],
    "total": 12
  }
}
```

### Item fields [#item-fields]

| Field           | Type                      | Notes                                                                                                                                  |
| --------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `sessionId`     | string (UUID)             | `ChatSession.id` — pass to `GET /messages?sessionId=...` to drill into the thread                                                      |
| `otherParty`    | object                    | `{ id, username, displayName }` for the user on the other end of the session                                                           |
| `lastMessage`   | object \| null            | Last message in this session — content is the literal `'[encrypted]'` sentinel (see callout). Null if the session has no messages yet. |
| `unreadCount`   | number                    | Count of messages where this user is the receiver AND status is `PENDING` / `ESCROWED` / `DELIVERED` (the "unread" trio)               |
| `lastMessageAt` | string (ISO 8601) \| null | Most recent message timestamp on this session                                                                                          |
| `isBlocked`     | boolean                   | `true` when the calling user has blocked the other party (this user → them)                                                            |
| `isBlockedBy`   | boolean                   | `true` when the other party has blocked the calling user (them → this user)                                                            |

### Top-level fields [#top-level-fields]

| Field   | Type   | Notes                                                                        |
| ------- | ------ | ---------------------------------------------------------------------------- |
| `items` | array  | Up to `limit` conversations, ordered by `lastMessageAt DESC`                 |
| `total` | number | Total `ChatSession` rows matching this user (no filter beyond participation) |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`            | Reason                                  |
| ----- | ----------------------------- | --------------------------------------- |
| `401` | (guard)                       | Missing / invalid bearer token          |
| `429` | (throttle)                    | Rate limit exceeded (60 req/min)        |
| `503` | `features.messaging_disabled` | Admin kill switch `MESSAGING` is active |

## Side effects [#side-effects]

1. Clamp `page = max(page, 1)` and `limit = clamp(limit, 1, 50)`.
2. **In parallel**: `chatSession.findMany({ where: OR [fanId, creatorId], orderBy lastMessageAt desc, skip, take })` + `chatSession.count({ where })`.
3. Build `otherPartyIds` array (the non-self side of each session).
4. **In parallel**: `user.findMany({ id IN otherPartyIds, select id+username+displayName })` + `blockList.findMany({ ownerId: userId, blockedId IN otherPartyIds })` + `blockList.findMany({ ownerId IN otherPartyIds, blockedId: userId })` — three batch lookups, one round-trip each.
5. Build `userMap`, `blockedByMeSet`, `blockedMeSet` (in-memory).
6. **Per-session enrichment** (inside `Promise.all` over `sessions`):
   * `message.findFirst({ where chatSessionId, orderBy createdAt desc, select: id+content+dmType+status+createdAt+senderId })` for `lastMessage`.
   * `message.count({ where chatSessionId AND receiverId = userId AND status IN [PENDING, ESCROWED, DELIVERED] })` for `unreadCount`.
   * Resolve `otherParty` from `userMap`.
   * **Replace `lastMessage.content` with `'[encrypted]'` literal** (no per-row decryption).
   * Stamp `isBlocked` / `isBlockedBy` from the sets.
7. Return `{ items, total }`. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/messages/conversations?page=1&limit=20' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type ConversationOtherParty = {
      id: string;
      username: string | null;
      displayName: string | null;
    };

    type ConversationLastMessage = {
      id: string;
      content: string; // always '[encrypted]' here
      dmType: 'FREE' | 'SINGLE_PAY' | 'PER_MESSAGE';
      status: string;
      createdAt: string;
      senderId: string;
    };

    type ConversationItem = {
      sessionId: string;
      otherParty: ConversationOtherParty;
      lastMessage: ConversationLastMessage | null;
      unreadCount: number;
      lastMessageAt: string | null;
      isBlocked: boolean;
      isBlockedBy: boolean;
    };

    type ConversationList = {
      items: ConversationItem[];
      total: number;
    };

    async function listConversations(
      accessToken: string,
      page = 1,
      limit = 20,
    ): Promise<ConversationList> {
      const url = new URL('https://api.bio.re/api/v1/messages/conversations');
      url.searchParams.set('page', String(page));
      url.searchParams.set('limit', String(limit));
      const res = await fetch(url, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Conversations fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery, keepPreviousData } from '@tanstack/react-query';

    export const messageKeys = {
      conversations: (page: number, limit: number) =>
        ['messages', 'conversations', page, limit] as const,
    };

    export function useConversations(page = 1, limit = 20) {
      return useQuery({
        queryKey: messageKeys.conversations(page, limit),
        queryFn: async () => {
          const url = new URL('/api/v1/messages/conversations', window.location.origin);
          url.searchParams.set('page', String(page));
          url.searchParams.set('limit', String(limit));
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Conversations fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as ConversationList;
        },
        placeholderData: keepPreviousData,
        staleTime: 10_000, // refresh frequently — new messages flip unreadCount
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/messages/conversations', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                   | Lines                                                                                                                                            |
| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/message/message.controller.ts`              | `109–121` (`getConversations`)                                                                                                                   |
| DTO (response) | `apps/api-core/src/modules/message/dto/message-client-response.dto.ts` | `142–148` (`ConversationListResponseDto`), `114–135` (`ConversationItemDto` + nested `ConversationOtherPartyDto` / `ConversationLastMessageDto`) |
| Service        | `apps/api-core/src/modules/message/message.service.ts`                 | `844–913` (`getConversations`)                                                                                                                   |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                                 | `ChatSession`, `Message`, `User`, `BlockList`                                                                                                    |


# Get Message Detail (/docs/message/detail)



`GET /api/v1/messages/:id` — 🔑 **Bearer** · Rate limit: **60 req / minute** · Kill-switched

Returns the full client-facing slice of a single `Message` row by id. **Ownership-checked**: you must be either `senderId` or `receiverId`; otherwise `403 not_authorized`. Content is decrypted server-side on read (best-effort fallback to raw on decryption error).



<Callout type="info">
  This endpoint is implemented **inline in the controller** (no separate service method) — direct Prisma `findUnique` plus the ownership check plus `safeDecrypt`. Performance characteristic: a single indexed lookup, near-constant time.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param | Type   | Validation                              | Notes                                                                |
| ----- | ------ | --------------------------------------- | -------------------------------------------------------------------- |
| `id`  | string | (no UUID pipe — raw string passthrough) | The `Message.id`. Whatever you pass is fed to `findUnique` directly. |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<MessageDetailClientDto>` [#200-ok--apiresponseofmessagedetailclientdto]

```json
{
  "success": true,
  "data": {
    "id": "m1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "content": "Hey, love your content!",
    "status": "REPLIED",
    "dmType": "SINGLE_PAY",
    "priceSnapshot": "5.00",
    "senderId": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
    "receiverId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "createdAt": "2026-04-29T20:00:00.000Z",
    "expiresAt": "2026-05-02T20:00:00.000Z",
    "repliedAt": "2026-04-30T18:00:00.000Z",
    "completedAt": null,
    "timeoutHours": 72
  }
}
```

### Fields [#fields]

| Field                     | Type                      | Notes                                                                                                                                |
| ------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                      | string (UUID)             | `Message.id`                                                                                                                         |
| `content`                 | string                    | Decrypted body (best-effort; falls back to raw on decryption failure)                                                                |
| `status`                  | enum                      | One of `PENDING` / `ESCROWED` / `DELIVERED` / `READ` / `REPLIED` / `COMPLETED` / `EXPIRED` / `REFUNDED` / `REJECTED` / `QUARANTINED` |
| `dmType`                  | enum                      | `FREE` / `SINGLE_PAY` / `PER_MESSAGE` (snapshot at send time)                                                                        |
| `priceSnapshot`           | string \| null            | Decimal as string. The price the fan paid at send time. `null` for `FREE`.                                                           |
| `senderId` / `receiverId` | string (UUID)             | Participants — you must be one of them                                                                                               |
| `createdAt`               | string (ISO 8601)         | Send timestamp                                                                                                                       |
| `expiresAt`               | string (ISO 8601) \| null | Reply window deadline (after this, system flips to `EXPIRED` + refunds the fan)                                                      |
| `repliedAt`               | string (ISO 8601) \| null | When the creator replied (null if no reply yet)                                                                                      |
| `completedAt`             | string (ISO 8601) \| null | When the message reached terminal `COMPLETED` state (escrow released to creator)                                                     |
| `timeoutHours`            | number \| null            | The reply deadline window in hours, captured at send time (used to compute `expiresAt`)                                              |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                   | Reason                                     |
| ----- | ------------------------------------ | ------------------------------------------ |
| `401` | (guard)                              | Missing / invalid bearer token             |
| `403` | `message.reply.error.not_authorized` | You're neither `senderId` nor `receiverId` |
| `404` | `message.reply.error.not_found`      | No `Message` with this id                  |
| `429` | (throttle)                           | Rate limit exceeded (60 req/min)           |
| `503` | `features.messaging_disabled`        | Admin kill switch `MESSAGING` is active    |

## Side effects [#side-effects]

1. `prisma.message.findUnique({ where: { id: messageId }, select: { id, content, status, dmType, priceSnapshot, senderId, receiverId, createdAt, expiresAt, repliedAt, completedAt, timeoutHours } })`.
2. Throw `not_found` if missing.
3. Ownership check: `senderId !== userId AND receiverId !== userId` → throw `not_authorized`.
4. Decrypt `content` via `safeDecrypt` (try / fallback to raw).
5. Return the row with decrypted content. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/messages/m1a2b3c4-d5e6-7890-abcd-ef1234567890 \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type MessageDetail = {
      id: string;
      content: string;
      status: string;
      dmType: 'FREE' | 'SINGLE_PAY' | 'PER_MESSAGE';
      priceSnapshot: string | null;
      senderId: string;
      receiverId: string;
      createdAt: string;
      expiresAt: string | null;
      repliedAt: string | null;
      completedAt: string | null;
      timeoutHours: number | null;
    };

    async function getMessage(accessToken: string, messageId: string): Promise<MessageDetail> {
      const res = await fetch(`https://api.bio.re/api/v1/messages/${messageId}`, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Message fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const messageKeys = {
      detail: (id: string) => ['messages', 'detail', id] as const,
    };

    export function useMessageDetail(messageId: string) {
      return useQuery({
        queryKey: messageKeys.detail(messageId),
        queryFn: async () => {
          const res = await fetch(`/api/v1/messages/${messageId}`);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Message fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as MessageDetail;
        },
        enabled: Boolean(messageId),
        staleTime: 10_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/messages/{id}', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source                   | Path                                                                   | Lines                                                                    |
| ------------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Controller (inline impl) | `apps/api-core/src/modules/message/message.controller.ts`              | `135–158` (`getMessage` — direct Prisma + ownership check + safeDecrypt) |
| DTO (response)           | `apps/api-core/src/modules/message/dto/message-client-response.dto.ts` | `165–201` (`MessageDetailClientDto`)                                     |
| Encryption               | `apps/api-core/src/common/encryption.ts`                               | `decryptContent()`                                                       |
| Prisma model             | `packages/prisma/prisma/schema.prisma`                                 | `Message` (`enum MessageStatus`, `enum DmType`)                          |


# List Messages (Inbox) (/docs/message/list)



`GET /api/v1/messages` — 🔑 **Bearer** · Rate limit: **60 req / minute** · Kill-switched

Paginated message list. **Role filter**: `fan` returns messages the user sent (as a fan); `creator` returns messages they received (as a creator). **Optional `sessionId` filter** scopes to a single chat session — when provided, the user must be a participant in that session (otherwise 403). Server decrypts each row's `content` on read (best-effort: if decryption fails, the raw stored value is returned).



<Callout type="info">
  **Content is encrypted at rest.** Each row's `content` field is decrypted server-side before returning. If the decryption helper throws (e.g. legacy plaintext or missing key), the original stored string is returned as a fallback so reads never fail outright. Don't expect a stable plaintext format — display as user content, not as a structured field.
</Callout>

<Callout type="warn">
  **`MESSAGING` kill switch.** All `/messages/*` endpoints share `@RequireKillSwitch('MESSAGING')`. Admin-disabled state returns `503 features.messaging_disabled` (same shape across read + write endpoints). Surface a "messaging temporarily unavailable" UI on that response.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param       | Type          | Default | Validation                                            | Notes                                                                                 |
| ----------- | ------------- | ------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `role`      | enum          | `fan`   | `fan` / `creator` (anything else falls back to `fan`) | `fan` filters to sent messages, `creator` to received                                 |
| `sessionId` | string (UUID) | —       | UUID regex check (else 400)                           | Scopes to a single chat session; participation enforced server-side (403 on mismatch) |
| `page`      | number        | `1`     | `parseInt`, server-clamped to `>= 1`                  | 1-based page index                                                                    |
| `limit`     | number        | `20`    | `parseInt`, server-clamped to `[1, 100]`              | Items per page                                                                        |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `PaginatedApiResponseOf<MessageInboxItemDto>` [#200-ok--paginatedapiresponseofmessageinboxitemdto]

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "m1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "content": "Hey, love your content!",
        "status": "ESCROWED",
        "dmType": "SINGLE_PAY",
        "priceSnapshot": "5.00",
        "senderId": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
        "receiverId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "createdAt": "2026-04-29T20:00:00.000Z",
        "expiresAt": "2026-05-02T20:00:00.000Z"
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}
```

### Item fields [#item-fields]

| Field                     | Type                      | Notes                                                                                                                                 |
| ------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                      | string (UUID)             | `Message.id`                                                                                                                          |
| `content`                 | string                    | Decrypted on read (fallback to raw if decryption fails)                                                                               |
| `status`                  | enum                      | One of: `PENDING` / `ESCROWED` / `DELIVERED` / `READ` / `REPLIED` / `COMPLETED` / `EXPIRED` / `REFUNDED` / `REJECTED` / `QUARANTINED` |
| `dmType`                  | enum                      | `FREE` / `SINGLE_PAY` / `PER_MESSAGE` (snapshot of the DM type at send time)                                                          |
| `priceSnapshot`           | string \| null            | Decimal as string (the price paid at send time; `null` for `FREE`)                                                                    |
| `senderId` / `receiverId` | string (UUID)             | Participants                                                                                                                          |
| `createdAt`               | string (ISO 8601)         | When the message was sent                                                                                                             |
| `expiresAt`               | string (ISO 8601) \| null | When the creator's reply window closes (after which the system refunds + flips to `EXPIRED`)                                          |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`               | Reason                                                     |
| ----- | -------------------------------- | ---------------------------------------------------------- |
| `400` | (validation)                     | `sessionId` not a valid UUID                               |
| `401` | (guard)                          | Missing / invalid bearer token                             |
| `403` | `message.session.not_authorized` | `sessionId` resolved a session you're not a participant in |
| `404` | `message.session.not_found`      | `sessionId` doesn't match any `ChatSession` row            |
| `429` | (throttle)                       | Rate limit exceeded (60 req/min)                           |
| `503` | `features.messaging_disabled`    | Admin kill switch `MESSAGING` is active                    |

## Side effects [#side-effects]

1. **`sessionId` validation** — UUID regex check at controller; service additionally verifies `ChatSession` exists AND user is `fanId` or `creatorId`.
2. Clamp `page = max(page, 1)` and `limit = clamp(limit, 1, 100)`.
3. Build the `where` clause — `senderId = userId` (role=fan) OR `receiverId = userId` (role=creator), `+chatSessionId = sessionId` if supplied.
4. **Two queries in parallel**: `findMany({ orderBy createdAt desc, skip, take, select: <inbox slice> })` + `count({ where })`.
5. **Decrypt each `content`** via `safeDecrypt()` (try / fallback to raw on error).
6. Return `{ items, total, page, limit, totalPages }`. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    # fan inbox (sent messages)
    curl 'https://api.bio.re/api/v1/messages?role=fan&page=1&limit=20' \
      -H "Authorization: Bearer $ACCESS_TOKEN"

    # creator inbox (received messages, scoped to one session)
    curl 'https://api.bio.re/api/v1/messages?role=creator&sessionId=s1a2b3c4-d5e6-7890-abcd-ef1234567890' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type MessageStatus =
      | 'PENDING' | 'ESCROWED' | 'DELIVERED' | 'READ'
      | 'REPLIED' | 'COMPLETED' | 'EXPIRED'
      | 'REFUNDED' | 'REJECTED' | 'QUARANTINED';

    type DmType = 'FREE' | 'SINGLE_PAY' | 'PER_MESSAGE';

    type MessageInboxItem = {
      id: string;
      content: string;
      status: MessageStatus;
      dmType: DmType;
      priceSnapshot: string | null;
      senderId: string;
      receiverId: string;
      createdAt: string;
      expiresAt: string | null;
    };

    type Paginated<T> = {
      items: T[];
      total: number;
      page: number;
      limit: number;
      totalPages: number;
    };

    async function listMessages(
      accessToken: string,
      filter: { role?: 'fan' | 'creator'; sessionId?: string; page?: number; limit?: number } = {},
    ): Promise<Paginated<MessageInboxItem>> {
      const url = new URL('https://api.bio.re/api/v1/messages');
      if (filter.role) url.searchParams.set('role', filter.role);
      if (filter.sessionId) url.searchParams.set('sessionId', filter.sessionId);
      if (filter.page) url.searchParams.set('page', String(filter.page));
      if (filter.limit) url.searchParams.set('limit', String(filter.limit));
      const res = await fetch(url, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Inbox fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery, keepPreviousData } from '@tanstack/react-query';

    export const messageKeys = {
      list: (filter: { role?: string; sessionId?: string; page?: number; limit?: number }) =>
        ['messages', 'list', filter] as const,
    };

    export function useMessageList(filter: {
      role?: 'fan' | 'creator';
      sessionId?: string;
      page?: number;
      limit?: number;
    } = {}) {
      return useQuery({
        queryKey: messageKeys.list(filter),
        queryFn: async () => {
          const url = new URL('/api/v1/messages', window.location.origin);
          if (filter.role) url.searchParams.set('role', filter.role);
          if (filter.sessionId) url.searchParams.set('sessionId', filter.sessionId);
          if (filter.page) url.searchParams.set('page', String(filter.page));
          if (filter.limit) url.searchParams.set('limit', String(filter.limit));
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Inbox fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as Paginated<MessageInboxItem>;
        },
        placeholderData: keepPreviousData, // smooth pagination
        staleTime: 10_000, // refetch frequently — DM status flips on webhook events
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/messages', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source              | Path                                                                   | Lines                                                                                |
| ------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Controller          | `apps/api-core/src/modules/message/message.controller.ts`              | `58–85` (`listMessages`)                                                             |
| DTO (response item) | `apps/api-core/src/modules/message/dto/message-client-response.dto.ts` | `21–48` (`MessageInboxItemDto`)                                                      |
| Service             | `apps/api-core/src/modules/message/message.service.ts`                 | `927–...` (`getInbox`)                                                               |
| Encryption          | `apps/api-core/src/common/encryption.ts`                               | `decryptContent()` (used via service `safeDecrypt`)                                  |
| Kill switch         | `apps/api-core/src/common/guards/kill-switch.guard.ts`                 | `RequireKillSwitch('MESSAGING')` (class-level)                                       |
| Prisma models       | `packages/prisma/prisma/schema.prisma`                                 | `Message` (`enum MessageStatus`, `enum DmType`), `ChatSession` (participation check) |


# Rate Message (/docs/message/rate)



`POST /api/v1/messages/:id/rate` — 🔑 **Bearer** · Rate limit: **20 req / hour** · Kill-switched

Fan rates the completed message thread 1–5 stars. **Sender-only** (the fan, not the creator). &#x2A;*Status-only `COMPLETED`** — pending / rejected / expired messages can't be rated. Creates a `CreatorRating` row AND recomputes `CreatorProfile.avgRating` + `ratingCount` in the **same transaction**, keeping the aggregates consistent.



<Callout type="warn">
  **Single-shot per message.** A unique constraint on `messageId` enforces "one rating per message ever" — duplicate attempts surface as `409 already_rated`. There is no "edit rating" endpoint; the rating you submit is immutable.
</Callout>

<Callout type="info">
  **`comment` is accepted but stored differently.** The DTO accepts an optional `comment` field; the service signature destructures it as `_comment` (prefix-underscore = "intentionally unused"). It's not currently persisted on the `CreatorRating` row — only the numeric `rating` is. This may change in a future iteration; for now, treat `comment` as a no-op write.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param | Type   | Validation     | Notes                    |
| ----- | ------ | -------------- | ------------------------ |
| `id`  | string | (no UUID pipe) | The completed message id |

### Body — `RateMessageDto` [#body--ratemessagedto]

| Field     | Type   | Required | Validation         | Notes                                                                                                            |
| --------- | ------ | -------- | ------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `rating`  | number | ✓        | `Min(1)`, `Max(5)` | Integer 1–5. Server re-checks the `[1, 5]` range after class-validator.                                          |
| `comment` | string | optional | `IsString()`       | **Currently a no-op write** (see callout) — DTO accepts it, service ignores it. Send for forward-compat or skip. |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                                                                                                                         |
| --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `success` | boolean | Always `true` on 200. Creator's profile (`/creators/profile`) `avgRating` + `ratingCount` reflect the new value on next read. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                  | Reason                                                                                   |   |              |
| ----- | ----------------------------------- | ---------------------------------------------------------------------------------------- | - | ------------ |
| `400` | `message.rate.error.invalid_range`  | \`rating \< 1                                                                            |   | rating > 5\` |
| `400` | `message.rate.error.invalid_status` | `Message.status !== 'COMPLETED'`                                                         |   |              |
| `400` | (DTO validation)                    | `rating` not a number, missing                                                           |   |              |
| `401` | (guard)                             | Missing / invalid bearer token                                                           |   |              |
| `403` | `message.rate.error.not_sender`     | You're not the message's `senderId` (only the fan who sent it can rate)                  |   |              |
| `404` | `message.reply.error.not_found`     | No `Message` with this id                                                                |   |              |
| `404` | `message.rate.error.not_found`      | Receiver has no `CreatorProfile` (data inconsistency — should not happen in normal flow) |   |              |
| `409` | `message.rate.error.already_rated`  | `CreatorRating` row already exists for this `messageId` (Prisma P2002)                   |   |              |
| `429` | (throttle)                          | Rate limit exceeded (20 req/hour)                                                        |   |              |
| `503` | `features.messaging_disabled`       | Admin kill switch `MESSAGING` is active                                                  |   |              |

## Side effects [#side-effects]

1. **Range guard** (`1 <= rating <= 5`).
2. **Lookup + sender check** — load `Message`; `not_found` if missing; `not_sender` if `senderId !== userId`.
3. **Status guard** — must be `COMPLETED`; otherwise `invalid_status`.
4. **Lookup `CreatorProfile`** for the receiver — `not_found` if missing.
5. **Inside one transaction**:
   * `CreatorRating.create({ id, creatorId, userId: fanId, messageId, rating })` — Prisma P2002 → throw `already_rated`.
   * `creatorRating.aggregate({ _avg: { rating }, _count: { rating } })` for this creator.
   * `CreatorProfile.update({ avgRating: agg._avg.rating ?? 0, ratingCount: agg._count.rating })`.
6. Audit log: `[msg] Rated: {messageId} → {rating} stars`.
7. **No notification** to the creator on rate (creator's profile aggregates update silently — fan-side action shouldn't ping the creator).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/messages/m1a2b3c4-d5e6-7890-abcd-ef1234567890/rate \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"rating": 5, "comment": "Great response!"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function rateMessage(
      accessToken: string,
      messageId: string,
      rating: 1 | 2 | 3 | 4 | 5,
      comment?: string,
    ): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/messages/${messageId}/rate`, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ rating, comment }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Rate failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useRateMessage() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (vars: { messageId: string; rating: number; comment?: string }) => {
          const res = await fetch(`/api/v1/messages/${vars.messageId}/rate`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ rating: vars.rating, comment: vars.comment }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Rate failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          // Creator profile aggregates may have changed
          qc.invalidateQueries({ queryKey: ['creators', 'profile'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/messages/{id}/rate', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                      | Lines                                                                                                                               |
| -------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/message/message.controller.ts` | `201–217` (`rateMessage`)                                                                                                           |
| DTO (request)  | `apps/api-core/src/modules/message/dto/index.ts`          | `33–38` (`RateMessageDto`)                                                                                                          |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts`     | `SuccessOnlyResponseDto`                                                                                                            |
| Service        | `apps/api-core/src/modules/message/message.service.ts`    | `767–806` (`rateMessage`)                                                                                                           |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                    | `Message.status` (`COMPLETED`), `CreatorRating` (`@@unique([messageId])`), `CreatorProfile.avgRating`, `CreatorProfile.ratingCount` |


# Reject Message (/docs/message/reject)



`POST /api/v1/messages/:id/reject` — 🔑 **Bearer** · Rate limit: **60 req / minute** · Kill-switched

Creator declines to reply to a message. **Atomically claims** the row (`ESCROWED|DELIVERED → REJECTED`) to prevent races with reply / expiry. For paid DMs, the escrow is **refunded to the fan's wallet in full** (no commission deducted on rejection); for free DMs, the message is simply marked refunded (no money moved). Optional `reason` is included in the fan's notification and the audit trail.



<Callout type="info">
  **Reject = full refund.** The fan gets `priceSnapshot` back to their wallet — no platform commission, no creator earnings. The platform only earns on `COMPLETED` (creator replied within window).
</Callout>

<Callout type="warn">
  **Critical-failure path**: if the escrow refund throws, the message stays at `REJECTED` (not advanced to `REFUNDED`) and the failure is logged at `[msg] CRITICAL`. Operations must reconcile the wallet state manually. The reject itself is committed — there's no compensation revert here (because reject is the safe-for-fan direction; "still rejected, refund pending" is a recoverable state).
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param | Type   | Validation     | Notes                      |
| ----- | ------ | -------------- | -------------------------- |
| `id`  | string | (no UUID pipe) | The message being rejected |

### Body — `RejectMessageDto` [#body--rejectmessagedto]

| Field    | Type   | Required | Validation   | Notes                                                                                                                                                            |
| -------- | ------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reason` | string | optional | `IsString()` | Free-form rejection reason. Surfaces in the fan's "your message was declined" notification AND in the audit trail. Defaults to `'Creator declined'` when absent. |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                                                                                              |
| --------- | ------- | -------------------------------------------------------------------------------------------------- |
| `success` | boolean | Always `true` on 200. The fan's wallet balance refresh + notification dispatch happen out-of-band. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                   | Reason                                                                  |
| ----- | ------------------------------------ | ----------------------------------------------------------------------- |
| `400` | `message.reply.error.invalid_status` | Status is not `ESCROWED` or `DELIVERED`. Payload includes `{ status }`. |
| `401` | (guard)                              | Missing / invalid bearer token                                          |
| `403` | `message.reply.error.not_authorized` | You're not the message's `receiverId`                                   |
| `404` | `message.reply.error.not_found`      | No `Message` with this id                                               |
| `429` | (throttle)                           | Rate limit exceeded (60 req/min — controller default)                   |
| `503` | `features.messaging_disabled`        | Admin kill switch `MESSAGING` is active                                 |

## Side effects [#side-effects]

1. **Lookup + ownership** — load `Message`; `not_found` if missing; `not_authorized` if `receiverId !== userId`.
2. **Status guard** — must be `ESCROWED` or `DELIVERED`; otherwise `invalid_status`.
3. **Atomic claim** — `updateMany({ id, status: <currentStatus> }, data: { status: REJECTED })`. `count = 0` → race with reply/expiry, throw `invalid_status`.
4. **Paid DM refund**:
   * `escrowService.refundEscrow(messageId, fanUserId, reason ?? 'Creator rejected')`.
   * On success: transition `REJECTED → REFUNDED`.
   * **On failure**: log `[msg] CRITICAL` (manual reconciliation needed). Status stays `REJECTED`. The reject itself is NOT reverted.
5. **Free DM**: skip escrow refund; transition directly `REJECTED → REFUNDED` (no money moved).
6. Audit log: `[msg] Rejected + refunded: {messageId}`.
7. **Notify fan** via `notificationService.send({ eventKey: 'message_rejected_refunded', variables: { creatorName, amount: '$<priceSnapshot>', reason } })` (fire-and-forget).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/messages/m1a2b3c4-d5e6-7890-abcd-ef1234567890/reject \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"reason": "Not accepting questions on this topic right now"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function rejectMessage(accessToken: string, messageId: string, reason?: string): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/messages/${messageId}/reject`, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ reason }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Reject failed'), {
          code: json?.error?.code,
          status: json?.error?.status,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useRejectMessage() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (vars: { messageId: string; reason?: string }) => {
          const res = await fetch(`/api/v1/messages/${vars.messageId}/reject`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ reason: vars.reason }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Reject failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
              status: json?.error?.status,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['messages'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/messages/{id}/reject', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source                | Path                                                             | Lines                                                                            |
| --------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Controller            | `apps/api-core/src/modules/message/message.controller.ts`        | `182–197` (`rejectMessage`)                                                      |
| DTO (request)         | `apps/api-core/src/modules/message/dto/index.ts`                 | `28–31` (`RejectMessageDto`)                                                     |
| DTO (response)        | `apps/api-core/src/common/dto/common-response.dto.ts`            | `SuccessOnlyResponseDto`                                                         |
| Service               | `apps/api-core/src/modules/message/message.service.ts`           | `676–711` (`rejectMessage`), `360–419` (`transition` + `getValidSourceStatuses`) |
| Escrow                | `apps/api-core/src/modules/payment/escrow.service.ts`            | `refundEscrow()`                                                                 |
| Notification pipeline | `apps/api-core/src/modules/notification/notification.service.ts` | `send({ eventKey: 'message_rejected_refunded' })`                                |
| Prisma models         | `packages/prisma/prisma/schema.prisma`                           | `Message.status`, `Wallet` (fan refund), `Escrow` (refund record)                |


# Reply to Message (/docs/message/reply)



`POST /api/v1/messages/:id/reply` — 🔑 **Bearer** · Rate limit: **20 req / minute** · Kill-switched

Creator's reply to a fan's message. Requires status `ESCROWED` (paid DMs) or `DELIVERED` (free DMs). **Atomic claim** prevents race with the expiry cron job. For paid DMs, escrow is released to the creator's wallet (after commission). On escrow-release failure, the message status is **reverted** and the orphan reply row is deleted (compensation).



<Callout type="info">
  **Status state machine**: `ESCROWED|DELIVERED → REPLIED → COMPLETED`. The intermediate `REPLIED` state exists so escrow release happens AFTER the row is "claimed" — guaranteeing exactly one reply even when the expiry cron is racing.
</Callout>

<Callout type="warn">
  **Compensation on escrow-release failure**: if the escrow service throws, the server attempts to revert the message back to its original status (and clear `repliedAt`) AND delete the orphan reply message that was just created. **If the revert also fails, the row is left in `REPLIED` status with no completion** — manual reconciliation is required (operations alerts on `[msg] CRITICAL` log lines).
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param | Type   | Validation     | Notes                                              |
| ----- | ------ | -------------- | -------------------------------------------------- |
| `id`  | string | (no UUID pipe) | The original message id (the one being replied to) |

### Body — `ReplyMessageDto` [#body--replymessagedto]

| Field     | Type   | Required | Validation                        | Notes                                                                                                           |
| --------- | ------ | -------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `content` | string | ✓        | `MinLength(1)`, `MaxLength(5000)` | Reply body. &#x2A;*Higher cap than send (`5000` vs `2000`)** — creators can be more verbose. Encrypted at rest. |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                                                                                                                                                                              |
| --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `success` | boolean | Always `true` on 200. Refetch the message detail or conversation list to see the new state (`COMPLETED` for paid, with creator wallet credited; or directly `COMPLETED` for free). |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                   | Reason                                                                                                        |
| ----- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `400` | `message.reply.error.invalid_status` | Status is not `ESCROWED` or `DELIVERED`. Payload includes `{ status }` so the UI can render the actual state. |
| `400` | (DTO validation)                     | Content empty / over 5000 chars                                                                               |
| `401` | (guard)                              | Missing / invalid bearer token                                                                                |
| `403` | `message.reply.error.not_authorized` | You're not the message's `receiverId`                                                                         |
| `404` | `message.reply.error.not_found`      | No `Message` with this id                                                                                     |
| `429` | (throttle)                           | Rate limit exceeded (20 req/min)                                                                              |
| `503` | `features.messaging_disabled`        | Admin kill switch `MESSAGING` is active                                                                       |

## Side effects [#side-effects]

1. **Lookup + ownership** — load `Message`; throw `not_found` if missing; throw `not_authorized` if `receiverId !== userId`.
2. **Status guard** — must be `ESCROWED` or `DELIVERED`; otherwise `invalid_status` (carries `{ status }`).
3. **Atomic claim** — `updateMany({ id, status: <currentStatus> }, data: { status: REPLIED, repliedAt: now() })`. `count = 0` → already-processed-by-other-operation (race with expiry / reject). Throw `invalid_status`.
4. **Create reply message** — `Message.create({ senderId: creator, receiverId: original-sender, dmType: <inherited>, content: encrypted, status: COMPLETED })`. (The reply itself starts at `COMPLETED` — there's no escrow on the reply direction.)
5. **Paid DM path** — release escrow via `escrowService.releaseEscrow(messageId, creatorUserId)`. On success: transition original message `REPLIED → COMPLETED` (with `completedAt = now()`). **On failure** (CRITICAL log): revert original to its prior status with `repliedAt = null` AND delete the orphan reply message (5s window check). Throw the original error.
6. **Free DM path** — skip escrow; transition original `REPLIED → COMPLETED` directly.
7. **Update `ChatSession.lastMessageAt`** for conversation ordering.
8. Increment `messageRepliedTotal` Prometheus counter.
9. **Notify fan** via `notificationService.send({ eventKey: 'message_replied_fan', deepLink: '/messages/<sessionId>' })` (fire-and-forget).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/messages/m1a2b3c4-d5e6-7890-abcd-ef1234567890/reply \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"content": "Thanks for reaching out!"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function replyToMessage(accessToken: string, messageId: string, content: string): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/messages/${messageId}/reply`, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ content }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Reply failed'), {
          code: json?.error?.code,
          status: json?.error?.status, // present on 'invalid_status'
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useReplyToMessage() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (vars: { messageId: string; content: string }) => {
          const res = await fetch(`/api/v1/messages/${vars.messageId}/reply`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ content: vars.content }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Reply failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
              status: json?.error?.status,
            });
          }
        },
        onSuccess: () => {
          // Multi-resource invalidation: message detail + thread inbox + conversations + unread + creator wallet
          qc.invalidateQueries({ queryKey: ['messages'] });
          qc.invalidateQueries({ queryKey: ['wallet', 'balance'] });
          qc.invalidateQueries({ queryKey: ['wallet', 'activity'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/messages/{id}/reply', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source                | Path                                                             | Lines                                                                                               |
| --------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Controller            | `apps/api-core/src/modules/message/message.controller.ts`        | `162–178` (`replyToMessage`)                                                                        |
| DTO (request)         | `apps/api-core/src/modules/message/dto/index.ts`                 | `23–26` (`ReplyMessageDto`)                                                                         |
| DTO (response)        | `apps/api-core/src/common/dto/common-response.dto.ts`            | `SuccessOnlyResponseDto`                                                                            |
| Service               | `apps/api-core/src/modules/message/message.service.ts`           | `590–671` (`replyToMessage`), `360–419` (`transition` + `getValidSourceStatuses`)                   |
| Escrow                | `apps/api-core/src/modules/payment/escrow.service.ts`            | `releaseEscrow()`                                                                                   |
| Encryption            | `apps/api-core/src/common/encryption.ts`                         | `encryptContent()`                                                                                  |
| Notification pipeline | `apps/api-core/src/modules/notification/notification.service.ts` | `send({ eventKey: 'message_replied_fan' })`                                                         |
| Prisma models         | `packages/prisma/prisma/schema.prisma`                           | `Message` (`enum MessageStatus`), `ChatSession.lastMessageAt`, `Wallet` (creator credit via escrow) |


# Search Messages (/docs/message/search)



`GET /api/v1/messages/search` — 🔑 **Bearer** · Rate limit: **60 req / minute** · Kill-switched

Substring search (case-insensitive) over the user's own messages — both sent and received. Searches the `Message.searchContent` column (an indexed, plaintext-for-search projection of the encrypted `content`). Returns paginated results with `content` decrypted for display.



<Callout type="info">
  **`searchContent` is the search index, `content` is the encrypted body.** The server stores message bodies encrypted in `content` and a searchable plaintext / normalized projection in `searchContent`. Search runs against `searchContent` (Prisma `contains` + `mode: 'insensitive'`) — clients never see this field, only the decrypted `content`.
</Callout>

<Callout type="warn">
  **No tokenization, no ranking.** This is a substring `LIKE` search, not full-text. `query="hello"` matches "Hello there" and "hellothere"; it doesn't tokenize, doesn't stem, doesn't rank. Pass the raw user input — server normalizes via `mode: 'insensitive'` only.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param   | Type   | Required | Default | Validation                               | Notes                                                                                                    |
| ------- | ------ | -------- | ------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `query` | string | ✓        | —       | —                                        | Search substring. Empty / missing → server falls back to `''` (matches everything; useful for browsing). |
| `page`  | number | optional | `1`     | `parseInt`, server-clamped to `>= 1`     | 1-based page index                                                                                       |
| `limit` | number | optional | `20`    | `parseInt`, server-clamped to `[1, 100]` | Items per page                                                                                           |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `PaginatedApiResponseOf<MessageSearchItemDto>` [#200-ok--paginatedapiresponseofmessagesearchitemdto]

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "m1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "content": "Hey, love your content!",
        "status": "REPLIED",
        "dmType": "SINGLE_PAY",
        "senderId": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
        "receiverId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "createdAt": "2026-04-29T20:00:00.000Z"
      }
    ],
    "total": 7,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}
```

### Item fields [#item-fields]

| Field                     | Type              | Notes                                                                                                                                |
| ------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                      | string (UUID)     | `Message.id`                                                                                                                         |
| `content`                 | string            | Decrypted body (best-effort; falls back to raw on decryption failure)                                                                |
| `status`                  | enum              | One of `PENDING` / `ESCROWED` / `DELIVERED` / `READ` / `REPLIED` / `COMPLETED` / `EXPIRED` / `REFUNDED` / `REJECTED` / `QUARANTINED` |
| `dmType`                  | enum              | `FREE` / `SINGLE_PAY` / `PER_MESSAGE`                                                                                                |
| `senderId` / `receiverId` | string (UUID)     | Participants                                                                                                                         |
| `createdAt`               | string (ISO 8601) | Message timestamp                                                                                                                    |

Note: search results **do not include** `priceSnapshot` / `expiresAt` (slimmer projection vs `MessageInboxItemDto`). Pull the full detail via `GET /messages/:id` when needed.

### Errors [#errors]

| HTTP  | `code` / `i18nKey`            | Reason                                  |
| ----- | ----------------------------- | --------------------------------------- |
| `401` | (guard)                       | Missing / invalid bearer token          |
| `429` | (throttle)                    | Rate limit exceeded (60 req/min)        |
| `503` | `features.messaging_disabled` | Admin kill switch `MESSAGING` is active |

## Side effects [#side-effects]

1. Clamp `page = max(page, 1)` and `limit = clamp(limit, 1, 100)`.
2. Build `where`: `OR: [{ senderId: userId }, { receiverId: userId }] AND searchContent: { contains: query, mode: 'insensitive' }`.
3. **Two queries in parallel**: `findMany({ orderBy createdAt desc, skip, take, select: <search slice> })` + `count({ where })`.
4. Decrypt each `content` via `safeDecrypt()`.
5. Return `{ items, total, page, limit, totalPages }`. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/messages/search?query=love&page=1&limit=20' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type MessageSearchItem = {
      id: string;
      content: string;
      status: string;
      dmType: 'FREE' | 'SINGLE_PAY' | 'PER_MESSAGE';
      senderId: string;
      receiverId: string;
      createdAt: string;
    };

    async function searchMessages(
      accessToken: string,
      query: string,
      page = 1,
      limit = 20,
    ): Promise<Paginated<MessageSearchItem>> {
      const url = new URL('https://api.bio.re/api/v1/messages/search');
      url.searchParams.set('query', query);
      url.searchParams.set('page', String(page));
      url.searchParams.set('limit', String(limit));
      const res = await fetch(url, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Search failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery, keepPreviousData } from '@tanstack/react-query';

    export const messageKeys = {
      search: (query: string, page: number, limit: number) =>
        ['messages', 'search', query, page, limit] as const,
    };

    export function useMessageSearch(query: string, page = 1, limit = 20) {
      // Caller is responsible for debouncing the query input upstream
      return useQuery({
        queryKey: messageKeys.search(query, page, limit),
        queryFn: async () => {
          const url = new URL('/api/v1/messages/search', window.location.origin);
          url.searchParams.set('query', query);
          url.searchParams.set('page', String(page));
          url.searchParams.set('limit', String(limit));
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Search failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as Paginated<MessageSearchItem>;
        },
        enabled: query.length >= 2,
        placeholderData: keepPreviousData,
        staleTime: 30_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/messages/search', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source              | Path                                                                   | Lines                                                                              |
| ------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Controller          | `apps/api-core/src/modules/message/message.controller.ts`              | `89–105` (`searchMessages`)                                                        |
| DTO (response item) | `apps/api-core/src/modules/message/dto/message-client-response.dto.ts` | `55–76` (`MessageSearchItemDto`)                                                   |
| Service             | `apps/api-core/src/modules/message/message.service.ts`                 | `812–838` (`searchMessages`)                                                       |
| Encryption          | `apps/api-core/src/common/encryption.ts`                               | `decryptContent()`                                                                 |
| Prisma model        | `packages/prisma/prisma/schema.prisma`                                 | `Message.content` (encrypted), `Message.searchContent` (indexed search projection) |


# Send Message (/docs/message/send)



`POST /api/v1/messages` — 🔑 **Bearer** · Rate limit: **10 req / minute** · Kill-switched

The most complex endpoint in the message module. **Validates a long chain of preconditions** (sender email verification, receiver active, block list, DM enabled, no vacation, dmType matches creator's config, no duplicate-window collision, no pending paid-DM concurrency violation, sufficient wallet balance for paid DMs), then **atomically** creates the `Message`, escrow record (paid DMs), and `MessageRuleSnapshot`. **Content moderation runs after persistence**; flagged messages get quarantined (silent to the fan — they see "sent").



<Callout type="warn">
  **Quarantine is silent.** When the moderation rule engine flags a message, the server transitions it to `QUARANTINED` server-side but **returns `status: PENDING` to the caller** (intentional — fan doesn't know they were flagged). The status only flips for admin / creator visibility. The DSA Article 17 "Statement of Reasons" is emitted server-side as audit trail.
</Callout>

<Callout type="info">
  **Status returned by this endpoint** is one of:

  * `PENDING` — paid DM where moderation flagged it (silently quarantined; status surface lies to the caller)
  * `ESCROWED` — paid DM that passed moderation (escrow created, awaiting creator)
  * `DELIVERED` — free DM that passed moderation (no escrow path)

  For paid DMs, **escrow is created BEFORE moderation runs** so quarantined paid messages still have escrow available for the admin approval flow.
</Callout>

<Callout type="warn">
  **Free DMs are doubly rate-limited.** Beyond the endpoint's `10/min` throttle, free DMs hit two per-day Redis counters: `dm.free_daily_limit` (default 5/user/day) and `dm.free_per_creator_daily` (default 1/user/creator/day), keyed by UTC date. Limits reset at UTC midnight. **If Redis is unavailable, free DMs are rejected** (security-first — can't enforce limits without it).
</Callout>

## Request [#request]

### Body — `SendMessageDto` [#body--sendmessagedto]

| Field          | Type             | Required    | Validation                                    | Notes                                                                                                                         |
| -------------- | ---------------- | ----------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `receiverId`   | string           | ✓           | `IsString()` (NOT UUID-pipe; raw passthrough) | Creator's user id                                                                                                             |
| `content`      | string           | ✓           | `MinLength(1)`, `MaxLength(2000)`             | Encrypted at rest; first 500 chars projected to `searchContent` for FTS                                                       |
| `dmType`       | enum             | ✓           | `IsEnum(DmType)`                              | `FREE` / `SINGLE_PAY` / `PER_MESSAGE` — **must match the creator's `dmType` config** (else 400)                               |
| `price`        | string (decimal) | conditional | `Matches(/^\d+(\.\d{1,2})?$/)`                | **Required when `dmType !== 'FREE'`**. Decimal as string. Server enforces `>= active DMPackage.price` for the creator.        |
| `timeoutHours` | number           | optional    | `Min(1)`, `Max(720)`                          | Reply-window deadline; defaults to `dm.timeout_hours` config (default 48). After expiry, system flips to `EXPIRED` + refunds. |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `201 Created` — `ApiResponseOf<SendMessageResponseDto>` [#201-created--apiresponseofsendmessageresponsedto]

```json
{
  "success": true,
  "data": {
    "messageId": "m1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "status": "ESCROWED"
  }
}
```

| Field       | Type          | Notes                                                                                |
| ----------- | ------------- | ------------------------------------------------------------------------------------ |
| `messageId` | string (UUID) | The new `Message.id`                                                                 |
| `status`    | enum          | `PENDING` (silently-quarantined paid) / `ESCROWED` (paid OK) / `DELIVERED` (free OK) |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                             | Reason                                                                                                 |
| ----- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `400` | `message.send.error.self_message`              | `senderId === receiverId`                                                                              |
| `400` | `message.send.error.empty_content`             | Content empty after `.trim()`                                                                          |
| `400` | `message.send.error.creator_unavailable`       | Receiver missing OR `User.status !== ACTIVE`                                                           |
| `400` | `message.send.error.dm_disabled`               | Creator has no `CreatorProfile` OR `dmActive: false`                                                   |
| `400` | `message.send.error.vacation`                  | Creator has `vacationMode: true`                                                                       |
| `400` | `message.send.error.dm_type_mismatch`          | Submitted `dmType` doesn't match creator's configured `dmType`                                         |
| `400` | `message.send.error.duplicate`                 | Same `senderId + receiverId + searchContent` within `messaging.duplicate_window_seconds` (default 60s) |
| `400` | `message.send.error.free_dm_daily_limit`       | `dm.free_daily_limit` exhausted (UTC day)                                                              |
| `400` | `message.send.error.free_dm_per_creator_limit` | `dm.free_per_creator_daily` exhausted for this creator (UTC day)                                       |
| `400` | `message.send.error.service_unavailable`       | Redis cache offline (free DMs only — security-first reject)                                            |
| `400` | `message.send.error.price_below_minimum`       | Submitted `price < activeDMPackage.price`                                                              |
| `400` | `message.send.error.pending_paid_exists`       | Already have a `PENDING`/`ESCROWED` paid DM to this same creator                                       |
| `400` | `payment.escrow.wallet_unavailable`            | No FAN wallet OR `frozen: true` (paid DMs)                                                             |
| `400` | `payment.escrow.insufficient_balance`          | `wallet.balance < price` (paid DMs)                                                                    |
| `401` | (guard)                                        | Missing / invalid bearer token                                                                         |
| `403` | `message.send.error.email_not_verified`        | Sender hasn't verified email                                                                           |
| `403` | `message.send.error.blocked`                   | Receiver has blocked sender (BlockList check)                                                          |
| `429` | (throttle)                                     | Rate limit exceeded (10 req/min)                                                                       |
| `503` | `features.messaging_disabled`                  | Admin kill switch `MESSAGING` is active                                                                |

## Side effects [#side-effects]

1. **Self-message guard** + content non-empty.
2. **Sender email verification gate** (404/403 if missing or unverified).
3. **Receiver gate** — must exist AND `User.status = ACTIVE`.
4. **Block check** — `BlockList { ownerId: receiverId, blockedId: senderId }`.
5. **Creator DM config** — `CreatorProfile.dmActive` AND not `vacationMode` AND `dmType` matches.
6. **Duplicate window** — `searchContent` projection match within `messaging.duplicate_window_seconds`.
7. **Free DM rate limits** (when `dmType = FREE`) — Redis INCR with TTL on `free_dm:<senderId>:<utcDate>` AND `free_dm:<senderId>:<receiverId>:<utcDate>`. Rollback DECR on over-limit. &#x2A;*Reject if Redis offline.**
8. **Get-or-create `ChatSession`** for the (fan, creator) pair (bidirectional match).
9. **Resolve `timeoutHours`** — body or `dm.timeout_hours` default.
10. **Paid DM extra checks** (when `dmType !== 'FREE' && price > 0`):
    * `price >= activeDMPackage.price` (Decimal comparison).
    * **Pending paid concurrency cap** — count of `PENDING`/`ESCROWED` paid DMs from sender to receiver must be `0`.
    * **Pre-escrow balance check** — wallet exists, not frozen, `balance >= price`.
    * **Resolve `commissionRate`** from `creator.commission_<level>` config (per creator level).
11. **Atomic create**: insert `Message` (encrypted `content`, plaintext `searchContent`, `priceSnapshot`, `commissionRate`, `expiresAt`).
12. **Create escrow** for paid DMs via `escrowService.createEscrow` — on failure, **delete the orphan message + new chat session** for recovery.
13. **Snapshot** — `MessageRuleSnapshot.create` (fire-and-forget — failure logs but doesn't block).
14. **Moderation** — `moderateContent(content)` against active `ModerationRule` rows (Redis-cached, DB fallback, hardcoded fallback). On flag:
    * Transition message to `QUARANTINED`.
    * Emit DSA Art. 17 `sorService.emit` (fire-and-forget audit).
    * **Return `{ messageId, status: 'PENDING' }`** to the fan (silent quarantine).
15. **Status transition** (no flag) — paid → `ESCROWED`, free → `DELIVERED`.
16. **Notify creator** via `notificationService.send({ eventKey: 'new_message_creator', deepLink: '/messages/<sessionId>' })` (fire-and-forget; failure logged).
17. **Update `ChatSession.lastMessageAt`** for conversation ordering.
18. Increment `messageSentTotal` Prometheus counter.
19. Return `{ messageId, status }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    # Free DM
    curl -X POST https://api.bio.re/api/v1/messages \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "receiverId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "content": "Loved your latest post!",
        "dmType": "FREE"
      }'

    # Paid DM
    curl -X POST https://api.bio.re/api/v1/messages \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "receiverId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "content": "Quick question about your service.",
        "dmType": "SINGLE_PAY",
        "price": "5.00",
        "timeoutHours": 48
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type DmType = 'FREE' | 'SINGLE_PAY' | 'PER_MESSAGE';

    type SendMessageInput = {
      receiverId: string;
      content: string; // 1-2000 chars
      dmType: DmType;
      price?: string;        // required when dmType !== 'FREE'
      timeoutHours?: number; // 1-720, default from dm.timeout_hours admin config
    };

    type SendMessageResult = {
      messageId: string;
      status: 'PENDING' | 'ESCROWED' | 'DELIVERED';
    };

    async function sendMessage(accessToken: string, input: SendMessageInput): Promise<SendMessageResult> {
      const res = await fetch('https://api.bio.re/api/v1/messages', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Send failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useSendMessage() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (input: SendMessageInput) => {
          const res = await fetch('/api/v1/messages', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Send failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as SendMessageResult;
        },
        onSuccess: () => {
          // Multi-resource invalidation — message lists, conversations, unread, balance (paid DMs)
          qc.invalidateQueries({ queryKey: ['messages'] });
          qc.invalidateQueries({ queryKey: ['wallet', 'balance'] });
          qc.invalidateQueries({ queryKey: ['wallet', 'activity'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/messages', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source                | Path                                                                   | Lines                                                                                                                                                                               |
| --------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Controller            | `apps/api-core/src/modules/message/message.controller.ts`              | `34–54` (`sendMessage`)                                                                                                                                                             |
| DTO (request)         | `apps/api-core/src/modules/message/dto/index.ts`                       | `5–21` (`SendMessageDto`)                                                                                                                                                           |
| DTO (response)        | `apps/api-core/src/modules/message/dto/message-client-response.dto.ts` | `8–14` (`SendMessageResponseDto`)                                                                                                                                                   |
| Service               | `apps/api-core/src/modules/message/message.service.ts`                 | `93–348` (`sendMessage`), `541–584` (`enforceFreeDmLimits`), `488–528` (`moderateContent`), `360–419` (`transition` + `getValidSourceStatuses`)                                     |
| Escrow                | `apps/api-core/src/modules/payment/escrow.service.ts`                  | `createEscrow()`                                                                                                                                                                    |
| Encryption            | `apps/api-core/src/common/encryption.ts`                               | `encryptContent()`                                                                                                                                                                  |
| Notification pipeline | `apps/api-core/src/modules/notification/notification.service.ts`       | `send({ eventKey: 'new_message_creator' })`                                                                                                                                         |
| Config keys           | `apps/api-core/src/modules/config/config.service.ts`                   | `dm.timeout_hours`, `dm.free_daily_limit`, `dm.free_per_creator_daily`, `messaging.duplicate_window_seconds`, `creator.commission_<level>` (admin-managed)                          |
| Prisma models         | `packages/prisma/prisma/schema.prisma`                                 | `Message`, `ChatSession`, `Wallet` (FAN, escrow check), `BlockList`, `CreatorProfile.dm*`, `DMPackage.price`, `MessageRuleSnapshot`, `Escrow`, `ModerationRule`, `MessageStatusLog` |


# Get Unread Count (/docs/message/unread-count)



`GET /api/v1/messages/unread-count` — 🔑 **Bearer** · Rate limit: **60 req / minute** · Kill-switched

Returns the **total count of unread messages** for the calling user — across all sessions. "Unread" = you're the `receiverId` AND `status IN (PENDING, ESCROWED, DELIVERED)`. Use this to drive the navigation badge / app icon counter.



<Callout type="info">
  **Read state isn't user-driven.** There is no `POST /messages/:id/read` — status flips to `READ` server-side when the chat-service Socket.IO layer marks the message read in real-time (or via internal background job). This endpoint counts messages still in `PENDING` / `ESCROWED` / `DELIVERED` — anything beyond `READ` (`REPLIED` / `COMPLETED` / `EXPIRED` / `REFUNDED` / `REJECTED` / `QUARANTINED`) is excluded.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<UnreadCountResponseDto>` [#200-ok--apiresponseofunreadcountresponsedto]

```json
{
  "success": true,
  "data": {
    "total": 5
  }
}
```

| Field   | Type   | Notes                                                               |
| ------- | ------ | ------------------------------------------------------------------- |
| `total` | number | Total unread messages across all sessions where you're the receiver |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`            | Reason                                  |
| ----- | ----------------------------- | --------------------------------------- |
| `401` | (guard)                       | Missing / invalid bearer token          |
| `429` | (throttle)                    | Rate limit exceeded (60 req/min)        |
| `503` | `features.messaging_disabled` | Admin kill switch `MESSAGING` is active |

## Side effects [#side-effects]

1. Single `prisma.message.count({ where: { receiverId: userId, status: { in: [PENDING, ESCROWED, DELIVERED] } } })`.
2. Return `{ total }`. &#x2A;*No mutations.**

## Polling guidance [#polling-guidance]

* Refresh on app focus + after returning from a chat screen (Socket.IO event flips status → count drops).
* Don't tight-loop poll — the count flips via Socket.IO events delivered to the chat-service WebSocket. Subscribe there for real-time updates instead of polling.
* A 30s background refresh covers the case where the user backgrounded the WebSocket layer.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/messages/unread-count \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function getUnreadCount(accessToken: string): Promise<number> {
      const res = await fetch('https://api.bio.re/api/v1/messages/unread-count', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Unread count fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.total as number;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const messageKeys = {
      unreadCount: () => ['messages', 'unread-count'] as const,
    };

    export function useUnreadCount() {
      return useQuery({
        queryKey: messageKeys.unreadCount(),
        queryFn: async () => {
          const res = await fetch('/api/v1/messages/unread-count');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Unread count fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.total as number;
        },
        // Refresh on focus is the primary trigger; tight polling is wasteful (use Socket.IO instead)
        staleTime: 30_000,
        refetchOnWindowFocus: true,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/messages/unread-count', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source            | Path                                                                   | Lines                                                         |
| ----------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------- |
| Controller        | `apps/api-core/src/modules/message/message.controller.ts`              | `125–131` (`getUnreadCount`)                                  |
| DTO (response)    | `apps/api-core/src/modules/message/dto/message-client-response.dto.ts` | `155–158` (`UnreadCountResponseDto`)                          |
| Service           | `apps/api-core/src/modules/message/message.service.ts`                 | `915–923` (`getUnreadCount`)                                  |
| Real-time updates | `apps/chat-service/`                                                   | Socket.IO events flip read state on the server side           |
| Prisma model      | `packages/prisma/prisma/schema.prisma`                                 | `Message.status` (`enum MessageStatus`), `Message.receiverId` |


# Get Last-Seen + Online Status (/docs/presence/last-seen)



`GET /api/v1/presence/:userId/last-seen` — 🔑 **Bearer** · Rate limit: **60 req / minute**

Read the live presence snapshot for any user — typically rendered as a green dot ("online") or "Last seen 5 min ago" in chat surfaces, profile cards, and the inbox list. The state is **written by chat-service** (Socket.IO connect / disconnect events) and **read by api-core** through a shared session-Redis instance — this endpoint is the read side.



<Callout type="info">
  **Two Redis keys, two semantics, one snapshot.** `isOnline` is derived from `presence:{userId}` (a Redis SET of active socket IDs, TTL 60s — `scard > 0` means at least one live socket). `lastSeen` is read from `presence:lastseen:{userId}` (ISO-8601 string, TTL \~30 days). Both reads are issued in parallel; the response combines them. No DB hop.
</Callout>

<Callout type="warn">
  **`lastSeen: null` is ambiguous on purpose.** It means *one of*: the user has never connected, the 30-day TTL has expired, or the session Redis was unreachable on this request. **Don't render "Last seen never" with confidence** — show "Last seen a while ago" or simply hide the row. The endpoint cannot distinguish these cases.
</Callout>

<Callout type="warn">
  **Soft-degrades to "offline" when Redis session is down.** If the session Redis is unavailable or the read throws, the controller still returns `200` with `{ isOnline: false, lastSeen: null }` instead of erroring. Treat absence of online state as "unknown," not "definitely offline" — the user might be live but the read just failed. Surfacing a stale "online" dot is worse than a missing dot, so this is the right default — but log/Sentry your own client retry policy if you build off this.
</Callout>

<Callout type="warn">
  **v1 has no privacy gate.** Any authenticated user can read presence for any other userId. There is **no** "hide online status" preference on `UserSettings` yet — that's a planned follow-up. Don't expose this endpoint in your UI as if it were privacy-aware: the user being looked up has no opt-out.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param    | Type          | Required | Validation                                                    | Notes                                                                                                                                                   |
| -------- | ------------- | -------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId` | string (UUID) | ✓        | `ParseUUIDPipe` (Nest built-in — rejects non-UUID with `400`) | Target user. Any UUID is accepted; non-existent userIds return `isOnline: false, lastSeen: null` (no 404 — Redis miss looks identical to "never seen"). |

| Header                                | Required | Notes                                                 |
| ------------------------------------- | -------- | ----------------------------------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login`. `JwtAuthGuard` enforces. |

No body, no query params.

## Response [#response]

### `200 OK` — `ApiResponseOf<PresenceLastSeenDto>` [#200-ok--apiresponseofpresencelastseendto]

```json
{
  "success": true,
  "data": {
    "userId": "00000000-0000-4000-8000-000000000001",
    "lastSeen": "2026-04-24T12:34:56.000Z",
    "isOnline": false
  }
}
```

### Fields [#fields]

| Field      | Type           | Notes                                                                                                                                                                                       |
| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId`   | string (UUID)  | Echo of the path parameter.                                                                                                                                                                 |
| `lastSeen` | string \| null | ISO-8601 timestamp of the user's most recent disconnect. `null` when never seen / 30-day TTL expired / Redis read failed.                                                                   |
| `isOnline` | boolean        | `true` iff at least one socket ID is in the live presence set (`scard(presence:{userId}) > 0`). The set has a 60s TTL — sockets that drop without a clean disconnect age out automatically. |

### Errors [#errors]

| HTTP  | Reason                                                  |
| ----- | ------------------------------------------------------- |
| `400` | `userId` is not a valid UUID (`ParseUUIDPipe` rejects). |
| `401` | Missing / invalid bearer token.                         |
| `429` | Rate limit exceeded (60 req/min).                       |

**No `404` for unknown users.** A nonexistent or never-seen userId returns `200` with `{ isOnline: false, lastSeen: null }` — the Redis miss path doesn't validate that the user row exists. If you need to confirm the user is real, hit `GET /users/:id` separately.

## Side effects [#side-effects]

1. `JwtAuthGuard` validates the bearer token; `ParseUUIDPipe` validates `userId`.
2. Resolve the session Redis instance. If unavailable → return `{ userId, lastSeen: null, isOnline: false }` (no throw).
3. Issue **two parallel Redis reads** against the session instance:
   * `SCARD presence:{userId}` → integer count of live socket IDs
   * `GET presence:lastseen:{userId}` → ISO-8601 string or `null`
4. Combine: `isOnline = (count ?? 0) > 0`, `lastSeen = value ?? null`.
5. On any Redis exception → log warning, return `{ lastSeen: null, isOnline: false }`. &#x2A;*No retry, no Sentry side effect, no DB write.**

This endpoint is strictly read-only — the keys are written by `apps/chat-service/src/presence.ts` on Socket.IO connect (add socketId to set, refresh TTL) / disconnect (remove socketId, write `lastseen` timestamp on the final disconnect).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query (polling)', 'Render helper']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/presence/00000000-0000-4000-8000-000000000001/last-seen \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type PresenceSnapshot = {
      userId: string;
      lastSeen: string | null; // ISO-8601 or null
      isOnline: boolean;
    };

    async function getPresence(
      accessToken: string,
      userId: string,
    ): Promise<PresenceSnapshot> {
      const res = await fetch(
        `https://api.bio.re/api/v1/presence/${userId}/last-seen`,
        { headers: { Authorization: `Bearer ${accessToken}` } },
      );
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Presence fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query (polling)">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const presenceKeys = {
      forUser: (userId: string) => ['presence', userId] as const,
    };

    // Poll every 60s — matches the presence:{userId} Redis TTL.
    // Sockets that disconnect cleanly write lastSeen immediately;
    // sockets that drop will age out within 60s, so polling at this
    // cadence keeps the UI within one tick of reality.
    export function usePresence(userId: string, enabled = true) {
      return useQuery({
        queryKey: presenceKeys.forUser(userId),
        queryFn: async () => {
          const res = await fetch(`/api/v1/presence/${userId}/last-seen`);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Presence fetch failed'), {
              code: json?.error?.code,
            });
          }
          return json.data as PresenceSnapshot;
        },
        enabled,
        refetchInterval: 60_000,
        // Stale = the moment we get the response. We want fresh on remount.
        staleTime: 0,
      });
    }
    ```
  </Tab>

  <Tab value="Render helper">
    ```ts
    function formatPresence(snap: PresenceSnapshot, now = Date.now()): string {
      if (snap.isOnline) return 'Online';
      if (!snap.lastSeen) return 'Last seen a while ago'; // ambiguous null — never / TTL / read fail
      const diffMs = now - new Date(snap.lastSeen).getTime();
      const min = Math.floor(diffMs / 60_000);
      if (min < 1) return 'Just now';
      if (min < 60) return `Last seen ${min}m ago`;
      const hr = Math.floor(min / 60);
      if (hr < 24) return `Last seen ${hr}h ago`;
      const day = Math.floor(hr / 24);
      return `Last seen ${day}d ago`;
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/presence/{userId}/last-seen', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source                     | Path                                                              | Lines                                                                               |
| -------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Controller                 | `apps/api-core/src/modules/presence/presence.controller.ts`       | `20–37` (class), `27–36` (`getLastSeen`)                                            |
| DTO (response)             | `apps/api-core/src/modules/presence/dto/presence-response.dto.ts` | `10–24` (`PresenceLastSeenDto`)                                                     |
| Service                    | `apps/api-core/src/modules/presence/presence.service.ts`          | `33–54` (`getPresence` — Redis read + soft-degrade)                                 |
| Redis key constants        | `apps/api-core/src/modules/presence/presence.service.ts`          | `14–15` (`PRESENCE_PREFIX = 'presence:'`, `LASTSEEN_PREFIX = 'presence:lastseen:'`) |
| Write-side (informational) | `apps/chat-service/src/presence.ts`                               | `24–25` (matching key constants — same Redis instance)                              |


# Create Support Ticket (/docs/support/create)



`POST /api/v1/tickets` — 🔑 **Bearer** · Rate limit: **5 req / minute**

Creates a new support ticket owned by the current user. The first message body is created in the same DB transaction, so the ticket starts with exactly one user message and is ready for an agent to pick up.



<Callout type="info">
  **Single-shot atomic write.** The ticket row and its first `TicketMessage` are created in one Prisma `$transaction([...])`. Either both rows land or neither does — there's no half-created state where the ticket exists but has no body.
</Callout>

<Callout type="info">
  **Priority resolution order:** explicit `priority` in body > category's default priority (if `categoryId` is set) > `MEDIUM`. The category is fetched only when `categoryId` is provided; if it doesn't exist, the request fails with `support.category.not_found` (404) **before** any ticket is created.
</Callout>

<Callout type="warn">
  **Notification is fire-and-forget.** After the ticket is committed, the service calls `notificationService.send({ eventKey: 'ticket_created', ... })` and **does not await** the result — failures are logged but never bubble up. A 201 means the ticket was created; it does NOT mean the user has been notified yet.
</Callout>

## Request [#request]

### Body — `CreateTicketDto` [#body--createticketdto]

| Field        | Type          | Required | Validation                                                | Notes                                                                                           |
| ------------ | ------------- | -------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `subject`    | string        | ✓        | `MinLength(3) + MaxLength(200)`                           | Short title — surface in the inbox row.                                                         |
| `content`    | string        | ✓        | `MinLength(10) + MaxLength(5000)`                         | First message body. Plain text — no HTML sanitization at this layer.                            |
| `categoryId` | string (UUID) | optional | `IsString`                                                | Pre-existing category from the admin tool. If supplied and not found → 404.                     |
| `priority`   | enum          | optional | `IsEnum(Priority)` — `LOW` / `MEDIUM` / `HIGH` / `URGENT` | Overrides the category default. Omit to inherit from the category, or fall through to `MEDIUM`. |

### Headers [#headers]

| Header                                | Required | Notes                  |
| ------------------------------------- | -------- | ---------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | Global `JwtAuthGuard`. |
| `Content-Type: application/json`      | ✓        | Standard.              |

## Response [#response]

### `201 Created` — `ApiResponseOf<CreateTicketResponseDto>` [#201-created--apiresponseofcreateticketresponsedto]

```json
{
  "success": true,
  "data": {
    "ticketId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

| Field      | Type          | Notes                                                                                                                                                    |
| ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ticketId` | string (UUID) | Server-generated `randomUUID()`. Use it as `:ticketId` for [detail](/docs/support/detail), [reply](/docs/support/reply), [reopen](/docs/support/reopen). |

The ticket starts at `status: 'OPEN'` with the resolved priority. The first message is created with `authorType: 'USER'` and `isInternal: false`.

### Errors [#errors]

| HTTP  | Code / `i18nKey`             | Reason                                                                                      |
| ----- | ---------------------------- | ------------------------------------------------------------------------------------------- |
| `400` | (DTO validation)             | `subject`/`content` length out of range, missing fields, unknown enum value for `priority`. |
| `401` | (guard)                      | Missing / invalid bearer token.                                                             |
| `404` | `support.category.not_found` | `categoryId` was supplied but the row doesn't exist. &#x2A;*No ticket is created.**         |
| `429` | `THROTTLE_LIMIT_EXCEEDED`    | More than 5 requests / minute from this IP. Response carries `retryAfter` (seconds).        |

## Side effects [#side-effects]

1. Decode bearer (global `JwtAuthGuard`).
2. `ThrottleGuard` increments `throttle:<ip>:POST:/api/v1/tickets` in Redis cache; throws `429` if count > 5 in 60s window. Falls back to in-process Map if Redis cache is down.
3. If `categoryId` is set: `prisma.ticketCategory.findUnique({ where: { id }, select: { id, priority } })`. Missing → throw `I18nNotFound('support.category.not_found')` (no rows written).
4. Resolve `priority`: `body.priority ?? cat.priority ?? Priority.MEDIUM`.
5. Generate `ticketId = randomUUID()`.
6. **Atomic write** via `prisma.$transaction([...])`:
   * Create `Ticket` row: `{ id: ticketId, userId, subject, status: 'OPEN', priority, categoryId }`.
   * Create `TicketMessage` row: `{ id: randomUUID(), ticketId, authorId: userId, authorType: 'USER', content, isInternal: false }`.
7. **Fire-and-forget** notification: `notificationService.send({ eventKey: 'ticket_created', userId, variables: { ticketId } })` — `.catch(...)` logs errors only.
8. Log `[support] Ticket created: <id> (priority: <p>)` and return `{ ticketId }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query (mutation)']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/tickets \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "subject": "Payout delayed by 3 days",
        "content": "I requested a payout on 2026-04-20 but I have not received the funds yet.",
        "categoryId": "11111111-2222-3333-4444-555555555555"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type CreateTicketBody = {
      subject: string;     // 3-200 chars
      content: string;     // 10-5000 chars
      categoryId?: string;
      priority?: 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT';
    };

    async function createTicket(
      accessToken: string,
      body: CreateTicketBody,
    ): Promise<{ ticketId: string }> {
      const res = await fetch('https://api.bio.re/api/v1/tickets', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(body),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Create failed'), {
          code: json?.error?.code,
          retryAfter: json?.retryAfter,  // present on 429
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query (mutation)">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useCreateTicket() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (body: CreateTicketBody) => {
          const res = await fetch('/api/v1/tickets', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(body),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Create failed'), {
              code: json?.error?.code,
            });
          }
          return json.data as { ticketId: string };
        },
        onSuccess: () => {
          // The new ticket is OPEN — invalidate the ticket list so it re-fetches.
          qc.invalidateQueries({ queryKey: ['support', 'tickets'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/tickets', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                            | Lines                                                                                                                        |
| -------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/support/support.controller.ts`       | `48–57` (`create`, `@Throttle(5, 60)`)                                                                                       |
| DTO (request)  | `apps/api-core/src/modules/support/dto/index.ts`                | `5–17` (`CreateTicketDto`)                                                                                                   |
| DTO (response) | `apps/api-core/src/modules/support/dto/support-response.dto.ts` | `217–220` (`CreateTicketResponseDto`)                                                                                        |
| Service        | `apps/api-core/src/modules/support/support.service.ts`          | `52–74` (`createTicket` — category lookup, priority resolution, $transaction, notification)                                  |
| Throttle       | `apps/api-core/src/common/guards/throttle.guard.ts`             | `64–79` (Redis), `81–101` (in-memory fallback)                                                                               |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                          | `Ticket` lines `1245–1266`, `TicketMessage` lines `1268–1279`, `TicketCategory` lines `1281–1292`, `Priority` enum `819–824` |


# Get Ticket Detail (/docs/support/detail)



`GET /api/v1/tickets/:ticketId` — 🔑 **Bearer**

Returns the ticket plus its full ordered message history and the embedded category. **Owned by current user only** — see the security note below.



<Callout type="warn">
  **Foreign tickets respond `404`, not `403`.** The service does `if (!ticket || ticket.userId !== userId) throw I18nNotFound(...)`. This collapses two cases into one response so a caller can't probe for existence by trying random UUIDs. Don't try to distinguish "not found" from "not yours" client-side — they're indistinguishable on the wire by design.
</Callout>

<Callout type="info">
  **Internal messages are NOT filtered out here.** The service does `include: { messages: { orderBy: { createdAt: 'asc' } } }` — every `TicketMessage` row is returned, including those with `isInternal: true`. As of writing, the user-side controller doesn't strip them. **Hide rows where `isInternal === true` client-side** when rendering the user-facing thread, otherwise admin-only notes will leak into the user's UI.
</Callout>

<Callout type="info">
  **No throttle on this read.** Same as the list — only the ticket-create handler has `@Throttle()`. Polling is fine.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param      | Type          | Required | Validation                                    | Notes                                      |
| ---------- | ------------- | -------- | --------------------------------------------- | ------------------------------------------ |
| `ticketId` | string (UUID) | ✓        | `ParseUUIDPipe` (rejects non-UUID with `400`) | The ticket id you got from create or list. |

### Headers [#headers]

| Header                                | Required | Notes                  |
| ------------------------------------- | -------- | ---------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | Global `JwtAuthGuard`. |

## Response [#response]

### `200 OK` — `ApiResponseOf<TicketDetailDto>` [#200-ok--apiresponseofticketdetaildto]

```json
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userId": "00000000-0000-4000-8000-000000000001",
    "categoryId": "11111111-2222-3333-4444-555555555555",
    "subject": "Payout delayed by 3 days",
    "status": "WAITING_USER",
    "priority": "HIGH",
    "assignedTo": "agent-uuid",
    "resolvedAt": null,
    "closedAt": null,
    "createdAt": "2026-04-20T09:00:00.000Z",
    "updatedAt": "2026-04-22T14:30:00.000Z",
    "category": {
      "id": "11111111-2222-3333-4444-555555555555",
      "name": "Payments",
      "description": "Payment-related issues",
      "priority": "HIGH",
      "active": true,
      "sortOrder": 1,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    },
    "messages": [
      {
        "id": "msg-uuid-1",
        "ticketId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "authorId": "00000000-0000-4000-8000-000000000001",
        "authorType": "USER",
        "content": "I requested a payout on 2026-04-20 but I have not received the funds yet.",
        "isInternal": false,
        "createdAt": "2026-04-20T09:00:00.000Z"
      },
      {
        "id": "msg-uuid-2",
        "ticketId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "authorId": "agent-uuid",
        "authorType": "AGENT",
        "content": "Looking into this. Can you confirm the bank account on file?",
        "isInternal": false,
        "createdAt": "2026-04-22T14:30:00.000Z"
      }
    ]
  }
}
```

### Top-level fields [#top-level-fields]

Same as the [list item](/docs/support/list#item-fields-items) plus:

| Field      | Type                      | Notes                                                                                                        |
| ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `messages` | `TicketMessageEmbedDto[]` | Full message history sorted by `createdAt ASC` (oldest first). Includes internal notes — filter client-side. |

### Message fields (`messages[]`) [#message-fields-messages]

| Field        | Type              | Notes                                                                                                |
| ------------ | ----------------- | ---------------------------------------------------------------------------------------------------- |
| `id`         | string (UUID)     | Message id. No public endpoint to fetch a single message — always read via the parent ticket.        |
| `ticketId`   | string (UUID)     | Echo of the path parameter.                                                                          |
| `authorId`   | string (UUID)     | The user (`USER`) or agent (`AGENT`) who wrote this message.                                         |
| `authorType` | enum              | `USER` or `AGENT`.                                                                                   |
| `content`    | string            | Plain text — no HTML sanitization at this layer. Render with `whiteSpace: pre-wrap` for line breaks. |
| `isInternal` | boolean           | **Hide rows where this is `true`** in the user-facing UI.                                            |
| `createdAt`  | string (ISO 8601) | When the message was created.                                                                        |

### Errors [#errors]

| HTTP  | Code / `i18nKey`           | Reason                                                                                               |
| ----- | -------------------------- | ---------------------------------------------------------------------------------------------------- |
| `400` | (`ParseUUIDPipe`)          | `:ticketId` is not a UUID.                                                                           |
| `401` | (guard)                    | Missing / invalid bearer token.                                                                      |
| `404` | `support.ticket.not_found` | Ticket doesn't exist OR belongs to another user. &#x2A;*Cases are intentionally indistinguishable.** |

## Side effects [#side-effects]

1. Decode bearer; `ParseUUIDPipe` validates `:ticketId`.
2. `prisma.ticket.findUnique({ where: { id }, include: { messages: { orderBy: { createdAt: 'asc' } }, category: true } })`.
3. **Owner check + missing collapsed**: `if (!ticket || ticket.userId !== userId) throw I18nNotFound`.
4. Return the ticket as-is. &#x2A;*No DB writes, no notifications.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type TicketMessage = {
      id: string;
      ticketId: string;
      authorId: string;
      authorType: 'USER' | 'AGENT';
      content: string;
      isInternal: boolean;
      createdAt: string;
    };

    type TicketDetail = TicketListItem & { messages: TicketMessage[] };

    async function getTicket(
      accessToken: string,
      ticketId: string,
    ): Promise<TicketDetail> {
      const res = await fetch(
        `https://api.bio.re/api/v1/tickets/${ticketId}`,
        { headers: { Authorization: `Bearer ${accessToken}` } },
      );
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }

    // In your render layer — strip internal notes before showing to the user:
    const visible = (await getTicket(token, id)).messages.filter(m => !m.isInternal);
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export function useTicketDetail(ticketId: string) {
      return useQuery({
        queryKey: ['support', 'ticket', ticketId],
        queryFn: async () => {
          const res = await fetch(`/api/v1/tickets/${ticketId}`);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Fetch failed'), {
              code: json?.error?.code,
            });
          }
          return json.data as TicketDetail;
        },
        enabled: !!ticketId,
        // Refetch every 30s while the user is on this page; pair with a "send reply"
        // mutation that invalidates this query for instant updates after they post.
        refetchInterval: 30_000,
        staleTime: 0,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/tickets/{ticketId}', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                            | Lines                                                             |
| -------------- | --------------------------------------------------------------- | ----------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/support/support.controller.ts`       | `59–66` (`get`)                                                   |
| Service        | `apps/api-core/src/modules/support/support.service.ts`          | `102–109` (`getTicket` — owner check collapses 404 + 403)         |
| DTO (response) | `apps/api-core/src/modules/support/dto/support-response.dto.ts` | `114–117` (`TicketDetailDto`), `85–106` (`TicketMessageEmbedDto`) |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                          | `Ticket` lines `1245–1266`, `TicketMessage` lines `1268–1279`     |


# List My Tickets (/docs/support/list)



`GET /api/v1/tickets` — 🔑 **Bearer**

Returns a page of tickets owned by the current user (the bearer-token subject). Always filtered by `userId = req.user.id` server-side — there is **no way** to ask for someone else's tickets through this endpoint, regardless of query params.



<Callout type="info">
  **No throttle on this endpoint.** The class registers `@UseGuards(ThrottleGuard)` but only the ticket-create handler carries `@Throttle(5, 60)`. The list / detail / reply / reopen handlers have **no `@Throttle()` decorator**, and `ThrottleGuard.canActivate()` returns `true` when no decorator is found. List as freely as your client needs to.
</Callout>

<Callout type="warn">
  **`status` filter takes one value.** It's an enum string — `OPEN`, `ASSIGNED`, `IN_PROGRESS`, `WAITING_USER`, `WAITING_INTERNAL`, `RESOLVED`, or `CLOSED`. There's no `IN(...)` or comma-separated form. To show "active" tickets (not RESOLVED/CLOSED), omit the filter and partition client-side, or fire two parallel calls.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param    | Type              | Default | Notes                                                                                                                   |
| -------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `page`   | integer (1-based) | `1`     | Page number. Parsed via `parseInt` — `?page=abc` becomes `NaN`, then defaults to `1`.                                   |
| `limit`  | integer           | `20`    | Items per page. Service caps at &#x2A;*`100`** (`Math.min(limit, 100)`).                                                |
| `status` | enum              | —       | One of: `OPEN`, `ASSIGNED`, `IN_PROGRESS`, `WAITING_USER`, `WAITING_INTERNAL`, `RESOLVED`, `CLOSED`. Single value only. |

### Headers [#headers]

| Header                                | Required | Notes                           |
| ------------------------------------- | -------- | ------------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | Global `JwtAuthGuard` enforces. |

No body.

## Response [#response]

### `200 OK` — `PaginatedApiResponseOf<TicketListItemDto>` [#200-ok--paginatedapiresponseofticketlistitemdto]

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "userId": "00000000-0000-4000-8000-000000000001",
        "categoryId": "11111111-2222-3333-4444-555555555555",
        "subject": "Payout delayed by 3 days",
        "status": "WAITING_USER",
        "priority": "HIGH",
        "assignedTo": "agent-uuid",
        "resolvedAt": null,
        "closedAt": null,
        "createdAt": "2026-04-20T09:00:00.000Z",
        "updatedAt": "2026-04-22T14:30:00.000Z",
        "category": {
          "id": "11111111-2222-3333-4444-555555555555",
          "name": "Payments",
          "description": "Payment-related issues",
          "priority": "HIGH",
          "active": true,
          "sortOrder": 1,
          "createdAt": "2026-01-01T00:00:00.000Z",
          "updatedAt": "2026-01-01T00:00:00.000Z"
        }
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}
```

### Item fields (`items[]`) [#item-fields-items]

| Field                     | Type                      | Notes                                                                                            |
| ------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------ |
| `id`                      | string (UUID)             | Use as `:ticketId` for the detail/reply/reopen endpoints.                                        |
| `userId`                  | string (UUID)             | Always equals the authenticated user's id.                                                       |
| `categoryId`              | string (UUID) \| null     | Optional category at create time. Cascades to `null` if the category is deleted.                 |
| `subject`                 | string                    | 3-200 chars (validated on create).                                                               |
| `status`                  | enum                      | See [state machine](#status-state-machine) below.                                                |
| `priority`                | enum                      | `LOW` / `MEDIUM` / `HIGH` / `URGENT`. Defaults from category at create time, otherwise `MEDIUM`. |
| `assignedTo`              | string (UUID) \| null     | Agent currently assigned (admin-side action — user has no control).                              |
| `resolvedAt`              | string (ISO 8601) \| null | Set when ticket transitions to `RESOLVED`. Cleared on reopen.                                    |
| `closedAt`                | string (ISO 8601) \| null | Set when ticket transitions to `CLOSED`. Cleared on reopen.                                      |
| `createdAt` / `updatedAt` | string (ISO 8601)         | Standard timestamps.                                                                             |
| `category`                | object \| null            | Embedded full `TicketCategoryDto` (when set). Always included; not `categoryId`-only.            |

### Pagination envelope [#pagination-envelope]

| Field            | Type   | Notes                                                      |
| ---------------- | ------ | ---------------------------------------------------------- |
| `total`          | number | Total tickets matching the filter (for the current user).  |
| `page` / `limit` | number | Echo of the effective values (after defaulting + capping). |
| `totalPages`     | number | `Math.ceil(total / limit)`.                                |

### Errors [#errors]

| HTTP  | Reason                          |
| ----- | ------------------------------- |
| `401` | Missing / invalid bearer token. |

## Status state machine [#status-state-machine]

`status` is one of these states. Transitions are enforced server-side (see [reopen](/docs/support/reopen)):

| State              | Set by                                          | Next legal states                                        |
| ------------------ | ----------------------------------------------- | -------------------------------------------------------- |
| `OPEN`             | Ticket creation                                 | `ASSIGNED`                                               |
| `ASSIGNED`         | Admin assigns agent                             | `IN_PROGRESS`, `RESOLVED`, `CLOSED`                      |
| `IN_PROGRESS`      | Admin/agent reply, user reply on `WAITING_USER` | `WAITING_USER`, `WAITING_INTERNAL`, `RESOLVED`, `CLOSED` |
| `WAITING_USER`     | Agent reply                                     | `IN_PROGRESS` (on user reply), `RESOLVED`, `CLOSED`      |
| `WAITING_INTERNAL` | Admin escalation                                | `IN_PROGRESS`, `RESOLVED`, `CLOSED`                      |
| `RESOLVED`         | Admin resolves                                  | `CLOSED`, `OPEN` (via reopen)                            |
| `CLOSED`           | Admin closes                                    | `OPEN` (via reopen)                                      |

## Side effects [#side-effects]

1. Decode bearer token (global `JwtAuthGuard`); `req.user.id` is forwarded as `@CurrentUser('id')`.
2. Service builds `where = { userId }` plus optional `status`. **The `userId` clause is unconditional** — even if the controller forwarded an empty body or weird query, the WHERE always filters to the current user.
3. Two parallel Prisma queries:
   * `prisma.ticket.findMany({ where, orderBy: { createdAt: 'desc' }, skip, take, include: { category: true } })`
   * `prisma.ticket.count({ where })`
4. Compute `totalPages = Math.ceil(total / limit)`. Return the envelope.

**No mutations.** No notifications, no logs, no Redis touches.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query (paged)']">
  <Tab value="curl">
    ```bash
    # All my tickets, page 1, 20 per page
    curl https://api.bio.re/api/v1/tickets \
      -H "Authorization: Bearer $ACCESS_TOKEN"

    # Only OPEN tickets
    curl 'https://api.bio.re/api/v1/tickets?status=OPEN' \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type TicketStatus =
      | 'OPEN' | 'ASSIGNED' | 'IN_PROGRESS'
      | 'WAITING_USER' | 'WAITING_INTERNAL' | 'RESOLVED' | 'CLOSED';

    type TicketListItem = {
      id: string;
      userId: string;
      categoryId: string | null;
      subject: string;
      status: TicketStatus;
      priority: 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT';
      assignedTo: string | null;
      resolvedAt: string | null;
      closedAt: string | null;
      createdAt: string;
      updatedAt: string;
      category: { id: string; name: string; priority: string } | null;
    };

    type TicketListResponse = {
      items: TicketListItem[];
      total: number;
      page: number;
      limit: number;
      totalPages: number;
    };

    async function listTickets(
      accessToken: string,
      opts?: { page?: number; limit?: number; status?: TicketStatus },
    ): Promise<TicketListResponse> {
      const url = new URL('https://api.bio.re/api/v1/tickets');
      if (opts?.page) url.searchParams.set('page', String(opts.page));
      if (opts?.limit) url.searchParams.set('limit', String(opts.limit));
      if (opts?.status) url.searchParams.set('status', opts.status);

      const res = await fetch(url, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'List failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query (paged)">
    ```ts
    import { useQuery, keepPreviousData } from '@tanstack/react-query';

    export const supportKeys = {
      list: (opts: { page: number; status?: TicketStatus }) =>
        ['support', 'tickets', opts] as const,
      detail: (ticketId: string) => ['support', 'ticket', ticketId] as const,
    };

    export function useMyTickets(page = 1, status?: TicketStatus) {
      return useQuery({
        queryKey: supportKeys.list({ page, status }),
        queryFn: async () => {
          const url = new URL('/api/v1/tickets', location.origin);
          url.searchParams.set('page', String(page));
          if (status) url.searchParams.set('status', status);

          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'List failed'), {
              code: json?.error?.code,
            });
          }
          return json.data as TicketListResponse;
        },
        placeholderData: keepPreviousData,
        staleTime: 30_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/tickets', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source            | Path                                                            | Lines                                                                                |
| ----------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Controller        | `apps/api-core/src/modules/support/support.controller.ts`       | `20–46` (class), `27–46` (`list`)                                                    |
| Service           | `apps/api-core/src/modules/support/support.service.ts`          | `216–230` (`listTickets` — owner filter, ordering, pagination)                       |
| DTO (response)    | `apps/api-core/src/modules/support/dto/support-response.dto.ts` | `41–77` (`TicketListItemDto`), `9–33` (`TicketCategoryDto`)                          |
| Throttle behavior | `apps/api-core/src/common/guards/throttle.guard.ts`             | `43–48` (no-decorator → `return true`)                                               |
| Global JWT guard  | `apps/api-core/src/app.module.ts`                               | `62` (`APP_GUARD: JwtAuthGuard`)                                                     |
| Prisma model      | `packages/prisma/prisma/schema.prisma`                          | `Ticket` lines `1245–1266`, `TicketStatus` enum `809–817`, `Priority` enum `819–824` |


# Reopen Ticket (/docs/support/reopen)



`POST /api/v1/tickets/:ticketId/reopen` — 🔑 **Bearer**

Transitions a ticket from `RESOLVED` or `CLOSED` back to `OPEN`. Both `resolvedAt` and `closedAt` are nulled in the same update. Use this when the user's underlying issue wasn't actually solved and they need an agent to look again.



<Callout type="warn">
  **Only `RESOLVED` and `CLOSED` can be reopened.** The transition map says `RESOLVED → CLOSED, OPEN` and `CLOSED → OPEN`. Trying to reopen an already-active ticket (`OPEN`, `ASSIGNED`, `IN_PROGRESS`, `WAITING_USER`, `WAITING_INTERNAL`) returns `400 support.ticket.invalid_transition` with the current status in the error payload. The transition validator runs **before** the ownership check.
</Callout>

<Callout type="warn">
  **Error precedence: not-found > invalid-transition > not-owner.** The validator runs `findUnique` first (404 if missing), then checks the transition map (400 if not in `RESOLVED`/`CLOSED`), and only then does the ownership check (403). So if you try to reopen someone else's already-OPEN ticket, you get `400`, not `403` — the existence + state of the ticket are revealed before authorization. Worth knowing if you build any abuse rules around this.
</Callout>

<Callout type="info">
  **No notification fires from this endpoint.** Unlike create and reply, the reopen path doesn't emit any `ticket_*` event — the admin/agent will see the ticket back at the top of the OPEN queue on their next refresh, but no push/email is sent.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param      | Type          | Required | Validation      | Notes                                                      |
| ---------- | ------------- | -------- | --------------- | ---------------------------------------------------------- |
| `ticketId` | string (UUID) | ✓        | `ParseUUIDPipe` | Your ticket — must currently be in `RESOLVED` or `CLOSED`. |

### Headers [#headers]

| Header                                | Required | Notes                  |
| ------------------------------------- | -------- | ---------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | Global `JwtAuthGuard`. |

No body.

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{ "success": true }
```

After this returns, fetching [`GET /tickets/:ticketId`](/docs/support/detail) shows:

* `status: 'OPEN'`
* `resolvedAt: null`
* `closedAt: null`
* existing `messages[]` unchanged (no new system message is appended)

The ticket is now back in the agent queue with no assignment carry-over (the previous `assignedTo` value is left as-is — only `status`, `resolvedAt`, `closedAt` are touched).

### Errors [#errors]

| HTTP  | Code / `i18nKey`                    | Reason                                                                                                                                       |
| ----- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | (`ParseUUIDPipe`)                   | `:ticketId` is not a UUID.                                                                                                                   |
| `400` | `support.ticket.invalid_transition` | Ticket is in a status that doesn't allow `OPEN` (anything except `RESOLVED` / `CLOSED`). Payload: `{ currentStatus, targetStatus: 'OPEN' }`. |
| `401` | (guard)                             | Missing / invalid bearer token.                                                                                                              |
| `403` | `support.ticket.not_owner`          | The ticket exists, is in `RESOLVED`/`CLOSED`, but belongs to another user. (See note above on error precedence.)                             |
| `404` | `support.ticket.not_found`          | Ticket does not exist.                                                                                                                       |

## Side effects [#side-effects]

1. Decode bearer; `ParseUUIDPipe` validates `:ticketId`.
2. **Transition validator first**: `prisma.ticket.findUnique({ where: { id } })`. Missing → throw `404`. Then check `status` is in `['RESOLVED', 'CLOSED']`; if not → throw `400 invalid_transition`.
3. **Owner check second**: `if (ticket.userId !== userId) throw 403 not_owner`.
4. `prisma.ticket.update({ where: { id }, data: { status: 'OPEN', resolvedAt: null, closedAt: null } })` — no transaction (single row write).
5. **No notification, no log mutation**, no message append. The audit trail of "user reopened" lives only in the status/timestamp diff.
6. Return `{ success: true }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query (mutation)']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/reopen \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function reopenTicket(
      accessToken: string,
      ticketId: string,
    ): Promise<void> {
      const res = await fetch(
        `https://api.bio.re/api/v1/tickets/${ticketId}/reopen`,
        {
          method: 'POST',
          headers: { Authorization: `Bearer ${accessToken}` },
        },
      );
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Reopen failed'), {
          code: json?.error?.code,
          // For invalid_transition, the API includes currentStatus in the payload:
          currentStatus: json?.error?.payload?.currentStatus,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query (mutation)">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useReopenTicket(ticketId: string) {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async () => {
          const res = await fetch(`/api/v1/tickets/${ticketId}/reopen`, {
            method: 'POST',
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Reopen failed'), {
              code: json?.error?.code,
            });
          }
        },
        onSuccess: () => {
          // status flipped to OPEN, resolvedAt/closedAt cleared
          qc.invalidateQueries({ queryKey: ['support', 'ticket', ticketId] });
          qc.invalidateQueries({ queryKey: ['support', 'tickets'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/tickets/{ticketId}/reopen', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source               | Path                                                      | Lines                                                                                                                           |
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Controller           | `apps/api-core/src/modules/support/support.controller.ts` | `80–90` (`reopen`)                                                                                                              |
| Service              | `apps/api-core/src/modules/support/support.service.ts`    | `130–134` (`reopenTicket` — transition validator + owner check + null timestamps)                                               |
| Transition validator | `apps/api-core/src/modules/support/support.service.ts`    | `36–48` (`validateTicketTransition`), `12–20` (`VALID_TICKET_TRANSITIONS` — only `RESOLVED → OPEN` and `CLOSED → OPEN` allowed) |
| Prisma model         | `packages/prisma/prisma/schema.prisma`                    | `Ticket` lines `1245–1266`, `TicketStatus` enum `809–817`                                                                       |


# Reply to Ticket (/docs/support/reply)



`POST /api/v1/tickets/:ticketId/reply` — 🔑 **Bearer** · `204 200 OK` (success-only envelope)

Adds a user-authored message to the ticket. If the ticket was waiting for the user (`WAITING_USER`), it flips to `IN_PROGRESS` so the agent's queue picks it up. Otherwise the status doesn't change.



<Callout type="warn">
  **`isInternal` in the request body is ignored for users.** The DTO accepts the field, but the user-facing controller hard-codes `'USER'` as the `authorType` and the service path for users never reads `isInternal` — the message lands with `isInternal: false`. (The same DTO is reused by the admin agent-reply endpoint, which DOES respect it.) Don't ship `isInternal: true` in client code expecting it to do anything.
</Callout>

<Callout type="warn">
  **Foreign tickets respond `403`, not `404`.** Unlike the [detail endpoint](/docs/support/detail), the reply path runs the lookup first and then checks ownership separately — non-owners get `support.ticket.not_owner` (403). Combined with detail-endpoint behavior, **a malicious caller could in theory probe by attempting a reply to a guessed ticketId — but they'd still need to send valid auth and a 1-5000 char body**, so it's a noisy attack. Worth knowing for monitoring rules.
</Callout>

<Callout type="info">
  **Notification to the agent is fire-and-forget.** After the message is committed, the service sends a `ticket_update` notification to `ticket.assignedTo` (if set) &#x2A;*only when `isInternal === false`**. For user replies, `isInternal` is always `false`, so the notification always fires when an agent is assigned.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param      | Type          | Required | Validation      | Notes        |
| ---------- | ------------- | -------- | --------------- | ------------ |
| `ticketId` | string (UUID) | ✓        | `ParseUUIDPipe` | Your ticket. |

### Body — `ReplyTicketDto` [#body--replyticketdto]

| Field        | Type    | Required | Validation                       | Notes                                            |
| ------------ | ------- | -------- | -------------------------------- | ------------------------------------------------ |
| `content`    | string  | ✓        | `MinLength(1) + MaxLength(5000)` | Plain text. No HTML sanitization at this layer.  |
| `isInternal` | boolean | optional | `IsBoolean`                      | **Ignored on the user path** — see warn callout. |

### Headers [#headers]

| Header                                | Required | Notes                  |
| ------------------------------------- | -------- | ---------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | Global `JwtAuthGuard`. |
| `Content-Type: application/json`      | ✓        | Standard.              |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{ "success": true }
```

The controller hard-codes `@HttpCode(200)` so the framework's default `201` for `POST` is overridden. The body is the platform's success-only envelope — no payload, no message id returned. To see the message in context, fetch [`GET /tickets/:ticketId`](/docs/support/detail) again.

### Status transition [#status-transition]

The status change happens inside the same `$transaction` as the new message:

| Ticket was                                                                        | After your reply                  | Why                                                                  |
| --------------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------- |
| `WAITING_USER`                                                                    | `IN_PROGRESS`                     | User responded — back into the agent queue.                          |
| Anything else (`OPEN`, `ASSIGNED`, `IN_PROGRESS`, `WAITING_INTERNAL`, `RESOLVED`) | unchanged                         | Service doesn't pull the ticket out of these states on a user reply. |
| `CLOSED`                                                                          | n/a — request rejected with `400` | See errors.                                                          |

### Errors [#errors]

| HTTP  | Code / `i18nKey`           | Reason                                          |
| ----- | -------------------------- | ----------------------------------------------- |
| `400` | (`ParseUUIDPipe`)          | `:ticketId` is not a UUID.                      |
| `400` | (DTO validation)           | `content` length out of range, missing field.   |
| `400` | `support.ticket.closed`    | Ticket is in `CLOSED` status — reopen it first. |
| `401` | (guard)                    | Missing / invalid bearer token.                 |
| `403` | `support.ticket.not_owner` | The ticket exists but belongs to another user.  |
| `404` | `support.ticket.not_found` | Ticket does not exist.                          |

## Side effects [#side-effects]

1. Decode bearer; `ParseUUIDPipe` validates `:ticketId`.
2. `prisma.ticket.findUnique({ where: { id } })`. If missing → throw `404`.
3. If `status === 'CLOSED'` → throw `400 support.ticket.closed`.
4. Owner check: `if (ticket.userId !== userId) throw 403 support.ticket.not_owner`.
5. Compute `newStatus`: was `WAITING_USER` → `IN_PROGRESS`; otherwise unchanged.
6. **Atomic write** via `prisma.$transaction([...])`:
   * Create `TicketMessage` row: `{ id: randomUUID(), ticketId, authorId: userId, authorType: 'USER', content, isInternal: false }`.
   * Update `Ticket.status` to `newStatus` (no-op when unchanged).
7. **Fire-and-forget** notification to the assigned agent (when `ticket.assignedTo` is set): `notificationService.send({ eventKey: 'ticket_update', userId: ticket.assignedTo, variables: { ticketId } })` — failures logged only.
8. Return `{ success: true }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query (mutation)']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/reply \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{ "content": "Yes, the IBAN is the same as the one on file. Please retry." }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function replyToTicket(
      accessToken: string,
      ticketId: string,
      content: string,
    ): Promise<void> {
      const res = await fetch(
        `https://api.bio.re/api/v1/tickets/${ticketId}/reply`,
        {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${accessToken}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ content }),
        },
      );
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Reply failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query (mutation)">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useReplyToTicket(ticketId: string) {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (content: string) => {
          const res = await fetch(`/api/v1/tickets/${ticketId}/reply`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ content }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Reply failed'), {
              code: json?.error?.code,
            });
          }
        },
        onSuccess: () => {
          // Pull the new message + status from the server.
          qc.invalidateQueries({ queryKey: ['support', 'ticket', ticketId] });
          // Status may have flipped (WAITING_USER → IN_PROGRESS), so refresh the list too.
          qc.invalidateQueries({ queryKey: ['support', 'tickets'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/tickets/{ticketId}/reply', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source        | Path                                                      | Lines                                                                                  |
| ------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Controller    | `apps/api-core/src/modules/support/support.controller.ts` | `68–78` (`reply` — hard-codes `'USER'` authorType)                                     |
| DTO (request) | `apps/api-core/src/modules/support/dto/index.ts`          | `19–25` (`ReplyTicketDto`)                                                             |
| Service       | `apps/api-core/src/modules/support/support.service.ts`    | `76–100` (`replyToTicket` — close check, owner check, status transition, notification) |
| Prisma models | `packages/prisma/prisma/schema.prisma`                    | `Ticket` lines `1245–1266`, `TicketMessage` lines `1268–1279`                          |


# Get Active Theme (/docs/theme/active)



`GET /api/v1/themes/active?target=CLIENT` — 🌐 **Public**

Returns the **currently active client-web theme preset** — the one fan / creator bio pages render with right now. Includes the full theming surface (`layout` + `assets`) needed for live application — more fields than the [list endpoint](/docs/theme/list).



<Callout type="warn">
  **Always pass `?target=CLIENT` explicitly.** Omitting the query parameter does NOT default to client-web — pass it explicitly every time. The example URL above shows the canonical form.
</Callout>

<Callout type="info">
  **`preset: null` is a normal response.** When no theme is currently active for client-web (e.g. fresh install, admin temporarily disabled all presets), the response is `{ preset: null }` — NOT a 404. Frontend should fall back to a built-in default theme bundled at build time when this happens.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param    | Type   | Required | Notes                                                                           |
| -------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `target` | string | ✓        | Pass `CLIENT` literal (case-insensitive). Always send this — see callout above. |

No headers required.

## Response [#response]

### `200 OK` — `ApiResponseOf<ActiveThemeResponseDto>` [#200-ok--apiresponseofactivethemeresponsedto]

```json
{
  "success": true,
  "data": {
    "preset": {
      "id": "tp1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "Default Light",
      "slug": "default-light",
      "target": "CLIENT",
      "lightTokens": { "color": { "bg": "#FFFFFF", "fg": "#0F172A" } },
      "darkTokens": { "color": { "bg": "#0F172A", "fg": "#FFFFFF" } },
      "typography": { "fontFamily": "Inter, sans-serif" },
      "layout": { "maxWidth": "1280px" },
      "assets": { "logo": "https://cdn.bio.re/themes/default-light/logo.svg" },
      "publishedAt": "2026-04-29T20:00:00.000Z"
    }
  }
}
```

When no active client-web preset exists:

```json
{
  "success": true,
  "data": {
    "preset": null
  }
}
```

### `preset` fields [#preset-fields]

| Field                        | Type                      | Notes                                                                         |
| ---------------------------- | ------------------------- | ----------------------------------------------------------------------------- |
| `id`                         | string (UUID)             | `ThemePreset.id`                                                              |
| `name`                       | string                    | Display name                                                                  |
| `slug`                       | string                    | URL-friendly identifier                                                       |
| `target`                     | string                    | Always `"CLIENT"` here (echoes the query)                                     |
| `lightTokens` / `darkTokens` | object                    | JSON color/spacing/etc tokens                                                 |
| `typography`                 | object                    | JSON typography settings                                                      |
| `layout`                     | object                    | JSON layout settings (max-width, gutters, etc) — **NOT in the list endpoint** |
| `assets`                     | object                    | JSON asset references (logo URLs, etc) — **NOT in the list endpoint**         |
| `publishedAt`                | string (ISO 8601) \| null | When the preset was published                                                 |

### Stripped fields [#stripped-fields]

`status` (always PUBLISHED+isActive here, filter excludes others), `isActive` (always true here), `tokenSchema`, `description`, `thumbnail`, `createdBy`, `publishedBy`, `activatedBy`, `activatedAt`, `createdAt`, `updatedAt` — internal-only.

### Errors [#errors]

This endpoint has no documented error responses. `preset: null` is the "no active preset" path; there's no 404.

## Side effects [#side-effects]

1. `prisma.themePreset.findFirst({ where: { target: 'CLIENT', isActive: true } })` (Prisma returns the first match — there's expected to be at most one active preset).
2. **Missing** → return `{ preset: null }`.
3. **Found** → map to the 10-field sanitized projection (excludes internal metadata) and return `{ preset }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/themes/active?target=CLIENT'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type ActiveThemePreset = {
      id: string;
      name: string;
      slug: string;
      target: 'CLIENT';
      lightTokens: object;
      darkTokens: object;
      typography: object;
      layout: object;
      assets: object;
      publishedAt: string | null;
    };

    async function getActiveTheme(): Promise<ActiveThemePreset | null> {
      const url = new URL('https://api.bio.re/api/v1/themes/active');
      url.searchParams.set('target', 'CLIENT');
      const res = await fetch(url);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Active theme fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.preset;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const themeKeys = {
      active: () => ['themes', 'active'] as const,
    };

    export function useActiveTheme() {
      return useQuery({
        queryKey: themeKeys.active(),
        queryFn: async () => {
          const url = new URL('/api/v1/themes/active', window.location.origin);
          url.searchParams.set('target', 'CLIENT');
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Active theme fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.preset as ActiveThemePreset | null;
        },
        // Active theme rarely flips during a session
        staleTime: 5 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/themes/active', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                       | Lines                                                                    |
| -------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/theme-preset/theme-preset-public.controller.ts` | `40–64` (`getActive`)                                                    |
| DTO (response) | `apps/api-core/src/modules/theme-preset/dto/theme-preset-response.dto.ts`  | `164–167` (`ActiveThemeResponseDto`), `127–157` (`ActiveThemePresetDto`) |
| Service        | `apps/api-core/src/modules/theme-preset/theme-preset.service.ts`           | `139–143` (`findActive(target)`)                                         |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                                     | `ThemePreset` (filter `target = CLIENT` + `isActive = true`)             |


# List Theme Presets (/docs/theme/list)



`GET /api/v1/themes` — 🌐 **Public**

Returns the **published theme presets** for client-web theming — typically used to render a theme picker in the creator's bio editor. PUBLISHED-only filter; DRAFT / ARCHIVED never leak. Internal metadata (`status`, `isActive`, `tokenSchema`, `layout`, `assets`, `description`, `thumbnail`, `createdBy`, `publishedBy`, `activatedBy`, all timestamps) is stripped from the response.



<Callout type="info">
  **Sanitized list shape.** This endpoint returns ONLY `{ id, name, slug, lightTokens, darkTokens, typography }` per preset. To get the **active** preset for live application (which includes `layout` + `assets`), use [`GET /themes/active`](/docs/theme/active). The list is for picker UI only — render a thumbnail-style card from `name` + `slug` and let the user click to apply.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param    | Type   | Default  | Notes                                                                                                    |
| -------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- |
| `target` | string | `CLIENT` | Always omit — server defaults to `CLIENT` (the only target relevant to client-web / creator bio editor). |

No headers required.

## Response [#response]

### `200 OK` — `ApiResponseOf<PublicThemeListResponseDto>` [#200-ok--apiresponseofpublicthemelistresponsedto]

```json
{
  "success": true,
  "data": {
    "themes": [
      {
        "id": "tp1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "name": "Default Light",
        "slug": "default-light",
        "lightTokens": { "color": { "bg": "#FFFFFF", "fg": "#0F172A" } },
        "darkTokens": { "color": { "bg": "#0F172A", "fg": "#FFFFFF" } },
        "typography": { "fontFamily": "Inter, sans-serif" }
      }
    ]
  }
}
```

### Item fields [#item-fields]

| Field         | Type          | Notes                                    |
| ------------- | ------------- | ---------------------------------------- |
| `id`          | string (UUID) | `ThemePreset.id`                         |
| `name`        | string        | Display name                             |
| `slug`        | string        | URL-friendly identifier                  |
| `lightTokens` | object        | JSON design-token tree (light mode)      |
| `darkTokens`  | object        | JSON design-token tree (dark mode)       |
| `typography`  | object        | JSON typography settings (fonts, scales) |

### Stripped fields [#stripped-fields]

`status` (always PUBLISHED here, filter excludes), `isActive`, `tokenSchema`, `layout`, `assets`, `description`, `thumbnail`, `createdBy`, `publishedBy`, `activatedBy`, `publishedAt`, `activatedAt`, `createdAt`, `updatedAt` — all internal-only, excluded.

### Errors [#errors]

This endpoint has no documented error responses beyond infrastructure failures.

## Side effects [#side-effects]

1. `prisma.themePreset.findMany({ where: { target: 'CLIENT', status: 'PUBLISHED' }, orderBy: createdAt desc, take: 500 })`.
2. Map each row to the sanitized 6-field projection. &#x2A;*No mutations.**

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/themes
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type PublicThemePreset = {
      id: string;
      name: string;
      slug: string;
      lightTokens: object;
      darkTokens: object;
      typography: object;
    };

    async function listThemes(): Promise<PublicThemePreset[]> {
      const res = await fetch('https://api.bio.re/api/v1/themes');
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Themes fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.themes;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const themeKeys = {
      list: () => ['themes', 'list'] as const,
    };

    export function useThemeList() {
      return useQuery({
        queryKey: themeKeys.list(),
        queryFn: async () => {
          const res = await fetch('/api/v1/themes');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Themes fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.themes as PublicThemePreset[];
        },
        // Catalog rarely changes within a session
        staleTime: 5 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/themes', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                       | Lines                                                                       |
| -------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/theme-preset/theme-preset-public.controller.ts` | `21–38` (`listPublished`)                                                   |
| DTO (response) | `apps/api-core/src/modules/theme-preset/dto/theme-preset-response.dto.ts`  | `116–119` (`PublicThemeListResponseDto`), `91–109` (`PublicThemePresetDto`) |
| Service        | `apps/api-core/src/modules/theme-preset/theme-preset.service.ts`           | `119–129` (`findAll(target, status)`)                                       |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                                     | `ThemePreset` (filter `target = CLIENT` + `status = PUBLISHED`)             |


# Get Presigned Upload URL (/docs/upload/presign)



`POST /api/v1/upload/presign` — 🔑 **Bearer** · Rate limit: **30 req / minute**

Generates a **presigned PUT URL** for direct client-to-storage upload. The server validates the upload `type` (`avatar` / `media` / `document`) and `contentType` (MIME) against admin-managed allowlists, then issues a signed URL pre-bound to a max size and a 5-minute (default) expiry. **Client then uploads the file body directly to the signed URL** (skipping the platform server entirely for file bytes).



<Callout type="info">
  **Two-step flow.** Step 1: call this endpoint, get back `{ uploadUrl, publicUrl, key, expiresIn }`. Step 2: HTTP `PUT` your file body to `uploadUrl` with the same `Content-Type` header you sent in the body. After successful PUT, the file is reachable at `publicUrl`. Pass either `publicUrl` or `key` to downstream endpoints that accept user-uploaded files (e.g. `PATCH /users/avatar`).
</Callout>

<Callout type="warn">
  **The signed URL is pre-bound to the max size for your type.** The server signs the URL with `Content-Length` = max bytes (e.g. `5 * 1024 * 1024` for avatar). The storage backend rejects PUTs that violate this. **You don't need to enforce size client-side** — the storage provider does it — but surface a friendly error if the PUT fails with a 4xx body.
</Callout>

<Callout type="warn">
  **Vendor abstraction.** The active object storage provider is admin-managed; the client sees only the resulting `uploadUrl` (a signed PUT URL host-keyed to whichever provider is active). Don't parse the host/path of `uploadUrl` to infer the vendor — treat it as opaque.
</Callout>

## Upload type matrix [#upload-type-matrix]

| Type       | Default MIME allowlist                                            | Default max size | Storage path prefix               |
| ---------- | ----------------------------------------------------------------- | ---------------- | --------------------------------- |
| `avatar`   | `image/jpeg`, `image/png`, `image/webp`                           | 5 MB             | `avatars/<userId>/<uuid>.<ext>`   |
| `media`    | `image/jpeg`, `image/png`, `image/webp`, `image/gif`, `video/mp4` | 50 MB            | `media/<userId>/<uuid>.<ext>`     |
| `document` | `application/pdf`, `image/jpeg`, `image/png`                      | 10 MB            | `documents/<userId>/<uuid>.<ext>` |

**All three columns are admin-managed via `ConfigService`:**

* MIME allowlists: `upload.<type>_mimes` (JSON array)
* Size caps: `upload.max_<type>_size_mb` (number)
* URL expiry: `upload.presign_expiry_seconds` (number, default 300 = 5 min)

## Request [#request]

### Body — `PresignedUploadDto` [#body--presigneduploaddto]

| Field         | Type   | Required | Validation                            | Notes                                                                                                                                                                    |
| ------------- | ------ | -------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`        | enum   | ✓        | `IsIn(['avatar','media','document'])` | Determines folder, MIME allowlist, size cap                                                                                                                              |
| `contentType` | string | ✓        | `IsString()`                          | MIME type to send in the PUT request. Must be in the admin allowlist for the `type`.                                                                                     |
| `fileName`    | string | optional | `IsString()`                          | Original file name — **stored only for support / log reference**. The server-generated key uses a random UUID for the filename, so this doesn't affect the storage path. |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<PresignedUrlResponseDto>` [#200-ok--apiresponseofpresignedurlresponsedto]

```json
{
  "success": true,
  "data": {
    "uploadUrl": "https://<active-storage-host>/avatars/<userId>/<uuid>.png?X-Amz-Signature=...",
    "publicUrl": "https://cdn.bio.re/avatars/<userId>/<uuid>.png",
    "key": "avatars/<userId>/<uuid>.png",
    "expiresIn": 300
  }
}
```

| Field       | Type   | Notes                                                                                                                                                                          |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uploadUrl` | string | **Treat as opaque.** Send `PUT <uploadUrl>` with the file body and the same `Content-Type` header you put in the request. URL signature is host-locked to the active provider. |
| `publicUrl` | string | Where the file will be reachable AFTER the PUT succeeds. Save this on your domain row (e.g. `User.avatarUrl`).                                                                 |
| `key`       | string | Storage object key (path). Useful if your downstream endpoint takes a key instead of a URL.                                                                                    |
| `expiresIn` | number | Seconds until `uploadUrl` becomes invalid (admin-managed `upload.presign_expiry_seconds`, default `300`). Plan to PUT within this window.                                      |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                  | Reason                                                                                                                                                |
| ----- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `error.upload.not_configured`       | Active object storage provider isn't configured server-side — admin must set credentials                                                              |
| `400` | `error.upload.invalid_type`         | `type` not one of `avatar` / `media` / `document` (DTO catches this earlier; service guard is defense-in-depth)                                       |
| `400` | `error.upload.invalid_content_type` | `contentType` not in the admin allowlist for the supplied `type`. Payload includes `{ contentType, type }` so the UI can render the actual allowlist. |
| `400` | (DTO validation)                    | Missing fields; non-string                                                                                                                            |
| `401` | (guard)                             | Missing / invalid bearer token                                                                                                                        |
| `429` | (throttle)                          | Rate limit exceeded (30 req/min)                                                                                                                      |

## Side effects [#side-effects]

1. Resolve active storage client; if not configured → throw `not_configured`.
2. Lookup `folder` from `type` (`avatars` / `media` / `documents`); guard against unknown types.
3. Read MIME allowlist from `upload.<type>_mimes` (admin config); reject if `contentType` isn't in the list. Error payload includes `{ contentType, type }`.
4. Read `maxSizeMb` from `upload.max_<type>_size_mb` (admin config; defaults 5 / 50 / 10).
5. Read `presignExpiry` from `upload.presign_expiry_seconds` (admin config; default 300).
6. Generate `key = <folder>/<userId>/<randomUUID>.<ext>` (where `ext` is parsed from `contentType`).
7. Build `PutObjectCommand({ Bucket, Key: key, ContentType, ContentLength: maxSizeMb * 1024 * 1024, Metadata: { userId, type } })`.
8. `getSignedUrl(client, command, { expiresIn: presignExpiry })` — wrapped in `withRetry` for transient SDK failures.
9. Compute `publicUrl` from active CDN config or fall back to a provider-default host.
10. Return `{ uploadUrl, publicUrl, key, expiresIn: presignExpiry }`. **No DB writes** — the row that references this file is created by whichever downstream endpoint the client calls next (e.g. `PATCH /users/avatar`).

## Code samples [#code-samples]



<Tabs items="['curl (presign only)', 'Two-step (presign + PUT)', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl (presign only)">
    ```bash
    curl -X POST https://api.bio.re/api/v1/upload/presign \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "type": "avatar",
        "contentType": "image/png",
        "fileName": "profile-photo.png"
      }'
    ```
  </Tab>

  <Tab value="Two-step (presign + PUT)">
    ```bash
    # Step 1: get signed URL
    RESPONSE=$(curl -s -X POST https://api.bio.re/api/v1/upload/presign \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"type":"avatar","contentType":"image/png"}')

    UPLOAD_URL=$(echo "$RESPONSE" | jq -r '.data.uploadUrl')
    PUBLIC_URL=$(echo "$RESPONSE" | jq -r '.data.publicUrl')

    # Step 2: PUT the file body directly to the storage URL
    curl -X PUT "$UPLOAD_URL" \
      -H 'Content-Type: image/png' \
      --data-binary @./profile-photo.png

    # Step 3: tell the platform about the new file (e.g. set as avatar)
    curl -X PATCH https://api.bio.re/api/v1/users/avatar \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d "{\"avatarUrl\": \"$PUBLIC_URL\"}"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type UploadType = 'avatar' | 'media' | 'document';

    type PresignedUrl = {
      uploadUrl: string;
      publicUrl: string;
      key: string;
      expiresIn: number;
    };

    async function presignUpload(
      accessToken: string,
      type: UploadType,
      file: File,
    ): Promise<PresignedUrl> {
      const res = await fetch('https://api.bio.re/api/v1/upload/presign', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          type,
          contentType: file.type,
          fileName: file.name,
        }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Presign failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }

    // Two-step upload — usable as a single helper
    async function uploadFile(
      accessToken: string,
      type: UploadType,
      file: File,
    ): Promise<{ publicUrl: string; key: string }> {
      const { uploadUrl, publicUrl, key } = await presignUpload(accessToken, type, file);

      // Step 2: PUT directly to storage. Use the SAME contentType as in the body.
      const putRes = await fetch(uploadUrl, {
        method: 'PUT',
        headers: { 'Content-Type': file.type },
        body: file,
      });
      if (!putRes.ok) {
        throw new Error(`Upload failed: ${putRes.status}`);
      }

      return { publicUrl, key };
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useUploadFile() {
      return useMutation({
        mutationFn: async (vars: { type: UploadType; file: File }) => {
          // Step 1: get presigned URL
          const presignRes = await fetch('/api/v1/upload/presign', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
              type: vars.type,
              contentType: vars.file.type,
              fileName: vars.file.name,
            }),
          });
          const presignJson = await presignRes.json();
          if (!presignRes.ok || !presignJson.success) {
            throw Object.assign(new Error(presignJson?.error?.message ?? 'Presign failed'), {
              code: presignJson?.error?.code,
              i18nKey: presignJson?.error?.i18nKey,
            });
          }
          const { uploadUrl, publicUrl, key } = presignJson.data as PresignedUrl;

          // Step 2: PUT directly to storage
          const putRes = await fetch(uploadUrl, {
            method: 'PUT',
            headers: { 'Content-Type': vars.file.type },
            body: vars.file,
          });
          if (!putRes.ok) {
            throw new Error(`Upload failed: ${putRes.status}`);
          }

          return { publicUrl, key };
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/upload/presign', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source               | Path                                                          | Lines                                                                                                                            |
| -------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Controller           | `apps/api-core/src/modules/upload/upload.controller.ts`       | `56–92` (`getPresignedUrl`), `16–41` (`PresignedUploadDto` inline)                                                               |
| DTO (response)       | `apps/api-core/src/modules/upload/dto/upload-response.dto.ts` | `5–28` (`PresignedUrlResponseDto`)                                                                                               |
| Service              | `apps/api-core/src/modules/upload/upload.service.ts`          | `158–206` (`getPresignedUploadUrl`)                                                                                              |
| Storage client       | (admin-managed via `external.storage.active_provider`)        | `getActiveClient()`, `getActiveBucket()`, `getActivePublicUrl()`                                                                 |
| Config keys          | `apps/api-core/src/modules/config/config.service.ts`          | `upload.<type>_mimes` (allowlists), `upload.max_<type>_size_mb` (caps), `upload.presign_expiry_seconds` (URL TTL)                |
| Downstream consumers | various                                                       | `PATCH /users/avatar` (avatar URL), `PATCH /creators/:creatorId/bio` (avatarUrl), `POST /messages` (no attachments yet — future) |


# Get Platform Stats (/docs/platform/stats)



`GET /api/v1/platform/stats` — 🌐 **Public** · Rate limit: **60 req / minute**

Returns three aggregate counters across the entire platform plus a `cachedAt` timestamp. Used for marketing surfaces (trust badges, "X creators · Y messages" hero text, social proof footers). Cached on **two layers** — Redis (server-side, 1 hour) and `Cache-Control: public, s-maxage=3600` (CDN edge, 1 hour) — so you can hammer this endpoint freely from a static site or RSC layout without warming concerns.



<Callout type="info">
  **Two cache layers, both 1 hour.** The server caches the computed snapshot in Redis under key `platform:stats` for 3600s, AND emits `Cache-Control: public, s-maxage=3600` so the CDN holds the response for the same window. A change in creator/message counts can take **up to \~1 hour** to surface here — this is a marketing counter, not a real-time dashboard. If you need fresh numbers, render server-side and skip the CDN, but you'll still hit the Redis layer.
</Callout>

<Callout type="warn">
  **`totalMessagesSent` counts ALL messages, every status.** The query is a bare `prisma.message.count()` with no `status` filter — so PENDING, ESCROWED, DELIVERED, REPLIED, REFUNDED, EXPIRED rows are all included. This is intentional ("messages sent" = anything that entered the system) but be careful if you label this as "delivered" or "answered" in the UI.
</Callout>

<Callout type="warn">
  **`totalEarned` is a string, not a number.** It's a `Decimal(12, 2)` in Postgres serialized via `.toString()`. Parse with `Number(totalEarned)` or a decimal lib, and never display the raw string with currency formatting — it has no thousands separators or symbol.
</Callout>

## Request [#request]

No body, no params, no headers required. Bearer token is allowed but ignored.

## Response [#response]

### `200 OK` — `ApiResponseOf<PlatformStatsDto>` [#200-ok--apiresponseofplatformstatsdto]

```json
{
  "success": true,
  "data": {
    "totalCreators": 1250,
    "totalMessagesSent": 48320,
    "totalEarned": "125400.00",
    "cachedAt": "2026-04-29T12:00:00.000Z"
  }
}
```

### Fields [#fields]

| Field               | Type              | Notes                                                                                                                                                                                                |
| ------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `totalCreators`     | number            | Count of `CreatorProfile` rows where `user.status = ACTIVE` AND `deletedAt IS NULL`. Excludes suspended/deleted/inactive accounts.                                                                   |
| `totalMessagesSent` | number            | Count of ALL `Message` rows — every status, every type. No filter.                                                                                                                                   |
| `totalEarned`       | string            | Sum of `CreatorProfile.totalEarnings` for non-deleted creators, serialized as a `Decimal(12, 2)` string (e.g. `"125400.00"`). Currency: USD. Includes earnings whether or not they've been paid out. |
| `cachedAt`          | string (ISO 8601) | When this snapshot was computed and stored in Redis. Use it to render "Last updated X minutes ago" if you want.                                                                                      |

### Errors [#errors]

| HTTP  | Reason                                                                                              |
| ----- | --------------------------------------------------------------------------------------------------- |
| `429` | Rate limit exceeded (60 req/min — but you should rarely hit this since the response is CDN-cached). |

No documented error responses beyond infrastructure failures.

## Side effects [#side-effects]

1. Read Redis cache at key `platform:stats`. &#x2A;*If hit → return immediately.**
2. On miss, run **three parallel Prisma queries**:
   * `prisma.creatorProfile.count({ where: { user: { status: 'ACTIVE' }, deletedAt: null } })`
   * `prisma.message.count()`
   * `prisma.creatorProfile.aggregate({ _sum: { totalEarnings: true }, where: { deletedAt: null } })`
3. Build the snapshot — `totalEarnings` is coerced from `Decimal` to string (`?.toString() ?? '0'`); `cachedAt` is `new Date().toISOString()`.
4. `redis.cacheSet('platform:stats', snapshot, 3600)` — non-blocking write-back.
5. Return the snapshot wrapped manually as `{ success: true, data }` (the controller hand-rolls the envelope rather than relying on the response interceptor — same shape on the wire).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/platform/stats
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type PlatformStats = {
      totalCreators: number;
      totalMessagesSent: number;
      totalEarned: string; // Decimal(12,2) as string
      cachedAt: string;    // ISO 8601
    };

    async function getPlatformStats(): Promise<PlatformStats> {
      const res = await fetch('https://api.bio.re/api/v1/platform/stats');
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Stats fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }

    // Usage in a hero section:
    const stats = await getPlatformStats();
    const earnedUsd = Number(stats.totalEarned).toLocaleString('en-US', {
      style: 'currency',
      currency: 'USD',
      maximumFractionDigits: 0,
    });
    // → "$125,400"
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const platformKeys = {
      stats: () => ['platform', 'stats'] as const,
    };

    export function usePlatformStats() {
      return useQuery({
        queryKey: platformKeys.stats(),
        queryFn: async () => {
          const res = await fetch('/api/v1/platform/stats');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Stats fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as PlatformStats;
        },
        // CDN + Redis already cache for 1 hour — match the server-side TTL.
        staleTime: 60 * 60_000,
        gcTime: 2 * 60 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/platform/stats', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                              | Lines                                                                                                                                 |
| -------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/platform/platform.controller.ts`       | `13–25` (class), `17–24` (`getStats`)                                                                                                 |
| DTO (response) | `apps/api-core/src/modules/platform/dto/platform-response.dto.ts` | `5–26` (`PlatformStatsDto`)                                                                                                           |
| Service        | `apps/api-core/src/modules/platform/platform.service.ts`          | `27–41` (`getStats` — Redis read-through), `43–70` (`computeStats` — 3 parallel queries)                                              |
| Cache config   | `apps/api-core/src/modules/platform/platform.service.ts`          | `5–6` (`CACHE_KEY = 'platform:stats'`, `CACHE_TTL_SECONDS = 3600`)                                                                    |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                            | `CreatorProfile.totalEarnings` (line 331, `Decimal(12,2)`), `CreatorProfile.deletedAt`, `User.status`, `Message` (counted unfiltered) |


# Track Referral Click (/docs/referral/click)



`POST /api/v1/referral/click/:code` — 🌐 **Public** · Rate limit: **60 req / minute** · Kill-switched

Increments the `clicks` counter on the `ReferralLink` row matching `code`. Public — no auth required (clicks come from landing pages where the visitor isn't signed in yet). **Silent on missing/inactive codes**: if the code doesn't exist, the database update fails internally, the failure is logged at warn level, and the response is still `200 OK`.



<Callout type="info">
  **Always returns `tracked: true`.** Whether the code matched or not, the response shape is identical. This is intentional — landing pages call this from JavaScript and shouldn't block on tracking failures. The server logs the failure for observability.
</Callout>

<Callout type="warn">
  **Click counter is best-effort, not auditable.** The `clicks` increment is unguarded — no duplicate suppression, no IP tracking, no bot filtering. For the actual referral attribution chain, the platform records `signups` (in `recordSignup`) and `conversions` (in commission-paid flows) which are tied to authenticated user creation, not click events.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param  | Type   | Notes                                         |
| ------ | ------ | --------------------------------------------- |
| `code` | string | The referral code (no UUID pipe — raw string) |

No body, no headers required.

## Response [#response]

### `200 OK` — `ApiResponseOf<TrackClickResponseDto>` [#200-ok--apiresponseoftrackclickresponsedto]

```json
{
  "success": true,
  "data": {
    "tracked": true
  }
}
```

| Field     | Type    | Notes                                                                       |
| --------- | ------- | --------------------------------------------------------------------------- |
| `tracked` | boolean | Always `true` on 200 — even if the code doesn't exist (silent failure path) |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`           | Reason                                 |
| ----- | ---------------------------- | -------------------------------------- |
| `429` | (throttle)                   | Rate limit exceeded (60 req/min)       |
| `503` | `features.referral_disabled` | Admin kill switch `REFERRAL` is active |

The endpoint **does not return 4xx for missing codes** — see callout.

## Side effects [#side-effects]

1. `prisma.referralLink.update({ where: { code }, data: { clicks: { increment: 1 } } })`.
2. `.catch()`-d to a warn log on failure (e.g. unknown code, DB transient issue). &#x2A;*Failure does NOT propagate.**
3. Return `{ tracked: true }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'Landing page (HTML/JS)']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/referral/click/alice123
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function trackReferralClick(code: string): Promise<void> {
      // Fire-and-forget — landing page navigation should never block on this
      await fetch(`https://api.bio.re/api/v1/referral/click/${encodeURIComponent(code)}`, {
        method: 'POST',
      }).catch(() => { /* swallow — analytics is non-critical */ });
    }
    ```
  </Tab>

  <Tab value="Landing page (HTML/JS)">
    ```html
    <!-- /ref/[code]/page.tsx (Next.js) -->
    <script>
      // Extract code from URL: /ref/alice123 → 'alice123'
      const code = window.location.pathname.split('/').filter(Boolean).pop();
      if (code) {
        fetch(`/api/v1/referral/click/${code}`, { method: 'POST' }).catch(() => {});
      }
    </script>
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/referral/click/{code}', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                              | Lines                               |
| -------------- | ----------------------------------------------------------------- | ----------------------------------- |
| Controller     | `apps/api-core/src/modules/referral/referral.controller.ts`       | `49–56` (`trackClick`)              |
| DTO (response) | `apps/api-core/src/modules/referral/dto/referral-response.dto.ts` | `311–314` (`TrackClickResponseDto`) |
| Service        | `apps/api-core/src/modules/referral/referral.service.ts`          | `49–53` (`trackClick`)              |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                            | `ReferralLink.clicks` (counter)     |


# Apply Coupon (/docs/referral/coupon-apply)



`POST /api/v1/referral/coupon/apply` — 🔑 **Bearer** · Rate limit: **10 req / minute** · Kill-switched

Validates a coupon code against the active rules + the user's prior usage, calculates the discount with Decimal arithmetic (no float rounding), and records a `CouponUsage` row — all under a `SELECT ... FOR UPDATE` row lock so concurrent applications can't both pass the `maxUses` check.



<Callout type="info">
  **TOCTOU-safe.** The full validation chain (active flag, time window, applicability, min purchase, total uses, per-user uses) plus the `CouponUsage` insert run inside one transaction with the coupon row locked via `SELECT ... FOR UPDATE`. Two concurrent requests for the last available slot can't both succeed.
</Callout>

<Callout type="warn">
  **Discount is calculated, not stored as money.** The endpoint returns the discount **value** (a number) — the actual money side-effect happens in the calling flow (e.g. wallet load, message send) which deducts this amount from the transaction price. &#x2A;*The server records the usage; the caller is responsible for actually applying the discount to their domain transaction.**
</Callout>

## Request [#request]

### Body — `ApplyCouponDto` [#body--applycoupondto]

| Field               | Type   | Required | Validation             | Notes                                                                                                                          |
| ------------------- | ------ | -------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `code`              | string | ✓        | `IsString()`           | The coupon code to apply (case-sensitive — server does NOT uppercase before lookup)                                            |
| `transactionAmount` | number | ✓        | `IsNumber()`, `Min(1)` | The amount the coupon is being applied against, in dollars (NOT cents). Used for `minPurchase` check + percentage calculation. |
| `appliesTo`         | string | ✓        | `IsString()`           | What domain the coupon is being applied to (e.g. `message`). Server matches against `Coupon.appliesTo` (`'BOTH'` accepts any). |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<ApplyCouponResponseDto>` [#200-ok--apiresponseofapplycouponresponsedto]

```json
{
  "success": true,
  "data": {
    "discount": 2.50
  }
}
```

| Field      | Type   | Notes                                                                                                              |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `discount` | number | Calculated discount in dollars (already capped at `transactionAmount` — won't exceed the input). 2 decimal places. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`               | Payload   | Reason                                                               |
| ----- | -------------------------------- | --------- | -------------------------------------------------------------------- |
| `400` | `referral.coupon.invalid`        | —         | Code unknown OR `Coupon.active = false`                              |
| `400` | `referral.coupon.not_active`     | —         | `Coupon.startsAt` is in the future                                   |
| `400` | `referral.coupon.expired`        | —         | `Coupon.endsAt` is in the past                                       |
| `400` | `referral.coupon.not_applicable` | —         | `Coupon.appliesTo !== 'BOTH'` AND `!== submitted appliesTo`          |
| `400` | `referral.coupon.min_purchase`   | `{ min }` | `transactionAmount < Coupon.minPurchase`                             |
| `400` | `referral.coupon.usage_limit`    | —         | Total `CouponUsage` count `>= Coupon.maxUses`                        |
| `400` | `referral.coupon.already_used`   | —         | This user's `CouponUsage` count `>= Coupon.perUserLimit` (default 1) |
| `400` | (DTO validation)                 | —         | Missing fields / `transactionAmount < 1`                             |
| `401` | (guard)                          | —         | Missing / invalid bearer token                                       |
| `429` | (throttle)                       | —         | Rate limit exceeded (10 req/min)                                     |
| `503` | `features.referral_disabled`     | —         | Admin kill switch `REFERRAL` is active                               |

## Side effects [#side-effects]

**Inside one transaction (`timeout: 10s`):**

1. **Lock the coupon row** — `SELECT ... FOR UPDATE` on `Coupon` by `code`. Missing OR `active = false` → throw `invalid`.
2. **Time window** — reject if `startsAt > now` (`not_active`) OR `endsAt < now` (`expired`).
3. **Applicability** — reject if `coupon.appliesTo !== 'BOTH' && coupon.appliesTo !== submitted appliesTo`.
4. **Minimum purchase** — reject if `coupon.minPurchase` set AND `transactionAmount < minPurchase`. Error carries `{ min }` payload.
5. **Total usage cap** — `couponUsage.count({ where: { couponId } })`; if `>= maxUses`, throw `usage_limit`.
6. **Per-user cap** — `couponUsage.count({ where: { couponId, userId } })`; if `>= perUserLimit` (default 1), throw `already_used`.
7. **Discount calculation** (Prisma.Decimal arithmetic):
   * `FIXED` type → `discount = coupon.value`.
   * `PERCENTAGE` type → `discount = transactionAmount * (coupon.value / 100)`.
   * **Cap at transaction amount** — `discount = min(discount, transactionAmount)`.
   * Round to 2 decimal places.
8. **Record usage** — `couponUsage.create({ id, couponId, userId, amount: discount })`.

After the transaction commits, return `{ discount: discountDec.toNumber() }`. Audit log: `[coupon] Applied <code>: $<amount> off for user <userId>`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/referral/coupon/apply \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "code": "WELCOME20",
        "transactionAmount": 10,
        "appliesTo": "message"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type ApplyCouponInput = {
      code: string;
      transactionAmount: number;
      appliesTo: string;
    };

    type ApplyCouponResult = {
      discount: number;
    };

    async function applyCoupon(accessToken: string, input: ApplyCouponInput): Promise<ApplyCouponResult> {
      const res = await fetch('https://api.bio.re/api/v1/referral/coupon/apply', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Coupon apply failed'), {
          code: json?.error?.code,
          min: json?.error?.min, // present on 'min_purchase'
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useApplyCoupon() {
      return useMutation({
        mutationFn: async (input: ApplyCouponInput) => {
          const res = await fetch('/api/v1/referral/coupon/apply', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Coupon apply failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
              min: json?.error?.min,
            });
          }
          return json.data as ApplyCouponResult;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/referral/coupon/apply', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                              | Lines                                                                                                                                                                           |
| -------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/referral/referral.controller.ts`       | `66–77` (`applyCoupon`)                                                                                                                                                         |
| DTO (request)  | `apps/api-core/src/modules/referral/dto/index.ts`                 | `5–14` (`ApplyCouponDto`)                                                                                                                                                       |
| DTO (response) | `apps/api-core/src/modules/referral/dto/referral-response.dto.ts` | `382–385` (`ApplyCouponResponseDto`)                                                                                                                                            |
| Service        | `apps/api-core/src/modules/referral/referral.service.ts`          | `392–442` (`applyCoupon` — TOCTOU-safe transaction with row lock)                                                                                                               |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                            | `Coupon` (`code` unique, `type` enum FIXED/PERCENTAGE, `appliesTo`, `maxUses`, `perUserLimit`, `minPurchase`, time window), `CouponUsage` (records each use), `enum CouponType` |


# Get Referral Dashboard (/docs/referral/dashboard)



`GET /api/v1/referral/dashboard` — 🔑 **Bearer** · Rate limit: **30 req / minute** · Kill-switched

Returns the user's referral dashboard payload — `link` (the user's `ReferralLink` row with counters), `rewards` (last 50 active rewards, ordered newest-first; clawed-back rewards excluded), and `totalEarnings` (decimal as string from the link's running total).



<Callout type="info">
  **`link: null` is a valid response.** If the user never called `GET /referral/link`, no `ReferralLink` row exists yet, and the dashboard returns `{ link: null, rewards: [], totalEarnings: '0' }`. Clients should call `/referral/link` once to bootstrap the row, or branch on `link === null` and render an "activate referrals" CTA.
</Callout>

<Callout type="warn">
  **`rewards` excludes clawed-back items.** The filter is `clawedBack: false`. If admin has reversed a reward (commission clawback after a refund / chargeback / fraud), it disappears from this list. The `totalEarnings` snapshot on `link` is also adjusted by clawback flows.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<ReferralDashboardResponseDto>` [#200-ok--apiresponseofreferraldashboardresponsedto]

```json
{
  "success": true,
  "data": {
    "link": {
      "id": "rl1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "code": "alice123",
      "clicks": 142,
      "signups": 17,
      "conversions": 5,
      "totalEarnings": "25.00",
      "active": true
    },
    "rewards": [
      {
        "id": "rr1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "triggerType": "FIRST_PAYMENT",
        "amount": "5.00",
        "clawedBack": false,
        "createdAt": "2026-04-29T20:00:00.000Z"
      }
    ],
    "totalEarnings": "25.00"
  }
}
```

### Top-level fields [#top-level-fields]

| Field           | Type             | Notes                                                                                                                                                           |
| --------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `link`          | object \| null   | The user's `ReferralLink` row (see fields below). `null` until first `/referral/link` call.                                                                     |
| `rewards`       | array            | Last 50 active `ReferralReward` rows (`clawedBack: false`), ordered `createdAt DESC`                                                                            |
| `totalEarnings` | string (decimal) | Running total from `ReferralLink.totalEarnings`. &#x2A;*Same value as `link.totalEarnings`** when `link` is non-null — duplicated at top level for convenience. |

### `link` fields [#link-fields]

| Field           | Type             | Notes                                                                                         |
| --------------- | ---------------- | --------------------------------------------------------------------------------------------- |
| `id`            | string (UUID)    | `ReferralLink.id`                                                                             |
| `code`          | string           | The shareable referral code                                                                   |
| `clicks`        | number           | Lifetime click counter (incremented by `POST /referral/click/:code`)                          |
| `signups`       | number           | Lifetime new-user signups attributed to this code                                             |
| `conversions`   | number           | Lifetime conversion events (paid/recurring payment triggers)                                  |
| `totalEarnings` | string (decimal) | Running total of paid-out reward amounts (decimal as string)                                  |
| `active`        | boolean          | When `false`, the link is admin-disabled — clicks still tracked but no signups/rewards record |

### `rewards` item fields (`ReferralDashboardRewardItemDto`) [#rewards-item-fields-referraldashboardrewarditemdto]

| Field         | Type              | Notes                                                                            |
| ------------- | ----------------- | -------------------------------------------------------------------------------- |
| `id`          | string (UUID)     | `ReferralReward.id`                                                              |
| `triggerType` | enum              | `REGISTRATION` (tracking-only, amount=0) / `FIRST_PAYMENT` / `RECURRING_PAYMENT` |
| `amount`      | string (decimal)  | Reward amount (decimal as string). `'0'` for `REGISTRATION` rows.                |
| `clawedBack`  | boolean           | Always `false` here (filter excludes true)                                       |
| `createdAt`   | string (ISO 8601) | When the reward was recorded                                                     |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`           | Reason                                 |
| ----- | ---------------------------- | -------------------------------------- |
| `401` | (guard)                      | Missing / invalid bearer token         |
| `429` | (throttle)                   | Rate limit exceeded (30 req/min)       |
| `503` | `features.referral_disabled` | Admin kill switch `REFERRAL` is active |

## Side effects [#side-effects]

1. `prisma.referralLink.findUnique({ where: { userId } })`.
2. **Missing link** → return `{ link: null, rewards: [], totalEarnings: '0' }`. &#x2A;*No second query.**
3. `prisma.referralReward.findMany({ where: { referrerId: userId, clawedBack: false }, orderBy: createdAt desc, take: 50 })`.
4. Return `{ link, rewards, totalEarnings: String(link.totalEarnings) }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/referral/dashboard \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type ReferralDashboardLink = {
      id: string;
      code: string;
      clicks: number;
      signups: number;
      conversions: number;
      totalEarnings: string;
      active: boolean;
    };

    type ReferralDashboardRewardItem = {
      id: string;
      triggerType: 'REGISTRATION' | 'FIRST_PAYMENT' | 'RECURRING_PAYMENT';
      amount: string;
      clawedBack: boolean;
      createdAt: string;
    };

    type ReferralDashboard = {
      link: ReferralDashboardLink | null;
      rewards: ReferralDashboardRewardItem[];
      totalEarnings: string;
    };

    async function getReferralDashboard(accessToken: string): Promise<ReferralDashboard> {
      const res = await fetch('https://api.bio.re/api/v1/referral/dashboard', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Dashboard fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const referralKeys = {
      dashboard: () => ['referral', 'dashboard'] as const,
    };

    export function useReferralDashboard() {
      return useQuery({
        queryKey: referralKeys.dashboard(),
        queryFn: async () => {
          const res = await fetch('/api/v1/referral/dashboard');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Dashboard fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as ReferralDashboard;
        },
        staleTime: 30_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/referral/dashboard', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                              | Lines                                                                                                                                                                                                            |
| -------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/referral/referral.controller.ts`       | `58–64` (`getDashboard`)                                                                                                                                                                                         |
| DTO (response) | `apps/api-core/src/modules/referral/dto/referral-response.dto.ts` | `367–376` (`ReferralDashboardResponseDto`), `320–361` (nested `ReferralDashboardLinkDto` + `ReferralDashboardRewardItemDto`)                                                                                     |
| Service        | `apps/api-core/src/modules/referral/referral.service.ts`          | `356–365` (`getDashboard`)                                                                                                                                                                                       |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                            | `ReferralLink` (`clicks`, `signups`, `conversions`, `totalEarnings`, `active`), `ReferralReward` (filter `clawedBack: false`), `enum ReferralTriggerType` (`REGISTRATION`, `FIRST_PAYMENT`, `RECURRING_PAYMENT`) |


# Get Referral Link (/docs/referral/link)



`GET /api/v1/referral/link` — 🔑 **Bearer** · Kill-switched

Returns the calling user's personal referral link. **Get-or-create**: first read generates a `ReferralLink` row (code derived from `User.username`, falling back to an 8-char UUID slice on collision); every subsequent read returns the existing row.



<Callout type="info">
  **Cross-table uniqueness.** The `ReferralLink.code` must NOT collide with any `User.referralCode` (a separate column on the `User` table — also a referral identifier). The server retries up to 3 times with random UUID slices on collision; if all 3 retry, the request fails with `400 code_collision`.
</Callout>

<Callout type="warn">
  **Username drives the default code.** If the user's username is `alice123`, their referral link will be `bio.re/ref/alice123` — username and referral code are linked at first creation, but subsequent username changes do NOT update the existing code.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<ReferralLinkCodeResponseDto>` [#200-ok--apiresponseofreferrallinkcoderesponsedto]

```json
{
  "success": true,
  "data": {
    "code": "alice123",
    "link": "bio.re/ref/alice123"
  }
}
```

| Field  | Type   | Notes                                                                       |
| ------ | ------ | --------------------------------------------------------------------------- |
| `code` | string | The referral identifier — pass to `POST /referral/click/:code` for tracking |
| `link` | string | The full shareable URL — `bio.re/ref/<code>`                                |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`             | Reason                                                                                                                                         |
| ----- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `referral.link.code_collision` | Failed to generate a unique code after 3 retries (rare — would require username-vs-other-user collision plus 2 UUID slice collisions in a row) |
| `401` | (guard)                        | Missing / invalid bearer token                                                                                                                 |
| `503` | `features.referral_disabled`   | Admin kill switch `REFERRAL` is active                                                                                                         |

## Side effects [#side-effects]

1. `referralLink.findUnique({ where: { userId } })`. **Existing row** → return `{ code, link }` directly.
2. **No row** — load `User.username` for the candidate code; fallback to `randomUUID().slice(0, 8)` if null.
3. **Cross-table collision check** (up to 3 attempts):
   * `user.findUnique({ where: { referralCode: code } })` — if hit, regenerate with `randomUUID().slice(0, 8)`.
   * 3rd failure → throw `code_collision`.
4. `referralLink.create({ id, userId, code })`.
5. Return `{ code, link: 'bio.re/ref/<code>' }`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/referral/link \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type ReferralLink = {
      code: string;
      link: string;
    };

    async function getReferralLink(accessToken: string): Promise<ReferralLink> {
      const res = await fetch('https://api.bio.re/api/v1/referral/link', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Referral link fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const referralKeys = {
      link: () => ['referral', 'link'] as const,
    };

    export function useReferralLink() {
      return useQuery({
        queryKey: referralKeys.link(),
        queryFn: async () => {
          const res = await fetch('/api/v1/referral/link');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Referral link fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as ReferralLink;
        },
        staleTime: Infinity, // code never changes after first creation
        gcTime: 60 * 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/referral/link', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                              | Lines                                                                                               |
| -------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/referral/referral.controller.ts`       | `42–47` (`getLink`)                                                                                 |
| DTO (response) | `apps/api-core/src/modules/referral/dto/referral-response.dto.ts` | `298–304` (`ReferralLinkCodeResponseDto`)                                                           |
| Service        | `apps/api-core/src/modules/referral/referral.service.ts`          | `23–47` (`getOrCreateLink`)                                                                         |
| Kill switch    | `apps/api-core/src/common/guards/kill-switch.guard.ts`            | `RequireKillSwitch('REFERRAL')` (class-level)                                                       |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                            | `ReferralLink` (unique `userId`, unique `code`), `User.referralCode` (cross-table uniqueness check) |


# Regenerate Backup Codes (/docs/auth/2fa-backup-codes-regenerate)



`POST /api/v1/auth/2fa/backup-codes/regenerate` — 🔑 **Bearer** · Rate limit: **3 req / hour**

Issues a fresh batch of backup codes (`auth.backup_code_count`, default 10) and atomically deletes the previous batch. **Requires a valid TOTP code** — backup codes are explicitly rejected here, because the operation must prove the user still has access to the authenticator.



<Callout type="warn">
  The previous batch is deleted **before** the response is returned. Any unspent backup codes the user had on paper / in a vault are now dead. Show the new batch and prompt the user to replace stored copies.
</Callout>

<Callout type="info">
  Why TOTP-only (no backup-code path here)? If a stolen backup code could itself rotate the backup codes, an attacker with one code could lock the legitimate user out. Requiring a live TOTP keeps regeneration tied to authenticator possession.
</Callout>

## Request [#request]

### Body — `VerifyTotpDto` [#body--verifytotpdto]

| Field  | Type   | Required | Validation                       | Notes                                                                                  |
| ------ | ------ | -------- | -------------------------------- | -------------------------------------------------------------------------------------- |
| `code` | string | ✓        | exactly 6 chars (`Length(6, 6)`) | 6-digit TOTP code from the authenticator. &#x2A;*Backup codes are not accepted here.** |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<BackupCodesResponseDto>` [#200-ok--apiresponseofbackupcodesresponsedto]

```json
{
  "success": true,
  "data": {
    "backupCodes": [
      "ABCD-2345",
      "EFGH-6789",
      "JKLM-2345",
      "NPQR-6789",
      "STUV-2345",
      "WXYZ-6789",
      "23AB-CDEF",
      "45GH-JKLM",
      "67NP-QRST",
      "89UV-WXYZ"
    ]
  }
}
```

| Field         | Type       | Notes                                                                                                         |
| ------------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
| `backupCodes` | `string[]` | New one-time codes in `XXXX-XXXX` format. Count = `auth.backup_code_count`. Server stores bcrypt hashes only. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`      | Reason                                                    |
| ----- | ----------------------- | --------------------------------------------------------- |
| `400` | `auth.2fa.not_enabled`  | `User.twoFactorEnabled = false` — enable 2FA first        |
| `400` | `auth.2fa.invalid_code` | TOTP code doesn't match (within `auth.totp_window` drift) |
| `401` | (guard)                 | Missing / invalid bearer token                            |
| `429` | (throttle)              | Rate limit exceeded (3 req/hour)                          |

## Side effects [#side-effects]

1. Lookup `User`; assert `twoFactorEnabled = true` AND `twoFactorSecret IS NOT NULL`.
2. Decrypt `User.twoFactorSecret` and `otplib.verify()` the submitted code with `epochTolerance = auth.totp_window`.
3. Generate `auth.backup_code_count` new codes (`XXXX-XXXX`, no `0/O/1/I`); bcrypt-hash each (`auth.salt_rounds`).
4. **Inside one transaction**:
   * `DELETE FROM BackupCode WHERE userId = :userId` (drop the entire previous batch).
   * Insert the new batch.
5. Audit log: `[2fa] Backup codes regenerated for user {userId}`.
6. **Sessions are NOT revoked** here — the user keeps their session because the authenticator possession check just succeeded.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/2fa/backup-codes/regenerate \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"code": "123456"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type BackupCodes = { backupCodes: string[] };

    async function regenerateBackupCodes(accessToken: string, code: string): Promise<BackupCodes> {
      const res = await fetch('https://api.bio.re/api/v1/auth/2fa/backup-codes/regenerate', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ code }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Regenerate failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useRegenerateBackupCodes() {
      return useMutation({
        mutationFn: async (code: string) => {
          const res = await fetch('/api/v1/auth/2fa/backup-codes/regenerate', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ code }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Regenerate failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as BackupCodes;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/2fa/backup-codes/regenerate', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                      | Lines                                 |
| -------------- | --------------------------------------------------------- | ------------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/two-factor.controller.ts` | `76–86` (`regenerateBackupCodes`)     |
| DTO (request)  | `apps/api-core/src/modules/auth/dto/two-factor.dto.ts`    | `4–7` (`VerifyTotpDto`)               |
| DTO (response) | `apps/api-core/src/modules/auth/dto/response.dto.ts`      | `126–129` (`BackupCodesResponseDto`)  |
| Service        | `apps/api-core/src/modules/auth/two-factor.service.ts`    | `179–219` (`regenerateBackupCodes`)   |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                    | `BackupCode`, `User.twoFactorEnabled` |


# Disable 2FA (/docs/auth/2fa-disable)



`POST /api/v1/auth/2fa/disable` — 🔑 **Bearer** · Rate limit: **5 req / hour**

Disables 2FA on the current account. **Requires the current account password** as a re-confirmation step (in addition to the bearer token). On success: clears `User.twoFactorSecret`, deletes every `BackupCode`, and revokes every `Session` for the user.



<Callout type="warn">
  Sessions are revoked, including the one calling this endpoint. The user must re-login afterwards (no longer with 2FA). Plan a redirect to the login screen on success.
</Callout>

<Callout type="info">
  The password check exists because the bearer token alone shouldn't be enough to weaken account security. A stolen / leaked access token cannot disable 2FA without also knowing the password.
</Callout>

## Request [#request]

### Body — `DisableTwoFactorDto` [#body--disabletwofactordto]

| Field      | Type   | Required | Validation     | Notes                                                                         |
| ---------- | ------ | -------- | -------------- | ----------------------------------------------------------------------------- |
| `password` | string | ✓        | `MinLength(8)` | The current account password — checked against `User.passwordHash` via bcrypt |

| Header                                | Required | Notes                                                   |
| ------------------------------------- | -------- | ------------------------------------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` (which itself required 2FA) |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                |
| --------- | ------- | -------------------- |
| `success` | boolean | Always `true` on 200 |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`          | Reason                                                                                                                        |
| ----- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `400` | `auth.2fa.no_password`      | `User.passwordHash` is null (account was created via OAuth-only — set a password first via `POST /auth/change-password` flow) |
| `400` | `auth.2fa.invalid_password` | Password mismatch                                                                                                             |
| `401` | (guard)                     | Missing / invalid bearer token                                                                                                |
| `429` | (throttle)                  | Rate limit exceeded (5 req/hour)                                                                                              |

## Side effects [#side-effects]

1. Lookup `User.passwordHash`; if null → throw `no_password`.
2. `bcrypt.compare(submittedPassword, passwordHash)`; if false → throw `invalid_password`.
3. **Inside one transaction**:
   * `User.twoFactorEnabled = false`, `User.twoFactorSecret = null`.
   * `DELETE FROM BackupCode WHERE userId = :userId` (all of them).
   * `UPDATE Session SET revoked = true, revokedAt = now() WHERE userId = :userId AND revoked = false`.
4. Audit log: `[2fa] Disabled for user {userId}`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/2fa/disable \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"password": "current-account-password"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function disableTwoFactor(accessToken: string, password: string): Promise<void> {
      const res = await fetch('https://api.bio.re/api/v1/auth/2fa/disable', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ password }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? '2FA disable failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useDisableTwoFactor() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (password: string) => {
          const res = await fetch('/api/v1/auth/2fa/disable', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ password }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? '2FA disable failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          // Sessions revoked server-side — drop cached identity, force re-login
          qc.invalidateQueries({ queryKey: ['auth', 'me'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/2fa/disable', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                      | Lines                                                                            |
| -------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/two-factor.controller.ts` | `64–74` (`disable`)                                                              |
| DTO (request)  | `apps/api-core/src/modules/auth/dto/two-factor.dto.ts`    | `17–22` (`DisableTwoFactorDto`)                                                  |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts`     | `SuccessOnlyResponseDto`                                                         |
| Service        | `apps/api-core/src/modules/auth/two-factor.service.ts`    | `130–161` (`disable`)                                                            |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                    | `User.twoFactorEnabled`, `User.twoFactorSecret`, `BackupCode`, `Session.revoked` |


# Init 2FA Setup (Stable Shape) (/docs/auth/2fa-setup-init)



`POST /api/v1/auth/2fa/setup-init` — 🔑 **Bearer** · Rate limit: **10 req / hour**

**Alias** of `POST /auth/2fa/setup` with one cosmetic difference: the response shape includes `recoveryCodes: null` so the frontend can use a single response type across setup → verify without conditional fields.



<Callout type="info">
  Behavior is identical to `POST /auth/2fa/setup` — same secret generation, same encrypted persistence, same `already_enabled` guard. The only difference is the explicit `recoveryCodes: null` field. Recovery codes are still issued by `POST /auth/2fa/verify`, never here.
</Callout>

## Why two endpoints [#why-two-endpoints]

The original `/setup` returns `{ secret, qrCodeDataUrl, otpauthUrl }`. After `/verify` succeeds, the response is `{ backupCodes: [...] }`. The shapes don't overlap. `/setup-init` returns `{ secret, qrCodeUrl, otpauthUrl, recoveryCodes: null }` so a single TS type covers both stages — `recoveryCodes` flips from `null` (setup-init) to `string[]` (verify), nothing else changes.

Use `/setup` if you want the canonical endpoint. Use `/setup-init` if you need the stable response shape across the two-step flow.

## Request [#request]

No body. The current user is resolved from the bearer token.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<TwoFactorSetupInitResponseDto>` [#200-ok--apiresponseoftwofactorsetupinitresponsedto]

```json
{
  "success": true,
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qrCodeUrl": "data:image/png;base64,iVBORw0KGgo...",
    "otpauthUrl": "otpauth://totp/BIO.RE:creator@bio.re?secret=JBSWY3DPEHPK3PXP&issuer=BIO.RE",
    "recoveryCodes": null
  }
}
```

| Field           | Type            | Notes                                                                                                                                                         |
| --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `secret`        | string (base32) | TOTP secret for manual entry                                                                                                                                  |
| `qrCodeUrl`     | string          | `data:image/png;base64,…` — note the field name is `qrCodeUrl`, not `qrCodeDataUrl` (the only naming drift from `/setup`)                                     |
| `otpauthUrl`    | string          | `otpauth://totp/...` deep-link                                                                                                                                |
| `recoveryCodes` | `null`          | **Always `null` here.** Recovery codes are issued by `POST /auth/2fa/verify` after the user proves TOTP works. Forward-compat field so the type stays stable. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`         | Reason                                    |
| ----- | -------------------------- | ----------------------------------------- |
| `400` | `auth.2fa.already_enabled` | `User.twoFactorEnabled` is already `true` |
| `401` | (guard)                    | Missing / invalid bearer token            |
| `404` | `auth.2fa.user_not_found`  | Token decoded but user row missing        |
| `429` | (throttle)                 | Rate limit exceeded (10 req/hour)         |

## Side effects [#side-effects]

Identical to `POST /auth/2fa/setup`:

1. Lookup `User`; assert `twoFactorEnabled = false`.
2. Generate fresh TOTP secret (`otplib.generateSecret()`).
3. Build `otpauth://` URL + render QR PNG data URL.
4. AES-256-GCM-encrypt the secret and persist to `User.twoFactorSecret`.
5. **No backup code generation** — that's deferred to `/verify`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/2fa/setup-init \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type TwoFactorSetupInit = {
      secret: string;
      qrCodeUrl: string;
      otpauthUrl: string;
      recoveryCodes: string[] | null; // null on setup-init, string[] after verify
    };

    async function initTwoFactorSetup(accessToken: string): Promise<TwoFactorSetupInit> {
      const res = await fetch('https://api.bio.re/api/v1/auth/2fa/setup-init', {
        method: 'POST',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? '2FA setup-init failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useInitTwoFactorSetup() {
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/auth/2fa/setup-init', { method: 'POST' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? '2FA setup-init failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as TwoFactorSetupInit;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/2fa/setup-init', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                         | Lines                                           |
| -------------- | ------------------------------------------------------------ | ----------------------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/two-factor.controller.ts`    | `30–50` (`setupInit`)                           |
| DTO (response) | `apps/api-core/src/modules/auth/dto/two-factor-setup.dto.ts` | `15–34` (`TwoFactorSetupInitResponseDto`)       |
| Service        | `apps/api-core/src/modules/auth/two-factor.service.ts`       | `31–50` (`generateSetup`, shared)               |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                       | `User.twoFactorSecret`, `User.twoFactorEnabled` |


# Generate 2FA Setup (/docs/auth/2fa-setup)



`POST /api/v1/auth/2fa/setup` — 🔑 **Bearer** · Rate limit: **10 req / hour**

Generates a TOTP secret server-side, AES-256-GCM-encrypts it onto `User.twoFactorSecret`, and returns the secret + QR code data URL + `otpauth://` URL. **Does not yet activate 2FA** — the user must prove they can read TOTP from their authenticator via `POST /auth/2fa/verify` before backup codes are issued and 2FA is flipped on.



<Callout type="warn">
  The `secret` is also rendered into the QR code. Show it once and recommend the user store it via the authenticator. Don't log it. Don't echo it back over an unrelated channel.
</Callout>

<Callout type="info">
  Backup codes are **not** returned here — they are issued by `POST /auth/2fa/verify` after the user proves their TOTP works. This avoids a window where the user has backup codes for a 2FA setup they never completed.
</Callout>

## Request [#request]

No body. The current user is resolved from the bearer token.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `201 Created` — `ApiResponseOf<TwoFactorSetupResponseDto>` [#201-created--apiresponseoftwofactorsetupresponsedto]

```json
{
  "success": true,
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qrCodeDataUrl": "data:image/png;base64,iVBORw0KGgo...",
    "otpauthUrl": "otpauth://totp/BIO.RE:creator@bio.re?secret=JBSWY3DPEHPK3PXP&issuer=BIO.RE"
  }
}
```

| Field           | Type            | Notes                                                                       |
| --------------- | --------------- | --------------------------------------------------------------------------- |
| `secret`        | string (base32) | TOTP secret for manual entry into the authenticator                         |
| `qrCodeDataUrl` | string          | `data:image/png;base64,…` — render directly in `<img src=...>`              |
| `otpauthUrl`    | string          | `otpauth://totp/...` — useful for native deep-links into authenticator apps |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`         | Reason                                                                                 |
| ----- | -------------------------- | -------------------------------------------------------------------------------------- |
| `400` | `auth.2fa.already_enabled` | `User.twoFactorEnabled` is already `true` — disable first via `POST /auth/2fa/disable` |
| `401` | (guard)                    | Missing / invalid bearer token                                                         |
| `404` | `auth.2fa.user_not_found`  | Token decoded but user row missing (deleted account)                                   |
| `429` | (throttle)                 | Rate limit exceeded (10 req/hour)                                                      |

## Side effects [#side-effects]

1. Lookup `User` by id; assert `twoFactorEnabled = false` (else throw `already_enabled`).
2. Generate a fresh TOTP secret via `otplib.generateSecret()` (Google Authenticator / Authy compatible).
3. Build `otpauth://` URL with `BIO.RE` issuer + user email as label.
4. Render QR code as PNG data URL via `qrcode.toDataURL()`.
5. **Encrypt the secret with AES-256-GCM** (`encryptPii`) and persist to `User.twoFactorSecret`. Until `/verify`, this secret exists but `twoFactorEnabled = false` — login is unaffected.
6. Calling this endpoint twice replaces the secret — only the most recent `/setup` matches the `/verify` step.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/2fa/setup \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type TwoFactorSetup = {
      secret: string;
      qrCodeDataUrl: string;
      otpauthUrl: string;
    };

    async function startTwoFactorSetup(accessToken: string): Promise<TwoFactorSetup> {
      const res = await fetch('https://api.bio.re/api/v1/auth/2fa/setup', {
        method: 'POST',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? '2FA setup failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useStartTwoFactorSetup() {
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/auth/2fa/setup', { method: 'POST' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? '2FA setup failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as TwoFactorSetup;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/2fa/setup', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                      | Lines                                           |
| -------------- | --------------------------------------------------------- | ----------------------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/two-factor.controller.ts` | `20–28` (`generateSetup`)                       |
| DTO (response) | `apps/api-core/src/modules/auth/dto/response.dto.ts`      | `114–123` (`TwoFactorSetupResponseDto`)         |
| Service        | `apps/api-core/src/modules/auth/two-factor.service.ts`    | `31–50` (`generateSetup`)                       |
| PII encryption | `apps/api-core/src/common/pii-encryption.ts`              | `encryptPii()` (AES-256-GCM)                    |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                    | `User.twoFactorSecret`, `User.twoFactorEnabled` |


# Get 2FA Status (/docs/auth/2fa-status)



`GET /api/v1/auth/2fa/status` — 🔑 **Bearer** · No throttle

Returns the current `User.twoFactorEnabled` value. No mutations — purely a read.



<Callout type="info">
  The same flag is also returned by `GET /auth/me` as `twoFactorEnabled`. Use this dedicated endpoint when you only need that single bit and want to keep the `me` cache untouched (e.g., to drive a "Two-Factor Authentication" toggle on a settings screen).
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<TwoFactorStatusResponseDto>` [#200-ok--apiresponseoftwofactorstatusresponsedto]

```json
{
  "success": true,
  "data": {
    "enabled": true
  }
}
```

| Field     | Type    | Notes                           |
| --------- | ------- | ------------------------------- |
| `enabled` | boolean | Mirrors `User.twoFactorEnabled` |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                         |
| ----- | ------------------ | ------------------------------ |
| `401` | (guard)            | Missing / invalid bearer token |

## Side effects [#side-effects]

1. Lookup `User.twoFactorEnabled` (single field select).
2. Return `{ enabled }`. No mutations.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/auth/2fa/status \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function getTwoFactorStatus(accessToken: string): Promise<boolean> {
      const res = await fetch('https://api.bio.re/api/v1/auth/2fa/status', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Status check failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.enabled;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const twoFactorKeys = {
      status: () => ['auth', '2fa', 'status'] as const,
    };

    export function useTwoFactorStatus() {
      return useQuery({
        queryKey: twoFactorKeys.status(),
        queryFn: async () => {
          const res = await fetch('/api/v1/auth/2fa/status');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Status check failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.enabled as boolean;
        },
        staleTime: 60_000, // 1 min — flips rarely outside of explicit setup/disable
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/2fa/status', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                      | Lines                                    |
| -------------- | --------------------------------------------------------- | ---------------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/two-factor.controller.ts` | `88–95` (`isEnabled`)                    |
| DTO (response) | `apps/api-core/src/modules/auth/dto/response.dto.ts`      | `132–135` (`TwoFactorStatusResponseDto`) |
| Service        | `apps/api-core/src/modules/auth/two-factor.service.ts`    | `166–172` (`isEnabled`)                  |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                    | `User.twoFactorEnabled`                  |


# Verify TOTP & Activate 2FA (/docs/auth/2fa-verify)



`POST /api/v1/auth/2fa/verify` — 🔑 **Bearer** · Rate limit: **5 req / hour**

Verifies the 6-digit code against the secret stored by `POST /auth/2fa/setup` (or `/setup-init`). On success: flips `User.twoFactorEnabled = true`, generates `auth.backup_code_count` one-time backup codes, and **revokes all existing sessions** for the user (a re-login is required, this time with 2FA).



<Callout type="warn">
  **Backup codes are returned ONCE.** Display them and prompt the user to download / print / save to a password manager. The server only stores bcrypt hashes — there is no way to fetch them again. To rotate, call `POST /auth/2fa/backup-codes/regenerate`.
</Callout>

<Callout type="info">
  All sessions for this user are revoked on success — including the one calling this endpoint. The next request with the old access token will succeed only until the JWT expires (`auth.access_token_ttl_seconds`); the refresh cookie is dead immediately. Plan to redirect to a 2FA-enabled login flow right after handling the response.
</Callout>

## Request [#request]

### Body — `VerifyTotpDto` [#body--verifytotpdto]

| Field  | Type   | Required | Validation                       | Notes                                    |
| ------ | ------ | -------- | -------------------------------- | ---------------------------------------- |
| `code` | string | ✓        | exactly 6 chars (`Length(6, 6)`) | 6-digit TOTP code from the authenticator |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<BackupCodesResponseDto>` [#200-ok--apiresponseofbackupcodesresponsedto]

```json
{
  "success": true,
  "data": {
    "backupCodes": [
      "ABCD-2345",
      "EFGH-6789",
      "JKLM-2345",
      "NPQR-6789",
      "STUV-2345",
      "WXYZ-6789",
      "23AB-CDEF",
      "45GH-JKLM",
      "67NP-QRST",
      "89UV-WXYZ"
    ]
  }
}
```

| Field         | Type       | Notes                                                                                                                                                                                                                            |
| ------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `backupCodes` | `string[]` | One-time codes in `XXXX-XXXX` format (alphabet skips `0/O/1/I` to avoid confusion). Count = `auth.backup_code_count` (admin-managed config; default 10). Server stores bcrypt hashes only — these strings are never recoverable. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`             | Reason                                                              |
| ----- | ------------------------------ | ------------------------------------------------------------------- |
| `400` | `auth.2fa.setup_not_initiated` | No `User.twoFactorSecret` — call `/setup` first                     |
| `400` | `auth.2fa.already_enabled`     | `User.twoFactorEnabled` is already `true`                           |
| `400` | `auth.2fa.invalid_code`        | TOTP code doesn't match (within `auth.totp_window` drift tolerance) |
| `401` | (guard)                        | Missing / invalid bearer token                                      |
| `429` | (throttle)                     | Rate limit exceeded (5 req/hour)                                    |

## Side effects [#side-effects]

1. Lookup `User`; assert `twoFactorSecret IS NOT NULL` AND `twoFactorEnabled = false`.
2. Decrypt `User.twoFactorSecret` (`decryptPii` — AES-256-GCM; handles legacy plaintext too).
3. `otplib.verify()` against decrypted secret with `epochTolerance = auth.totp_window` (default 1 step = ±30s).
4. On success, **inside one transaction**:
   * Generate `auth.backup_code_count` codes (`XXXX-XXXX` format, no `0/O/1/I`).
   * Bcrypt-hash each code (`auth.salt_rounds`) and insert into `BackupCode` table.
   * Set `User.twoFactorEnabled = true`.
   * Update all `Session` rows for this user → `revoked = true`, `revokedAt = now()`.
5. Audit log: `[2fa] Activated for user {userId}`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/2fa/verify \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"code": "123456"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type BackupCodes = { backupCodes: string[] };

    async function verifyTwoFactor(accessToken: string, code: string): Promise<BackupCodes> {
      const res = await fetch('https://api.bio.re/api/v1/auth/2fa/verify', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ code }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? '2FA verify failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useVerifyTwoFactor() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (code: string) => {
          const res = await fetch('/api/v1/auth/2fa/verify', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ code }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? '2FA verify failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as BackupCodes;
        },
        onSuccess: () => {
          // Sessions revoked server-side — invalidate identity + force re-auth flow
          qc.invalidateQueries({ queryKey: ['auth', 'me'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/2fa/verify', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                      | Lines                                                    |
| -------------- | --------------------------------------------------------- | -------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/two-factor.controller.ts` | `52–62` (`verifyAndActivate`)                            |
| DTO (request)  | `apps/api-core/src/modules/auth/dto/two-factor.dto.ts`    | `4–7` (`VerifyTotpDto`)                                  |
| DTO (response) | `apps/api-core/src/modules/auth/dto/response.dto.ts`      | `126–129` (`BackupCodesResponseDto`)                     |
| Service        | `apps/api-core/src/modules/auth/two-factor.service.ts`    | `55–101` (`verifyAndActivate`)                           |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                    | `User.twoFactorEnabled`, `BackupCode`, `Session.revoked` |


# Get Challenge Metadata (/docs/auth/challenge)



`GET /api/v1/auth/challenge/{id}` — 🌐 **Public** · Rate limit: **60 req / hour**

Returns the metadata for an active `Challenge` so the UI can render appropriate state: masked phone (last 4 digits), expiry, attempts remaining, and the next resend availability time. **Does NOT return the code** — the code only travels via SMS.



<Callout type="info">
  This endpoint is **public** because Challenge ownership is implicit in the unguessable UUIDv4 `id`. The `id` itself acts as a capability token — if the client lost it (e.g., after a page refresh), they cannot re-acquire it without going through `/send-otp` again.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param | Type          | Validation      | Notes                                               |
| ----- | ------------- | --------------- | --------------------------------------------------- |
| `id`  | string (UUID) | `ParseUUIDPipe` | The `challengeId` returned by `POST /auth/send-otp` |

No body, no query.

## Response [#response]

### `200 OK` — `ApiResponseOf<ChallengeMetadataResponseDto>` [#200-ok--apiresponseofchallengemetadataresponsedto]

```json
{
  "success": true,
  "data": {
    "challengeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "purpose": "verify-phone-fan",
    "phoneMask": "+90 ••• ••• ••12",
    "expiresAt": "2026-04-29T20:15:00.000Z",
    "attemptsRemaining": 4,
    "resendAvailableAt": "2026-04-29T20:01:30.000Z"
  }
}
```

| Field               | Type                      | Notes                                                                           |
| ------------------- | ------------------------- | ------------------------------------------------------------------------------- |
| `challengeId`       | string (UUID)             | Echoed back                                                                     |
| `purpose`           | `OtpPurpose`              | One of: `verify-phone-fan` / `verify-phone-profile` / `2fa-setup` / `login-2fa` |
| `phoneMask`         | string \| null            | Masked — last 4 digits visible (e.g., `+90 ••• ••• ••12`)                       |
| `expiresAt`         | string (ISO 8601)         | Challenge expiry                                                                |
| `attemptsRemaining` | number                    | `auth.otp_max_attempts − Challenge.attempts`                                    |
| `resendAvailableAt` | string (ISO 8601) \| null | Earliest time another `/resend-otp` will succeed (cooldown gate)                |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`         | Reason                                     |
| ----- | -------------------------- | ------------------------------------------ |
| `404` | `auth.challenge.not_found` | Challenge ID does not exist OR has expired |
| `429` | (throttle)                 | Rate limit exceeded (60 req/hour)          |

## Side effects [#side-effects]

1. Lookup `Challenge` by `id`.
2. Mask phone for display (`maskPhone()` helper — last 4 digits visible).
3. Compute `resendAvailableAt` based on last dispatch + `auth.otp_resend_cooldown_seconds`.
4. No mutations — pure read.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/auth/challenge/a1b2c3d4-e5f6-7890-abcd-ef1234567890
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type ChallengeMetadata = {
      challengeId: string;
      purpose: 'verify-phone-fan' | 'verify-phone-profile' | '2fa-setup' | 'login-2fa';
      phoneMask: string | null;
      expiresAt: string;
      attemptsRemaining: number;
      resendAvailableAt: string | null;
    };

    async function getChallenge(challengeId: string): Promise<ChallengeMetadata> {
      const res = await fetch(`https://api.bio.re/api/v1/auth/challenge/${challengeId}`);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const challengeKeys = {
      detail: (id: string) => ['auth', 'challenge', id] as const,
    };

    export function useChallenge(challengeId: string) {
      return useQuery({
        queryKey: challengeKeys.detail(challengeId),
        queryFn: async () => {
          const res = await fetch(`/api/v1/auth/challenge/${challengeId}`);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Failed'), {
              code: json?.error?.code,
            });
          }
          return json.data as ChallengeMetadata;
        },
        refetchInterval: 1000, // Tick the countdown UI every second
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/challenge/{id}', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                  | Lines                                    |
| -------------- | ----------------------------------------------------- | ---------------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/auth.controller.ts`   | `383–401` (`getChallenge`)               |
| DTO (response) | `apps/api-core/src/modules/auth/dto/challenge.dto.ts` | `27–44` (`ChallengeMetadataResponseDto`) |
| Service        | `apps/api-core/src/modules/auth/challenge.service.ts` | `getChallenge()`                         |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                | `Challenge`                              |


# Change Password (/docs/auth/change-password)



`POST /api/v1/auth/change-password` — 🔑 **User-auth** (Bearer JWT) · Rate limit: **3 req / hour**

Authenticated password change. Verifies the current password before applying the new one. All existing sessions are revoked on success — user is logged out everywhere except the device that performed the change.



<Callout type="warn">
  This endpoint requires a valid JWT (`Authorization: Bearer <accessToken>`). It overrides the controller-level `@Public()` decorator via `@SetMetadata(IS_PUBLIC_KEY, false)`.
</Callout>

## Request [#request]

### Headers [#headers]

| Header          | Value                  | Notes                             |
| --------------- | ---------------------- | --------------------------------- |
| `Authorization` | `Bearer <accessToken>` | Required — JWT from `/auth/login` |
| `Content-Type`  | `application/json`     | Required                          |

### Body — `ChangePasswordDto` [#body--changepassworddto]

| Field             | Type   | Required | Validation                                      | Notes                                       |
| ----------------- | ------ | -------- | ----------------------------------------------- | ------------------------------------------- |
| `currentPassword` | string | ✓        | min 1 char                                      | bcrypt-compared against `User.passwordHash` |
| `newPassword`     | string | ✓        | 8–128 chars; must include upper + lower + digit | Must differ from current; bcrypt hashed     |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{ "success": true }
```

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                     | Reason                                               |
| ----- | -------------------------------------- | ---------------------------------------------------- |
| `400` | (DTO validation)                       | New password fails policy (length, character class)  |
| `400` | `auth.change_password.same_as_current` | New password matches current password                |
| `401` | `auth.change_password.invalid_current` | `currentPassword` does not match `User.passwordHash` |
| `401` | (no JWT or invalid)                    | Not authenticated                                    |
| `429` | (throttle)                             | Rate limit exceeded (3 req/hour)                     |

## Side effects [#side-effects]

1. Verify `currentPassword` against `User.passwordHash` (bcrypt compare).
2. Confirm new password is different from current (bcrypt compare again).
3. Hash new password (bcrypt).
4. Atomic transaction: update `User.passwordHash`, **revoke ALL `Session` records EXCEPT the current one** (the device performing the change stays logged in).
5. Send security alert email: "Your password was changed on `{date}` from `{device}`".
6. Audit log: `auth.change_password.success`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/change-password \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer <accessToken>' \
      -d '{
        "currentPassword": "OldP@ss123",
        "newPassword": "NewSecureP@ss456"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function changePassword(currentPassword: string, newPassword: string, accessToken: string): Promise<void> {
      const res = await fetch('https://api.bio.re/api/v1/auth/change-password', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${accessToken}`,
        },
        body: JSON.stringify({ currentPassword, newPassword }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Change failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useChangePassword() {
      return useMutation({
        mutationFn: async (input: { currentPassword: string; newPassword: string }) => {
          const res = await fetch('/api/v1/auth/change-password', {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json',
              'Authorization': `Bearer ${getAccessToken()}`,
            },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Change failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          toast.success(t('auth.change_password.success'));
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/change-password', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source        | Path                                                | Lines                           |
| ------------- | --------------------------------------------------- | ------------------------------- |
| Controller    | `apps/api-core/src/modules/auth/auth.controller.ts` | `225–243`                       |
| DTO (request) | `apps/api-core/src/modules/auth/dto/index.ts`       | `123–135` (`ChangePasswordDto`) |
| Service       | `apps/api-core/src/modules/auth/auth.service.ts`    | `changePassword()`              |
| Prisma models | `packages/prisma/prisma/schema.prisma`              | `User`, `Session`               |


# Forgot Password (/docs/auth/forgot-password)



`POST /api/v1/auth/forgot-password` — 🌐 **Public** · Rate limit: **5 req / hour**

Initiates the password reset flow. If the email is registered + active, a reset email is queued (worker-service). Returns success even if the account is unknown — anti-enumeration.



<Callout type="warn">
  **Privacy by default**: response is `200 OK` regardless of whether the email is registered. Client should display a generic "If the address is registered, a reset email has been sent." Do not infer account existence from this response.
</Callout>

## Request [#request]

### Body — `ForgotPasswordDto` [#body--forgotpassworddto]

| Field   | Type              | Required | Validation           | Notes                       |
| ------- | ----------------- | -------- | -------------------- | --------------------------- |
| `email` | string (RFC 5322) | ✓        | Trimmed + lowercased | Lookup against `User.email` |

## Response [#response]

### `200 OK` — `ApiResponseOf<MessageResponseDto>` [#200-ok--apiresponseofmessageresponsedto]

```json
{ "success": true, "data": { "message": "Password reset email sent if account exists" } }
```

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                                                                |
| ----- | ------------------ | --------------------------------------------------------------------- |
| `429` | (throttle)         | Rate limit exceeded (5 req/hour — strict to deter enumeration + spam) |

## Side effects [#side-effects]

1. Lookup `User` by email; **always returns success** (anti-enumeration).
2. If user exists + active + email-verified: invalidate prior `PasswordReset` records, create new token, queue reset email (worker-service).
3. Audit log: `auth.forgot_password.requested` (always logged regardless of account existence).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/forgot-password \
      -H 'Content-Type: application/json' \
      -d '{"email": "creator@example.com"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function forgotPassword(email: string): Promise<{ message: string }> {
      const res = await fetch('https://api.bio.re/api/v1/auth/forgot-password', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Request failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useForgotPassword() {
      return useMutation({
        mutationFn: async (email: string) => {
          const res = await fetch('/api/v1/auth/forgot-password', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ email }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Request failed'), {
              code: json?.error?.code,
            });
          }
          return json.data;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/forgot-password', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source        | Path                                                | Lines                           |
| ------------- | --------------------------------------------------- | ------------------------------- |
| Controller    | `apps/api-core/src/modules/auth/auth.controller.ts` | `204–212`                       |
| DTO (request) | `apps/api-core/src/modules/auth/dto/index.ts`       | `108–113` (`ForgotPasswordDto`) |
| Service       | `apps/api-core/src/modules/auth/auth.service.ts`    | `forgotPassword()`              |
| Prisma models | `packages/prisma/prisma/schema.prisma`              | `User`, `PasswordReset`         |


# Complete Login with 2FA (/docs/auth/login-2fa)



`POST /api/v1/auth/login/2fa` — 🌐 **Public** · Rate limit: **10 req / hour** · AUTH-P16

Completes the 2FA login flow. Call this AFTER `POST /auth/login` returned `requiresTwoFactor: true` with a `tempToken`. Returns full JWT pair (access + refresh cookie) on success.

## Request [#request]

### Body — `LoginTwoFactorDto` [#body--logintwofactordto]

| Field       | Type          | Required | Validation    | Notes                                           |
| ----------- | ------------- | -------- | ------------- | ----------------------------------------------- |
| `tempToken` | string (UUID) | ✓        | `@IsUUID()`   | Temp token from prior `/auth/login` response    |
| `code`      | string        | ✓        | `@IsString()` | 6-digit TOTP code OR a backup code (8–10 chars) |

## Response [#response]

### `200 OK` — `ApiResponseOf<LoginResponseDto>` [#200-ok--apiresponseofloginresponsedto]

```json
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 900
  }
}
```

Refresh token is set as `httpOnly` cookie scoped to `.bio.re` (not in body).

### Errors [#errors]

| HTTP  | `code` / `i18nKey`           | Reason                                           |
| ----- | ---------------------------- | ------------------------------------------------ |
| `401` | `auth.2fa.invalid_code`      | TOTP code wrong, or backup code already used     |
| `401` | `auth.2fa.challenge_expired` | `tempToken` expired (>5 min) or already consumed |
| `429` | (throttle)                   | Rate limit exceeded (10 req/hour)                |

## Side effects [#side-effects]

1. Look up `Challenge` by `tempToken`; verify not expired + not consumed.
2. Verify TOTP code against `User.twoFactorSecret` (decrypted with `ENCRYPTION_MASTER_KEY`) — OR match a backup code from `BackupCode` (deletes on use).
3. Mark `Challenge.usedAt = now()` (single-use).
4. Issue access + refresh JWT pair; create `Session` record.
5. Audit log: `auth.2fa.login.success` or `auth.2fa.login.failure`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/login/2fa \
      -H 'Content-Type: application/json' \
      -c cookies.txt \
      -d '{
        "tempToken": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "code": "123456"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function loginTwoFactor(tempToken: string, code: string): Promise<{ accessToken: string; expiresIn: number }> {
      const res = await fetch('https://api.bio.re/api/v1/auth/login/2fa', {
        method: 'POST',
        credentials: 'include',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ tempToken, code }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? '2FA failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useLoginTwoFactor() {
      return useMutation({
        mutationFn: async (input: { tempToken: string; code: string }) => {
          const res = await fetch('/api/v1/auth/login/2fa', {
            method: 'POST',
            credentials: 'include',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? '2FA failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data;
        },
        onSuccess: () => {
          router.push('/dashboard');
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/login/2fa', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                   | Lines                                                        |
| -------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/auth/auth.controller.ts`    | `144–164`                                                    |
| DTO (request)  | `apps/api-core/src/modules/auth/dto/two-factor.dto.ts` | `9–15` (`LoginTwoFactorDto`)                                 |
| DTO (response) | `apps/api-core/src/modules/auth/dto/response.dto.ts`   | `17–29` (`LoginResponseDto`)                                 |
| Service        | `apps/api-core/src/modules/auth/auth.service.ts`       | `verifyLoginTwoFactor()`                                     |
| Service (TOTP) | `apps/api-core/src/modules/auth/two-factor.service.ts` | TOTP verify                                                  |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                 | `Challenge`, `BackupCode`, `User.twoFactorSecret`, `Session` |


# Login with Email + Password (/docs/auth/login)



`POST /api/v1/auth/login` — 🌐 **Public** · Rate limit: **20 req / hour** · Captcha: **required**

Authenticates with email + password. Two flows:

* **Standard** → returns `accessToken` + `expiresIn` + sets `biore_refresh` httpOnly cookie.
* **2FA enabled** → returns `requiresTwoFactor: true` + `tempToken`. Client must call `POST /auth/login/2fa` next.



<Callout type="info">
  The refresh token is set as an `httpOnly`, `secure`, `SameSite=Strict` cookie scoped to `.bio.re`. It is **not** in the response body — clients should not read it.
</Callout>

## Request [#request]

### Body — `LoginDto` [#body--logindto]

| Field            | Type              | Required | Validation                                                          | Notes                                       |
| ---------------- | ----------------- | -------- | ------------------------------------------------------------------- | ------------------------------------------- |
| `email`          | string (RFC 5322) | ✓        | Trimmed + lowercased                                                | Lookup against `User.email`                 |
| `password`       | string            | ✓        | `IsString()`                                                        | bcrypt-compared against `User.passwordHash` |
| `captchaToken`   | string            | —        | Validated by `CaptchaGuard` (admin-managed provider)                | Required if captcha enabled                 |
| `turnstileToken` | string            | —        | **Deprecated** alias for `captchaToken` (1 sprint backwards-compat) | —                                           |

## Response [#response]

### `200 OK` — standard flow (`ApiResponseOf<LoginResponseDto>`) [#200-ok--standard-flow-apiresponseofloginresponsedto]

```json
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 900
  }
}
```

### `200 OK` — 2FA flow (LoginResponseDto with `requiresTwoFactor`) [#200-ok--2fa-flow-loginresponsedto-with-requirestwofactor]

```json
{
  "success": true,
  "data": {
    "requiresTwoFactor": true,
    "tempToken": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

### Errors [#errors]

| HTTP  | `code` / `i18nKey`               | Reason                                                        |
| ----- | -------------------------------- | ------------------------------------------------------------- |
| `400` | (DTO validation)                 | Invalid email or missing password                             |
| `401` | `auth.login.invalid_credentials` | Email not found OR password mismatch (deliberately ambiguous) |
| `401` | `auth.login.account_locked`      | `User.lockedUntil` in the future (too many failed attempts)   |
| `401` | `auth.login.account_suspended`   | `User.status = SUSPENDED`                                     |
| `401` | `auth.login.account_deactivated` | `User.status = DEACTIVATED` (use reactivate flow)             |
| `403` | `auth.login.email_not_verified`  | Account exists but `User.emailVerified = false`               |
| `429` | (throttle)                       | Rate limit exceeded (20 req/hour)                             |

## Side effects [#side-effects]

1. Lookup `User` by email.
2. bcrypt compare against `User.passwordHash`.
3. On success: create `Session` record, generate access + refresh JWTs, set httpOnly cookie.
4. On failure: increment `User.loginAttempts`; lock account (`User.lockedUntil`) after threshold (config `auth.lockout_threshold`).
5. If `User.twoFactorEnabled`: skip token issuance, return `tempToken` from `Challenge` table.
6. Track device via `device-tracking.service` — new device → security alert email.
7. Audit log: `auth.login.success` or `auth.login.failure`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/login \
      -H 'Content-Type: application/json' \
      -c cookies.txt \
      -d '{
        "email": "creator@example.com",
        "password": "SecureP@ss123",
        "captchaToken": "<turnstile_token>"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type LoginResponse =
      | { accessToken: string; expiresIn: number }
      | { requiresTwoFactor: true; tempToken: string };

    async function login(email: string, password: string, captchaToken?: string): Promise<LoginResponse> {
      const res = await fetch('https://api.bio.re/api/v1/auth/login', {
        method: 'POST',
        credentials: 'include', // accept refresh cookie
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email, password, captchaToken }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Login failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useLogin() {
      return useMutation({
        mutationFn: async (input: { email: string; password: string; captchaToken?: string }) => {
          const res = await fetch('/api/v1/auth/login', {
            method: 'POST',
            credentials: 'include',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Login failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as LoginResponse;
        },
        onSuccess: (data) => {
          if ('requiresTwoFactor' in data) {
            router.push(`/auth/2fa?tempToken=${data.tempToken}`);
          } else {
            // Store accessToken in memory; refresh cookie is httpOnly
            router.push('/dashboard');
          }
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/login', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                 | Lines                                    |
| -------------- | ---------------------------------------------------- | ---------------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/auth.controller.ts`  | `119–142`                                |
| DTO (request)  | `apps/api-core/src/modules/auth/dto/index.ts`        | `74–90` (`LoginDto`)                     |
| DTO (response) | `apps/api-core/src/modules/auth/dto/response.dto.ts` | `17–29` (`LoginResponseDto`)             |
| Service        | `apps/api-core/src/modules/auth/auth.service.ts`     | `login()`, `device-tracking.service.ts`  |
| Prisma models  | `packages/prisma/prisma/schema.prisma`               | `User`, `Session`, `Challenge`, `Device` |


# Logout (/docs/auth/logout)



`POST /api/v1/auth/logout` — 🌐 **Public** · Rate limit: **60 req / hour**

Revokes the user's refresh token (from `biore_refresh` httpOnly cookie or `body.refreshToken`) and clears the cookie. Always returns success even if no token is present (idempotent).



<Callout type="info">
  This endpoint marks the `Session` row revoked. The user's access token (JWT) remains valid until expiry (\~15 minutes) — to truly kill access immediately, also invalidate it client-side and rely on the short access TTL.
</Callout>

## Request [#request]

### Cookies [#cookies]

| Cookie          | Notes                                                     |
| --------------- | --------------------------------------------------------- |
| `biore_refresh` | httpOnly cookie, automatically sent. Cleared in response. |

### Body — `LogoutDto` (cookie fallback only) [#body--logoutdto-cookie-fallback-only]

| Field          | Type   | Required | Validation                  | Notes                                              |
| -------------- | ------ | -------- | --------------------------- | -------------------------------------------------- |
| `refreshToken` | string | —        | `@IsOptional() @IsString()` | Used only when no cookie (mobile / non-web client) |

## Response [#response]

### `200 OK` — `ApiResponseOf<MessageResponseDto>` [#200-ok--apiresponseofmessageresponsedto]

```json
{ "success": true, "data": { "message": "Logged out successfully" } }
```

The `biore_refresh` cookie is set with `Max-Age=0` (cleared).

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                            |
| ----- | ------------------ | --------------------------------- |
| `429` | (throttle)         | Rate limit exceeded (60 req/hour) |

## Side effects [#side-effects]

1. Mark `Session.revokedAt = now()` for the matching refresh token (if present).
2. Clear `biore_refresh` cookie via `Set-Cookie` with `Max-Age=0`.
3. Audit log: `auth.logout.success`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/logout \
      -b cookies.txt -c cookies.txt
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function logout(): Promise<void> {
      await fetch('https://api.bio.re/api/v1/auth/logout', {
        method: 'POST',
        credentials: 'include',
      });
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useLogout() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async () => {
          await fetch('/api/v1/auth/logout', {
            method: 'POST',
            credentials: 'include',
          });
        },
        onSettled: () => {
          qc.clear();
          router.push('/login');
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/logout', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source        | Path                                                | Lines                   |
| ------------- | --------------------------------------------------- | ----------------------- |
| Controller    | `apps/api-core/src/modules/auth/auth.controller.ts` | `188–202`               |
| DTO (request) | `apps/api-core/src/modules/auth/dto/index.ts`       | `103–106` (`LogoutDto`) |
| Service       | `apps/api-core/src/modules/auth/auth.service.ts`    | `logout()`              |
| Prisma model  | `packages/prisma/prisma/schema.prisma`              | `Session.revokedAt`     |


# Current User Identity (/docs/auth/me)



`GET /api/v1/auth/me` — 🔑 **User-auth** (Bearer JWT) · Rate limit: **60 req / hour**

Returns the current authenticated user's identity. Lightweight — only canonical user fields, no role or permission data (use `/users/profile` for richer profile).



<Callout type="info">
  This is the canonical "who am I" endpoint — frontends typically call it on app boot to hydrate the auth state and decide rendering (creator vs fan, verified vs unverified, status).
</Callout>

## Request [#request]

### Headers [#headers]

| Header          | Value                  | Notes    |
| --------------- | ---------------------- | -------- |
| `Authorization` | `Bearer <accessToken>` | Required |

No body, no query params.

## Response [#response]

### `200 OK` — `ApiResponseOf<UserIdentityResponseDto>` [#200-ok--apiresponseofuseridentityresponsedto]

```json
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "creator@bio.re",
    "username": "creator",
    "displayName": "Awesome Creator",
    "avatarUrl": "https://cdn.bio.re/avatars/abc.jpg",
    "status": "ACTIVE",
    "emailVerified": true
  }
}
```

### `UserIdentityResponseDto` fields [#useridentityresponsedto-fields]

| Field           | Type           | Notes                                                             |
| --------------- | -------------- | ----------------------------------------------------------------- |
| `id`            | string (UUID)  | `User.id`                                                         |
| `email`         | string         | `User.email` (lowercase)                                          |
| `username`      | string \| null | `User.username` (nullable — fan accounts may not have one)        |
| `displayName`   | string \| null | `User.displayName`                                                |
| `avatarUrl`     | string \| null | `User.avatarUrl`                                                  |
| `status`        | enum           | One of: `ACTIVE`, `SUSPENDED`, `BANNED`, `DELETED`, `DEACTIVATED` |
| `emailVerified` | boolean        | `User.emailVerified`                                              |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`  | Reason                             |
| ----- | ------------------- | ---------------------------------- |
| `401` | (no JWT or invalid) | Not authenticated or token expired |
| `429` | (throttle)          | Rate limit exceeded (60 req/hour)  |

## Side effects [#side-effects]

1. Lookup `User` by `id` (decoded from JWT).
2. Project to `UserIdentityResponseDto` (no relations loaded).
3. No mutations.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X GET https://api.bio.re/api/v1/auth/me \
      -H 'Authorization: Bearer <accessToken>'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type Identity = {
      id: string;
      email: string;
      username: string | null;
      displayName: string | null;
      avatarUrl: string | null;
      status: 'ACTIVE' | 'SUSPENDED' | 'BANNED' | 'DELETED' | 'DEACTIVATED';
      emailVerified: boolean;
    };

    async function getMe(accessToken: string): Promise<Identity> {
      const res = await fetch('https://api.bio.re/api/v1/auth/me', {
        headers: { 'Authorization': `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const meKeys = {
      identity: ['auth', 'me'] as const,
    };

    export function useMe() {
      return useQuery({
        queryKey: meKeys.identity,
        queryFn: async () => {
          const res = await fetch('/api/v1/auth/me', {
            headers: { 'Authorization': `Bearer ${getAccessToken()}` },
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            if (res.status === 401) {
              // Trigger refresh flow or redirect to login
              throw Object.assign(new Error('Unauthenticated'), { code: 'auth.unauthenticated' });
            }
            throw Object.assign(new Error(json?.error?.message ?? 'Failed'), {
              code: json?.error?.code,
            });
          }
          return json.data as Identity;
        },
        staleTime: 5 * 60 * 1000, // 5 min — identity rarely changes
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/me', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                 | Lines                                    |
| -------------- | ---------------------------------------------------- | ---------------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/auth.controller.ts`  | `299–313`                                |
| DTO (response) | `apps/api-core/src/modules/auth/dto/response.dto.ts` | `49–82` (`UserIdentityResponseDto`)      |
| Service        | `apps/api-core/src/modules/auth/auth.service.ts`     | `getIdentity(userId)`                    |
| Prisma model   | `packages/prisma/prisma/schema.prisma`               | `User` (status, emailVerified, username) |


# Link OAuth Provider (/docs/auth/oauth-link)



`POST /api/v1/auth/oauth/link` — 🔑 **User-auth** (Bearer JWT) · Rate limit: **20 req / hour**

Links an OAuth identity to the current user. Useful when a user registered with email + password and later wants to add Google/Apple/X login as an alternative sign-in.



<Callout type="info">
  The provider account is **unique per platform**: an OAuth identity that's already linked to another user returns `409 conflict`. Server-side verification of the token (same `OAuthVerifierService` as `/auth/oauth/login`) prevents claim forgery.
</Callout>

## Request [#request]

### Headers [#headers]

| Header          | Value                  | Notes    |
| --------------- | ---------------------- | -------- |
| `Authorization` | `Bearer <accessToken>` | Required |
| `Content-Type`  | `application/json`     | Required |

### Body — `OAuthLinkDto` [#body--oauthlinkdto]

Same shape as `OAuthLoginDto` minus `referralCode`:

| Field          | Type                         | Required       | Notes                   |
| -------------- | ---------------------------- | -------------- | ----------------------- |
| `provider`     | `'google' \| 'apple' \| 'x'` | ✓              | `IsIn(OAUTH_PROVIDERS)` |
| `idToken`      | string                       | conditional    | Google / Apple flow     |
| `code`         | string                       | conditional    | Code flow               |
| `codeVerifier` | string                       | required for X | PKCE                    |

## Response [#response]

### `200 OK` — `ApiResponseOf<MessageResponseDto>` [#200-ok--apiresponseofmessageresponsedto]

```json
{ "success": true, "data": { "message": "Provider linked successfully" } }
```

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                | Reason                                                          |
| ----- | --------------------------------- | --------------------------------------------------------------- |
| `400` | `auth.oauth.already_linked`       | This user already has the provider linked                       |
| `400` | `auth.oauth.provider_disabled`    | Admin disabled this platform                                    |
| `400` | (DTO validation)                  | Missing both `idToken` and `code`; missing `codeVerifier` for X |
| `401` | (no JWT or invalid)               | Not authenticated OR token verification failed                  |
| `409` | `auth.oauth.linked_to_other_user` | This OAuth identity is already linked to a different user       |
| `429` | (throttle)                        | Rate limit exceeded (20 req/hour)                               |

## Side effects [#side-effects]

1. Verify token via `OAuthVerifierService.verify()`.
2. Check existing `SocialAccount` for `(provider, providerUserId)`:
   * If linked to **current user** → return `400 already_linked`.
   * If linked to **another user** → return `409 linked_to_other_user`.
3. Insert `SocialAccount` row tying current user to provider profile.
4. Audit log: `auth.oauth.link.success`.
5. Send notification email: "`{Provider}` account linked to your BIO.RE login on `{date}`".

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/oauth/link \
      -H 'Authorization: Bearer <accessToken>' \
      -H 'Content-Type: application/json' \
      -d '{
        "provider": "google",
        "idToken": "<google_id_token>"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type OAuthLinkInput = {
      provider: 'google' | 'apple' | 'x';
      idToken?: string;
      code?: string;
      codeVerifier?: string;
    };

    async function linkOAuth(input: OAuthLinkInput, accessToken: string): Promise<{ message: string }> {
      const res = await fetch('https://api.bio.re/api/v1/auth/oauth/link', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${accessToken}`,
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Link failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';
    import { meKeys } from './use-me';

    export function useOAuthLink() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (input: OAuthLinkInput) => {
          const res = await fetch('/api/v1/auth/oauth/link', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              'Authorization': `Bearer ${getAccessToken()}`,
            },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Link failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data;
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: meKeys.identity });
          toast.success(t('auth.oauth.linked'));
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/oauth/link', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source           | Path                                                       | Lines                    |
| ---------------- | ---------------------------------------------------------- | ------------------------ |
| Controller       | `apps/api-core/src/modules/auth/oauth.controller.ts`       | `67–88` (`link`)         |
| DTO (request)    | `apps/api-core/src/modules/auth/dto/oauth.dto.ts`          | `35–57` (`OAuthLinkDto`) |
| Service (verify) | `apps/api-core/src/modules/auth/oauth-verifier.service.ts` | `verify()`               |
| Service (link)   | `apps/api-core/src/modules/auth/oauth.service.ts`          | `linkProvider()`         |
| Prisma model     | `packages/prisma/prisma/schema.prisma`                     | `SocialAccount`, `User`  |


# Login or Register via OAuth (/docs/auth/oauth-login)



`POST /api/v1/auth/oauth/login` — 🌐 **Public** · Rate limit: **10 req / hour** · Captcha: **NOT required** (provider handles)

Single endpoint for OAuth flows: if the provider's user is unknown, a fresh BIO.RE account is auto-created from the verified profile. If known, the existing account is logged in. Returns `accessToken` + sets `httpOnly` refresh cookie.



<Callout type="info">
  Server-side verification is **mandatory**. The frontend obtains an `idToken` (Google/Apple) or `code` (any provider) from the SDK, sends it here; the backend re-verifies against the provider's public keys via `OAuthVerifierService` — never trusts the frontend's claim blindly.
</Callout>

<Callout type="warn">
  **Three login providers**: `google`, `apple`, `x`. Despite 15 OAuth platforms in admin (`OAuthProvider` table), only these three are accepted for **login**. The other 12 (discord, github, instagram, linkedin, pinterest, reddit, spotify, threads, tiktok, twitch, youtube, facebook) are **verify-only** — used by `creator/social/connect` to attach social accounts, not to log in.
</Callout>

## Request [#request]

### Body — `OAuthLoginDto` [#body--oauthlogindto]

| Field          | Type                         | Required       | Validation              | Notes                                                           |
| -------------- | ---------------------------- | -------------- | ----------------------- | --------------------------------------------------------------- |
| `provider`     | `'google' \| 'apple' \| 'x'` | ✓              | `IsIn(OAUTH_PROVIDERS)` | Active login provider                                           |
| `idToken`      | string                       | conditional    | max 5000 chars          | Required for Google + Apple flows (alternative to `code`)       |
| `code`         | string                       | conditional    | max 2000 chars          | Authorization code from any provider (alternative to `idToken`) |
| `codeVerifier` | string                       | required for X | max 256 chars           | PKCE code verifier — **mandatory for X** flow                   |
| `referralCode` | string                       | —              | —                       | Attribution if a brand-new account is auto-created              |

At least one of `idToken` or `code` MUST be present. PKCE (`codeVerifier`) is X-specific.

## Response [#response]

### `200 OK` — `ApiResponseOf<OAuthLoginResponseDto>` [#200-ok--apiresponseofoauthloginresponsedto]

```json
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 900,
    "isNewUser": false
  }
}
```

| Field         | Type    | Notes                                                                               |
| ------------- | ------- | ----------------------------------------------------------------------------------- |
| `accessToken` | string  | Short-lived JWT (\~15 min)                                                          |
| `expiresIn`   | number  | Seconds to access token expiry                                                      |
| `isNewUser`   | boolean | `true` if this call auto-created a fresh BIO.RE account; client may show onboarding |

Refresh token is set as `httpOnly` cookie scoped to `.bio.re`.

### Errors [#errors]

| HTTP  | `code` / `i18nKey`             | Reason                                                                                                                                               |
| ----- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `auth.oauth.provider_disabled` | `provider` not in active login set OR admin disabled the platform                                                                                    |
| `400` | (DTO validation)               | Missing both `idToken` and `code`; missing `codeVerifier` for X                                                                                      |
| `401` | `auth.oauth.token_invalid`     | Provider rejected the token (signature, audience, expiry)                                                                                            |
| `409` | `auth.oauth.email_exists`      | Account already exists under that email; response includes `hasPassword` + `hasOAuth` flags so client can prompt linking via `POST /auth/oauth/link` |
| `429` | (throttle)                     | Rate limit exceeded (10 req/hour)                                                                                                                    |

## Side effects [#side-effects]

1. **OAuthVerifierService.verify(provider, idToken, code, codeVerifier)** — exchanges code for tokens (when `code` flow) and verifies idToken against provider's JWK set.
2. Lookup existing `SocialAccount` by `(provider, providerUserId)`. If found → load `User`, log in.
3. If not found, lookup `User` by verified `email` from provider profile. If found → conflict (`email_exists`) — client must call `/auth/oauth/link`.
4. If neither match → auto-register: insert `User` (verified email, no password), `SocialAccount`, optional `referredBy` resolution, `ConsentRecord` (terms + privacy implicitly accepted via OAuth flow per platform policy).
5. Issue access + refresh JWT pair, set httpOnly cookie.
6. Audit log: `auth.oauth.login.success` or `.register.success`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    # Google flow (idToken from Google Identity Services)
    curl -X POST https://api.bio.re/api/v1/auth/oauth/login \
      -H 'Content-Type: application/json' \
      -c cookies.txt \
      -d '{
        "provider": "google",
        "idToken": "<google_id_token>"
      }'

    # X flow (code + PKCE verifier)
    curl -X POST https://api.bio.re/api/v1/auth/oauth/login \
      -H 'Content-Type: application/json' \
      -c cookies.txt \
      -d '{
        "provider": "x",
        "code": "<authorization_code>",
        "codeVerifier": "<pkce_code_verifier>"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type OAuthLoginInput = {
      provider: 'google' | 'apple' | 'x';
      idToken?: string;
      code?: string;
      codeVerifier?: string;
      referralCode?: string;
    };

    type OAuthLoginResponse = {
      accessToken: string;
      expiresIn: number;
      isNewUser: boolean;
    };

    async function oauthLogin(input: OAuthLoginInput): Promise<OAuthLoginResponse> {
      const res = await fetch('https://api.bio.re/api/v1/auth/oauth/login', {
        method: 'POST',
        credentials: 'include',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'OAuth failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useOAuthLogin() {
      return useMutation({
        mutationFn: async (input: OAuthLoginInput) => {
          const res = await fetch('/api/v1/auth/oauth/login', {
            method: 'POST',
            credentials: 'include',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'OAuth failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as OAuthLoginResponse;
        },
        onSuccess: (data) => {
          router.push(data.isNewUser ? '/onboarding' : '/dashboard');
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/oauth/login', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source                   | Path                                                       | Lines                                               |
| ------------------------ | ---------------------------------------------------------- | --------------------------------------------------- |
| Controller               | `apps/api-core/src/modules/auth/oauth.controller.ts`       | `30–63` (`login`)                                   |
| DTO (request)            | `apps/api-core/src/modules/auth/dto/oauth.dto.ts`          | `6–33` (`OAuthLoginDto`)                            |
| DTO (response)           | `apps/api-core/src/modules/auth/dto/response.dto.ts`       | `36–45` (`OAuthLoginResponseDto`)                   |
| Service (verify)         | `apps/api-core/src/modules/auth/oauth-verifier.service.ts` | `verify()`                                          |
| Service (login/register) | `apps/api-core/src/modules/auth/oauth.service.ts`          | `loginOrRegister()`                                 |
| Prisma models            | `packages/prisma/prisma/schema.prisma`                     | `User`, `SocialAccount`, `Session`, `ConsentRecord` |


# List OAuth Login Providers (/docs/auth/oauth-providers)



`GET /api/v1/auth/oauth/providers` — 🌐 **Public** · Rate limit: **60 req / hour**



<Callout type="info">
  🛠️ **Admin-managed**: this list is sourced from the `OAuthProvider` table — providers can be enabled/disabled by admin without redeploy. **Never hardcode** `['google', 'x', 'apple']` in the frontend; always read from this endpoint and render only what comes back.
</Callout>

Returns the list of OAuth platforms currently enabled for **login** (subset of all 15 platforms; the rest are verify-only for social account linking). Each entry has the public client ID needed to bootstrap the provider's frontend SDK.

## Request [#request]

No headers, no body, no params.

## Response [#response]

### `200 OK` — `ApiResponseOf<OAuthProvidersResponseDto>` [#200-ok--apiresponseofoauthprovidersresponsedto]

```json
{
  "success": true,
  "data": {
    "providers": [
      {
        "platform": "google",
        "clientId": "123456789-abc.apps.googleusercontent.com",
        "redirectUri": "https://bio.re/auth/callback/google"
      },
      {
        "platform": "apple",
        "clientId": "com.bio.re.signin",
        "redirectUri": "https://bio.re/auth/callback/apple"
      },
      {
        "platform": "x",
        "clientId": "abcdef123456",
        "redirectUri": "https://bio.re/auth/callback/x"
      }
    ]
  }
}
```

### `OAuthProviderDto` fields [#oauthproviderdto-fields]

| Field         | Type                         | Notes                                                                                 |
| ------------- | ---------------------------- | ------------------------------------------------------------------------------------- |
| `platform`    | `'google' \| 'apple' \| 'x'` | OAuth login provider key — passes back into `POST /auth/oauth/login` `provider` field |
| `clientId`    | string                       | Public client ID for the provider's frontend SDK                                      |
| `redirectUri` | string \| null               | Configured redirect URI; null if not set in admin                                     |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                            |
| ----- | ------------------ | --------------------------------- |
| `429` | (throttle)         | Rate limit exceeded (60 req/hour) |

## Side effects [#side-effects]

1. Read all `OAuthProvider` rows where `enabled = true` AND `loginEnabled = true`.
2. Project to `{ platform, clientId, redirectUri }` (never expose secrets).
3. Cached in-memory by `OAuthVerifierService` for \~5 minutes (admin updates invalidate the cache via internal pub/sub).
4. No mutations.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/auth/oauth/providers
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type OAuthProvider = {
      platform: 'google' | 'apple' | 'x';
      clientId: string;
      redirectUri: string | null;
    };

    async function getOAuthProviders(): Promise<OAuthProvider[]> {
      const res = await fetch('https://api.bio.re/api/v1/auth/oauth/providers');
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.providers;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const oauthKeys = {
      providers: ['auth', 'oauth', 'providers'] as const,
    };

    export function useOAuthProviders() {
      return useQuery({
        queryKey: oauthKeys.providers,
        queryFn: async () => {
          const res = await fetch('/api/v1/auth/oauth/providers');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Failed'), {
              code: json?.error?.code,
            });
          }
          return json.data.providers as OAuthProvider[];
        },
        staleTime: 5 * 60 * 1000, // mirrors backend cache
      });
    }
    ```
  </Tab>
</Tabs>

Render dynamically:

```tsx
const { data: providers = [] } = useOAuthProviders();

return (
  <>
    {providers.map((p) => (
      <SignInWithButton key={p.platform} platform={p.platform} clientId={p.clientId} />
    ))}
  </>
);
```

Never `<SignInWithGoogle />` `<SignInWithApple />` `<SignInWithX />` hardcoded — admin can disable a provider at any time.

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/oauth/providers', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                       | Lines                                                                   |
| -------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/oauth.controller.ts`       | `114–123` (`providers`)                                                 |
| DTO (response) | `apps/api-core/src/modules/auth/dto/response.dto.ts`       | `138–152` (`OAuthProviderDto`, `OAuthProvidersResponseDto`)             |
| Service        | `apps/api-core/src/modules/auth/oauth-verifier.service.ts` | `getPublicClientIds()`                                                  |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                     | `OAuthProvider` (15 platforms — `loginEnabled` filters to login subset) |


# Unlink OAuth Provider (/docs/auth/oauth-unlink)



`DELETE /api/v1/auth/oauth/unlink/{provider}` — 🔑 **User-auth** (Bearer JWT) · Rate limit: **20 req / hour**

Detaches an OAuth identity from the current user. Refuses to unlink if it's the user's **only** sign-in method (no password + no other OAuth) — protects against accidental lockout.



<Callout type="warn">
  **Anti-lockout guard**: if the user has no `User.passwordHash` AND only this provider is linked, the request returns `400 only_auth_method`. Set a password first via the password reset flow if you want to unlink the only OAuth login.
</Callout>

## Request [#request]

### Headers [#headers]

| Header          | Value                  | Notes    |
| --------------- | ---------------------- | -------- |
| `Authorization` | `Bearer <accessToken>` | Required |

### Path parameters [#path-parameters]

| Param      | Type                         | Validation                                   | Notes                                                                  |
| ---------- | ---------------------------- | -------------------------------------------- | ---------------------------------------------------------------------- |
| `provider` | `'google' \| 'apple' \| 'x'` | Allowlisted in controller (`validProviders`) | Hardcoded check — non-login providers (discord, github, etc.) rejected |

No body, no query.

## Response [#response]

### `200 OK` — `ApiResponseOf<MessageResponseDto>` [#200-ok--apiresponseofmessageresponsedto]

```json
{ "success": true, "data": { "message": "Provider unlinked successfully" } }
```

### Errors [#errors]

| HTTP  | `code` / `i18nKey`             | Reason                                                        |
| ----- | ------------------------------ | ------------------------------------------------------------- |
| `400` | `auth.oauth.provider_disabled` | `provider` not in `['google', 'apple', 'x']`                  |
| `400` | `auth.oauth.not_linked`        | Current user has no `SocialAccount` row for this provider     |
| `400` | `auth.oauth.only_auth_method`  | Anti-lockout — no password + this is the last linked provider |
| `401` | (no JWT or invalid)            | Not authenticated                                             |
| `429` | (throttle)                     | Rate limit exceeded (20 req/hour)                             |

## Side effects [#side-effects]

1. Validate `provider` against allowlist (`['google', 'apple', 'x']`).
2. Look up `SocialAccount` row for `(userId, provider)`; verify exists.
3. Anti-lockout check: count user's `SocialAccount` rows + check `User.passwordHash`. If unlinking would leave **zero** sign-in methods → reject `400 only_auth_method`.
4. Delete `SocialAccount` row.
5. Audit log: `auth.oauth.unlink.success`.
6. Send notification email: "`{Provider}` unlinked from your BIO.RE login on `{date}`".

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X DELETE https://api.bio.re/api/v1/auth/oauth/unlink/google \
      -H 'Authorization: Bearer <accessToken>'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function unlinkOAuth(provider: 'google' | 'apple' | 'x', accessToken: string): Promise<{ message: string }> {
      const res = await fetch(`https://api.bio.re/api/v1/auth/oauth/unlink/${provider}`, {
        method: 'DELETE',
        headers: { 'Authorization': `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Unlink failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';
    import { meKeys } from './use-me';

    export function useOAuthUnlink() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (provider: 'google' | 'apple' | 'x') => {
          const res = await fetch(`/api/v1/auth/oauth/unlink/${provider}`, {
            method: 'DELETE',
            headers: { 'Authorization': `Bearer ${getAccessToken()}` },
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Unlink failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data;
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: meKeys.identity });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/oauth/unlink/{provider}', method: 'delete' }]" hasHead="false" />

## Source [#source]

| Source       | Path                                                 | Lines                                |
| ------------ | ---------------------------------------------------- | ------------------------------------ |
| Controller   | `apps/api-core/src/modules/auth/oauth.controller.ts` | `92–110` (`unlink`)                  |
| Service      | `apps/api-core/src/modules/auth/oauth.service.ts`    | `unlinkProvider()`                   |
| Prisma model | `packages/prisma/prisma/schema.prisma`               | `SocialAccount`, `User.passwordHash` |


# Validate Reactivation Token (/docs/auth/reactivate-validate)



`GET /api/v1/auth/reactivate/validate?token=...` — 🌐 **Public** · Rate limit: **30 req / hour**

Pre-flight check: validates a reactivation token without committing reactivation. Returns the account status (`paused` / `pending-deletion` / `expired` / `deleted`) so the landing page can render appropriate UI before the user clicks the "Reactivate" button.



<Callout type="info">
  The actual reactivation happens via `POST /users/reactivate` (separate endpoint, in the `user` module). This endpoint is read-only — it lets the UI show "Welcome back, your account is paused — click below to reactivate" vs "This account was deleted and cannot be recovered".
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param   | Type   | Required | Notes                                         |
| ------- | ------ | -------- | --------------------------------------------- |
| `token` | string | ✓        | Opaque reactivation token from the email link |

No body, no path params, no headers.

## Response [#response]

### `200 OK` — `ApiResponseOf<ReactivateValidateResponseDto>` [#200-ok--apiresponseofreactivatevalidateresponsedto]

```json
{
  "success": true,
  "data": {
    "valid": true,
    "status": "paused",
    "userMaskEmail": "u***@b***.re",
    "deletionDate": null
  }
}
```

| Field           | Type                      | Notes                                                                                               |
| --------------- | ------------------------- | --------------------------------------------------------------------------------------------------- |
| `valid`         | boolean                   | `false` if token is malformed, unknown, used, or expired                                            |
| `status`        | enum                      | One of: `paused` / `pending-deletion` / `expired` / `deleted`                                       |
| `userMaskEmail` | string \| null            | Masked email (single-letter prefix per `maskEmail` helper) of the account associated with the token |
| `deletionDate`  | string (ISO 8601) \| null | Hard-deletion schedule — present **only** when `status = pending-deletion`                          |

### Status semantics [#status-semantics]

| `status`           | Meaning                                                                                         | UI guidance                                                    |
| ------------------ | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `paused`           | Account is `DEACTIVATED`, no pending deletion → reactivate eligible                             | "Reactivate your account" CTA                                  |
| `pending-deletion` | Account is `DEACTIVATED` + `GDPRRequest DELETION` pending in grace window → reactivate eligible | "Cancel deletion + reactivate (deadline `{deletionDate}`)" CTA |
| `expired`          | Token signature valid but `expiresAt` past → user must re-request link                          | "This link expired — request a new one"                        |
| `deleted`          | Account purged (`UserStatus.DELETED`) → cannot reactivate                                       | "This account has been permanently deleted" — terminal         |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                            |
| ----- | ------------------ | --------------------------------- |
| `429` | (throttle)         | Rate limit exceeded (30 req/hour) |

The endpoint always returns 200 — invalid / unknown / expired tokens come back with `valid: false` (not 4xx) so the landing page can render a coherent expired-link UI.

## Side effects [#side-effects]

1. Decode + verify token signature.
2. Look up associated `User` + `GDPRRequest` (if any).
3. Compute status from `User.status` + `GDPRRequest.status` + `expiresAt`.
4. Mask email for display.
5. **No mutations** — purely a read endpoint. The reactivation itself is a separate POST.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/auth/reactivate/validate?token=abc123-from-email-link'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type ReactivateStatus = 'paused' | 'pending-deletion' | 'expired' | 'deleted';

    type ReactivateValidate = {
      valid: boolean;
      status: ReactivateStatus;
      userMaskEmail: string | null;
      deletionDate: string | null;
    };

    async function validateReactivate(token: string): Promise<ReactivateValidate> {
      const url = new URL('https://api.bio.re/api/v1/auth/reactivate/validate');
      url.searchParams.set('token', token);
      const res = await fetch(url);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const reactivateKeys = {
      validate: (token: string) => ['auth', 'reactivate', 'validate', token] as const,
    };

    export function useReactivateValidate(token: string) {
      return useQuery({
        queryKey: reactivateKeys.validate(token),
        queryFn: async () => {
          const url = new URL('/api/v1/auth/reactivate/validate', window.location.origin);
          url.searchParams.set('token', token);
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Failed'), {
              code: json?.error?.code,
            });
          }
          return json.data as ReactivateValidate;
        },
        enabled: Boolean(token),
        retry: false, // Token state is deterministic — no point retrying
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/reactivate/validate', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                            | Lines                                                                      |
| -------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/auth.controller.ts`             | `407–423` (`reactivateValidate`)                                           |
| DTO (response) | `apps/api-core/src/modules/auth/dto/reactivate-validate.dto.ts` | `34–45` (`ReactivateValidateResponseDto`), `21–24` (`REACTIVATE_STATUSES`) |
| Service        | `apps/api-core/src/modules/auth/challenge.service.ts`           | `validateReactivationToken()`                                              |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                          | `User.status`, `GDPRRequest`                                               |


# Refresh Access Token (/docs/auth/refresh)



`POST /api/v1/auth/refresh` — 🌐 **Public** · Rate limit: **60 req / hour**

Rotates the refresh token. Reads from the `biore_refresh` httpOnly cookie by default, or from `body.refreshToken` as fallback. Issues a new access token + new refresh token (cookie). Detects refresh token reuse → revokes ALL sessions for the user (security alert).



<Callout type="warn">
  **Token reuse detection**: if a refresh token is presented after it's been rotated, the entire user session family is revoked and a security alert email is sent. Clients must always discard the old refresh token immediately upon receiving a new one.
</Callout>

## Request [#request]

### Cookies [#cookies]

| Cookie          | Notes                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------- |
| `biore_refresh` | httpOnly, Secure, SameSite=Strict, scoped to `.bio.re`. Auto-sent by browsers; preferred path. |

### Body — `RefreshDto` (cookie fallback only) [#body--refreshdto-cookie-fallback-only]

| Field          | Type   | Required | Validation                  | Notes                                                             |
| -------------- | ------ | -------- | --------------------------- | ----------------------------------------------------------------- |
| `refreshToken` | string | —        | `@IsOptional() @IsString()` | Used only when cookie is absent (e.g., mobile app non-web client) |

## Response [#response]

### `200 OK` — `ApiResponseOf<LoginResponseDto>` [#200-ok--apiresponseofloginresponsedto]

```json
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 900
  }
}
```

A new `biore_refresh` cookie is set. The old refresh token is revoked (Session record updated).

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                  | Reason                                                                      |
| ----- | ----------------------------------- | --------------------------------------------------------------------------- |
| `401` | `auth.refresh.invalid_token`        | Refresh token not found, expired, or already rotated                        |
| `401` | `auth.refresh.token_reuse_detected` | **Security alert** — token reused after rotation; all user sessions revoked |
| `401` | `auth.refresh.account_suspended`    | `User.status = SUSPENDED` between issuance and refresh                      |
| `429` | (throttle)                          | Rate limit exceeded (60 req/hour)                                           |

## Side effects [#side-effects]

1. Verify refresh token signature + lookup `Session` record.
2. **Reuse check**: if `Session.rotatedAt != null`, all sessions for this `User` are revoked + admin alert + email to user (security incident).
3. On valid refresh: mark old `Session.rotatedAt = now()`, create new Session with new refresh token, issue new access token.
4. Update httpOnly cookie with new refresh token.
5. Audit log: `auth.refresh.success` or `auth.refresh.token_reuse_detected`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    # Cookie-based (preferred):
    curl -X POST https://api.bio.re/api/v1/auth/refresh \
      -b cookies.txt -c cookies.txt

    # Body-based (mobile / non-cookie clients):
    curl -X POST https://api.bio.re/api/v1/auth/refresh \
      -H 'Content-Type: application/json' \
      -d '{"refreshToken": "..."}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function refresh(): Promise<{ accessToken: string; expiresIn: number }> {
      const res = await fetch('https://api.bio.re/api/v1/auth/refresh', {
        method: 'POST',
        credentials: 'include', // sends + receives biore_refresh cookie
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Refresh failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useRefresh() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/auth/refresh', {
            method: 'POST',
            credentials: 'include',
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Refresh failed'), {
              code: json?.error?.code,
            });
          }
          return json.data;
        },
        onError: (err: { code?: string }) => {
          if (err.code === 'auth.refresh.token_reuse_detected') {
            // Security incident — force re-login
            qc.clear();
            router.push('/login?reason=security_alert');
          }
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/refresh', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                 | Lines                                         |
| -------------- | ---------------------------------------------------- | --------------------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/auth.controller.ts`  | `166–186`                                     |
| DTO (request)  | `apps/api-core/src/modules/auth/dto/index.ts`        | `98–101` (`RefreshDto`)                       |
| DTO (response) | `apps/api-core/src/modules/auth/dto/response.dto.ts` | `17–29` (`LoginResponseDto`)                  |
| Service        | `apps/api-core/src/modules/auth/auth.service.ts`     | `refresh()`, reuse detection logic            |
| Prisma model   | `packages/prisma/prisma/schema.prisma`               | `Session.rotatedAt` (token rotation tracking) |


# Register New Account (/docs/auth/register)





`POST /api/v1/auth/register` — 🌐 **Public** · Rate limit: **10 req / hour** · Captcha: **required**

Creates a new user account. Sends a verification email. Returns the new `userId` so the client can navigate to the email verification flow. Username is optional at registration; users can claim a username later.

<Callout type="info">
  This endpoint enforces the platform-wide kill switch `platform.registration_enabled` (admin-managed). When the switch is off, registration returns `403 Forbidden` with i18nKey `auth.register.closed`.
</Callout>

## Request [#request]

### Headers [#headers]

| Header             | Value              | Notes                                        |
| ------------------ | ------------------ | -------------------------------------------- |
| `Content-Type`     | `application/json` | Required                                     |
| `User-Agent`       | (auto)             | Captured into `User.registrationDevice`      |
| `Accept-Language`  | (auto)             | Used as fallback when `body.locale` is empty |
| `cf-connecting-ip` | (auto, Cloudflare) | Source for GeoIP `User.registrationCountry`  |

### Body — `RegisterDto` [#body--registerdto]

| Field                                                        | Type                 | Required | Validation                                                                                                                 | Notes                                                              |
| ------------------------------------------------------------ | -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `email`                                                      | string (RFC 5322)    | ✓        | Trimmed + lowercased; disposable domain blocked; MX record checked                                                         | Persisted to `User.email` (unique)                                 |
| `password`                                                   | string               | ✓        | 8–128 chars; must include upper + lower + digit                                                                            | bcrypt hashed (salt rounds from config `auth.salt_rounds`, min 10) |
| `acceptedTerms`                                              | boolean              | ✓        | Must equal `true`                                                                                                          | GDPR consent record written                                        |
| `acceptedPrivacy`                                            | boolean              | ✓        | Must equal `true`                                                                                                          | GDPR consent record written                                        |
| `username`                                                   | string               | —        | 1–100 chars, `^[a-z0-9._-]+$`                                                                                              | Unique across User + ReservedUsername                              |
| `displayName`                                                | string               | —        | max 100 chars                                                                                                              | UI display (separate from username)                                |
| `intent`                                                     | `'creator' \| 'fan'` | —        | max 20 chars                                                                                                               | Sets `User.intent`; null = undecided                               |
| `captchaToken`                                               | string               | —        | Validated by `CaptchaGuard` against the **active captcha provider** (admin-managed via `external.captcha.active_provider`) | Required when captcha is enabled                                   |
| `referralCode`                                               | string               | —        | Resolves against `User.referralCode` first, then `ReferralLink.code`                                                       | Sets `User.referredBy`                                             |
| `locale`                                                     | string               | —        | Must be in `platform.supported_locales`                                                                                    | Falls back to `Accept-Language` then platform default              |
| `utmSource` `utmMedium` `utmCampaign` `utmTerm` `utmContent` | string × 5           | —        | max 100 chars each                                                                                                         | Permanent attribution                                              |
| `firstReferrerUrl`                                           | string               | —        | max 2048 chars                                                                                                             | Permanent attribution                                              |
| `firstLandingPage`                                           | string               | —        | max 2048 chars                                                                                                             | Permanent attribution                                              |

<Callout type="warn">
  Field `turnstileToken` is **deprecated** — accepted as a backwards-compat alias for `captchaToken` for one sprint. Do not use in new code; the active provider is admin-selected via `external.captcha.active_provider`.
</Callout>

## Response [#response]

### `201 Created` — success [#201-created--success]

```json
{
  "success": true,
  "data": {
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message": "Registration successful. Please check your email to verify your account."
  }
}
```

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                         | Reason                                                                                        |
| ----- | ------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `400` | `auth.register.invalid_email`              | Disposable domain, invalid MX, or otherwise rejected by `EmailValidatorService`               |
| `400` | (DTO validation array)                     | `class-validator` failure (password policy, terms not accepted, etc.)                         |
| `403` | `auth.register.closed`                     | Platform kill switch `platform.registration_enabled = false`                                  |
| `409` | `auth.register.email_exists`               | Email already registered                                                                      |
| `409` | `auth.register.account_previously_deleted` | Email matches a GDPR-deleted tombstone (SHA-256 hash)                                         |
| `409` | `auth.register.username_unavailable`       | Username taken in `User` or `ReservedUsername`                                                |
| `409` | `auth.register.referral_code_collision`    | Generated referral code collided 3 times against `ReferralLink.code` (rare; client can retry) |
| `429` | (throttle)                                 | Rate limit exceeded (10 req/hour)                                                             |

All non-validation errors follow the platform error envelope:

```json
{ "success": false, "error": { "code": "auth.register.email_exists", "message": "Email already registered", "i18nKey": "auth.register.email_exists", "correlationId": "..." } }
```

## Side effects [#side-effects]

1. **Kill-switch check** — `platform.registration_enabled` (ConfigService).
2. **Email validation** — disposable domain + MX record check (`EmailValidatorService`).
3. **Email uniqueness** — Prisma `User.email` unique.
4. **GDPR tombstone check** — SHA-256 of email matched against `email = 'deleted_<hash>@deleted.bio.re'` and `status = DELETED`.
5. **Username uniqueness** — both `User.username` and `ReservedUsername.username`.
6. **Referral resolution** — `User.referralCode` first, fallback to `ReferralLink.code`.
7. **Password hashing** — bcrypt, configurable salt rounds (min 10).
8. **Atomic transaction** — `User` insert + `EmailVerification` insert + `ConsentRecord` (terms, privacy) insert.
9. **Cross-table referral code uniqueness** — generated code retried up to 3 times against `ReferralLink.code`.
10. **GeoIP lookup** — non-blocking; populates `User.registrationCountry`.
11. **Welcome / verification email** — queued to worker-service, dispatched via the **active email provider** (admin-managed via `external.email.active_provider`; failover handled server-side).

## Code samples [#code-samples]

<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/register \
      -H 'Content-Type: application/json' \
      -H 'Accept-Language: en' \
      -d '{
        "email": "creator@example.com",
        "username": "creator",
        "password": "SecureP@ss123",
        "acceptedTerms": true,
        "acceptedPrivacy": true,
        "displayName": "Awesome Creator",
        "intent": "creator",
        "captchaToken": "<turnstile_token>",
        "locale": "en"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type RegisterRequest = {
      email: string;
      password: string;
      acceptedTerms: true;
      acceptedPrivacy: true;
      username?: string;
      displayName?: string;
      intent?: 'creator' | 'fan';
      captchaToken?: string;
      referralCode?: string;
      locale?: string;
    };

    type RegisterResponse = { userId: string; message: string };

    async function register(input: RegisterRequest): Promise<RegisterResponse> {
      const res = await fetch('https://api.bio.re/api/v1/auth/register', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        const code = json?.error?.code ?? `http_${res.status}`;
        throw Object.assign(new Error(json?.error?.message ?? 'Register failed'), { code });
      }
      return json.data as RegisterResponse;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useRegister() {
      return useMutation({
        mutationFn: async (input: RegisterRequest) => {
          const res = await fetch('/api/v1/auth/register', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Register failed'), {
              code: json?.error?.code ?? `http_${res.status}`,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as RegisterResponse;
        },
        onSuccess: ({ userId }) => {
          // Navigate to email verification page
          router.push(`/auth/verify-email?userId=${userId}`);
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<Callout type="warn">
  **Staging only.** Production API requires admin-managed captcha tokens and is rate-limited. Set `NEXT_PUBLIC_OPENAPI_PROXY_URL` env var to a staging proxy if you want browser-side requests; otherwise use the playground for request shape inspection only.
</Callout>

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/register', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                 | Lines                             |
| -------------- | ---------------------------------------------------- | --------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/auth.controller.ts`  | `60–96`                           |
| DTO (request)  | `apps/api-core/src/modules/auth/dto/index.ts`        | `5–65` (`RegisterDto`)            |
| DTO (response) | `apps/api-core/src/modules/auth/dto/response.dto.ts` | `6–12` (`RegisterResponseDto`)    |
| Service        | `apps/api-core/src/modules/auth/auth.service.ts`     | `126` (`register()`, \~120 lines) |
| Prisma model   | `packages/prisma/prisma/schema.prisma`               | `24` (`User`)                     |


# Resend Phone OTP (/docs/auth/resend-otp)



`POST /api/v1/auth/resend-otp` — 🌐 **Public** · Rate limit: **10 req / hour**

Generates a fresh code for an existing `Challenge`, resets `attempts = 0`, increments `resendCount`, and dispatches a new SMS via the **active SMS provider** (admin-managed). Two server-side caps:

* `auth.otp_max_resends` — per-challenge resend ceiling.
* `auth.otp_resend_cooldown_seconds` — minimum seconds between resends.

## Request [#request]

### Body — `ResendOtpDto` [#body--resendotpdto]

| Field         | Type          | Required | Validation | Notes                             |
| ------------- | ------------- | -------- | ---------- | --------------------------------- |
| `challengeId` | string (UUID) | ✓        | `IsUUID()` | Returned by `POST /auth/send-otp` |

## Response [#response]

### `200 OK` — `ApiResponseOf<ChallengeDispatchResponseDto>` [#200-ok--apiresponseofchallengedispatchresponsedto]

```json
{
  "success": true,
  "data": {
    "challengeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "expiresAt": "2026-04-29T20:25:00.000Z",
    "attemptsRemaining": 5,
    "resendCount": 1
  }
}
```

Same shape as `/send-otp` but with `resendCount` populated.

| Field               | Type              | Notes                                        |
| ------------------- | ----------------- | -------------------------------------------- |
| `challengeId`       | string (UUID)     | Same id — Challenge row reused, code rotated |
| `expiresAt`         | string (ISO 8601) | New TTL window from now                      |
| `attemptsRemaining` | number            | Reset to `auth.otp_max_attempts`             |
| `resendCount`       | number            | Total dispatches so far for this Challenge   |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`            | Reason                                                  |
| ----- | ----------------------------- | ------------------------------------------------------- |
| `400` | `auth.otp.resend.cap_reached` | `Challenge.resendCount >= auth.otp_max_resends`         |
| `400` | `auth.otp.resend.cooldown`    | Last dispatch within `auth.otp_resend_cooldown_seconds` |
| `404` | `auth.otp.resend.not_found`   | `challengeId` does not exist                            |
| `429` | (throttle)                    | Rate limit exceeded (10 req/hour)                       |

## Side effects [#side-effects]

1. Lookup `Challenge` by `challengeId`; verify exists, not used, not expired.
2. Cap check: `Challenge.resendCount < auth.otp_max_resends` AND last dispatch ≥ `auth.otp_resend_cooldown_seconds` ago.
3. Generate fresh 6-digit code; bcrypt-hash; update `Challenge.codeHash`.
4. Reset `Challenge.attempts = 0`; increment `Challenge.resendCount`; refresh `expiresAt`.
5. Dispatch SMS via the **active SMS provider** (admin-managed via `external.sms.active_provider`).
6. Audit log: `auth.otp.resend.success` (with masked phone).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/resend-otp \
      -H 'Content-Type: application/json' \
      -d '{"challengeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function resendOtp(challengeId: string): Promise<ChallengeDispatch> {
      const res = await fetch('https://api.bio.re/api/v1/auth/resend-otp', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ challengeId }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Resend OTP failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useResendOtp() {
      return useMutation({
        mutationFn: async (challengeId: string) => {
          const res = await fetch('/api/v1/auth/resend-otp', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ challengeId }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Resend OTP failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as ChallengeDispatch;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/resend-otp', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                   | Lines                                                               |
| -------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/auth.controller.ts`    | `359–381` (`resendOtp`)                                             |
| DTO (request)  | `apps/api-core/src/modules/auth/dto/resend-otp.dto.ts` | `4–8` (`ResendOtpDto`)                                              |
| DTO (response) | `apps/api-core/src/modules/auth/dto/challenge.dto.ts`  | `7–22` (`ChallengeDispatchResponseDto`)                             |
| Service        | `apps/api-core/src/modules/auth/challenge.service.ts`  | `resendOtp()`                                                       |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                 | `Challenge.resendCount`, `Challenge.codeHash`, `Challenge.attempts` |


# Resend Verification Email (/docs/auth/resend-verification)



`POST /api/v1/auth/resend-verification` — 🌐 **Public** · Rate limit: **5 req / hour** · Captcha: **required**

Re-dispatches the verification email if an unverified account exists for the given address. Always returns success (does NOT leak whether the email is registered) — privacy-by-default.



<Callout type="warn">
  This endpoint always returns 200 even if the email is unknown — to prevent account enumeration. Client should display a generic "If the address is registered, a verification email has been sent." message.
</Callout>

## Request [#request]

### Body — `ResendVerificationDto` [#body--resendverificationdto]

| Field   | Type              | Required | Validation           | Notes                       |
| ------- | ----------------- | -------- | -------------------- | --------------------------- |
| `email` | string (RFC 5322) | ✓        | Trimmed + lowercased | Lookup against `User.email` |

## Response [#response]

### `200 OK` — `ApiResponseOf<MessageResponseDto>` [#200-ok--apiresponseofmessageresponsedto]

```json
{ "success": true, "data": { "message": "Verification email sent (if account exists)" } }
```

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                                                  |
| ----- | ------------------ | ------------------------------------------------------- |
| `429` | (throttle)         | Rate limit exceeded (5 req/hour — strict to deter spam) |

## Side effects [#side-effects]

1. Lookup `User` by email; **always returns success** even if not found (anti-enumeration).
2. If user exists + not verified: invalidate prior `EmailVerification` records, create new token, queue email job to `worker-service` — dispatched via the **active email provider** (admin-managed via `external.email.active_provider`; failover handled server-side).
3. Audit log: `auth.resend_verification.requested` (success regardless of account existence).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/resend-verification \
      -H 'Content-Type: application/json' \
      -d '{"email": "creator@example.com"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function resendVerification(email: string): Promise<{ message: string }> {
      const res = await fetch('https://api.bio.re/api/v1/auth/resend-verification', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Resend failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useResendVerification() {
      return useMutation({
        mutationFn: async (email: string) => {
          const res = await fetch('/api/v1/auth/resend-verification', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ email }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Resend failed'), {
              code: json?.error?.code,
            });
          }
          return json.data;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/resend-verification', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source        | Path                                                | Lines                             |
| ------------- | --------------------------------------------------- | --------------------------------- |
| Controller    | `apps/api-core/src/modules/auth/auth.controller.ts` | `108–117`                         |
| DTO (request) | `apps/api-core/src/modules/auth/dto/index.ts`       | `67–72` (`ResendVerificationDto`) |
| Service       | `apps/api-core/src/modules/auth/auth.service.ts`    | `resendVerification()`            |
| Prisma model  | `packages/prisma/prisma/schema.prisma`              | `User`, `EmailVerification`       |


# Reset Password (/docs/auth/reset-password)



`POST /api/v1/auth/reset-password` — 🌐 **Public** · Rate limit: **3 req / hour**

Completes the password reset flow. Validates the reset token from the email link, updates `User.passwordHash`, and revokes all existing sessions for the user (forces re-login).

## Request [#request]

### Body — `ResetPasswordDto` [#body--resetpassworddto]

| Field         | Type   | Required | Validation                                      | Notes                                               |
| ------------- | ------ | -------- | ----------------------------------------------- | --------------------------------------------------- |
| `token`       | string | ✓        | `@IsString()`                                   | Reset token from email link (`PasswordReset.token`) |
| `newPassword` | string | ✓        | 8–128 chars; must include upper + lower + digit | bcrypt hashed (salt rounds from `auth.salt_rounds`) |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{ "success": true }
```

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                  | Reason                                                                 |
| ----- | ----------------------------------- | ---------------------------------------------------------------------- |
| `400` | `auth.reset_password.invalid_token` | Token not found, expired, or already consumed                          |
| `400` | (DTO validation)                    | Password policy violation (length, character class)                    |
| `429` | (throttle)                          | Rate limit exceeded (3 req/hour — extra strict for password mutations) |

## Side effects [#side-effects]

1. Lookup `PasswordReset` by token; verify not expired + not used.
2. bcrypt hash new password (salt rounds from config).
3. Atomic transaction: update `User.passwordHash`, mark `PasswordReset.usedAt = now()`, **revoke ALL active `Session` records** (force re-login on every device).
4. Reset `User.loginAttempts = 0` and `User.lockedUntil = null` (account unlocked).
5. Send security alert email: "Your password was reset on `{date}`".
6. Audit log: `auth.reset_password.success`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/reset-password \
      -H 'Content-Type: application/json' \
      -d '{
        "token": "abc123-reset-token-from-email",
        "newPassword": "NewSecureP@ss456"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function resetPassword(token: string, newPassword: string): Promise<void> {
      const res = await fetch('https://api.bio.re/api/v1/auth/reset-password', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ token, newPassword }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Reset failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useResetPassword() {
      return useMutation({
        mutationFn: async (input: { token: string; newPassword: string }) => {
          const res = await fetch('/api/v1/auth/reset-password', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Reset failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          router.push('/login?reason=password_reset');
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/reset-password', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source        | Path                                                | Lines                              |
| ------------- | --------------------------------------------------- | ---------------------------------- |
| Controller    | `apps/api-core/src/modules/auth/auth.controller.ts` | `214–223`                          |
| DTO (request) | `apps/api-core/src/modules/auth/dto/index.ts`       | `115–121` (`ResetPasswordDto`)     |
| Service       | `apps/api-core/src/modules/auth/auth.service.ts`    | `resetPassword()`                  |
| Prisma models | `packages/prisma/prisma/schema.prisma`              | `User`, `PasswordReset`, `Session` |


# Send Phone OTP (/docs/auth/send-otp)



`POST /api/v1/auth/send-otp` — 🌐 **Public** · Rate limit: **3 req / 10 min**

Creates a `Challenge` record and dispatches a 6-digit code via SMS to the given phone number. Returns the `challengeId` that the client passes to `/verify-otp`, `/resend-otp`, and `/challenge/{id}`.



<Callout type="info">
  The SMS is sent via the **active SMS provider** (admin-managed via `external.sms.active_provider`; failover handled server-side). Vendor identity stays in admin — this endpoint guarantees delivery via whichever provider is active.
</Callout>

## Purposes (`OtpPurpose` enum) [#purposes-otppurpose-enum]

| Purpose                | Auth required | Notes                                            |
| ---------------------- | ------------- | ------------------------------------------------ |
| `verify-phone-fan`     | ❌ Public      | Signup flow — account not yet created            |
| `verify-phone-profile` | 🔑 Bearer     | Account settings → add or change phone           |
| `2fa-setup`            | 🔑 Bearer     | Enabling 2FA via SMS (paired with TOTP setup)    |
| `login-2fa`            | ❌ Public      | Uses `tempToken` from `/auth/login`, not session |

## Request [#request]

### Body — `SendOtpDto` [#body--sendotpdto]

| Field     | Type           | Required | Validation                              | Notes                                        |
| --------- | -------------- | -------- | --------------------------------------- | -------------------------------------------- |
| `phone`   | string (E.164) | ✓        | max 20 chars; regex `^\+[1-9]\d{7,14}$` | E.g., `+15551234567` — plus prefix mandatory |
| `purpose` | `OtpPurpose`   | ✓        | `IsEnum(OTP_PURPOSES)`                  | One of the four purposes above               |

## Response [#response]

### `200 OK` — `ApiResponseOf<ChallengeDispatchResponseDto>` [#200-ok--apiresponseofchallengedispatchresponsedto]

```json
{
  "success": true,
  "data": {
    "challengeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "expiresAt": "2026-04-29T20:15:00.000Z",
    "attemptsRemaining": 5
  }
}
```

| Field               | Type              | Notes                                                    |
| ------------------- | ----------------- | -------------------------------------------------------- |
| `challengeId`       | string (UUID)     | Pass to `/verify-otp`, `/resend-otp`, `/challenge/{id}`  |
| `expiresAt`         | string (ISO 8601) | TTL = `auth.otp_ttl_minutes` (admin-managed config)      |
| `attemptsRemaining` | number            | Initial = `auth.otp_max_attempts` (admin-managed config) |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`         | Reason                                                             |
| ----- | -------------------------- | ------------------------------------------------------------------ |
| `400` | `auth.otp.send.rate_limit` | Per-phone rate limit exhausted (`auth.otp_per_phone_max_per_hour`) |
| `400` | (DTO validation)           | Phone not E.164, or invalid purpose enum                           |
| `429` | (throttle)                 | Endpoint rate limit exceeded (3 req / 10 min)                      |

## Side effects [#side-effects]

1. **Per-phone rate-limit check** — config-driven (`auth.otp_per_phone_max_per_hour`).
2. Generate 6-digit code; bcrypt-hash it (`Challenge.codeHash`).
3. Insert `Challenge` row with `purpose`, `phone`, `codeHash`, `expiresAt`, `attempts = 0`, `resendCount = 0`.
4. Dispatch SMS to phone via the **active SMS provider** (admin-managed via `external.sms.active_provider`). Failover is handled server-side.
5. Audit log: `auth.otp.sent` (with masked phone — last 4 digits only).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/send-otp \
      -H 'Content-Type: application/json' \
      -d '{
        "phone": "+15551234567",
        "purpose": "verify-phone-fan"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type OtpPurpose = 'verify-phone-fan' | 'verify-phone-profile' | '2fa-setup' | 'login-2fa';

    type ChallengeDispatch = {
      challengeId: string;
      expiresAt: string;
      attemptsRemaining: number;
      resendCount?: number;
    };

    async function sendOtp(phone: string, purpose: OtpPurpose): Promise<ChallengeDispatch> {
      const res = await fetch('https://api.bio.re/api/v1/auth/send-otp', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ phone, purpose }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Send OTP failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useSendOtp() {
      return useMutation({
        mutationFn: async (input: { phone: string; purpose: OtpPurpose }) => {
          const res = await fetch('/api/v1/auth/send-otp', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Send OTP failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as ChallengeDispatch;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/send-otp', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                  | Lines                                            |
| -------------- | ----------------------------------------------------- | ------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/auth/auth.controller.ts`   | `315–339` (`sendOtp`)                            |
| DTO (request)  | `apps/api-core/src/modules/auth/dto/send-otp.dto.ts`  | `15–25` (`SendOtpDto`), `11–12` (`OTP_PURPOSES`) |
| DTO (response) | `apps/api-core/src/modules/auth/dto/challenge.dto.ts` | `7–22` (`ChallengeDispatchResponseDto`)          |
| Service        | `apps/api-core/src/modules/auth/challenge.service.ts` | `sendOtp()`                                      |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                | `Challenge`                                      |


# Revoke Single Session (/docs/auth/session-revoke)



`DELETE /api/v1/auth/sessions/{id}` — 🔑 **User-auth** (Bearer JWT) · Rate limit: **20 req / hour**

Revokes a specific session. The user's other devices using that session lose access immediately (their refresh tokens are killed; access tokens expire within 15 min). Cannot revoke the **current** session — that requires `/auth/logout`.



<Callout type="warn">
  Attempting to revoke the session that owns the requesting refresh token returns `400 cannot_revoke_current_session`. Use `/auth/logout` instead — semantic separation.
</Callout>

## Request [#request]

### Headers [#headers]

| Header                      | Value                  | Notes                                  |
| --------------------------- | ---------------------- | -------------------------------------- |
| `Authorization`             | `Bearer <accessToken>` | Required                               |
| `Cookie: biore_refresh=...` | (auto)                 | Used to detect "current session" guard |

### Path parameters [#path-parameters]

| Param | Type          | Validation      | Notes                                |
| ----- | ------------- | --------------- | ------------------------------------ |
| `id`  | string (UUID) | `ParseUUIDPipe` | Session ID from `GET /auth/sessions` |

No body, no query.

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{ "success": true }
```

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                    | Reason                                                                           |
| ----- | ------------------------------------- | -------------------------------------------------------------------------------- |
| `400` | `auth.sessions.cannot_revoke_current` | The session ID matches the requesting refresh token — use `/auth/logout` instead |
| `400` | (UUID validation)                     | `id` is not a valid UUID                                                         |
| `401` | (no JWT or invalid)                   | Not authenticated                                                                |
| `404` | `auth.sessions.not_found`             | Session does not exist OR does not belong to current user                        |
| `429` | (throttle)                            | Rate limit exceeded (20 req/hour)                                                |

## Side effects [#side-effects]

1. Look up `Session` by `id`; verify `Session.userId` matches the authenticated user.
2. Verify session ID is NOT the current refresh token's session (anti-foot-shoot).
3. Mark `Session.revokedAt = now()`.
4. Audit log: `auth.sessions.revoke.success`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X DELETE https://api.bio.re/api/v1/auth/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
      -H 'Authorization: Bearer <accessToken>' \
      -b cookies.txt
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function revokeSession(sessionId: string, accessToken: string): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/auth/sessions/${sessionId}`, {
        method: 'DELETE',
        headers: { 'Authorization': `Bearer ${accessToken}` },
        credentials: 'include',
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Revoke failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';
    import { sessionKeys } from './use-sessions';

    export function useRevokeSession() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (sessionId: string) => {
          const res = await fetch(`/api/v1/auth/sessions/${sessionId}`, {
            method: 'DELETE',
            credentials: 'include',
            headers: { 'Authorization': `Bearer ${getAccessToken()}` },
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Revoke failed'), {
              code: json?.error?.code,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: sessionKeys.all });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/sessions/{id}', method: 'delete' }]" hasHead="false" />

## Source [#source]

| Source       | Path                                                | Lines                       |
| ------------ | --------------------------------------------------- | --------------------------- |
| Controller   | `apps/api-core/src/modules/auth/auth.controller.ts` | `260–280` (`revokeSession`) |
| Service      | `apps/api-core/src/modules/auth/auth.service.ts`    | `revokeSession()`           |
| Prisma model | `packages/prisma/prisma/schema.prisma`              | `Session.revokedAt`         |


# Revoke All Other Sessions (/docs/auth/sessions-revoke-all)



`POST /api/v1/auth/sessions/revoke-all` — 🔑 **User-auth** (Bearer JWT) · Rate limit: **5 req / hour**

Revokes all sessions for the authenticated user **EXCEPT the current one**. Pair with `GET /auth/sessions` to power "Sign out all other devices" buttons in account settings.



<Callout type="info">
  The current session (the one matching the requesting `biore_refresh` cookie) stays alive. Other devices' refresh tokens become invalid immediately; their access tokens expire within \~15 min.
</Callout>

## Request [#request]

### Headers [#headers]

| Header                      | Value                  | Notes                                             |
| --------------------------- | ---------------------- | ------------------------------------------------- |
| `Authorization`             | `Bearer <accessToken>` | Required                                          |
| `Cookie: biore_refresh=...` | (auto)                 | Used to identify the current session (kept alive) |

No body, no path/query params.

## Response [#response]

### `200 OK` — empty body [#200-ok--empty-body]

```json
{ "success": true }
```

### Errors [#errors]

| HTTP  | `code` / `i18nKey`  | Reason                                                                  |
| ----- | ------------------- | ----------------------------------------------------------------------- |
| `401` | (no JWT or invalid) | Not authenticated                                                       |
| `429` | (throttle)          | Rate limit exceeded (5 req/hour — strict; this is a destructive action) |

## Side effects [#side-effects]

1. Hash the current refresh token (SHA-256) → match against `Session.refreshTokenHash` to identify the current session.
2. Update all `Session` rows where `userId = current user` AND `id != current session id` AND `revokedAt IS NULL`: set `revokedAt = now()`.
3. Audit log: `auth.sessions.revoke_all.success` (with count of sessions revoked).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/sessions/revoke-all \
      -H 'Authorization: Bearer <accessToken>' \
      -b cookies.txt
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function revokeAllSessions(accessToken: string): Promise<void> {
      const res = await fetch('https://api.bio.re/api/v1/auth/sessions/revoke-all', {
        method: 'POST',
        headers: { 'Authorization': `Bearer ${accessToken}` },
        credentials: 'include',
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Revoke-all failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';
    import { sessionKeys } from './use-sessions';

    export function useRevokeAllSessions() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/auth/sessions/revoke-all', {
            method: 'POST',
            credentials: 'include',
            headers: { 'Authorization': `Bearer ${getAccessToken()}` },
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Revoke-all failed'), {
              code: json?.error?.code,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: sessionKeys.all });
          toast.success(t('auth.sessions.revoke_all.success'));
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/sessions/revoke-all', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source       | Path                                                | Lines                                           |
| ------------ | --------------------------------------------------- | ----------------------------------------------- |
| Controller   | `apps/api-core/src/modules/auth/auth.controller.ts` | `282–298` (`revokeAllSessions`)                 |
| Service      | `apps/api-core/src/modules/auth/auth.service.ts`    | `revokeAllSessions()`                           |
| Prisma model | `packages/prisma/prisma/schema.prisma`              | `Session.refreshTokenHash`, `Session.revokedAt` |


# List Active Sessions (/docs/auth/sessions)



`GET /api/v1/auth/sessions` — 🔑 **User-auth** (Bearer JWT) · Rate limit: **30 req / hour**

Returns the current user's active session list. Each entry includes the device (parsed User-Agent), masked IP, last-active timestamp, and an `isCurrent` flag indicating which session matches the requesting refresh token.



<Callout type="info">
  Use this endpoint to power "Active sessions" UI in account settings. Combine with `DELETE /auth/sessions/{id}` (revoke one) and `POST /auth/sessions/revoke-all` (revoke all except current).
</Callout>

## Request [#request]

### Headers [#headers]

| Header                      | Value                  | Notes                              |
| --------------------------- | ---------------------- | ---------------------------------- |
| `Authorization`             | `Bearer <accessToken>` | Required                           |
| `Cookie: biore_refresh=...` | (auto)                 | Used to determine `isCurrent` flag |

No body, no query params.

## Response [#response]

### `200 OK` — `ApiResponseOf<SessionListResponseDto>` [#200-ok--apiresponseofsessionlistresponsedto]

```json
{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "device": "Chrome on macOS",
        "ipMasked": "192.168.1.***",
        "location": null,
        "isCurrent": true,
        "createdAt": "2026-04-20T10:30:00.000Z",
        "lastActiveAt": "2026-04-29T18:45:23.000Z"
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
        "device": "Safari on iOS",
        "ipMasked": "10.0.0.***",
        "location": null,
        "isCurrent": false,
        "createdAt": "2026-04-15T08:00:00.000Z",
        "lastActiveAt": "2026-04-28T12:15:00.000Z"
      }
    ]
  }
}
```

### `SessionItemDto` fields [#sessionitemdto-fields]

| Field          | Type              | Notes                                                            |
| -------------- | ----------------- | ---------------------------------------------------------------- |
| `id`           | string (UUID)     | Session ID — pass to `DELETE /auth/sessions/{id}` to revoke      |
| `device`       | string \| null    | Parsed from `Session.userAgent` (e.g., "Chrome on macOS")        |
| `ipMasked`     | string \| null    | IP with last octet masked (`192.168.1.***`)                      |
| `location`     | string \| null    | Reserved for future GeoIP integration (currently `null`)         |
| `isCurrent`    | boolean           | `true` for the session that matches the requesting refresh token |
| `createdAt`    | string (ISO 8601) | When the session was created (login time)                        |
| `lastActiveAt` | string (ISO 8601) | Last refresh or API call timestamp                               |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`  | Reason                            |
| ----- | ------------------- | --------------------------------- |
| `401` | (no JWT or invalid) | Not authenticated                 |
| `429` | (throttle)          | Rate limit exceeded (30 req/hour) |

## Side effects [#side-effects]

1. Read all `Session` rows for `userId` where `revokedAt = null` and `expiresAt > now()`.
2. Hash the requesting refresh token from cookie → match against `Session.refreshTokenHash` to determine `isCurrent`.
3. Mask IPs (last octet) before serialization.
4. No mutations.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X GET https://api.bio.re/api/v1/auth/sessions \
      -H 'Authorization: Bearer <accessToken>' \
      -b cookies.txt
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type Session = {
      id: string;
      device: string | null;
      ipMasked: string | null;
      location: string | null;
      isCurrent: boolean;
      createdAt: string;
      lastActiveAt: string;
    };

    async function getSessions(accessToken: string): Promise<{ sessions: Session[] }> {
      const res = await fetch('https://api.bio.re/api/v1/auth/sessions', {
        headers: { 'Authorization': `Bearer ${accessToken}` },
        credentials: 'include',
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const sessionKeys = {
      all: ['auth', 'sessions'] as const,
    };

    export function useSessions() {
      return useQuery({
        queryKey: sessionKeys.all,
        queryFn: async () => {
          const res = await fetch('/api/v1/auth/sessions', {
            credentials: 'include',
            headers: { 'Authorization': `Bearer ${getAccessToken()}` },
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Failed'), {
              code: json?.error?.code,
            });
          }
          return json.data as { sessions: Session[] };
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/sessions', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                 | Lines                                                             |
| -------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/auth.controller.ts`  | `244–278` (`getSessions`)                                         |
| DTO (response) | `apps/api-core/src/modules/auth/dto/response.dto.ts` | `85–106` (`SessionItemDto`), `108–111` (`SessionListResponseDto`) |
| Service        | `apps/api-core/src/modules/auth/auth.service.ts`     | `getSessions()`                                                   |
| Prisma model   | `packages/prisma/prisma/schema.prisma`               | `Session`                                                         |


# Verify Email (/docs/auth/verify-email)



`POST /api/v1/auth/verify-email` — 🌐 **Public** · Rate limit: **20 req / hour**

Verifies the user's email using the UUID token sent during registration. On success the `User.emailVerified` flag flips to `true`. Idempotent — re-verifying an already-verified token returns the same success response.

## Request [#request]

### Body — `VerifyEmailDto` [#body--verifyemaildto]

| Field   | Type             | Required | Validation  | Notes                                                               |
| ------- | ---------------- | -------- | ----------- | ------------------------------------------------------------------- |
| `token` | string (UUID v4) | ✓        | `@IsUUID()` | Token sent via `EmailVerification.token` from the registration flow |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{ "success": true }
```

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                | Reason                                        |
| ----- | --------------------------------- | --------------------------------------------- |
| `400` | `auth.verify_email.invalid_token` | Token not found, expired, or already consumed |
| `400` | (DTO validation)                  | Token is not a valid UUID                     |
| `429` | (throttle)                        | Rate limit exceeded (20 req/hour)             |

## Side effects [#side-effects]

1. Look up `EmailVerification` by `token` (Prisma).
2. If valid + unexpired: set `User.emailVerified = true`, `EmailVerification.usedAt = now()` in atomic transaction.
3. Audit log entry (`auth.verify_email.success`).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/verify-email \
      -H 'Content-Type: application/json' \
      -d '{"token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function verifyEmail(token: string): Promise<void> {
      const res = await fetch('https://api.bio.re/api/v1/auth/verify-email', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ token }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Verification failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useVerifyEmail() {
      return useMutation({
        mutationFn: async (token: string) => {
          const res = await fetch('/api/v1/auth/verify-email', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ token }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Verification failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/verify-email', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source        | Path                                                | Lines                                     |
| ------------- | --------------------------------------------------- | ----------------------------------------- |
| Controller    | `apps/api-core/src/modules/auth/auth.controller.ts` | `98–106`                                  |
| DTO (request) | `apps/api-core/src/modules/auth/dto/index.ts`       | `92–96` (`VerifyEmailDto`)                |
| Service       | `apps/api-core/src/modules/auth/auth.service.ts`    | `verifyEmail()`                           |
| Prisma model  | `packages/prisma/prisma/schema.prisma`              | `EmailVerification`, `User.emailVerified` |


# Verify Phone OTP (/docs/auth/verify-otp)



`POST /api/v1/auth/verify-otp` — 🌐 **Public** · Rate limit: **20 req / hour**

Verifies the 6-digit code against `Challenge.codeHash` (bcrypt). On success, the `Challenge` is marked as used (`Challenge.usedAt = now()`). The calling flow consumes the verified Challenge to gate its own state change (e.g., flip `User.phoneVerified = true`).



<Callout type="info">
  The response shape includes optional `accessToken` + `expiresIn` fields **reserved for a future SMS-OTP login bridge**. They are currently always absent — for the login 2FA path, continue using `POST /auth/login/2fa` with TOTP / backup codes.
</Callout>

## Request [#request]

### Body — `VerifyOtpDto` [#body--verifyotpdto]

| Field         | Type          | Required | Validation                       | Notes                             |
| ------------- | ------------- | -------- | -------------------------------- | --------------------------------- |
| `challengeId` | string (UUID) | ✓        | `IsUUID()`                       | Returned by `POST /auth/send-otp` |
| `code`        | string        | ✓        | exactly 6 chars; regex `^\d{6}$` | Numeric OTP from SMS              |

## Response [#response]

### `200 OK` — `ApiResponseOf<VerifyOtpResponseDto>` [#200-ok--apiresponseofverifyotpresponsedto]

```json
{
  "success": true,
  "data": {
    "success": true
  }
}
```

| Field         | Type                | Notes                                                                                        |
| ------------- | ------------------- | -------------------------------------------------------------------------------------------- |
| `success`     | boolean             | Always `true` on 200                                                                         |
| `accessToken` | string \| undefined | **Reserved** — currently always undefined. Will carry a JWT once SMS-OTP login bridge ships. |
| `expiresIn`   | number \| undefined | **Reserved** — mirrors `/auth/login.expiresIn` semantics when present                        |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                   | Reason                                        |
| ----- | ------------------------------------ | --------------------------------------------- |
| `401` | `auth.otp.verify.invalid`            | Code mismatch — `Challenge.attempts++`        |
| `401` | `auth.otp.verify.expired`            | `Challenge.expiresAt` is past                 |
| `401` | `auth.otp.verify.attempts_exhausted` | `Challenge.attempts >= auth.otp_max_attempts` |
| `401` | `auth.otp.verify.already_used`       | `Challenge.usedAt != null` (single-use)       |
| `429` | (throttle)                           | Rate limit exceeded (20 req/hour)             |

## Side effects [#side-effects]

1. Lookup `Challenge` by `challengeId`; verify `expiresAt > now()` AND `usedAt = null` AND `attempts < auth.otp_max_attempts`.
2. bcrypt-compare submitted `code` against `Challenge.codeHash`.
3. On success: set `Challenge.usedAt = now()` (single-use lock).
4. On failure: increment `Challenge.attempts`. If cap reached, all further attempts return `attempts_exhausted`.
5. Audit log: `auth.otp.verify.success` or `auth.otp.verify.failure`.
6. **Calling flow consumes the verified Challenge** to make its state change (e.g., `verify-phone-fan` → set `User.phoneVerified = true` in the next call). This endpoint does NOT make user-facing mutations beyond the Challenge row.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/auth/verify-otp \
      -H 'Content-Type: application/json' \
      -d '{
        "challengeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "code": "123456"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type VerifyOtpResponse = {
      success: boolean;
      accessToken?: string;
      expiresIn?: number;
    };

    async function verifyOtp(challengeId: string, code: string): Promise<VerifyOtpResponse> {
      const res = await fetch('https://api.bio.re/api/v1/auth/verify-otp', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ challengeId, code }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Verify OTP failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useVerifyOtp() {
      return useMutation({
        mutationFn: async (input: { challengeId: string; code: string }) => {
          const res = await fetch('/api/v1/auth/verify-otp', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Verify OTP failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as VerifyOtpResponse;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/auth/verify-otp', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                   | Lines                                                          |
| -------------- | ------------------------------------------------------ | -------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/auth/auth.controller.ts`    | `341–357` (`verifyOtp`)                                        |
| DTO (request)  | `apps/api-core/src/modules/auth/dto/verify-otp.dto.ts` | `4–14` (`VerifyOtpDto`)                                        |
| DTO (response) | `apps/api-core/src/modules/auth/dto/challenge.dto.ts`  | `60–80` (`VerifyOtpResponseDto`)                               |
| Service        | `apps/api-core/src/modules/auth/challenge.service.ts`  | `verifyOtp()`                                                  |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                 | `Challenge.codeHash`, `Challenge.attempts`, `Challenge.usedAt` |


# Submit Appeal (/docs/user/appeals)



`POST /api/v1/users/appeals` — 🔑 **Bearer** · Rate limit: **3 req / day**

Submits an appeal against a moderation action. Calls into the **trust-safety** module (not the user service) to create an `Appeal` row with `status = PENDING`. The endpoint is decorated `@BypassBanCheck()` so banned / suspended users can reach it — that's the whole reason it exists on the user-facing path.



<Callout type="info">
  **`@BypassBanCheck` is a deliberate exception.** Most user-facing endpoints reject banned/suspended accounts via `BanCheckGuard`. This endpoint is whitelisted because the platform must give blocked users a way to appeal — refusing that would be procedurally unfair.
</Callout>

<Callout type="warn">
  **Only one pending appeal at a time.** If an `Appeal` already exists with `status IN (PENDING, UNDER_REVIEW)`, the call is rejected with `400 error.trust_safety.appeal_already_pending`. Wait for moderation to resolve the open one (or hit the 3/day limit) before filing another.
</Callout>

## Request [#request]

### Body — `SubmitAppealDto` [#body--submitappealdto]

| Field      | Type          | Required | Validation                                                     | Notes                                                          |
| ---------- | ------------- | -------- | -------------------------------------------------------------- | -------------------------------------------------------------- |
| `type`     | string        | ✓        | `IsIn(['ban','fraud_flag','content_removal','report_action'])` | Which moderation decision is being contested                   |
| `reason`   | string        | ✓        | `MaxLength(5000)`                                              | Free-form explanation — surface to the moderator review queue  |
| `banId`    | string (UUID) | optional | `IsUUID()`                                                     | The `Ban` row being appealed (recommended when `type = 'ban'`) |
| `evidence` | string        | optional | `MaxLength(5000)`                                              | Supporting evidence / additional context                       |

| Header                                | Required | Notes                                                                                                    |
| ------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login`. The endpoint accepts the JWT even if the account is `BANNED` / `SUSPENDED`. |

## Response [#response]

### `201 Created` — `ApiResponseOf<AppealSubmittedDto>` [#201-created--apiresponseofappealsubmitteddto]

```json
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "PENDING",
    "createdAt": "2026-04-29T20:00:00.000Z"
  }
}
```

| Field       | Type              | Notes                                                                                                   |
| ----------- | ----------------- | ------------------------------------------------------------------------------------------------------- |
| `id`        | string (UUID)     | `Appeal.id`                                                                                             |
| `status`    | enum              | One of `PENDING` / `REVIEWING` / `RESOLVED` / `DISMISSED`. Always `PENDING` immediately after creation. |
| `createdAt` | string (ISO 8601) | Server-side timestamp                                                                                   |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                          | Reason                                                                            |
| ----- | ------------------------------------------- | --------------------------------------------------------------------------------- |
| `400` | (DTO validation)                            | Invalid `type` enum, fields exceeding 5000 chars, malformed `banId` UUID          |
| `400` | `error.trust_safety.appeal_already_pending` | An `Appeal` with `status IN (PENDING, UNDER_REVIEW)` already exists for this user |
| `401` | (guard)                                     | Missing / invalid bearer token                                                    |
| `429` | (throttle)                                  | Rate limit exceeded (3 req/day)                                                   |

## Side effects [#side-effects]

1. **No ban-check** — `@BypassBanCheck` skips the gate that normally blocks banned/suspended users.
2. Look for existing `Appeal { userId, status IN (PENDING, UNDER_REVIEW) }`. If found → `appeal_already_pending`.
3. `prisma.appeal.create({ data: { id: randomUUID(), userId, type, reason, banId: banId ?? null, evidence: evidence ?? null } })`.
4. Surfaces in the moderation review queue — operator response is out-of-band (notification when status flips).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/users/appeals \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "type": "ban",
        "reason": "I believe my ban was issued in error.",
        "banId": "b1a2n3i4-d5f6-7890-abcd-ef1234567890",
        "evidence": "Logs from the disputed session."
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type AppealType = 'ban' | 'fraud_flag' | 'content_removal' | 'report_action';

    type SubmitAppealInput = {
      type: AppealType;
      reason: string;
      banId?: string;
      evidence?: string;
    };

    type AppealSubmitted = {
      id: string;
      status: 'PENDING' | 'REVIEWING' | 'RESOLVED' | 'DISMISSED';
      createdAt: string;
    };

    async function submitAppeal(accessToken: string, input: SubmitAppealInput): Promise<AppealSubmitted> {
      const res = await fetch('https://api.bio.re/api/v1/users/appeals', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Appeal submission failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useSubmitAppeal() {
      return useMutation({
        mutationFn: async (input: SubmitAppealInput) => {
          const res = await fetch('/api/v1/users/appeals', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Appeal submission failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as AppealSubmitted;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/appeals', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                                | Lines                                      |
| -------------- | ------------------------------------------------------------------- | ------------------------------------------ |
| Controller     | `apps/api-core/src/modules/user/user.controller.ts`                 | `273–282` (`submitAppeal`)                 |
| DTO (request)  | `apps/api-core/src/modules/trust-safety/dto/submit-appeal.dto.ts`   | `4–17` (`SubmitAppealDto`)                 |
| DTO (response) | `apps/api-core/src/modules/user/dto/user-client-response.dto.ts`    | `274–283` (`AppealSubmittedDto`)           |
| Service        | `apps/api-core/src/modules/trust-safety/trust-safety.service.ts`    | `1282–1303` (`submitAppeal`)               |
| Decorator      | `apps/api-core/src/common/decorators/bypass-ban-check.decorator.ts` | `BypassBanCheck()` (skips `BanCheckGuard`) |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                              | `Appeal`, `AppealStatus`, `Ban`            |


# Get Attribution (/docs/user/attribution)



`GET /api/v1/users/attribution` — 🔑 **Bearer**

Returns the attribution snapshot captured **at registration time**. All fields are read-only after signup — there is no patch endpoint. Useful for analytics views, support tooling, and creator-attribution flows.



<Callout type="info">
  The same fields are also embedded in `GET /users/profile`. This endpoint exists for consumers who want only the attribution slice without paying the cost of fetching the full profile (and the social-accounts join).
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<UserAttributionDto>` [#200-ok--apiresponseofuserattributiondto]

```json
{
  "success": true,
  "data": {
    "referredBy": "c1d2e3f4-a5b6-7890-1234-56789abcdef0",
    "referralCode": "REF123",
    "firstReferrerUrl": "https://example.com/ref",
    "firstLandingPage": "/landing",
    "acquiredViaCreatorId": "d2e3f4a5-b6c7-8901-2345-6789abcdef01",
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "spring_promo",
    "utmTerm": "creator-tools",
    "utmContent": "banner-top",
    "registrationDevice": "mobile",
    "registrationCountry": "TR",
    "createdAt": "2025-12-01T08:30:00.000Z"
  }
}
```

| Field                                                                | Type                  | Notes                                                                               |
| -------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------- |
| `referredBy`                                                         | string (UUID) \| null | The user id of whoever referred this account                                        |
| `referralCode`                                                       | string \| null        | The referral code that was used at signup (e.g. another user's `User.referralCode`) |
| `firstReferrerUrl`                                                   | string \| null        | The HTTP `Referer` captured on the first landing                                    |
| `firstLandingPage`                                                   | string \| null        | Path of the first page hit (e.g. `/landing`, `/creators/alice`)                     |
| `acquiredViaCreatorId`                                               | string (UUID) \| null | If the user signed up through a creator's profile / link, the creator's id          |
| `utmSource` / `utmMedium` / `utmCampaign` / `utmTerm` / `utmContent` | string \| null        | UTM query params captured at first landing                                          |
| `registrationDevice`                                                 | string \| null        | Device classification (e.g. `mobile`, `desktop`, `tablet`)                          |
| `registrationCountry`                                                | string \| null        | ISO country code from the IP geo-lookup at signup time                              |
| `createdAt`                                                          | string (ISO 8601)     | When the user record was created — also when this snapshot was captured             |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`     | Reason                             |
| ----- | ---------------------- | ---------------------------------- |
| `401` | (guard)                | Missing / invalid bearer token     |
| `404` | `error.user.not_found` | Token decoded but user row missing |

## Side effects [#side-effects]

1. `prisma.user.findUnique({ where: { id: userId }, select: { ...all 13 attribution fields } })`.
2. Throw `not_found` if missing.
3. Return the row. No mutations — attribution is **immutable** post-signup; mutating it would break analytics retention.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/users/attribution \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type UserAttribution = {
      referredBy: string | null;
      referralCode: string | null;
      firstReferrerUrl: string | null;
      firstLandingPage: string | null;
      acquiredViaCreatorId: string | null;
      utmSource: string | null;
      utmMedium: string | null;
      utmCampaign: string | null;
      utmTerm: string | null;
      utmContent: string | null;
      registrationDevice: string | null;
      registrationCountry: string | null;
      createdAt: string;
    };

    async function getAttribution(accessToken: string): Promise<UserAttribution> {
      const res = await fetch('https://api.bio.re/api/v1/users/attribution', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Attribution fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const userKeys = {
      attribution: () => ['users', 'attribution'] as const,
    };

    export function useAttribution() {
      return useQuery({
        queryKey: userKeys.attribution(),
        queryFn: async () => {
          const res = await fetch('/api/v1/users/attribution');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Attribution fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as UserAttribution;
        },
        // Attribution never changes after signup — cache aggressively
        staleTime: Infinity,
        gcTime: 60 * 60_000, // 1 hour
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/attribution', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                             | Lines                                                                                                                                                                                     |
| -------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/user/user.controller.ts`              | `318–325` (`getAttribution`)                                                                                                                                                              |
| DTO (response) | `apps/api-core/src/modules/user/dto/user-client-response.dto.ts` | `231–270` (`UserAttributionDto`)                                                                                                                                                          |
| Service        | `apps/api-core/src/modules/user/user.service.ts`                 | `818–839` (`getAttribution`)                                                                                                                                                              |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                           | `User.referredBy`, `User.referralCode`, `User.firstReferrerUrl`, `User.firstLandingPage`, `User.acquiredViaCreatorId`, `User.utm*`, `User.registrationDevice`, `User.registrationCountry` |


# Remove Avatar (/docs/user/avatar-remove)



`POST /api/v1/users/avatar/remove` — 🔑 **Bearer**

Sets `User.avatarUrl = null` and **deletes the avatar file from object storage** in the background (fire-and-forget). Idempotent — calling it on a user with no avatar succeeds with no side effect on storage.



<Callout type="info">
  This is `POST` (not `DELETE`) because some clients / proxies strip bodies on `DELETE`. Treat it as the canonical "remove" verb for avatars.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                |
| --------- | ------- | -------------------- |
| `success` | boolean | Always `true` on 200 |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                         |
| ----- | ------------------ | ------------------------------ |
| `401` | (guard)            | Missing / invalid bearer token |

## Side effects [#side-effects]

1. Read current `User.avatarUrl` (to remember which file to delete).
2. `prisma.user.update({ avatarUrl: null })`.
3. **Fire-and-forget**: extract object-storage key from the previous URL and delete the file. Failures are logged, not surfaced.
4. If `avatarUrl` was already `null`, no storage call is made — DB write is still issued (idempotent set).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/users/avatar/remove \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function removeAvatar(accessToken: string): Promise<void> {
      const res = await fetch('https://api.bio.re/api/v1/users/avatar/remove', {
        method: 'POST',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Remove avatar failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useRemoveAvatar() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/users/avatar/remove', { method: 'POST' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Remove avatar failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['users', 'profile'] });
          qc.invalidateQueries({ queryKey: ['auth', 'me'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/avatar/remove', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source                 | Path                                                  | Lines                                 |
| ---------------------- | ----------------------------------------------------- | ------------------------------------- |
| Controller             | `apps/api-core/src/modules/user/user.controller.ts`   | `81–88` (`removeAvatar`)              |
| DTO (response)         | `apps/api-core/src/common/dto/common-response.dto.ts` | `SuccessOnlyResponseDto`              |
| Service                | `apps/api-core/src/modules/user/user.service.ts`      | `114–135` (`removeAvatar`)            |
| Object storage cleanup | `apps/api-core/src/modules/upload/upload.service.ts`  | `extractKeyFromUrl()`, `deleteFile()` |
| Prisma model           | `packages/prisma/prisma/schema.prisma`                | `User.avatarUrl`                      |


# Set Avatar (/docs/user/avatar-set)



`PATCH /api/v1/users/avatar` — 🔑 **Bearer**

Persists a new avatar URL on `User.avatarUrl` and **deletes the previous file from object storage** in the background (fire-and-forget, no error surfaced if the old file is already gone).



<Callout type="info">
  This endpoint does not upload — it only persists the URL after upload. To upload the image bytes, use the upload module first to get a CDN URL, then send that URL here. The cleanup of the previous file is the reason to prefer this over `PATCH /users/profile { avatarUrl }`.
</Callout>

<Callout type="warn">
  The previous file deletion happens **after** the response is returned. If the old file is referenced elsewhere (e.g., cached in another row), reflect that before calling this endpoint.
</Callout>

## Request [#request]

### Body — `SetAvatarDto` [#body--setavatardto]

| Field       | Type         | Required | Validation                   | Notes                         |
| ----------- | ------------ | -------- | ---------------------------- | ----------------------------- |
| `avatarUrl` | string (URL) | ✓        | `IsUrl()`, `MaxLength(2048)` | CDN URL of the uploaded image |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<AvatarUrlResponseDto>` [#200-ok--apiresponseofavatarurlresponsedto]

```json
{
  "success": true,
  "data": {
    "avatarUrl": "https://cdn.bio.re/avatars/user/uuid.webp"
  }
}
```

| Field       | Type   | Notes                                                          |
| ----------- | ------ | -------------------------------------------------------------- |
| `avatarUrl` | string | Echoed back — same URL you sent (server does not transform it) |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                                                |
| ----- | ------------------ | ----------------------------------------------------- |
| `400` | (DTO validation)   | `avatarUrl` not a valid URL OR longer than 2048 chars |
| `401` | (guard)            | Missing / invalid bearer token                        |

## Side effects [#side-effects]

1. Read current `User.avatarUrl` (to remember which file to delete).
2. `prisma.user.update({ avatarUrl })`.
3. **Fire-and-forget**: extract object-storage key from the old URL and delete it via the upload service. Failures are logged, not surfaced to the caller (so a stale orphan never breaks the avatar update path).
4. Audit log: `[avatar] Updated for user {userId}`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X PATCH https://api.bio.re/api/v1/users/avatar \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"avatarUrl": "https://cdn.bio.re/avatars/user/abc.webp"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type AvatarUrlResponse = { avatarUrl: string };

    async function setAvatar(accessToken: string, avatarUrl: string): Promise<AvatarUrlResponse> {
      const res = await fetch('https://api.bio.re/api/v1/users/avatar', {
        method: 'PATCH',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ avatarUrl }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Set avatar failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useSetAvatar() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (avatarUrl: string) => {
          const res = await fetch('/api/v1/users/avatar', {
            method: 'PATCH',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ avatarUrl }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Set avatar failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as AvatarUrlResponse;
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['users', 'profile'] });
          qc.invalidateQueries({ queryKey: ['auth', 'me'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/avatar', method: 'patch' }]" hasHead="false" />

## Source [#source]

| Source                 | Path                                                             | Lines                                 |
| ---------------------- | ---------------------------------------------------------------- | ------------------------------------- |
| Controller             | `apps/api-core/src/modules/user/user.controller.ts`              | `73–79` (`setAvatar`)                 |
| DTO (request)          | `apps/api-core/src/modules/user/dto/index.ts`                    | `5–7` (`SetAvatarDto`)                |
| DTO (response)         | `apps/api-core/src/modules/user/dto/user-client-response.dto.ts` | `113–116` (`AvatarUrlResponseDto`)    |
| Service                | `apps/api-core/src/modules/user/user.service.ts`                 | `90–112` (`setAvatar`)                |
| Object storage cleanup | `apps/api-core/src/modules/upload/upload.service.ts`             | `extractKeyFromUrl()`, `deleteFile()` |
| Prisma model           | `packages/prisma/prisma/schema.prisma`                           | `User.avatarUrl`                      |


# Block a User (/docs/user/block)



`POST /api/v1/users/block/:userId` — 🔑 **Bearer** · Rate limit: **10 req / hour**

Adds the target user to the caller's `BlockList`. **Self-block is rejected** — `ownerId === blockedId` throws `400 user.block.self`. **Double-block is a 409** — calling twice for the same target throws `user.block.already_blocked`. The mutation is audit-logged at warn level for moderation review.



<Callout type="info">
  Block is **directional** — a blocks b is independent from b blocks a. Server-side feed/messaging filters use the union of both directions, but the underlying row is one-way.
</Callout>

<Callout type="warn">
  Blocked users are not notified. Don't surface "you have been blocked" UI on the blocked side — that's a deliberate design choice across the platform.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param    | Type          | Validation      | Notes             |
| -------- | ------------- | --------------- | ----------------- |
| `userId` | string (UUID) | `ParseUUIDPipe` | The user to block |

No body.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                |
| --------- | ------- | -------------------- |
| `success` | boolean | Always `true` on 200 |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`           | Reason                                                       |
| ----- | ---------------------------- | ------------------------------------------------------------ |
| `400` | `user.block.self`            | `userId` path param equals the bearer's subject              |
| `400` | (validation)                 | `userId` not a valid UUID                                    |
| `401` | (guard)                      | Missing / invalid bearer token                               |
| `409` | `user.block.already_blocked` | A `BlockList` row already exists for this owner/blocked pair |
| `429` | (throttle)                   | Rate limit exceeded (10 req/hour)                            |

## Side effects [#side-effects]

1. Reject self-block (`ownerId === blockedId`) → `user.block.self`.
2. `prisma.blockList.findFirst({ where: { ownerId, blockedId } })`. If found → `already_blocked`.
3. `prisma.blockList.create({ data: { id: randomUUID(), ownerId, blockedId } })`.
4. Audit log (warn level): `[block] AUDIT: User {ownerId} blocked {blockedId}`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/users/block/f0e1d2c3-b4a5-6789-0123-456789abcdef \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function blockUser(accessToken: string, blockedUserId: string): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/users/block/${blockedUserId}`, {
        method: 'POST',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Block failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useBlockUser() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (blockedUserId: string) => {
          const res = await fetch(`/api/v1/users/block/${blockedUserId}`, { method: 'POST' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Block failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['users', 'blocked'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/block/{userId}', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                  | Lines                    |
| -------------- | ----------------------------------------------------- | ------------------------ |
| Controller     | `apps/api-core/src/modules/user/user.controller.ts`   | `286–296` (`blockUser`)  |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts` | `SuccessOnlyResponseDto` |
| Service        | `apps/api-core/src/modules/user/user.service.ts`      | `767–777` (`blockUser`)  |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                | `BlockList`              |


# List Blocked Users (/docs/user/blocked)



`GET /api/v1/users/blocked` — 🔑 **Bearer**

Returns the **first 50 most recently blocked** users from the caller's `BlockList`, plus the `total` count. Pagination is **not exposed** through this endpoint — the controller calls the service with the defaults (`page = 1`, `limit = 50`). For users with more than 50 blocks, the additional rows are not currently reachable via this REST endpoint; surface a "view all" affordance only when `total <= 50`.



<Callout type="info">
  The service supports pagination internally (`page`, `limit` params, max 50/page) but the controller doesn't accept query params. If you need paginated reads in the future, the service is ready — track the controller change in a follow-up.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<BlockedUsersResponseDto>` [#200-ok--apiresponseofblockedusersresponsedto]

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
        "username": "alice",
        "displayName": "Alice Smith",
        "blockedAt": "2026-04-29T20:00:00.000Z"
      },
      {
        "id": "e1d2c3b4-a5f6-7890-1234-56789abcdef0",
        "username": "bob",
        "displayName": null,
        "blockedAt": "2026-04-28T15:30:00.000Z"
      }
    ],
    "total": 2
  }
}
```

| Field                 | Type              | Notes                                                                                                 |
| --------------------- | ----------------- | ----------------------------------------------------------------------------------------------------- |
| `items`               | array             | Up to 50 entries, ordered by `blockedAt` DESC                                                         |
| `items[].id`          | string (UUID)     | The blocked user's id (NOT the `BlockList` row id) — pass to `DELETE /users/block/:userId` to unblock |
| `items[].username`    | string \| null    | Blocked user's username (may be null if never set)                                                    |
| `items[].displayName` | string \| null    | Blocked user's display name                                                                           |
| `items[].blockedAt`   | string (ISO 8601) | When the block row was created                                                                        |
| `total`               | number            | Total `BlockList` rows for this user (may exceed `items.length` when total > 50)                      |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                         |
| ----- | ------------------ | ------------------------------ |
| `401` | (guard)            | Missing / invalid bearer token |

## Side effects [#side-effects]

1. `prisma.blockList.findMany({ where: { ownerId: userId }, include: { blocked: { select: { id, username, displayName } } }, orderBy: { createdAt: 'desc' }, skip: 0, take: 50 })`.
2. `prisma.blockList.count({ where: { ownerId: userId } })` — runs in parallel with `findMany`.
3. Map each `BlockList` row → `{ id: blockedId, username, displayName, blockedAt: createdAt }`.
4. Return `{ items, total }`. No mutations.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/users/blocked \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type BlockedUserItem = {
      id: string;
      username: string | null;
      displayName: string | null;
      blockedAt: string;
    };

    type BlockedUsersResponse = {
      items: BlockedUserItem[];
      total: number;
    };

    async function getBlockedUsers(accessToken: string): Promise<BlockedUsersResponse> {
      const res = await fetch('https://api.bio.re/api/v1/users/blocked', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Blocked list fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const userKeys = {
      blocked: () => ['users', 'blocked'] as const,
    };

    export function useBlockedUsers() {
      return useQuery({
        queryKey: userKeys.blocked(),
        queryFn: async () => {
          const res = await fetch('/api/v1/users/blocked');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Blocked list fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as BlockedUsersResponse;
        },
        staleTime: 30_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/blocked', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                             | Lines                                                       |
| -------------- | ---------------------------------------------------------------- | ----------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/user/user.controller.ts`              | `308–314` (`getBlockedUsers`)                               |
| DTO (response) | `apps/api-core/src/modules/user/dto/user-client-response.dto.ts` | `205–227` (`BlockedUsersResponseDto`, `BlockedUserItemDto`) |
| Service        | `apps/api-core/src/modules/user/user.service.ts`                 | `788–808` (`getBlockedUsers`)                               |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                           | `BlockList`, `User.username`, `User.displayName`            |


# Change Email (Request) (/docs/user/change-email)



`POST /api/v1/users/change-email` — 🔑 **Bearer** · Rate limit: **3 req / hour**

Initiates an email-change flow. Re-confirms the current password, validates the new email (format + disposable-domain + MX + GDPR tombstone + uniqueness), creates a fresh verification token, and queues a verification email to the **new** address through the active email provider (admin-managed). The account's `User.email` does **not** change here — it only flips after the user clicks the link in the verification email (separate verify endpoint, in the `auth` module).



<Callout type="warn">
  The verification email is sent to the **NEW** email, not the current one. The current account email is unchanged until the link is followed. This means a stolen access token cannot quietly hijack the account by swapping email — the attacker would also need access to the new mailbox.
</Callout>

<Callout type="info">
  The dispatch is delegated to the **active email provider** (admin-managed via `external.email.active_provider`; failover handled server-side). Vendor identity stays in admin — this endpoint guarantees delivery via whichever provider is active. The send itself is enqueued via the notification pipeline (BullMQ G2) — failures to deliver SMTP-side are logged but do not fail the request.
</Callout>

## Request [#request]

### Body — `ChangeEmailDto` [#body--changeemaildto]

| Field      | Type   | Required | Validation     | Notes                                                                 |
| ---------- | ------ | -------- | -------------- | --------------------------------------------------------------------- |
| `newEmail` | string | ✓        | `IsEmail()`    | The desired new email — server normalizes via `.toLowerCase().trim()` |
| `password` | string | ✓        | `MinLength(8)` | Current account password — re-confirms via bcrypt                     |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<EmailChangeMessageDto>` [#200-ok--apiresponseofemailchangemessagedto]

```json
{
  "success": true,
  "data": {
    "message": "Verification email sent to your new address. Please check your inbox."
  }
}
```

| Field     | Type   | Notes                                                                       |
| --------- | ------ | --------------------------------------------------------------------------- |
| `message` | string | Localizable confirmation message — render under the form, no further fields |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                           | Reason                                                                                                               |
| ----- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `400` | (DTO validation)                             | `newEmail` not a valid email format; `password` shorter than 8 chars                                                 |
| `400` | `user.change_email.password_required`        | Account has no `passwordHash` (OAuth-only — set a password via the change-password flow first)                       |
| `400` | `user.change_email.password_incorrect`       | Bcrypt password check failed                                                                                         |
| `400` | `user.change_email.email_same`               | New email equals current `User.email` after normalization                                                            |
| `400` | `user.change_email.email_invalid`            | Email validator rejected (disposable domain or MX failure)                                                           |
| `401` | (guard)                                      | Missing / invalid bearer token                                                                                       |
| `404` | `user.change_email.not_found`                | Token decoded but user row missing                                                                                   |
| `409` | `user.change_email.email_taken`              | Active user already holds this email (also caught from Prisma P2002 race)                                            |
| `409` | `user.change_email.email_previously_deleted` | Email matches the deleted-tombstone hash (`deleted_<sha256(email)>@deleted.bio.re`) — refuse to reuse for compliance |
| `429` | (throttle)                                   | Rate limit exceeded (3 req/hour)                                                                                     |

## Side effects [#side-effects]

1. Normalize submitted email; lookup `User`; reject if no `passwordHash`.
2. **Bcrypt-compare** `password` against `User.passwordHash`.
3. Reject if `newEmail === user.email` (no-op).
4. **Email validator** — checks disposable-domain blocklist + MX record presence.
5. Reject if any other user already holds this email.
6. **GDPR tombstone check** — compute `sha256(newEmail)`; if a row exists with `email = "deleted_<hash>@deleted.bio.re"` AND `status = DELETED`, reject. (Prevents reusing emails of accounts that were deleted under GDPR right-to-erasure.)
7. **Inside one transaction**:
   * `UPDATE EmailVerification SET verified=true, usedAt=now() WHERE userId=:userId AND newEmail IS NOT NULL AND verified=false` — invalidate any pending change-email tokens.
   * `INSERT EmailVerification { userId, token=randomUUID(), newEmail, expiresAt = now() + auth.verification_token_expiry_hours }` (default 24h).
   * On Prisma `P2002` (concurrent email claim), throw `email_taken`.
8. **Queue verification email** — `notificationService.send({ eventKey: 'email_verification', userId, variables: { username, verifyUrl } })`. This enqueues a BullMQ job consumed by worker-service, which dispatches via the active email provider. Failure is logged, not surfaced.
9. Audit log: `[emailChange] Verification sent for user {userId} to <masked email>` (last-4 prefix masking via `maskEmail()`).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/users/change-email \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "newEmail": "new-address@example.com",
        "password": "current-account-password"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type ChangeEmailInput = { newEmail: string; password: string };
    type ChangeEmailResponse = { message: string };

    async function changeEmail(accessToken: string, input: ChangeEmailInput): Promise<ChangeEmailResponse> {
      const res = await fetch('https://api.bio.re/api/v1/users/change-email', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Change email failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useChangeEmail() {
      return useMutation({
        mutationFn: async (input: ChangeEmailInput) => {
          const res = await fetch('/api/v1/users/change-email', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Change email failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as ChangeEmailResponse;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/change-email', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source                | Path                                                             | Lines                                                  |
| --------------------- | ---------------------------------------------------------------- | ------------------------------------------------------ |
| Controller            | `apps/api-core/src/modules/user/user.controller.ts`              | `125–135` (`changeEmail`)                              |
| DTO (request)         | `apps/api-core/src/modules/user/dto/index.ts`                    | `26–32` (`ChangeEmailDto`)                             |
| DTO (response)        | `apps/api-core/src/modules/user/dto/user-client-response.dto.ts` | `127–130` (`EmailChangeMessageDto`)                    |
| Service               | `apps/api-core/src/modules/user/user.service.ts`                 | `271–345` (`requestEmailChange`)                       |
| Notification pipeline | `apps/api-core/src/modules/notification/notification.service.ts` | `send()` (enqueues BullMQ G2 job)                      |
| Email provider        | (admin-managed)                                                  | `external.email.active_provider` ConfigService key     |
| Prisma models         | `packages/prisma/prisma/schema.prisma`                           | `User.email`, `User.passwordHash`, `EmailVerification` |


# Check Username Availability (/docs/user/check-username)



`GET /api/v1/users/check-username` — 🌐 **Public** · Rate limit: **30 req / minute**

Real-time check used by the registration / settings form before submit. Returns `{ available: true }` only when the value normalizes within the configured length bounds, matches the format regex, **and** is not currently held by an active user or the reserved-name list.



<Callout type="info">
  This is the only public endpoint in the user module — needed because the registration form runs before login. The 30/min throttle is per-IP. Pair it with client-side debouncing (\~300ms) to keep within budget.
</Callout>

<Callout type="warn">
  A length / format failure also returns `{ available: false }` — there is **no separate "invalid format" code path**. If you need to distinguish "taken" from "malformed", validate format client-side before calling. The cooldown rule applies only to `PATCH /users/username`, not here.
</Callout>

## Request [#request]

### Query parameters [#query-parameters]

| Param      | Type   | Required | Notes                                                                                    |
| ---------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| `username` | string | ✓        | The candidate username — server normalizes via `.toLowerCase().trim()` before evaluation |

No body, no headers required.

## Response [#response]

### `200 OK` — `ApiResponseOf<UsernameAvailabilityDto>` [#200-ok--apiresponseofusernameavailabilitydto]

```json
{
  "success": true,
  "data": {
    "available": true
  }
}
```

| Field       | Type    | Notes                                                                 |
| ----------- | ------- | --------------------------------------------------------------------- |
| `available` | boolean | `true` only when length + format + uniqueness + not-reserved all pass |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                           |
| ----- | ------------------ | -------------------------------- |
| `429` | (throttle)         | Rate limit exceeded (30 req/min) |

The endpoint never throws on invalid input — `available: false` is the universal "not usable" signal.

## Side effects [#side-effects]

1. Normalize input (`.toLowerCase().trim()`).
2. Length check against `site.username_min_length` / `site.username_max_length` (admin-managed) → if outside bounds, return `{ available: false }`.
3. Format check against `^[a-z0-9._-]+$` → if failing, return `{ available: false }`.
4. `prisma.user.findUnique({ where: { username } })` → if hit, return `{ available: false }`.
5. `prisma.reservedUsername.findUnique({ where: { username } })` → if hit, return `{ available: false }`.
6. Otherwise: return `{ available: true }`. No mutations.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl 'https://api.bio.re/api/v1/users/check-username?username=johndoe'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function checkUsername(username: string): Promise<boolean> {
      const url = new URL('https://api.bio.re/api/v1/users/check-username');
      url.searchParams.set('username', username);
      const res = await fetch(url);
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Check failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.available;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const usernameKeys = {
      availability: (username: string) => ['users', 'check-username', username] as const,
    };

    export function useUsernameAvailability(username: string) {
      // Caller is responsible for debouncing the input upstream.
      return useQuery({
        queryKey: usernameKeys.availability(username),
        queryFn: async () => {
          const url = new URL('/api/v1/users/check-username', window.location.origin);
          url.searchParams.set('username', username);
          const res = await fetch(url);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Check failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.available as boolean;
        },
        enabled: username.length >= 3,
        staleTime: 10_000, // 10s — registration form lifetime is short
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/check-username', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                             | Lines                                    |
| -------------- | ---------------------------------------------------------------- | ---------------------------------------- |
| Controller     | `apps/api-core/src/modules/user/user.controller.ts`              | `114–121` (`checkUsername`, `@Public()`) |
| DTO (response) | `apps/api-core/src/modules/user/dto/user-client-response.dto.ts` | `120–123` (`UsernameAvailabilityDto`)    |
| Service        | `apps/api-core/src/modules/user/user.service.ts`                 | `246–259` (`checkUsernameAvailability`)  |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                           | `User.username`, `ReservedUsername`      |


# Get Consent History (/docs/user/consent-history)



`GET /api/v1/users/consent` — 🔑 **Bearer**

Returns up to **100 most recent** `ConsentRecord` rows for the calling user, ordered by `createdAt DESC`. Each row exposes the document type / version, whether it was accepted or declined, and the timestamp. The IP / user-agent metadata is **not** returned to the client (kept server-side for compliance audit only).



<Callout type="info">
  Capped at 100 rows — sufficient for the typical "your consent history" UI. For full audit exports across longer time spans, use the GDPR data-export pipeline (`POST /gdpr/export`) which includes the full table.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ArrayApiResponseOf<ConsentHistoryItemDto>` [#200-ok--arrayapiresponseofconsenthistoryitemdto]

```json
{
  "success": true,
  "data": [
    {
      "documentType": "tos",
      "documentVersion": "2.1",
      "accepted": true,
      "createdAt": "2026-04-29T20:00:00.000Z"
    },
    {
      "documentType": "privacy",
      "documentVersion": "1.4",
      "accepted": true,
      "createdAt": "2026-04-29T20:00:00.000Z"
    },
    {
      "documentType": "marketing-emails",
      "documentVersion": "1.0",
      "accepted": false,
      "createdAt": "2026-04-29T20:00:00.000Z"
    }
  ]
}
```

### Item fields [#item-fields]

| Field             | Type              | Notes                                                                                     |
| ----------------- | ----------------- | ----------------------------------------------------------------------------------------- |
| `documentType`    | string            | The key recorded by the original `POST /users/consent` (e.g. `tos`, `privacy`, `cookies`) |
| `documentVersion` | string            | The version recorded with the consent                                                     |
| `accepted`        | boolean           | `true` for opt-in, `false` for explicit decline                                           |
| `createdAt`       | string (ISO 8601) | Server-side timestamp of when the consent was recorded                                    |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                         |
| ----- | ------------------ | ------------------------------ |
| `401` | (guard)            | Missing / invalid bearer token |

## Side effects [#side-effects]

1. `prisma.consentRecord.findMany({ where: { userId }, orderBy: { createdAt: 'desc' }, take: 100, select: { documentType, documentVersion, accepted, createdAt } })`.
2. Return the array. No mutations.
3. **`ipAddress` and `userAgent` are intentionally excluded from the select** — they are stored server-side for compliance audit and are never exposed in this read.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/users/consent \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type ConsentHistoryItem = {
      documentType: string;
      documentVersion: string;
      accepted: boolean;
      createdAt: string;
    };

    async function getConsentHistory(accessToken: string): Promise<ConsentHistoryItem[]> {
      const res = await fetch('https://api.bio.re/api/v1/users/consent', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Consent history fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const userKeys = {
      consent: () => ['users', 'consent'] as const,
    };

    export function useConsentHistory() {
      return useQuery({
        queryKey: userKeys.consent(),
        queryFn: async () => {
          const res = await fetch('/api/v1/users/consent');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Consent history fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as ConsentHistoryItem[];
        },
        staleTime: 60_000, // History changes only when user actively records new consent
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/consent', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source              | Path                                                             | Lines                               |
| ------------------- | ---------------------------------------------------------------- | ----------------------------------- |
| Controller          | `apps/api-core/src/modules/user/user.controller.ts`              | `263–269` (`getConsentHistory`)     |
| DTO (response item) | `apps/api-core/src/modules/user/dto/user-client-response.dto.ts` | `189–201` (`ConsentHistoryItemDto`) |
| Service             | `apps/api-core/src/modules/user/user.service.ts`                 | `739–751` (`getConsentHistory`)     |
| Prisma model        | `packages/prisma/prisma/schema.prisma`                           | `ConsentRecord`                     |


# Record Consent (/docs/user/consent-record)



`POST /api/v1/users/consent` — 🔑 **Bearer**

Records a single immutable consent decision in the `ConsentRecord` log. Captures the user's choice (`accepted: true | false`), the document type and version, plus `req.ip` and the `User-Agent` header for compliance audit. **Append-only** — there is no update/delete; revising consent for the same document is a new row.



<Callout type="info">
  Compliance-grade. The IP and user-agent are stored to prove *who, when, and from where* a consent was given. The frontend sends only the document type / version / accepted flag; the request metadata (`req.ip`, `req.headers['user-agent']`) is captured server-side.
</Callout>

## Request [#request]

### Body — `RecordConsentDto` [#body--recordconsentdto]

| Field             | Type    | Required | Validation    | Notes                                                                                      |
| ----------------- | ------- | -------- | ------------- | ------------------------------------------------------------------------------------------ |
| `documentType`    | string  | ✓        | `IsString()`  | Free-form key — typical values: `tos`, `privacy`, `cookies`, `marketing-emails`            |
| `documentVersion` | string  | ✓        | `IsString()`  | Semver-ish version of the document being agreed to (e.g. `2.1`, `2026-04-29`)              |
| `accepted`        | boolean | ✓        | `IsBoolean()` | `true` for an opt-in, `false` for an explicit decline (declines are also logged for audit) |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `201 Created` — `ApiResponseOf<ConsentRecordedDto>` [#201-created--apiresponseofconsentrecordeddto]

```json
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

| Field | Type          | Notes                                                           |
| ----- | ------------- | --------------------------------------------------------------- |
| `id`  | string (UUID) | `ConsentRecord.id` — useful only for tracing in support tickets |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                         |
| ----- | ------------------ | ------------------------------ |
| `400` | (DTO validation)   | Missing / wrong-typed fields   |
| `401` | (guard)            | Missing / invalid bearer token |

## Side effects [#side-effects]

1. Generate `id = randomUUID()`.
2. Insert `ConsentRecord { id, userId, documentType, documentVersion, accepted, ipAddress: req.ip, userAgent: req.headers['user-agent'] }`. **No deduplication** — calling twice with the same document/version creates two rows.
3. Audit log: `[consent] {documentType} v{documentVersion} accepted/declined by user {userId}`.
4. No further side effects — does **not** flip any flag on `User`. Document gating is read separately via the consent history (or `hasConsent()` server-side helper).

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/users/consent \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "documentType": "tos",
        "documentVersion": "2.1",
        "accepted": true
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type RecordConsentInput = {
      documentType: string;
      documentVersion: string;
      accepted: boolean;
    };

    async function recordConsent(accessToken: string, input: RecordConsentInput): Promise<string> {
      const res = await fetch('https://api.bio.re/api/v1/users/consent', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Record consent failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.id as string;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useRecordConsent() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (input: RecordConsentInput) => {
          const res = await fetch('/api/v1/users/consent', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Record consent failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.id as string;
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['users', 'consent'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/consent', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                             | Lines                            |
| -------------- | ---------------------------------------------------------------- | -------------------------------- |
| Controller     | `apps/api-core/src/modules/user/user.controller.ts`              | `248–261` (`recordConsent`)      |
| DTO (request)  | `apps/api-core/src/modules/user/dto/index.ts`                    | `20–24` (`RecordConsentDto`)     |
| DTO (response) | `apps/api-core/src/modules/user/dto/user-client-response.dto.ts` | `182–185` (`ConsentRecordedDto`) |
| Service        | `apps/api-core/src/modules/user/user.service.ts`                 | `719–734` (`recordConsent`)      |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                           | `ConsentRecord`                  |


# Deactivate Account (/docs/user/deactivate)



`POST /api/v1/users/deactivate` — 🔑 **Bearer** · Rate limit: **3 req / hour**

Sets `User.status = DEACTIVATED` and **revokes every active session** for this user. Reversible — the user can come back via `POST /users/reactivate` (auth-session mode) or by clicking a reactivation link sent later (token-bearer mode).



<Callout type="warn">
  **All sessions are revoked, including the one calling this endpoint.** The next request with the existing access token will succeed only until the JWT expires (`auth.access_token_ttl_seconds`); the refresh cookie is dead immediately. Plan a redirect to a logged-out landing page on success.
</Callout>

<Callout type="info">
  Deactivation is **distinct from deletion**. Deactivation is reversible and preserves all data. Deletion is `POST /users/delete` (or `POST /gdpr/delete`), which schedules permanent erasure after a grace period. Deactivation by itself does not start any deletion timer.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                |
| --------- | ------- | -------------------- |
| `success` | boolean | Always `true` on 200 |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`              | Reason                                                                             |
| ----- | ------------------------------- | ---------------------------------------------------------------------------------- |
| `400` | `error.user.account_not_active` | `User.status` is not `ACTIVE` (already DEACTIVATED, SUSPENDED, BANNED, or DELETED) |
| `401` | (guard)                         | Missing / invalid bearer token                                                     |
| `404` | `error.user.not_found`          | Token decoded but user row missing                                                 |
| `429` | (throttle)                      | Rate limit exceeded (3 req/hour)                                                   |

## Side effects [#side-effects]

1. Lookup `User`; throw `not_found` if missing.
2. Reject if `User.status !== 'ACTIVE'` — no idempotent re-deactivation.
3. **Inside one transaction**:
   * `User.status = DEACTIVATED`.
   * `UPDATE Session SET revoked = true, revokedAt = now() WHERE userId = :userId AND revoked = false` (every live session).
4. Audit log: `[account] AUDIT: Deactivated by user {userId}` (warn level).
5. **No** scheduled deletion is created — that requires the separate `/users/delete` flow.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/users/deactivate \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function deactivateAccount(accessToken: string): Promise<void> {
      const res = await fetch('https://api.bio.re/api/v1/users/deactivate', {
        method: 'POST',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Deactivate failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useDeactivateAccount() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/users/deactivate', { method: 'POST' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Deactivate failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          // Sessions revoked server-side — drop all caches, force re-auth flow
          qc.clear();
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/deactivate', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                  | Lines                                                |
| -------------- | ----------------------------------------------------- | ---------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/user/user.controller.ts`   | `158–167` (`deactivateAccount`)                      |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts` | `SuccessOnlyResponseDto`                             |
| Service        | `apps/api-core/src/modules/user/user.service.ts`      | `402–421` (`deactivateAccount`)                      |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                | `User.status` (`UserStatus` enum), `Session.revoked` |


# Request Deletion (Legacy) (/docs/user/delete-legacy)



`POST /api/v1/users/delete` — 🔑 **Bearer** · Rate limit: **3 req / hour**

Legacy alias of `POST /gdpr/delete`. **Same effect** (scheduled deletion + immediate deactivation + session revoke), but it **additionally requires the current account password** in the body and returns the leaner `{ scheduledAt }` shape.



<Callout type="warn">
  **New clients should use [`POST /gdpr/delete`](/docs/user/gdpr-delete).** This legacy endpoint differs from the modern equivalent in three ways:

  1. **Body is required** — `{ password }` must be sent and is bcrypt-checked against `User.passwordHash`.
  2. **Response is leaner** — `{ scheduledAt }` only, no request id or status field.
  3. **Throttle is looser** — 3/hour vs 1/day on the modern endpoint.

  To cancel a deletion requested through this endpoint, use [`DELETE /gdpr/delete`](/docs/user/gdpr-delete-cancel) — both endpoints write to the same `GDPRRequest` table, so the cancel endpoint sees both.
</Callout>

## Request [#request]

### Body — `RequestDeletionDto` [#body--requestdeletiondto]

| Field      | Type   | Required | Validation     | Notes                                                                  |
| ---------- | ------ | -------- | -------------- | ---------------------------------------------------------------------- |
| `password` | string | ✓        | `MinLength(8)` | Current account password — bcrypt-compared against `User.passwordHash` |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<DeletionScheduledDto>` [#200-ok--apiresponseofdeletionscheduleddto]

```json
{
  "success": true,
  "data": {
    "scheduledAt": "2026-05-29T20:00:00.000Z"
  }
}
```

| Field         | Type              | Notes                                                                                                       |
| ------------- | ----------------- | ----------------------------------------------------------------------------------------------------------- |
| `scheduledAt` | string (ISO 8601) | When the worker will run the actual purge — `now + gdpr.delete_grace_days` (admin-managed, default 30 days) |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`              | Reason                                                                                                                 |
| ----- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `400` | (DTO validation)                | `password` shorter than 8 chars                                                                                        |
| `400` | `error.user.password_required`  | Account has no `passwordHash` (OAuth-only — set a password first or use the modern endpoint which doesn't require one) |
| `400` | `error.user.password_incorrect` | Bcrypt password check failed                                                                                           |
| `401` | (guard)                         | Missing / invalid bearer token                                                                                         |
| `404` | `error.user.not_found`          | Token decoded but user row missing                                                                                     |
| `409` | `error.user.deletion_scheduled` | A previous DELETION request is already `PENDING`                                                                       |
| `429` | (throttle)                      | Rate limit exceeded (3 req/hour)                                                                                       |

## Side effects [#side-effects]

1. Lookup `User`; reject if missing or no `passwordHash`.
2. **Bcrypt-compare** `password` against `User.passwordHash`.
3. Look for an existing `GDPRRequest { type: DELETION, status: PENDING }`. If found → `deletion_scheduled`.
4. Compute `scheduledAt = now + gdpr.delete_grace_days * 86400 * 1000`.
5. **Inside one transaction** (same as `/gdpr/delete`):
   * Insert `GDPRRequest { id, userId, type: DELETION, status: PENDING, scheduledAt }`.
   * `User.status = DEACTIVATED`.
   * Revoke every active `Session`.
6. Audit log: `[gdpr] Deletion scheduled for user {userId} at <iso>`.

## Migration to the modern endpoint [#migration-to-the-modern-endpoint]

```diff
- await fetch('/api/v1/users/delete', {
-   method: 'POST',
-   body: JSON.stringify({ password }),
- });
+ // The modern endpoint does not require the password — re-confirm via UI flow if you want
+ await fetch('/api/v1/gdpr/delete', { method: 'POST' });
```

If you need the password-confirmation UX (recommended for destructive operations), keep using this legacy endpoint **or** add an interstitial password re-prompt in your app before calling `/gdpr/delete`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/users/delete \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"password": "current-account-password"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function requestDeletionLegacy(accessToken: string, password: string): Promise<string> {
      const res = await fetch('https://api.bio.re/api/v1/users/delete', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ password }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Deletion request failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.scheduledAt as string;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useRequestDeletionLegacy() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (password: string) => {
          const res = await fetch('/api/v1/users/delete', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ password }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Deletion request failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.scheduledAt as string;
        },
        onSuccess: () => {
          // Sessions revoked server-side — drop all caches, force re-auth flow
          qc.clear();
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/delete', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source            | Path                                                             | Lines                                           |
| ----------------- | ---------------------------------------------------------------- | ----------------------------------------------- |
| Controller        | `apps/api-core/src/modules/user/user.controller.ts`              | `223–233` (`requestDeletion`)                   |
| DTO (request)     | `apps/api-core/src/modules/user/dto/index.ts`                    | `16–18` (`RequestDeletionDto`)                  |
| DTO (response)    | `apps/api-core/src/modules/user/dto/user-client-response.dto.ts` | `168–171` (`DeletionScheduledDto`)              |
| Service           | `apps/api-core/src/modules/user/user.service.ts`                 | `483–526` (`requestDeletion`)                   |
| Modern equivalent | `apps/api-core/src/modules/user/gdpr.controller.ts`              | `72–82` (`requestDeletion`)                     |
| Prisma models     | `packages/prisma/prisma/schema.prisma`                           | `GDPRRequest`, `User.status`, `Session.revoked` |


# Request Export (Legacy) (/docs/user/export-legacy)



`POST /api/v1/users/export` — 🔑 **Bearer** · Rate limit: **3 req / hour**

Legacy alias of `POST /gdpr/export`. **Same purpose**, slightly different behavior — kept for backward compatibility.



<Callout type="warn">
  **New clients should use [`POST /gdpr/export`](/docs/user/gdpr-export).** This legacy endpoint differs from it in two ways:

  1. **Duplicate-check is looser** — it only blocks when an existing request is `PENDING`. The modern endpoint blocks on `PENDING` **or** `PROCESSING`.
  2. **Response is leaner** — only `{ requestId }` is returned, no `status` or `createdAt`.

  The throttle ceiling is also higher here (3 / hour vs 3 / day on the modern endpoint), which exists for historical reasons.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<ExportRequestedDto>` [#200-ok--apiresponseofexportrequesteddto]

```json
{
  "success": true,
  "data": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

| Field       | Type          | Notes                                                                                                                                                                   |
| ----------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requestId` | string (UUID) | `GDPRRequest.id` — pass to `GET /gdpr/export/:id/status` and `GET /gdpr/export/:id/download` (the modern status / download endpoints accept ids created by either path) |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`              | Reason                                                                                                              |
| ----- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `401` | (guard)                         | Missing / invalid bearer token                                                                                      |
| `409` | `error.user.export_in_progress` | A previous EXPORT request is `PENDING` (does **not** trigger on `PROCESSING` — that's the modern-endpoint behavior) |
| `429` | (throttle)                      | Rate limit exceeded (3 req/hour)                                                                                    |

## Side effects [#side-effects]

1. Look for an existing `GDPRRequest { type: EXPORT, status: PENDING }` for this user. If found → `export_in_progress`.
2. Insert `GDPRRequest { id: randomUUID(), userId, type: EXPORT, status: PENDING }`.
3. Audit log: `[gdpr] Export requested for user {userId}: {requestId}`.
4. Worker pickup happens the same way as the modern endpoint — there is one shared worker that processes all `PENDING` `GDPRRequest EXPORT` rows regardless of which controller created them.

## Migration to the modern endpoint [#migration-to-the-modern-endpoint]

```diff
- const res = await fetch('/api/v1/users/export', { method: 'POST' });
- const { requestId } = (await res.json()).data;
+ const res = await fetch('/api/v1/gdpr/export', { method: 'POST' });
+ const { id, status, createdAt } = (await res.json()).data;
```

The status / download endpoints (`GET /gdpr/export/:id/status` and `GET /gdpr/export/:id/download`) work identically against either id — there is **no need to migrate already-issued ids**.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/users/export \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function requestExportLegacy(accessToken: string): Promise<string> {
      const res = await fetch('https://api.bio.re/api/v1/users/export', {
        method: 'POST',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Export request failed'), {
          code: json?.error?.code,
        });
      }
      return json.data.requestId;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useRequestExportLegacy() {
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/users/export', { method: 'POST' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Export request failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data.requestId as string;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/export', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source            | Path                                                             | Lines                                   |
| ----------------- | ---------------------------------------------------------------- | --------------------------------------- |
| Controller        | `apps/api-core/src/modules/user/user.controller.ts`              | `235–244` (`requestExport`)             |
| DTO (response)    | `apps/api-core/src/modules/user/dto/user-client-response.dto.ts` | `175–178` (`ExportRequestedDto`)        |
| Service           | `apps/api-core/src/modules/user/user.service.ts`                 | `531–550` (`requestDataExport`)         |
| Modern equivalent | `apps/api-core/src/modules/user/gdpr.controller.ts`              | `32–42` (`requestExport`)               |
| Prisma model      | `packages/prisma/prisma/schema.prisma`                           | `GDPRRequest`, `GDPRRequestType.EXPORT` |


# Cancel Pending Deletion (/docs/user/gdpr-delete-cancel)



`DELETE /api/v1/gdpr/delete` — 🔑 **Bearer**

Cancels a pending deletion and reactivates the account in one transaction. Flips `GDPRRequest.status = CANCELLED` and `User.status = ACTIVE`. **Existing sessions are not restored** — they were revoked when the deletion was requested and remain revoked; the user must log in fresh.



<Callout type="info">
  The bearer token used here is typically issued **after** logging back in during the grace period — when the user changes their mind, they log in again (which works fine on a `DEACTIVATED` account because login bypasses the deactivation gate explicitly for this flow), then call this endpoint to abort the deletion.
</Callout>

<Callout type="warn">
  Once `GDPRRequest.status` leaves `PENDING` (i.e., the worker has begun `PROCESSING` or already `COMPLETED` the purge), this endpoint is a 404 — there is no rollback for an in-flight or completed purge.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                |
| --------- | ------- | -------------------- |
| `success` | boolean | Always `true` on 200 |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`               | Reason                                                                                                              |
| ----- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `401` | (guard)                          | Missing / invalid bearer token                                                                                      |
| `404` | `error.gdpr.no_pending_deletion` | No `GDPRRequest DELETION PENDING` row exists for this user (already cancelled, already processed, or never existed) |

## Side effects [#side-effects]

1. Look up the **most recent** `GDPRRequest { type: DELETION, status: PENDING }` for this user. If absent → `no_pending_deletion`.
2. **Inside one transaction**:
   * `GDPRRequest.status = CANCELLED` (for the matched row).
   * `User.status = ACTIVE` (reactivate the account).
3. Audit log: `[gdpr] Deletion cancelled by user {userId}, request <id>`.
4. **Sessions are NOT touched** — they were revoked at deletion-request time and remain so. The user must log in fresh.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X DELETE https://api.bio.re/api/v1/gdpr/delete \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function cancelGdprDeletion(accessToken: string): Promise<void> {
      const res = await fetch('https://api.bio.re/api/v1/gdpr/delete', {
        method: 'DELETE',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Cancel failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useCancelGdprDeletion() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/gdpr/delete', { method: 'DELETE' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Cancel failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          // Account is ACTIVE again — invalidate identity caches
          qc.invalidateQueries({ queryKey: ['users', 'profile'] });
          qc.invalidateQueries({ queryKey: ['auth', 'me'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/gdpr/delete', method: 'delete' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                  | Lines                               |
| -------------- | ----------------------------------------------------- | ----------------------------------- |
| Controller     | `apps/api-core/src/modules/user/gdpr.controller.ts`   | `84–92` (`cancelDeletion`)          |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts` | `SuccessOnlyResponseDto`            |
| Service        | `apps/api-core/src/modules/user/user.service.ts`      | `683–709` (`gdprCancelDeletion`)    |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                | `GDPRRequest.status`, `User.status` |


# Request Account Deletion (GDPR) (/docs/user/gdpr-delete)



`POST /api/v1/gdpr/delete` — 🔑 **Bearer** · Rate limit: **1 req / day**

Schedules the calling account for permanent deletion. Creates a `GDPRRequest DELETION PENDING` row, **deactivates the account immediately** (`User.status = DEACTIVATED`), and revokes every active session in the same transaction. The actual purge runs after a grace period (`gdpr.delete_grace_days`, admin-managed, default 30) — until then, the user can cancel via `DELETE /gdpr/delete` (or by clicking the reactivation link from the email flow).



<Callout type="warn">
  **Sessions are revoked immediately**, including the one calling this endpoint. The user must re-authenticate to interact with the account again. Plan a redirect to a logged-out landing page on success.
</Callout>

<Callout type="info">
  For the legacy alias `POST /users/delete`, see [Request Deletion (Legacy)](/docs/user/delete-legacy). The legacy endpoint additionally requires the current account password in the body — kept for backward compatibility but the modern endpoint here is preferred.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<GdprDeletionRequestDto>` [#200-ok--apiresponseofgdprdeletionrequestdto]

```json
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "PENDING",
    "gracePeriodEnds": "2026-05-29T20:00:00.000Z"
  }
}
```

| Field             | Type              | Notes                                                                                                                                                      |
| ----------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | string (UUID)     | `GDPRRequest.id` — pass to `DELETE /gdpr/delete` to cancel                                                                                                 |
| `status`          | enum              | Always `PENDING` immediately after creation. Will progress to `PROCESSING` → `COMPLETED` (worker-driven) or `CANCELLED` (user-driven via cancel endpoint). |
| `gracePeriodEnds` | string (ISO 8601) | When the actual purge will run — `now + gdpr.delete_grace_days` (default 30 days)                                                                          |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                    | Reason                                           |
| ----- | ------------------------------------- | ------------------------------------------------ |
| `401` | (guard)                               | Missing / invalid bearer token                   |
| `409` | `error.gdpr.deletion_already_pending` | A previous DELETION request is already `PENDING` |
| `429` | (throttle)                            | Rate limit exceeded (1 req/day)                  |

## Side effects [#side-effects]

1. Look for an existing `GDPRRequest { type: DELETION, status: PENDING }` for this user. If found → `deletion_already_pending`.
2. Compute `gracePeriodEnds = now + gdpr.delete_grace_days * 86400 * 1000`.
3. **Inside one transaction**:
   * Insert `GDPRRequest { id, userId, type: DELETION, status: PENDING, scheduledAt: gracePeriodEnds }`.
   * `User.status = DEACTIVATED` — account is hidden during the grace period.
   * `UPDATE Session SET revoked = true, revokedAt = now() WHERE userId = :userId AND revoked = false`.
4. Audit log: `[gdpr] Self-service deletion requested by user {userId}, grace ends <iso>`.
5. **Worker pickup** — after `gracePeriodEnds`, the worker-service cron flips `status` to `PROCESSING`, performs the purge (Art. 17 erasure across all owned data), and sets `status = COMPLETED`. The cancel endpoint becomes a no-op once status leaves `PENDING`.

## Cancel flow [#cancel-flow]

To stop a scheduled deletion before the grace period ends:

```bash
# Cancel + reactivate the account in one call
curl -X DELETE https://api.bio.re/api/v1/gdpr/delete \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

The cancel endpoint flips `GDPRRequest.status = CANCELLED` and `User.status = ACTIVE` atomically. **Sessions stay revoked** — the user must log in fresh after cancelling.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/gdpr/delete \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type GdprDeletionRequest = {
      id: string;
      status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
      gracePeriodEnds: string;
    };

    async function requestGdprDeletion(accessToken: string): Promise<GdprDeletionRequest> {
      const res = await fetch('https://api.bio.re/api/v1/gdpr/delete', {
        method: 'POST',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Deletion request failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useRequestGdprDeletion() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/gdpr/delete', { method: 'POST' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Deletion request failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as GdprDeletionRequest;
        },
        onSuccess: () => {
          // Sessions revoked server-side — drop all caches, force re-auth flow
          qc.clear();
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/gdpr/delete', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                      | Lines                                                                               |
| -------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/user/gdpr.controller.ts`       | `72–82` (`requestDeletion`)                                                         |
| DTO (response) | `apps/api-core/src/modules/user/dto/gdpr-response.dto.ts` | `51–63` (`GdprDeletionRequestDto`)                                                  |
| Service        | `apps/api-core/src/modules/user/user.service.ts`          | `638–678` (`gdprRequestDeletion`)                                                   |
| Worker pickup  | `apps/worker-service/`                                    | cron scans `GDPRRequest` with `type=DELETION, status=PENDING, scheduledAt <= now()` |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                    | `GDPRRequest`, `User.status`, `Session.revoked`                                     |


# Download Export (/docs/user/gdpr-export-download)



`GET /api/v1/gdpr/export/:id/download` — 🔑 **Bearer**

Returns a **time-limited signed URL** for the completed export archive. Only succeeds when the request is `COMPLETED`; intermediate states return `404 export_not_ready`. The URL is short-lived (expires at `DataExport.expiresAt&#x60;, falling back to **+24h** when no expiry is recorded).



<Callout type="warn">
  The signed URL is **single-shot in spirit**. Don't email it, don't paste it in chat — anyone with the URL can download until it expires. Render into an `<a href={downloadUrl} download>` and trigger the click immediately, then discard from memory.
</Callout>

<Callout type="info">
  Returning a URL (rather than streaming the bytes) keeps the API server out of the data path — the file is served directly by object storage. The signing model is owned by the upload service; the URL works without further auth headers until `expiresAt`.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param | Type          | Validation      | Notes                                    |
| ----- | ------------- | --------------- | ---------------------------------------- |
| `id`  | string (UUID) | `ParseUUIDPipe` | The `id` returned by `POST /gdpr/export` |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<GdprExportDownloadDto>` [#200-ok--apiresponseofgdprexportdownloaddto]

```json
{
  "success": true,
  "data": {
    "downloadUrl": "https://cdn.bio.re/exports/uuid/export.zip?sig=...",
    "expiresAt": "2026-04-30T20:04:32.000Z"
  }
}
```

| Field         | Type              | Notes                                                                                 |
| ------------- | ----------------- | ------------------------------------------------------------------------------------- |
| `downloadUrl` | string            | Time-limited URL to the export archive — render directly into `<a href download>`     |
| `expiresAt`   | string (ISO 8601) | When the URL stops working — pulled from `DataExport.expiresAt`, fallback `now + 24h` |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`               | Reason                                                                          |
| ----- | -------------------------------- | ------------------------------------------------------------------------------- |
| `400` | `error.gdpr.not_export`          | The `GDPRRequest` exists but is type `DELETION`, not `EXPORT`                   |
| `401` | (guard)                          | Missing / invalid bearer token                                                  |
| `403` | `error.gdpr.not_owner`           | Request exists but `userId` does not match                                      |
| `404` | `error.gdpr.request_not_found`   | No `GDPRRequest` row with this id                                               |
| `404` | `error.gdpr.export_not_ready`    | Status is `PENDING` / `PROCESSING` / `FAILED` / `CANCELLED` (not `COMPLETED`)   |
| `404` | `error.gdpr.export_file_missing` | Status is `COMPLETED` but no matching `DataExport` row with `fileUrl` was found |

## Side effects [#side-effects]

1. Lookup `GDPRRequest`; throw `request_not_found` if missing.
2. Ownership check (`request.userId === jwt.sub`) → else `not_owner`.
3. Type check (`request.type === EXPORT`) → else `not_export`.
4. Status check (`request.status === COMPLETED`) → else `export_not_ready`.
5. Find the user's most recent `DataExport` with `status = COMPLETED` AND `fileUrl != null` (`orderBy: createdAt desc`). If none → `export_file_missing`.
6. Hand the file URL to the upload service, which produces a **signed, time-limited URL** suitable for direct browser download.
7. Compute `expiresAt = DataExport.expiresAt ?? (now + 24h)`.
8. Return `{ downloadUrl, expiresAt }`. No mutations.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/gdpr/export/a1b2c3d4-e5f6-7890-abcd-ef1234567890/download \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type GdprExportDownload = {
      downloadUrl: string;
      expiresAt: string;
    };

    async function getExportDownload(accessToken: string, id: string): Promise<GdprExportDownload> {
      const res = await fetch(`https://api.bio.re/api/v1/gdpr/export/${id}/download`, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Download URL fetch failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }

    // Trigger the download immediately so the URL doesn't linger in memory
    function triggerDownload(downloadUrl: string) {
      const a = document.createElement('a');
      a.href = downloadUrl;
      a.download = '';
      document.body.appendChild(a);
      a.click();
      a.remove();
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useGetExportDownload() {
      // Mutation — not a query — because it produces a side-effect (triggers download)
      // and we never want to cache the signed URL.
      return useMutation({
        mutationFn: async (id: string) => {
          const res = await fetch(`/api/v1/gdpr/export/${id}/download`);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Download URL fetch failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as GdprExportDownload;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/gdpr/export/{id}/download', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                      | Lines                                                       |
| -------------- | --------------------------------------------------------- | ----------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/user/gdpr.controller.ts`       | `57–68` (`downloadExport`)                                  |
| DTO (response) | `apps/api-core/src/modules/user/dto/gdpr-response.dto.ts` | `41–47` (`GdprExportDownloadDto`)                           |
| Service        | `apps/api-core/src/modules/user/user.service.ts`          | `603–631` (`gdprDownloadExport`)                            |
| URL signing    | `apps/api-core/src/modules/upload/upload.service.ts`      | `getSignedDownloadUrl()`                                    |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                    | `GDPRRequest`, `DataExport.fileUrl`, `DataExport.expiresAt` |


# Get Export Status (/docs/user/gdpr-export-status)



`GET /api/v1/gdpr/export/:id/status` — 🔑 **Bearer**

Returns the current state of a `GDPRRequest EXPORT` row owned by the calling user. **Ownership-checked** — `request.userId` must match the JWT subject; otherwise `403`.



<Callout type="info">
  This is the canonical poll endpoint. The status progresses `PENDING` → `PROCESSING` → `COMPLETED` (or `FAILED`). Once `COMPLETED`, fetch the signed download URL from `GET /gdpr/export/:id/download`.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param | Type          | Validation      | Notes                                    |
| ----- | ------------- | --------------- | ---------------------------------------- |
| `id`  | string (UUID) | `ParseUUIDPipe` | The `id` returned by `POST /gdpr/export` |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<GdprExportStatusDto>` [#200-ok--apiresponseofgdprexportstatusdto]

```json
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "COMPLETED",
    "createdAt": "2026-04-29T20:00:00.000Z",
    "completedAt": "2026-04-29T20:04:32.000Z"
  }
}
```

| Field         | Type                      | Notes                                                                                           |
| ------------- | ------------------------- | ----------------------------------------------------------------------------------------------- |
| `id`          | string (UUID)             | Echoes the request id                                                                           |
| `status`      | enum                      | One of `PENDING` / `PROCESSING` / `COMPLETED` / `FAILED` / `CANCELLED`                          |
| `createdAt`   | string (ISO 8601)         | Request creation timestamp                                                                      |
| `completedAt` | string (ISO 8601) \| null | Set when worker flips status to `COMPLETED` or `FAILED`. `null` while `PENDING` / `PROCESSING`. |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`             | Reason                                                          |
| ----- | ------------------------------ | --------------------------------------------------------------- |
| `401` | (guard)                        | Missing / invalid bearer token                                  |
| `403` | `error.gdpr.not_owner`         | Request exists but `userId` does not match the bearer's subject |
| `404` | `error.gdpr.request_not_found` | No `GDPRRequest` row with this id                               |

## Side effects [#side-effects]

1. `prisma.gdprRequest.findUnique({ where: { id } })` selecting `id, userId, status, createdAt, completedAt`.
2. If row missing → throw `request_not_found`.
3. If `userId` mismatch → throw `not_owner`.
4. Return the slice. No mutations.

## Polling guidance [#polling-guidance]

* The worker pickup is on the order of seconds; total processing depends on dataset size (typically minutes).
* Recommended poll cadence: every 3–5 seconds while the dialog is open. Stop polling once `status === 'COMPLETED'` or `'FAILED'`.
* For large datasets, fall back to background polling (e.g., 30s) and surface a notification when done.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/gdpr/export/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type GdprExportStatus = {
      id: string;
      status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
      createdAt: string;
      completedAt: string | null;
    };

    async function getExportStatus(accessToken: string, id: string): Promise<GdprExportStatus> {
      const res = await fetch(`https://api.bio.re/api/v1/gdpr/export/${id}/status`, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Status check failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const gdprKeys = {
      exportStatus: (id: string) => ['gdpr', 'export', id, 'status'] as const,
    };

    export function useExportStatus(id: string) {
      return useQuery({
        queryKey: gdprKeys.exportStatus(id),
        queryFn: async () => {
          const res = await fetch(`/api/v1/gdpr/export/${id}/status`);
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Status check failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as GdprExportStatus;
        },
        enabled: Boolean(id),
        // Poll until terminal state, then stop
        refetchInterval: (query) => {
          const data = query.state.data;
          if (!data) return 5000;
          return data.status === 'COMPLETED' || data.status === 'FAILED' || data.status === 'CANCELLED'
            ? false
            : 5000;
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/gdpr/export/{id}/status', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                      | Lines                             |
| -------------- | --------------------------------------------------------- | --------------------------------- |
| Controller     | `apps/api-core/src/modules/user/gdpr.controller.ts`       | `44–55` (`getExportStatus`)       |
| DTO (response) | `apps/api-core/src/modules/user/dto/gdpr-response.dto.ts` | `22–37` (`GdprExportStatusDto`)   |
| Service        | `apps/api-core/src/modules/user/user.service.ts`          | `586–597` (`gdprGetExportStatus`) |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                    | `GDPRRequest`                     |


# Request Data Export (GDPR) (/docs/user/gdpr-export)



`POST /api/v1/gdpr/export` — 🔑 **Bearer** · Rate limit: **3 req / day**

Creates a `GDPRRequest` row of type `EXPORT` in `PENDING` state. A worker-service cron picks the row up, builds the export archive, writes a `DataExport` row, and flips the request status to `COMPLETED` (or `FAILED`). Clients poll `GET /gdpr/export/:id/status` until completion, then call `GET /gdpr/export/:id/download` for the signed URL.



<Callout type="info">
  This is the **modern** export endpoint. The legacy alias `POST /users/export` still exists for backward compatibility but only checks `PENDING` (not `PROCESSING`) when guarding against duplicates and returns the simpler `{ requestId }` shape. New clients should use this endpoint.
</Callout>

<Callout type="warn">
  Only one export can be in flight per user — if a `PENDING` or `PROCESSING` `GDPRRequest EXPORT` already exists, the call is rejected with `409 export_already_pending`. Wait for the previous one to complete (or hit the 3/day limit and try again tomorrow).
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<GdprExportRequestDto>` [#200-ok--apiresponseofgdprexportrequestdto]

```json
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "PENDING",
    "createdAt": "2026-04-29T20:00:00.000Z"
  }
}
```

| Field       | Type              | Notes                                                                                                        |
| ----------- | ----------------- | ------------------------------------------------------------------------------------------------------------ |
| `id`        | string (UUID)     | `GDPRRequest.id` — pass to status / download endpoints                                                       |
| `status`    | enum              | Always `PENDING` immediately after creation. Will progress through `PROCESSING` → `COMPLETED` (or `FAILED`). |
| `createdAt` | string (ISO 8601) | Server-side timestamp                                                                                        |

### Status lifecycle [#status-lifecycle]

| Status       | Set by           | Meaning                                               |
| ------------ | ---------------- | ----------------------------------------------------- |
| `PENDING`    | This endpoint    | Queued; worker hasn't started yet                     |
| `PROCESSING` | Worker           | Archive is being built                                |
| `COMPLETED`  | Worker           | Archive ready — `/download` will return a signed URL  |
| `FAILED`     | Worker           | Archive build failed — surface the request to support |
| `CANCELLED`  | (admin / system) | Operator-cancelled — never set by this endpoint       |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                  | Reason                                                 |
| ----- | ----------------------------------- | ------------------------------------------------------ |
| `401` | (guard)                             | Missing / invalid bearer token                         |
| `409` | `error.gdpr.export_already_pending` | A previous EXPORT request is `PENDING` or `PROCESSING` |
| `429` | (throttle)                          | Rate limit exceeded (3 req/day)                        |

## Side effects [#side-effects]

1. Look for an existing `GDPRRequest` for this user with `type = EXPORT` AND `status IN (PENDING, PROCESSING)`. If found, throw `export_already_pending`.
2. Insert `GDPRRequest { id: randomUUID(), userId, type: EXPORT, status: PENDING }`.
3. Audit log: `[gdpr] Self-service export requested by user {userId}: {id}`.
4. **The worker-service cron** scans for `PENDING` exports, builds the archive, writes a `DataExport` row with `fileUrl` and `expiresAt`, and flips the `GDPRRequest.status`. This pickup is asynchronous — typical completion is on the order of minutes; clients should poll `/gdpr/export/:id/status`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.bio.re/api/v1/gdpr/export \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type GdprStatus = 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';

    type GdprExportRequest = {
      id: string;
      status: GdprStatus;
      createdAt: string;
    };

    async function requestGdprExport(accessToken: string): Promise<GdprExportRequest> {
      const res = await fetch('https://api.bio.re/api/v1/gdpr/export', {
        method: 'POST',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Export request failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useRequestGdprExport() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async () => {
          const res = await fetch('/api/v1/gdpr/export', { method: 'POST' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Export request failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as GdprExportRequest;
        },
        onSuccess: (data) => {
          // Seed the status cache so the polling query starts with the freshly created row
          qc.setQueryData(['gdpr', 'export', data.id, 'status'], {
            id: data.id,
            status: data.status,
            createdAt: data.createdAt,
            completedAt: null,
          });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/gdpr/export', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                      | Lines                                                                      |
| -------------- | --------------------------------------------------------- | -------------------------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/user/gdpr.controller.ts`       | `32–42` (`requestExport`)                                                  |
| DTO (response) | `apps/api-core/src/modules/user/dto/gdpr-response.dto.ts` | `5–18` (`GdprExportRequestDto`)                                            |
| Service        | `apps/api-core/src/modules/user/user.service.ts`          | `561–581` (`gdprRequestExport`)                                            |
| Worker pickup  | `apps/worker-service/`                                    | cron scans `GDPRRequest` with `status = PENDING`                           |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                    | `GDPRRequest`, `DataExport`, `GDPRRequestType.EXPORT`, `GDPRRequestStatus` |


# Set User Intent (/docs/user/intent)



`PATCH /api/v1/users/intent` — 🔑 **Bearer**

Sets `User.intent` to `FAN` or `CREATOR`. **One-time only** — after the value is set, all subsequent calls return `400 intent_already_set`. The atomic `updateMany({ intent: null })` guard prevents a race between two concurrent requests.



<Callout type="info">
  After this succeeds, route the user accordingly: `FAN` → discovery feed, `CREATOR` → onboarding wizard. The flag never changes after the first set; account-type changes are out of scope for this endpoint.
</Callout>

## Request [#request]

### Body — `SetIntentDto` [#body--setintentdto]

| Field    | Type                | Required | Validation           | Notes                     |
| -------- | ------------------- | -------- | -------------------- | ------------------------- |
| `intent` | enum (`UserIntent`) | ✓        | `IsEnum(UserIntent)` | One of: `FAN` / `CREATOR` |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                |
| --------- | ------- | -------------------- |
| `success` | boolean | Always `true` on 200 |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`              | Reason                                                                  |
| ----- | ------------------------------- | ----------------------------------------------------------------------- |
| `400` | (DTO validation)                | `intent` not in the enum                                                |
| `400` | `error.user.intent_already_set` | `User.intent` is non-null — second call after the value was already set |
| `401` | (guard)                         | Missing / invalid bearer token                                          |
| `404` | `error.user.not_found`          | Token decoded but user row missing                                      |

## Side effects [#side-effects]

1. **Atomic check-and-set**: `prisma.user.updateMany({ where: { id, intent: null }, data: { intent } })`. If the row already had a non-null intent, `count = 0` and no write happens.
2. If `count = 0`, look up the user to distinguish "intent already set" from "user not found", then throw the matching error.
3. On success: increment `userIntentSetTotal` Prometheus counter (labelled by chosen intent).
4. Audit log: `[intent] User {userId} set intent: {intent}`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X PATCH https://api.bio.re/api/v1/users/intent \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"intent": "CREATOR"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type UserIntent = 'FAN' | 'CREATOR';

    async function setIntent(accessToken: string, intent: UserIntent): Promise<void> {
      const res = await fetch('https://api.bio.re/api/v1/users/intent', {
        method: 'PATCH',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ intent }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Set intent failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useSetIntent() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (intent: UserIntent) => {
          const res = await fetch('/api/v1/users/intent', {
            method: 'PATCH',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ intent }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Set intent failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['users', 'profile'] });
          qc.invalidateQueries({ queryKey: ['auth', 'me'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/intent', method: 'patch' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                  | Lines                                                |
| -------------- | ----------------------------------------------------- | ---------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/user/user.controller.ts`   | `92–99` (`setIntent`)                                |
| DTO (request)  | `apps/api-core/src/modules/user/dto/index.ts`         | `45–49` (`SetIntentDto`)                             |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts` | `SuccessOnlyResponseDto`                             |
| Service        | `apps/api-core/src/modules/user/user.service.ts`      | `223–241` (`setIntent`)                              |
| Prisma enum    | `packages/prisma/prisma/schema.prisma`                | `enum UserIntent` (`FAN` / `CREATOR`), `User.intent` |


# Update User Profile (/docs/user/profile-update)



`PATCH /api/v1/users/profile` — 🔑 **Bearer**

Patches a small slice of the user row — `displayName`, `bio`, `avatarUrl`. Sparse update: only the fields you send are touched. Returns the updated row (not the full profile — call `GET /users/profile` for the full read).



<Callout type="info">
  For avatar handling, prefer the dedicated `PATCH /users/avatar` (it also cleans up the previous file from object storage). Setting `avatarUrl` here works but does **not** delete the old file from storage.
</Callout>

## Request [#request]

### Body — `UpdateProfileDto` [#body--updateprofiledto]

All fields optional. Send only what you want to change.

| Field         | Type   | Validation       | Notes                                                     |
| ------------- | ------ | ---------------- | --------------------------------------------------------- |
| `displayName` | string | `MaxLength(100)` | Free-form display name                                    |
| `bio`         | string | `MaxLength(500)` | Free-form bio                                             |
| `avatarUrl`   | string | `IsUrl()`        | CDN URL — prefer `PATCH /users/avatar` for orphan cleanup |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<UpdatedProfileDto>` [#200-ok--apiresponseofupdatedprofiledto]

```json
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "displayName": "John Doe",
    "bio": "Software engineer.",
    "avatarUrl": "https://cdn.bio.re/avatars/abc.jpg",
    "username": "johndoe",
    "email": "user@example.com",
    "locale": "en"
  }
}
```

| Field         | Type           | Notes                                               |
| ------------- | -------------- | --------------------------------------------------- |
| `id`          | string (UUID)  | Account id                                          |
| `displayName` | string \| null | After update                                        |
| `bio`         | string \| null | After update                                        |
| `avatarUrl`   | string \| null | After update                                        |
| `username`    | string \| null | Echoed for convenience (unchanged by this endpoint) |
| `email`       | string         | Echoed (unchanged)                                  |
| `locale`      | string \| null | Echoed (unchanged)                                  |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`     | Reason                                                                    |
| ----- | ---------------------- | ------------------------------------------------------------------------- |
| `400` | (DTO validation)       | `displayName > 100` chars, `bio > 500` chars, `avatarUrl` not a valid URL |
| `401` | (guard)                | Missing / invalid bearer token                                            |
| `404` | `error.user.not_found` | Token decoded but user row missing                                        |

## Side effects [#side-effects]

1. Lookup `User`; if missing, throw `not_found`.
2. Build sparse `data` object from defined keys only.
3. **If no fields supplied**, return the existing user row unchanged (no DB write).
4. Otherwise: `prisma.user.update()` with the sparse data, return the fresh selected slice.
5. Audit log: `[profile] Updated for user {userId}`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X PATCH https://api.bio.re/api/v1/users/profile \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "displayName": "John Doe",
        "bio": "Software engineer."
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type UpdateProfileInput = {
      displayName?: string;
      bio?: string;
      avatarUrl?: string;
    };

    type UpdatedProfile = {
      id: string;
      displayName: string | null;
      bio: string | null;
      avatarUrl: string | null;
      username: string | null;
      email: string;
      locale: string | null;
    };

    async function updateProfile(accessToken: string, input: UpdateProfileInput): Promise<UpdatedProfile> {
      const res = await fetch('https://api.bio.re/api/v1/users/profile', {
        method: 'PATCH',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Update failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useUpdateProfile() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (input: UpdateProfileInput) => {
          const res = await fetch('/api/v1/users/profile', {
            method: 'PATCH',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Update failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as UpdatedProfile;
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['users', 'profile'] });
          qc.invalidateQueries({ queryKey: ['auth', 'me'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/profile', method: 'patch' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                             | Lines                                            |
| -------------- | ---------------------------------------------------------------- | ------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/user/user.controller.ts`              | `62–69` (`updateProfile`)                        |
| DTO (request)  | `apps/api-core/src/modules/user/dto/index.ts`                    | `34–43` (`UpdateProfileDto`)                     |
| DTO (response) | `apps/api-core/src/modules/user/dto/user-client-response.dto.ts` | `88–109` (`UpdatedProfileDto`)                   |
| Service        | `apps/api-core/src/modules/user/user.service.ts`                 | `61–80` (`updateProfile`)                        |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                           | `User.displayName`, `User.bio`, `User.avatarUrl` |


# Get User Profile (/docs/user/profile)



`GET /api/v1/users/profile` — 🔑 **Bearer**

Returns the full profile for the user resolved from the bearer token: identity fields, account flags (`twoFactorEnabled`, `isCreator`, `emailVerified`), linked OAuth accounts, and attribution metadata captured at registration.



<Callout type="info">
  This is heavier than `GET /auth/me`. `/auth/me` returns the lightweight identity slice for nav-bar / session checks; `/users/profile` returns the full row with social accounts and attribution. Use `/auth/me` for frequent polling, `/users/profile` for the account / settings screens.
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<UserProfileDto>` [#200-ok--apiresponseofuserprofiledto]

```json
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "user@example.com",
    "username": "johndoe",
    "displayName": "John Doe",
    "avatarUrl": "https://cdn.bio.re/avatars/abc.jpg",
    "bio": "Software engineer and creator.",
    "status": "ACTIVE",
    "emailVerified": true,
    "locale": "en",
    "lastLoginAt": "2026-04-29T19:00:00.000Z",
    "twoFactorEnabled": false,
    "createdAt": "2025-12-01T08:30:00.000Z",
    "isCreator": false,
    "socialAccounts": [
      {
        "platform": "INSTAGRAM",
        "platformUsername": "johndoe",
        "connectedAt": "2026-01-15T10:00:00.000Z"
      }
    ],
    "referralCode": "REF123",
    "firstReferrerUrl": "https://example.com/ref",
    "firstLandingPage": "/landing",
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "spring_promo",
    "registrationDevice": "mobile",
    "registrationCountry": "TR"
  }
}
```

### Fields [#fields]

| Field                                                                                           | Type                      | Notes                                                                 |
| ----------------------------------------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------- |
| `id`                                                                                            | string (UUID)             | Account id                                                            |
| `email`                                                                                         | string                    | Account email                                                         |
| `username`                                                                                      | string \| null            | `null` until first set via `PATCH /users/username`                    |
| `displayName`                                                                                   | string \| null            | Free-form display name                                                |
| `avatarUrl`                                                                                     | string \| null            | CDN URL of the current avatar                                         |
| `bio`                                                                                           | string \| null            | Free-form bio (max 500 chars)                                         |
| `status`                                                                                        | enum                      | `ACTIVE` / `SUSPENDED` / `BANNED` / `DEACTIVATED` / `DELETED`         |
| `emailVerified`                                                                                 | boolean                   | True after `POST /auth/verify-email`                                  |
| `locale`                                                                                        | string \| null            | Preferred locale code (e.g. `en`, `tr`)                               |
| `lastLoginAt`                                                                                   | string (ISO 8601) \| null | Most recent login timestamp                                           |
| `twoFactorEnabled`                                                                              | boolean                   | Mirrors `User.twoFactorEnabled`                                       |
| `createdAt`                                                                                     | string (ISO 8601)         | Account creation timestamp                                            |
| `isCreator`                                                                                     | boolean                   | `true` if a `CreatorProfile` row exists for this user                 |
| `socialAccounts`                                                                                | array                     | Linked OAuth accounts — `{ platform, platformUsername, connectedAt }` |
| `referralCode`                                                                                  | string \| null            | This user's own referral code                                         |
| `firstReferrerUrl` / `firstLandingPage` / `utm*` / `registrationDevice` / `registrationCountry` | string \| null            | Attribution snapshot captured at registration                         |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`     | Reason                                               |
| ----- | ---------------------- | ---------------------------------------------------- |
| `401` | (guard)                | Missing / invalid bearer token                       |
| `404` | `error.user.not_found` | Token decoded but user row missing (deleted account) |

## Side effects [#side-effects]

1. Single `prisma.user.findUnique()` with selected fields + relations (`creatorProfile.id`, `socialAccounts`).
2. `isCreator` derived from whether `creatorProfile` is non-null (the row itself isn't returned).
3. No mutations — pure read.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/users/profile \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type SocialAccount = {
      platform: string;
      platformUsername: string | null;
      connectedAt: string;
    };

    type UserProfile = {
      id: string;
      email: string;
      username: string | null;
      displayName: string | null;
      avatarUrl: string | null;
      bio: string | null;
      status: 'ACTIVE' | 'SUSPENDED' | 'BANNED' | 'DEACTIVATED' | 'DELETED';
      emailVerified: boolean;
      locale: string | null;
      lastLoginAt: string | null;
      twoFactorEnabled: boolean;
      createdAt: string;
      isCreator: boolean;
      socialAccounts: SocialAccount[];
      referralCode: string | null;
      firstReferrerUrl: string | null;
      firstLandingPage: string | null;
      utmSource: string | null;
      utmMedium: string | null;
      utmCampaign: string | null;
      registrationDevice: string | null;
      registrationCountry: string | null;
    };

    async function getProfile(accessToken: string): Promise<UserProfile> {
      const res = await fetch('https://api.bio.re/api/v1/users/profile', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Failed to load profile'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const userKeys = {
      profile: () => ['users', 'profile'] as const,
    };

    export function useProfile() {
      return useQuery({
        queryKey: userKeys.profile(),
        queryFn: async () => {
          const res = await fetch('/api/v1/users/profile');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Failed to load profile'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as UserProfile;
        },
        staleTime: 60_000, // 1 min — profile changes are user-triggered
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/profile', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                             | Lines                                                   |
| -------------- | ---------------------------------------------------------------- | ------------------------------------------------------- |
| Controller     | `apps/api-core/src/modules/user/user.controller.ts`              | `53–60` (`getProfile`)                                  |
| DTO (response) | `apps/api-core/src/modules/user/dto/user-client-response.dto.ts` | `18–84` (`UserProfileDto`), `5–14` (`SocialAccountDto`) |
| Service        | `apps/api-core/src/modules/user/user.service.ts`                 | `38–59` (`getProfile`)                                  |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                           | `User`, `CreatorProfile`, `SocialAccount`               |


# Reactivate Account (/docs/user/reactivate)



`POST /api/v1/users/reactivate` — 🔑 **Bearer** OR 🌐 **Token-bearer** · Rate limit: **10 req / hour**

Restores a `DEACTIVATED` account to `ACTIVE`. **Two auth modes** — the endpoint is decorated `@Public()` and resolves identity manually so the email-link landing page can call it without a session. If both a JWT and a token are presented, the **token wins**.



<Callout type="info">
  **Mode A — auth-session.** User has a valid bearer JWT (or `biore_session` cookie). Send an empty body. Reactivates the JWT subject.

  **Mode B — token-bearer.** User clicked an email link; no JWT is available. Send the opaque token via `X-Reactivate-Token` header **or** `{ "token": "..." }` body. The header takes precedence if both are present. Validate the token with `GET /auth/reactivate/validate` first to render the right landing UI before this `POST` is fired.
</Callout>

<Callout type="warn">
  If a pending `GDPRRequest DELETION` exists for this user, it is **cancelled** in the same transaction — clicking "Reactivate" before the grace period ends restores the account and aborts the scheduled deletion.
</Callout>

## Request [#request]

### Body — `ReactivateTokenBearerDto` [#body--reactivatetokenbearerdto]

All fields optional. Body is `{}` in auth-session mode.

| Field   | Type   | Required | Validation | Notes                                                                                              |
| ------- | ------ | -------- | ---------- | -------------------------------------------------------------------------------------------------- |
| `token` | string | optional | —          | Opaque reactivation token from the email link. Ignored if `X-Reactivate-Token` header is also set. |

### Headers [#headers]

| Header                                | Mode             | Notes                                                                                    |
| ------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------- |
| `Authorization: Bearer <accessToken>` | A — auth-session | JWT from `POST /auth/login`. Refresh-cookie `biore_session` also accepted as a fallback. |
| `X-Reactivate-Token: <token>`         | B — token-bearer | Wins over body's `token` field if both are sent.                                         |

If neither a token nor a JWT is found, the request is `401`.

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                |
| --------- | ------- | -------------------- |
| `success` | boolean | Always `true` on 200 |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`                   | Reason                                                                                 |
| ----- | ------------------------------------ | -------------------------------------------------------------------------------------- |
| `400` | `error.user.account_not_deactivated` | Account status is not `DEACTIVATED` (already ACTIVE, SUSPENDED, BANNED, or DELETED)    |
| `400` | (token validation)                   | Token malformed / expired / already used (consumed via `Challenge.usedAt` single-shot) |
| `401` | `error.guard.missing_auth_header`    | Both modes failed: no token AND no JWT                                                 |
| `401` | `error.guard.invalid_token`          | Auth-session mode: JWT failed signature verify or wrong token type                     |
| `404` | `error.user.not_found`               | Token resolved a userId but the user row is missing                                    |
| `429` | (throttle)                           | Rate limit exceeded (10 req/hour)                                                      |

## Side effects [#side-effects]

### Mode A — auth-session [#mode-a--auth-session]

1. Class-level `JwtAuthGuard` is **bypassed** by the `@Public()` metadata; identity is resolved manually.
2. Read `Authorization: Bearer <jwt>` header; fall back to `biore_session` cookie.
3. `jwtService.verify(jwt)` — accept only `type === 'access'` (or undefined).
4. Hand off to the shared reactivate path with the resolved `userId`.

### Mode B — token-bearer [#mode-b--token-bearer]

1. Read token from `X-Reactivate-Token` header; if absent, read `body.token`.
2. `challengeService.consumeReactivationToken(token)` — single-shot consume; returns `{ userId }`. Replays raise the underlying token-expired / already-used error.
3. Hand off to the shared reactivate path.

### Shared path (both modes) [#shared-path-both-modes]

1. Lookup `User`; throw `not_found` if missing.
2. Reject if `User.status !== 'DEACTIVATED'`.
3. **Inside one transaction**:
   * `UPDATE GDPRRequest SET status = CANCELLED WHERE userId = :userId AND type = DELETION AND status = PENDING` (cancels any scheduled deletion).
   * `User.status = ACTIVE`.
4. Audit log: `[account] AUDIT: Reactivated by user {userId}` (auth-session) or `Reactivated via token for user {userId}` (token-bearer).
5. **Existing sessions stay revoked.** The user must log in fresh after reactivation.

## Code samples [#code-samples]



<Tabs items="['curl (token)', 'curl (bearer)', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl (token)">
    ```bash
    # Mode B — token-bearer (from email link)
    curl -X POST https://api.bio.re/api/v1/users/reactivate \
      -H 'X-Reactivate-Token: abc123-from-email-link' \
      -H 'Content-Type: application/json' \
      -d '{}'
    ```
  </Tab>

  <Tab value="curl (bearer)">
    ```bash
    # Mode A — auth-session (logged-in user)
    curl -X POST https://api.bio.re/api/v1/users/reactivate \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type ReactivateMode =
      | { mode: 'session'; accessToken: string }
      | { mode: 'token'; token: string };

    async function reactivateAccount(input: ReactivateMode): Promise<void> {
      const headers: Record<string, string> = { 'Content-Type': 'application/json' };
      if (input.mode === 'session') {
        headers.Authorization = `Bearer ${input.accessToken}`;
      } else {
        headers['X-Reactivate-Token'] = input.token;
      }
      const res = await fetch('https://api.bio.re/api/v1/users/reactivate', {
        method: 'POST',
        headers,
        body: JSON.stringify({}),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Reactivate failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation } from '@tanstack/react-query';

    export function useReactivateAccount() {
      return useMutation({
        mutationFn: async (input: ReactivateMode) => {
          const headers: Record<string, string> = { 'Content-Type': 'application/json' };
          if (input.mode === 'token') {
            headers['X-Reactivate-Token'] = input.token;
          }
          // 'session' mode: rely on httpOnly biore_session cookie that the browser sends
          const res = await fetch('/api/v1/users/reactivate', {
            method: 'POST',
            headers,
            body: JSON.stringify({}),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Reactivate failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/reactivate', method: 'post' }]" hasHead="false" />

## Source [#source]

| Source                 | Path                                                            | Lines                                       |
| ---------------------- | --------------------------------------------------------------- | ------------------------------------------- |
| Controller             | `apps/api-core/src/modules/user/user.controller.ts`             | `169–221` (`reactivateAccount`, dual-mode)  |
| DTO (request)          | `apps/api-core/src/modules/auth/dto/reactivate-validate.dto.ts` | `ReactivateTokenBearerDto`                  |
| DTO (response)         | `apps/api-core/src/common/dto/common-response.dto.ts`           | `SuccessOnlyResponseDto`                    |
| Service (auth-session) | `apps/api-core/src/modules/user/user.service.ts`                | `426–445` (`reactivateAccount`)             |
| Service (token-bearer) | `apps/api-core/src/modules/user/user.service.ts`                | `455–477` (`reactivateByToken`)             |
| Token consume          | `apps/api-core/src/modules/auth/challenge.service.ts`           | `consumeReactivationToken()`                |
| Pre-flight             | `apps/api-core/src/modules/auth/auth.controller.ts`             | `407–423` (`GET /auth/reactivate/validate`) |
| Prisma models          | `packages/prisma/prisma/schema.prisma`                          | `User.status`, `GDPRRequest`, `Challenge`   |


# Update User Settings (/docs/user/settings-update)



`PATCH /api/v1/users/settings` — 🔑 **Bearer**

Sparse update — only fields present in the body are touched. If the user has no `UserSettings` row yet, one is created with the submitted values (and Prisma defaults filling the rest). When `locale` changes, the same value is also written back to the legacy `User.locale` field for backward compatibility.



<Callout type="info">
  **`UserSettings.locale` is the source of truth.** `User.locale` exists as a deprecated mirror for legacy code paths and is kept in sync by this endpoint when you patch `locale`. Frontend should always read locale from `/users/settings`, not `/users/profile`.
</Callout>

## Request [#request]

### Body — `UpdateSettingsDto` [#body--updatesettingsdto]

All fields optional. Send only what you want to change.

| Field                | Type    | Validation                        | Notes                          |
| -------------------- | ------- | --------------------------------- | ------------------------------ |
| `locale`             | string  | `MaxLength(10)`                   | e.g. `en`, `tr`, `pt-BR`       |
| `theme`              | string  | `MaxLength(20)`                   | e.g. `dark`, `light`, `system` |
| `emailNotifications` | boolean | —                                 |                                |
| `pushNotifications`  | boolean | —                                 |                                |
| `inAppNotifications` | boolean | —                                 |                                |
| `digestMode`         | string  | `IsIn(['DAILY','WEEKLY','NONE'])` |                                |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<UserSettingsDto>` [#200-ok--apiresponseofusersettingsdto]

Returns the **fresh** settings row after update (same shape as `GET /users/settings`):

```json
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userId": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
    "locale": "tr",
    "theme": "dark",
    "emailNotifications": true,
    "pushNotifications": false,
    "inAppNotifications": true,
    "digestMode": "WEEKLY",
    "createdAt": "2026-04-29T08:30:00.000Z",
    "updatedAt": "2026-04-29T20:00:00.000Z"
  }
}
```

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                                             |
| ----- | ------------------ | -------------------------------------------------- |
| `400` | (DTO validation)   | Invalid `digestMode` enum, fields exceeding length |
| `401` | (guard)            | Missing / invalid bearer token                     |

## Side effects [#side-effects]

1. Lookup existing `UserSettings` row (may be `null`).
2. Build sparse `data` object from defined keys only.
3. **If no fields supplied**, return the existing row unchanged (no DB write).
4. **Inside one transaction**:
   * If row exists: `prisma.userSettings.update({ where: { userId }, data })`.
   * If missing: `prisma.userSettings.create({ data: { id: randomUUID(), userId, ...data } })`.
   * **If `locale` was supplied**: also `prisma.user.update({ where: { id: userId }, data: { locale } })` (legacy mirror).
5. Audit log: `[settings] Updated for user {userId}`.
6. Return a fresh `findUnique` of the updated row — guarantees the response reflects the post-write state.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X PATCH https://api.bio.re/api/v1/users/settings \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "locale": "tr",
        "pushNotifications": false,
        "digestMode": "WEEKLY"
      }'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type UpdateSettingsInput = {
      locale?: string;
      theme?: string;
      emailNotifications?: boolean;
      pushNotifications?: boolean;
      inAppNotifications?: boolean;
      digestMode?: 'DAILY' | 'WEEKLY' | 'NONE';
    };

    async function updateSettings(accessToken: string, input: UpdateSettingsInput): Promise<UserSettings> {
      const res = await fetch('https://api.bio.re/api/v1/users/settings', {
        method: 'PATCH',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Update settings failed'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useUpdateSettings() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (input: UpdateSettingsInput) => {
          const res = await fetch('/api/v1/users/settings', {
            method: 'PATCH',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(input),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Update settings failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as UserSettings;
        },
        onSuccess: (data) => {
          // Write-through cache: settings is the canonical source, profile mirrors locale
          qc.setQueryData(['users', 'settings'], data);
          qc.invalidateQueries({ queryKey: ['users', 'profile'] });
          qc.invalidateQueries({ queryKey: ['auth', 'me'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/settings', method: 'patch' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                             | Lines                                         |
| -------------- | ---------------------------------------------------------------- | --------------------------------------------- |
| Controller     | `apps/api-core/src/modules/user/user.controller.ts`              | `147–154` (`updateSettings`)                  |
| DTO (request)  | `apps/api-core/src/modules/user/dto/index.ts`                    | `51–69` (`UpdateSettingsDto`)                 |
| DTO (response) | `apps/api-core/src/modules/user/dto/user-client-response.dto.ts` | `134–164` (`UserSettingsDto`)                 |
| Service        | `apps/api-core/src/modules/user/user.service.ts`                 | `362–392` (`updateSettings`)                  |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                           | `UserSettings`, `User.locale` (legacy mirror) |


# Get User Settings (/docs/user/settings)



`GET /api/v1/users/settings` — 🔑 **Bearer**

Returns the `UserSettings` row for the current user. **Lazy bootstrap** — if the row doesn't exist yet, the server creates it with defaults on this read and returns the freshly created row, so the client never has to special-case `null`.



<Callout type="info">
  `UserSettings` is a separate table from `User`, joined by `userId`. Defaults are applied at the Prisma level (model defaults) — `emailNotifications`, `pushNotifications`, `inAppNotifications` default to `true`, `locale` / `theme` / `digestMode` default to `null` (UI falls back to product-level defaults).
</Callout>

## Request [#request]

No body, no params.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `ApiResponseOf<UserSettingsDto>` [#200-ok--apiresponseofusersettingsdto]

```json
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userId": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
    "locale": "en",
    "theme": "dark",
    "emailNotifications": true,
    "pushNotifications": true,
    "inAppNotifications": true,
    "digestMode": "DAILY",
    "createdAt": "2026-04-29T08:30:00.000Z",
    "updatedAt": "2026-04-29T19:00:00.000Z"
  }
}
```

| Field                | Type              | Notes                                                                                         |
| -------------------- | ----------------- | --------------------------------------------------------------------------------------------- |
| `id`                 | string (UUID)     | Settings row id                                                                               |
| `userId`             | string (UUID)     | Owning user id (matches the bearer token's `sub`)                                             |
| `locale`             | string \| null    | Preferred locale code (e.g. `en`, `tr`) — also written back to legacy `User.locale` on update |
| `theme`              | string \| null    | UI theme tag (e.g. `dark`, `light`, `system`)                                                 |
| `emailNotifications` | boolean           | Defaults to `true`                                                                            |
| `pushNotifications`  | boolean           | Defaults to `true`                                                                            |
| `inAppNotifications` | boolean           | Defaults to `true`                                                                            |
| `digestMode`         | enum \| null      | One of: `DAILY` / `WEEKLY` / `NONE`                                                           |
| `createdAt`          | string (ISO 8601) | Settings row creation timestamp                                                               |
| `updatedAt`          | string (ISO 8601) | Last update timestamp                                                                         |

### Errors [#errors]

| HTTP  | `code` / `i18nKey` | Reason                         |
| ----- | ------------------ | ------------------------------ |
| `401` | (guard)            | Missing / invalid bearer token |

## Side effects [#side-effects]

1. `prisma.userSettings.findUnique({ where: { userId } })`.
2. **If missing** (first access): `prisma.userSettings.create({ data: { id: randomUUID(), userId } })` — Prisma applies model-level defaults; this is the only write this endpoint may perform.
3. Return the row. No mutations on subsequent reads.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl https://api.bio.re/api/v1/users/settings \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type DigestMode = 'DAILY' | 'WEEKLY' | 'NONE';

    type UserSettings = {
      id: string;
      userId: string;
      locale: string | null;
      theme: string | null;
      emailNotifications: boolean;
      pushNotifications: boolean;
      inAppNotifications: boolean;
      digestMode: DigestMode | null;
      createdAt: string;
      updatedAt: string;
    };

    async function getSettings(accessToken: string): Promise<UserSettings> {
      const res = await fetch('https://api.bio.re/api/v1/users/settings', {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Failed to load settings'), {
          code: json?.error?.code,
        });
      }
      return json.data;
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useQuery } from '@tanstack/react-query';

    export const userKeys = {
      settings: () => ['users', 'settings'] as const,
    };

    export function useSettings() {
      return useQuery({
        queryKey: userKeys.settings(),
        queryFn: async () => {
          const res = await fetch('/api/v1/users/settings');
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Failed to load settings'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
          return json.data as UserSettings;
        },
        staleTime: 60_000,
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/settings', method: 'get' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                             | Lines                         |
| -------------- | ---------------------------------------------------------------- | ----------------------------- |
| Controller     | `apps/api-core/src/modules/user/user.controller.ts`              | `139–145` (`getSettings`)     |
| DTO (response) | `apps/api-core/src/modules/user/dto/user-client-response.dto.ts` | `134–164` (`UserSettingsDto`) |
| Service        | `apps/api-core/src/modules/user/user.service.ts`                 | `351–360` (`getSettings`)     |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                           | `UserSettings`                |


# Unblock a User (/docs/user/unblock)



`DELETE /api/v1/users/block/:userId` — 🔑 **Bearer**

Removes the `BlockList` row for the `(ownerId, blockedId)` pair. **Not idempotent** — if no row exists, returns `404 user.block.not_blocked` so the caller knows nothing changed. The opposite direction (other user blocking this user) is unaffected.



<Callout type="info">
  The path mirrors `POST /users/block/:userId` exactly — same param, same auth. Method (POST vs DELETE) is the only differentiator.
</Callout>

## Request [#request]

### Path parameters [#path-parameters]

| Param    | Type          | Validation      | Notes               |
| -------- | ------------- | --------------- | ------------------- |
| `userId` | string (UUID) | `ParseUUIDPipe` | The user to unblock |

No body.

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                |
| --------- | ------- | -------------------- |
| `success` | boolean | Always `true` on 200 |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`       | Reason                                                |
| ----- | ------------------------ | ----------------------------------------------------- |
| `400` | (validation)             | `userId` not a valid UUID                             |
| `401` | (guard)                  | Missing / invalid bearer token                        |
| `404` | `user.block.not_blocked` | No `BlockList` row exists for this owner/blocked pair |

## Side effects [#side-effects]

1. `prisma.blockList.findFirst({ where: { ownerId, blockedId } })`. If absent → `not_blocked`.
2. `prisma.blockList.delete({ where: { id: existing.id } })`.
3. Audit log (info level): `[block] User {ownerId} unblocked {blockedId}`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X DELETE https://api.bio.re/api/v1/users/block/f0e1d2c3-b4a5-6789-0123-456789abcdef \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    async function unblockUser(accessToken: string, blockedUserId: string): Promise<void> {
      const res = await fetch(`https://api.bio.re/api/v1/users/block/${blockedUserId}`, {
        method: 'DELETE',
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Unblock failed'), {
          code: json?.error?.code,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useUnblockUser() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (blockedUserId: string) => {
          const res = await fetch(`/api/v1/users/block/${blockedUserId}`, { method: 'DELETE' });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Unblock failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['users', 'blocked'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/block/{userId}', method: 'delete' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                  | Lines                     |
| -------------- | ----------------------------------------------------- | ------------------------- |
| Controller     | `apps/api-core/src/modules/user/user.controller.ts`   | `298–306` (`unblockUser`) |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts` | `SuccessOnlyResponseDto`  |
| Service        | `apps/api-core/src/modules/user/user.service.ts`      | `779–786` (`unblockUser`) |
| Prisma model   | `packages/prisma/prisma/schema.prisma`                | `BlockList`               |


# Change Username (/docs/user/username)



`PATCH /api/v1/users/username` — 🔑 **Bearer** · Rate limit: **5 req / hour**

Sets or rotates `User.username`. Format-validates against admin-configurable bounds (`site.username_min_length`, `site.username_max_length`, default 3–30, lowercase alphanumeric + `._-`), enforces a per-user cooldown after each change (`username.change_cooldown_days`, default 30), checks the desired value against active users + the reserved-name list, and writes a `UsernameHistory` row for audit.



<Callout type="info">
  **First-time set has no cooldown.** If the user has never set a username (`User.username = null`), the cooldown check is skipped — they can claim a name on signup-completion flows without waiting.
</Callout>

<Callout type="warn">
  The `error.user.username_cooldown` error includes a `daysLeft` payload param so the UI can render `"Try again in 7 days"` without re-fetching the change history.
</Callout>

## Request [#request]

### Body — `ChangeUsernameDto` [#body--changeusernamedto]

| Field      | Type   | Required | Validation                            | Notes                                                                                                                                                                       |
| ---------- | ------ | -------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `username` | string | ✓        | min 3, max 30, regex `^[a-z0-9._-]+$` | Lowercase only — server normalizes via `.toLowerCase().trim()`. The DTO bounds match defaults; admin can widen via `site.username_min_length` / `site.username_max_length`. |

| Header                                | Required | Notes                       |
| ------------------------------------- | -------- | --------------------------- |
| `Authorization: Bearer <accessToken>` | ✓        | JWT from `POST /auth/login` |

## Response [#response]

### `200 OK` — `SuccessOnlyResponseDto` [#200-ok--successonlyresponsedto]

```json
{
  "success": true
}
```

| Field     | Type    | Notes                |
| --------- | ------- | -------------------- |
| `success` | boolean | Always `true` on 200 |

### Errors [#errors]

| HTTP  | `code` / `i18nKey`             | Payload params       | Reason                                                                                           |
| ----- | ------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------ |
| `400` | `error.user.username_length`   | `{ minLen, maxLen }` | Outside admin-configured length bounds                                                           |
| `400` | `error.user.username_format`   | —                    | Failed regex (must be lowercase alphanumeric + `._-`)                                            |
| `400` | `error.user.username_same`     | —                    | The submitted value equals the current `User.username` (only checked for non-first-time set)     |
| `400` | `error.user.username_cooldown` | `{ daysLeft }`       | Last change is within the cooldown window                                                        |
| `401` | (guard)                        | —                    | Missing / invalid bearer token                                                                   |
| `404` | `error.user.not_found`         | —                    | Token decoded but user row missing                                                               |
| `409` | `error.user.username_taken`    | —                    | Already taken by another user OR matches a reserved name OR concurrent claim race (Prisma P2002) |
| `429` | (throttle)                     | —                    | Rate limit exceeded (5 req/hour)                                                                 |

## Side effects [#side-effects]

1. Normalize submitted value (`.toLowerCase().trim()`).
2. Length check against `site.username_min_length` / `site.username_max_length` (admin-managed defaults 3 / 30).
3. Format check against `^[a-z0-9._-]+$`.
4. Lookup `User`; throw `not_found` if missing.
5. Determine `isFirstSet = (user.username === null)`. Cooldown checks below skip when first-set.
6. Reject if value equals current username (`username_same`).
7. **Cooldown check** — read `usernameHistory` (most recent `changedAt`); if within `username.change_cooldown_days` (default 30), throw `username_cooldown` with `{ daysLeft }`.
8. Availability check — `prisma.user.findUnique({ where: { username } })` AND `prisma.reservedUsername.findUnique`; throw `username_taken` if either hits.
9. **Inside one transaction**:
   * Insert `UsernameHistory { oldUsername, newUsername, changedAt: now() }`.
   * Update `User.username = normalized`.
   * On Prisma `P2002` (concurrent claim race), throw `username_taken`.
10. Audit log: `[username] Changed: <old> → <new> (user {userId})`.

## Code samples [#code-samples]



<Tabs items="['curl', 'TypeScript fetch', 'TanStack Query']">
  <Tab value="curl">
    ```bash
    curl -X PATCH https://api.bio.re/api/v1/users/username \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"username": "johndoe"}'
    ```
  </Tab>

  <Tab value="TypeScript fetch">
    ```ts
    type UsernameError = {
      code:
        | 'error.user.username_length'
        | 'error.user.username_format'
        | 'error.user.username_same'
        | 'error.user.username_cooldown'
        | 'error.user.username_taken'
        | 'error.user.not_found';
      daysLeft?: number;     // present when code === 'error.user.username_cooldown'
      minLen?: number;       // present when code === 'error.user.username_length'
      maxLen?: number;       // present when code === 'error.user.username_length'
    };

    async function changeUsername(accessToken: string, username: string): Promise<void> {
      const res = await fetch('https://api.bio.re/api/v1/users/username', {
        method: 'PATCH',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ username }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Change username failed'), {
          code: json?.error?.code,
          daysLeft: json?.error?.daysLeft,
          minLen: json?.error?.minLen,
          maxLen: json?.error?.maxLen,
        });
      }
    }
    ```
  </Tab>

  <Tab value="TanStack Query">
    ```ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';

    export function useChangeUsername() {
      const qc = useQueryClient();
      return useMutation({
        mutationFn: async (username: string) => {
          const res = await fetch('/api/v1/users/username', {
            method: 'PATCH',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ username }),
          });
          const json = await res.json();
          if (!res.ok || !json.success) {
            throw Object.assign(new Error(json?.error?.message ?? 'Change username failed'), {
              code: json?.error?.code,
              i18nKey: json?.error?.i18nKey,
              // Cooldown errors carry daysLeft for UI rendering
              daysLeft: json?.error?.daysLeft,
            });
          }
        },
        onSuccess: () => {
          qc.invalidateQueries({ queryKey: ['users', 'profile'] });
          qc.invalidateQueries({ queryKey: ['auth', 'me'] });
        },
      });
    }
    ```
  </Tab>
</Tabs>

## Try it [#try-it]

<APIPage document="./public/openapi/full.json" operations="[{ path: '/api/v1/users/username', method: 'patch' }]" hasHead="false" />

## Source [#source]

| Source         | Path                                                  | Lines                                                  |
| -------------- | ----------------------------------------------------- | ------------------------------------------------------ |
| Controller     | `apps/api-core/src/modules/user/user.controller.ts`   | `103–112` (`changeUsername`)                           |
| DTO (request)  | `apps/api-core/src/modules/user/dto/index.ts`         | `9–14` (`ChangeUsernameDto`)                           |
| DTO (response) | `apps/api-core/src/common/dto/common-response.dto.ts` | `SuccessOnlyResponseDto`                               |
| Service        | `apps/api-core/src/modules/user/user.service.ts`      | `145–217` (`changeUsername`)                           |
| Prisma models  | `packages/prisma/prisma/schema.prisma`                | `User.username`, `UsernameHistory`, `ReservedUsername` |