'use client';

import { Badge } from '@tpmjs/ui/Badge/Badge';
import { Button } from '@tpmjs/ui/Button/Button';
import { CodeBlock } from '@tpmjs/ui/CodeBlock/CodeBlock';
import Link from 'next/link';
import { useEffect, useState } from 'react';
import { AppHeader } from '~/components/AppHeader';

const NAV_SECTIONS = [
  {
    title: 'Getting Started',
    items: [
      { id: 'overview', label: 'Overview' },
      { id: 'quick-start', label: 'Quick Start' },
      { id: 'authentication', label: 'Authentication' },
    ],
  },
  {
    title: 'Public Endpoints',
    items: [
      { id: 'tools', label: 'Tools' },
      { id: 'search', label: 'Search' },
      { id: 'collections', label: 'Collections' },
      { id: 'agents', label: 'Agents' },
      { id: 'stats', label: 'Stats' },
    ],
  },
  {
    title: 'MCP Protocol',
    items: [
      { id: 'mcp-overview', label: 'Overview' },
      { id: 'mcp-initialize', label: 'Initialize' },
      { id: 'mcp-tools-list', label: 'Tools List' },
      { id: 'mcp-tools-call', label: 'Tools Call' },
    ],
  },
  {
    title: 'Execution',
    items: [
      { id: 'execute-tool', label: 'Execute Tool' },
      { id: 'streaming', label: 'Streaming' },
    ],
  },
  {
    title: 'Response Format',
    items: [
      { id: 'success', label: 'Success Response' },
      { id: 'errors', label: 'Error Handling' },
      { id: 'pagination', label: 'Pagination' },
    ],
  },
];

function SidebarNav({
  activeSection,
  onSectionClick,
}: {
  activeSection: string;
  onSectionClick: (id: string) => void;
}) {
  return (
    <nav className="space-y-6">
      {NAV_SECTIONS.map((section) => (
        <div key={section.title}>
          <h3 className="text-xs font-semibold uppercase tracking-wider text-foreground-tertiary mb-2">
            {section.title}
          </h3>
          <ul className="space-y-1">
            {section.items.map((item) => (
              <li key={item.id}>
                <button
                  type="button"
                  onClick={() => onSectionClick(item.id)}
                  className={`block w-full text-left px-3 py-1.5 text-sm rounded-md transition-colors ${
                    activeSection === item.id
                      ? 'bg-primary/10 text-primary font-medium'
                      : 'text-foreground-secondary hover:text-foreground hover:bg-surface-elevated'
                  }`}
                >
                  {item.label}
                </button>
              </li>
            ))}
          </ul>
        </div>
      ))}
    </nav>
  );
}

function DocSection({
  id,
  title,
  children,
}: {
  id: string;
  title: string;
  children: React.ReactNode;
}) {
  return (
    <section id={id} className="scroll-mt-24 mb-16">
      <h2 className="text-2xl font-bold mb-6 text-foreground pb-3 border-b border-border">
        {title}
      </h2>
      {children}
    </section>
  );
}

function EndpointCard({
  method,
  path,
  description,
  children,
}: {
  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
  path: string;
  description: string;
  children?: React.ReactNode;
}) {
  const methodColors = {
    GET: 'bg-success/10 text-success border-success/30',
    POST: 'bg-info/10 text-info border-info/30',
    PUT: 'bg-warning/10 text-warning border-warning/30',
    DELETE: 'bg-error/10 text-error border-error/30',
  };

  return (
    <div className="border border-border rounded-lg overflow-hidden mb-6">
      <div className="bg-surface p-4 border-b border-border">
        <div className="flex items-center gap-3 mb-2">
          <span
            className={`px-2 py-1 text-xs font-mono font-bold rounded border ${methodColors[method]}`}
          >
            {method}
          </span>
          <code className="text-sm font-mono text-foreground">{path}</code>
        </div>
        <p className="text-sm text-foreground-secondary">{description}</p>
      </div>
      {children && <div className="p-4 bg-background">{children}</div>}
    </div>
  );
}

