import type { Metadata } from 'next';
import Link from 'next/link';
import { BreadcrumbLd } from '@/components/meta/breadcrumb-ld';
import { DataTable, Td, Th } from '@/components/ui/data-table';
import { Container, Note, PageHeader, Section } from '@/components/ui/section';
import { Unavailable } from '@/components/ui/unavailable';
import { api, safe } from '@/lib/api';
import { PUBLIC_API_BASE, routes, SITE_NAME } from '@/lib/site';
import type { Stats } from '@/lib/types';
import { RequestBuilder } from './request-builder';
import { ROUTES } from './routes';

export const metadata: Metadata = { title: 'Developers — public API 1.1, request builder, provenance and history recipes', description: 'The AI Atlas public API: JSON over HTTPS, no key for public routes, OpenAPI docs, an interactive request builder with curl / Python / JavaScript snippets, and recipes for pagination, provenance and historical queries.', alternates: { canonical: '/developers' } };
export const revalidate = 3600;

/** Compact, honest projection of /stats for the example block (the real payload has more counters). */
function statsExample(s: Stats) {
  return { entities: s.entities, entities_total: s.entities_total, organizations_total: s.organizations_total, change_events_live_24h: s.change_events_live_24h, claims_current: s.claims_current, prices_current: s.prices_current, last_event_at: s.last_event_at, definitions: s.definitions ? `${Object.keys(s.definitions).length} counter definitions` : undefined, computed_at: s.computed_at, '…': `${Object.keys(s).length} keys in total` };
}
function Code({ children }: { children: string }) {
  return (
    <pre className="scrollbar-thin mt-3 overflow-x-auto border border-rule bg-surface p-4 text-[12.5px] leading-relaxed text-ink">
      <code>{children}</code>
    </pre>
  );
}

