Initial commit: nick docs

03 - API Reference/Admin API.md

@@ -0,0 +1,143 @@
+---
+title: Admin API
+tags: [api, admin, reference]
+---
+
+# Admin API
+
+There is no single `/api/admin` namespace — admin-only endpoints are scattered across the service routers. This page catalogs them in one place. All require `Bearer JWT` with `req.user.role === 'admin'`. The two enforcement patterns are:
+
+- Middleware: `authorizeRoles('admin')` after `authenticateToken` (used by the dispute, data-cleanup, blog routers).
+- Inline check inside the handler: `if (req.user.role !== 'admin') return 403` (used by user, points, payment routes).
+
+## User management
+
+See full descriptions in [[User API]].
+
+| Endpoint | Action |
+| --- | --- |
+| `POST /api/user/admin/create` | Create user with role/status |
+| `DELETE /api/user/admin/:userId` | Delete user (admins cannot delete each other) |
+| `PATCH /api/user/admin/:userId/status` | Activate / suspend |
+| `PATCH /api/user/admin/:userId/toggle-status` | Flip active flag |
+| `PATCH /api/user/admin/:userId/role` | Change role |
+| `GET /api/user/admin/list` | Paginated directory + stats |
+| `GET /api/user/admin/:userId/dependencies` | Pre-delete dependency check |
+| `GET /api/users/admin/stats` | Aggregate user analytics |
+| `GET /api/users/admin/:userId` | Full user detail (admin view) |
+| `PUT /api/users/admin/:userId` | Mass update user |
+| `PUT /api/users/admin/update/:email` | Mass update by email |
+| `PATCH /api/users/admin/:userId/password` | Force password reset (wipes refresh tokens) |
+| `POST /api/users/admin/:userId/resend-verification` | Resend verification email |
+
+## Listing / marketplace moderation
+
+See [[Marketplace API]]. Admins can use most marketplace endpoints with elevated privileges (e.g. delete any purchase request, override offer status). Specific admin-only actions:
+
+| Endpoint | Action |
+| --- | --- |
+| `PUT /api/marketplace/offers/:id/status` | Direct status mutation including admin overrides |
+| `POST /api/marketplace/purchase-requests/:id/release-payment` | Force escrow release |
+| `PATCH /api/marketplace/purchase-requests/:id/status` (any → any) | Override request state machine |
+
+Template approval is implicit: admins use the same template CRUD endpoints with override privileges.
+
+## Dispute mediation
+
+See [[Dispute API]].
+
+| Endpoint | Action |
+| --- | --- |
+| `POST /api/disputes/:id/assign` | Assign moderator |
+| `PATCH /api/disputes/:id/status` | Update status |
+| `POST /api/disputes/:id/resolve` | Final decision (buyer / seller / split) |
+| `GET /api/disputes/statistics` | Admin dashboard data |
+
+## Manual payment operations
+
+See [[Payment API]].
+
+| Endpoint | Action |
+| --- | --- |
+| `POST /api/payment/payments/cleanup-pending` | Delete stale pending payments |
+| `POST /api/payment/payments/:id/fetch-tx` | Re-query chain for missing tx hash |
+| `POST /api/payment/payments/auto-fetch-missing` | Batch tx-hash backfill |
+| `POST /api/payment/shkeeper/:id/release` | Build escrow-release tx |
+| `POST /api/payment/shkeeper/:id/release/confirm` | Confirm release tx hash |
+| `POST /api/payment/shkeeper/:id/refund` | Build refund tx |
+| `POST /api/payment/shkeeper/:id/refund/confirm` | Confirm refund tx hash |
+| `POST /api/payment/shkeeper/payout` | Create payout task |
+| `GET /api/payment/shkeeper/webhook-stats` | Webhook telemetry |
+| `POST /api/payment/decentralized/admin-payout` | Direct admin-wallet payout |
+
+## Points (admin)
+
+See [[Points API]].
+
+| Endpoint | Action |
+| --- | --- |
+| `POST /api/points/admin/add` | Manually grant / deduct points for a user |
+
+## Data cleanup
+
+Router: [`backend/src/services/admin/dataCleanupRoutes.ts`](../../backend/src/services/admin/dataCleanupRoutes.ts). Mounted under `/api/admin/cleanup/*`. The router applies `authenticateToken` + `authorizeRoles('admin')` to every endpoint.
+
+### GET /api/admin/cleanup/stats
+
+**Description:** Per-collection document counts and sizes.
+**Response 200:** `{ success, data: { collections: [{ name, count, sizeBytes }] } }`
+
+### GET /api/admin/cleanup/collections
+
+**Description:** List collections that can be cleaned and the supported flags.
+**Response 200:** `{ success, data: { collections, options } }`
+
+### POST /api/admin/cleanup/clean
+
+**Description:** Bulk delete records. Defaults to `dryRun: true` and `keepAdmins: true`.
+**Request body:**
+```ts
+{
+  collections?: string[];        // default ["all"]
+  dryRun?: boolean;              // default true
+  keepAdmins?: boolean;          // default true
+  olderThanDays?: number;        // optional age filter
+  confirm?: "DELETE_ALL_DATA";   // required for actual deletion
+}
+```
+**Response 200:** `{ success, data: { deletedCounts, dryRun } }`
+
+### DELETE /api/admin/cleanup/user/:userId
+
+**Description:** Cascade-delete all data for a specific user (GDPR). Requires `?confirm=DELETE_USER_DATA` for real execution.
+**Query params:** `dryRun=true|false`, `confirm=DELETE_USER_DATA`
+
+### POST /api/admin/cleanup/temp
+
+**Description:** Purge temporary data older than N hours (verification codes, file temp uploads).
+**Request body:** `{ olderThanHours?: number }` (default 24)
+
+### POST /api/admin/cleanup/seed-templates
+
+**Description:** Re-runs the request templates seeder (production safe; idempotent).
+
+### POST /api/admin/cleanup/seed-all
+
+**Description:** Seeds users, addresses, and templates in dependency order. Used to bootstrap a fresh staging environment.
+
+## Analytics
+
+There is no dedicated analytics router. Admin dashboards stitch together:
+
+- `GET /api/users/admin/stats` (user metrics)
+- `GET /api/payment/stats` (payment aggregates)
+- `GET /api/disputes/statistics` (dispute KPIs)
+- `GET /api/admin/cleanup/stats` (collection sizes)
+- `GET /api/payment/shkeeper/webhook-stats` (provider health)
+- `GET /api/payment/shkeeper/wallet-monitor/status` (chain monitor)
+
+## Related
+
+- [[Admin Console Architecture]]
+- [[Authorization Model]]
+- [[Error Codes]]