function ParamTable({
  params,
}: {
  params: { name: string; type: string; required: boolean; description: string }[];
}) {
  return (
    <div className="overflow-x-auto border border-border rounded-lg">
      <table className="w-full text-sm">
        <thead>
          <tr className="border-b border-border bg-surface">
            <th className="text-left py-3 px-4 text-foreground font-medium">Parameter</th>
            <th className="text-left py-3 px-4 text-foreground font-medium">Type</th>
            <th className="text-left py-3 px-4 text-foreground font-medium">Required</th>
            <th className="text-left py-3 px-4 text-foreground font-medium">Description</th>
          </tr>
        </thead>
        <tbody>
          {params.map((param, i) => (
            <tr
              key={param.name}
              className={i !== params.length - 1 ? 'border-b border-border' : ''}
            >
              <td className="py-3 px-4 font-mono text-primary">{param.name}</td>
              <td className="py-3 px-4 font-mono text-foreground-secondary">{param.type}</td>
              <td className="py-3 px-4">
                {param.required ? (
                  <Badge variant="default" size="sm">
                    Yes
                  </Badge>
                ) : (
                  <span className="text-foreground-tertiary">No</span>
                )}
              </td>
              <td className="py-3 px-4 text-foreground-secondary">{param.description}</td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}

export default function APIDocsPage(): React.ReactElement {
  const [activeSection, setActiveSection] = useState('overview');
  const [mobileNavOpen, setMobileNavOpen] = useState(false);

  useEffect(() => {
    const observer = new IntersectionObserver(
      (entries) => {
        entries.forEach((entry) => {
          if (entry.isIntersecting) {
            setActiveSection(entry.target.id);
          }
        });
      },
      { rootMargin: '-100px 0px -66%' }
    );

    NAV_SECTIONS.forEach((section) => {
      section.items.forEach((item) => {
        const element = document.getElementById(item.id);
        if (element) observer.observe(element);
      });
    });

    return () => observer.disconnect();
  }, []);

  const scrollToSection = (id: string) => {
    const element = document.getElementById(id);
    if (element) {
      element.scrollIntoView({ behavior: 'smooth' });
      setMobileNavOpen(false);
    }
  };

  return (
    <div className="min-h-screen flex flex-col bg-background">
      <AppHeader />

      <div className="flex-1 flex flex-col lg:flex-row">
        {/* Mobile Navigation Toggle */}
        <div className="lg:hidden sticky top-0 z-30 bg-background border-b border-border px-4 py-3">
          <button
            type="button"
            onClick={() => setMobileNavOpen(!mobileNavOpen)}
            className="flex items-center gap-2 text-sm font-medium text-foreground"
          >
            <span className="text-lg">{mobileNavOpen ? '✕' : '☰'}</span>
            <span>API Documentation</span>
          </button>
          {mobileNavOpen && (
            <div className="absolute left-0 right-0 top-full bg-background border-b border-border shadow-lg max-h-[70vh] overflow-y-auto px-4 py-4">
              <SidebarNav activeSection={activeSection} onSectionClick={scrollToSection} />
            </div>
          )}
        </div>

        {/* Desktop Sidebar */}
        <aside className="hidden lg:block w-64 flex-shrink-0 border-r border-border bg-surface/50">
          <div className="sticky top-0 h-screen overflow-y-auto py-8 px-4">
            <div className="mb-6">
              <Link
                href="/docs"
                className="text-foreground-secondary hover:text-foreground text-sm"
              >
                ← Back to Docs
              </Link>
              <h2 className="text-lg font-bold text-foreground mt-4">API Reference</h2>
              <p className="text-sm text-foreground-tertiary">REST & MCP</p>
            </div>
            <SidebarNav activeSection={activeSection} onSectionClick={scrollToSection} />
          </div>
        </aside>

        {/* Main Content */}
        <main className="flex-1 min-w-0">
          <div className="max-w-4xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
            {/* Hero */}
            <div className="mb-12">
              <div className="flex items-center gap-2 mb-4">
                <Badge variant="secondary">API</Badge>
                <Badge variant="outline">v1.0</Badge>
              </div>
              <h1 className="text-3xl md:text-4xl font-bold mb-4 text-foreground">
                TPMJS API Reference
              </h1>
              <p className="text-xl text-foreground-secondary mb-6">
                REST API and MCP protocol for accessing tools, collections, and agents.
              </p>
              <div className="p-4 border border-border rounded-lg bg-surface">
                <p className="text-sm text-foreground-secondary">
                  <strong className="text-foreground">Base URL:</strong>{' '}
                  <code className="text-primary">https://tpmjs.com/api</code>
                </p>
              </div>
            </div>

            {/* ==================== GETTING STARTED ==================== */}
            <DocSection id="overview" title="Overview">
              <p className="text-foreground-secondary mb-6">
                The TPMJS API provides programmatic access to the tool registry, collections, and
                agents. There are two ways to interact with the API:
              </p>
              <div className="grid grid-cols-1 md:grid-cols-2 gap-4 mb-6">
                <div className="p-5 border border-border rounded-lg bg-surface">
                  <h3 className="font-semibold text-foreground mb-2">REST API</h3>
                  <p className="text-sm text-foreground-secondary">
                    Standard REST endpoints for listing tools, searching, and executing. No
                    authentication required for public endpoints.
                  </p>
                </div>
                <div className="p-5 border border-border rounded-lg bg-surface">
                  <h3 className="font-semibold text-foreground mb-2">MCP Protocol</h3>
                  <p className="text-sm text-foreground-secondary">
                    JSON-RPC 2.0 over HTTP for AI clients like Claude Desktop, Cursor, and others
                    that support Model Context Protocol.
                  </p>
                </div>
              </div>
            </DocSection>

            <DocSection id="quick-start" title="Quick Start">
              <p className="text-foreground-secondary mb-6">
                Try these examples to get started. All API endpoints require authentication via API
                key. Generate one from <strong>Settings → TPMJS API Keys</strong> in your dashboard.
              </p>

              <div className="space-y-6">
                <div>
                  <h3 className="text-lg font-semibold text-foreground mb-3">1. List Tools</h3>
                  <CodeBlock
                    language="bash"
                    code={`curl "https://tpmjs.com/api/tools?limit=5" \\
  -H "Authorization: Bearer tpmjs_sk_your_api_key_here" | jq`}
                  />
                </div>

                <div>
                  <h3 className="text-lg font-semibold text-foreground mb-3">2. Search Tools</h3>
                  <CodeBlock
                    language="bash"
                    code={`curl "https://tpmjs.com/api/tools/search?q=web+scraping&limit=3" \\
  -H "Authorization: Bearer tpmjs_sk_your_api_key_here" | jq`}
                  />
                </div>

                <div>
                  <h3 className="text-lg font-semibold text-foreground mb-3">
                    3. Get Tool Details
                  </h3>
                  <CodeBlock
                    language="bash"
                    code={`curl "https://tpmjs.com/api/tools/@tpmjs/hello/helloWorldTool" \\
  -H "Authorization: Bearer tpmjs_sk_your_api_key_here" | jq`}
                  />
                </div>

                <div>
                  <h3 className="text-lg font-semibold text-foreground mb-3">
                    4. MCP Tools List (Collection)
                  </h3>
                  <CodeBlock
                    language="bash"
                    code={`curl -X POST "https://tpmjs.com/api/mcp/ajax/ajax-collection-tbc/http" \\
  -H "Authorization: Bearer tpmjs_sk_your_api_key_here" \\
  -H "Content-Type: application/json" \\
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' | jq`}
                  />
                </div>
              </div>
            </DocSection>

            <DocSection id="authentication" title="Authentication">
              <p className="text-foreground-secondary mb-6">
                All API endpoints require authentication via TPMJS API keys. Generate an API key
                from your dashboard at <strong>Settings → TPMJS API Keys</strong>.
              </p>

              <div className="space-y-4 mb-6">
                <div className="p-4 border border-primary/30 rounded-lg bg-primary/5">
                  <h3 className="font-semibold text-foreground mb-2">API Key Format</h3>
                  <p className="text-sm text-foreground-secondary mb-2">
                    API keys use the <code className="text-primary">tpmjs_sk_</code> prefix and are
                    passed in the Authorization header:
                  </p>
                  <CodeBlock
                    language="bash"
                    code={`curl "https://tpmjs.com/api/tools" \\
  -H "Authorization: Bearer tpmjs_sk_your_api_key_here"`}
                  />
                </div>

                <div className="p-4 border border-warning/30 rounded-lg bg-warning/5">
                  <h3 className="font-semibold text-foreground mb-2">API Key Scopes</h3>
                  <ul className="text-sm text-foreground-secondary list-disc list-inside space-y-1">
                    <li>
                      <code className="text-primary">mcp:execute</code> - MCP tool execution
                    </li>
                    <li>
                      <code className="text-primary">agent:chat</code> - Agent conversations
                    </li>
                    <li>
                      <code className="text-primary">bridge:connect</code> - Bridge connections
                    </li>
                    <li>
                      <code className="text-primary">collection:read</code> - Collection access
                    </li>
                    <li>
                      <code className="text-primary">usage:read</code> - Usage analytics
                    </li>
                  </ul>
                </div>

                <div className="p-4 border border-success/30 rounded-lg bg-success/5">
                  <h3 className="font-semibold text-foreground mb-2">Rate Limits</h3>
                  <ul className="text-sm text-foreground-secondary list-disc list-inside space-y-1">
                    <li>FREE tier: 100 requests/hour</li>
                    <li>PRO tier: 1,000 requests/hour</li>
                    <li>ENTERPRISE tier: 10,000 requests/hour</li>
                  </ul>
                </div>
              </div>
            </DocSection>

            {/* ==================== PUBLIC ENDPOINTS ==================== */}
            <DocSection id="tools" title="Tools">
              <EndpointCard
                method="GET"
                path="/api/tools"
                description="List all tools with optional filtering and pagination."
              >
                <ParamTable
                  params={[
                    { name: 'q', type: 'string', required: false, description: 'Search query' },
                    {
                      name: 'category',
                      type: 'string',
                      required: false,
                      description: 'Filter by category',
                    },
                    {
                      name: 'official',
                      type: 'boolean',
                      required: false,
                      description: 'Official tools only',
                    },
                    {
                      name: 'limit',
                      type: 'number',
                      required: false,
                      description: 'Results per page (default: 20, max: 50)',
                    },
                    {
                      name: 'offset',
                      type: 'number',
                      required: false,
                      description: 'Pagination offset',
                    },
                  ]}
                />
                <div className="mt-4">
                  <CodeBlock
                    language="bash"
                    code='curl "https://tpmjs.com/api/tools?category=web-scraping&limit=10"'
                  />
                </div>
              </EndpointCard>

              <EndpointCard
                method="GET"
                path="/api/tools/[package]/[toolName]"
                description="Get detailed information about a specific tool."
              >
                <CodeBlock
                  language="bash"
                  code='curl "https://tpmjs.com/api/tools/@tpmjs/hello/helloWorldTool"'
                />
                <div className="mt-4">
                  <h4 className="text-sm font-semibold text-foreground mb-2">Response</h4>
                  <CodeBlock
                    language="json"
                    code={`{
  "success": true,
  "data": {
    "id": "clx...",
    "name": "helloWorldTool",
    "description": "Returns a simple greeting",
    "package": {
      "npmPackageName": "@tpmjs/hello",
      "npmVersion": "1.0.0"
    },
    "inputSchema": {
      "type": "object",
      "properties": {}
    },
    "healthStatus": "HEALTHY",
    "qualityScore": 0.85
  }
}`}
                  />
                </div>
              </EndpointCard>
            </DocSection>

            <DocSection id="search" title="Search">
              <EndpointCard
                method="GET"
                path="/api/tools/search"
                description="BM25-ranked semantic search optimized for AI tool discovery."
              >
                <ParamTable
                  params={[
                    { name: 'q', type: 'string', required: true, description: 'Search query' },
                    {
                      name: 'limit',
                      type: 'number',
                      required: false,
                      description: 'Max results (default: 5, max: 20)',
                    },
                  ]}
                />
                <div className="mt-4">
                  <CodeBlock
                    language="bash"
                    code='curl "https://tpmjs.com/api/tools/search?q=convert+pdf+to+markdown&limit=5"'
                  />
                </div>
              </EndpointCard>
            </DocSection>

            <DocSection id="collections" title="Collections">
              <EndpointCard
                method="GET"
                path="/api/public/collections"
                description="List all public collections with tools and creator info."
              >
                <CodeBlock language="bash" code='curl "https://tpmjs.com/api/public/collections"' />
              </EndpointCard>

              <EndpointCard
                method="GET"
                path="/api/public/collections/[id]"
                description="Get a specific public collection with its tools."
              >
                <CodeBlock
                  language="bash"
                  code='curl "https://tpmjs.com/api/public/collections/clx123..."'
                />
              </EndpointCard>

              <EndpointCard
                method="GET"
                path="/api/public/users/[username]/collections/[slug]"
                description="Get a collection by username and slug (human-readable URL)."
              >
                <CodeBlock
                  language="bash"
                  code='curl "https://tpmjs.com/api/public/users/ajax/collections/web-tools"'
                />
              </EndpointCard>
            </DocSection>

            <DocSection id="agents" title="Agents">
              <EndpointCard
                method="GET"
                path="/api/public/agents"
                description="List all public agents with their configurations."
              >
                <CodeBlock language="bash" code='curl "https://tpmjs.com/api/public/agents"' />
              </EndpointCard>

              <EndpointCard
                method="GET"
                path="/api/public/users/[username]/agents/[uid]"
                description="Get an agent by username and unique identifier."
              >
                <CodeBlock
                  language="bash"
                  code='curl "https://tpmjs.com/api/public/users/lisa/agents/alpha"'
                />
              </EndpointCard>
            </DocSection>

            <DocSection id="stats" title="Stats">
              <EndpointCard
                method="GET"
                path="/api/stats"
                description="Get platform-wide statistics including tool counts and categories."
              >
                <CodeBlock language="bash" code='curl "https://tpmjs.com/api/stats"' />
                <div className="mt-4">
                  <h4 className="text-sm font-semibold text-foreground mb-2">Response</h4>
                  <CodeBlock
                    language="json"
                    code={`{
  "success": true,
  "data": {
    "totalTools": 150,
    "totalPackages": 45,
    "totalExecutions": 12500,
    "categories": {
      "web-scraping": 25,
      "text-analysis": 18,
      "code-generation": 15
    }
  }
}`}
                  />
                </div>
              </EndpointCard>
            </DocSection>

            {/* ==================== MCP PROTOCOL ==================== */}
            <DocSection id="mcp-overview" title="MCP Overview">
              <p className="text-foreground-secondary mb-6">
                TPMJS implements the Model Context Protocol (MCP) for AI clients. Each public
                collection exposes an MCP endpoint that can be connected to Claude Desktop, Cursor,
                or any MCP-compatible client.
              </p>

              <div className="p-4 border border-border rounded-lg bg-surface mb-6">
                <h3 className="font-semibold text-foreground mb-2">Endpoint Format</h3>
                <code className="text-primary">
                  POST https://tpmjs.com/api/mcp/[username]/[collection-slug]/http
                </code>
              </div>

              <div className="space-y-4">
                <div className="p-4 border border-border rounded-lg bg-surface">
                  <h4 className="font-semibold text-foreground mb-2">Request Headers</h4>
                  <code className="text-sm text-foreground-secondary block">
                    Authorization: Bearer tpmjs_sk_your_api_key_here
                  </code>
                  <code className="text-sm text-foreground-secondary block mt-1">
                    Content-Type: application/json
                  </code>
                </div>
                <div className="p-4 border border-border rounded-lg bg-surface">
                  <h4 className="font-semibold text-foreground mb-2">Protocol</h4>
                  <p className="text-sm text-foreground-secondary">
                    JSON-RPC 2.0 with MCP methods: <code className="text-primary">initialize</code>,{' '}
                    <code className="text-primary">tools/list</code>,{' '}
                    <code className="text-primary">tools/call</code>
                  </p>
                </div>
              </div>
            </DocSection>

            <DocSection id="mcp-initialize" title="MCP Initialize">
              <EndpointCard
                method="POST"
                path="/api/mcp/[username]/[slug]/http"
                description="Initialize an MCP session and get server capabilities."
              >
                <h4 className="text-sm font-semibold text-foreground mb-2">Request</h4>
                <CodeBlock
                  language="json"
                  code={`{
  "jsonrpc": "2.0",
  "method": "initialize",
  "id": 1
}`}
                />
                <h4 className="text-sm font-semibold text-foreground mb-2 mt-4">Response</h4>
                <CodeBlock
                  language="json"
                  code={`{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": {
      "name": "TPMJS: My Collection",
      "version": "1.0.0"
    },
    "capabilities": {
      "tools": {}
    }
  }
}`}
                />
              </EndpointCard>
            </DocSection>

            <DocSection id="mcp-tools-list" title="MCP Tools List">
              <EndpointCard
                method="POST"
                path="/api/mcp/[username]/[slug]/http"
                description="List all tools available in the collection with their schemas."
              >
                <h4 className="text-sm font-semibold text-foreground mb-2">Request</h4>
                <CodeBlock
                  language="json"
                  code={`{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 2
}`}
                />
                <h4 className="text-sm font-semibold text-foreground mb-2 mt-4">Response</h4>
                <CodeBlock
                  language="json"
                  code={`{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "tpmjs-tools-toc-generate--tocGenerateTool",
        "description": "Generate a table of contents from markdown",
        "inputSchema": {
          "type": "object",
          "required": ["markdown"],
          "properties": {
            "markdown": { "type": "string" }
          }
        }
      }
    ]
  }
}`}
                />
              </EndpointCard>
            </DocSection>

            <DocSection id="mcp-tools-call" title="MCP Tools Call">
              <EndpointCard
                method="POST"
                path="/api/mcp/[username]/[slug]/http"
                description="Execute a tool from the collection with the provided arguments."
              >
                <h4 className="text-sm font-semibold text-foreground mb-2">Request</h4>
                <CodeBlock
                  language="json"
                  code={`{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "tpmjs-tools-toc-generate--tocGenerateTool",
    "arguments": {
      "markdown": "# Heading 1\\n## Heading 2\\n### Heading 3"
    }
  },
  "id": 3
}`}
                />
                <h4 className="text-sm font-semibold text-foreground mb-2 mt-4">Response</h4>
                <CodeBlock
                  language="json"
                  code={`{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\\"toc\\": \\"- [Heading 1](#heading-1)\\\\n  - [Heading 2](#heading-2)\\"}"
      }
    ]
  }
}`}
                />
              </EndpointCard>

              <div className="mt-6">
                <h3 className="text-lg font-semibold text-foreground mb-4">Full cURL Example</h3>
                <CodeBlock
                  language="bash"
                  code={`curl -X POST "https://tpmjs.com/api/mcp/ajax/ajax-collection-tbc/http" \\
  -H "Authorization: Bearer tpmjs_sk_your_api_key_here" \\
  -H "Content-Type: application/json" \\
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "tpmjs-tools-changelog-entry--changelogEntryTool",
      "arguments": {
        "version": "1.0.0",
        "changes": [
          {"type": "Added", "description": "New feature"}
        ]
      }
    },
    "id": 1
  }'`}
                />
              </div>
            </DocSection>

            {/* ==================== EXECUTION ==================== */}
            <DocSection id="execute-tool" title="Execute Tool">
              <EndpointCard
                method="POST"
                path="/api/tools/execute/[package]/[toolName]"
                description="Execute a tool with an AI agent and stream the response."
              >
                <ParamTable
                  params={[
                    {
                      name: 'prompt',
                      type: 'string',
                      required: true,
                      description: 'Natural language prompt (max 2000 chars)',
                    },
                    {
                      name: 'parameters',
                      type: 'object',
                      required: false,
                      description: 'Direct tool parameters',
                    },
                  ]}
                />
                <div className="mt-4">
                  <CodeBlock
                    language="bash"
                    code={`curl -X POST "https://tpmjs.com/api/tools/execute/@tpmjs/hello/helloWorldTool" \\
  -H "Content-Type: application/json" \\
  -d '{"prompt": "Say hello to the world"}'`}
                  />
                </div>
              </EndpointCard>
            </DocSection>

            <DocSection id="streaming" title="Streaming Responses">
              <p className="text-foreground-secondary mb-6">
                The execute endpoint returns Server-Sent Events (SSE) for real-time streaming.
              </p>

              <div className="space-y-4 mb-6">
                <div className="p-4 border border-border rounded-lg bg-surface">
                  <code className="text-primary font-mono">event: chunk</code>
                  <p className="text-sm text-foreground-secondary mt-1">
                    Streaming text from the AI agent
                  </p>
                </div>
                <div className="p-4 border border-border rounded-lg bg-surface">
                  <code className="text-primary font-mono">event: tokens</code>
                  <p className="text-sm text-foreground-secondary mt-1">Token usage updates</p>
                </div>
                <div className="p-4 border border-border rounded-lg bg-surface">
                  <code className="text-primary font-mono">event: complete</code>
                  <p className="text-sm text-foreground-secondary mt-1">
                    Final result with output and timing
                  </p>
                </div>
                <div className="p-4 border border-border rounded-lg bg-surface">
                  <code className="text-primary font-mono">event: error</code>
                  <p className="text-sm text-foreground-secondary mt-1">Error if execution fails</p>
                </div>
              </div>

              <h3 className="text-lg font-semibold text-foreground mb-4">JavaScript Example</h3>
              <CodeBlock
                language="typescript"
                code={`const response = await fetch(
  'https://tpmjs.com/api/tools/execute/@tpmjs/hello/helloWorldTool',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer tpmjs_sk_your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ prompt: 'Say hello' }),
  }
);

const reader = response.body?.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  for (const line of chunk.split('\\n')) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      console.log(data);
    }
  }
}`}
              />
            </DocSection>

            {/* ==================== RESPONSE FORMAT ==================== */}
            <DocSection id="success" title="Success Response">
              <p className="text-foreground-secondary mb-6">
                All API endpoints return a consistent JSON response format.
              </p>
              <CodeBlock
                language="json"
                code={`{
  "success": true,
  "data": { ... },
  "pagination": {
    "limit": 20,
    "offset": 0,
    "hasMore": true
  },
  "meta": {
    "version": "1.0.0",
    "timestamp": "2026-01-10T12:00:00.000Z",
    "requestId": "abc123..."
  }
}`}
              />
            </DocSection>

            <DocSection id="errors" title="Error Handling">
              <p className="text-foreground-secondary mb-6">
                Errors include a code and message for debugging.
              </p>
              <CodeBlock
                language="json"
                code={`{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Tool not found"
  },
  "meta": {
    "version": "1.0.0",
    "timestamp": "2026-01-10T12:00:00.000Z"
  }
}`}
              />
              <div className="mt-6">
                <h3 className="text-lg font-semibold text-foreground mb-4">HTTP Status Codes</h3>
                <div className="space-y-2">
                  <div className="flex items-center gap-3">
                    <Badge variant="success">200</Badge>
                    <span className="text-foreground-secondary">Success</span>
                  </div>
                  <div className="flex items-center gap-3">
                    <Badge variant="warning">400</Badge>
                    <span className="text-foreground-secondary">
                      Bad request / validation error
                    </span>
                  </div>
                  <div className="flex items-center gap-3">
                    <Badge variant="warning">401</Badge>
                    <span className="text-foreground-secondary">Authentication required</span>
                  </div>
                  <div className="flex items-center gap-3">
                    <Badge variant="error">404</Badge>
                    <span className="text-foreground-secondary">Resource not found</span>
                  </div>
                  <div className="flex items-center gap-3">
                    <Badge variant="error">429</Badge>
                    <span className="text-foreground-secondary">Rate limit exceeded</span>
                  </div>
                  <div className="flex items-center gap-3">
                    <Badge variant="error">500</Badge>
                    <span className="text-foreground-secondary">Internal server error</span>
                  </div>
                </div>
              </div>
            </DocSection>

            <DocSection id="pagination" title="Pagination">
              <p className="text-foreground-secondary mb-6">
                List endpoints support limit/offset pagination.
              </p>
              <ParamTable
                params={[
                  {
                    name: 'limit',
                    type: 'number',
                    required: false,
                    description: 'Items per page (default varies by endpoint)',
                  },
                  {
                    name: 'offset',
                    type: 'number',
                    required: false,
                    description: 'Number of items to skip',
                  },
                ]}
              />
              <div className="mt-4">
                <CodeBlock
                  language="bash"
                  code={`# Page 1: First 20 items
curl "https://tpmjs.com/api/tools?limit=20&offset=0"

# Page 2: Next 20 items
curl "https://tpmjs.com/api/tools?limit=20&offset=20"`}
                />
              </div>
            </DocSection>

            {/* CTA */}
            <section className="text-center py-12 border border-border rounded-lg bg-surface mt-12">
              <h2 className="text-2xl font-bold mb-4 text-foreground">Need More Help?</h2>
              <p className="text-foreground-secondary mb-6 max-w-xl mx-auto">
                Check out the full documentation or try the interactive playground.
              </p>
              <div className="flex flex-wrap gap-4 justify-center">
                <Link href="/docs">
                  <Button variant="default">Full Documentation</Button>
                </Link>
                <a href="https://playground.tpmjs.com" target="_blank" rel="noopener noreferrer">
                  <Button variant="outline">Try Playground</Button>
                </a>
                <a href="https://github.com/tpmjs/tpmjs" target="_blank" rel="noopener noreferrer">
                  <Button variant="outline">GitHub</Button>
                </a>
              </div>
            </section>
          </div>
        </main>
      </div>
    </div>
  );
}