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 { ParamTable } from "@/components/docs/param-table";
import { CodeTabs } from "@/components/docs/code-tabs";
import { ResponseExample } from "@/components/docs/response-example";
import { apiTabs, fetchTabs } from "@/components/docs/snippets";

export const metadata: Metadata = {
  title: "Sessions",
  description: "Sticky sessions keep the same exit identity across requests: create, use, inspect and close them, with TTL, geography, idempotency and expiry rules.",
};

const SESSION = {
  id: "sess_8f2k1m9d3p7q4r6s",
  label: "checkout-user-42",
  status: "active",
  network: "residential",
  country: "CA",
  region: "quebec",
  city: null,
  request_count: 0,
  last_used_at: null,
  expires_at: "2026-09-07T14:32:11.000Z",
  created_at: "2026-09-07T14:17:11.000Z",
};

export default function SessionsPage() {
  return (
    <DocPage path="/docs/sessions" eyebrow="Core API" title="Sessions" description="A session pins a stable exit identity for a period of time so that a sequence of requests looks like one visitor. Use it for login flows, paginated listings and any site that ties state to the client IP." status="Stable">
      <H2>What a session preserves</H2>
      <Ul>
        <Li>
          <Strong>Exit identity.</Strong> All requests that reference the session are routed through the same network route with the same sticky key, so the target sees the same IP for the
          session&apos;s lifetime, as long as the network keeps that exit available.
        </Li>
        <Li>
          <Strong>Network class and geography.</Strong> The class chosen at creation and the country you asked for are applied to every request that omits them.
        </Li>
        <Li>
          <Strong>Cookies you pass.</Strong> Fetcha does not maintain a cookie jar. Read <Code>cookies</Code> from a response and send them back in the next request&apos;s <Code>cookies</Code>{" "}
          field. Because the IP is stable, the target accepts them as belonging to the same visitor.
        </Li>
      </Ul>
      <Callout variant="info" title="Retries inside a session">
        Normally each retry uses a fresh exit IP. When a request is pinned to a session, retries keep the session&apos;s identity so the target never sees the visitor jump between IPs. If the
        session&apos;s exit is being blocked, close the session and create a new one.
      </Callout>

      <H2>Create a session</H2>
      <Endpoint method="POST" path="/v1/sessions" scope="sessions:write" status="Live" />
      <ParamTable
        rows={[
          { name: "country", type: "string", constraints: "exactly 2 chars", description: <>ISO 3166-1 alpha-2 country for the exit. See <A href="/docs/geolocation">Geolocation</A>.</> },
          { name: "region", type: "string", constraints: "≤ 64 chars", description: <>State or province hint.</> },
          { name: "city", type: "string", constraints: "≤ 128 chars", description: <>City hint.</> },
          { name: "network", type: '"auto" | "datacenter" | "residential" | "isp" | "mobile"', default: '"auto"', description: <>Network class. The concrete class picked by the engine is returned in <code>network</code>. Classes outside your plan or without a sticky-capable route return <code>NETWORK_UNAVAILABLE</code>.</> },
          { name: "ttl", type: "integer (seconds)", default: "600", constraints: "60–1,800", description: <>Lifetime of the session. It is fixed at creation and is <strong>not</strong> extended by use.</> },
          { name: "label", type: "string", constraints: "≤ 128 chars", description: <>Free-form label for your own bookkeeping, shown in the dashboard.</> },
        ]}
      />
      <P>
        The body may be empty (<Code>{"{}"}</Code>): you then get a 10-minute session on the best sticky-capable route with no geography constraint. The schema is strict; unknown fields fail
        with <Code>INVALID_REQUEST</Code>.
      </P>
      <CodeTabs tabs={apiTabs({ method: "POST", path: "/v1/sessions", body: { country: "CA", region: "QC", ttl: 900, label: "checkout-user-42" }, idempotencyKey: "checkout-user-42-2026-09-07" })} />
      <ResponseExample status={200} body={SESSION} />
      <ParamTable
        showDefault={false}
        rows={[
          { name: "id", type: "string", description: <>Session identifier (<code>sess_…</code>). Pass it as <code>session</code> in fetch requests.</> },
          { name: "label", type: "string | null", description: <>Your label.</> },
          { name: "status", type: '"active" | "expired" | "closed"', description: <><code>expired</code> is derived from <code>expires_at</code>; <code>closed</code> means you deleted it.</> },
          { name: "network", type: "string", description: <>Concrete class serving the session.</> },
          { name: "country / region / city", type: "string | null", description: <>Normalised geography (region and city as slugs).</> },
          { name: "request_count", type: "integer", description: <>Number of fetch requests that used the session.</> },
          { name: "last_used_at", type: "string | null", description: <>ISO 8601 timestamp of the last fetch, or <code>null</code>.</> },
          { name: "expires_at", type: "string", description: <>ISO 8601 expiry, <code>created_at + ttl</code>.</> },
          { name: "created_at", type: "string", description: <>ISO 8601 creation time.</> },
        ]}
      />

      <H3>Idempotency-Key</H3>
      <P>
        Send an <Code>Idempotency-Key</Code> header with the create request to make it safe to retry. If Fetcha has already created a session for that key in your project within the last 24
        hours, it returns the existing session instead of creating a new one. Keys are scoped to the project; any string works, though a value derived from your own entity (user id, job id) is
        the most useful.
      </P>

      <H2>Use a session in a fetch</H2>
      <P>
        Reference the id in the <Code>session</Code> field. If you omit <Code>country</Code>, the session&apos;s country applies; if <Code>network</Code> is <Code>auto</Code>, the session&apos;s class
        applies. <Code>metadata.session</Code> echoes the id.
      </P>
      <CodeTabs
        tabs={fetchTabs(
          { url: "https://www.example.ca/account", session: "sess_8f2k1m9d3p7q4r6s", cookies: { sid: "3f9a…" } },
          {
            javascript: `console.log(data.metadata.session, data.metadata.country); // "sess_8f2k1m9d3p7q4r6s" "CA"`,
            python: `print(data["metadata"]["session"], data["metadata"]["country"])`,
          },
        )}
      />
      <Table dense>
        <THead>
          <Tr>
            <Th>Condition</Th>
            <Th>Result</Th>
          </Tr>
        </THead>
        <TBody>
          <Tr>
            <Td>Id does not exist, or belongs to another project</Td>
            <Td mono>404 SESSION_NOT_FOUND</Td>
          </Tr>
          <Tr>
            <Td>
              Session is past <Code>expires_at</Code>, or was closed
            </Td>
            <Td mono>410 SESSION_EXPIRED</Td>
          </Tr>
        </TBody>
      </Table>
      <P>
        Both are raised before any network activity, so they cost nothing and do not consume an attempt. Pass the same geography as the session or omit it; requesting a different country on a
        pinned session is allowed but defeats the purpose.
      </P>

      <H2>List sessions</H2>
      <Endpoint method="GET" path="/v1/sessions" scope={null} status="Live" />
      <P>Returns the 100 most recent sessions of the project, newest first, including expired and closed ones.</P>
      <CodeTabs tabs={apiTabs({ method: "GET", path: "/v1/sessions" }, ["curl", "javascript", "python"])} />
      <ResponseExample status={200} body={{ data: [SESSION] }} />

      <H2>Get a session</H2>
      <Endpoint method="GET" path="/v1/sessions/:id" scope={null} status="Live" />
      <CodeTabs tabs={apiTabs({ method: "GET", path: "/v1/sessions/sess_8f2k1m9d3p7q4r6s" }, ["curl", "javascript", "python"])} />
      <P>
        Returns the same object as creation, with a live <Code>status</Code>. Unknown ids return <Code>404 SESSION_NOT_FOUND</Code>.
      </P>

      <H2>Close a session</H2>
      <Endpoint method="DELETE" path="/v1/sessions/:id" scope="sessions:write" status="Live" />
      <CodeTabs tabs={apiTabs({ method: "DELETE", path: "/v1/sessions/sess_8f2k1m9d3p7q4r6s" }, ["curl", "javascript", "python"])} />
      <ResponseExample status={200} body={{ id: "sess_8f2k1m9d3p7q4r6s", status: "closed" }} />
      <P>
        Closing is immediate and irreversible; later fetches with the id return <Code>SESSION_EXPIRED</Code>. Sessions you do not close simply expire at <Code>expires_at</Code>. There is no per-plan
        limit on the number of sessions.
      </P>

      <H2>Two-step login example</H2>
      <P>
        A typical flow: create a session, POST credentials, keep the returned cookies, then GET the protected page with the same session and cookies. The SDK version is on the{" "}
        <A href="/docs/examples">Examples</A> page.
      </P>
      <CodeBlock
        lang="bash"
        title="Terminal"
        code={`# 1. Create a Canadian session for 15 minutes
SESSION=$(curl -s https://www.fetcha.co/v1/sessions -X POST \\
  -H "Authorization: Bearer $FETCHA_API_KEY" -H "Content-Type: application/json" \\
  -d '{"country": "CA", "ttl": 900}' | jq -r .id)

# 2. Log in (cookies come back in .cookies)
curl -s https://www.fetcha.co/v1/fetch -X POST \\
  -H "Authorization: Bearer $FETCHA_API_KEY" -H "Content-Type: application/json" \\
  -d "{\\"url\\": \\"https://www.example.ca/login\\", \\"method\\": \\"POST\\", \\"session\\": \\"$SESSION\\",
       \\"headers\\": {\\"Content-Type\\": \\"application/x-www-form-urlencoded\\"},
       \\"body\\": \\"user=me&pass=secret\\"}" | jq .cookies

# 3. Fetch the account page with the same session and the returned cookies
curl -s https://www.fetcha.co/v1/fetch -X POST \\
  -H "Authorization: Bearer $FETCHA_API_KEY" -H "Content-Type: application/json" \\
  -d "{\\"url\\": \\"https://www.example.ca/account\\", \\"session\\": \\"$SESSION\\", \\"format\\": \\"text\\",
       \\"cookies\\": {\\"sid\\": \\"3f9a…\\"}}" | jq -r .text`}
      />
    </DocPage>
  );
}