import type { Metadata } from "next";
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: "Authentication",
  description: "API keys, Bearer and X-API-Key headers, scopes, rotation, revocation and the email verification requirement.",
};

export default function AuthenticationPage() {
  return (
    <DocPage path="/docs/authentication" title="Authentication" description="Every request to the Fetcha API is authenticated with a project-scoped API key sent in a header. Keys carry scopes, a mode and an optional expiry." status="Stable">
      <H2>API keys</H2>
      <P>
        Keys are created in the dashboard under a project. A key belongs to exactly one project and one organization; the requests it makes are logged and counted against them (Fetcha is a private
        platform with a single unlimited plan, so nothing is billed). The plaintext has a recognisable prefix so you can tell keys apart in configuration:
      </P>
      <Table>
        <THead>
          <Tr>
            <Th>Prefix</Th>
            <Th>Mode</Th>
            <Th>Meaning</Th>
          </Tr>
        </THead>
        <TBody>
          <Tr>
            <Td mono>fch_live_…</Td>
            <Td>live</Td>
            <Td>Production key. Use it in deployed services.</Td>
          </Tr>
          <Tr>
            <Td mono>fch_test_…</Td>
            <Td>test</Td>
            <Td>
              Marked as a test key in logs and in <Code>GET /v1/me</Code>. Behaves like a live key today: requests are real and appear in your usage.
            </Td>
          </Tr>
        </TBody>
      </Table>
      <P>
        A key is between 20 and 128 characters. Anything else, or a token without one of the two prefixes, is rejected with <Code>401 INVALID_API_KEY</Code> before the database is consulted.
      </P>

      <H3>Shown once, hashed at rest</H3>
      <P>
        The plaintext is displayed a single time when the key is created (or rotated). Fetcha persists only a SHA-256 hash together with the non-secret prefix and last four characters used to
        identify the key in the dashboard. There is no way to retrieve a lost key; rotate it instead.
      </P>

      <H2>Sending the key</H2>
      <P>Use the standard Bearer scheme. This is what the SDKs send.</P>
      <CodeBlock lang="text" code={`Authorization: Bearer fch_live_…`} />
      <P>
        If your HTTP client cannot set <Code>Authorization</Code>, send the key in <Code>X-API-Key</Code> instead. When both headers are present, <Code>X-API-Key</Code> takes precedence.
      </P>
      <CodeBlock lang="text" code={`X-API-Key: fch_live_…`} />
      <Callout variant="warning" title="Server-side only">
        Never ship a key in a browser bundle or mobile app: anyone who can read it can fetch on your behalf, fill your request log and trip your spending limits. Call Fetcha from your backend. The API allows cross-origin requests so that the dashboard
        can talk to it, not so that keys can live in the browser.
      </Callout>

      <H2>Scopes</H2>
      <P>
        Each key has a list of scopes chosen at creation. A request that needs a scope the key lacks is refused with <Code>403 FORBIDDEN</Code> and a message naming the missing scope.
      </P>
      <Table>
        <THead>
          <Tr>
            <Th>Scope</Th>
            <Th>Grants</Th>
            <Th>Status</Th>
          </Tr>
        </THead>
        <TBody>
          <Tr>
            <Td mono>fetch:execute</Td>
            <Td>
              <Code>POST /v1/fetch</Code>
            </Td>
            <Td>Live</Td>
          </Tr>
          <Tr>
            <Td mono>sessions:write</Td>
            <Td>
              <Code>POST /v1/sessions</Code>, <Code>DELETE /v1/sessions/:id</Code>. Listing and reading sessions requires no scope.
            </Td>
            <Td>Live</Td>
          </Tr>
          <Tr>
            <Td mono>usage:read</Td>
            <Td>
              <Code>GET /v1/usage</Code>
            </Td>
            <Td>Live</Td>
          </Tr>
          <Tr>
            <Td mono>browser:use</Td>
            <Td>
              Kept for compatibility. The <A href="/docs/browser">managed browser</A> is part of <Code>POST /v1/fetch</Code> and needs only <Code>fetch:execute</Code>.
            </Td>
            <Td>Compatibility</Td>
          </Tr>
        </TBody>
      </Table>
      <P>
        <Code>GET /v1/me</Code> and <Code>GET /v1/sessions</Code> only require a valid key.
      </P>

      <H2>Accounts and email verification</H2>
      <P>
        Fetcha is invitation-only: an account can only be created with an email address that a Fetcha administrator placed on the access list. Once the account exists, API keys work only after
        that email address is verified. Until then every authenticated call, including <Code>/v1/me</Code>, fails with <Code>403 EMAIL_NOT_VERIFIED</Code>. Resend the verification email from the
        dashboard if you did not receive it. The dashboard Playground is exempt so you can try the product before verifying.
      </P>
      <ResponseExample
        status={403}
        statusText="Forbidden"
        body={{ error: { code: "EMAIL_NOT_VERIFIED", message: "Verify your email address before using the production API.", request_id: "req_7f2c1a9e0d4b6h3k" } }}
      />

      <H2>Rotation and revocation</H2>
      <Ul>
        <Li>
          <Strong>Rotate</Strong> replaces the secret of an existing key and shows the new plaintext once. The old plaintext stops working immediately.
        </Li>
        <Li>
          <Strong>Revoke</Strong> disables a key permanently. Requests made with it return <Code>401 INVALID_API_KEY</Code> with the message <Code>This API key was revoked.</Code>
        </Li>
        <Li>
          <Strong>Expiry</Strong> is optional and set in days at creation. Expired keys return <Code>401 INVALID_API_KEY</Code> with <Code>This API key has expired.</Code>
        </Li>
      </Ul>
      <P>
        Authenticated principals are cached for up to 30 seconds per API process. The dashboard invalidates the cache when you rotate or revoke, so changes normally apply at once; in the rare case
        the invalidation is lost, a stale key stops working within 30 seconds.
      </P>
      <P>
        Other conditions that block a key even when it is valid: the project was archived (<Code>403 FORBIDDEN</Code>), the organization was suspended (<Code>403 FORBIDDEN</Code>, contact{" "}
        <A href="mailto:support@fetcha.co">support@fetcha.co</A>).
      </P>

      <H2>Checking a key</H2>
      <P>
        <Code>GET /v1/me</Code> validates the key and returns the project, organization and key metadata it resolves to. It is the cheapest call you can make and a good health check for your
        configuration.
      </P>
      <Endpoint method="GET" path="/v1/me" scope={null} status="Live" />
      <CodeTabs tabs={apiTabs({ method: "GET", path: "/v1/me" })} />
      <ResponseExample
        status={200}
        body={{
          project: { id: "proj_2k8d1m3p9q4r7s6t", name: "Default" },
          organization: { id: "org_9a1b2c3d4e5f6g7h", name: "Acme Data", plan: "unlimited" },
          key: { id: "key_5t6y7u8i9o0p1a2s", name: "backend", mode: "live", scopes: ["fetch:execute", "sessions:write", "usage:read"] },
        }}
      />

      <H2>Logging and redaction</H2>
      <P>
        Fetcha never logs your API key. On the request log, <Code>Authorization</Code>, <Code>Cookie</Code>, <Code>Set-Cookie</Code>, <Code>X-API-Key</Code> and similar headers that you send to
        targets are stored as <Code>[redacted]</Code> when your project log level includes headers. Response bodies are not stored by default.
      </P>
    </DocPage>
  );
}