@talonic/docs 0.21.0 → 0.21.2

package/openapi.json

@@ -70,8 +70,8 @@
       "description": "Queue of validation records requiring human review; supports single- and batch-action approvals/rejections."
     },
     {
-      "name": "Quality",
-      "description": "Ground truth datasets and benchmark runs for measuring extraction accuracy."
+      "name": "Benchmarks",
+      "description": "Ground-truth datasets and benchmark runs measuring extraction accuracy."
     },
     {
       "name": "Batches",
@@ -125,10 +125,6 @@
       "name": "Telemetry",
       "description": "Aggregate structuring metrics — capture hit rate, synthesize rate, strategy distribution, and tier funnel breakdowns per schema or run."
     },
-    {
-      "name": "Validation",
-      "description": "Ground-truth dataset management and validation runs for measuring extraction accuracy."
-    },
     {
       "name": "Credits",
       "description": "Credit balance, usage history, daily breakdown, and per-request usage log."
@@ -172,6 +168,14 @@
     {
       "name": "Webhooks",
       "description": "Outbound HMAC-signed event webhooks — configure endpoints and read the event catalog, delivery format, signature scheme, and retry policy."
+    },
+    {
+      "name": "Events",
+      "description": "The tenant event feed — the timeline of everything that happened (extractions, run completions, review verdicts, delivery outcomes). The same rows webhooks fan out from, so missed webhook deliveries can be reconciled against this feed."
+    },
+    {
+      "name": "Provenance",
+      "description": "Document-level provenance — deterministic (subject, predicate, object) claims synthesized from captured fields and spans, each carrying its evidence quote and grounded flag."
     }
   ],
   "paths": {
@@ -368,6 +372,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "402": {
+            "$ref": "#/components/responses/InsufficientCredits"
+          },
           "403": {
             "$ref": "#/components/responses/Forbidden"
           },
@@ -5103,7 +5110,7 @@
         "operationId": "listGroundTruthDatasets",
         "summary": "List ground truth datasets",
         "tags": [
-          "Quality"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -5165,7 +5172,7 @@
         "operationId": "createGroundTruthDataset",
         "summary": "Create a ground truth dataset",
         "tags": [
-          "Quality"
+          "Benchmarks"
         ],
         "requestBody": {
           "required": true,
@@ -5216,7 +5223,7 @@
         "summary": "Get a ground truth dataset",
         "description": "Returns the dataset together with its sample entries (curated known-correct values).",
         "tags": [
-          "Quality"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -5251,7 +5258,7 @@
         "operationId": "listBenchmarkRuns",
         "summary": "List benchmark runs",
         "tags": [
-          "Quality"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -5316,7 +5323,7 @@
         "summary": "Get a benchmark run",
         "description": "Returns the benchmark run together with its per-document results.",
         "tags": [
-          "Quality"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -8698,7 +8705,7 @@
         "summary": "List ground-truth datasets",
         "description": "Returns all ground-truth datasets for the customer.",
         "tags": [
-          "Validation"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -8751,7 +8758,7 @@
         "operationId": "getGroundTruth",
         "summary": "Get a ground-truth dataset",
         "tags": [
-          "Validation"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -8784,7 +8791,7 @@
         "operationId": "deleteGroundTruth",
         "summary": "Delete a ground-truth dataset",
         "tags": [
-          "Validation"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -8819,7 +8826,7 @@
         "operationId": "listValidationRuns",
         "summary": "List validation runs",
         "tags": [
-          "Validation"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -8871,7 +8878,7 @@
         "summary": "Create a validation run",
         "description": "Start a new validation run against a ground-truth dataset.",
         "tags": [
-          "Validation"
+          "Benchmarks"
         ],
         "requestBody": {
           "required": true,
@@ -8928,7 +8935,7 @@
         "operationId": "getValidationRun",
         "summary": "Get a validation run",
         "tags": [
-          "Validation"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -8961,7 +8968,7 @@
         "operationId": "deleteValidationRun",
         "summary": "Delete a validation run",
         "tags": [
-          "Validation"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -8997,7 +9004,7 @@
         "summary": "Get validation run results",
         "description": "Returns per-document and per-field accuracy results for the validation run.",
         "tags": [
-          "Validation"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -9387,17 +9394,102 @@
         }
       }
     },
+    "/v1/billing/packs": {
+      "get": {
+        "operationId": "getBillingPacks",
+        "summary": "List purchasable credit packs",
+        "description": "The self-serve credit-purchase catalog: flat prepaid packs\n(1,000 credits = 1 EUR, no volume bonuses). Buy via the checkout URL\nfrom `GET /v1/billing/upgrade-link`.\n",
+        "tags": [
+          "Billing"
+        ],
+        "responses": {
+          "200": {
+            "description": "Credit pack catalog.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "currency",
+                    "packs"
+                  ],
+                  "properties": {
+                    "currency": {
+                      "type": "string",
+                      "example": "EUR"
+                    },
+                    "packs": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "key",
+                          "eur",
+                          "credits"
+                        ],
+                        "properties": {
+                          "key": {
+                            "type": "string",
+                            "example": "50"
+                          },
+                          "lookupKey": {
+                            "type": "string",
+                            "example": "credits_pack_50"
+                          },
+                          "eur": {
+                            "type": "number",
+                            "example": 50
+                          },
+                          "credits": {
+                            "type": "integer",
+                            "example": 50000
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "429": {
+            "$ref": "#/components/responses/RateLimitExceeded"
+          }
+        }
+      }
+    },
     "/v1/billing/upgrade-link": {
       "get": {
         "operationId": "getBillingUpgradeLink",
-        "summary": "Get an upgrade link",
-        "description": "Returns a URL the agent can hand to a human to upgrade the plan or add\npayment. When a hosted billing portal exists this is a portal session\nURL; until then it is a deep link into the dashboard billing settings\n(`provider: \"dashboard\"`). A human must complete the upgrade.\n",
+        "summary": "Get a buy-credits link",
+        "description": "Returns a URL the agent hands to a human to buy prepaid credits. With\nbilling configured this is a real Stripe hosted-Checkout session\n(`provider: \"stripe\"`) for the selected pack; credits are available\nseconds after the human completes payment. Falls back to a dashboard\nbilling deep link (`provider: \"dashboard\"`) on deployments without\nStripe. A human must complete the payment either way.\n",
         "tags": [
           "Billing"
         ],
+        "parameters": [
+          {
+            "name": "pack",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "10",
+                "50",
+                "250",
+                "1000"
+              ],
+              "default": "50"
+            },
+            "description": "Credit pack to check out (see `GET /v1/billing/packs`)."
+          }
+        ],
         "responses": {
           "200": {
-            "description": "Upgrade link.",
+            "description": "Buy-credits link.",
             "content": {
               "application/json": {
                 "schema": {
@@ -9411,16 +9503,20 @@
                     "url": {
                       "type": "string",
                       "format": "uri",
-                      "example": "https://app.talonic.com/settings/billing?upgrade=1"
+                      "example": "https://checkout.stripe.com/c/pay/cs_test_..."
                     },
                     "provider": {
                       "type": "string",
-                      "description": "'dashboard' (deep link) or 'stripe' (portal session) once a portal exists.",
-                      "example": "dashboard"
+                      "description": "'stripe' (hosted Checkout session) or 'dashboard' (deep link fallback).",
+                      "example": "stripe"
                     },
                     "requires_human": {
                       "type": "boolean"
                     },
+                    "pack": {
+                      "type": "object",
+                      "description": "The selected pack (stripe provider only)."
+                    },
                     "message": {
                       "type": "string"
                     }
@@ -11646,7 +11742,7 @@
         "operationId": "listGroundTruthEntries",
         "summary": "List entries in a ground truth dataset",
         "tags": [
-          "Quality"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -11700,7 +11796,7 @@
         "operationId": "createGroundTruthEntry",
         "summary": "Add an entry to a ground truth dataset",
         "tags": [
-          "Quality"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -11766,7 +11862,7 @@
         "operationId": "updateGroundTruthEntry",
         "summary": "Update a ground truth entry",
         "tags": [
-          "Quality"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -11830,7 +11926,7 @@
         "operationId": "deleteGroundTruthEntry",
         "summary": "Delete a ground truth entry",
         "tags": [
-          "Quality"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -11877,7 +11973,7 @@
         "summary": "Compare two benchmark runs",
         "description": "Returns both benchmark runs side by side together with the overall accuracy delta (run_a minus run_b). The delta is null when either run has not yet produced an overall accuracy score.",
         "tags": [
-          "Quality"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -11951,7 +12047,7 @@
         "summary": "Get benchmark results",
         "description": "Returns per-document accuracy results for a benchmark run.",
         "tags": [
-          "Quality"
+          "Benchmarks"
         ],
         "parameters": [
           {
@@ -11993,7 +12089,8 @@
       "post": {
         "operationId": "submitProcess",
         "summary": "Submit a document for processing",
-        "description": "Upload a document and trigger a configured processing pipeline.\nAlways returns 202. Results delivered via `process.completed` webhook.\n\nIdempotency is automatic: the same (config_id, batch_id, file) combination\nreturns the existing run without re-processing. If batch_id is absent,\ndedup applies within a 24-hour window.\n",
+        "deprecated": true,
+        "description": "Deprecated: prefer `/v1/pipelines` for new integrations; this endpoint remains supported.\n\nUpload a document and trigger a configured processing pipeline.\nAlways returns 202. Results delivered via `process.completed` webhook.\n\nIdempotency is automatic: the same (config_id, batch_id, file) combination\nreturns the existing run without re-processing. If batch_id is absent,\ndedup applies within a 24-hour window.\n",
         "tags": [
           "Process"
         ],
@@ -12139,7 +12236,8 @@
       "get": {
         "operationId": "listConfigs",
         "summary": "List available processing configs",
-        "description": "Returns all processing configurations available to your organization.",
+        "deprecated": true,
+        "description": "Deprecated: prefer `/v1/pipelines` for new integrations; this endpoint remains supported. Returns all processing configurations available to your organization.\n",
         "tags": [
           "Process"
         ],
@@ -15936,7 +16034,8 @@
           "Fields"
         ],
         "summary": "Query the field registry by field values",
-        "description": "Returns documents whose captured field values match the `where` map (values matched via ILIKE). A read operation that takes a POST body. Requires the `read` scope. An unknown `where` field returns a 200 body `{ error: 'unknown_field' }`.\n",
+        "deprecated": true,
+        "description": "Deprecated: moved under `/v1/fields/registry/*`; use `POST /v1/fields/registry/query`. This path remains supported and serves the same handler. Returns documents whose captured field values match the `where` map (values matched via ILIKE). A read operation that takes a POST body. Requires the `read` scope. An unknown `where` field returns a 200 body `{ error: 'unknown_field' }`.\n",
         "operationId": "queryRegistry",
         "security": [
           {
@@ -15982,6 +16081,58 @@
         }
       }
     },
+    "/v1/fields/registry/query": {
+      "post": {
+        "tags": [
+          "Fields"
+        ],
+        "summary": "Query the field registry by field values",
+        "description": "The canonical home of the registry query going forward (alias of the deprecated `POST /v1/registry/query`; both serve the same handler). Returns documents whose captured field values match the `where` map (values matched via ILIKE). A read operation that takes a POST body. Requires the `read` scope. An unknown `where` field returns a 200 body `{ error: 'unknown_field' }`.\n",
+        "operationId": "queryFieldsRegistry",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "where"
+                ],
+                "properties": {
+                  "where": {
+                    "type": "object",
+                    "minProperties": 1,
+                    "additionalProperties": true
+                  },
+                  "select": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "default": 100,
+                    "maximum": 500
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "{ data: row[], total }"
+          }
+        }
+      }
+    },
     "/v1/matching/packages/configs": {
       "get": {
         "tags": [
@@ -16481,7 +16632,8 @@
           "Fields"
         ],
         "summary": "Field-registry health snapshot (read-only)",
-        "description": "Tier + admission counts, singleton/weak-name rates, occurrence and resolution stats, transfer hit rate, and coherence/atomicity metrics for the tenant's field registry. The same view the in-app registry dashboard reads; no lifecycle or cleanup actions are exposed.\n",
+        "deprecated": true,
+        "description": "Deprecated: moved under `/v1/fields/registry/*`; use `GET /v1/fields/registry/health`. This path remains supported and serves the same handler. Tier + admission counts, singleton/weak-name rates, occurrence and resolution stats, transfer hit rate, and coherence/atomicity metrics for the tenant's field registry. The same view the in-app registry dashboard reads; no lifecycle or cleanup actions are exposed.\n",
         "operationId": "getRegistryHealth",
         "security": [
           {
@@ -16495,6 +16647,26 @@
         }
       }
     },
+    "/v1/fields/registry/health": {
+      "get": {
+        "tags": [
+          "Fields"
+        ],
+        "summary": "Field-registry health snapshot (read-only)",
+        "description": "The canonical home of the registry health snapshot going forward (alias of the deprecated `GET /v1/registry/health`; both serve the same handler). Tier + admission counts, singleton/weak-name rates, occurrence and resolution stats, transfer hit rate, and coherence/atomicity metrics for the tenant's field registry. The same view the in-app registry dashboard reads; no lifecycle or cleanup actions are exposed.\n",
+        "operationId": "getFieldsRegistryHealth",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Registry health snapshot"
+          }
+        }
+      }
+    },
     "/v1/customer-ontologies": {
       "get": {
         "tags": [
@@ -17342,6 +17514,99 @@
         }
       }
     },
+    "/v1/events": {
+      "get": {
+        "tags": [
+          "Events"
+        ],
+        "summary": "List tenant events",
+        "description": "Newest-first feed of platform events (document.extracted, run.*.completed/failed, result.flagged/approved/rejected, delivery.item.*, case.resolved). Alias of /v1/delivery/events at the API root.\n",
+        "operationId": "listEvents",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "event_type",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Filter by event type, e.g. document.extracted"
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "default": 50,
+              "maximum": 200
+            }
+          },
+          {
+            "name": "offset",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "default": 0
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "{ data: [{ id, event_type, payload, created_at }], total, limit, offset }"
+          }
+        }
+      }
+    },
+    "/v1/documents/{id}/claims": {
+      "get": {
+        "tags": [
+          "Provenance"
+        ],
+        "summary": "List a document's provenance claims",
+        "description": "Deterministic atomic (subject, predicate, object) claims synthesized from the document's captured fields + provenance spans (no LLM). Each claim carries its evidence quote, grounded flag, and confidence. Field-level span detail lives on GET /v1/field-reviews/{docId}/{fieldKey}.\n",
+        "operationId": "listDocumentClaims",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "grounded",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "boolean"
+            },
+            "description": "true = only span-backed claims"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "{ data: [{ subject, predicate, object, qualifier, evidence, segment_id, grounded, confidence, origin }], total }"
+          },
+          "404": {
+            "description": "Document not found or not owned by the caller."
+          }
+        }
+      }
+    },
     "/v1/webhooks/events": {
       "get": {
         "tags": [
@@ -18508,7 +18773,7 @@
               "statusCode": 429,
               "code": "QUOTA_EXCEEDED",
               "error": "Too Many Requests",
-              "message": "Daily extract request limit (50) reached. Resets at midnight UTC.",
+              "message": "Daily extract request ceiling reached. Resets at midnight UTC. Spend is governed by credits, not this abuse ceiling.",
               "retryable": true,
               "timestamp": "2026-04-25T23:45:00.000Z",
               "path": "/v1/extract"
@@ -18516,6 +18781,48 @@
           }
         }
       },
+      "InsufficientCredits": {
+        "description": "Insufficient credits (402). The body is the agent-actionable contract:\n`buy_credits_url` is where a human completes a purchase (see also\n`GET /v1/billing/upgrade-link` for a direct Stripe Checkout link), and\n`pricing_url` is the machine-readable rate catalog. Free workspaces\nreceive 5,000 credits monthly; purchased credits top up the same\nbalance.\n",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "required": [
+                "error",
+                "message",
+                "required_credits",
+                "balance_credits"
+              ],
+              "properties": {
+                "error": {
+                  "type": "string",
+                  "example": "insufficient_credits"
+                },
+                "message": {
+                  "type": "string"
+                },
+                "required_credits": {
+                  "type": "integer",
+                  "example": 100
+                },
+                "balance_credits": {
+                  "type": "integer",
+                  "example": 0
+                },
+                "buy_credits_url": {
+                  "type": "string",
+                  "format": "uri",
+                  "example": "https://app.talonic.com/settings/billing?buy=1"
+                },
+                "pricing_url": {
+                  "type": "string",
+                  "example": "/v1/pricing"
+                }
+              }
+            }
+          }
+        }
+      },
       "InternalServerError": {
         "description": "An unexpected error occurred.",
         "content": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talonic/docs",
-  "version": "0.21.0",
+  "version": "0.21.2",
   "description": "Talonic documentation components — API Reference & Platform Guide",
   "license": "UNLICENSED",
   "private": false,

package/dist/tailwind-preset.d.cts

@@ -1,45 +0,0 @@
-/**
- * Tailwind CSS preset for @talonic/docs consumers.
- * Adds the Void design system color tokens and font families
- * so doc components render correctly in any host app.
- */
-declare const voidDocsPreset: {
-    darkMode: "class";
-    theme: {
-        extend: {
-            colors: {
-                'void-bg': string;
-                'void-bg-elevated': string;
-                'void-surface': string;
-                'void-surface-2': string;
-                'void-surface-3': string;
-                'void-border': string;
-                'void-border-hover': string;
-                'void-text-primary': string;
-                'void-text-secondary': string;
-                'void-text-muted': string;
-                'void-text-tertiary': string;
-                'void-accent': string;
-                'void-accent-hover': string;
-                'void-accent-dim': string;
-                'void-accent-tint': string;
-                'void-danger': string;
-                'void-danger-solid': string;
-                'void-divider': string;
-                'void-warning': string;
-                'void-warning-dim': string;
-                'void-tier-1': string;
-                'void-tier-2': string;
-                'void-tier-3': string;
-            };
-            fontFamily: {
-                space: string[];
-                body: string[];
-                mono: string[];
-            };
-        };
-    };
-    plugins: never[];
-};
-
-export { voidDocsPreset as default };