Add customer contact fields and admin API docs (refs #41)

2025-10-14 18:29:21 +02:00
parent 8f297e25c4
commit 775c5159ea
21 changed files with 1124 additions and 103 deletions
@@ -0,0 +1,147 @@
+# PicPeak Admin API Quickstart
+
+This guide explains how to authenticate against the PicPeak Admin API, use the OpenAPI documentation, and exercise the three automation endpoints (`create event`, `photo upload`, `resend email`) that now ship with machine-readable docs.
+
+> **Prerequisites**
+>
+> - PicPeak backend running (Docker or local `node backend/server.js`)
+> - An admin account (see `data/ADMIN_CREDENTIALS.txt` for the seeded defaults)
+> - API base URL (defaults to `http://localhost:3001/api`)
+
+---
+
+## 1. Obtain an Admin API Token
+
+1. Determine whether reCAPTCHA is enabled in **Admin → Settings → Security**. If disabled (the default), you can skip the `recaptchaToken` field shown below.
+2. Authenticate with your admin username/email and password:
+
+```bash
+curl --fail --silent --show-error \
+  -X POST "http://localhost:3001/api/auth/admin/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username": "admin",
+    "password": "BoldTiger5872%",
+    "recaptchaToken": ""
+  }' | jq
+```
+
+Successful responses look like:
+
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "user": {
+    "id": 1,
+    "username": "admin",
+    "email": "admin@example.com",
+    "mustChangePassword": false
+  }
+}
+```
+
+- PicPeak also sets the `admin_token` cookie; however, when scripting you typically pass the token in an `Authorization: Bearer <token>` header.
+- Tokens expire after 24 hours. Log in again to refresh them.
+
+---
+
+## 2. Use the OpenAPI Documentation
+
+The machine-readable spec lives at `docs/picpeak-admin-api.openapi.yaml`. You can:
+
+- Preview it interactively with Redocly:
+
+  ```bash
+  npx --yes @redocly/cli preview-docs docs/picpeak-admin-api.openapi.yaml
+  ```
+
+- Import it into Postman, Insomnia, or VS Code REST client.
+- Validate changes as part of CI with:
+
+  ```bash
+  npx --yes @apidevtools/swagger-cli@4.0.4 validate docs/picpeak-admin-api.openapi.yaml
+  ```
+
+Keep this file in sync whenever the backend endpoints evolve.
+
+---
+
+## 3. Call the Key Admin Endpoints
+
+Below are minimal `curl` examples that rely on the bearer token captured earlier.
+
+### 3.1 Create an Event
+
+```bash
+API_URL="http://localhost:3001/api"
+TOKEN="REPLACE_WITH_JWT"
+
+curl --fail --silent --show-error \
+  -X POST "$API_URL/admin/events" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "event_type": "wedding",
+    "event_name": "Emily & Jordan Celebration",
+    "event_date": "2025-06-07",
+    "customer_name": "Emily Carter",
+    "customer_email": "emily@example.com",
+    "admin_email": "studio@example.com",
+    "require_password": true,
+    "password": "Shutter123",
+    "expiration_days": 45
+  }' | jq
+```
+
+### 3.2 Upload Photos to the Event
+
+```bash
+EVENT_ID=512
+
+curl --fail --silent --show-error \
+  -X POST "$API_URL/admin/events/$EVENT_ID/upload" \
+  -H "Authorization: Bearer $TOKEN" \
+  -F "photos=@/path/to/DSC_2031.jpg" \
+  -F "photos=@/path/to/DSC_2032.jpg" \
+  -F "category_id=individual" | jq
+```
+
+- Files must be JPEG/PNG/WebP, each ≤ 50 MB.
+- The per-request file count respects the `general_max_files_per_upload` admin setting (default 500).
+
+### 3.3 Resend the Gallery Email
+
+```bash
+curl --fail --silent --show-error \
+  -X POST "$API_URL/admin/events/$EVENT_ID/resend-email" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"password": "Shutter123"}' | jq
+```
+
+Omit `"password"` to send the standard security message instead.
+
+---
+
+## 4. Quick Testing Checklist
+
+- ✅ Login succeeds and returns a token (HTTP 200).
+- ✅ Creating an event returns `id`, `slug`, and `share_link`.
+- ✅ Uploading more files than allowed returns HTTP 400 with a helpful message.
+- ✅ Resending email for a missing event returns HTTP 404.
+- ✅ `swagger-cli validate` passes after any spec edits.
+
+Automate these checks using your preferred test harness or CI pipeline to catch regressions early.
+
+---
+
+## 5. Migrating From `host_*`
+
+- Run backend migrations to add the new `customer_name` / `customer_email` columns: `npm --prefix backend run migrate` (or your existing deployment flow). The migration copies legacy data automatically, so upgrades remain seamless.
+- All admin APIs now require the `customer_*` fields. Older `host_*` payloads are rejected, which makes downstream client issues obvious during testing instead of silently dropping data.
+- API responses still mirror `customer_*` even if migrations have not run yet (the server falls back to legacy columns until the upgrade is complete), so existing frontends can move over incrementally.
+- Once every consumer writes and reads the new fields, you can safely plan the removal of the legacy `host_*` columns in a future release.
+
+---
+
+Need deeper integration examples or language-specific SDKs? Import the OpenAPI spec into code generators such as `openapi-generator` or `orval` to scaffold API clients quickly.