# HomeServer API Guide
# Base URL: http://server.tailcea348.ts.net
# Public URL: https://server.tailcea348.ts.net
# Tailscale URL: http://server:5000
# This is a plain-text guide for Claude agents.
# Use the public URL from anywhere, Tailscale URL from the Tailnet.

## Registered Apps
  - homeserver-companion: HomeServer Companion v1.0.5 (gradle)
  - weather: Weather v1.4.3 (capacitor)
  - kokoboco-lite: KokoBocoLite v0.2.0 (expo)
  - boco-ads: BocoAds v1.0.0 (expo)
  - home-hub: HomeHub v1.0.0 (webapp)

## Vault Data (per-app debug uploads)
  - kokoboco-lite-contractor: 1 entries (latest: 20260329-213525)
  - weather: 2 entries (latest: 20260329-230530)

## ── API Reference ──────────────────────────────────────

### Health
  GET /api/health
  Returns: {"status":"ok", "apk_apps":N, ...}

### App Registry
  GET  /api/registry              — list all registered apps
  GET  /api/registry/<id>         — get one app entry
  POST /api/registry              — register/update app (auth required)
       Body: {"displayName":"...", "type":"expo|capacitor|gradle|webapp|static", "path":"...", "version":"1.0.0"}
  DELETE /api/registry/<id>       — unregister (auth required)
  POST /api/registry/<id>/version — bump version (auth required)
       Body: {"bump":"patch|minor|major"} or {"version":"1.2.3"}

### APK Upload & Download
  GET  /api/apps                  — list all APKs as JSON
  POST /api/upload                — upload APK (auth required)
       Form: file=@app.apk, app=AppName, version=1.0.0, notes=...
       Names: PascalCase (e.g. Weather, BudgetTracker)
  DELETE /api/delete/<app>/<ver>  — delete APK version (auth required)
  GET  /apks/<app>/<ver>/<file>   — download APK file

### Web App Deploy
  GET  /api/webapps               — list deployed web apps
  POST /api/webapps/upload        — deploy web app (auth required)
       Form: file=@app.zip, app=appname, notes=...
       Names: lowercase-hyphens (e.g. weather, budget-tracker)
       Zip must contain index.html at root or single subdirectory.
       Server auto-injects <base> tag — no build config needed.
  DELETE /api/webapps/delete/<app> — delete web app (auth required)
  GET  /apps/<app>/               — open deployed web app

### Vault (Debug Data Upload)
  GET  /api/vault/<app-id>              — list all vault entries for app
  GET  /api/vault/<app-id>/latest       — most recent entry (for agents)
  GET  /api/vault/<app-id>/<entry-id>   — get specific entry
  POST /api/vault/<app-id>              — upload vault entry (auth required)
       Form fields:
         files[]    — one or more files (screenshots, logs, etc.)
         summary    — short description
         type       — bug | crash | screenshot | log | data
         console    — console output text (saved as console.txt)
         stacktrace — stack trace text (saved as stacktrace.txt)
         metadata   — JSON string with extra context
  DELETE /api/vault/<app-id>/<entry-id> — delete entry (auth required)
  GET  /vault/files/<app>/<entry>/<file> — download vault file

### Deploy (Trigger Builds Remotely)
  POST /api/deploy/<app-id>         — trigger deploy (auth required, returns job ID)
       Body: {"git_pull":true, "bump":"patch", "notes":"...", "output":"web|apk|apk web"}
       output: "web" = web only, "apk" = APK only, "" = all from registry
       Response: {"ok":true, "job_id":"...", "status_url":"/api/deploy/status/..."}
  GET  /api/deploy/status/<job-id>  — poll job status + build output
  GET  /api/deploy/jobs             — list recent deploy jobs (?app=filter)
  Flow: git pull in project dir → deploy.sh builds → uploads to server.
  Builds run in background. Poll status until status is "success" or "failed".

### Drop (Quick File Transfer)
  POST /api/drop         — upload a file (form: file=@f, name=label)
  GET  /api/drops        — list dropped files
  DELETE /api/drops/<name> — delete a drop

## ── Quick Examples ─────────────────────────────────────

# Check what vault data exists for your app:
curl http://server.tailcea348.ts.net/api/vault/weather/latest

# Upload a bug report with screenshot:
curl -X POST http://server.tailcea348.ts.net/api/vault/weather \
  -H "Authorization: Bearer $APK_SERVER_TOKEN" \
  -F "type=bug" \
  -F "summary=Crash on settings page" \
  -F "files[]=@screenshot.png" \
  -F "stacktrace=Error: Cannot read property ..."

# Deploy a web app:
curl -F "file=@dist.zip" -F "app=weather" \
  -F "notes=Fixed navbar" \
  http://server.tailcea348.ts.net/api/webapps/upload

# Upload an APK:
curl -F "file=@app-debug.apk" -F "app=Weather" \
  -F "version=1.4.3" -F "notes=Bug fix" \
  http://server.tailcea348.ts.net/api/upload

# Trigger a remote deploy (git pull + build + deploy):
curl -X POST http://server.tailcea348.ts.net/api/deploy/weather \
  -H "Authorization: Bearer $APK_SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"git_pull": true, "notes": "Deploy from phone"}'
# Then poll: curl http://server.tailcea348.ts.net/api/deploy/status/<job-id>

## ── Auth ───────────────────────────────────────────────
# Token is set via APK_SERVER_TOKEN env var on the server.
# Pass it as: -H "Authorization: Bearer $APK_SERVER_TOKEN"
# Read endpoints (GET) do not require auth.
# Write endpoints (POST/DELETE) require auth when token is set.

## ── Naming Conventions ─────────────────────────────────
# APK app names: PascalCase (Weather, BudgetTracker)
# Web app names: lowercase-hyphens (weather, budget-tracker)
# Vault app IDs: match the registry ID (lowercase-hyphens)
# Versions: semver (1.2.3) — bump patch for each deploy