extractia-sdk 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -81,12 +81,45 @@ export interface AppUserProfile {
   webhook?: string | null;
   /** Number of form templates owned. */
   formTemplatesCount?: number;
-  /** Total documents processed. */
+  /** Total documents processed (lifetime). */
   documentsCount?: number;
+  /** Documents remaining in the current billing cycle (plan quota). */
+  documentsAvailableThisMonth?: number;
+  /** Extra/add-on documents available (purchased separately). */
+  extraDocsAvailable?: number;
   tier?: object;
   subscription?: object;
 }
 
+/** A single document processing audit entry (upload history). */
+export interface DocumentAuditEntry {
+  id?: string;
+  userId: string;
+  templateId?: string | null;
+  templateName?: string | null;
+  /** "SUCCESS" or "FAILURE". */
+  status: string;
+  uploadDate: string;
+  processingTimeMs?: number;
+  /** Number of pages processed. */
+  pages?: number;
+  /** Number of template fields. */
+  fields?: number;
+  errorMessage?: string | null;
+}
+
+/** A sub-user belonging to an account. */
+export interface SubUser {
+  username: string;
+  /** Granted permission strings (e.g. "upload", "view", "template", "settings", "export", "api"). */
+  permissions: string[];
+  /** Whether the sub-user is currently suspended. */
+  suspended: boolean;
+  /** Last known geographic location ("lat,lng" format). */
+  lastKnownLocation?: string | null;
+  lastLocationAt?: string | null;
+}
+
 /** AI credit balance. */
 export interface CreditsBalance {
   monthlyBalance: number;
@@ -117,7 +150,10 @@ export interface OcrToolConfig {
   id?: string;
   /** Human-friendly display name (e.g. "Proof of Residence Check"). */
   name: string;
-  /** Natural-language instruction evaluated against the document image. */
+  /**
+   * Natural-language instruction evaluated against the document image. Max 3 000 characters
+   * (after parameter substitution). May contain {{?1}}, {{?2}}, … placeholders.
+   */
   prompt: string;
   /** Expected output shape. */
   outputType: OcrOutputType;
@@ -126,9 +162,38 @@ export interface OcrToolConfig {
    * List of possible labels the AI must pick from.
    */
   labels?: string[];
+  /**
+   * Dynamic parameter definitions for {{?N}} placeholders in `prompt`.
+   * At run time the caller supplies a value for each placeholder via `runOcrTool` `options.params`.
+   */
+  parameterDefinitions?: OcrParameterDefinition[];
   createdAt?: string;
 }
 
+/** Configuration for a single dynamic {{?N}} placeholder in an OCR tool prompt. */
+export interface OcrParameterDefinition {
+  /** 1-based index matching the {{?N}} placeholder in the prompt. */
+  key: number;
+  /** Human-readable label shown in the UI and used in validation error messages. */
+  label: string;
+  /** Optional hint text displayed to the user when filling in this parameter. */
+  description?: string;
+  /**
+   * Maximum character count for this parameter's value (1–500, default 200).
+   * Affects the total substituted prompt length limit of 3 000 characters.
+   */
+  maxChars?: number;
+}
+
+/** Options accepted by {@link runOcrTool}. */
+export interface OcrRunOptions {
+  /**
+   * Values for {{?N}} placeholders, keyed by the string form of the placeholder index (e.g. `"1"`, `"2"`).
+   * Each value must not exceed the parameter's `maxChars` limit.
+   */
+  params?: Record<string, string>;
+}
+
 /** Result returned after running an OCR tool. */
 export interface OcrRunResult {
   /** The AI's answer (e.g. "YES", "invoice", or free-form text). */
@@ -484,6 +549,27 @@ export function getCreditsHistory(options?: {
   totalElements: number;
 }>;
 
+/**
+ * Returns a paginated history of document processing events
+ * (uploads, OCR tool runs, both successes and failures).
+ *
+ * @param options
+ * @param [options.page=0]  Zero-based page index.
+ * @param [options.size=20] Page size (max 100).
+ *
+ * @example
+ * const history = await getDocumentHistory({ size: 50 });
+ * history.content.forEach(e => console.log(e.templateName, e.status, e.uploadDate));
+ */
+export function getDocumentHistory(options?: {
+  page?: number;
+  size?: number;
+}): Promise<{
+  content: DocumentAuditEntry[];
+  totalPages: number;
+  totalElements: number;
+}>;
+
 // ─── OCR Tools ────────────────────────────────────────────────────────────────
 
 /**
@@ -526,14 +612,85 @@ export function deleteOcrTool(id: string): Promise<void>;
  * The image may include a data-URL prefix (e.g. `data:image/jpeg;base64,...`)
  * or be a plain base64 string. Max image size is 5 MB.
  *
+ * Each run deducts **1 document credit** from the user's quota plus AI credits
+ * based on token usage (`ceil(totalTokens / 1000)` credits).
+ * The AI responds in the same language as the prompt / parameter values.
+ *
  * @param id          OCR tool ID.
  * @param base64Image Base64-encoded image.
+ * @param options     Optional run options, including dynamic parameter values.
+ *
+ * @throws {ExtractiaError} 400 — missing/invalid parameter or prompt too long after substitution.
+ * @throws {TierError}      402 — document quota or AI credits exhausted.
  *
  * @example
  * const result = await runOcrTool('tool_789', base64String);
  * if (result.answer === 'YES') console.log('Proof of residence confirmed');
+ *
+ * // With dynamic parameters:
+ * const result = await runOcrTool('ownership_tool', base64String, {
+ *   params: { "1": "123 Main St", "2": "Jane Doe" }
+ * });
+ */
+export function runOcrTool(id: string, base64Image: string, options?: OcrRunOptions): Promise<OcrRunResult>;
+
+// ─── Sub-Users ────────────────────────────────────────────────────────────────
+
+/**
+ * Returns all sub-users for the authenticated account.
+ * Only available on plans that support sub-users (Pro and above).
+ */
+export function getSubUsers(): Promise<SubUser[]>;
+
+/**
+ * Creates a new sub-user.
+ *
+ * Available permissions: `"upload"`, `"view"`, `"template"`, `"settings"`, `"export"`, `"api"`.
+ *
+ * @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.
+ *
+ * @example
+ * await createSubUser({
+ *   username: 'agent_bob',
+ *   password: 'SecurePass1',
+ *   permissions: ['upload', 'view'],
+ * });
+ */
+export function createSubUser(subUser: {
+  username: string;
+  password: string;
+  permissions: string[];
+}): Promise<{ username: string; permissions: string[] }>;
+
+/**
+ * Deletes a sub-user by username.
+ * @param username The sub-user's username.
+ * @throws {NotFoundError} 404 if the sub-user does not exist.
+ */
+export function deleteSubUser(username: string): Promise<{ deleted: string }>;
+
+/**
+ * Updates the permissions and/or password of a sub-user.
+ * Only the provided fields are changed.
+ *
+ * @param username The sub-user's username.
+ * @param updates  Fields to update.
+ * @throws {NotFoundError} 404 if the sub-user does not exist.
+ */
+export function updateSubUser(
+  username: string,
+  updates: { permissions?: string[]; password?: string }
+): Promise<{ username: string; updated: boolean }>;
+
+/**
+ * Toggles the suspended state of a sub-user.
+ * A suspended sub-user cannot log in until unsuspended.
+ *
+ * @param username The sub-user's username.
+ * @throws {NotFoundError} 404 if the sub-user does not exist.
  */
-export function runOcrTool(id: string, base64Image: string): Promise<OcrRunResult>;
+export function toggleSuspendSubUser(username: string): Promise<{ username: string; suspended: boolean }>;
 
 // ─── Default export ───────────────────────────────────────────────────────────
 
@@ -571,12 +728,19 @@ declare const extractia: {
   // Analytics
   getCreditsBalance: typeof getCreditsBalance;
   getCreditsHistory: typeof getCreditsHistory;
+  getDocumentHistory: typeof getDocumentHistory;
   // OCR Tools
   getOcrTools: typeof getOcrTools;
   createOcrTool: typeof createOcrTool;
   updateOcrTool: typeof updateOcrTool;
   deleteOcrTool: typeof deleteOcrTool;
   runOcrTool: typeof runOcrTool;
+  // Sub-users
+  getSubUsers: typeof getSubUsers;
+  createSubUser: typeof createSubUser;
+  deleteSubUser: typeof deleteSubUser;
+  updateSubUser: typeof updateSubUser;
+  toggleSuspendSubUser: typeof toggleSuspendSubUser;
 };
 
 export default extractia;

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "extractia-sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "JavaScript SDK for the ExtractIA API — document extraction, OCR tools, AI summaries, templates & more",
+  "type": "module",
   "author": "ExtractIA Team",
   "license": "MIT",
   "keywords": [

package/src/analytics.js

@@ -25,3 +25,22 @@ export async function getCreditsHistory({ page = 0, size = 20 } = {}) {
   });
   return res.data;
 }
+
+/**
+ * Returns a paginated history of document processing events (uploads, OCR tool runs, etc.)
+ * for the authenticated user.
+ *
+ * Each entry includes: templateId, templateName, status (SUCCESS | FAILURE),
+ * uploadDate, processingTimeMs, pages, fields, and an optional errorMessage.
+ *
+ * @param {Object} [options]
+ * @param {number} [options.page=0]  - Zero-based page index.
+ * @param {number} [options.size=20] - Page size (max 100).
+ * @returns {Promise<Object>} Spring Page object with `content` array and pagination info.
+ */
+export async function getDocumentHistory({ page = 0, size = 20 } = {}) {
+  const res = await api.get("/me/documents/history", {
+    params: { page, size: Math.min(size, 100) },
+  });
+  return res.data;
+}

package/src/apiClient.js

@@ -1,46 +1,46 @@
-import axios from "axios";
-import { mapAxiosError } from "./errors.js";
-
-let token = null;
-
-const DEFAULT_BASE_URL = "https://www.extractia-api.cat/api/public";
-
-const api = axios.create({
-  baseURL: DEFAULT_BASE_URL,
-  timeout: 60000, // 60s — AI processing can take 10–30s
-});
-
-api.interceptors.request.use((config) => {
-  if (!token) {
-    throw new Error(
-      "API token is required. Call setToken(yourApiToken) before making requests.",
-    );
-  }
-  config.headers.Authorization = `Bearer ${token}`;
-  return config;
-});
-
-api.interceptors.response.use(
-  (response) => response,
-  (err) => Promise.reject(mapAxiosError(err)),
-);
-
-/**
- * Sets the API token used for all subsequent requests.
- * Must be called before any SDK method.
- * @param {string} newToken - Your Extractia API token.
- */
-export function setToken(newToken) {
-  token = newToken;
-}
-
-/**
- * Configures SDK options.
- * @param {object} opts
- * @param {string} [opts.baseURL] - Override the default API base URL.
- */
-export function configure({ baseURL } = {}) {
-  if (baseURL) api.defaults.baseURL = baseURL;
-}
-
-export default api;
+import axios from "axios";
+import { mapAxiosError } from "./errors.js";
+
+let token = null;
+
+const DEFAULT_BASE_URL = "https://api.extractia.info/api/public";
+
+const api = axios.create({
+  baseURL: DEFAULT_BASE_URL,
+  timeout: 60000, // 60s — AI processing can take 10–30s
+});
+
+api.interceptors.request.use((config) => {
+  if (!token) {
+    throw new Error(
+      "API token is required. Call setToken(yourApiToken) before making requests.",
+    );
+  }
+  config.headers.Authorization = `Bearer ${token}`;
+  return config;
+});
+
+api.interceptors.response.use(
+  (response) => response,
+  (err) => Promise.reject(mapAxiosError(err)),
+);
+
+/**
+ * Sets the API token used for all subsequent requests.
+ * Must be called before any SDK method.
+ * @param {string} newToken - Your Extractia API token.
+ */
+export function setToken(newToken) {
+  token = newToken;
+}
+
+/**
+ * Configures SDK options.
+ * @param {object} opts
+ * @param {string} [opts.baseURL] - Override the default API base URL.
+ */
+export function configure({ baseURL } = {}) {
+  if (baseURL) api.defaults.baseURL = baseURL;
+}
+
+export default api;

package/src/browser-entry.js

@@ -1,8 +1,8 @@
-import * as auth from './auth.js';
-import * as templates from './templates.js';
-import * as documents from './documents.js';
-import * as analytics from './analytics.js';
-import * as ocrTools from './ocrTools.js';
+import * as auth from "./auth.js";
+import * as templates from "./templates.js";
+import * as documents from "./documents.js";
+import * as analytics from "./analytics.js";
+import * as ocrTools from "./ocrTools.js";
 
 const extractia = {
   ...auth,

package/src/documents.js

@@ -33,7 +33,9 @@ export async function getDocumentsByTemplateId(templateId, options = {}) {
  */
 export async function getDocumentById(templateId, docId, options = {}) {
   const params = { includeImage: options.includeImage ? 1 : 0 };
-  const res = await api.get(`/templates/${templateId}/documents/${docId}`, { params });
+  const res = await api.get(`/templates/${templateId}/documents/${docId}`, {
+    params,
+  });
   return res.data;
 }
 
@@ -44,7 +46,9 @@ export async function getDocumentById(templateId, docId, options = {}) {
  * @returns {Promise<Object[]>} Array of document projection objects.
  */
 export async function getRecentDocuments(size = 10) {
-  const res = await api.get("/documents/recent", { params: { size: Math.min(size, 50) } });
+  const res = await api.get("/documents/recent", {
+    params: { size: Math.min(size, 50) },
+  });
   return res.data;
 }
 
@@ -67,7 +71,9 @@ export async function deleteDocument(documentId) {
  * @returns {Promise<Object>} The created UserDocument with extracted JSON.
  */
 export async function processImage(templateId, base64Image) {
-  const res = await api.post(`/templates/${templateId}/process`, { image: base64Image });
+  const res = await api.post(`/templates/${templateId}/process`, {
+    image: base64Image,
+  });
   return res.data;
 }
 
@@ -80,7 +86,9 @@ export async function processImage(templateId, base64Image) {
  * @returns {Promise<Object>} The created UserDocument with merged extracted JSON.
  */
 export async function processImagesMultipage(templateId, base64ImagesArray) {
-  const res = await api.post(`/templates/${templateId}/process-multipage`, { images: base64ImagesArray });
+  const res = await api.post(`/templates/${templateId}/process-multipage`, {
+    images: base64ImagesArray,
+  });
   return res.data;
 }
 
@@ -163,7 +171,8 @@ export async function bulkPreconform(ids) {
  */
 export async function exportDocumentsCsv(templateId, options = {}) {
   const params = {};
-  if (options.fields && options.fields.length > 0) params.fields = options.fields.join(",");
+  if (options.fields && options.fields.length > 0)
+    params.fields = options.fields.join(",");
   const res = await api.get(`/templates/${templateId}/documents/export/csv`, {
     params,
     responseType: "text",
@@ -184,4 +193,3 @@ export async function exportDocumentsJson(templateId) {
   const res = await api.get(`/templates/${templateId}/documents/export/json`);
   return res.data;
 }
-

package/src/index.d.ts

@@ -81,12 +81,45 @@ export interface AppUserProfile {
   webhook?: string | null;
   /** Number of form templates owned. */
   formTemplatesCount?: number;
-  /** Total documents processed. */
+  /** Total documents processed (lifetime). */
   documentsCount?: number;
+  /** Documents remaining in the current billing cycle (plan quota). */
+  documentsAvailableThisMonth?: number;
+  /** Extra/add-on documents available (purchased separately). */
+  extraDocsAvailable?: number;
   tier?: object;
   subscription?: object;
 }
 
+/** A single document processing audit entry (upload history). */
+export interface DocumentAuditEntry {
+  id?: string;
+  userId: string;
+  templateId?: string | null;
+  templateName?: string | null;
+  /** "SUCCESS" or "FAILURE". */
+  status: string;
+  uploadDate: string;
+  processingTimeMs?: number;
+  /** Number of pages processed. */
+  pages?: number;
+  /** Number of template fields. */
+  fields?: number;
+  errorMessage?: string | null;
+}
+
+/** A sub-user belonging to an account. */
+export interface SubUser {
+  username: string;
+  /** Granted permission strings (e.g. "upload", "view", "template", "settings", "export", "api"). */
+  permissions: string[];
+  /** Whether the sub-user is currently suspended. */
+  suspended: boolean;
+  /** Last known geographic location ("lat,lng" format). */
+  lastKnownLocation?: string | null;
+  lastLocationAt?: string | null;
+}
+
 /** AI credit balance. */
 export interface CreditsBalance {
   monthlyBalance: number;
@@ -117,7 +150,10 @@ export interface OcrToolConfig {
   id?: string;
   /** Human-friendly display name (e.g. "Proof of Residence Check"). */
   name: string;
-  /** Natural-language instruction evaluated against the document image. */
+  /**
+   * Natural-language instruction evaluated against the document image. Max 3 000 characters
+   * (after parameter substitution). May contain {{?1}}, {{?2}}, … placeholders.
+   */
   prompt: string;
   /** Expected output shape. */
   outputType: OcrOutputType;
@@ -126,9 +162,38 @@ export interface OcrToolConfig {
    * List of possible labels the AI must pick from.
    */
   labels?: string[];
+  /**
+   * Dynamic parameter definitions for {{?N}} placeholders in `prompt`.
+   * At run time the caller supplies a value for each placeholder via `runOcrTool` `options.params`.
+   */
+  parameterDefinitions?: OcrParameterDefinition[];
   createdAt?: string;
 }
 
+/** Configuration for a single dynamic {{?N}} placeholder in an OCR tool prompt. */
+export interface OcrParameterDefinition {
+  /** 1-based index matching the {{?N}} placeholder in the prompt. */
+  key: number;
+  /** Human-readable label shown in the UI and used in validation error messages. */
+  label: string;
+  /** Optional hint text displayed to the user when filling in this parameter. */
+  description?: string;
+  /**
+   * Maximum character count for this parameter's value (1–500, default 200).
+   * Affects the total substituted prompt length limit of 3 000 characters.
+   */
+  maxChars?: number;
+}
+
+/** Options accepted by {@link runOcrTool}. */
+export interface OcrRunOptions {
+  /**
+   * Values for {{?N}} placeholders, keyed by the string form of the placeholder index (e.g. `"1"`, `"2"`).
+   * Each value must not exceed the parameter's `maxChars` limit.
+   */
+  params?: Record<string, string>;
+}
+
 /** Result returned after running an OCR tool. */
 export interface OcrRunResult {
   /** The AI's answer (e.g. "YES", "invoice", or free-form text). */
@@ -484,6 +549,27 @@ export function getCreditsHistory(options?: {
   totalElements: number;
 }>;
 
+/**
+ * Returns a paginated history of document processing events
+ * (uploads, OCR tool runs, both successes and failures).
+ *
+ * @param options
+ * @param [options.page=0]  Zero-based page index.
+ * @param [options.size=20] Page size (max 100).
+ *
+ * @example
+ * const history = await getDocumentHistory({ size: 50 });
+ * history.content.forEach(e => console.log(e.templateName, e.status, e.uploadDate));
+ */
+export function getDocumentHistory(options?: {
+  page?: number;
+  size?: number;
+}): Promise<{
+  content: DocumentAuditEntry[];
+  totalPages: number;
+  totalElements: number;
+}>;
+
 // ─── OCR Tools ────────────────────────────────────────────────────────────────
 
 /**
@@ -526,14 +612,85 @@ export function deleteOcrTool(id: string): Promise<void>;
  * The image may include a data-URL prefix (e.g. `data:image/jpeg;base64,...`)
  * or be a plain base64 string. Max image size is 5 MB.
  *
+ * Each run deducts **1 document credit** from the user's quota plus AI credits
+ * based on token usage (`ceil(totalTokens / 1000)` credits).
+ * The AI responds in the same language as the prompt / parameter values.
+ *
  * @param id          OCR tool ID.
  * @param base64Image Base64-encoded image.
+ * @param options     Optional run options, including dynamic parameter values.
+ *
+ * @throws {ExtractiaError} 400 — missing/invalid parameter or prompt too long after substitution.
+ * @throws {TierError}      402 — document quota or AI credits exhausted.
  *
  * @example
  * const result = await runOcrTool('tool_789', base64String);
  * if (result.answer === 'YES') console.log('Proof of residence confirmed');
+ *
+ * // With dynamic parameters:
+ * const result = await runOcrTool('ownership_tool', base64String, {
+ *   params: { "1": "123 Main St", "2": "Jane Doe" }
+ * });
+ */
+export function runOcrTool(id: string, base64Image: string, options?: OcrRunOptions): Promise<OcrRunResult>;
+
+// ─── Sub-Users ────────────────────────────────────────────────────────────────
+
+/**
+ * Returns all sub-users for the authenticated account.
+ * Only available on plans that support sub-users (Pro and above).
+ */
+export function getSubUsers(): Promise<SubUser[]>;
+
+/**
+ * Creates a new sub-user.
+ *
+ * Available permissions: `"upload"`, `"view"`, `"template"`, `"settings"`, `"export"`, `"api"`.
+ *
+ * @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.
+ *
+ * @example
+ * await createSubUser({
+ *   username: 'agent_bob',
+ *   password: 'SecurePass1',
+ *   permissions: ['upload', 'view'],
+ * });
+ */
+export function createSubUser(subUser: {
+  username: string;
+  password: string;
+  permissions: string[];
+}): Promise<{ username: string; permissions: string[] }>;
+
+/**
+ * Deletes a sub-user by username.
+ * @param username The sub-user's username.
+ * @throws {NotFoundError} 404 if the sub-user does not exist.
+ */
+export function deleteSubUser(username: string): Promise<{ deleted: string }>;
+
+/**
+ * Updates the permissions and/or password of a sub-user.
+ * Only the provided fields are changed.
+ *
+ * @param username The sub-user's username.
+ * @param updates  Fields to update.
+ * @throws {NotFoundError} 404 if the sub-user does not exist.
+ */
+export function updateSubUser(
+  username: string,
+  updates: { permissions?: string[]; password?: string }
+): Promise<{ username: string; updated: boolean }>;
+
+/**
+ * Toggles the suspended state of a sub-user.
+ * A suspended sub-user cannot log in until unsuspended.
+ *
+ * @param username The sub-user's username.
+ * @throws {NotFoundError} 404 if the sub-user does not exist.
  */
-export function runOcrTool(id: string, base64Image: string): Promise<OcrRunResult>;
+export function toggleSuspendSubUser(username: string): Promise<{ username: string; suspended: boolean }>;
 
 // ─── Default export ───────────────────────────────────────────────────────────
 
@@ -571,12 +728,19 @@ declare const extractia: {
   // Analytics
   getCreditsBalance: typeof getCreditsBalance;
   getCreditsHistory: typeof getCreditsHistory;
+  getDocumentHistory: typeof getDocumentHistory;
   // OCR Tools
   getOcrTools: typeof getOcrTools;
   createOcrTool: typeof createOcrTool;
   updateOcrTool: typeof updateOcrTool;
   deleteOcrTool: typeof deleteOcrTool;
   runOcrTool: typeof runOcrTool;
+  // Sub-users
+  getSubUsers: typeof getSubUsers;
+  createSubUser: typeof createSubUser;
+  deleteSubUser: typeof deleteSubUser;
+  updateSubUser: typeof updateSubUser;
+  toggleSuspendSubUser: typeof toggleSuspendSubUser;
 };
 
 export default extractia;

package/src/index.js

@@ -3,6 +3,7 @@ export * from "./templates.js";
 export * from "./documents.js";
 export * from "./analytics.js";
 export * from "./ocrTools.js";
+export * from "./subusers.js";
 export {
   ExtractiaError,
   AuthError,
@@ -17,6 +18,7 @@ import * as templates from "./templates.js";
 import * as documents from "./documents.js";
 import * as analytics from "./analytics.js";
 import * as ocrTools from "./ocrTools.js";
+import * as subusers from "./subusers.js";
 
 const extractia = {
   ...auth,
@@ -24,6 +26,7 @@ const extractia = {
   ...documents,
   ...analytics,
   ...ocrTools,
+  ...subusers,
 };
 
 export default extractia;