meta {
  name: Trigger Backfill
  type: http
  seq: 1
}

post {
  url: {{appview_url}}/api/admin/backfill
}

params:query {
  ~force: full_sync
}

headers {
  Content-Type: application/json
}

assert {
  res.status: in [200, 202]
  res.body.message: isDefined
}

docs {
  Triggers a backfill of AT Protocol repo records for all known forum members.
  Runs asynchronously — returns immediately with 202 Accepted or 200 (if not needed).

  Requires authentication via session cookie and `space.atbb.permission.manageForum` permission.

  Query params:
  - force: string (optional) - Override automatic gap detection. One of:
    - "catch_up"   — Replay firehose events since last cursor (missed events only)
    - "full_sync"  — Re-sync every member's full repo from scratch

  When `force` is omitted, the endpoint runs automatic gap detection:
    - If cursor is older than backfillCursorMaxAgeHours, triggers CatchUp
    - If no cursor exists at all, triggers FullSync
    - If cursor is recent and healthy, returns 200 with "No backfill needed" message

  Returns (202 — backfill started):
  {
    "message": "Backfill started",
    "type": "catch_up" | "full_sync",
    "status": "in_progress",
    "id": "42"   // bigint as string — use with GET /api/admin/backfill/:id to poll progress
  }

  Returns (200 — no backfill needed):
  {
    "message": "No backfill needed. Use ?force=catch_up or ?force=full_sync to override."
  }

  Error codes:
  - 401: Unauthorized (not authenticated)
  - 403: Forbidden (lacks manageForum permission)
  - 409: Conflict — a backfill is already in progress
  - 503: BackfillManager not available (server configuration issue)

  Error codes (additional):
  - 500: Failed to check backfill status or create progress row (server error)

  Notes:
  - The backfill ID in the 202 response can be used immediately with GET /api/admin/backfill/:id
  - Unrecognized values for ?force are ignored and fall through to automatic gap detection
}