@talonic/docs 0.19.0 → 0.19.1

package/dist/content.js

@@ -1,23 +1,23 @@
 // src/content/helpers.ts
-function deriveBreadcrumbs(sections43, leafId, domain) {
+function deriveBreadcrumbs(sections44, leafId, domain) {
   const root = {
     label: domain === "api" ? "API Reference" : "Platform Guide",
     slug: domain
   };
-  for (const group of sections43) {
+  for (const group of sections44) {
     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 = sections44.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(sections44, leafId) {
+  const flat = sections44.flatMap(
     (s) => s.children ?? [{ id: s.id, label: s.label }]
   );
   const idx = flat.findIndex((c) => c.id === leafId);
@@ -221,6 +221,11 @@ var API_NAV_SECTIONS = [
     { id: "manage-routing-rule", label: "Manage Rule" },
     { id: "reorder-routing-rules", label: "Reorder" }
   ] },
+  { 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 +10705,186 @@ 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/errors-rate-limits.ts
+var sections43 = [
   {
     slug: "error-format",
     parentSlug: "errors-rate-limits",
@@ -10853,7 +11036,8 @@ var ALL_API_RAW = [
   ...sections39,
   ...sections40,
   ...sections41,
-  ...sections42
+  ...sections42,
+  ...sections43
 ];
 function enrich(raw, navSections, domain) {
   return raw.map((r) => {

package/dist/index.js

@@ -6565,6 +6565,11 @@ var API_NAV_SECTIONS = [
     { id: "manage-routing-rule", label: "Manage Rule" },
     { id: "reorder-routing-rules", label: "Reorder" }
   ] },
+  { 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 +6715,7 @@ 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: "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 = [