import type { Metadata } from "next";
import Link from "next/link";
import { Page, PageHeader } from "@/components/ui/section";
import { SITE_URL } from "@/lib/site";

export const metadata: Metadata = { title: "Developers", description: "Market Atlas API: REST endpoints, WebSocket and SSE streams, envelopes, errors and rate limits.", alternates: { canonical: "/developers" } };

const REST: Array<[string, string]> = [
  ["GET /v1/stats", "Live telemetry (instruments, connectors, observations today, events, freshness)."],
  ["GET /v1/markets", "Global overview: featured indices, crypto, FX, rates, commodities, equities, movers, exchanges with state, breadth."],
  ["GET /v1/instruments?asset_class=&exchange=&country=&q=&quoted=1&sort=&limit=&offset=", "Instrument master with canonical quotes. sort ∈ symbol | change | -change | volume | name."],
  ["GET /v1/instruments/{id|SYMBOL|VENUE:SYMBOL}", "Instrument detail: company, exchange + status, quote, aliases, observing sources, related instruments."],
  ["GET /v1/quotes/{id}", "One canonical quote."],
  ["GET /v1/quotes?ids=a,b,c", "Up to 200 canonical quotes."],
  ["GET /v1/quotes/{id}/provenance", "“Why this price?” — source coverage matrix: every contribution with observation_type, delta_bps vs consensus, weight, age, inclusion and reason; plus comparability, proxy/validator confirmations, coverage and shared_upstream_pairs."],
  ["GET /v1/coverage?asset_class=&tier=A|B|C|D&limit=", "Source Coverage Engine: summary (quoted, multiSource, byFamilies ≥5/≥3/≥2/1/0, weightedScore, tiers attainment, byAssetClass, proxiesConfirming, validatorsConfirming), targets, source-expansion queue, inferred shared upstreams (lineage)."],
  ["GET /v1/coverage/{id}", "Coverage of one instrument: tier, target, families, observations, proxies, validators, live/delayed/official counts, score, status, gap."],
  ["GET /v1/history/{id}?resolution=1m|5m|15m|1h|1d&from=&to=&limit=", "OHLCV bars (t, o, h, l, c, v, n sources, p producer)."],
  ["GET /v1/events?type=&instrument=&country=&asset_class=&severity=&since=&before=&limit=", "Canonical events; GET /v1/events/{id} for one."],
  ["GET /v1/filings?form=&cik=&q=&limit=&offset=", "Regulatory filings observed on EDGAR."],
  ["GET /v1/exchanges · GET /v1/exchanges/{id}", "Venues with session state, holidays, breadth, movers, events."],
  ["GET /v1/countries · GET /v1/countries/{code}", "Country atlas: exchanges, indices, rates, FX, equities, events."],
  ["GET /v1/search?q=", "Hybrid search grouped by asset class, exchange, country."],
  ["GET /v1/compare?ids=&resolution=", "Rebased series, return/volatility/drawdown, pairwise correlation."],
  ["GET /v1/changes?window=1m|5m|15m|1h|1d", "What changed: movers > 1 %, events, filings, by type."],
  ["GET /v1/breadth?scope=world|US|xnas", "Advancers/decliners/highs/lows for a scope."],
  ["GET /v1/sources · GET /v1/connectors · GET /v1/data-health · GET /v1/status · GET /v1/health · GET /v1/metrics", "Provenance directory, connector operations, health, public status, liveness, Prometheus metrics."],
];

