extractia-sdk 1.4.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)

package/dist/extractia-sdk.browser.js

@@ -2785,7 +2785,10 @@ var ExtractiaSDK = (() => {
         const fields = (_b = body == null ? void 0 : body.fields) != null ? _b : Array.isArray(body == null ? void 0 : body.fieldErrors) ? Object.fromEntries(
           body.fieldErrors.map((f) => {
             var _a2;
-            return [f.field, (_a2 = f.message) != null ? _a2 : f.defaultMessage];
+            return [
+              f.field,
+              (_a2 = f.message) != null ? _a2 : f.defaultMessage
+            ];
           })
         ) : null;
         error = new ValidationError(detail != null ? detail : STATUS_MESSAGES[400], fields);
@@ -2813,12 +2816,18 @@ var ExtractiaSDK = (() => {
       case 429: {
         const retryAfterHeader = (_c = err.response.headers) == null ? void 0 : _c["retry-after"];
         const retryAfter = retryAfterHeader != null ? parseInt(retryAfterHeader, 10) : null;
-        error = new RateLimitError(detail != null ? detail : void 0, isNaN(retryAfter) ? null : retryAfter);
+        error = new RateLimitError(
+          detail != null ? detail : void 0,
+          isNaN(retryAfter) ? null : retryAfter
+        );
         break;
       }
       default:
         if (status >= 500) {
-          error = new ServerError((_d = detail != null ? detail : STATUS_MESSAGES[status]) != null ? _d : STATUS_MESSAGES[500], status);
+          error = new ServerError(
+            (_d = detail != null ? detail : STATUS_MESSAGES[status]) != null ? _d : STATUS_MESSAGES[500],
+            status
+          );
         } else {
           error = new ExtractiaError(
             detail != null ? detail : err.message,
@@ -3137,6 +3146,7 @@ var ExtractiaSDK = (() => {
   __export(ocrTools_exports, {
     createOcrTool: () => createOcrTool,
     deleteOcrTool: () => deleteOcrTool,
+    getOcrToolExecutions: () => getOcrToolExecutions,
     getOcrTools: () => getOcrTools,
     runOcrTool: () => runOcrTool,
     updateOcrTool: () => updateOcrTool
@@ -3165,6 +3175,16 @@ var ExtractiaSDK = (() => {
     const res = await apiClient_default.post(`/ocr-tools/${id}/run`, body);
     return res.data;
   }
+  async function getOcrToolExecutions({
+    toolId,
+    page = 0,
+    size = 20
+  } = {}) {
+    const params = { page, size };
+    if (toolId) params.toolId = toolId;
+    const res = await apiClient_default.get("/ocr-tools/executions", { params });
+    return res.data;
+  }
 
   // src/subusers.js
   var subusers_exports = {};
@@ -3239,16 +3259,18 @@ var ExtractiaSDK = (() => {
       );
       reader.onerror = () => {
         var _a;
-        return reject(new Error(`fileToBase64: failed to read file "${(_a = file.name) != null ? _a : "unknown"}".`));
+        return reject(
+          new Error(
+            `fileToBase64: failed to read file "${(_a = file.name) != null ? _a : "unknown"}".`
+          )
+        );
       };
       reader.readAsDataURL(file);
     });
   }
   function stripDataUrlPrefix(base64OrDataUrl) {
     if (typeof base64OrDataUrl !== "string") {
-      throw new TypeError(
-        "stripDataUrlPrefix: argument must be a string."
-      );
+      throw new TypeError("stripDataUrlPrefix: argument must be a string.");
     }
     const idx = base64OrDataUrl.indexOf(";base64,");
     return idx !== -1 ? base64OrDataUrl.slice(idx + 8) : base64OrDataUrl;

package/dist/extractia-sdk.cjs.js

@@ -122,6 +122,7 @@ __export(index_exports, {
   getDocumentsByTemplateId: () => getDocumentsByTemplateId,
   getMimeType: () => getMimeType,
   getMyProfile: () => getMyProfile,
+  getOcrToolExecutions: () => getOcrToolExecutions,
   getOcrTools: () => getOcrTools,
   getRecentDocuments: () => getRecentDocuments,
   getSubUsers: () => getSubUsers,
@@ -2849,7 +2850,10 @@ function mapAxiosError(err) {
       const fields = (_b = body == null ? void 0 : body.fields) != null ? _b : Array.isArray(body == null ? void 0 : body.fieldErrors) ? Object.fromEntries(
         body.fieldErrors.map((f) => {
           var _a2;
-          return [f.field, (_a2 = f.message) != null ? _a2 : f.defaultMessage];
+          return [
+            f.field,
+            (_a2 = f.message) != null ? _a2 : f.defaultMessage
+          ];
         })
       ) : null;
       error = new ValidationError(detail != null ? detail : STATUS_MESSAGES[400], fields);
@@ -2877,12 +2881,18 @@ function mapAxiosError(err) {
     case 429: {
       const retryAfterHeader = (_c = err.response.headers) == null ? void 0 : _c["retry-after"];
       const retryAfter = retryAfterHeader != null ? parseInt(retryAfterHeader, 10) : null;
-      error = new RateLimitError(detail != null ? detail : void 0, isNaN(retryAfter) ? null : retryAfter);
+      error = new RateLimitError(
+        detail != null ? detail : void 0,
+        isNaN(retryAfter) ? null : retryAfter
+      );
       break;
     }
     default:
       if (status >= 500) {
-        error = new ServerError((_d = detail != null ? detail : STATUS_MESSAGES[status]) != null ? _d : STATUS_MESSAGES[500], status);
+        error = new ServerError(
+          (_d = detail != null ? detail : STATUS_MESSAGES[status]) != null ? _d : STATUS_MESSAGES[500],
+          status
+        );
       } else {
         error = new ExtractiaError(
           detail != null ? detail : err.message,
@@ -3201,6 +3211,7 @@ var ocrTools_exports = {};
 __export(ocrTools_exports, {
   createOcrTool: () => createOcrTool,
   deleteOcrTool: () => deleteOcrTool,
+  getOcrToolExecutions: () => getOcrToolExecutions,
   getOcrTools: () => getOcrTools,
   runOcrTool: () => runOcrTool,
   updateOcrTool: () => updateOcrTool
@@ -3229,6 +3240,16 @@ async function runOcrTool(id, base64Image, options = {}) {
   const res = await apiClient_default.post(`/ocr-tools/${id}/run`, body);
   return res.data;
 }
+async function getOcrToolExecutions({
+  toolId,
+  page = 0,
+  size = 20
+} = {}) {
+  const params = { page, size };
+  if (toolId) params.toolId = toolId;
+  const res = await apiClient_default.get("/ocr-tools/executions", { params });
+  return res.data;
+}
 
 // src/subusers.js
 var subusers_exports = {};
@@ -3303,16 +3324,18 @@ function fileToBase64(file) {
     );
     reader.onerror = () => {
       var _a;
-      return reject(new Error(`fileToBase64: failed to read file "${(_a = file.name) != null ? _a : "unknown"}".`));
+      return reject(
+        new Error(
+          `fileToBase64: failed to read file "${(_a = file.name) != null ? _a : "unknown"}".`
+        )
+      );
     };
     reader.readAsDataURL(file);
   });
 }
 function stripDataUrlPrefix(base64OrDataUrl) {
   if (typeof base64OrDataUrl !== "string") {
-    throw new TypeError(
-      "stripDataUrlPrefix: argument must be a string."
-    );
+    throw new TypeError("stripDataUrlPrefix: argument must be a string.");
   }
   const idx = base64OrDataUrl.indexOf(";base64,");
   return idx !== -1 ? base64OrDataUrl.slice(idx + 8) : base64OrDataUrl;

package/dist/extractia-sdk.esm.js

@@ -2767,7 +2767,10 @@ function mapAxiosError(err) {
       const fields = (_b = body == null ? void 0 : body.fields) != null ? _b : Array.isArray(body == null ? void 0 : body.fieldErrors) ? Object.fromEntries(
         body.fieldErrors.map((f) => {
           var _a2;
-          return [f.field, (_a2 = f.message) != null ? _a2 : f.defaultMessage];
+          return [
+            f.field,
+            (_a2 = f.message) != null ? _a2 : f.defaultMessage
+          ];
         })
       ) : null;
       error = new ValidationError(detail != null ? detail : STATUS_MESSAGES[400], fields);
@@ -2795,12 +2798,18 @@ function mapAxiosError(err) {
     case 429: {
       const retryAfterHeader = (_c = err.response.headers) == null ? void 0 : _c["retry-after"];
       const retryAfter = retryAfterHeader != null ? parseInt(retryAfterHeader, 10) : null;
-      error = new RateLimitError(detail != null ? detail : void 0, isNaN(retryAfter) ? null : retryAfter);
+      error = new RateLimitError(
+        detail != null ? detail : void 0,
+        isNaN(retryAfter) ? null : retryAfter
+      );
       break;
     }
     default:
       if (status >= 500) {
-        error = new ServerError((_d = detail != null ? detail : STATUS_MESSAGES[status]) != null ? _d : STATUS_MESSAGES[500], status);
+        error = new ServerError(
+          (_d = detail != null ? detail : STATUS_MESSAGES[status]) != null ? _d : STATUS_MESSAGES[500],
+          status
+        );
       } else {
         error = new ExtractiaError(
           detail != null ? detail : err.message,
@@ -3119,6 +3128,7 @@ var ocrTools_exports = {};
 __export(ocrTools_exports, {
   createOcrTool: () => createOcrTool,
   deleteOcrTool: () => deleteOcrTool,
+  getOcrToolExecutions: () => getOcrToolExecutions,
   getOcrTools: () => getOcrTools,
   runOcrTool: () => runOcrTool,
   updateOcrTool: () => updateOcrTool
@@ -3147,6 +3157,16 @@ async function runOcrTool(id, base64Image, options = {}) {
   const res = await apiClient_default.post(`/ocr-tools/${id}/run`, body);
   return res.data;
 }
+async function getOcrToolExecutions({
+  toolId,
+  page = 0,
+  size = 20
+} = {}) {
+  const params = { page, size };
+  if (toolId) params.toolId = toolId;
+  const res = await apiClient_default.get("/ocr-tools/executions", { params });
+  return res.data;
+}
 
 // src/subusers.js
 var subusers_exports = {};
@@ -3221,16 +3241,18 @@ function fileToBase64(file) {
     );
     reader.onerror = () => {
       var _a;
-      return reject(new Error(`fileToBase64: failed to read file "${(_a = file.name) != null ? _a : "unknown"}".`));
+      return reject(
+        new Error(
+          `fileToBase64: failed to read file "${(_a = file.name) != null ? _a : "unknown"}".`
+        )
+      );
     };
     reader.readAsDataURL(file);
   });
 }
 function stripDataUrlPrefix(base64OrDataUrl) {
   if (typeof base64OrDataUrl !== "string") {
-    throw new TypeError(
-      "stripDataUrlPrefix: argument must be a string."
-    );
+    throw new TypeError("stripDataUrlPrefix: argument must be a string.");
   }
   const idx = base64OrDataUrl.indexOf(";base64,");
   return idx !== -1 ? base64OrDataUrl.slice(idx + 8) : base64OrDataUrl;
@@ -3358,6 +3380,7 @@ export {
   getDocumentsByTemplateId,
   getMimeType,
   getMyProfile,
+  getOcrToolExecutions,
   getOcrTools,
   getRecentDocuments,
   getSubUsers,

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// ─── Extractia SDK v1.1 — TypeScript type declarations ───────────────────────
+// ─── Extractia SDK v1.5 — TypeScript type declarations ───────────────────────
 // Keep in sync with JavaScript source files.
 
 // ─── Primitives ───────────────────────────────────────────────────────────────
@@ -111,8 +111,14 @@ export interface DocumentAuditEntry {
 /** A sub-user belonging to an account. */
 export interface SubUser {
   username: string;
-  /** Granted permission strings (e.g. "upload", "view", "template", "settings", "export", "api"). */
+  /**
+   * Granted permission strings.
+   * Valid values: `"upload"`, `"view"`, `"template"`, `"settings"`, `"export"`, `"api"`,
+   * `"ocr_tools"`, `"gallery"`, `"smart_scan"`, `"ia_agent"`, `"assistant"`.
+   */
   permissions: string[];
+  /** Optional list of form template IDs this sub-user may access. Null = access to all. */
+  allowedFormIds?: string[] | null;
   /** Whether the sub-user is currently suspended. */
   suspended: boolean;
   /** Last known geographic location ("lat,lng" format). */
@@ -202,6 +208,47 @@ export interface OcrRunResult {
   explanation: string;
 }
 
+/** A single AI Agent execution record stored in `ocr_tool_executions`. */
+export interface OcrToolExecution {
+  id: string;
+  toolId: string;
+  /** Snapshot of the tool name at execution time. */
+  toolName: string;
+  /** Original image encoded as base64 (with or without data-URL prefix). */
+  imageBase64: string;
+  mimeType: string;
+  /** Dynamic parameter values supplied at run time, keyed 1-based (e.g. `{ "1": "Main St" }`). */
+  paramValues?: Record<string, string> | null;
+  /** AI answer text (YES/NO, label, or free-form text). */
+  answer: string;
+  /** Short rationale explaining the answer. */
+  explanation: string;
+  /** Parsed boolean for `YES_NO` tools; `null` for `LABEL` and `TEXT` tools. */
+  booleanAnswer: boolean | null;
+  /** `"SUCCESS"` or `"FAILURE"`. */
+  status: 'SUCCESS' | 'FAILURE';
+  /** Error message when `status` is `"FAILURE"`. */
+  errorMessage?: string;
+  /** Wall-clock time in milliseconds for the AI provider call. */
+  processingTimeMs?: number;
+  /** ISO 8601 UTC timestamp. */
+  createdAt: string;
+}
+
+/** Spring-style paginated response wrapping a list of {@link OcrToolExecution} records. */
+export interface OcrExecutionPage {
+  content: OcrToolExecution[];
+  totalElements: number;
+  totalPages: number;
+  /** Applied page size. */
+  size: number;
+  /** 0-based page index. */
+  number: number;
+  first: boolean;
+  last: boolean;
+  empty: boolean;
+}
+
 // ─── Error classes ────────────────────────────────────────────────────────────
 
 /** Base error class for all Extractia SDK errors. */
@@ -730,6 +777,24 @@ export function deleteOcrTool(id: string): Promise<void>;
  */
 export function runOcrTool(id: string, base64Image: string, options?: OcrRunOptions): Promise<OcrRunResult>;
 
+/**
+ * Returns a paginated list of OCR tool execution history for the authenticated user.
+ *
+ * Each record includes the original image, answer, explanation, and run metadata.
+ * Keep page sizes small when rendering image thumbnails.
+ *
+ * @param options.toolId Filter by tool ID. Omit to return executions for all tools.
+ * @param options.page   0-based page index (default `0`).
+ * @param options.size   Page size, 1–50 (default `20`; values above 50 are capped server-side).
+ *
+ * @throws {AuthError} 401 if the user is not authenticated.
+ */
+export function getOcrToolExecutions(options?: {
+  toolId?: string;
+  page?: number;
+  size?: number;
+}): Promise<OcrExecutionPage>;
+
 // ─── Sub-Users ────────────────────────────────────────────────────────────────
 
 /**
@@ -741,7 +806,8 @@ export function getSubUsers(): Promise<SubUser[]>;
 /**
  * Creates a new sub-user.
  *
- * Available permissions: `"upload"`, `"view"`, `"template"`, `"settings"`, `"export"`, `"api"`.
+ * Available permissions: `"upload"`, `"view"`, `"template"`, `"settings"`, `"export"`, `"api"`,
+ * `"ocr_tools"`, `"gallery"`, `"smart_scan"`, `"ia_agent"`, `"assistant"`.
  *
  * @throws {ForbiddenError} 403 if the plan does not support sub-users or the limit is reached.
  * @throws {ExtractiaError} 409 if the username is already taken.
@@ -750,14 +816,17 @@ export function getSubUsers(): Promise<SubUser[]>;
  * await createSubUser({
  *   username: 'agent_bob',
  *   password: 'SecurePass1',
- *   permissions: ['upload', 'view'],
+ *   permissions: ['upload', 'view', 'ocr_tools'],
+ *   allowedFormIds: ['tpl_123'],  // optional — omit for access to all forms
  * });
  */
 export function createSubUser(subUser: {
   username: string;
   password: string;
   permissions: string[];
-}): Promise<{ username: string; permissions: string[] }>;
+  /** Restrict this sub-user to specific form templates. Omit or pass null for all forms. */
+  allowedFormIds?: string[] | null;
+}): Promise<{ username: string; permissions: string[]; allowedFormIds?: string[] | null }>;
 
 /**
  * Deletes a sub-user by username.
@@ -767,7 +836,7 @@ export function createSubUser(subUser: {
 export function deleteSubUser(username: string): Promise<{ deleted: string }>;
 
 /**
- * Updates the permissions and/or password of a sub-user.
+ * Updates the permissions, allowed forms, and/or password of a sub-user.
  * Only the provided fields are changed.
  *
  * @param username The sub-user's username.
@@ -776,7 +845,12 @@ export function deleteSubUser(username: string): Promise<{ deleted: string }>;
  */
 export function updateSubUser(
   username: string,
-  updates: { permissions?: string[]; password?: string }
+  updates: {
+    permissions?: string[];
+    password?: string;
+    /** New allowed form ID list (replaces existing). Pass empty array to remove all restrictions. */
+    allowedFormIds?: string[] | null;
+  }
 ): Promise<{ username: string; updated: boolean }>;
 
 /**
@@ -907,6 +981,7 @@ declare const extractia: {
   updateOcrTool: typeof updateOcrTool;
   deleteOcrTool: typeof deleteOcrTool;
   runOcrTool: typeof runOcrTool;
+  getOcrToolExecutions: typeof getOcrToolExecutions;
   // Sub-users
   getSubUsers: typeof getSubUsers;
   createSubUser: typeof createSubUser;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extractia-sdk",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "JavaScript SDK for the ExtractIA API — document extraction, OCR tools, AI summaries, templates & more",
   "type": "module",
   "author": "ExtractIA Team",
@@ -49,7 +49,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "test:ui": "vitest --ui"
+    "test:ui": "vitest --ui",
+    "test:integration": "vitest run --config vitest.integration.config.js"
   },
   "dependencies": {
     "axios": "^1.10.0"

package/src/apiClient.js

@@ -194,7 +194,10 @@ export function configure(opts = {}) {
   if (opts.retryDelay != null) _config.retryDelay = opts.retryDelay;
   if (opts.debug != null) _config.debug = Boolean(opts.debug);
   if (opts.defaultHeaders) {
-    _config.defaultHeaders = { ..._config.defaultHeaders, ...opts.defaultHeaders };
+    _config.defaultHeaders = {
+      ..._config.defaultHeaders,
+      ...opts.defaultHeaders,
+    };
   }
   if (opts.onBeforeRequest) _config.onBeforeRequest = opts.onBeforeRequest;
   if (opts.onAfterResponse) _config.onAfterResponse = opts.onAfterResponse;

package/src/errors.js

@@ -32,12 +32,7 @@ export class ExtractiaError extends Error {
    * @param {string} [userMessage] — Human-friendly sentence shown to end users.
    * @param {string} [code]     — Machine-readable error code.
    */
-  constructor(
-    message,
-    status = 0,
-    userMessage = null,
-    code = "SDK_ERROR",
-  ) {
+  constructor(message, status = 0, userMessage = null, code = "SDK_ERROR") {
     super(message);
     this.name = "ExtractiaError";
     this.status = status;
@@ -140,10 +135,7 @@ export class ValidationError extends ExtractiaError {
    * @param {string}                    [message]
    * @param {Record<string,string>|null} [fields] — Field-level errors, if the server provides them.
    */
-  constructor(
-    message = STATUS_MESSAGES[400],
-    fields = null,
-  ) {
+  constructor(message = STATUS_MESSAGES[400], fields = null) {
     super(message, 400, STATUS_MESSAGES[400], "VALIDATION_ERROR");
     this.name = "ValidationError";
     /** @type {Record<string,string>|null} */
@@ -256,7 +248,9 @@ export function mapAxiosError(err) {
   const detail = extractServerDetail(err.response.data);
   const userMessage =
     STATUS_MESSAGES[status] ??
-    (status >= 500 ? STATUS_MESSAGES[500] : "Something went wrong. Please try again.");
+    (status >= 500
+      ? STATUS_MESSAGES[500]
+      : "Something went wrong. Please try again.");
 
   let error;
 
@@ -268,7 +262,10 @@ export function mapAxiosError(err) {
         body?.fields ??
         (Array.isArray(body?.fieldErrors)
           ? Object.fromEntries(
-              body.fieldErrors.map((f) => [f.field, f.message ?? f.defaultMessage]),
+              body.fieldErrors.map((f) => [
+                f.field,
+                f.message ?? f.defaultMessage,
+              ]),
             )
           : null);
       error = new ValidationError(detail ?? STATUS_MESSAGES[400], fields);
@@ -303,12 +300,18 @@ export function mapAxiosError(err) {
       const retryAfterHeader = err.response.headers?.["retry-after"];
       const retryAfter =
         retryAfterHeader != null ? parseInt(retryAfterHeader, 10) : null;
-      error = new RateLimitError(detail ?? undefined, isNaN(retryAfter) ? null : retryAfter);
+      error = new RateLimitError(
+        detail ?? undefined,
+        isNaN(retryAfter) ? null : retryAfter,
+      );
       break;
     }
     default:
       if (status >= 500) {
-        error = new ServerError(detail ?? STATUS_MESSAGES[status] ?? STATUS_MESSAGES[500], status);
+        error = new ServerError(
+          detail ?? STATUS_MESSAGES[status] ?? STATUS_MESSAGES[500],
+          status,
+        );
       } else {
         error = new ExtractiaError(
           detail ?? err.message,

package/src/index.d.ts

@@ -1,4 +1,4 @@
-// ─── Extractia SDK v1.1 — TypeScript type declarations ───────────────────────
+// ─── Extractia SDK v1.5 — TypeScript type declarations ───────────────────────
 // Keep in sync with JavaScript source files.
 
 // ─── Primitives ───────────────────────────────────────────────────────────────
@@ -111,8 +111,14 @@ export interface DocumentAuditEntry {
 /** A sub-user belonging to an account. */
 export interface SubUser {
   username: string;
-  /** Granted permission strings (e.g. "upload", "view", "template", "settings", "export", "api"). */
+  /**
+   * Granted permission strings.
+   * Valid values: `"upload"`, `"view"`, `"template"`, `"settings"`, `"export"`, `"api"`,
+   * `"ocr_tools"`, `"gallery"`, `"smart_scan"`, `"ia_agent"`, `"assistant"`.
+   */
   permissions: string[];
+  /** Optional list of form template IDs this sub-user may access. Null = access to all. */
+  allowedFormIds?: string[] | null;
   /** Whether the sub-user is currently suspended. */
   suspended: boolean;
   /** Last known geographic location ("lat,lng" format). */
@@ -202,6 +208,47 @@ export interface OcrRunResult {
   explanation: string;
 }
 
+/** A single AI Agent execution record stored in `ocr_tool_executions`. */
+export interface OcrToolExecution {
+  id: string;
+  toolId: string;
+  /** Snapshot of the tool name at execution time. */
+  toolName: string;
+  /** Original image encoded as base64 (with or without data-URL prefix). */
+  imageBase64: string;
+  mimeType: string;
+  /** Dynamic parameter values supplied at run time, keyed 1-based (e.g. `{ "1": "Main St" }`). */
+  paramValues?: Record<string, string> | null;
+  /** AI answer text (YES/NO, label, or free-form text). */
+  answer: string;
+  /** Short rationale explaining the answer. */
+  explanation: string;
+  /** Parsed boolean for `YES_NO` tools; `null` for `LABEL` and `TEXT` tools. */
+  booleanAnswer: boolean | null;
+  /** `"SUCCESS"` or `"FAILURE"`. */
+  status: 'SUCCESS' | 'FAILURE';
+  /** Error message when `status` is `"FAILURE"`. */
+  errorMessage?: string;
+  /** Wall-clock time in milliseconds for the AI provider call. */
+  processingTimeMs?: number;
+  /** ISO 8601 UTC timestamp. */
+  createdAt: string;
+}
+
+/** Spring-style paginated response wrapping a list of {@link OcrToolExecution} records. */
+export interface OcrExecutionPage {
+  content: OcrToolExecution[];
+  totalElements: number;
+  totalPages: number;
+  /** Applied page size. */
+  size: number;
+  /** 0-based page index. */
+  number: number;
+  first: boolean;
+  last: boolean;
+  empty: boolean;
+}
+
 // ─── Error classes ────────────────────────────────────────────────────────────
 
 /** Base error class for all Extractia SDK errors. */
@@ -730,6 +777,24 @@ export function deleteOcrTool(id: string): Promise<void>;
  */
 export function runOcrTool(id: string, base64Image: string, options?: OcrRunOptions): Promise<OcrRunResult>;
 
+/**
+ * Returns a paginated list of OCR tool execution history for the authenticated user.
+ *
+ * Each record includes the original image, answer, explanation, and run metadata.
+ * Keep page sizes small when rendering image thumbnails.
+ *
+ * @param options.toolId Filter by tool ID. Omit to return executions for all tools.
+ * @param options.page   0-based page index (default `0`).
+ * @param options.size   Page size, 1–50 (default `20`; values above 50 are capped server-side).
+ *
+ * @throws {AuthError} 401 if the user is not authenticated.
+ */
+export function getOcrToolExecutions(options?: {
+  toolId?: string;
+  page?: number;
+  size?: number;
+}): Promise<OcrExecutionPage>;
+
 // ─── Sub-Users ────────────────────────────────────────────────────────────────
 
 /**
@@ -741,7 +806,8 @@ export function getSubUsers(): Promise<SubUser[]>;
 /**
  * Creates a new sub-user.
  *
- * Available permissions: `"upload"`, `"view"`, `"template"`, `"settings"`, `"export"`, `"api"`.
+ * Available permissions: `"upload"`, `"view"`, `"template"`, `"settings"`, `"export"`, `"api"`,
+ * `"ocr_tools"`, `"gallery"`, `"smart_scan"`, `"ia_agent"`, `"assistant"`.
  *
  * @throws {ForbiddenError} 403 if the plan does not support sub-users or the limit is reached.
  * @throws {ExtractiaError} 409 if the username is already taken.
@@ -750,14 +816,17 @@ export function getSubUsers(): Promise<SubUser[]>;
  * await createSubUser({
  *   username: 'agent_bob',
  *   password: 'SecurePass1',
- *   permissions: ['upload', 'view'],
+ *   permissions: ['upload', 'view', 'ocr_tools'],
+ *   allowedFormIds: ['tpl_123'],  // optional — omit for access to all forms
  * });
  */
 export function createSubUser(subUser: {
   username: string;
   password: string;
   permissions: string[];
-}): Promise<{ username: string; permissions: string[] }>;
+  /** Restrict this sub-user to specific form templates. Omit or pass null for all forms. */
+  allowedFormIds?: string[] | null;
+}): Promise<{ username: string; permissions: string[]; allowedFormIds?: string[] | null }>;
 
 /**
  * Deletes a sub-user by username.
@@ -767,7 +836,7 @@ export function createSubUser(subUser: {
 export function deleteSubUser(username: string): Promise<{ deleted: string }>;
 
 /**
- * Updates the permissions and/or password of a sub-user.
+ * Updates the permissions, allowed forms, and/or password of a sub-user.
  * Only the provided fields are changed.
  *
  * @param username The sub-user's username.
@@ -776,7 +845,12 @@ export function deleteSubUser(username: string): Promise<{ deleted: string }>;
  */
 export function updateSubUser(
   username: string,
-  updates: { permissions?: string[]; password?: string }
+  updates: {
+    permissions?: string[];
+    password?: string;
+    /** New allowed form ID list (replaces existing). Pass empty array to remove all restrictions. */
+    allowedFormIds?: string[] | null;
+  }
 ): Promise<{ username: string; updated: boolean }>;
 
 /**
@@ -907,6 +981,7 @@ declare const extractia: {
   updateOcrTool: typeof updateOcrTool;
   deleteOcrTool: typeof deleteOcrTool;
   runOcrTool: typeof runOcrTool;
+  getOcrToolExecutions: typeof getOcrToolExecutions;
   // Sub-users
   getSubUsers: typeof getSubUsers;
   createSubUser: typeof createSubUser;

package/src/index.js

@@ -20,12 +20,7 @@ export {
   TimeoutError,
   mapAxiosError,
 } from "./errors.js";
-export {
-  getToken,
-  hasToken,
-  clearToken,
-  getConfig,
-} from "./apiClient.js";
+export { getToken, hasToken, clearToken, getConfig } from "./apiClient.js";
 
 import * as auth from "./auth.js";
 import * as templates from "./templates.js";

package/src/ocrTools.js

@@ -82,3 +82,51 @@ export async function runOcrTool(id, base64Image, options = {}) {
   const res = await api.post(`/ocr-tools/${id}/run`, body);
   return res.data;
 }
+
+/**
+ * Returns a paginated list of OCR tool execution history for the authenticated user.
+ *
+ * Each record contains the original image, the answer, explanation, and metadata about
+ * the run. Image data (`imageBase64`) is included, so pages should be kept small when
+ * rendering thumbnails.
+ *
+ * @param {Object}  [options]          - Query options.
+ * @param {string}  [options.toolId]   - Filter by tool ID. Omit to return executions for all tools.
+ * @param {number}  [options.page=0]   - 0-based page index.
+ * @param {number}  [options.size=20]  - Page size (1–50; values above 50 are capped server-side).
+ * @returns {Promise<{
+ *   content: Array<{
+ *     id: string,
+ *     toolId: string,
+ *     toolName: string,
+ *     imageBase64: string,
+ *     mimeType: string,
+ *     paramValues: Record<string, string> | null,
+ *     answer: string,
+ *     explanation: string,
+ *     booleanAnswer: boolean | null,
+ *     status: 'SUCCESS' | 'FAILURE',
+ *     errorMessage?: string,
+ *     processingTimeMs: number,
+ *     createdAt: string
+ *   }>,
+ *   totalElements: number,
+ *   totalPages: number,
+ *   size: number,
+ *   number: number,
+ *   first: boolean,
+ *   last: boolean,
+ *   empty: boolean
+ * }>}
+ * @throws {AuthError} 401 if the user is not authenticated.
+ */
+export async function getOcrToolExecutions({
+  toolId,
+  page = 0,
+  size = 20,
+} = {}) {
+  const params = { page, size };
+  if (toolId) params.toolId = toolId;
+  const res = await api.get("/ocr-tools/executions", { params });
+  return res.data;
+}

package/src/subusers.js

@@ -26,7 +26,7 @@ export async function getSubUsers() {
  * Creates a new sub-user for the authenticated account.
  *
  * Available permissions: `"upload"`, `"view"`, `"template"`, `"settings"`,
- * `"export"`, `"ocr_tools"`, `"gallery"`, `"smart_scan"`, `"ia_agent"`.
+ * `"export"`, `"api"`, `"ocr_tools"`, `"gallery"`, `"smart_scan"`, `"ia_agent"`, `"assistant"`.
  *
  * @param {Object}    subUser                   - Sub-user definition.
  * @param {string}    subUser.username           - Unique username (must not be an existing account email).

package/src/utils.js

@@ -30,7 +30,11 @@ export function fileToBase64(file) {
     const reader = new FileReader();
     reader.onload = () => resolve(/** @type {string} */ (reader.result));
     reader.onerror = () =>
-      reject(new Error(`fileToBase64: failed to read file "${file.name ?? "unknown"}".`));
+      reject(
+        new Error(
+          `fileToBase64: failed to read file "${file.name ?? "unknown"}".`,
+        ),
+      );
     reader.readAsDataURL(file);
   });
 }
@@ -45,9 +49,7 @@ export function fileToBase64(file) {
  */
 export function stripDataUrlPrefix(base64OrDataUrl) {
   if (typeof base64OrDataUrl !== "string") {
-    throw new TypeError(
-      "stripDataUrlPrefix: argument must be a string.",
-    );
+    throw new TypeError("stripDataUrlPrefix: argument must be a string.");
   }
   const idx = base64OrDataUrl.indexOf(";base64,");
   return idx !== -1 ? base64OrDataUrl.slice(idx + 8) : base64OrDataUrl;
@@ -76,7 +78,9 @@ export function isBase64(str) {
   if (typeof str !== "string" || !str.trim()) return false;
   const raw = stripDataUrlPrefix(str);
   // Must be divisible by 4 and only contain valid base64 characters
-  return raw.length > 0 && raw.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(raw);
+  return (
+    raw.length > 0 && raw.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(raw)
+  );
 }
 
 /**

package/vitest.integration.config.js

@@ -0,0 +1,27 @@
+import { defineConfig } from "vitest/config";
+
+/**
+ * Vitest config for integration tests against the real ExtractIA API.
+ *
+ * Required env vars:
+ *   EXTRACTIA_API_TOKEN     — valid bearer token (all integration tests)
+ *   EXTRACTIA_ALLOW_WRITE   — "true" to enable create/update/delete tests
+ *   EXTRACTIA_ALLOW_CREDITS — "true" to enable tests that consume doc/AI credits
+ *
+ * Run:
+ *   EXTRACTIA_API_TOKEN=sk_xxx EXTRACTIA_ALLOW_WRITE=true EXTRACTIA_ALLOW_CREDITS=true \
+ *     npm run test:integration
+ */
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["tests/integration/**/*.integration.test.js"],
+    // Real HTTP calls — 30 s per test, 30 s for setup/teardown hooks
+    testTimeout: 30_000,
+    hookTimeout: 30_000,
+    // Sequential: avoid hammering the API and triggering rate-limits
+    sequence: { concurrent: false },
+    reporters: ["verbose"],
+  },
+});