import type { Metadata } from "next";
import { Code } from "@/components/code";
import { Chip, PageHeader, Panel, Table, Td } from "@/components/ui";
import { SITE_URL } from "@/lib/api";

export const metadata: Metadata = { title: "API", description: "WebSensor REST API, RSS feed and replayable WebSocket live stream (protocol 2). Public, no key required in phase 1; owner-scoped tools use an anonymous header." };

const PUBLIC: [string, string][] = [
  ["GET /api/v1/events", "List events (cursor pagination). See filters below. order=recent|importance|signal"],
  ["GET /api/v1/events/count", "Count of events matching the same filters as /events"],
  ["GET /api/v1/events/{id|slug}", "Event detail: change + field changes + unified diff, score reasons, related, cluster with propagation, interpretations, snapshots (has_raw), sensor reliability, history of the URL"],
  ["GET /api/v1/changes/{id}", "Raw change with heuristic, semantic class, field changes and the unified patch"],
  ["GET /api/v1/snapshots/{id}", "Snapshot metadata + canonical content; ?raw=1 streams the original body when retention kept it"],
  ["GET /api/v1/snapshots/compare?a=&b=", "Diff between any two snapshots of the same URL"],
  ["GET /api/v1/breaking", "Breaking desk: breaking_now, developing, recently_confirmed clusters + high-signal watching list"],
  ["GET /api/v1/pulse", "Pulse: 6 h activity series, desks, rising entities, anomalous sources, silent changes, group totals"],
  ["GET /api/v1/radar", "Radar: indicators (unusual source activity, silent clusters, doc/repo bursts, status changes, new coverage)"],
  ["GET /api/v1/clusters?limit=&since=", "Event clusters (state, signals, sources, lead time)"],
  ["GET /api/v1/clusters/{id|slug}", "Cluster detail: events, entities, propagation timeline, first-party vs external signals, lead_time_ms"],
  ["GET /api/v1/entities", "Entities (type, q)"],
  ["GET /api/v1/entities/rank?limit=", "Entity ranking: 24 h / 7 d activity, avg signal, confirmed ratio, baseline, rank score"],
  ["GET /api/v1/entities/{id}", "Entity detail: children, relations, sources, aliases, recent, insights (heatmap, anomaly, rank)"],
  ["GET /api/v1/entities/{id}/timeline", "Entity timeline (cursor pagination)"],
  ["GET /api/v1/countries", "Countries with sources, events and breaking counts (24 h)"],
  ["GET /api/v1/countries/{code}", "Country desk: breaking, by category, sources, by type, silent, recent"],
  ["GET /api/v1/categories/{channel}", "Category desk (ai · cyber · finance · health · government · science · products · infrastructure · news)"],
  ["GET /api/v1/sources", "Monitored organizations (category, q, country, tier, first_party)"],
  ["GET /api/v1/sources/{id}", "Source detail: sensors, entities, activity anomaly, quality, discovery, daily"],
  ["GET /api/v1/sensors/{id}", "Sensor detail: runs, snapshots, changes, events"],
  ["GET /api/v1/sensors/{id}/snapshots?limit=", "Snapshot history of one sensor (hashes, HTTP status, has_raw, event slug)"],
  ["GET /api/v1/domains/{domain}/timeline", "Domain: monitored URLs + events"],
  ["GET /api/v1/urls/history?url=", "URL history: snapshots, changes, events, removals"],
  ["GET /api/v1/search?q=", "Search events, entities, sources, URLs, clusters — accepts the q syntax below"],
  ["GET /api/v1/stats", "Platform counters (checks/min, events/min, breaking_now, 304 ratio…)"],
  ["GET /api/v1/trending?hours=24", "Trending entities"],
  ["GET /api/v1/explore", "Explore aggregates"],
  ["GET /api/v1/health/connectors", "Connector health, throughput, engine heartbeat, failing domains, slowest sensors"],
  ["GET /api/v1/feed.rss", "RSS 2.0 of the latest events (same filters as /events)"],
  ["WSS /api/v1/live", "Real-time event stream, protocol 2 (replayable)"],
];

