extractia-sdk 1.3.0 → 1.5.0

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,49 +208,139 @@ 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. */
 export class ExtractiaError extends Error {
-  /** HTTP status code associated with the error. */
+  /** HTTP status code (0 = no response). */
   status: number;
-  constructor(message: string, status: number);
+  /** Polished, user-facing English sentence always suitable for display. */
+  userMessage: string;
+  /** Machine-readable error code (e.g. "AUTH_ERROR", "QUOTA_EXCEEDED"). */
+  code: string;
+  /** X-Request-Id / X-Correlation-Id from the server response header, when present. */
+  requestId: string | null;
+  constructor(message: string, status?: number, userMessage?: string, code?: string);
+  /** Returns true if automatically retrying the same request may succeed. */
+  isRetryable(): boolean;
+  toJSON(): { name: string; code: string; status: number; message: string; userMessage: string; requestId: string | null };
 }
 
-/** Thrown when the API token is missing or invalid (HTTP 401). */
+/** HTTP 401 — token missing, expired, or malformed. */
 export class AuthError extends ExtractiaError {
   constructor(message?: string);
 }
 
-/** Thrown when the account lacks permission to perform the action (HTTP 403). */
+/** HTTP 403 — authenticated but lacking required permission. */
 export class ForbiddenError extends ExtractiaError {
   constructor(message?: string);
 }
 
-/** Thrown when the active plan does not allow the requested operation (HTTP 402). */
+/** HTTP 402 — plan tier does not include this feature. */
 export class TierError extends ExtractiaError {
   constructor(message?: string, status?: number);
 }
 
