Merge branch 'B2B'

docs/backend/FRONTEND-API-SURFACE-COMPLETE.md

@@ -1,6 +1,6 @@
 # Complete Frontend API Surface — Master Endpoint List
 
-Generated 2026-08-18, updated same day after the frontend backlog (F1–F65) closed. Directly from source (every `this.http.get/post/patch/put/delete` call across `src/app/core/`, `src/app/features/admin/`, `src/app/services/api.service.ts`). This is not a design document — it is a **census**: every endpoint this codebase currently calls or will call once its gateway swap goes live, in one place, cross-referenced against the contracts that already exist.
+Generated 2026-08-18, updated same day after the frontend backlog (F1–F65) closed, updated again same day to add §0 after a direct question ("everything is there? payment auth?") caught that the first pass only grepped `src/app/` — auth moved into the external `@marketplaces/auth` package this session, and its own HTTP calls (§0) were missing from what this doc called "complete." Fixed by grepping `node_modules/@marketplaces/auth/dist/` directly. Directly from source (every `this.http.get/post/patch/put/delete` call across `src/app/core/`, `src/app/features/admin/`, `src/app/services/api.service.ts`, and now the auth package). This is not a design document — it is a **census**: every endpoint this codebase currently calls or will call once its gateway swap goes live, in one place, cross-referenced against the contracts that already exist.
 
 **This is the final handoff doc for this pass.** Frontend work is done except one item that genuinely cannot be finished without a live backend (§19). Everything else — every gateway, every model, every invariant — is written, tested, and pushed. What follows is everything backend needs to make it real.
 
@@ -16,6 +16,41 @@ Generated 2026-08-18, updated same day after the frontend backlog (F1–F65) clo
 
 ---
 
+## 0. Auth — lives in `@marketplaces/auth`, not this repo, and payment authorization runs through it
+
+Two separate, real mechanisms. Both are called from the external package (`node_modules/@marketplaces/auth/dist/`), which is why §0 didn't exist in the first pass of this doc — that pass only grepped `src/app/`.
+
+### 0.1 Telegram QR/session — ✅ Specified, **live**
+
+Per `BACKEND-HANDOFF.md` §3 and `PACKAGES-USAGE.md`. **Customer and admin login call the same endpoints** — only client-side storage differs, which is exactly why every admin endpoint must independently verify authorization server-side (stated plainly in `BACKEND-HANDOFF.md` §3 as "the single most serious open issue in the system").
+
+| Method | Path | Purpose |
+|---|---|---|
+| POST | `{authApiUrl}/users/sessions` | create a session from a Telegram login |
+| GET | `{authApiUrl}/users/sessions/{id}` | poll / check session status |
+| DELETE | `{authApiUrl}/users/sessions/{id}` | log out |
+
+Expected response: `{ webSessionID, user: { userId, username, firstName, lastName }, status, expiresAt }` — parsed permissively client-side (many key-name variants accepted), but a clean backend implementation should return exactly this shape.
+
+### 0.2 Ed25519 admin challenge/response — specified, **not built**
+
+Per `BACKEND-HANDOFF.md` §3 and the package's own `ed25519/models/auth-api.model.ts`. This is what backend-authorizes an admin session distinctly from a customer one, and it does not exist server-side yet — every request today shows a `backend-unavailable` screen once the client reaches for it, nothing is mocked.
+
+| Method | Path |
+|---|---|
+| GET | `/api/admin/auth/challenge` |
+| POST | `/api/admin/auth/verify` |
+| POST | `/api/admin/auth/refresh` |
+| POST | `/api/admin/auth/logout` |
+
+### 0.3 What this has to do with payment
+
+There is no separate "payment login." Authorization for anything payment-adjacent — creating a checkout session, viewing `GET /api/admin/v2/orders/{id}`'s pricing breakdown (§20), touching a partner credential (§16) — rides on whichever of the two sessions above is active. The partner-provisioning API (§16) has its **own**, separate signed-request auth (§6 of that contract, public-key based, no session token at all) — that one is unrelated to Telegram/ed25519 and is not a gap, it's a different, already-built mechanism for a different caller (partners, not our own admins or customers).
+
+**The actual payment gap is §1 below, not auth**: QR/card payment creation and status polling are real, live, and completely undocumented anywhere in `docs/backend/`.
+
+---
+
 ## 1. Legacy surface (still called today, no `/api/v2` contract)
 
 These come from `BACKEND-API-REFERENCE.md`, not `docs/backend/`. Base URL is `environment.localhostApiUrl` / tenant-resolved; `qrBaseUrl` is a separate provider base for QR-specific calls.
@@ -336,15 +371,18 @@ The frontend added a client-side guard against double-submitting checkout (a rea
 
 | Status | Count |
 |---|---|
-| ✅ Specified | 51 |
+| ✅ Specified | 54 |
 | ⚠️ Inferred (needs confirmation) | 24 |
 | ❌ Undocumented (legacy) | 15 |
-| **Total distinct endpoints called** | **90** |
+| **Total distinct endpoints called** | **97** |
+
+(§0's 3 Telegram endpoints count as Specified+live; its 4 ed25519 endpoints count as Specified+not-built — both are real, named endpoints with a known shape, distinct from §1's "no contract exists anywhere" undocumented status.)
 
 Plus 3 response-shape additions (§19–21) on existing endpoints — not new endpoints, new optional fields on responses those endpoints already return.
 
 ## What backend needs to do with this
 
+0. **§0.2 first, ahead of everything else on this list.** The 4 ed25519 admin auth endpoints are the single most serious open issue named anywhere in `docs/backend/` (`BACKEND-HANDOFF.md` §3's own words). Every other item below assumes an admin session exists to authorize the request — that session mechanism does not exist server-side yet.
 1. **Build the ✅ rows as written** — they match an existing contract doc exactly. This includes §18's 4 revision endpoints, pending confirmation on the `validated`/`preview` ambiguity called out there.
 2. **Confirm or correct every ⚠️ row** — each one has a comment at its call site in source explaining the inference. Search the codebase for `Inferred` to find all 24 in place, with the reasoning right next to the code.
 3. **Populate the 3 optional field sets (§19–21)** on the endpoints that already exist — `routing` and pricing-breakdown fields on `GET /api/admin/v2/orders/{id}`, the 8 metric fields on `GET /api/admin/v2/dashboard/metrics`. Nothing on the frontend breaks while these are absent; nothing shows the real data either.