extractia-sdk 1.3.0 → 1.5.0

package/README.md

@@ -22,6 +22,7 @@ Works in Node.js ≥ 18 and modern browsers via the provided UMD build.
    - [AI Features](#ai-features)
    - [Exports](#exports)
    - [OCR Tools](#ocr-tools)
+   - [Execution History](#getocrtoolexecutionsoptions)
    - [Credits & Analytics](#credits--analytics)
    - [Sub-Users](#sub-users)
 6. [TypeScript](#typescript)
@@ -796,6 +797,74 @@ if (docType === "invoice") {
 
 ---
 
+#### `getOcrToolExecutions(options?)`
+
+Returns a paginated list of OCR tool execution history for the authenticated user.
+Each record includes the original image (`imageBase64`), the AI answer, explanation, and run metadata.
+
+> **Image data is included in every record.** Keep page sizes small when rendering thumbnails to avoid large payloads.
+
+| Option   | Type     | Default | Description                                              |
+| -------- | -------- | ------- | -------------------------------------------------------- |
+| `toolId` | `string` | —       | Filter by tool ID. Omit to return executions for all tools |
+| `page`   | `number` | `0`     | Zero-based page index                                    |
+| `size`   | `number` | `20`    | Page size — values above 50 are capped server-side       |
+
+```js
+// All executions (most recent first)
+const history = await getOcrToolExecutions();
+console.log(`${history.totalElements} total executions`);
+
+for (const exec of history.content) {
+  console.log(exec.toolName, exec.answer, exec.status); // "Proof of Residence" "YES" "SUCCESS"
+  // exec.imageBase64 — the original image that was analyzed
+  // exec.createdAt   — ISO 8601 UTC timestamp
+}
+
+// Filter by a specific tool
+const residenceHistory = await getOcrToolExecutions({
+  toolId: "tool_residence_check",
+  page: 0,
+  size: 10,
+});
+
+// Check for failed executions
+const failures = history.content.filter((e) => e.status === "FAILURE");
+failures.forEach((e) => console.error(e.toolName, e.errorMessage));
+```
+
+**Response shape:**
+
+```json
+{
+  "content": [
+    {
+      "id": "exec_abc123",
+      "toolId": "tool_residence_check",
+      "toolName": "Proof of Residence",
+      "imageBase64": "...",
+      "mimeType": "image/jpeg",
+      "paramValues": null,
+      "answer": "YES",
+      "explanation": "Utility bill dated within 3 months.",
+      "booleanAnswer": true,
+      "status": "SUCCESS",
+      "processingTimeMs": 1240,
+      "createdAt": "2026-04-13T10:00:00Z"
+    }
+  ],
+  "totalElements": 42,
+  "totalPages": 3,
+  "size": 20,
+  "number": 0,
+  "first": true,
+  "last": false,
+  "empty": false
+}
+```
+
+---
+
 ### Credits & Analytics
 
 #### `getCreditsBalance()`
@@ -833,8 +902,25 @@ history.content.forEach((entry) => {
 
 > Requires a **Pro or higher** plan. The plan determines the maximum number of sub-users allowed.
 
-Sub-users can log in to the web app and operate within the permissions you grant them.  
-Available permissions: `"upload"` · `"view"` · `"template"` · `"settings"` · `"export"` · `"api"`
+Sub-users can log in to the web app and operate within the permissions you grant them.
+
+**Available permissions:**
+
+| Permission     | What it grants                                       |
+| -------------- | ---------------------------------------------------- |
+| `"upload"`     | Upload and process new documents                     |
+| `"view"`       | View all documents owned by the account              |
+| `"template"`   | Create and edit form templates                       |
+| `"settings"`   | View and edit account settings                       |
+| `"export"`     | Export documents to CSV / Excel / JSON               |
+| `"api"`        | Use the public API with their own API key            |
+| `"ocr_tools"`  | Access the AI Agents / OCR Tools feature             |
+| `"gallery"`    | Browse and clone templates from the public gallery   |
+| `"smart_scan"` | Use the Smart Scan camera capture flow               |
+| `"ia_agent"`   | Use the IA Agent for intelligent document extraction |
+| `"assistant"`  | Use the built-in AI chatbot assistant                |
+
+**`allowedFormIds`** (optional): restrict which form templates the sub-user can access. Pass `null` or omit to grant access to all templates.
 
 ### Document History
 
@@ -862,13 +948,29 @@ const users = await getSubUsers();
 ```js
 import { createSubUser } from "extractia-sdk";
 
+// Basic — access to all templates
 const sub = await createSubUser({
   username: "agent_carlos",
   password: "SecurePass1",
+  permissions: ["upload", "view", "ocr_tools"],
+});
+
+// Restricted to specific templates only
+const restricted = await createSubUser({
+  username: "agent_maria",
+  password: "SecurePass2",
   permissions: ["upload", "view"],
+  allowedFormIds: ["tpl_invoices", "tpl_receipts"], // null = all templates
 });
 ```
 
+| Parameter        | Type       | Required | Description                                         |
+| ---------------- | ---------- | -------- | --------------------------------------------------- |
+| `username`       | `string`   | ✅       | Must not be an existing account email               |
+| `password`       | `string`   | ✅       | Must differ from the owner's password               |
+| `permissions`    | `string[]` | ✅       | See permissions table above                         |
+| `allowedFormIds` | `string[]` | —        | Template IDs accessible to this sub-user (null = all) |
+
 **Error codes:**
 | Code | Reason |
 |------|--------|
@@ -876,16 +978,31 @@ const sub = await createSubUser({
 | `409` | Username already in use |
 | `400` | Missing fields or password matches the main account |
 
-### Update Permissions or Password
+### Update Permissions, Template Access, or Password
 
-Only the fields you include are changed. Omit `password` to keep it unchanged.
+Only the fields you include are changed. Omit any field to leave it unchanged.
 
 ```js
 import { updateSubUser } from "extractia-sdk";
 
+// Change permissions
 await updateSubUser("agent_carlos", {
-  permissions: ["upload", "view", "export"],
-  // password: 'NewPass99',   ← optional
+  permissions: ["upload", "view", "export", "ocr_tools"],
+});
+
+// Restrict to specific templates
+await updateSubUser("agent_carlos", {
+  allowedFormIds: ["tpl_invoices"],
+});
+
+// Remove template restriction (grant access to all)
+await updateSubUser("agent_carlos", {
+  allowedFormIds: null,
+});
+
+// Change password only
+await updateSubUser("agent_carlos", {
+  password: "NewPass99",
 });
 ```
 
@@ -914,15 +1031,36 @@ console.log(state.suspended); // true | false
 
 The SDK ships with a full `index.d.ts` declaration file — no `@types` package needed.
 
+**Key exported types:**
+
+| Type                  | Description                                              |
+| --------------------- | -------------------------------------------------------- |
+| `FormTemplate`        | A template with `id`, `label`, `fields`, `userId`        |
+| `FormField`           | A single field: `label`, `type`, `required`, `listLabel` |
+| `UserDocument`        | A processed document with `rawJson`, `createdAt`, etc.   |
+| `OcrToolConfig`       | An OCR agent configuration                               |
+| `OcrRunResult`        | Result of `runOcrTool`: `answer` + `explanation`         |
+| `OcrToolExecution`    | A single execution record from `getOcrToolExecutions`    |
+| `OcrExecutionPage`    | Paginated response of `OcrToolExecution` records         |
+| `SubUser`             | Sub-user with `username`, `permissions`, `allowedFormIds`, `suspended` |
+| `AppUserProfile`      | User profile with quota, plan, and settings fields       |
+| `DocumentAuditEntry`  | An entry from `getDocumentHistory`                       |
+| `ExtractiaError`      | Base error class with `status`, `code`, `userMessage`    |
+
 ```ts
 import {
   setToken,
   processImage,
   runOcrTool,
+  getOcrToolExecutions,
+  createSubUser,
   suggestFields,
   exportDocumentsJson,
   UserDocument,
   OcrRunResult,
+  OcrToolExecution,
+  OcrExecutionPage,
+  SubUser,
   FormField,
   TierError,
   RateLimitError,
@@ -948,6 +1086,18 @@ async function classifyAndExtract(
   // Extract with template
   return processImage(templateId, base64);
 }
+
+// Typed execution history
+const page: OcrExecutionPage = await getOcrToolExecutions({ size: 5 });
+const recent: OcrToolExecution[] = page.content;
+
+// Typed sub-user with allowedFormIds
+const sub: SubUser = await createSubUser({
+  username: "agent_ts",
+  password: "Secure1!",
+  permissions: ["upload", "view", "ocr_tools"],
+  allowedFormIds: ["tpl_invoices"],
+});
 ```
 
 ---
@@ -968,6 +1118,13 @@ Purchase extra document packs or upgrade your plan from the dashboard to continu
 
 ## Changelog
 
+### v1.5.0
+
+- **New:** `getOcrToolExecutions(opts?)` — paginated execution history for AI Agent runs, including the original image, answer, explanation, status, and processing time. Filterable by `toolId`.
+- **New:** `createSubUser` and `updateSubUser` now support `allowedFormIds` — restrict which form templates a sub-user can access (`null` = all templates).
+- **Expanded:** Sub-user permissions updated from 6 to 11: added `"ocr_tools"`, `"gallery"`, `"smart_scan"`, `"ia_agent"`, `"assistant"`.
+- **New TypeScript types:** `OcrToolExecution`, `OcrExecutionPage` interfaces; `SubUser` updated with `allowedFormIds` and all 11 permissions.
+
 ### v1.2.0
 
 - **New:** `getDocumentHistory(opts?)` — paginated log of all document processing events (successes and failures)