@talonic/docs 0.19.0 → 0.19.2

package/dist/content.js

@@ -1,23 +1,23 @@
 // src/content/helpers.ts
-function deriveBreadcrumbs(sections43, leafId, domain) {
+function deriveBreadcrumbs(sections45, leafId, domain) {
   const root = {
     label: domain === "api" ? "API Reference" : "Platform Guide",
     slug: domain
   };
-  for (const group of sections43) {
+  for (const group of sections45) {
     const child = group.children?.find((c) => c.id === leafId);
     if (child) {
       return [root, { label: group.label, slug: group.id }, { label: child.label, slug: child.id }];
     }
   }
-  const topLevel = sections43.find((s) => s.id === leafId);
+  const topLevel = sections45.find((s) => s.id === leafId);
   if (topLevel) {
     return [root, { label: topLevel.label, slug: topLevel.id }];
   }
   return [root];
 }
-function derivePrevNext(sections43, leafId) {
-  const flat = sections43.flatMap(
+function derivePrevNext(sections45, leafId) {
+  const flat = sections45.flatMap(
     (s) => s.children ?? [{ id: s.id, label: s.label }]
   );
   const idx = flat.findIndex((c) => c.id === leafId);
@@ -221,6 +221,14 @@ var API_NAV_SECTIONS = [
     { id: "manage-routing-rule", label: "Manage Rule" },
     { id: "reorder-routing-rules", label: "Reorder" }
   ] },
+  { id: "registry", label: "Registry", children: [
+    { id: "registry-query", label: "Query" }
+  ] },
+  { id: "billing", label: "Billing", children: [
+    { id: "billing-settings", label: "Settings" },
+    { id: "billing-topup", label: "Auto Top-Up" },
+    { id: "cost-headers", label: "Cost Headers" }
+  ] },
   { id: "errors-rate-limits", label: "Errors & Rate Limits", children: [
     { id: "error-format", label: "Error Format" },
     { id: "error-codes", label: "Error Codes" },
@@ -10700,8 +10708,299 @@ var sections41 = [
   }
 ];
 
-// src/content/api/errors-rate-limits.ts
+// src/content/api/billing.ts
 var sections42 = [
+  {
+    slug: "billing-settings",
+    parentSlug: "billing",
+    title: "Get / Update Settings",
+    seoTitle: "Billing Settings Endpoint \u2014 Talonic Docs",
+    description: "Get and update auto top-up billing settings. A human must enable auto top-up before agents can use the topup endpoint.",
+    content: [
+      {
+        type: "paragraph",
+        text: "Billing settings control whether AI agents can autonomously top up credits. A human must enable auto top-up and configure the threshold and amount before agents can call the topup endpoint."
+      },
+      {
+        type: "endpoint",
+        method: "GET",
+        path: "/v1/billing/settings",
+        summary: "Get current billing settings.",
+        description: "Requires read scope.",
+        blocks: [
+          {
+            type: "code",
+            title: "Response",
+            code: `{
+  "auto_topup_enabled": false,
+  "auto_topup_threshold": 5000,
+  "auto_topup_amount": 50000
+}`
+          }
+        ]
+      },
+      {
+        type: "endpoint",
+        method: "PATCH",
+        path: "/v1/billing/settings",
+        summary: "Update billing settings.",
+        description: "Requires write scope. All fields are optional \u2014 only provided fields are updated.",
+        blocks: [
+          {
+            type: "param-table",
+            title: "Body parameters",
+            params: [
+              { name: "auto_topup_enabled", type: "boolean", description: "Enable or disable auto top-up for agents." },
+              { name: "auto_topup_threshold", type: "integer", description: "Balance threshold (credits) below which agents can top up. Minimum 1,000.", default: "5000" },
+              { name: "auto_topup_amount", type: "integer", description: "Credits added per top-up. Minimum 1,000, maximum 500,000.", default: "50000" }
+            ]
+          }
+        ]
+      }
+    ],
+    related: [
+      { label: "Auto Top-Up", slug: "billing-topup" },
+      { label: "Credits Balance", slug: "credits-balance" }
+    ],
+    faq: [
+      {
+        question: "Who can enable auto top-up?",
+        answer: "Only a human with write access can enable auto top-up via PATCH /v1/billing/settings. Agents cannot enable it themselves."
+      }
+    ],
+    mentions: ["billing settings", "auto top-up", "threshold", "credits"]
+  },
+  {
+    slug: "billing-topup",
+    parentSlug: "billing",
+    title: "Auto Top-Up",
+    seoTitle: "Auto Top-Up Endpoint \u2014 Talonic Docs",
+    description: "Agent-callable endpoint to autonomously top up credits. Requires auto_topup_enabled to be set by a human. Returns 403 if not enabled.",
+    content: [
+      {
+        type: "paragraph",
+        text: "AI agents call this endpoint to autonomously add credits when the balance falls below the configured threshold. **A human must first enable auto top-up** via `PATCH /v1/billing/settings`."
+      },
+      {
+        type: "endpoint",
+        method: "POST",
+        path: "/v1/billing/topup",
+        summary: "Top up credits autonomously. Requires billing scope.",
+        description: "Returns 403 if auto_topup_enabled is false. If balance is already above threshold, returns topped_up: false without adding credits.",
+        blocks: [
+          {
+            type: "code",
+            title: "Response (topped up)",
+            code: `{
+  "topped_up": true,
+  "amount_credits": 50000,
+  "new_balance_credits": 54930,
+  "new_balance_eur": 54.93
+}`
+          },
+          {
+            type: "code",
+            title: "Response (not needed)",
+            code: `{
+  "topped_up": false,
+  "reason": "balance_above_threshold",
+  "balance_credits": 64930,
+  "balance_eur": 64.93,
+  "threshold_credits": 5000
+}`
+          },
+          {
+            type: "callout",
+            variant: "warning",
+            text: "The `billing` scope must be explicitly granted to the API key. Existing keys do not have it by default."
+          }
+        ]
+      }
+    ],
+    related: [
+      { label: "Billing Settings", slug: "billing-settings" },
+      { label: "Credits Balance", slug: "credits-balance" }
+    ],
+    faq: [
+      {
+        question: "Can an agent enable auto top-up itself?",
+        answer: "No. Auto top-up must be enabled by a human via PATCH /v1/billing/settings. The POST /v1/billing/topup endpoint returns 403 if it is not enabled."
+      },
+      {
+        question: "What scope does the API key need?",
+        answer: "The billing scope. This must be explicitly granted when creating the API key \u2014 existing keys do not have it by default."
+      }
+    ],
+    mentions: ["auto top-up", "agent", "billing scope", "credits", "autonomous"]
+  },
+  {
+    slug: "cost-headers",
+    parentSlug: "billing",
+    title: "Cost Response Headers",
+    seoTitle: "Cost Response Headers \u2014 Talonic Docs",
+    description: "Every successful POST /v1/extract response includes X-Talonic-Cost-* headers showing credits consumed, EUR equivalent, remaining balance, and cell resolution breakdown.",
+    content: [
+      {
+        type: "paragraph",
+        text: "Every successful `POST /v1/extract` response includes cost headers so AI agents can track spending without a separate API call:"
+      },
+      {
+        type: "param-table",
+        title: "Response headers",
+        params: [
+          { name: "X-Talonic-Cost-Credits", type: "integer", description: "Credits consumed for this extraction request." },
+          { name: "X-Talonic-Cost-EUR", type: "float", description: "EUR equivalent of credits consumed (at the configured rate)." },
+          { name: "X-Talonic-Balance-Credits", type: "integer", description: "Remaining credit balance after this request." },
+          { name: "X-Talonic-Cells-Resolved-Registry", type: "integer", description: "Number of fields resolved from the registry (no AI cost)." },
+          { name: "X-Talonic-Cells-Resolved-AI", type: "integer", description: "Number of fields resolved by AI extraction." }
+        ]
+      },
+      {
+        type: "code",
+        title: "Example response headers",
+        language: "http",
+        code: `HTTP/1.1 200 OK
+X-Talonic-Cost-Credits: 70
+X-Talonic-Cost-EUR: 0.07
+X-Talonic-Balance-Credits: 64930
+X-Talonic-Cells-Resolved-Registry: 0
+X-Talonic-Cells-Resolved-AI: 1`
+      },
+      {
+        type: "paragraph",
+        text: "Agents can read these headers after every extraction to decide whether to call `POST /v1/billing/topup` to replenish credits."
+      }
+    ],
+    related: [
+      { label: "POST /v1/extract", slug: "post-extract" },
+      { label: "Auto Top-Up", slug: "billing-topup" },
+      { label: "Credits Balance", slug: "credits-balance" }
+    ],
+    faq: [
+      {
+        question: "Are cost headers included on async (202) responses?",
+        answer: "No. Cost headers are only included on synchronous 200 responses where extraction completes immediately. Async responses return a poll URL instead."
+      }
+    ],
+    mentions: ["cost headers", "X-Talonic-Cost", "credits", "balance", "cells resolved"]
+  }
+];
+
+// src/content/api/registry.ts
+var sections43 = [
+  {
+    slug: "registry-query",
+    parentSlug: "registry",
+    title: "Query the Registry",
+    seoTitle: "Registry Query \u2014 Ingest Once, Query Forever \u2014 Talonic Docs",
+    description: "Query previously-extracted field values across all documents without re-extraction. Zero AI calls. Filter by field values and select which fields to return.",
+    content: [
+      {
+        type: "paragraph",
+        text: "The registry query endpoint searches across **all previously-extracted documents** by field values. No document upload, no re-extraction, no AI calls. Documents ingested days or months ago are queryable immediately."
+      },
+      {
+        type: "endpoint",
+        method: "POST",
+        path: "/v1/registry/query",
+        summary: "Query extracted field values across documents.",
+        description: "Requires read scope. Returns flat rows with one entry per matching document. All `where` conditions are ANDed.",
+        blocks: [
+          {
+            type: "param-table",
+            title: "Body parameters",
+            params: [
+              { name: "where", type: "object", required: true, description: "Field-value conditions. Keys are field names, values are the expected values. All conditions are ANDed." },
+              { name: "select", type: "string[]", description: "Field names to return in results. If omitted, returns all fields referenced in `where`." },
+              { name: "limit", type: "integer", description: "Maximum rows to return (default 100, max 500).", default: "100" }
+            ]
+          },
+          {
+            type: "code",
+            title: "Request",
+            language: "json",
+            code: `{
+  "where": {
+    "vendor_name": "Meridian Energy AG",
+    "contract_year": "2026"
+  },
+  "select": ["contract_value", "auto_renew", "notice_period_days"],
+  "limit": 50
+}`
+          },
+          {
+            type: "code",
+            title: "Response",
+            language: "json",
+            code: `{
+  "data": [
+    {
+      "document_id": "d7a1b2c3-...",
+      "filename": "meridian-framework-2026.pdf",
+      "document_type": "Framework Agreement",
+      "vendor_name": "Meridian Energy AG",
+      "contract_year": "2026",
+      "contract_value": "450000",
+      "auto_renew": "true",
+      "notice_period_days": "90"
+    },
+    {
+      "document_id": "e8f4a5b6-...",
+      "filename": "meridian-amendment-q2.pdf",
+      "document_type": "Contract Amendment",
+      "vendor_name": "Meridian Energy AG",
+      "contract_year": "2026",
+      "contract_value": "475000",
+      "auto_renew": "true",
+      "notice_period_days": "90"
+    }
+  ],
+  "total": 2
+}`
+          },
+          {
+            type: "callout",
+            text: "Field names in `where` and `select` are resolved against your workspace's field registry by canonical name (case-insensitive). Unknown field names return an error."
+          },
+          {
+            type: "paragraph",
+            text: "**How it works:** The query searches the `resolved_document_values` table \u2014 materialized field values produced by the extraction and jobs pipeline. Every field extracted from every document is queryable. No LLM calls are made."
+          }
+        ]
+      }
+    ],
+    related: [
+      { label: "Field Registry", slug: "field-registry" },
+      { label: "Filter Documents", slug: "filter-documents" },
+      { label: "POST /v1/extract", slug: "post-extract" }
+    ],
+    faq: [
+      {
+        question: "Does registry query re-extract documents?",
+        answer: "No. It searches previously-extracted field values with zero AI calls. Documents can have been ingested days or months ago."
+      },
+      {
+        question: "What field names can I use in where and select?",
+        answer: "Any canonical field name from your workspace's field registry. Names are resolved case-insensitively. Use GET /v1/fields to discover available field names."
+      },
+      {
+        question: "How is this different from POST /filter/documents?",
+        answer: "Registry query returns flat rows (field name \u2192 value), shaped for agents and programmatic consumption. Filter documents returns document objects with nested field_values, shaped for UI consumption."
+      }
+    ],
+    mentions: [
+      "registry query",
+      "ingest once",
+      "query forever",
+      "field values",
+      "zero re-extraction",
+      "resolved_document_values"
+    ]
+  }
+];
+
+// src/content/api/errors-rate-limits.ts
+var sections44 = [
   {
     slug: "error-format",
     parentSlug: "errors-rate-limits",
@@ -10853,7 +11152,9 @@ var ALL_API_RAW = [
   ...sections39,
   ...sections40,
   ...sections41,
-  ...sections42
+  ...sections42,
+  ...sections43,
+  ...sections44
 ];
 function enrich(raw, navSections, domain) {
   return raw.map((r) => {

package/dist/index.js

@@ -6565,6 +6565,14 @@ var API_NAV_SECTIONS = [
     { id: "manage-routing-rule", label: "Manage Rule" },
     { id: "reorder-routing-rules", label: "Reorder" }
   ] },
+  { id: "registry", label: "Registry", children: [
+    { id: "registry-query", label: "Query" }
+  ] },
+  { id: "billing", label: "Billing", children: [
+    { id: "billing-settings", label: "Settings" },
+    { id: "billing-topup", label: "Auto Top-Up" },
+    { id: "cost-headers", label: "Cost Headers" }
+  ] },
   { id: "errors-rate-limits", label: "Errors & Rate Limits", children: [
     { id: "error-format", label: "Error Format" },
     { id: "error-codes", label: "Error Codes" },
@@ -6710,6 +6718,8 @@ var API_SECTION_META = [
   { id: "review", title: "Review API", description: "Review queue for validation records \u2014 list items, stats, take action (approve/reject/flag), batch operations, and assignment." },
   { id: "quality", title: "Quality API", description: "Ground truth datasets, entries management with CSV import, benchmark runs, per-field accuracy results, and benchmark comparison." },
   { id: "routing-rules", title: "Routing Rules API", description: "Document routing rules \u2014 create, manage, and reorder priority-based rules for automatic document workflow assignment." },
+  { id: "registry", title: "Registry API", description: "Query previously-extracted field values across all documents \u2014 ingest once, query forever. Zero re-extraction, zero AI calls." },
+  { id: "billing", title: "Billing API", description: "Billing settings, auto top-up for AI agents, and cost response headers on extraction requests." },
   { id: "errors-rate-limits", title: "Errors & Rate Limits", description: "Error response format, error codes, rate limit tiers by plan, and rate limit headers." }
 ];
 var PLATFORM_SECTION_META = [