extractia-sdk 1.0.6 → 1.2.0

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "extractia-sdk",
-  "version": "1.0.6",
-  "description": "JavaScript SDK for the ExtractIA API",
-  "author": "Tu Nombre o Empresa",
+  "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": [
     "sdk",
@@ -10,17 +11,27 @@
     "ocr",
     "documents",
     "api",
-    "client"
+    "client",
+    "document-extraction",
+    "ai",
+    "gemini"
   ],
   "main": "dist/extractia-sdk.cjs.js",
-  "module": "dist/extractia-sdk.esm.js",    
-  "browser": "dist/extractia-sdk.browser.js", 
+  "module": "dist/extractia-sdk.esm.js",
+  "browser": "dist/extractia-sdk.browser.js",
   "exports": {
     "import": "./dist/extractia-sdk.esm.js",
     "require": "./dist/extractia-sdk.cjs.js",
     "default": "./dist/extractia-sdk.esm.js"
   },
-  "types": "./dist/index.d.ts",             
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./src/index.d.ts"
+      ]
+    }
+  },
   "scripts": {
     "build": "node build.js",
     "test": "echo \"Error: no test specified\" && exit 1"

package/src/analytics.js

@@ -0,0 +1,46 @@
+// src/analytics.js
+import api from "./apiClient.js";
+
+/**
+ * Returns the current AI-credit balance for the authenticated user.
+ *
+ * @returns {Promise<{ monthlyBalance: number, addonBalance: number, totalBalance: number }>}
+ */
+export async function getCreditsBalance() {
+  const res = await api.get("/me/credits");
+  return res.data;
+}
+
+/**
+ * Returns a paginated history of AI credit consumption events.
+ *
+ * @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 getCreditsHistory({ page = 0, size = 20 } = {}) {
+  const res = await api.get("/me/credits/history", {
+    params: { page, size: Math.min(size, 100) },
+  });
+  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,22 +1,46 @@
-import axios from 'axios';
-
-let token = null;
-
-const api = axios.create({
-  baseURL: 'https://www.extractia-api.cat/api/public',
-  timeout: 10000,
-});
-
-api.interceptors.request.use((config) => {
-  if (!token) {
-    throw new Error('API token is required');
-  }
-  config.headers.Authorization = `Bearer ${token}`;
-  return config;
-});
-
-export function setToken(newToken) {
-  token = newToken;
-}
-
-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/auth.js

@@ -1,16 +1,25 @@
 // src/auth.js
-import api, { setToken } from './apiClient.js';
+import api, { setToken, configure } from "./apiClient.js";
 
+/**
+ * Returns the profile of the authenticated user.
+ * @returns {Promise<Object>} User profile object.
+ */
 export async function getMyProfile() {
-  const response = await api.get('/me');
+  const response = await api.get("/me");
   return response.data;
 }
 
+/**
+ * Updates the webhook URL for the authenticated user.
+ * @param {string} url - The new webhook URL.
+ * @returns {Promise<Object>} Updated user object.
+ */
 export async function updateWebhook(url) {
-  const response = await api.put('/me/webhook', null, {
-    params: { webhookUrl: url }
+  const response = await api.put("/me/webhook", null, {
+    params: { webhookUrl: url },
   });
   return response.data;
 }
 
-export { setToken };
+export { setToken, configure };

package/src/browser-entry.js

@@ -1,11 +1,15 @@
-import * as auth from './auth.js';
-import * as templates from './templates.js';
-import * as documents from './documents.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,
   ...templates,
   ...documents,
+  ...analytics,
+  ...ocrTools,
 };
 
-export default extractia;
+export default extractia;

package/src/documents.js

@@ -1,33 +1,195 @@
 // src/documents.js
-import api from './apiClient.js';
+import api from "./apiClient.js";
 
+/**
+ * Retrieves documents associated with a template (paginated).
+ *
+ * @param {string} templateId - The template ID to query.
+ * @param {Object} [options]
+ * @param {boolean} [options.preconformed] - Filter by preconfirmed status.
+ * @param {number}  [options.index]        - Zero-based page index.
+ * @param {string}  [options.sort]         - Sort direction: "1" = ASC, "-1" = DESC (default).
+ * @param {boolean} [options.includeImage] - Whether to include the base64 image in results.
+ * @returns {Promise<{ content: Object[], totalPages: number }>} Paginated document list.
+ */
 export async function getDocumentsByTemplateId(templateId, options = {}) {
-  const params = {
-    preconformed: options.preconformed ?? null,
-    index: options.index ?? 0,
-    sort: options.sort ?? -1,
-    includeImage: options.includeImage ? 1 : 0,
-  };
-
+  const params = {};
+  if (options.preconformed != null) params.preconformed = options.preconformed;
+  if (options.index != null) params.index = options.index;
+  if (options.sort != null) params.sort = options.sort;
+  params.includeImage = options.includeImage ? 1 : 0;
   const res = await api.get(`/templates/${templateId}/documents`, { params });
   return res.data;
 }
 
+/**
+ * Returns a single document by its template and document ID.
+ *
+ * @param {string}  templateId    - Template ID.
+ * @param {string}  docId         - Document ID.
+ * @param {Object}  [options]
+ * @param {boolean} [options.includeImage] - Whether to include the base64 source image.
+ * @returns {Promise<Object>} The document object.
+ */
+export async function getDocumentById(templateId, docId, options = {}) {
+  const params = { includeImage: options.includeImage ? 1 : 0 };
+  const res = await api.get(`/templates/${templateId}/documents/${docId}`, {
+    params,
+  });
+  return res.data;
+}
+
+/**
+ * Returns the N most-recent documents across all templates.
+ *
+ * @param {number} [size=10] - Maximum number of documents to return (max 50).
+ * @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) },
+  });
+  return res.data;
+}
+
+/**
+ * Deletes a document by its ID.
+ *
+ * @param {string} documentId - The document ID to delete.
+ * @returns {Promise<void>}
+ */
 export async function deleteDocument(documentId) {
   const res = await api.delete(`/documents/${documentId}`);
   return res.data;
 }
 
+/**
+ * Processes a single base64-encoded image against a template.
+ *
+ * @param {string} templateId   - The template ID to process with.
+ * @param {string} base64Image  - Base64-encoded image (with or without data-URL prefix).
+ * @returns {Promise<Object>} The created UserDocument with extracted JSON.
+ */
 export async function processImage(templateId, base64Image) {
-  const res = await api.post(`/public/templates/${templateId}/process`, {
-    image: base64Image
+  const res = await api.post(`/templates/${templateId}/process`, {
+    image: base64Image,
   });
   return res.data;
 }
 
+/**
+ * Processes multiple base64-encoded images as a multi-page document.
+ * All pages are merged into a single UserDocument.
+ *
+ * @param {string}   templateId        - The template ID to process with.
+ * @param {string[]} base64ImagesArray - Array of base64-encoded images (one per page).
+ * @returns {Promise<Object>} The created UserDocument with merged extracted JSON.
+ */
 export async function processImagesMultipage(templateId, base64ImagesArray) {
-  const res = await api.post(`/public/templates/${templateId}/process-multipage`, {
-    images: base64ImagesArray
+  const res = await api.post(`/templates/${templateId}/process-multipage`, {
+    images: base64ImagesArray,
+  });
+  return res.data;
+}
+
+/**
+ * Generates an AI summary for the extracted data of a document.
+ *
+ * @param {string} docId - The document ID.
+ * @returns {Promise<{ summary: string }>} Object with the generated summary text.
+ */
+export async function generateDocumentSummary(docId) {
+  const res = await api.post(`/documents/${docId}/summary`);
+  return res.data;
+}
+
+/**
+ * Updates the status of a document.
+ *
+ * Valid status values depend on your workflow configuration
+ * (e.g. "REVIEWED", "PENDING", "APPROVED").
+ *
+ * @param {string} docId   - The document ID.
+ * @param {string} status  - The new status string.
+ * @returns {Promise<{ id: string, status: string }>}
+ */
+export async function updateDocumentStatus(docId, status) {
+  const res = await api.put(`/documents/${docId}/status`, { status });
+  return res.data;
+}
+
+/**
+ * Saves or clears reviewer notes on a document.
+ *
+ * @param {string} docId  - The document ID.
+ * @param {string} notes  - Annotation text. Pass an empty string to clear.
+ * @returns {Promise<{ id: string, notes: string }>}
+ */
+export async function updateDocumentNotes(docId, notes) {
+  const res = await api.put(`/documents/${docId}/notes`, { notes });
+  return res.data;
+}
+
+/**
+ * Updates the extracted JSON data of a document and optionally marks it as reviewed.
+ *
+ * @param {string}  docId             - The document ID.
+ * @param {Object}  data              - New extracted data object (key-value pairs).
+ * @param {Object}  [options]
+ * @param {boolean} [options.preconformed=false] - Whether to mark the document as reviewed/confirmed.
+ * @returns {Promise<Object>} The updated UserDocument.
+ */
+export async function updateDocumentData(docId, data, options = {}) {
+  const res = await api.put(`/documents/${docId}/data`, {
+    data,
+    preconformed: options.preconformed ?? false,
+  });
+  return res.data;
+}
+
+/**
+ * Marks multiple documents as preconformed (reviewed) in a single request.
+ *
+ * @param {string[]} ids - Array of document IDs to mark as reviewed.
+ * @returns {Promise<{ updated: number }>} Number of documents actually updated.
+ */
+export async function bulkPreconform(ids) {
+  const res = await api.post("/documents/bulk-preconform", { ids });
+  return res.data;
+}
+
+/**
+ * Exports all documents of a template as a CSV string.
+ *
+ * The returned string is UTF-8 CSV (with BOM). You can save it as a `.csv` file
+ * or feed it into a CSV parser.
+ *
+ * @param {string}   templateId       - The template ID.
+ * @param {Object}   [options]
+ * @param {string[]} [options.fields] - Optional subset of column names to include.
+ * @returns {Promise<string>} Raw CSV text.
+ */
+export async function exportDocumentsCsv(templateId, options = {}) {
+  const params = {};
+  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",
   });
   return res.data;
 }
+
+/**
+ * Exports all documents of a template as a JSON array.
+ *
+ * Each element contains the extracted field map plus three metadata keys:
+ * `_id`, `_preconformed`, and `_uploadedAt`.
+ *
+ * @param {string} templateId - The template ID.
+ * @returns {Promise<Object[]>} Array of document data objects.
+ */
+export async function exportDocumentsJson(templateId) {
+  const res = await api.get(`/templates/${templateId}/documents/export/json`);
+  return res.data;
+}

package/src/errors.js

@@ -0,0 +1,95 @@
+/**
+ * Base error for all Extractia SDK errors.
+ * Always carries the HTTP `status` code and a human-readable `message`.
+ */
+export class ExtractiaError extends Error {
+  /** @param {string} message @param {number} status */
+  constructor(message, status) {
+    super(message);
+    this.name = "ExtractiaError";
+    this.status = status;
+  }
+}
+
+/**
+ * Thrown when the API token is missing or invalid (HTTP 401).
+ */
+export class AuthError extends ExtractiaError {
+  constructor(message = "Unauthorized. Check your API token.") {
+    super(message, 401);
+    this.name = "AuthError";
+  }
+}
+
+/**
+ * Thrown when the account has no permission to perform the action (HTTP 403).
+ * Typically means the email is unconfirmed or a sub-user lacks the required permission.
+ */
+export class ForbiddenError extends ExtractiaError {
+  constructor(message = "Forbidden. Insufficient permissions.") {
+    super(message, 403);
+    this.name = "ForbiddenError";
+  }
+}
+
+/**
+ * Thrown when the active plan does not allow the requested operation (HTTP 402 / 429 tier).
+ * Check `error.status` to distinguish payment-required (402) from rate-limit (429).
+ */
+export class TierError extends ExtractiaError {
+  constructor(
+    message = "Tier limit reached. Upgrade your plan.",
+    status = 402,
+  ) {
+    super(message, status);
+    this.name = "TierError";
+  }
+}
+
+/**
+ * Thrown when the API rate limit is exceeded (HTTP 429).
+ */
+export class RateLimitError extends ExtractiaError {
+  constructor(message = "Too many requests. Please slow down.") {
+    super(message, 429);
+    this.name = "RateLimitError";
+  }
+}
+
+/**
+ * Thrown when a requested resource was not found (HTTP 404).
+ */
+export class NotFoundError extends ExtractiaError {
+  constructor(message = "Resource not found.") {
+    super(message, 404);
+    this.name = "NotFoundError";
+  }
+}
+
+/**
+ * Maps an Axios error to the appropriate typed SDK error.
+ * Falls back to a generic `ExtractiaError` for unexpected status codes.
+ *
+ * @param {import('axios').AxiosError} err
+ * @returns {ExtractiaError}
+ */
+export function mapAxiosError(err) {
+  const status = err.response?.status;
+  const serverMessage = err.response?.data;
+  const detail = typeof serverMessage === "string" ? serverMessage : undefined;
+
+  switch (status) {
+    case 401:
+      return new AuthError(detail);
+    case 402:
+      return new TierError(detail);
+    case 403:
+      return new ForbiddenError(detail);
+    case 404:
+      return new NotFoundError(detail);
+    case 429:
+      return new RateLimitError(detail);
+    default:
+      return new ExtractiaError(detail ?? err.message, status ?? 0);
+  }
+}