const OWNER: [string, string][] = [
  ["GET/POST/PUT/DELETE /api/v1/watchlists", "Watchlists; item kinds entity · source · keyword · category · url · event_type · country · group. GET /watchlists/{id}/events"],
  ["GET/POST/PATCH/DELETE /api/v1/alerts", "Alert rules {name, rule, channel: web|webhook, channel_config: {url, secret}}. PATCH {enabled, name}. Webhooks: https only, public hosts only"],
  ["GET /api/v1/notifications?limit=&unread=1", "Deliveries of your rules with event summary; POST /notifications/read {ids?} marks read (all when omitted)"],
  ["GET/POST/DELETE /api/v1/bookmarks", "Saved events {event_id, note?}; GET /bookmarks/ids for a quick membership check"],
  ["GET/POST/DELETE /api/v1/views", "Saved live-feed views {name, query} where query is a /live query string"],
  ["GET/POST/DELETE /api/v1/monitors", "Custom URL monitors {url, name?, frequency: hourly|daily, sensitivity: low|normal|high, selector?, keywords?}; GET /monitors/{id}/events. 5 per owner"],
];

const FILTERS: [string, string][] = [
  ["after · before", "ISO-8601 bounds on detected_at"],
  ["category · group", "Category slug (ai, cyber…) · event group (security, reliability, product, commercial, corporate, government, science, transport, sports, web)"],
  ["event_type", "Comma list of event types"],
  ["entity · source · domain · sensor · cluster", "Scope to one id"],
  ["importance_min · confidence_min · signal_min", "Score floors (0–100)"],
  ["silent_change · first_party · confirmed", "Booleans (true)"],
  ["country · language · change_class", "ISO-2 country (CA, US, EU…) · language code · semantic class (pricing, policy, product, personnel, meaningful…)"],
  ["q", "Free text + search syntax (right)"],
  ["order · limit · cursor", "recent (default) | importance | signal · ≤ 200 · opaque nextCursor"],
];

