import type { Metadata } from "next";
import { PLAN_LIMITS } from "@fetcha/core";
import { CodeBlock } from "@/components/ui/code-block";
import { DocPage } from "@/components/docs/doc-page";
import { A, Code, H2, H3, Li, P, Strong, Table, TBody, Td, Th, THead, Tr, Ul } from "@/components/docs/prose";
import { Callout } from "@/components/docs/callout";
import { Endpoint } from "@/components/docs/endpoint";
import { CodeTabs } from "@/components/docs/code-tabs";
import { ResponseExample } from "@/components/docs/response-example";
import { apiTabs } from "@/components/docs/snippets";

export const metadata: Metadata = {
  title: "Rate Limits",
  description: "Concurrency, sliding-window rate limits, RATE_LIMITED vs CONCURRENCY_LIMIT, optional spending limits, USAGE_LIMIT_REACHED and response headers on the single unlimited plan.",
};

const L = PLAN_LIMITS.unlimited;
const fmt = (n: number) => n.toLocaleString("en-US");

export default function RateLimitsPage() {
  const perOrgMinute = Math.max(60, L.concurrency * 60);
  const perKeySecond = Math.max(10, L.concurrency * 2);
  return (
    <DocPage
      path="/docs/rate-limits"
      eyebrow="Reliability"
      title="Rate limits"
      description="Fetcha is a private platform with a single plan: there is no monthly request quota. Two operational limits remain — how many requests run at once and how fast you can submit them — plus spending limits you can set yourself."
      status="Stable"
    >
      <Callout variant="info" title="One plan, no meters">
        Every organization has the same limits, listed below and returned by <Code>GET /v1/usage</Code>. There is nothing to upgrade: hitting a limit means smoothing your traffic, not paying more.
      </Callout>

      <H2>Concurrency</H2>
      <P>
        Concurrency is the number of fetch requests in flight at the same time, counted per <Strong>organization</Strong> (all projects and keys together). It is the limit that matters most in
        practice: a fetch takes a second or more, so sustained throughput is roughly concurrency divided by average latency.
      </P>
      <Table>
        <THead>
          <Tr>
            <Th>Limit</Th>
            <Th>Value</Th>
            <Th>Scope</Th>
          </Tr>
        </THead>
        <TBody>
          <Tr>
            <Td className="font-medium text-fg">Concurrent requests</Td>
            <Td mono>{fmt(L.concurrency)}</Td>
            <Td>Organization</Td>
          </Tr>
          <Tr>
            <Td className="font-medium text-fg">Concurrent browser renders</Td>
            <Td mono>{fmt(L.browser_concurrency)}</Td>
            <Td>Organization (subset of the above)</Td>
          </Tr>
          <Tr>
            <Td className="font-medium text-fg">Concurrent crawl jobs</Td>
            <Td mono>{fmt(L.crawl_concurrent_jobs)}</Td>
            <Td>Organization</Td>
          </Tr>
          <Tr>
            <Td className="font-medium text-fg">Monthly requests</Td>
            <Td mono>Unlimited</Td>
            <Td>&mdash;</Td>
          </Tr>
          <Tr>
            <Td className="font-medium text-fg">Log retention</Td>
            <Td mono>{L.retention_days} days</Td>
            <Td>Organization</Td>
          </Tr>
        </TBody>
      </Table>
      <P>
        When a request would exceed the limit it is refused immediately with <Code>429 CONCURRENCY_LIMIT</Code>; nothing is queued on Fetcha&apos;s side. A slot is released as soon as a request
        completes (successfully or not). As a safety net, a slot that is somehow never released expires after 150 seconds.
      </P>
      <ResponseExample status={429} statusText="Too Many Requests" body={{ error: { code: "CONCURRENCY_LIMIT", message: `Your organization allows ${L.concurrency} concurrent requests.`, request_id: "req_1l2m3n4o5p6q7r8s", details: { limit: L.concurrency } } }} />

      <H2>Request rate</H2>
      <P>
        Independently of concurrency, submissions are metered with sliding windows. They are set well above what the concurrency limit lets you sustain, so they only bite on bursts or runaway
        loops. Three windows are checked on every fetch:
      </P>
      <Table>
        <THead>
          <Tr>
            <Th>Window</Th>
            <Th>Scope</Th>
            <Th>Rule</Th>
            <Th>Value</Th>
          </Tr>
        </THead>
        <TBody>
          <Tr>
            <Td>60 seconds</Td>
            <Td>Organization (sustained)</Td>
            <Td>
              <Code>concurrency × 60</Code> per minute
            </Td>
            <Td mono>{fmt(perOrgMinute)} / min</Td>
          </Tr>
          <Tr>
            <Td>1 second</Td>
            <Td>API key (burst)</Td>
            <Td>
              <Code>concurrency × 2</Code> per second
            </Td>
            <Td mono>{fmt(perKeySecond)} / s</Td>
          </Tr>
          <Tr>
            <Td>1 second</Td>
            <Td>Client IP (abuse)</Td>
            <Td>Fixed</Td>
            <Td mono>200 / s</Td>
          </Tr>
        </TBody>
      </Table>
      <P>
        Exceeding any window returns <Code>429 RATE_LIMITED</Code> with a <Code>Retry-After</Code> header (seconds, rounded up) and <Code>details.retry_after_ms</Code>.
      </P>
      <ResponseExample status={429} statusText="Too Many Requests" body={{ error: { code: "RATE_LIMITED", message: "Too many requests. Slow down and retry after the indicated delay.", request_id: "req_4e5f6g7h8i9j0k1l", details: { retry_after_ms: 640 } } }} />

      <H3>RATE_LIMITED vs CONCURRENCY_LIMIT</H3>
      <Ul>
        <Li>
          <Code>RATE_LIMITED</Code>: you submitted too many requests in a short window. Wait <Code>Retry-After</Code> seconds, then continue. Smooth your submission rate.
        </Li>
        <Li>
          <Code>CONCURRENCY_LIMIT</Code>: too many requests are running right now. Do not sleep a fixed time; retry when one of your in-flight requests finishes. Use a semaphore or worker pool sized
          to {fmt(L.concurrency)} or less (see the <A href="/docs/examples#concurrency-within-plan-limits">concurrency example</A>).
        </Li>
      </Ul>

      <H2>No monthly quota</H2>
      <P>
        There is no cap on the number of requests per month and no overage. Usage is still counted per organization and per project (<Strong>every request that reaches the execution pipeline
        counts</Strong>, including those that end blocked or failed) so that the dashboard, <Code>GET /v1/usage</Code> and your optional spending limits have accurate figures. Requests refused
        earlier (authentication, validation, rate limits, session errors) are not counted.
      </P>

      <H2>Spending and project limits</H2>
      <P>
        You can cap usage yourself in the dashboard. These are guard-rails against runaway jobs, not billing: spend is an internal cost estimate and nothing is invoiced. All of them produce the same{" "}
        <Code>USAGE_LIMIT_REACHED</Code> code with a specific message and details:
      </P>
      <Table dense>
        <THead>
          <Tr>
            <Th>Limit</Th>
            <Th>Scope</Th>
            <Th>Effect when reached</Th>
            <Th>details</Th>
          </Tr>
        </THead>
        <TBody>
          <Tr>
            <Td>Monthly request limit</Td>
            <Td>Project</Td>
            <Td>Fetches in that project are refused</Td>
            <Td mono>{`{ limit, used }`}</Td>
          </Tr>
          <Tr>
            <Td>Hard spending limit (USD estimate)</Td>
            <Td>Organization</Td>
            <Td>All fetches are refused</Td>
            <Td mono>{`{ limit_usd, spent_usd }`}</Td>
          </Tr>
          <Tr>
            <Td>Hard spending limit (USD estimate)</Td>
            <Td>Project</Td>
            <Td>Fetches in that project are refused</Td>
            <Td mono>{`{ limit_usd, spent_usd }`}</Td>
          </Tr>
          <Tr>
            <Td>Soft spending limit (USD estimate)</Td>
            <Td>Organization or project</Td>
            <Td>Alert only; traffic continues</Td>
            <Td>&mdash;</Td>
          </Tr>
        </TBody>
      </Table>
      <ResponseExample
        status={402}
        statusText="Payment Required"
        title="402 · project request limit reached (set by you)"
        body={{ error: { code: "USAGE_LIMIT_REACHED", message: "Monthly request limit of 50,000 reached for this project.", request_id: "req_8s9t0u1v2w3x4y5z", details: { limit: 50000, used: 50000 } } }}
      />
      <Callout variant="info" title="Spend is an estimate">
        Spend is Fetcha&apos;s internal cost estimate of your usage, accumulated over the calendar month (UTC). It is what <Code>GET /v1/usage</Code> reports as <Code>spend_usd</Code>. Usage counters
        are cached for up to 20 seconds, so enforcement of a limit you set can lag a few requests behind.
      </Callout>

      <H2>Checking your usage</H2>
      <Endpoint method="GET" path="/v1/usage" scope="usage:read" status="Live" />
      <CodeTabs tabs={apiTabs({ method: "GET", path: "/v1/usage" }, ["curl", "javascript", "python"])} />
      <ResponseExample
        status={200}
        body={{
          period_start: "2026-09-01T00:00:00.000Z",
          plan: { id: "unlimited", label: "Unlimited", monthly_requests: null, concurrency: L.concurrency },
          organization: { requests: 12840, spend_usd: 3.2115 },
          project: { requests: 9911, spend_usd: 2.4402, successful_requests: 9640, success_rate: 97.3, bandwidth_bytes: 3892214411, latency_p50_ms: 1180, latency_p95_ms: 4210 },
          remaining_requests: null,
        }}
      />
      <Ul>
        <Li>
          <Code>organization</Code> covers every project; <Code>project</Code> is the key&apos;s project only.
        </Li>
        <Li>
          <Code>plan.monthly_requests</Code> and <Code>remaining_requests</Code> are <Code>null</Code>: there is no quota. A project-level request limit you configured is reported in the
          dashboard, not here.
        </Li>
        <Li>
          <Code>success_rate</Code> is a percentage with one decimal, or <Code>null</Code> when the project made no requests this month.
        </Li>
      </Ul>

      <H2>Response headers</H2>
      <P>Fetcha currently sets these headers on every API response. There are no <Code>X-RateLimit-*</Code> counters; use <Code>GET /v1/usage</Code> for month-to-date figures.</P>
      <CodeBlock
        lang="text"
        code={`X-Fetcha-Request-ID: req_…     # always; quote it to support
X-Fetcha-Version: 0.2.0         # API version
Cache-Control: no-store         # responses are never cacheable
Retry-After: <seconds>          # only on 429 RATE_LIMITED`}
      />
    </DocPage>
  );
}