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 { ParamTable } from "@/components/docs/param-table";
import { CodeTabs } from "@/components/docs/code-tabs";

export const metadata: Metadata = {
  title: "SDKs",
  description: "Official JavaScript/TypeScript and Python clients for Fetcha: installation from source, configuration, fetch/text/json helpers, sessions, usage, error classes.",
};

const JS_INSTALL = `# From a checkout of the Fetcha repository, inside your project:
pnpm add ./packages/sdk        # or: npm install ./packages/sdk

# Or simply copy the single source file into your codebase:
cp packages/sdk/src/index.ts src/lib/fetcha.ts`;

const PY_INSTALL = `# From a checkout of the Fetcha repository:
pip install ./sdk-python

# Requirements: Python >= 3.9, httpx >= 0.27 (installed automatically)`;

const JS_USAGE = `import { Fetcha, FetchaError } from "@fetcha/sdk";

const fetcha = new Fetcha({ apiKey: process.env.FETCHA_API_KEY! });

// Full control: every /v1/fetch field is available
const r = await fetcha.fetch({ url: "https://example.com/products/42", country: "CA", format: "html", retries: 2 });
console.log(r.success, r.status, r.metadata.network, r.metadata.attempts);
console.log(r.content?.slice(0, 200));

// Readable text (format: "text")
const text = await fetcha.text("https://example.com/about", { country: "CA" });

// Parsed JSON (format: "json"); the generic sets the return type
type Price = { amount: number; currency: string };
const price = await fetcha.json<Price>("https://api.example.com/v1/price?sku=42");`;

const PY_USAGE = `from fetcha import Fetcha, FetchaError

client = Fetcha(api_key=os.environ["FETCHA_API_KEY"])

# Full control: every /v1/fetch field is a keyword argument
r = client.fetch("https://example.com/products/42", country="CA", format="html", retries=2)
print(r.success, r.status, r.metadata["network"], r.metadata["attempts"])
print(r.content[:200])

# Readable text (format="text")
text = client.text("https://example.com/about", country="CA")

# Parsed JSON (format="json")
price = client.json("https://api.example.com/v1/price?sku=42")

# The client owns an httpx.Client; close it when done (or use it as a context manager)
with Fetcha(api_key=os.environ["FETCHA_API_KEY"]) as c:
    print(c.me()["project"]["name"])`;

const JS_SESSIONS = `// Create (optionally idempotent), use, inspect, list, close
const s = await fetcha.sessions.create({ country: "CA", ttl: 900, label: "user-42" }, "user-42-login");
const page = await fetcha.fetch({ url: "https://www.example.ca/account", session: s.id, cookies: { sid: "…" } });

const same = await fetcha.sessions.get(s.id);       // { id, status, network, country, expires_at, created_at, … }
const all = await fetcha.sessions.list();            // { data: Session[] }
await fetcha.sessions.close(s.id);                   // { id, status: "closed" }`;

const PY_SESSIONS = `# Create, use, inspect, list, close
s = client.sessions.create(country="CA", ttl=900, label="user-42")
page = client.fetch("https://www.example.ca/account", session=s.id, cookies={"sid": "…"})

same = client.sessions.get(s.id)        # Session dataclass; .raw has the full payload
all_sessions = client.sessions.list()   # list[Session]
client.sessions.close(s.id)             # {"id": ..., "status": "closed"}`;

const JS_ACCOUNT = `const me = await fetcha.me();
// { project: { id, name }, organization: { id, name, plan }, key: { id, name, scopes } }

const usage = await fetcha.usage.current();
// { period_start, plan, organization, project, remaining_requests }  (see Rate limits)`;

const PY_ACCOUNT = `me = client.me()
# {"project": {...}, "organization": {..., "plan": "developer"}, "key": {..., "scopes": [...]}}

usage = client.usage()
# {"period_start": ..., "plan": ..., "organization": ..., "project": ..., "remaining_requests": ...}`;

const JS_ERRORS = `try {
  await fetcha.fetch({ url: "http://169.254.169.254/latest/meta-data/" });
} catch (e) {
  if (e instanceof FetchaError) {
    e.code;      // "URL_NOT_ALLOWED"
    e.status;    // 400
    e.message;   // "Requests to local, private or internal hosts are not allowed."
    e.requestId; // "req_…" | null
  }
}`;

