import type { Metadata } from "next";
import { COUNTRIES } from "@fetcha/core";
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 { CodeTabs } from "@/components/docs/code-tabs";
import { ParamTable } from "@/components/docs/param-table";
import { ResponseExample } from "@/components/docs/response-example";
import { fetchTabs } from "@/components/docs/snippets";

export const metadata: Metadata = {
  title: "Geolocation",
  description: "Target a country, region and city for the exit IP: accepted values, normalisation rules and behaviour when a location is unavailable.",
};

const CA_REGIONS: Array<[string, string, string]> = [
  ["QC", "Quebec", "quebec"],
  ["ON", "Ontario", "ontario"],
  ["BC", "British Columbia", "british_columbia"],
  ["AB", "Alberta", "alberta"],
  ["MB", "Manitoba", "manitoba"],
  ["SK", "Saskatchewan", "saskatchewan"],
  ["NS", "Nova Scotia", "nova_scotia"],
  ["NB", "New Brunswick", "new_brunswick"],
  ["NL", "Newfoundland and Labrador", "newfoundland_and_labrador"],
  ["PE / PEI", "Prince Edward Island", "prince_edward_island"],
  ["YT", "Yukon", "yukon"],
  ["NT", "Northwest Territories", "northwest_territories"],
  ["NU", "Nunavut", "nunavut"],
];

const US_SAMPLE: Array<[string, string]> = [
  ["CA", "california"],
  ["NY", "new_york"],
  ["TX", "texas"],
  ["FL", "florida"],
  ["WA", "washington"],
  ["IL", "illinois"],
  ["MA", "massachusetts"],
  ["NJ", "new_jersey"],
  ["NC", "north_carolina"],
  ["DC", "district_of_columbia"],
];

export default function GeolocationPage() {
  const countries = Object.entries(COUNTRIES);
  return (
    <DocPage path="/docs/geolocation" eyebrow="Core API" title="Geolocation" description="Choose where your request appears to come from. Country is the primary control; region and city refine it where the network has coverage." status="Stable">
      <H2>Fields</H2>
      <P>
        The three geography fields are shared by <Code>POST /v1/fetch</Code> and <Code>POST /v1/sessions</Code>. All are optional. When none is set, the network picks any exit and{" "}
        <Code>metadata.country</Code> is <Code>null</Code>.
      </P>
      <ParamTable
        showDefault={false}
        rows={[
          { name: "country", type: "string", constraints: "exactly 2 characters", description: <>ISO 3166-1 alpha-2 code. Case-insensitive; normalised to upper case (<code>{`"ca"`}</code> → <code>{`"CA"`}</code>). Any other length fails validation with <code>INVALID_REQUEST</code>.</> },
          { name: "region", type: "string", constraints: "≤ 64 characters", description: <>State, province or territory. For <code>US</code> and <code>CA</code>, two-letter postal codes and full names are recognised and normalised to a canonical slug. For every other country the value is slugified as-is.</> },
          { name: "city", type: "string", constraints: "≤ 128 characters", description: <>City name, slugified: accents removed, lower-cased, non-alphanumeric runs replaced by <code>_</code>. <code>{`"Québec"`}</code> → <code>quebec</code>, <code>{`"Saint-Jean-sur-Richelieu"`}</code> → <code>saint_jean_sur_richelieu</code>.</> },
        ]}
      />

      <H2>Example</H2>
      <P>Fetch through a residential exit in Québec City, Canada.</P>
      <CodeTabs
        tabs={fetchTabs(
          { url: "https://www.example.ca/", country: "CA", region: "QC", city: "Quebec" },
          {
            javascript: `console.log(data.metadata.country); // "CA"`,
            python: `print(data["metadata"]["country"])  # "CA"`,
          },
        )}
      />
      <ResponseExample
        status={200}
        title="200 OK · metadata excerpt"
        body={{ metadata: { network: "residential", country: "CA", attempts: 1, duration_ms: 1290, bytes: 61233, session: null, cached: false } }}
      />

      <H2>Normalisation</H2>
      <P>
        Fetcha converts what you send into a canonical internal form before handing it to the network, so the same location can be written several ways. The tables below show the recognised
        aliases for Canada and a sample for the United States; every US state, plus <Code>DC</Code>, is supported.
      </P>
      <H3>Canadian provinces and territories</H3>
      <Table dense>
        <THead>
          <Tr>
            <Th>Code</Th>
            <Th>Name</Th>
            <Th>Normalised value</Th>
          </Tr>
        </THead>
        <TBody>
          {CA_REGIONS.map(([code, name, slug]) => (
            <Tr key={slug}>
              <Td mono>{code}</Td>
              <Td>{name}</Td>
              <Td mono>{slug}</Td>
            </Tr>
          ))}
        </TBody>
      </Table>
      <H3>US states (sample)</H3>
      <Table dense>
        <THead>
          <Tr>
            <Th>Code</Th>
            <Th>Normalised value</Th>
          </Tr>
        </THead>
        <TBody>
          {US_SAMPLE.map(([code, slug]) => (
            <Tr key={code}>
              <Td mono>{code}</Td>
              <Td mono>{slug}</Td>
            </Tr>
          ))}
        </TBody>
      </Table>
      <P>
        Full names are accepted for both countries (<Code>{`"Ontario"`}</Code>, <Code>{`"British Columbia"`}</Code>, <Code>{`"Québec"`}</Code>). Only the two-letter postal code is accepted for US states; full US state
        names fall through to plain slugification, which still yields the same slug for single-word states (<Code>{`"texas"`}</Code>) but not for multi-word ones.
      </P>

      <H2>Countries</H2>
      <P>
        The API accepts any two-letter code. The following {countries.length} countries are the ones surfaced in the dashboard pickers; coverage of others depends on the network and is best confirmed
        with a test request.
      </P>
      <div className="my-5 grid grid-cols-2 gap-x-6 gap-y-1 rounded-lg border border-border p-4 text-[13px] sm:grid-cols-3">
        {countries.map(([code, name]) => (
          <div key={code} className="flex items-baseline gap-2">
            <code className="font-mono text-[12px] text-fg">{code}</code>
            <span className="truncate text-fg-muted">{name}</span>
          </div>
        ))}
      </div>

      <H2>When a location is unavailable</H2>
      <Ul>
        <Li>
          <Strong>No route can serve the geography.</Strong> If none of the eligible routes supports the requested country, the request fails before any attempt: <Code>503 PROVIDER_UNAVAILABLE</Code>{" "}
          in <Code>auto</Code> mode, <Code>400 NETWORK_UNAVAILABLE</Code> with an explicit class. For sessions, creation fails with <Code>NETWORK_UNAVAILABLE</Code>.
        </Li>
        <Li>
          <Strong>Region or city has thin coverage.</Strong> Country is the level the routing engine guarantees when it selects a route. Region and city are forwarded to the network as targeting
          hints; the network serves the closest exit it has. Fetcha does not currently verify the exit location against an independent geo-IP database, so if the exact city matters to your use
          case, confirm it with a request to a geo-echo endpoint of your choice.
        </Li>
        <Li>
          <Strong>Sessions inherit geography.</Strong> When a fetch carries a <Code>session</Code> and omits <Code>country</Code>, the session&apos;s country is used. See{" "}
          <A href="/docs/sessions">Sessions</A>.
        </Li>
      </Ul>
      <Callout variant="info" title="metadata.country echoes your request">
        <Code>metadata.country</Code> reports the country that was targeted for the final attempt (yours or the session&apos;s), not a measured location. It is <Code>null</Code> when you did not ask
        for one.
      </Callout>
    </DocPage>
  );
}