{% extends 'paxalia/base.html' %}
{% load static i18n %}

{% block title %}{% trans "Paxalia API Reference" %} – Paxalia Analytics{% endblock %}
{% block page_title %}{% trans "Paxalia API Reference" %}{% endblock %}
{% block page_subtitle %}{% trans "Server-to-server event ingestion and read access" %}{% endblock %}

{% block extra_css %}
    <link rel="stylesheet" href="{% static 'paxalia/styles/components/security.css' %}">
{% endblock %}

{% block dashboard_content %}
<div class="security-page analytics-page-stack">

    <div class="table-card">
        <h2 class="card-title">{% trans "What this API is for" %}</h2>
        <div class="api-reference-purpose">
            <div class="api-purpose"><strong>{% trans "Server-to-server ingest" %}</strong><span>{% trans "Send trusted backend events without exposing an API key to browser JavaScript." %}</span></div>
            <div class="api-purpose"><strong>{% trans "Read analytics" %}</strong><span>{% trans "Pull summary, page-view, and event data into internal tools, jobs, or reporting systems." %}</span></div>
            <div class="api-purpose"><strong>{% trans "Automation" %}</strong><span>{% trans "Use scoped keys with CI, scheduled jobs, or integrations where anonymous browser tracking is not appropriate." %}</span></div>
        </div>
    </div>

    <div class="table-card">
        <h2 class="card-title">{% trans "Authentication" %}</h2>
        <p>
            {% trans "Every request needs an" %} <a href="{% url 'paxalia:api_keys' %}">{% trans "API key" %}</a>
            {% trans "sent as a Bearer token:" %}
        </p>
        <pre class="api-reference-code"><code>Authorization: Bearer pxa_...</code></pre>
        <p class="form-hint">
            {% trans "A key has one or both scopes: ingest (post events) and read (query data). Requests are rate-limited to 300/minute per key. This is separate from the anonymous, browser-facing event snippet — a secret key should never be embedded in client-side JavaScript." %}
        </p>
    </div>

    <div class="table-card">
        <h2 class="card-title">POST /paxalia-api/v1/ingest/</h2>
        <p>{% trans "Requires the ingest scope. Same payload shape as the public event snippet." %}</p>
        <pre class="api-reference-code"><code>curl -X POST {{ base_url }}ingest/ \
  -H "Authorization: Bearer pxa_..." \
  -H "Content-Type: application/json" \
  -d '{"category": "signup", "action": "completed", "label": "referral"}'</code></pre>
    </div>

    <div class="table-card">
        <h2 class="card-title">GET /paxalia-api/v1/stats/summary/</h2>
        <p>{% trans "Requires the read scope. Query params: start_date, end_date (YYYY-MM-DD, default: last 30 days)." %}</p>
        <pre class="api-reference-code"><code>curl {{ base_url }}stats/summary/?start_date=2026-01-01&end_date=2026-01-31 \
  -H "Authorization: Bearer pxa_..."

{
  "start_date": "2026-01-01",
  "end_date": "2026-01-31",
  "total_views": 48213,
  "unique_visitors": 12904
}</code></pre>
    </div>

    <div class="table-card">
        <h2 class="card-title">GET /paxalia-api/v1/pageviews/</h2>
        <p>{% trans "Requires the read scope. Query params: start_date, end_date, limit (max 500, default 100), offset." %}</p>
        <pre class="api-reference-code"><code>curl "{{ base_url }}pageviews/?limit=50" \
  -H "Authorization: Bearer pxa_..."

{
  "total": 48213, "limit": 50, "offset": 0,
  "results": [
    {"path": "/pricing/", "method": "GET", "status_code": 200,
     "referrer": "https://google.com/", "country_code": "US",
     "utm_source": "", "utm_medium": "", "utm_campaign": "",
     "created_at": "2026-01-15T09:32:00Z"}
  ]
}</code></pre>
    </div>

    <div class="table-card">
        <h2 class="card-title">GET /paxalia-api/v1/events/</h2>
        <p>{% trans "Requires the read scope. Query params: start_date, end_date, limit, offset, category." %}</p>
        <pre class="api-reference-code"><code>curl "{{ base_url }}events/?category=signup" \
  -H "Authorization: Bearer pxa_..."</code></pre>
    </div>

</div>
{% endblock %}