"use client";
import Link from "next/link";
import { ExternalLink } from "lucide-react";
import { Banner, Card, PageHeader } from "@/components/ui";

const BAR_COLUMNS: [string, string, string][] = [
  ["instrument_id", "string", "Stable id, e.g. firstrate:stock:AAPL"],
  ["symbol_as_reported", "string", "Ticker as delivered by the vendor at that date"],
  ["venue", "string?", "Exchange / venue when known"],
  ["asset_class", "string", "stock, etf, index, crypto, fx, futures"],
  ["interval", "string", "1m, 5m, 1d"],
  ["timestamp_utc", "timestamp[us, UTC]", "Bar OPEN instant, UTC"],
  ["session_date", "date", "US trading session (America/New_York)"],
  ["open / high / low / close", "float64", "Raw (as traded) prices"],
  ["volume", "float64", "Shares/contracts; zero-volume bars are absent"],
  ["currency", "string", "ISO 4217 (USD)"],
  ["trade_count", "int32?", "When supplied by the vendor"],
  ["vwap", "float64?", "When supplied by the vendor"],
  ["adjustment_type", "string", "Always raw in storage"],
  ["source_id", "string", "Source / product that produced the row"],
  ["ingested_at", "timestamp[us, UTC]", "Load instant"],
  ["quality_flags", "list<string>", "e.g. ohlc_inconsistent, price_jump, outside_session"],
  ["revision_id", "int32", "Increments when the vendor re-delivers a bar"],
];

