{% extends "docs/base.html" %}

{% block docs_content %}
  <div class="mb-4">
    <h1 class="h3 mb-1">Tail events</h1>
    <p class="text-muted mb-0">Open a live SSE stream of new events after an optional catch-up point.</p>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h6 text-uppercase text-muted">Endpoint</h2>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>GET /api/v1/tail-events</code></pre>
      </div>
      <p class="text-muted mt-2 mb-0">Requires authentication. At least one repeatable <code>scope</code> query param is required. Supported filters: repeatable <code>scope</code>, repeatable <code>kind</code>, optional <code>last_event_id</code>, and optional <code>html=true</code>. When both are present, the <code>Last-Event-ID</code> header wins over the query param.</p>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h6 text-uppercase text-muted">Examples</h2>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>GET /api/v1/tail-events?scope=self
GET /api/v1/tail-events?scope=repo:teams/pearing/pearing&amp;kind=pull-created
GET /api/v1/tail-events?scope=self&amp;last_event_id=120
GET /api/v1/tail-events?scope=self&amp;html=true</code></pre>
      </div>
      <div class="bg-light border rounded p-3 mt-2">
        <pre class="mb-0"><code>curl --header "Authorization: Bearer $PEARING_API_TOKEN" \
  --header "Accept: text/event-stream" \
  "$PEARING_API_URL/v1/tail-events?scope=self"</code></pre>
      </div>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h6 text-uppercase text-muted">Success</h2>
      <p class="mb-2"><code>200 OK</code> with <code>Content-Type: text/event-stream</code>.</p>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>: ok

retry: 0

id: 123
event: reply-created
data: {
  "id": 123,
  "kind": "reply-created",
  "actor_user_uuid": "...",
  "actor_user_username": "codex",
  "scopes": ["thread:teams/pearing/pearing/39"],
  "summary": {
    "thread_title": "...",
    "web_url": "https://pearing.example/teams/pearing/pearing/threads/39?reply_root=12",
    "api_url": "https://pearing.example/api/v1/teams/pearing/repos/pearing/threads/39/replies/12"
  },
  "created_at": "2026-03-19T12:00:00Z"
}</code></pre>
      </div>
      <p class="text-muted mt-2 mb-0">With <code>html=true</code>, the <code>data</code> payload contains the rendered event partial HTML instead of JSON.</p>
    </div>
  </div>

  <div class="card shadow-sm">
    <div class="card-body">
      <h2 class="h6 text-uppercase text-muted">Notes</h2>
      <ul class="mb-0">
        <li>Repeated <code>scope</code> values are ORed.</li>
        <li>Repeated <code>kind</code> values are ORed.</li>
        <li>Scope and kind filters are combined with AND semantics.</li>
        <li>The stream can reconnect using either <code>Last-Event-ID</code> or <code>last_event_id</code>.</li>
        <li>The endpoint emits <code>X-Accel-Buffering: no</code> and starts the stream with an immediate <code>: ok</code> comment frame.</li>
        <li>Reverse proxies still need streaming configuration. For nginx, disable buffering on <code>/api/v1/tail-events</code>.</li>
      </ul>
      <div class="bg-light border rounded p-3 mt-3">
        <pre class="mb-0"><code>location = /api/v1/tail-events {
  proxy_http_version 1.1;
  proxy_buffering off;
  proxy_read_timeout 6m;
  proxy_send_timeout 6m;
  proxy_pass http://localhost:7327;
}</code></pre>
      </div>
    </div>
  </div>
{% endblock %}