import type { Metadata } from "next";
import { CodeBlock } from "@/components/ui/code-block";
import { DocPage } from "@/components/docs/doc-page";
import { A, Code, H2, Li, P, Strong, Table, TBody, Td, Th, THead, Tr, Ul } from "@/components/docs/prose";
import { Callout, ComingSoon } from "@/components/docs/callout";
import { CodeTabs } from "@/components/docs/code-tabs";

export const metadata: Metadata = {
  title: "Webhooks",
  description: "Webhooks are coming soon. Planned events (usage thresholds, failed requests, billing, API keys), delivery format and the HMAC-SHA256 signature scheme.",
};

const EVENTS: Array<[string, string]> = [
  ["usage.threshold", "Monthly requests or spend crossed a threshold you configure (for example 80 % and 100 % of the plan quota, or a soft spending limit)."],
  ["request.failed", "A fetch ended in an error or a fully blocked target. Batched to avoid floods; includes request_id, domain, error code and attempts."],
  ["billing.invoice.created", "An invoice was issued for the organization."],
  ["billing.payment.succeeded", "A payment was collected."],
  ["billing.payment.failed", "A payment attempt failed; includes the retry schedule."],
  ["billing.plan.changed", "The organization's plan changed."],
  ["api_key.created", "A key was created in one of your projects."],
  ["api_key.rotated", "A key's secret was rotated."],
  ["api_key.revoked", "A key was revoked."],
  ["api_key.expiring", "A key expires within 7 days."],
];

const PAYLOAD = {
  id: "evt_7h8i9j0k1l2m3n4o",
  type: "usage.threshold",
  created_at: "2026-09-07T15:04:00.000Z",
  organization_id: "org_9a1b2c3d4e5f6g7h",
  project_id: "proj_2k8d1m3p9q4r7s6t",
  data: {
    metric: "requests",
    threshold: 0.8,
    used: 40_012,
    limit: 50_000,
    period_start: "2026-09-01T00:00:00.000Z",
  },
};

const VERIFY_JS = `import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyFetchaSignature(rawBody: string, header: string, secret: string, toleranceSec = 300) {
  // Header format: t=<unix seconds>,v1=<hex hmac>
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=") as [string, string]));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(\`\${t}.\${rawBody}\`).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1 ?? "", "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}`;

const VERIFY_PY = `import hmac, hashlib, time

def verify_fetcha_signature(raw_body: bytes, header: str, secret: str, tolerance_sec: int = 300) -> bool:
    # Header format: t=<unix seconds>,v1=<hex hmac>
    parts = dict(kv.split("=", 1) for kv in header.split(","))
    t = int(parts.get("t", "0"))
    if not t or abs(time.time() - t) > tolerance_sec:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))`;

export default function WebhooksPage() {
  return (
    <DocPage path="/docs/webhooks" eyebrow="Reliability" title="Webhooks" description="Receive HTTP notifications when something happens in your account: usage thresholds, failed requests, billing and API key events." status="Coming soon">
      <ComingSoon title="Coming soon — configuration UI not yet available">
        Webhook delivery is not live. There is no way to register an endpoint yet, no events are sent, and the details on this page are the planned design published for early integration work.
        The event names, payload shape and signature scheme may change before launch. Watch the <A href="/changelog">changelog</A>.
      </ComingSoon>

      <H2>Planned events</H2>
      <Table>
        <THead>
          <Tr>
            <Th>Event</Th>
            <Th>When it fires</Th>
          </Tr>
        </THead>
        <TBody>
          {EVENTS.map(([name, desc]) => (
            <Tr key={name}>
              <Td mono className="whitespace-nowrap">
                {name}
              </Td>
              <Td>{desc}</Td>
            </Tr>
          ))}
        </TBody>
      </Table>

      <H2>Delivery</H2>
      <Ul>
        <Li>
          Events will be delivered as <Code>POST</Code> requests with a JSON body to the HTTPS URL you register per organization, with the event types you subscribe to.
        </Li>
        <Li>
          Your endpoint should respond with a 2xx within 10 seconds. Non-2xx responses and timeouts are retried with exponential backoff for up to 24 hours, then recorded as failed in the
          dashboard.
        </Li>
        <Li>
          Deliveries are <Strong>at least once</Strong>: use <Code>id</Code> to deduplicate.
        </Li>
        <Li>
          Payloads never include page content, cookies or API key secrets, only identifiers and metrics.
        </Li>
      </Ul>
      <CodeBlock lang="json" title="Planned payload" code={JSON.stringify(PAYLOAD, null, 2)} />

      <H2>Signature</H2>
      <P>
        Each delivery will carry an <Code>X-Fetcha-Signature</Code> header so you can verify that the payload came from Fetcha and was not altered. The scheme is HMAC-SHA256 over a timestamp and the
        raw request body, keyed with the endpoint&apos;s secret shown once at creation:
      </P>
      <CodeBlock
        lang="text"
        code={`X-Fetcha-Signature: t=1788623040,v1=5f1c9c0a5b4e7d2b8a3f6e9d0c1b2a3f4e5d6c7b8a9f0e1d2c3b4a5f6e7d8c9b
X-Fetcha-Event: usage.threshold
X-Fetcha-Delivery: whd_1a2b3c4d5e6f7g8h

signed_payload = "<t>" + "." + <raw body>
v1 = hex( HMAC_SHA256( secret, signed_payload ) )`}
      />
      <Ul>
        <Li>
          Compute the HMAC over the <Strong>raw</Strong> bytes you received, before any JSON parsing or re-serialisation.
        </Li>
        <Li>Reject deliveries whose timestamp is more than five minutes old to prevent replay.</Li>
        <Li>Compare signatures with a constant-time function.</Li>
        <Li>
          During secret rotation both the old and the new secret will be valid for 24 hours; the header may then contain two <Code>v1</Code> values.
        </Li>
      </Ul>
      <CodeTabs
        tabs={[
          { label: "JavaScript", lang: "typescript", code: VERIFY_JS },
          { label: "Python", lang: "python", code: VERIFY_PY },
        ]}
      />

      <Callout variant="info" title="What you can do today">
        Poll <Code>GET /v1/usage</Code> for <Code>remaining_requests</Code> and spend, and watch the request log in the dashboard. Hard spending limits and project request limits already stop
        traffic when reached (see <A href="/docs/rate-limits">Rate limits</A>), which covers the most important protection webhooks would otherwise provide.
      </Callout>
    </DocPage>
  );
}