import type { Metadata } from 'next';
import Link from 'next/link';
import { ENDPOINT_GROUPS, RATE_LIMITS } from '@/components/meta/endpoints';
import { ATTRIBUTION, DISCLAIMER } from '@/components/meta/legal';
import { Callout, Code, DocLayout, DocSection, Prose } from '@/components/meta/prose';
import { Container, PageHeader } from '@/components/ui/section';
import { CONTACT_EMAIL, SITE_URL, routes } from '@/lib/site';

export const metadata: Metadata = {
  title: 'API for developers — free JSON access to the orbital catalog',
  description: 'The SatelliteIndex REST API: satellites, live SGP4 positions, constellations, operators, countries, launches, debris, reentries, events and statistics as JSON. Free during the MVP.',
  alternates: { canonical: `${SITE_URL}/developers` },
  openGraph: { title: 'API | SatelliteIndex', description: 'Free JSON API for everything in Earth orbit — the same API that powers this site.', url: `${SITE_URL}/developers` },
  twitter: { card: 'summary', title: 'API | SatelliteIndex', description: 'Free JSON API for everything in Earth orbit.' },
};

const BASE = `${SITE_URL}/api/v1`;

const TOC = [
  { id: 'basics', label: 'Basics' },
  { id: 'envelope', label: 'Response envelope' },
  ...ENDPOINT_GROUPS.map((g) => ({ id: `ep-${g.title.toLowerCase().replace(/[^a-z]+/g, '-')}`, label: g.title })),
  { id: 'positions-format', label: 'Batch positions format' },
  { id: 'rate-limits', label: 'Rate limits' },
  { id: 'attribution', label: 'Attribution & terms' },
  { id: 'roadmap', label: 'Keys and tiers' },
];