const PY_ERRORS = `try:
    client.fetch("http://169.254.169.254/latest/meta-data/")
except FetchaError as e:
    e.code        # "URL_NOT_ALLOWED"
    e.status      # 400
    e.message     # "Requests to local, private or internal hosts are not allowed."
    e.request_id  # "req_…" or None
    str(e)        # "URL_NOT_ALLOWED: Requests to local, private or internal hosts are not allowed."`;

export default function SdksPage() {
  return (
    <DocPage path="/docs/sdks" eyebrow="Tools" title="SDKs" description="Thin, typed clients over the REST API for JavaScript/TypeScript and Python. They add no behaviour of their own: every option maps 1:1 to a request field, and every error maps to an API error code." status="Beta">
      <Callout variant="warning" title="Not yet published to npm or PyPI">
        Both SDKs exist as source in the Fetcha repository (<Code>packages/sdk</Code> and <Code>sdk-python</Code>) and are installed from there until the packages are published. The CLI is not
        available yet. Package names are reserved: <Code>@fetcha/sdk</Code> on npm and <Code>fetcha</Code> on PyPI.
      </Callout>

      <Table>
        <THead>
          <Tr>
            <Th>SDK</Th>
            <Th>Package</Th>
            <Th>Version</Th>
            <Th>Dependencies</Th>
            <Th>Runtime</Th>
          </Tr>
        </THead>
        <TBody>
          <Tr>
            <Td className="font-medium text-fg">JavaScript / TypeScript</Td>
            <Td mono>@fetcha/sdk</Td>
            <Td mono>0.1.0</Td>
            <Td>None (uses the global <Code>fetch</Code>)</Td>
            <Td>Node 18+, Bun, Deno, edge runtimes; ESM; ships TypeScript source</Td>
          </Tr>
          <Tr>
            <Td className="font-medium text-fg">Python</Td>
            <Td mono>fetcha</Td>
            <Td mono>0.1.0</Td>
            <Td>
              <Code>httpx&gt;=0.27</Code>
            </Td>
            <Td>Python 3.9+; synchronous client</Td>
          </Tr>
        </TBody>
      </Table>
      <P>
        Requests made through the SDKs are tagged with source <Code>sdk</Code> in your request log (the SDKs send a <Code>fetcha-sdk-js/…</Code> or <Code>fetcha-sdk-python/…</Code> User-Agent
        to the Fetcha API; this does not affect the User-Agent sent to targets).
      </P>

      <H2>Installation</H2>
      <CodeTabs
        tabs={[
          { label: "JavaScript", lang: "bash", code: JS_INSTALL },
          { label: "Python", lang: "bash", code: PY_INSTALL },
        ]}
      />
      <P>
        The JavaScript package&apos;s entry point is its TypeScript source (<Code>src/index.ts</Code>), so use it from a TypeScript-aware toolchain (tsx, Bun, Deno, Vite, Next.js, esbuild) or copy the
        file into your own build. It has zero runtime dependencies.
      </P>

      <H2>Configuration</H2>
      <H3>JavaScript</H3>
      <ParamTable
        rows={[
          { name: "apiKey", type: "string", required: true, description: <>Your <code>fch_live_…</code> or <code>fch_test_…</code> key. The constructor throws if it is empty.</> },
          { name: "baseUrl", type: "string", default: '"https://www.fetcha.co"', description: <>API origin. Trailing slash is removed.</> },
          { name: "clientTimeout", type: "number (ms)", default: "150000", description: <>Client-side abort applied on top of the API&apos;s own <code>timeout</code>. Keep it above the largest <code>timeout</code> you send.</> },
          { name: "fetch", type: "typeof fetch", default: "globalThis.fetch", description: <>Custom fetch implementation (proxies, instrumentation, tests).</> },
        ]}
      />
      <H3>Python</H3>
      <ParamTable
        rows={[
          { name: "api_key", type: "str", required: true, description: <>Your API key. <code>ValueError</code> if empty.</> },
          { name: "base_url", type: "str", default: '"https://www.fetcha.co"', description: <>API origin.</> },
          { name: "timeout", type: "float (seconds)", default: "150.0", description: <>httpx timeout for the HTTP call to Fetcha.</> },
        ]}
      />

      <H2>Fetching</H2>
      <P>
        <Code>fetch</Code> takes the same fields as <A href="/docs/fetch">POST /v1/fetch</A> and returns the response document unchanged. <Code>text</Code> and <Code>json</Code> are shortcuts that set{" "}
        <Code>format</Code> and unwrap the corresponding field.
      </P>
      <CodeTabs
        tabs={[
          { label: "JavaScript", lang: "typescript", code: JS_USAGE },
          { label: "Python", lang: "python", code: PY_USAGE },
        ]}
      />
      <Ul>
        <Li>
          JavaScript: <Code>fetch(options): Promise&lt;FetchResult&gt;</Code>, <Code>text(url, options?)</Code> returns <Code>string</Code> (empty when the body was binary),{" "}
          <Code>json&lt;T&gt;(url, options?)</Code> returns <Code>T</Code> (<Code>undefined</Code> when the body did not parse).
        </Li>
        <Li>
          Python: <Code>fetch(url, **options)</Code> returns a <Code>FetchResult</Code> dataclass (<Code>request_id</Code>, <Code>success</Code>, <Code>status</Code>, <Code>url</Code>,{" "}
          <Code>final_url</Code>, <Code>content</Code>, <Code>content_type</Code>, <Code>headers</Code>, <Code>cookies</Code>, <Code>metadata</Code>, <Code>text</Code>, <Code>json</Code>, plus{" "}
          <Code>raw</Code> with the untouched payload). <Code>text()</Code> returns <Code>str</Code>, <Code>json()</Code> returns the parsed value or <Code>None</Code>.
        </Li>
        <Li>
          A fetch that reached the target never raises, even when <Code>success</Code> is <Code>false</Code>. Check it.
        </Li>
      </Ul>

      <H2>Sessions</H2>
      <CodeTabs
        tabs={[
          { label: "JavaScript", lang: "typescript", code: JS_SESSIONS },
          { label: "Python", lang: "python", code: PY_SESSIONS },
        ]}
      />
      <P>
        The JavaScript <Code>sessions.create(options, idempotencyKey?)</Code> second argument sets the <Code>Idempotency-Key</Code> header. The Python client does not expose the header yet; pass
        your own de-duplication logic or call the REST endpoint directly for idempotent creation. See <A href="/docs/sessions">Sessions</A>.
      </P>

      <H2>Account and usage</H2>
      <CodeTabs
        tabs={[
          { label: "JavaScript", lang: "typescript", code: JS_ACCOUNT },
          { label: "Python", lang: "python", code: PY_ACCOUNT },
        ]}
      />

      <H2>Errors</H2>
      <P>
        Any non-2xx response is raised as <Code>FetchaError</Code> with the API&apos;s <Code>code</Code>, the HTTP <Code>status</Code>, the <Code>message</Code> and the request id. If the response
        body is not a Fetcha envelope (for example a gateway error), <Code>code</Code> is <Code>{`"HTTP_ERROR"`}</Code>. Transport failures (DNS, connection reset, client-side timeout) surface as the
        runtime&apos;s native error, not as <Code>FetchaError</Code>.
      </P>
      <CodeTabs
        tabs={[
          { label: "JavaScript", lang: "typescript", code: JS_ERRORS },
          { label: "Python", lang: "python", code: PY_ERRORS },
        ]}
      />

      <H2>Types</H2>
      <P>The JavaScript SDK exports the following types; they mirror the API exactly.</P>
      <CodeBlock
        lang="typescript"
        code={`import type {
  FetchOptions,        // request fields of POST /v1/fetch
  FetchResult,         // response document
  FetchaNetwork,       // "auto" | "datacenter" | "residential" | "isp" | "mobile"
  FetchaFormat,        // "html" | "text" | "json" | "raw"
  SessionOptions,      // body of POST /v1/sessions
  Session,             // session object
  FetchaClientOptions, // constructor options
} from "@fetcha/sdk";`}
      />

      <H2>Other languages</H2>
      <P>
        There is no official SDK for Go, PHP, Ruby, Java or C# yet. The REST API is small enough that the raw-HTTP samples in this documentation (see the language tabs on the{" "}
        <A href="/docs/fetch">Fetch API</A> page) are a complete integration. If you publish a community client, tell us at <A href="mailto:hello@fetcha.co">hello@fetcha.co</A> and we will link it
        here.
      </P>
      <H3>CLI</H3>
      <P>
        A <Code>fetcha</Code> command-line tool is planned but <Strong>not available</Strong>. Until then, cURL with an exported <Code>FETCHA_API_KEY</Code> covers interactive use; see the{" "}
        <A href="/docs/quickstart">Quickstart</A>.
      </P>
    </DocPage>
  );
}