@inferencesh/ui 0.0.0-stage → 0.1.1

package/src/docs/api-docs.tsx

@@ -0,0 +1,763 @@
+'use client'
+
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { CodeBlock } from "../components/code-block"
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "../components/select"
+import { Separator } from "../shadcn/separator"
+import { TableOfContents, TocItem } from "./table-of-contents"
+import { TaskStatusCancelled, TaskStatusCompleted, TaskStatusFailed, TaskStatusRejected } from '@inferencesh/sdk'
+import { apiKeySetup, generateBackgroundExamples, generateFileExamples, generateResultOnlyExamples, generateStreamingExamples, generateSwiftWebhookExample, installCommands } from '../examples'
+import { exampleInput } from '../lib/example-input'
+import { getFieldsFromSchema, SchemaField, Schema } from '../lib/schema'
+import { cn } from 'cn'
+import { localStore } from '../lib/storage'
+import { Hash } from 'lucide-react'
+
+// Types
+export interface ApiDocsApp {
+  /** The slug that addresses the app. Stays in refs, URLs and code samples. */
+  name: string
+  /** The name a person reads, when the app has one. Headings and prose only. */
+  title?: string
+  namespace?: string
+  description?: string
+}
+
+export interface ApiDocsVersion {
+  short_id?: string
+  input_schema?: Schema
+  output_schema?: Schema
+  setup_schema?: Schema
+  functions?: Record<string, { name?: string; description?: string; input_schema?: Schema; output_schema?: Schema }>
+  default_function?: string
+}
+
+export interface ApiDocsFormData {
+  input?: Record<string, unknown>
+  setup?: Record<string, unknown>
+  infra?: string
+  workers?: string[]
+}
+
+export interface ApiDocsProps {
+  /** App metadata */
+  app: ApiDocsApp
+  /** Version containing schemas and functions */
+  version: ApiDocsVersion
+  /** Active function name (falls back to version.default_function → "run") */
+  functionName?: string | null
+  /** Current form data for generating examples */
+  formData?: ApiDocsFormData
+  /** Optional className */
+  className?: string
+  /** Link component for routing (defaults to <a>) */
+  LinkComponent?: React.ComponentType<{ to: string; className?: string; children: React.ReactNode }>
+  /** Base path for docs links (defaults to /docs) */
+  docsBasePath?: string
+  /** Base path for settings links (defaults to /settings) */
+  settingsBasePath?: string
+  /** Controlled language (if provided, component is controlled) */
+  language?: Language
+  /** Callback when language changes */
+  onLanguageChange?: (language: Language) => void
+}
+
+export type Language = 'python' | 'typescript' | 'javascript' | 'swift' | 'curl' | 'belt'
+
+/** The language a page shows first: plain HTTP works from anywhere. */
+export const DEFAULT_LANGUAGE: Language = 'curl'
+
+const LANGUAGE_KEY = 'api-docs-language'
+
+/**
+ * The page language, remembered per viewer across app pages. Starts at
+ * DEFAULT_LANGUAGE so server and first client render agree, then switches
+ * to the saved choice.
+ */
+export function useApiDocsLanguage(): [Language, (lang: Language) => void] {
+  const [language, setLanguageState] = useState<Language>(DEFAULT_LANGUAGE)
+  useEffect(() => {
+    const saved = localStore.getItem(LANGUAGE_KEY)
+    if (saved && LANGUAGES.some(l => l.value === saved)) setLanguageState(saved as Language)
+  }, [])
+  const setLanguage = useCallback((lang: Language) => {
+    setLanguageState(lang)
+    localStore.setItem(LANGUAGE_KEY, lang)
+  }, [])
+  return [language, setLanguage]
+}
+
+const LANGUAGES: { value: Language; label: string }[] = [
+  { value: 'curl', label: 'rest (curl)' },
+  { value: 'python', label: 'python' },
+  { value: 'typescript', label: 'typescript' },
+  { value: 'javascript', label: 'javascript' },
+  { value: 'swift', label: 'swift' },
+  { value: 'belt', label: 'belt cli' },
+]
+
+// Table of Contents structure (lowercase style)
+function buildTocItems(hasSetupSchema: boolean): TocItem[] {
+  const schemaChildren: TocItem[] = [
+    { id: 'schema-input', title: 'input' },
+    { id: 'schema-output', title: 'output' },
+  ]
+  if (hasSetupSchema) {
+    schemaChildren.push({ id: 'schema-setup', title: 'setup' })
+  }
+  return [
+    { id: 'api-key', title: 'get an api key' },
+    {
+      id: 'api-call',
+      title: '1. calling the api',
+      children: [
+        { id: 'api-call-install', title: 'install the client' },
+        { id: 'api-call-result', title: 'run and get result' },
+        { id: 'api-call-stream', title: 'stream live updates' },
+        { id: 'api-call-background', title: 'run in the background' },
+      ],
+    },
+    {
+      id: 'auth',
+      title: '2. authentication',
+    },
+    {
+      id: 'files',
+      title: '3. files',
+      children: [
+        { id: 'files-auto-upload', title: 'automatic upload' },
+        { id: 'files-manual', title: 'manual upload' },
+      ],
+    },
+    {
+      id: 'webhooks',
+      title: '4. webhooks',
+    },
+    {
+      id: 'schema',
+      title: '5. schema',
+      children: schemaChildren,
+    },
+  ]
+}
+
+// The webhook body: the task result in an event envelope (go/api projector deliverWebhook).
+const WEBHOOK_FIELDS = [
+  { key: 'event', type: 'string', desc: 'task.completed, task.failed or task.cancelled' },
+  { key: 'timestamp', type: 'string', desc: 'iso timestamp of the delivery' },
+  { key: 'data.id', type: 'string', desc: 'task id' },
+  { key: 'data.short_id', type: 'string', desc: 'short task id' },
+  { key: 'data.status', type: 'number', desc: `terminal status (${TaskStatusCompleted}=completed, ${TaskStatusFailed}=failed, ${TaskStatusCancelled}=cancelled, ${TaskStatusRejected}=rejected)` },
+  { key: 'data.status_text', type: 'string', desc: 'the status as a word: completed, failed or cancelled' },
+  { key: 'data.output', type: 'object', desc: 'task output (when completed)' },
+  { key: 'data.error', type: 'string', desc: 'error message (when failed, omitted otherwise)' },
+  { key: 'data.session_id', type: 'string', desc: 'session id (when the task ran in a session, omitted otherwise)' },
+  { key: 'data.created_at', type: 'string', desc: 'iso timestamp' },
+  { key: 'data.updated_at', type: 'string', desc: 'iso timestamp' },
+]
+
+// Default link component (plain anchor)
+function DefaultLink({ to, className, children }: { to: string; className?: string; children: React.ReactNode }) {
+  return <a href={to} className={className}>{children}</a>
+}
+
+// Helper Components
+function SectionHeading({
+  id,
+  children,
+  level = 2
+}: {
+  id: string
+  children: React.ReactNode
+  level?: 2 | 3
+}) {
+  const Tag = level === 2 ? 'h2' : 'h3'
+  const textSize = level === 2 ? 'text-lg' : 'text-base'
+
+  return (
+    <Tag
+      id={id}
+      className={cn("flex flex-row items-center gap-2 pt-2 font-medium text-foreground", textSize)}
+    >
+      <span>{children}</span>
+      <a
+        href={`#${id}`}
+        className="font-mono font-extralight text-muted-foreground/50 transition-colors hover:text-muted-foreground"
+      >
+        <Hash className="h-3.5 w-3.5" />
+      </a>
+    </Tag>
+  )
+}
+
+function SchemaProperty({
+  field,
+  isOutput = false,
+}: {
+  field: SchemaField
+  isOutput?: boolean
+}) {
+  const resolved = field.resolved || field
+  const type = field.type || resolved.type || 'any'
+  const description = field.description || resolved.description || field.title
+  const defaultValue = field.default ?? resolved.default
+  const example = Array.isArray(field.examples) ? field.examples[0] : field.examples
+  const resolvedExample = Array.isArray(resolved.examples) ? resolved.examples[0] : resolved.examples
+  const exampleValue = example || resolvedExample
+  const enumValues = resolved.enum || field.enum
+  const minimum = resolved.minimum ?? field.minimum
+  const maximum = resolved.maximum ?? field.maximum
+  const minLength = resolved.minLength ?? field.minLength
+  const maxLength = resolved.maxLength ?? field.maxLength
+  const pattern = resolved.pattern || field.pattern
+  const format = resolved.format || field.format
+
+  return (
+    <div className="border border-border rounded-lg p-3 space-y-2">
+      <div className="flex items-center flex-wrap">
+        <span className="text-sm font-semibold">
+          {field.key}
+        </span>
+        <span className="text-xs font-mono text-muted-foreground ml-1">
+          {type}
+          {format && <span className="text-muted-foreground ml-1">({format})</span>}
+        </span>
+        {field.isRequired && <span className="text-brand-pink ml-1 text-xs">*</span>}
+      </div>
+
+      {description && (
+        <p className="text-xs text-muted-foreground">{description.toLowerCase()}</p>
+      )}
+
+      {!isOutput && (
+        <>
+          <div className="flex flex-wrap gap-2 text-xs">
+            {defaultValue !== undefined && (
+              <span className="text-muted-foreground">
+                default: <span className="text-xs tracking-wider bg-muted px-1 rounded text-foreground">{JSON.stringify(defaultValue)}</span>
+              </span>
+            )}
+            {exampleValue !== undefined && (
+              <span className="text-muted-foreground">
+                example: <span className="text-xs tracking-wider bg-muted px-1 rounded text-foreground">{JSON.stringify(exampleValue)}</span>
+              </span>
+            )}
+            {minimum !== undefined && (
+              <span className="text-muted-foreground">min:
+                <span className="text-xs tracking-wider bg-muted px-1 rounded text-foreground">{minimum}</span>
+              </span>
+            )}
+            {maximum !== undefined && (
+              <span className="text-muted-foreground">max:
+                <span className="text-xs tracking-wider bg-muted px-1 rounded text-foreground">{maximum}</span>
+              </span>
+            )}
+            {minLength !== undefined && (
+              <span className="text-muted-foreground">minLength:
+                <span className="text-xs tracking-wider bg-muted px-1 rounded text-foreground">{minLength}</span>
+              </span>
+            )}
+            {maxLength !== undefined && (
+              <span className="text-muted-foreground">maxLength:
+                <span className="text-xs tracking-wider bg-muted px-1 rounded text-foreground">{maxLength}</span>
+              </span>
+            )}
+          </div>
+
+          {enumValues && enumValues.length > 0 && (
+            <div className="flex flex-wrap gap-1">
+              <span className="text-xs text-muted-foreground">options:</span>
+              {enumValues.map((v, i) => (
+                <span key={i} className="text-xs bg-muted px-1.5 py-0.5 rounded tracking-wider">
+                  {JSON.stringify(v)}
+                </span>
+              ))}
+            </div>
+          )}
+
+          {pattern && (
+            <div className="text-xs text-muted-foreground">
+              pattern: <span className="bg-muted px-1 rounded">{pattern}</span>
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  )
+}
+
+// Language selector for ToC header
+function LanguageSelector({
+  language,
+  onLanguageChange
+}: {
+  language: Language
+  onLanguageChange: (lang: Language) => void
+}) {
+  return (
+    <div className="mb-4">
+      <Select value={language} onValueChange={(v) => onLanguageChange(v as Language)}>
+        <SelectTrigger className="w-full">
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          {LANGUAGES.map((lang) => (
+            <SelectItem key={lang.value} value={lang.value}>
+              {lang.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </div>
+  )
+}
+
+// Main Component
+export function ApiDocs({
+  app,
+  version,
+  functionName,
+  formData,
+  className,
+  LinkComponent = DefaultLink,
+  docsBasePath = '/docs',
+  settingsBasePath = '/settings',
+  language: controlledLanguage,
+  onLanguageChange,
+}: ApiDocsProps) {
+  const [internalLanguage, setInternalLanguage] = useState<Language>(DEFAULT_LANGUAGE)
+  const language = controlledLanguage ?? internalLanguage
+  const setLanguage = (lang: Language) => {
+    if (onLanguageChange) onLanguageChange(lang)
+    else setInternalLanguage(lang)
+  }
+  const Link = LinkComponent
+
+  // Resolve effective schemas from version + function
+  const effectiveFn = functionName || version?.default_function || 'run'
+
+  // Build app reference — append :function when non-default and multiple functions exist
+  // Version is only appended when short_id is provided (caller controls via pinVersion toggle)
+  const namespace = app.namespace || ''
+  const shortId = version?.short_id
+  const defaultFn = version?.default_function || 'run'
+  const hasManyFunctions = version?.functions && Object.keys(version.functions).length > 1
+  const fnSuffix = (hasManyFunctions && effectiveFn !== defaultFn) ? `:${effectiveFn}` : ''
+  const versionSuffix = shortId ? `@${shortId}` : ''
+  const appRef = `${namespace}/${app.name}${versionSuffix}${fnSuffix}`
+  const func = version?.functions?.[effectiveFn]
+  const schema = func?.input_schema || version?.input_schema || {}
+  const outputSchema = func?.output_schema || version?.output_schema
+  const setupSchema = version?.setup_schema
+
+  // Check if setup has any actual values
+  const hasSetup = formData?.setup && Object.keys(formData.setup).length > 0
+
+  // Process input with schema defaults. Without form data (a public app page),
+  // the examples run the app's own example input, or one built from its schema.
+  const processedInput = useMemo(() => {
+    const input = formData?.input ?? exampleInput(schema)
+    if (!schema?.properties) return input
+
+    const result: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(input)) {
+      if (value === undefined && schema.properties[key]) {
+        const prop = schema.properties[key]
+        if (prop.default !== undefined) {
+          result[key] = prop.default
+        } else {
+          switch (prop.type) {
+            case "string": result[key] = ""; break
+            case "number":
+            case "integer": result[key] = 0; break
+            case "boolean": result[key] = false; break
+            case "array": result[key] = []; break
+            case "object": result[key] = {}; break
+            default: result[key] = value
+          }
+        }
+      } else {
+        result[key] = value
+      }
+    }
+    return result
+  }, [formData?.input, schema])
+
+  // Example params for code generation
+  const exampleParams = useMemo(() => ({
+    appRef,
+    shortId: version?.short_id,
+    input: processedInput,
+    setup: hasSetup ? formData?.setup : undefined,
+    infra: formData?.infra || undefined,
+    workers: formData?.infra === 'private' ? (formData?.workers || undefined) : undefined,
+  }), [appRef, version?.short_id, processedInput, formData?.setup, hasSetup, formData?.infra, formData?.workers])
+
+  // Generate separate examples for result-only and streaming
+  const resultOnlyExamples = useMemo(() => generateResultOnlyExamples(exampleParams), [exampleParams])
+  const streamingExamples = useMemo(() => generateStreamingExamples(exampleParams), [exampleParams])
+
+  // Get current code for selected language
+  const currentResultCode = resultOnlyExamples[language] || ''
+  const currentStreamCode = streamingExamples[language] || ''
+  const backgroundExamples = useMemo(() => generateBackgroundExamples(exampleParams), [exampleParams])
+  const currentBackgroundCode = backgroundExamples[language] || ''
+  const fileExamples = useMemo(() => generateFileExamples(appRef), [appRef])
+  const currentFileExamples = fileExamples[language] ?? fileExamples.curl
+  const currentInstall = installCommands[language]
+  const currentKeySetup = apiKeySetup[language]
+
+  // Parse schema properties for display
+  const inputFields = useMemo(() => {
+    if (!schema) return []
+    const { fields } = getFieldsFromSchema(schema)
+    return fields
+  }, [schema])
+
+  const outputFields = useMemo(() => {
+    if (!outputSchema) return []
+    const { fields } = getFieldsFromSchema(outputSchema)
+    return fields
+  }, [outputSchema])
+
+  const setupFields = useMemo(() => {
+    if (!setupSchema) return []
+    const { fields } = getFieldsFromSchema(setupSchema)
+    return fields
+  }, [setupSchema])
+
+  const hasSetupFields = setupFields.length > 0
+
+  // Build ToC with conditional setup section
+  const tocItems = useMemo(() => buildTocItems(hasSetupFields), [hasSetupFields])
+
+  // Footer link for ToC
+  const TocFooter = () => (
+    <div className="mt-4 pt-4 border-t border-border">
+      <Link
+        to={`${docsBasePath}/api/authentication`}
+        className="text-xs text-muted-foreground hover:text-foreground transition-colors"
+      >
+        → full api documentation
+      </Link>
+    </div>
+  )
+
+  return (
+    <div className={cn("", className)}>
+      <div className="grid grid-cols-1 gap-8 lg:grid-cols-12">
+        {/* table of contents - sticky sidebar */}
+        <div className="col-span-1 lg:col-span-3">
+          <div className="lg:sticky lg:top-4 border border-border rounded-xl bg-card p-4">
+            <TableOfContents
+              items={tocItems}
+              header={<LanguageSelector language={language} onLanguageChange={setLanguage} />}
+              footer={<TocFooter />}
+            />
+          </div>
+        </div>
+
+        {/* main content */}
+        <div className="col-span-1 lg:col-span-9 border border-border rounded-xl bg-card p-6 space-y-8">
+          {/* about section */}
+          <div>
+            <h3 className="text-lg font-medium mb-2">about</h3>
+            <p className="text-sm text-muted-foreground">{app.description?.toLowerCase() || `run ${app.title || app.name} via api.`}</p>
+          </div>
+
+          {/* get an api key */}
+          <div className="space-y-3">
+            <SectionHeading id="api-key">get an api key</SectionHeading>
+            <p className="text-sm text-muted-foreground">
+              create one in <Link to={`${settingsBasePath}/keys`} className="text-primary hover:underline">settings → api keys</Link>
+              {language === 'belt'
+                ? <>, or skip it and sign in with <code className="rounded bg-muted px-1 py-0.5 text-xs">belt login</code>. the examples read it from </>
+                : <>. the examples read it from </>}
+              <code className="rounded bg-muted px-1 py-0.5 text-xs">{currentKeySetup.variable}</code>.
+            </p>
+            <CodeBlock language="bash" textSize="text-xs">
+              {currentKeySetup.command}
+            </CodeBlock>
+          </div>
+
+          <Separator />
+
+          {/* 1. calling the api */}
+          <SectionHeading id="api-call">1. calling the api</SectionHeading>
+
+          <div className="space-y-6">
+            {/* install */}
+            <div className="space-y-3">
+              <SectionHeading id="api-call-install" level={3}>
+                install the client
+              </SectionHeading>
+              <p className="text-sm text-muted-foreground">
+                {currentInstall
+                  ? 'the client provides a convenient way to interact with the api.'
+                  : 'nothing to install. any http client works; the examples use curl, and jq to read responses. every response wraps its result in a data field.'}
+              </p>
+              {currentInstall && (
+                <CodeBlock
+                  language={language === 'swift' ? 'swift' : 'bash'}
+                  textSize="text-xs"
+                  className="max-h-[200px]"
+                >
+                  {currentInstall.command}
+                </CodeBlock>
+              )}
+            </div>
+
+            {/* run and get result */}
+            <div className="space-y-3">
+              <SectionHeading id="api-call-result" level={3}>
+                run and get result
+              </SectionHeading>
+              <p className="text-sm text-muted-foreground">
+                {language === 'curl'
+                  ? <>send <code className="rounded bg-muted px-1 py-0.5 text-xs">"wait": true</code> to hold the connection until the task finishes. without it the call returns right away with the task still running.</>
+                  : "submit a request and wait for the final result. best for batch processing or when you don't need progress updates."}
+              </p>
+              <CodeBlock
+                language={(language === 'curl' || language === 'belt') ? 'bash' : language}
+                textSize="text-xs"
+                className="max-h-[300px]"
+              >
+                {currentResultCode}
+              </CodeBlock>
+            </div>
+
+            {/* stream live updates */}
+            <div className="space-y-3">
+              <SectionHeading id="api-call-stream" level={3}>
+                stream live updates
+              </SectionHeading>
+              <p className="text-sm text-muted-foreground">
+                get real-time progress updates as the task runs. ideal for showing progress bars, partial results, or long-running tasks.
+                {language === 'curl' && <> send <code className="rounded bg-muted px-1 py-0.5 text-xs">"stream": true</code> and the response is a server-sent event stream that ends when the task does.</>}
+              </p>
+              <CodeBlock
+                language={(language === 'curl' || language === 'belt') ? 'bash' : language}
+                textSize="text-xs"
+                className="max-h-[300px]"
+              >
+                {currentStreamCode}
+              </CodeBlock>
+            </div>
+
+            {/* run in the background */}
+            <div className="space-y-3">
+              <SectionHeading id="api-call-background" level={3}>
+                run in the background
+              </SectionHeading>
+              <p className="text-sm text-muted-foreground">
+                start the task and get its id back right away, then check on it later. for long tasks, or when you'd rather be called back, see <a href="#webhooks" className="text-primary hover:underline">webhooks</a>.
+              </p>
+              <CodeBlock
+                language={(language === 'curl' || language === 'belt') ? 'bash' : language}
+                textSize="text-xs"
+                className="max-h-[300px]"
+              >
+                {currentBackgroundCode}
+              </CodeBlock>
+            </div>
+          </div>
+
+          <Separator />
+
+          {/* 2. authentication */}
+          <SectionHeading id="auth">2. authentication</SectionHeading>
+
+          <p className="text-sm text-muted-foreground">
+            the api uses api keys for authentication. see the{' '}
+            <Link to={`${docsBasePath}/api/authentication`} className="text-primary hover:underline">authentication docs</Link>{' '}
+            for detailed setup instructions.
+          </p>
+
+          <Separator />
+
+          {/* 3. files */}
+          <SectionHeading id="files">3. files</SectionHeading>
+
+          <p className="text-sm text-muted-foreground">
+            file inputs are automatically handled by the sdk. you can pass local paths, urls, or base64 data.
+          </p>
+
+          <div className="space-y-6">
+            {/* automatic upload */}
+            <div className="space-y-3">
+              <SectionHeading id="files-auto-upload" level={3}>
+                automatic upload
+              </SectionHeading>
+              <p className="text-sm text-muted-foreground">
+                {language === 'python'
+                  ? 'the python sdk automatically detects local file paths and uploads them. urls are passed through as-is.'
+                  : language === 'typescript' || language === 'javascript'
+                    ? 'the javascript sdk automatically uploads blob/file objects and data uris. urls are passed through as-is.'
+                    : language === 'swift'
+                      ? 'pass urls directly. upload local files with client.files.upload (below) and pass the returned uri.'
+                      : language === 'belt'
+                        ? 'belt detects local file paths in the input and uploads them. urls are passed through as-is.'
+                        : 'pass urls directly or use data uris for inline content.'}
+              </p>
+              <CodeBlock
+                language={(language === 'curl' || language === 'belt') ? 'bash' : language}
+                textSize="text-xs"
+              >
+                {currentFileExamples.auto}
+              </CodeBlock>
+            </div>
+
+            {/* manual upload */}
+            <div className="space-y-3">
+              <SectionHeading id="files-manual" level={3}>
+                manual upload
+              </SectionHeading>
+              <p className="text-sm text-muted-foreground">
+                you can also upload files manually and use the returned url.
+              </p>
+              <CodeBlock
+                language={(language === 'curl' || language === 'belt') ? 'bash' : language}
+                textSize="text-xs"
+              >
+                {currentFileExamples.manual}
+              </CodeBlock>
+            </div>
+          </div>
+
+          <Separator />
+
+          {/* 4. webhooks */}
+          <SectionHeading id="webhooks">4. webhooks</SectionHeading>
+
+          <p className="text-sm text-muted-foreground">
+            get notified when a task completes by providing a <code className="rounded bg-muted px-1 py-0.5 text-xs">webhook</code> url.
+            when the task reaches a terminal state (completed, failed, or cancelled), a POST request is sent to your url with the task result.
+          </p>
+
+          <CodeBlock
+            language={(language === 'curl' || language === 'belt') ? 'bash' : language}
+            textSize="text-xs"
+            className="max-h-[300px]"
+          >
+            {language === 'python' ? `result = client.run({
+    "app": "${appRef}",
+    "input": ${JSON.stringify(processedInput, null, 4).split('\n').map((l, i) => i === 0 ? l : '    ' + l).join('\n')},
+    "webhook": "https://your-server.com/webhook"
+}, wait=False)` :
+              language === 'typescript' || language === 'javascript' ? `const result = await client.run({
+  app: "${appRef}",
+  input: ${JSON.stringify(processedInput, null, 2).split('\n').map((l, i) => i === 0 ? l : '  ' + l).join('\n')},
+  webhook: "https://your-server.com/webhook"
+}, { wait: false });` :
+              language === 'swift' ? generateSwiftWebhookExample(appRef, processedInput) :
+                `curl -X POST https://api.inference.sh/apps/run \\
+  -H "Authorization: Bearer $INFERENCE_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "app": "${appRef}",
+    "input": ${JSON.stringify(processedInput, null, 4).split('\n').map((l, i) => i === 0 ? l : '    ' + l).join('\n')},
+    "webhook": "https://your-server.com/webhook"
+  }'`}
+          </CodeBlock>
+
+          <div className="space-y-3">
+            <p className="text-xs font-medium text-foreground">webhook payload</p>
+            <p className="text-xs text-muted-foreground">
+              your endpoint receives a JSON POST with the task result:
+            </p>
+            <CodeBlock language="json" textSize="text-xs">
+{`{
+  "event": "task.completed",
+  "timestamp": "2024-01-15T10:30:05Z",
+  "data": {
+    "id": "task_abc123",
+    "short_id": "abc123",
+    "status": ${TaskStatusCompleted},
+    "status_text": "completed",
+    "output": { ... },
+    "created_at": "2024-01-15T10:30:00Z",
+    "updated_at": "2024-01-15T10:30:05Z"
+  }
+}`}
+            </CodeBlock>
+            <div className="space-y-2">
+              {WEBHOOK_FIELDS.map(f => (
+                <div key={f.key} className="flex items-center gap-2 text-xs">
+                  <span className="font-semibold">{f.key}</span>
+                  <span className="font-mono text-muted-foreground">{f.type}</span>
+                  <span className="text-muted-foreground">{f.desc}</span>
+                </div>
+              ))}
+            </div>
+          </div>
+
+          <Separator />
+
+          {/* 5. schema */}
+          <SectionHeading id="schema">5. schema</SectionHeading>
+
+          <div className="space-y-6">
+            {/* input schema */}
+            <div className="space-y-4">
+              <SectionHeading id="schema-input" level={3}>
+                input
+              </SectionHeading>
+              {inputFields.length > 0 ? (
+                <div className="space-y-3">
+                  {inputFields.map((field) => (
+                    <SchemaProperty
+                      key={field.key}
+                      field={field}
+                    />
+                  ))}
+                </div>
+              ) : (
+                <p className="text-sm text-muted-foreground">no input parameters defined.</p>
+              )}
+            </div>
+
+            {/* output schema */}
+            <div className="space-y-4">
+              <SectionHeading id="schema-output" level={3}>
+                output
+              </SectionHeading>
+              {outputFields.length > 0 ? (
+                <div className="space-y-3">
+                  {outputFields.map((field) => (
+                    <SchemaProperty
+                      key={field.key}
+                      field={field}
+                      isOutput={true}
+                    />
+                  ))}
+                </div>
+              ) : (
+                <p className="text-sm text-muted-foreground">see task output for result format.</p>
+              )}
+            </div>
+
+            {/* setup schema */}
+            {hasSetupFields && (
+              <div className="space-y-4">
+                <SectionHeading id="schema-setup" level={3}>
+                  setup
+                </SectionHeading>
+                <p className="text-xs text-muted-foreground">setup parameters are provided once via the <code className="rounded bg-muted px-1 py-0.5 text-xs">setup</code> field and are persisted for a session.</p>
+                <div className="space-y-3">
+                  {setupFields.map((field) => (
+                    <SchemaProperty
+                      key={field.key}
+                      field={field}
+                    />
+                  ))}
+                </div>
+              </div>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default ApiDocs