export default function DevelopersPage() {
  return (
    <Container>
      <PageHeader eyebrow="Developers" title="The SatelliteIndex API" lede="Every page on this site is rendered from the public JSON API documented here — there is no private dataset behind it. Free, no key required during the MVP, rate-limited per client.">
        <p className="mt-4 flex flex-wrap gap-x-4 gap-y-1 text-sm">
          <a href="/api/v1/docs" className="link">
            Interactive docs (Swagger)
          </a>
          <a href="/api/v1/openapi.json" className="link">
            OpenAPI 3 schema
          </a>
          <Link href={routes.status()} className="link">
            Status
          </Link>
        </p>
      </PageHeader>

      <DocLayout toc={TOC}>
        <div>
          <DocSection id="basics" title="Basics">
            <Prose>
              <p>
                Base URL: <code>{BASE}</code>. All endpoints are <code>GET</code>, return <code>application/json</code> encoded in UTF-8, and use UTC ISO-8601 timestamps. Units are kilometres, km/s, kilograms, degrees and minutes. Countries are ISO 3166-1 alpha-2 codes. Numbers aggregated by the database may arrive as strings — parse them as decimals.
              </p>
              <p>
                Satellites can be addressed by slug (<code>iss-zarya-25544</code>), NORAD catalog number (<code>25544</code>) or COSPAR designator (<code>1998-067A</code>). Internal ids are prefixed ULIDs (<code>sat_…</code>) and are stable; NORAD and COSPAR are source identifiers and are kept as such.
              </p>
            </Prose>
            <Code label="curl">{`curl -s "${BASE}/satellites/25544" | jq '.data | {name, norad_id, status, orbit_class, live}'`}</Code>
          </DocSection>

          <DocSection id="envelope" title="Response envelope and pagination">
            <Prose>
              <p>
                Single resources return <code>{'{ data, meta }'}</code>; list endpoints add a <code>pagination</code> block. <code>meta.request_id</code> is the id you will find in our server logs if you report a problem; <code>meta.generated_at</code> is the server time of the response (responses may be cached for up to a few minutes).
              </p>
            </Prose>
            <Code label="Shape">{`{
  "data": [ … ],
  "pagination": { "page": 1, "page_size": 50, "total": 17026, "pages": 341 },
  "meta": { "request_id": "b382117229134a57", "generated_at": "2026-09-11T18:17:53Z" }
}`}</Code>
            <Prose className="mt-3">
              <p>
                Errors use the same envelope with an <code>error</code> object: <code>{'{ "error": { "title", "detail", "status" } }'}</code> and the matching HTTP status (404 unknown entity, 422 invalid parameter, 429 rate limited, 503 upstream/database unavailable). Paginate with <code>page</code> and <code>page_size</code> (1–200; sitemap feeds allow more).
              </p>
            </Prose>
          </DocSection>

          {ENDPOINT_GROUPS.map((g) => (
            <DocSection key={g.title} id={`ep-${g.title.toLowerCase().replace(/[^a-z]+/g, '-')}`} title={g.title} eyebrow="Endpoints">
              <ul className="divide-y divide-rule border-y border-rule">
                {g.endpoints.map((e) => (
                  <li key={e.path} className="py-3">
                    <div className="flex flex-wrap items-center gap-2">
                      <span className="mono rounded bg-plane-3 px-1.5 py-0.5 text-[11px] text-accent">{e.method}</span>
                      <code className="mono break-all text-sm text-ink">{e.path}</code>
                      {e.bucket && <span className="text-[11px] text-ink-3">rate bucket: {e.bucket}</span>}
                    </div>
                    <p className="mt-1 text-sm text-ink-2">{e.summary}</p>
                    <Code className="mt-2">{`curl -s "${BASE}${e.example}"`}</Code>
                  </li>
                ))}
              </ul>
            </DocSection>
          ))}

          <DocSection id="positions-format" title="Batch positions format">
            <Prose>
              <p>
                <code>/orbit/positions</code> returns the position of every object in the propagator (tens of thousands) at two instants, <code>t0</code> and <code>t1 = t0 + step_s</code>, so a client can interpolate smoothly between polls. To keep the payload small the response is a set of <strong>parallel arrays</strong> rather than one object per satellite: index <code>i</code> of each array describes the same object.
              </p>
            </Prose>
            <Code label="Fields">{`{
  "t0": "…", "t1": "…", "step_s": 60, "count": N, "total_tracked": N,
  "fields": ["norad", "cls", "mission", "active", "pos", "vel"],
  "norad":   [25544, …],            // NORAD id per object
  "cls":     [0, …],                // index into legend.cls   (orbit class)
  "mission": [8, …],                // index into legend.mission
  "active":  [1, …],                // 1 = ACTIVE status
  "pos":     [lat0, lon0, alt0, lat1, lon1, alt1, …],   // 6 numbers per object (deg, deg, km)
  "vel":     [v0, v1, …],           // km/s at t0 and t1
  "legend":  { "cls": ["LEO","MEO","GEO","HEO","OTHER"], "mission": [ … ] }
}`}</Code>
            <Prose className="mt-3">
              <p>Positions are derived from the latest element set of each object and inherit its age; check <code>/sources/status</code> for the median element age before relying on them.</p>
            </Prose>
          </DocSection>

          <DocSection id="rate-limits" title="Rate limits">
            <Prose>
              <p>Limits are applied per client IP over a sliding 60-second window. Exceeding a bucket returns <code>429 Too Many Requests</code> with the bucket name in the error detail. Cache responses on your side; most datasets change hourly at most.</p>
            </Prose>
            <div className="mt-4 overflow-x-auto">
              <table className="data-table stack sm:min-w-[480px]">
                <thead>
                  <tr>
                    <th>Bucket</th>
                    <th className="num">Requests / min</th>
                    <th>Applies to</th>
                  </tr>
                </thead>
                <tbody>
                  {RATE_LIMITS.map((r) => (
                    <tr key={r.bucket}>
                      <td className="primary mono text-sm">{r.bucket}</td>
                      <td data-label="Requests / min" className="num tnum text-sm">
                        {r.perMinute}
                      </td>
                      <td data-label="Applies to" className="mono text-xs text-ink-2">
                        {r.applies}
                      </td>
                    </tr>
                  ))}
                </tbody>
              </table>
            </div>
          </DocSection>

          <DocSection id="attribution" title="Attribution and terms">
            <Prose>
              <p>
                If you republish data from this API you must keep the upstream attributions. The orbital elements and catalog come from CelesTrak, whose terms require credit: <strong>“Orbital data courtesy of CelesTrak.”</strong> Derived values (orbit class, mission type, constellation membership, activity score, density) should be credited to SatelliteIndex with a link to the <Link href={routes.methodology()} className="link">methodology</Link>. The full source list with licenses is on <Link href={routes.sources()} className="link">/sources</Link>.
              </p>
              <p>{ATTRIBUTION}</p>
            </Prose>
            <Callout tone="warn">{DISCLAIMER}</Callout>
            <p className="mt-3 text-sm text-ink-3">
              Full <Link href={routes.terms()} className="link">terms of use</Link>.
            </p>
          </DocSection>

          <DocSection id="roadmap" title="Keys and tiers">
            <Prose>
              <p>
                The API is <strong>free during the MVP</strong> and requires no key. API keys, higher rate limits and paid tiers for heavy or commercial use will come later; the public endpoints documented here will keep a free tier. If you are building on the API, say hello at <a href={`mailto:${CONTACT_EMAIL}`} className="link">{CONTACT_EMAIL}</a> so we can warn you before any breaking change.
              </p>
            </Prose>
          </DocSection>
        </div>
      </DocLayout>
    </Container>
  );
}