export default function DevelopersPage() {
  const base = SITE_URL;
  const ws = base.replace(/^http/, "ws");
  return (
    <Page>
      <PageHeader kicker="API v1" title="Developers" lead="Public, read-only API over the same canonical data the site shows. Every response carries provenance metadata; values whose data rights forbid redistribution are withheld rather than silently omitted." />
      <div className="prose-ma max-w-3xl">
        <h2>Base URL & envelope</h2>
        <pre>
          <code>{`${base}/v1

{ "data": …, "meta": { "request_id": "…", "timestamp": "2026-09-12T14:31:42.512Z", "data_status": "DELAYED" } }`}</code>
        </pre>
        <p>
          Errors are structured: <code>{`{ "error": { "code": "INSTRUMENT_NOT_FOUND", "message": "instrument not found" } }`}</code> with the matching HTTP status. No stack traces.
        </p>
        <h2>Rate limits</h2>
        <p>
          20 requests per second sustained per IP (burst 300) on <code>/v1</code> REST; <code>429</code> with <code>Retry-After</code> when exceeded. Streams and web pages are not counted. Higher limits and API keys will come with the developer accounts.
        </p>
        <h2>REST endpoints</h2>
        <table>
          <thead>
            <tr>
              <th>Endpoint</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            {REST.map(([e, d]) => (
              <tr key={e}>
                <td>
                  <code>{e}</code>
                </td>
                <td>{d}</td>
              </tr>
            ))}
          </tbody>
        </table>
        <h3>Example</h3>
        <pre>
          <code>{`curl ${base}/v1/quotes/BTC-USD

{
  "data": {
    "instrument_id": "crypto_btc_usd", "symbol": "BTC-USD", "price": 77326.37, "change_percent": 0.0275,
    "bid": 77326.36, "ask": 77326.37, "currency": "USD",
    "source_count": 4, "observation_count": 7, "proxy_count": 0, "validator_count": 0, "comparability": "LIVE",
    "dispersion_bps": 2.13, "confidence": 0.958, "freshness_ms": 1552,
    "data_status": "REALTIME", "market_state": null, "rights_status": "PUBLIC_ATTRIBUTED", "withheld": false,
    "updated_at": "2026-09-12T08:42:34.479Z", "source_timestamp": "2026-09-12T08:42:34.358Z"
  },
  "meta": { "request_id": "…", "timestamp": "…", "data_status": "REALTIME" }
}`}</code>
        </pre>
        <h2>Quote fields</h2>
        <ul>
          <li>
            <code>data_status</code>: <code>REALTIME</code> · <code>DELAYED</code> · <code>AT_CLOSE</code> · <code>END_OF_DAY</code> · <code>STALE</code> · <code>WITHHELD</code>. Never treat anything but <code>REALTIME</code> as live.
          </li>
          <li>
            <code>source_count</code> = independent <em>voting</em> source families; <code>observation_count</code> = fresh observations of any role; <code>proxy_count</code> = stablecoin/derived proxies agreeing within 50 bp; <code>validator_count</code> = restricted-rights sources agreeing within 25 bp; <code>comparability</code> ∈ <code>LIVE</code> · <code>FIX</code> · <code>EOD</code> = class of the canonical value; <code>dispersion_bps</code> = spread between voting sources; <code>confidence</code> ∈ [0, 0.995].
          </li>
          <li>
            Provenance contributions: <code>observation_type</code> ∈ TRADE · MID · QUOTE · INDEX_VALUE · INDICATIVE · STABLECOIN_PROXY · DERIVED · OFFICIAL_FIX · REFERENCE_RATE · SETTLEMENT · EOD_CLOSE · NAV; <code>delta_bps</code> = distance to the canonical value; <code>reason</code> ∈ stale · not_comparable · temporal_mismatch · validation_only · validator_disagrees · outlier. Validator values are <code>null</code> (withheld).
          </li>
          <li>
            <code>freshness_ms</code> = age of the newest included observation at response time; <code>source_timestamp</code> is the source's own time when published.
          </li>
        </ul>
        <h2>WebSocket stream</h2>
        <pre>
          <code>{`${ws}/v1/stream

→ { "action": "subscribe", "channels": ["quotes:BTC-USD", "quotes:AAPL", "events:*", "market:xnas"] }
← { "type": "hello", "version": 1, "server_seq": 1024, "ts": 1789202146812 }
← { "type": "subscriptions", "channels": ["quotes:crypto_btc_usd", "quotes:eq_us_xnas_aapl", "events:*", "market:xnas"] }
← { "type": "batch", "seq": 1, "ts": 1789202146921, "messages": [
      { "type": "quote", "instrument_id": "crypto_btc_usd", "symbol": "BTC-USD", "price": 77326.37, "change": 21.27, "change_pct": 0.0275,
        "bid": 77326.36, "ask": 77326.37, "volume": 6634.6, "currency": "USD", "timestamp": 1789202146563, "received": 1789202146819,
        "confidence": 0.906, "sources": 2, "status": "REALTIME" },
      { "type": "event", "event": { "id": "evt_…", "type": "TRADING_HALT", "title": "…", "severity": "WARNING", "confidence": 1, "source_count": 1, "sources": ["nasdaq-trader"], "instrument_ids": [], "data": { … } } },
      { "type": "market_state", "exchangeId": "xnas", "state": "OPEN", "at": 1789392600000 }
   ] }
← { "type": "heartbeat", "ts": …, "seq": 42 }     (every 25 s)
→ { "action": "ping", "id": 1 }  ←  { "type": "pong", "id": 1, "ts": … }
→ { "action": "unsubscribe", "channels": ["quotes:AAPL"] }`}</code>
        </pre>
        <p>Channels:</p>
        <ul>
          <li>
            <code>quotes:&lt;SYMBOL|id&gt;</code> one instrument · <code>quotes:*</code> everything (throttled to 2 updates/s per instrument) · <code>quotes:class:CRYPTO</code> one asset class · <code>tape</code> compact price changes.
          </li>
          <li>
            <code>events:*</code> · <code>events:&lt;SYMBOL|id&gt;</code> · <code>events:US</code> (country) · <code>events:type:TRADING_HALT</code>.
          </li>
          <li>
            <code>market:&lt;exchange&gt;</code> or <code>market:*</code> for session-state changes.
          </li>
        </ul>
        <p>
          Frames are batched (≈ 10 per second per client) and carry a per-client <code>seq</code>; a gap means messages were dropped under backpressure. Up to 500 channels per connection.
        </p>
        <h2>Server-Sent Events</h2>
        <pre>
          <code>{`curl -N "${base}/v1/sse?channels=quotes:BTC-USD,events:*"

event: hello
data: {"version":1,"channels":["quotes:crypto_btc_usd","events:*"],"ts":…}

event: batch
id: 58
data: {"type":"batch","seq":1,"ts":…,"messages":[{"type":"quote",…}]}`}</code>
        </pre>
        <h2>Identifiers</h2>
        <p>
          Stable public ids: <code>eq_us_xnas_aapl</code>, <code>etf_us_arcx_spy</code>, <code>index_us_spx</code>, <code>crypto_btc_usd</code>, <code>fx_eur_usd</code>, <code>rate_us_us10y</code>, <code>cmd_xcme_gc_f</code>. Endpoints accepting <code>{"{id}"}</code> also accept a bare symbol (<code>AAPL</code>, <code>BTC-USD</code>) or <code>VENUE:SYMBOL</code>.
        </p>
        <h2>Attribution & terms</h2>
        <p>
          Data carries the rights status of its sources; see <Link href="/licensing">data rights</Link>. Cboe values are 15-minute delayed and must be displayed as such; venue and official-source attributions must be preserved when redistributing. Market Atlas is an informational platform, not investment advice.
        </p>
      </div>
    </Page>
  );
}