-/** Thrown when the API rate limit is exceeded (HTTP 429). */
-export class RateLimitError extends ExtractiaError {
-  /** Seconds to wait before the next request. */
-  retryAfter?: number;
+/** HTTP 402 — document processing quota exhausted for this billing period. */
+export class QuotaError extends ExtractiaError {
   constructor(message?: string);
 }
 
-/** Thrown when a requested resource was not found (HTTP 404). */
+/** HTTP 429 — requests sent too fast. Check `retryAfter` for the suggested wait time. */
+export class RateLimitError extends ExtractiaError {
+  /** Seconds to wait before retrying (from the Retry-After header), or null. */
+  retryAfter: number | null;
+  constructor(message?: string, retryAfter?: number | null);
+  isRetryable(): true;
+}
+
+/** HTTP 404 — the requested resource does not exist. */
 export class NotFoundError extends ExtractiaError {
   constructor(message?: string);
 }
 
+/** HTTP 400 — request body / parameters failed server-side validation. */
+export class ValidationError extends ExtractiaError {
+  /** Field-level errors, if the server provided them. */
+  fields: Record<string, string> | null;
+  constructor(message?: string, fields?: Record<string, string> | null);
+}
+
+/** HTTP 409 — a resource with the same unique identifier already exists. */
+export class ConflictError extends ExtractiaError {
+  constructor(message?: string);
+}
+
+/** HTTP 5xx — unexpected server-side failure. Always retryable. */
+export class ServerError extends ExtractiaError {
+  constructor(message?: string, status?: number);
+  isRetryable(): true;
+}
+
+/** No HTTP response — connection refused, DNS failure, etc. */
+export class NetworkError extends ExtractiaError {
+  constructor(message?: string);
+  isRetryable(): true;
+}
+
+/** Request timed out before the server responded. */
+export class TimeoutError extends ExtractiaError {
+  constructor(message?: string);
+  isRetryable(): true;
+}
+
+/** Maps an Axios error to the appropriate typed SDK error. */
+export function mapAxiosError(err: unknown): ExtractiaError;
+
 // ─── Setup ────────────────────────────────────────────────────────────────────
 
 /**
  * Sets the Bearer API token used for all subsequent requests.
  * **Must be called before any SDK method.**
  *
- * @param token Your Extractia API token (from Account → API Tokens).
+ * @param token Your Extractia API key (from Account → API Tokens).
+ * @throws {Error} If the token is empty or not a string.
  *
  * @example
  * import { setToken } from 'extractia-sdk';
@@ -252,12 +348,59 @@ export class NotFoundError extends ExtractiaError {
  */
 export function setToken(token: string): void;
 
+/** Returns the currently configured API token, or `null` if not set. */
+export function getToken(): string | null;
+
+/** Returns `true` if an API token has been set. */
+export function hasToken(): boolean;
+
+/** Clears the stored API token. Useful for logout flows or test teardown. */
+export function clearToken(): void;
+
+/** Returns a snapshot of the current SDK configuration (token excluded). */
+export function getConfig(): {
+  baseURL: string;
+  timeout: number;
+  retries: number;
+  retryDelay: number;
+  debug: boolean;
+  defaultHeaders: Record<string, string>;
+  onBeforeRequest: Function | null;
+  onAfterResponse: Function | null;
+  onError: Function | null;
+};
+
 /**
- * Configures SDK options.
- * @param opts
- * @param [opts.baseURL] Override the default API base URL (useful for self-hosted instances).
+ * Configures SDK behaviour. All properties are optional.
+ *
+ * @example
+ * configure({
+ *   timeout: 30_000,
+ *   retries: 2,
+ *   debug: true,
+ *   onError: (err) => sentryCapture(err),
+ * });
  */
-export function configure(opts: { baseURL?: string }): void;
+export function configure(opts: {
+  /** Override the API base URL (useful for staging or proxies). */
+  baseURL?: string;
+  /** Request timeout in milliseconds. Default: 60 000. */
+  timeout?: number;
+  /** Automatic retries on retryable errors (429 / 5xx / network). Default: 1. */
+  retries?: number;
+  /** Base delay (ms) between retries; multiplied by attempt number. Default: 1 000. */
+  retryDelay?: number;
+  /** Log requests / responses / retries to console.debug. Default: false. */
+  debug?: boolean;
+  /** Extra headers merged into every request. */
+  defaultHeaders?: Record<string, string>;
+  /** Hook called before each request. Return a modified config or void. */
+  onBeforeRequest?: (config: unknown) => unknown | void;
+  /** Hook called after each successful response. */
+  onAfterResponse?: (response: unknown) => void;
+  /** Hook called with the mapped SDK error whenever a request fails (after retries). */
+  onError?: (error: ExtractiaError) => void;
+}): void;
 
 // ─── Auth / Profile ───────────────────────────────────────────────────────────
 
@@ -634,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 ────────────────────────────────────────────────────────────────
 
 /**
@@ -645,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.
@@ -654,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.
@@ -671,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.
@@ -680,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 }>;
 
 /**
@@ -694,11 +864,87 @@ export function toggleSuspendSubUser(username: string): Promise<{ username: stri
 
 // ─── Default export ───────────────────────────────────────────────────────────
 
+// ─── Utilities ───────────────────────────────────────────────────────────────
+
+/**
+ * Converts a browser `File` or `Blob` to a base64 data-URL string.
+ * @throws {Error} In Node.js environments where `FileReader` is unavailable.
+ */
+export function fileToBase64(file: File | Blob): Promise<string>;
+
+/**
+ * Strips the `data:…;base64,` prefix from a base64 string.
+ * Safe to call on a plain base64 string — returns it unchanged.
+ */
+export function stripDataUrlPrefix(base64OrDataUrl: string): string;
+
+/**
+ * Returns the MIME type embedded in a data-URL prefix, or `null`.
+ * @example getMimeType('data:image/png;base64,...') // → 'image/png'
+ */
+export function getMimeType(dataUrl: string): string | null;
+
+/**
+ * Returns `true` if the string is a valid base64-encoded value
+ * (with or without a data-URL prefix).
+ */
+export function isBase64(str: string): boolean;
+
+/**
+ * Accepts a `File`, `Blob`, or base64 string and always resolves to a
+ * base64 string — the data-URL for files and the string as-is otherwise.
+ */
+export function ensureBase64(fileOrBase64: File | Blob | string): Promise<string>;
+
+/**
+ * Async generator that yields individual items across all pages of a
+ * paginated SDK function.
+ *
+ * @example
+ * for await (const entry of paginate(getCreditsHistory, { size: 100 })) {
+ *   console.log(entry);
+ * }
+ */
+export function paginate<T>(
+  fn: (opts: { page: number; size: number }) => Promise<{ content: T[]; totalPages: number }>,
+  opts?: { size?: number; startPage?: number; maxPages?: number }
+): AsyncGenerator<T>;
+
+/**
+ * Collects all pages of a paginated SDK function into a flat array.
+ */
+export function paginateAll<T>(
+  fn: (opts: { page: number; size: number }) => Promise<{ content: T[]; totalPages: number }>,
+  opts?: { size?: number; startPage?: number; maxPages?: number }
+): Promise<T[]>;
+
+/** Returns a Promise that resolves after `ms` milliseconds. */
+export function delay(ms: number): Promise<void>;
+
+/**
+ * Calls an async function and retries it with exponential back-off on
+ * retryable `ExtractiaError`s.
+ */
+export function withRetry<T>(
+  fn: () => Promise<T>,
+  opts?: {
+    retries?: number;
+    initialDelay?: number;
+    shouldRetry?: (err: Error) => boolean;
+  }
+): Promise<T>;
+
+// ─── Default export ───────────────────────────────────────────────────────────
+
 /** Namespace object bundling all SDK methods for UMD / CommonJS consumers. */
 declare const extractia: {
   // Setup
   setToken: typeof setToken;
+  getToken: typeof getToken;
+  hasToken: typeof hasToken;
+  clearToken: typeof clearToken;
   configure: typeof configure;
+  getConfig: typeof getConfig;
   // Auth
   getMyProfile: typeof getMyProfile;
   updateWebhook: typeof updateWebhook;
@@ -735,12 +981,23 @@ declare const extractia: {
   updateOcrTool: typeof updateOcrTool;
   deleteOcrTool: typeof deleteOcrTool;
   runOcrTool: typeof runOcrTool;
+  getOcrToolExecutions: typeof getOcrToolExecutions;
   // Sub-users
   getSubUsers: typeof getSubUsers;
   createSubUser: typeof createSubUser;
   deleteSubUser: typeof deleteSubUser;
   updateSubUser: typeof updateSubUser;
   toggleSuspendSubUser: typeof toggleSuspendSubUser;
+  // Utilities
+  fileToBase64: typeof fileToBase64;
+  stripDataUrlPrefix: typeof stripDataUrlPrefix;
+  getMimeType: typeof getMimeType;
+  isBase64: typeof isBase64;
+  ensureBase64: typeof ensureBase64;
+  paginate: typeof paginate;
+  paginateAll: typeof paginateAll;
+  delay: typeof delay;
+  withRetry: typeof withRetry;
 };
 
 export default extractia;

package/src/index.js

@@ -4,14 +4,23 @@ export * from "./documents.js";
 export * from "./analytics.js";
 export * from "./ocrTools.js";
 export * from "./subusers.js";
+export * from "./utils.js";
 export {
   ExtractiaError,
   AuthError,
   ForbiddenError,
   TierError,
+  QuotaError,
   RateLimitError,
   NotFoundError,
+  ValidationError,
+  ConflictError,
+  ServerError,
+  NetworkError,
+  TimeoutError,
+  mapAxiosError,
 } from "./errors.js";
+export { getToken, hasToken, clearToken, getConfig } from "./apiClient.js";
 
 import * as auth from "./auth.js";
 import * as templates from "./templates.js";
@@ -19,6 +28,8 @@ import * as documents from "./documents.js";
 import * as analytics from "./analytics.js";
 import * as ocrTools from "./ocrTools.js";
 import * as subusers from "./subusers.js";
+import * as utils from "./utils.js";
+import { getToken, hasToken, clearToken, getConfig } from "./apiClient.js";
 
 const extractia = {
   ...auth,
@@ -27,6 +38,11 @@ const extractia = {
   ...analytics,
   ...ocrTools,
   ...subusers,
+  ...utils,
+  getToken,
+  hasToken,
+  clearToken,
+  getConfig,
 };
 
 export default extractia;

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).