export default function DocsPage() {
  return (
    <>
      <PageHeader
        title="Documentation"
        subtitle="What FinData OS is, the data contract, licensing and how to use the API."
        actions={
          <>
            <a className="btn btn-sm" href="/api/docs" target="_blank" rel="noopener">
              Swagger UI <ExternalLink className="h-3.5 w-3.5" />
            </a>
            <a className="btn btn-sm" href="/api/v1/openapi.json" target="_blank" rel="noopener">
              OpenAPI JSON <ExternalLink className="h-3.5 w-3.5" />
            </a>
          </>
        }
      />
      <div className="prose-sm grid gap-4 lg:grid-cols-[220px_minmax(0,1fr)]">
        <nav className="card hidden h-fit lg:sticky lg:top-6 lg:block" aria-label="On this page">
          <ul className="flex flex-col gap-1 text-sm">
            {[["#platform", "The platform"], ["#contract", "Data contract"], ["#bars", "Bars columns"], ["#adjustments", "Adjustments"], ["#fundamentals", "Fundamentals (PIT)"], ["#license", "License"], ["#api", "API quick start"], ["#sdk", "Python SDK"], ["#limits", "Limits"], ["#limitations", "Limitations"]].map(([h, l]) => (
              <li key={h}>
                <a href={h} className="nav-link">
                  {l}
                </a>
              </li>
            ))}
          </ul>
        </nav>
        <div className="flex min-w-0 flex-col gap-4">
          <Card title="The platform" id="platform">
            <p className="text-sm">
              <strong>FinData OS</strong> is a private, research-grade financial data lakehouse. It ingests vendor files (FirstRate Data intraday bars, corporate actions and fundamentals; SEC EDGAR when configured) into an immutable Parquet lake with a
              Postgres catalog, versions every dataset, checks quality at load time, and serves the result through one HTTP API that this console, the Python SDK and ad-hoc SQL all share. One writer (the ingest worker) owns the lake; the API is read-only
              except for job control, keys and settings.
            </p>
            <ul className="mt-2 list-disc pl-5 text-sm text-ink-2">
              <li>Curated layer: Parquet files per dataset, <code>base</code> files plus <code>delta</code> appends, compacted into new versions.</li>
              <li>Raw layer: vendor archives kept for re-processing (hash-verified).</li>
              <li>Catalog: datasets, versions, files, coverage per (symbol, session), instruments, corporate actions, jobs, exports, audit.</li>
            </ul>
          </Card>

          <Card title="Data contract" id="contract">
            <dl className="grid gap-x-6 gap-y-2 text-sm sm:grid-cols-[auto_1fr]">
              <dt className="font-medium">Timestamp convention</dt>
              <dd>
                Every bar is stamped at its <strong>open</strong>: the 1-minute bar labelled 13:30:00Z covers 13:30:00 → 13:30:59.999 UTC.
              </dd>
              <dt className="font-medium">Storage timezone</dt>
              <dd>
                <code>timestamp_utc</code> is UTC. <code>session_date</code> is the US trading session in America/New_York; it is the key for coverage and expected-bar counts.
              </dd>
              <dt className="font-medium">Session span</dt>
              <dd>
                Bars are retained for the extended session <strong>04:00 – 20:00 ET</strong>; regular hours are 09:30 – 16:00 ET. Completeness = bars ÷ expected regular-hours bars, capped at 100 %.
              </dd>
              <dt className="font-medium">Zero-volume bars</dt>
              <dd>Minutes without a trade are <strong>absent</strong>, not stored as zero rows. A gap is not necessarily a vendor outage — check the coverage page.</dd>
              <dt className="font-medium">Adjustments</dt>
              <dd>
                Stored prices are <strong>raw</strong>. <code>split</code> and <code>split_div</code> are computed at query time from the corporate-actions table (ex-date based, backward factor), so a new split re-adjusts history without rewriting
                files. The API echoes <code>adjustment_notes</code> explaining what was applied.
              </dd>
              <dt className="font-medium">Versioning</dt>
              <dd>
                Each dataset has a <code>current_version</code> with a snapshot id. Exports pin the version at submission; <code>GET /market/bars?version=</code> can read an earlier one.
              </dd>
              <dt className="font-medium">Quality flags</dt>
              <dd>Rows are never silently dropped; suspicious bars carry <code>quality_flags</code> and are also recorded as anomalies.</dd>
            </dl>
          </Card>

          <Card title="Bars schema (findata.schema = bars, version 1)" id="bars">
            <div className="table-wrap">
              <table className="table">
                <thead>
                  <tr>
                    <th>Column</th>
                    <th>Arrow type</th>
                    <th>Meaning</th>
                  </tr>
                </thead>
                <tbody>
                  {BAR_COLUMNS.map(([c, t, m]) => (
                    <tr key={c}>
                      <td className="font-mono text-xs">{c}</td>
                      <td className="font-mono text-xs text-ink-2">{t}</td>
                      <td className="text-xs">{m}</td>
                    </tr>
                  ))}
                </tbody>
              </table>
            </div>
            <p className="mt-2 text-xs text-ink-3">
              The authoritative schema is served by <code>GET /api/v1/catalog/schema/bars</code>. In the SQL playground each dataset is a DuckDB view named after its id with dots replaced by underscores, e.g. <code>market_bars_stock_1m_raw</code>.
            </p>
          </Card>

          <Card title="Adjustments in practice" id="adjustments">
            <ul className="list-disc pl-5 text-sm">
              <li>
                <code>raw</code> — prices as traded; volumes as reported. Use for microstructure work and when you join your own actions.
              </li>
              <li>
                <code>split</code> — prices divided and volumes multiplied by the cumulative split factor of all splits with ex-date after the bar.
              </li>
              <li>
                <code>split_div</code> — additionally applies the cash-dividend backward factor <em>(1 − D / P<sub>close, prev</sub>)</em>. Total-return style; not suitable for tick-size studies.
              </li>
            </ul>
          </Card>

          <Card title="Fundamentals — point in time" id="fundamentals">
            <p className="text-sm">
              Every fact carries <code>available_at</code> (= filing date + 1 day 00:00 America/New_York, a conservative knowability instant) and <code>observed_at</code> (when this platform first saw the value). A request with <code>as_of</code> returns
              only facts with <code>available_at ≤ as_of</code>; among revisions, the first observed value is used unless a later revision was observed before <code>as_of</code>. The response counts <code>facts_hidden_by_as_of</code> so you can tell how much of the
              record you are not seeing.
            </p>
          </Card>

          <Card title="License and redistribution" id="license">
            <Banner tone="warn">
              <strong>FirstRate Data — private use only, no redistribution.</strong>
            </Banner>
            <ul className="mt-3 list-disc pl-5 text-sm">
              <li>Raw bars, exports, SQL results and tables derived row-for-row from them may be used by the subscriber only. They may <strong>not</strong> be published, shared, re-hosted or served through a public API.</li>
              <li>Aggregated results (charts, statistics, model outputs) may be published with attribution to FirstRate Data.</li>
              <li>SEC EDGAR content is U.S. public domain; the SEC fair-access policy (declared User-Agent, request rate) applies to retrieval.</li>
              <li>API keys are personal. Every download, export and query is written to the audit log with the principal and request id.</li>
            </ul>
          </Card>

          <Card title="API quick start" id="api">
            <p className="text-sm">All endpoints live under <code>/api/v1</code>. Authenticate with the console session (cookie + <code>X-CSRF-Token</code> on writes) or with an API key: <code>Authorization: Bearer fd_…</code>. Errors are JSON: <code>{`{"error":{"code","message","request_id"}}`}</code>.</p>
            <pre className="mt-2 overflow-auto rounded-md border border-hairline bg-surface-2 p-3 text-xs leading-relaxed">{`export FINDATA_URL="https://findata.spboucher.ai"
export FINDATA_API_KEY="fd_xxx.yyy"

# health + catalog
curl -s -H "Authorization: Bearer $FINDATA_API_KEY" "$FINDATA_URL/api/v1/health" | jq .status
curl -s -H "Authorization: Bearer $FINDATA_API_KEY" "$FINDATA_URL/api/v1/catalog/datasets" | jq '.data[].id'

# one week of 1-minute bars, split-adjusted, as CSV (≤ 31 days per call for 1m)
curl -s -H "Authorization: Bearer $FINDATA_API_KEY" \\
  "$FINDATA_URL/api/v1/market/bars?symbol=AAPL&interval=1m&start=2026-10-20&end=2026-10-24&adjustment=split&format=csv&limit=10000" -o aapl.csv

# bigger ranges: async export → poll → download
curl -s -X POST -H "Authorization: Bearer $FINDATA_API_KEY" -H "Content-Type: application/json" \\
  -d '{"dataset_id":"market_bars.stock.1m.raw","symbols":["AAPL","MSFT"],"start":"2024-01-01","end":"2026-10-30","format":"parquet"}' \\
  "$FINDATA_URL/api/v1/exports"
# → {"id":"…","status":"queued","poll":"/api/v1/exports/…"}; when status=ready: GET /api/v1/exports/{id}/download

# point-in-time fundamentals
curl -s -H "Authorization: Bearer $FINDATA_API_KEY" \\
  "$FINDATA_URL/api/v1/fundamentals/AAPL?as_of=2025-01-01T00:00:00Z&metrics=rev,net_inc&period_type=q"

# read-only SQL (DuckDB)
curl -s -X POST -H "Authorization: Bearer $FINDATA_API_KEY" -H "Content-Type: application/json" \\
  -d '{"sql":"SELECT session_date, sum(volume) v FROM market_bars_stock_1m_raw WHERE symbol_as_reported='"'"'AAPL'"'"' GROUP BY 1 ORDER BY 1 DESC LIMIT 5","max_rows":100}' \\
  "$FINDATA_URL/api/v1/query"`}</pre>
          </Card>

          <Card title="Python SDK" id="sdk">
            <p className="text-sm">
              Install from the repo (<code>packages/python-sdk</code>): <code>pip install -e packages/python-sdk</code>. The client pages through Arrow IPC automatically.
            </p>
            <pre className="mt-2 overflow-auto rounded-md border border-hairline bg-surface-2 p-3 text-xs leading-relaxed">{`from findata_sdk import FinData

fd = FinData("https://findata.spboucher.ai", api_key="fd_xxx.yyy")   # or FINDATA_URL / FINDATA_API_KEY env vars

bars = fd.bars("AAPL", "1m", "2026-10-26", "2026-10-30", adjustment="split")   # pyarrow.Table, all pages
df = bars.to_pandas()                                                           # or .to_polars()

path = fd.export(["AAPL", "MSFT"], "2024-01-01", "2026-10-30", format="parquet")  # waits, downloads, returns local path

facts = fd.fundamentals("AAPL", as_of="2025-01-01T00:00:00Z", metrics=["rev", "net_inc"])
print(fd.datasets()[0]["id"], fd.health()["status"])`}</pre>
          </Card>

          <Card title="Limits" id="limits">
            <ul className="list-disc pl-5 text-sm">
              <li>
                <code>GET /market/bars</code>: span ≤ <strong>31 days</strong> for 1m, 186 days for 5m, 3 660 days for 1d; ≤ 10 000 rows per page (cursor pagination). HTTP 413 <code>range_too_large</code> otherwise → use{" "}
                <Link href="/exports/" className="text-accent-ink hover:underline">
                  Exports
                </Link>
                .
              </li>
              <li>Exports: ≤ 500 symbols, ≤ 12 years, 3 concurrent per principal, files expire after ~72 h.</li>
              <li>SQL: one read-only statement, server-side timeout, ≤ 100 000 rows; the console displays at most 1 000 rows (download the CSV for the rest).</li>
              <li>Rate limit per key/session (default 600 requests/min, HTTP 429 with <code>Retry-After</code>).</li>
            </ul>
          </Card>

          <Card title="Known limitations" id="limitations">
            <ul className="list-disc pl-5 text-sm">
              <li>
                <strong>Fundamentals revision history starts at first ingestion.</strong> Values observed before the platform existed are a single revision (proxy for “as originally filed”); true as-filed history for older periods is not reconstructed.
              </li>
              <li>
                <strong>SEC EDGAR is “pending configuration”</strong> until a fair-access User-Agent is set on the server (<code>SEC_EDGAR_USER_AGENT</code>). Until then the dataset is listed but empty.
              </li>
              <li>
                <strong>Unsupported:</strong> tick data, quotes/NBBO, order-book depth, options chains. Those datasets appear as <em>unsupported</em> in the catalog on purpose so nobody plans on them.
              </li>
              <li>Vendor files arrive with a lag (typically next day); the overview shows <em>vendor lag</em> and <em>days since last session</em> per dataset.</li>
              <li>The console is a static bundle served by the API; it needs JavaScript and a modern browser. No telemetry, no third-party assets.</li>
            </ul>
          </Card>
        </div>
      </div>
    </>
  );
}