export default function ApiPage() {
  const base = SITE_URL;
  const wss = base.replace(/^http/, "ws");
  return (
    <>
      <PageHeader compact kicker="Machine-readable WebSensor" title="API" description="WebSensor practises what it monitors: stable URLs, JSON, RSS, JSON-LD and a replayable WebSocket feed. Phase 1 is public and unauthenticated; rate limit 600 requests / minute / IP. Owner-scoped tools (watchlists, alerts, bookmarks, views, monitors) use an anonymous X-WebSensor-Owner token generated by your browser. Higher limits, keys or questions: contact@spboucher.ai." />
      <div className="grid grid-cols-1 gap-4 lg:grid-cols-[minmax(0,1fr)_400px]">
        <div className="flex min-w-0 flex-col gap-4">
          <Panel title="Public REST endpoints" dense>
            <Table head={["Endpoint", "Description"]}>
              {PUBLIC.map(([ep, desc]) => (
                <tr key={ep}>
                  <Td mono className="sm:whitespace-nowrap">{ep}</Td>
                  <Td className="text-fg-muted">{desc}</Td>
                </tr>
              ))}
            </Table>
          </Panel>
          <Panel title={<span>Owner-scoped endpoints <span className="normal-case tracking-normal text-fg-subtle">· header X-WebSensor-Owner: &lt;16–80 chars [A-Za-z0-9_-]&gt;</span></span>} dense>
            <Table head={["Endpoint", "Description"]}>
              {OWNER.map(([ep, desc]) => (
                <tr key={ep}>
                  <Td mono className="sm:whitespace-nowrap">{ep}</Td>
                  <Td className="text-fg-muted">{desc}</Td>
                </tr>
              ))}
            </Table>
            <p className="border-t border-line px-3 py-2 text-[11.5px] text-fg-subtle">No accounts yet: the token is your identity. Anyone holding it can read and edit these resources. Webhook deliveries are signed when a secret is set: <code>X-WebSensor-Signature: sha256=&lt;HMAC-SHA256(secret, raw body)&gt;</code>.</p>
          </Panel>
          <Panel title="Event filters · /events, /events/count, /feed.rss" dense>
            <Table head={["Parameter", "Meaning"]}>
              {FILTERS.map(([k, v]) => (
                <tr key={k}>
                  <Td mono className="sm:whitespace-nowrap">{k}</Td>
                  <Td className="text-fg-muted">{v}</Td>
                </tr>
              ))}
            </Table>
          </Panel>
          <Panel title="Examples">
            <div className="flex flex-col gap-3 text-[13px]">
              <p>Strongest signals of the last 48 h, first-party only:</p>
              <Code>{`curl "${base}/api/v1/events?signal_min=80&first_party=true&order=signal&after=$(date -u -v-48H +%FT%TZ)"`}</Code>
              <p>Silent pricing / terms changes in the commercial group:</p>
              <Code>{`curl "${base}/api/v1/events?silent_change=true&group=commercial&change_class=pricing"`}</Code>
              <p>Everything from Canada in the government category, counted:</p>
              <Code>{`curl "${base}/api/v1/events/count?country=CA&category=government"`}</Code>
              <p>Search syntax (same as the ⌘K palette):</p>
              <Code>{`curl "${base}/api/v1/search?q=$(printf %s 'openai pricing type:pricing_change signal:>70 after:2026-09-01' | jq -sRr @uri)"`}</Code>
              <p>Cluster with propagation timeline and lead time:</p>
              <Code>{`curl "${base}/api/v1/clusters/<slug>" | jq '{lead_time_ms, first_party_signals, external_signals, propagation: .propagation[:3]}'`}</Code>
              <p>Create a signed webhook alert (owner token = any 16–80 char string you keep):</p>
              <Code>{`curl -X POST "${base}/api/v1/alerts" \\
  -H "content-type: application/json" -H "X-WebSensor-Owner: $OWNER" \\
  -d '{"name":"Critical security","rule":{"groups":["security"],"signal_min":80,"first_party_only":true},
       "channel":"webhook","channel_config":{"url":"https://example.com/hooks/ws","secret":"…"}}'`}</Code>
              <p>Subscribe an RSS reader:</p>
              <Code>{`${base}/api/v1/feed.rss?signal_min=60&group=reliability`}</Code>
            </div>
          </Panel>
          <Panel title="Event object">
            <Code lang="json">{`{
  "id": "evt_…", "slug": "openai-api-pricing-changed-…",
  "event_type": "pricing_change", "change_class": "pricing",
  "title": "OpenAI: price changed $10 / million tokens → $8 / million tokens",
  "summary": "…", "why_it_matters": "…",
  "signal_score": 91, "importance": 88.2, "confidence": 98.1, "novelty": 87.4,
  "impact_score": 85, "velocity_score": 40, "anomaly_score": 12,
  "score_reasons": [{ "sign": "+", "text": "First-party source", "points": 8 }, { "sign": "-", "text": "Single source so far", "points": -5 }],
  "importance_components": { "severity": 82, "source": 92, "entity": 92, "novelty": 87, "magnitude": 40, "confirmation": 0, "userImpact": 85, "unusualness": 30 },
  "field_changes": [{ "label": "gpt-4o input", "kind": "price", "before": "$10.00", "after": "$8.00", "deltaPct": -20 }],
  "categories": ["ai", "technology"], "keywords": ["pricing"],
  "silent_change": true, "first_party": true, "country": "US", "language": "en",
  "evidence_label": "OBSERVED",
  "url": "https://openai.com/api/pricing/",
  "published_at": null, "observed_from": "…", "detected_at": "…", "processed_at": "…",
  "detection_latency_ms": null, "processing_latency_ms": 412,
  "cluster": { "id": "clu_…", "slug": "openai-pricing-…", "state": "developing", "event_count": 3, "source_count": 2,
               "first_party_count": 1, "external_count": 2, "velocity": 61, "lead_time_ms": 5400000 },
  "change_id": "chg_…", "old_snapshot_id": "snap_…", "new_snapshot_id": "snap_…",
  "source": { "id": "openai", "name": "OpenAI", "domain": "openai.com", "tier": "S" },
  "sensor": { "id": "openai_pricing", "name": "pricing", "type": "HTML", "connector": "http" },
  "entities": [{ "id": "org_openai", "name": "OpenAI", "type": "organization", "role": "subject" }]
}`}</Code>
          </Panel>
        </div>
        <aside className="flex min-w-0 flex-col gap-4">
          <Panel title="WebSocket live stream · protocol 2">
            <div className="flex flex-col gap-3 text-[13px]">
              <Code>{`wscat -c ${wss}/api/v1/live
> {"subscribe":["group:security","country:CA","entity:org_openai"]}
> {"since":"1757333722000-0"}   # after a reconnect`}</Code>
              <p className="text-fg-muted">Channels:</p>
              <ul className="list-disc space-y-0.5 pl-5 font-mono text-[12px] text-fg-muted [overflow-wrap:anywhere]">
                <li>events:global (default) · events:breaking · events:silent · events:first-party</li>
                <li>events:{"{ai|cyber|finance|health|government|science|products|infrastructure|news}"}</li>
                <li>group:{"{security|reliability|product|commercial|corporate|government|science|transport|sports|web}"}</li>
                <li>country:{"{CA}"} · state:{"{breaking|developing|confirmed}"} · type:{"{event_type}"}</li>
                <li>entity:{"{entity_id}"} · source:{"{source_id}"} · watchlist:{"{watchlist_id}"}</li>
              </ul>
              <p className="text-fg-muted">Frames:</p>
              <Code lang="json">{`{"type":"hello","channels":["events:global"]}
{"type":"event","sid":"1757333722000-0","channels":["events:global","group:product"],
 "event":{"id":"evt_…","slug":"…","type":"model_release","title":"…",
          "signal":93,"importance":97,"confidence":95,"novelty":90,"impact":80,"velocity":55,
          "silent":false,"firstParty":true,"country":"US","changeClass":"product",
          "fieldChanges":[…],"evidence":"OBSERVED","group":"product",
          "source":{"id":"openai","name":"OpenAI","domain":"openai.com"},
          "sensor":{"id":"openai_news","name":"news feed","type":"RSS"},
          "entities":[{"id":"org_openai","name":"OpenAI","type":"organization"}],
          "categories":["ai"],"url":"https://…","clusterId":"clu_…","clusterSlug":"…","clusterState":"breaking",
          "detectedAt":"2026-09-08T12:15:22Z","publishedAt":"2026-09-08T12:14:55Z"}}
{"type":"replay_done","since":"1757333722000-0","count":12,"truncated":false}
{"type":"heartbeat","t":1757333722000}`}</Code>
              <ul className="list-disc space-y-1 pl-5 text-[12.5px] text-fg-muted">
                <li>Every event frame carries a stream id <code>sid</code>. Keep the last one; after reconnecting send <code>{`{"since": sid}`}</code> and up to 500 missed events are replayed in order, then <code>replay_done</code>.</li>
                <li>Send <code>{`{"ping":1}`}</code> for a <code>pong</code>. Heartbeats every 25 s keep proxies alive.</li>
                <li>Subscriptions are additive; <code>unsubscribe</code> removes channels (including the default <code>events:global</code>).</li>
              </ul>
            </div>
          </Panel>
          <Panel title="Search syntax · q">
            <Code>{`openai pricing entity:org_openai type:pricing_change,terms_change
after:2026-09-01 before:2026-09-10 after:7d
silent:true first_party:true confirmed:true
importance:>70 confidence:>=50 signal:>80
source:"bank of canada" category:ai country:CA lang:fr
class:pricing group:security cluster:clu_…`}</Code>
            <p className="mt-2 text-[12px] text-fg-muted">Quoted values allowed; unknown keys stay in the free-text part. Works in <code>/events?q=</code>, <code>/search?q=</code> and the ⌘K palette.</p>
          </Panel>
          <Panel title="Conventions">
            <ul className="list-disc space-y-1 pl-5 text-[12.5px] text-fg-muted">
              <li>All timestamps are UTC ISO-8601. Ids are prefixed (<code>evt_ chg_ snap_ clu_ src_ sen_ ent_</code>).</li>
              <li>Cursor pagination: pass <code>nextCursor</code> back as <code>cursor</code>.</li>
              <li>Scores are 0–100. Signal, importance and confidence are independent; <code>score_reasons</code> explain each signal score.</li>
              <li>Every event traces to change → snapshots → sensor → source; snapshots are immutable. Retention may drop raw bodies (<code>has_raw: false</code>) but never canonical forms or hashes.</li>
              <li>Labels OBSERVED / INFERRED / CONFIRMED / UNCONFIRMED are always exposed; AI text is labelled analysis.</li>
              <li>
                Errors share one shape: <code>{`{"error": "snake_case_code", "detail"?: "…"}`}</code>. Validation failures add <code>details</code> (issues); 404 is <code>not_found</code>, 429 <code>monitor_limit_reached</code> / <code>too_many_*</code>.
              </li>
              <li>
                Rate limit 600 req / min / IP on <code>/api/*</code>, exposed as <Chip className="font-mono">x-ratelimit-limit</Chip> <Chip className="font-mono">x-ratelimit-remaining</Chip> <Chip className="font-mono">x-ratelimit-reset</Chip>; every response has <code>x-request-id</code>.
              </li>
              <li>Planned: API keys, MCP server, e-mail / Slack / Discord channels.</li>
            </ul>
          </Panel>
        </aside>
      </div>
    </>
  );
}