Paul Nothaft
808b15bafb
Adds a long-lived bearer-token mechanism + scoped REST surface designed
for n8n-style automation: create a gallery, upload photos, fetch the
share URL — all via documented HTTPS endpoints instead of poking at the
admin UI's internal routes.
API
- Migration 081 adds `api_tokens` (hashed_token, scopes, owner FK,
last_used/expires/revoked timestamps).
- New apiTokenAuth middleware: parses `Authorization: Bearer pp_live_…`,
resolves to the owner admin user, attaches `req.admin` so existing
permission decorators (events.create etc.) still work. Token-level
scope check (read/write/admin) layers on top as defence in depth —
a leaked read-only token cannot mutate even if its owner is super_admin.
- adminApiTokens route exposes list/create/revoke for admins (cookie-
authed). Plaintext token is returned exactly once on creation.
- v1 surface mounted at /api/v1: POST/GET /events, GET /events/:id,
POST /events/:id/photos (multipart, single file), GET
/events/:id/share-link. Each endpoint annotated with @openapi JSDoc.
Documentation
- swagger-jsdoc + swagger-ui-express produce a live spec at
/api/openapi.json and a Swagger UI at /api/docs (admin-gated).
- backend/scripts/generate-openapi.js writes docs/openapi.{json,yaml}
to the repo so the spec is versioned.
- scripts/sync-api-docs.sh runs in pre-push: regenerates the spec and
copies it into the picpeak-docs Nextra site at app/api/. Writes only,
never commits or pushes the docs repo (PUSH_SKIP_DOCS=1 to bypass).
Frontend
- New Settings → API Tokens tab: generate, list, revoke. Plaintext
tokens are shown once with a copy-to-clipboard control.
66 lines
2.3 KiB
Bash
Executable File
66 lines
2.3 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
# Local-only API docs sync. Generates docs/openapi.{json,yaml} from
|
|
# the @openapi JSDoc blocks in backend/src/routes/v1/*, then copies the
|
|
# result into the picpeak-docs Nextra site at /Users/paul/Development/picpeak-docs/app/api/.
|
|
#
|
|
# Writes only — never commits or pushes the docs repo. Review the diff
|
|
# in picpeak-docs and commit there manually when ready.
|
|
|
|
set -euo pipefail
|
|
|
|
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
|
DOCS_REPO="${PICPEAK_DOCS_REPO:-/Users/paul/Development/picpeak-docs}"
|
|
SRC_DIR="$REPO_ROOT/docs"
|
|
TARGET_DIR="$DOCS_REPO/app/api"
|
|
|
|
cd "$REPO_ROOT/backend"
|
|
|
|
# 1. Generate fresh spec from JSDoc.
|
|
echo "▶ Generating OpenAPI spec from src/routes/v1/*"
|
|
node scripts/generate-openapi.js
|
|
|
|
# 2. Verify docs repo is reachable. Soft-fail so this doesn't block a
|
|
# push when the docs repo isn't on this machine.
|
|
if [ ! -d "$DOCS_REPO" ]; then
|
|
echo "▶ Docs repo not found at $DOCS_REPO — skipping sync."
|
|
echo " (Set PICPEAK_DOCS_REPO to override, or create the path to enable sync.)"
|
|
exit 0
|
|
fi
|
|
if [ ! -d "$TARGET_DIR" ]; then
|
|
echo "▶ Target dir $TARGET_DIR doesn't exist — creating."
|
|
mkdir -p "$TARGET_DIR"
|
|
fi
|
|
|
|
# 3. Copy spec files into the docs repo. We do NOT git-add or commit
|
|
# here — the user reviews and commits picpeak-docs manually.
|
|
cp "$SRC_DIR/openapi.json" "$TARGET_DIR/openapi.json"
|
|
cp "$SRC_DIR/openapi.yaml" "$TARGET_DIR/openapi.yaml"
|
|
echo "▶ Wrote openapi.{json,yaml} to $TARGET_DIR"
|
|
|
|
# 4. Brief drop-in MDX page that references the spec, so the Nextra
|
|
# nav has a stable target. Won't overwrite a hand-edited file —
|
|
# only writes if missing.
|
|
REF_MDX="$TARGET_DIR/reference.mdx"
|
|
if [ ! -f "$REF_MDX" ]; then
|
|
cat > "$REF_MDX" <<'EOF'
|
|
---
|
|
title: API Reference
|
|
---
|
|
|
|
# API Reference
|
|
|
|
The PicPeak v1 REST API is documented as an OpenAPI 3 spec.
|
|
|
|
- [Download `openapi.yaml`](./openapi.yaml)
|
|
- [Download `openapi.json`](./openapi.json)
|
|
- A live, browseable Swagger UI is served by every PicPeak instance at
|
|
`/api/docs` (admin login required).
|
|
|
|
This page is auto-generated from JSDoc annotations on the v1 route files.
|
|
Do not hand-edit. The narrative pages (auth, recipes) live alongside.
|
|
EOF
|
|
echo "▶ Created $REF_MDX (placeholder — replace with your preferred renderer)"
|
|
fi
|
|
|
|
echo "✓ API docs synced. Review changes in $DOCS_REPO before committing."
|