export default async function DevelopersPage() {
  const [health, stats, top] = await Promise.all([safe(api.health()), safe(api.stats()), safe(api.models({ limit: 1, sort: 'quality' }))]);
  const exA = top?.items[0]?.slug ?? '<model-slug>';
  const today = new Date().toISOString().slice(0, 10);
  const weekAgo = new Date(Date.now() - 7 * 86400000).toISOString().slice(0, 10);

  return (
    <Container wide>
      <BreadcrumbLd items={[{ name: SITE_NAME, href: '/' }, { name: 'Developers', href: '/developers' }]} />
      <PageHeader eyebrow="Developers" title="Public API 1.1" lede="Everything on this site comes from the same JSON API. Public routes need no key; responses carry a weak ETag and are cached for 1–10 minutes; search is rate-limited per IP. 1.1 is additive over v1 — no route, field or type was removed." aside={health ? <p className="text-sm text-ink-3">API <span className={health.status === 'ok' ? 'text-positive' : 'text-warning'}>{health.status}</span> · v{health.version}{(health as { api_version?: string }).api_version ? ` · contract ${(health as { api_version?: string }).api_version}` : ''}</p> : <p className="text-sm text-ink-3">API status unavailable</p>} />

      <Section eyebrow="Base URL" title={<span className="mono text-lg md:text-xl">{PUBLIC_API_BASE}</span>} hairline={false}>
        <p className="text-sm text-ink-2">
          Interactive OpenAPI documentation: <a href="/api/v1/docs" className="link mono">/api/v1/docs</a>. JSON, UTF-8, ISO-8601 UTC timestamps. Errors are <span className="mono">{'{ "detail": "…" }'}</span> with 400 / 404 / 409 / 429 / 501 / 503 (422 with <span className="mono">errors</span> for parameters rejected by validation). Every response carries <span className="mono">x-api-version: 1.1</span>.
        </p>
      </Section>

      <Section id="builder" eyebrow="Request builder" title="Build a request, try it, copy the snippet" lede="Routes and parameters come from the 1.1 contract; “Try” calls the API from your browser through this site's same-origin proxy.">
        <RequestBuilder />
      </Section>

      <Section id="recipes" eyebrow="Recipes" title="Pagination, provenance, history">
        <div className="grid gap-8 lg:grid-cols-2">
          <div className="min-w-0">
            <p className="text-sm font-medium text-ink">Cursor pagination on feeds</p>
            <Code>{`# /changes and /entities/{slug}/timeline return next_before; pass it back as before=
curl -s "${PUBLIC_API_BASE}/changes?importance_min=2&limit=50" | jq '{next_before, n: (.items|length)}'
curl -s "${PUBLIC_API_BASE}/changes?importance_min=2&limit=50&before=<next_before>"

# Listings use limit/offset (≤ 200; /sitemap ≤ 5 000). 1.1 feeds are keyed on occurred_at and exclude backfill:
curl -s "${PUBLIC_API_BASE}/changes?include_backfill=1&date_field=observed&limit=20"   # v1 behaviour`}</Code>
            <p className="mt-6 text-sm font-medium text-ink">Field-level provenance</p>
            <Code>{`# Every displayed value has a claim behind it
curl -s "${PUBLIC_API_BASE}/entities/${exA}/provenance/context_length" | jq '{value, source: .source.name, tier, extractor, observed_at, valid_since, claim_id, conflicts: (.conflicts|length)}'

# One claim and its lifecycle (previous, superseding, conflicting)
curl -s "${PUBLIC_API_BASE}/claims/<claim_id>" | jq '{property, claim: .claim.value, chain: (.chain | map_values(if type=="array" then length else . end))}'

# All current claims of an entity
curl -s "${PUBLIC_API_BASE}/entities/${exA}/claims?status=current&limit=50" | jq '.items[] | {property, value, tier, source_name}'`}</Code>
          </div>
          <div className="min-w-0">
            <p className="text-sm font-medium text-ink">Historical queries</p>
            <Code>{`# The atlas as of a date (reconstructed before the observation history)
curl -s "${PUBLIC_API_BASE}/time-machine?date=2025-06-01&scope=models&limit=20" | jq '{reconstructed, first_entity_at, total: .models.total}'

# One entity as of a date, and the full claim history of a property
curl -s "${PUBLIC_API_BASE}/entities/${exA}/asof?date=${weekAgo}" | jq '{existed, attributes}'
curl -s "${PUBLIC_API_BASE}/entities/${exA}/history?property=context_length" | jq '.items[] | {value, status, valid_from, valid_to}'

# What changed between two dates (scope: all | models | org:<slug> | family:<slug>)
curl -s "${PUBLIC_API_BASE}/diff?a=${weekAgo}&b=${today}&scope=models" | jq '.counts'

# Today in AI 2.0 — grouped sections, backfill excluded
curl -s "${PUBLIC_API_BASE}/changes/daily?date=${today}" | jq '{total, backfill_excluded, sections: [.today[] | {key, total}]}'`}</Code>
            <p className="mt-6 text-sm font-medium text-ink">Graph</p>
            <Code>{`# Typed neighbourhood explorer — never more than limit nodes, truncated says when the API cut
curl -s "${PUBLIC_API_BASE}/graph/explore?node=anthropic&mode=company&depth=1&limit=150" | jq '{truncated, counts, predicates}'`}</Code>
          </div>
        </div>
      </Section>

      <Section eyebrow="Live example" title="GET /stats" lede="Fetched from the API when this page was rendered (revalidated hourly) and trimmed for display — not sample data.">
        {stats ? <Code>{JSON.stringify(statsExample(stats), null, 2)}</Code> : <Unavailable what="Live /stats example" className="mt-3" />}
      </Section>

      <Section eyebrow="Endpoints" title="Public routes (1.1)">
        <DataTable caption="Public endpoints" compact>
          <thead>
            <tr>
              <Th>Route</Th>
              <Th>Group</Th>
              <Th>Returns</Th>
            </tr>
          </thead>
          <tbody>
            {ROUTES.map((r) => (
              <tr key={r.id}>
                <Td primary className="mono text-[12.5px] break-words">
                  {r.method} {r.path}
                  {r.params.length > 0 && <span className="block text-[11px] text-ink-3">{r.params.map((p) => p.name).join(' · ')}</span>}
                </Td>
                <Td label="Group" className="text-xs text-ink-2">{r.group}</Td>
                <Td label="Returns" wide className="text-ink-2">{r.returns}</Td>
              </tr>
            ))}
          </tbody>
        </DataTable>
        <Note className="mt-3">
          Shapes are documented in the OpenAPI schema and in <span className="mono">docs/API.md</span>. Admin routes (<span className="mono">/admin/*</span>) require the <span className="mono">x-aia-admin-token</span> header and are not public. Also: <span className="mono">/benchmarks/{'{slug}'}/frontier</span>, <span className="mono">/pareto</span>, <span className="mono">/cost/context</span>, <span className="mono">/hardware/{'{slug}'}/fit</span>, <span className="mono">/licenses/{'{key}'}</span>, <span className="mono">/compare</span>, <span className="mono">/explore/types</span>, <span className="mono">/explore/{'{type}'}</span>, <span className="mono">POST /views</span>.
        </Note>
      </Section>

      <Section eyebrow="Conventions" title="Reading responses">
        <ul className="max-w-3xl list-disc space-y-1.5 pl-5 text-sm leading-relaxed text-ink-2">
          <li>Numeric aggregates may arrive as <span className="mono">string</span> (Postgres decimals): treat every numeric field as <span className="mono">number | string | null</span> and coerce.</li>
          <li><span className="mono">null</span> means the sources did not state it. Never read a missing field as zero, and never average two conflicting claims — the API returns both, flagged.</li>
          <li>Events: <span className="mono">occurred_at = coalesce(effective_at, observed_at)</span>; <span className="mono">is_backfill</span> marks imported history; <span className="mono">group_key</span> folds one release seen in several documents.</li>
          <li>Universe: <span className="mono">/models</span> lists canonical model releases; artifacts and folded variants are excluded unless <span className="mono">include=artifacts</span>. Old slugs keep resolving (<span className="mono">redirected_from</span>).</li>
          <li>Benchmarks: results live in comparability groups (metric × <span className="mono">config_key</span>); leaderboards are one row per canonical model with a <span className="mono">trust_level</span>.</li>
          <li>Anything marked <span className="mono">estimated: true</span> (hardware fit, memory-derived parameter bounds) is derived by a stated formula — the <span className="mono">assumptions</span> array is part of the response.</li>
          <li>Caching: weak <span className="mono">ETag</span> + <span className="mono">Cache-Control: public, max-age=60, stale-while-revalidate=300</span>; send <span className="mono">If-None-Match</span> for a 304.</li>
        </ul>
      </Section>

      <Section eyebrow="Terms" title="Fair use">
        <ul className="max-w-3xl list-disc space-y-1.5 pl-5 text-sm leading-relaxed text-ink-2">
          <li>Public routes are free to use without a key. Please cache responses and identify your client with a User-Agent that includes a contact address.</li>
          <li>Search is rate-limited per IP (HTTP 429 when exceeded). Higher limits and developer keys (<span className="mono">x-api-key</span>) are available on request — see <Link href={routes.about()} className="link">contact</Link>.</li>
          <li>Attribution: “Data: AI Atlas (www.ai-atlas.co)” with a link. Every record carries its own upstream sources; please keep them when you redistribute.</li>
          <li>Agent-readable access (MCP server, bulk exports) is planned, not available yet — the routes above are the only supported surface today.</li>
        </ul>
      </Section>
    </Container>
  );
}