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

{% block docs_content %}
  <div class="mb-4">
    <h1 class="h3 mb-1">Suggest users</h1>
    <p class="text-muted mb-0">Autocomplete user suggestions by username or name, with optional scope-based ranking.</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/suggest-users?search=text&amp;scope=repo:teams/pearing/pearing</code></pre>
      </div>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h6 text-uppercase text-muted">Authentication</h2>
      <p class="mb-2">None required for public repos and teams. Optional for private repo scopes.</p>
      <p class="mb-0 text-muted">When <code>scope=repo:&lt;locator&gt;</code> targets a private repo, a valid API token with access to that repo is required for scoped ranking. Without a token (or without access), the request silently falls back to global suggestions.</p>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h6 text-uppercase text-muted">Parameters</h2>
      <ul class="mb-0">
        <li><code>search</code> (required) &mdash; text to match against username and name. Uses <code>pg_trgm</code> fuzzy matching and prefix matching.</li>
        <li><code>scope</code> (optional) &mdash; boost users relevant to a scope. Supported values:
          <ul>
            <li><code>repo:&lt;locator&gt;</code> &mdash; boost users who have participated in threads or pulls on the repo (e.g. <code>repo:teams/pearing/pearing</code> or <code>repo:benw/myrepo</code>)</li>
            <li><code>team:&lt;slug&gt;</code> &mdash; boost team members and users who have participated in the team's repos</li>
          </ul>
          Invalid or unresolvable scopes silently fall back to global suggestions.
        </li>
      </ul>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h6 text-uppercase text-muted">Usage</h2>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>curl "$PEARING_API_URL/v1/suggest-users?search=ben"</code></pre>
      </div>
      <div class="bg-light border rounded p-3 mt-2">
        <pre class="mb-0"><code>curl \
  "$PEARING_API_URL/v1/suggest-users?search=ben&amp;scope=repo:teams/pearing/pearing"</code></pre>
      </div>
      <div class="bg-light border rounded p-3 mt-2">
        <pre class="mb-0"><code>curl "$PEARING_API_URL/v1/suggest-users?search=cl&amp;scope=team:pearing"</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></p>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>{
  "next": null,
  "previous": null,
  "results": [
    { "uuid": "...", "username": "benwilber", "name": "Ben Wilber" },
    { "uuid": "...", "username": "bendev", "name": "Ben Developer" }
  ]
}</code></pre>
      </div>
      <p class="text-muted mb-0 mt-2">
        Returns up to 15 results. Only active users are included. Results are ranked by exact match, prefix match, scope participation, and trigram similarity.
      </p>
    </div>
  </div>

  <div class="card shadow-sm">
    <div class="card-body">
      <h2 class="h6 text-uppercase text-muted">Errors</h2>
      <ul class="mb-0">
        <li><code>400 Bad Request</code> when <code>search</code> is missing or empty.</li>
      </ul>
    </div>
  </div>
{% endblock %}