extractia-sdk 1.0.6 → 1.2.0

package/src/index.js

@@ -1,16 +1,32 @@
-export * from './auth.js';
-export * from './templates.js';
-export * from './documents.js';
-
-import * as auth from './auth.js';
-import * as templates from './templates.js';
-import * as documents from './documents.js';
+export * from "./auth.js";
+export * from "./templates.js";
+export * from "./documents.js";
+export * from "./analytics.js";
+export * from "./ocrTools.js";
+export * from "./subusers.js";
+export {
+  ExtractiaError,
+  AuthError,
+  ForbiddenError,
+  TierError,
+  RateLimitError,
+  NotFoundError,
+} from "./errors.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";
+import * as subusers from "./subusers.js";
 
 const extractia = {
   ...auth,
   ...templates,
   ...documents,
+  ...analytics,
+  ...ocrTools,
+  ...subusers,
 };
 
-export default extractia;
+export default extractia;

package/src/ocrTools.js

@@ -0,0 +1,84 @@
+// src/ocrTools.js
+import api from "./apiClient.js";
+
+/**
+ * Returns all OCR tool configurations belonging to the authenticated user.
+ *
+ * @returns {Promise<Object[]>} Array of OcrToolConfig objects.
+ */
+export async function getOcrTools() {
+  const res = await api.get("/ocr-tools");
+  return res.data;
+}
+
+/**
+ * Creates a new OCR tool configuration.
+ *
+ * @param {Object} config                             - Tool definition.
+ * @param {string} config.name                        - Human-friendly display name.
+ * @param {string} config.prompt                      - The AI instruction/question (max 3 000 chars). May include
+ *                                                      {{?1}}, {{?2}}, … placeholders for dynamic parameters.
+ * @param {'YES_NO'|'LABEL'|'TEXT'} config.outputType - Expected output shape.
+ * @param {string[]} [config.labels]                  - Required when outputType is 'LABEL'.
+ * @param {Array<{key:number,label:string,description?:string,maxChars?:number}>} [config.parameterDefinitions]
+ *   Dynamic parameter definitions for {{?N}} placeholders. Each entry needs at minimum `key` (1-based) and
+ *   `label`. Optional `maxChars` (1–500, default 200) limits per-parameter input length.
+ * @returns {Promise<Object>} The created OcrToolConfig.
+ */
+export async function createOcrTool(config) {
+  const res = await api.post("/ocr-tools", config);
+  return res.data;
+}
+
+/**
+ * Updates an existing OCR tool configuration.
+ *
+ * @param {string} id     - The OCR tool config ID.
+ * @param {Object} config - Updated fields (name, prompt, outputType, labels).
+ * @returns {Promise<Object>} The updated OcrToolConfig.
+ */
+export async function updateOcrTool(id, config) {
+  const res = await api.put(`/ocr-tools/${id}`, config);
+  return res.data;
+}
+
+/**
+ * Deletes an OCR tool configuration.
+ *
+ * @param {string} id - The OCR tool config ID.
+ * @returns {Promise<void>}
+ */
+export async function deleteOcrTool(id) {
+  const res = await api.delete(`/ocr-tools/${id}`);
+  return res.data;
+}
+
+/**
+ * Runs an OCR tool against a base64-encoded image.
+ *
+ * The image may include a data-URL prefix (e.g. `data:image/jpeg;base64,...`)
+ * or be a raw base64 string.
+ *
+ * Each run deducts **1 document credit** from the user's quota plus AI credits
+ * based on token usage: `ceil(totalTokens / 1000)` credits.
+ *
+ * The AI response language matches the language used in the prompt / parameter values.
+ *
+ * @param {string} id          - The OCR tool config ID.
+ * @param {string} base64Image - Base64-encoded image (with or without data-URL prefix). Max 5 MB.
+ * @param {{ params?: Record<string, string> }} [options]
+ *   Optional. `params` is a map from placeholder key (as string, e.g. "1") to value, used to
+ *   substitute {{?N}} placeholders in the tool's prompt. Values must not exceed the per-parameter
+ *   `maxChars` limit; the substituted prompt must not exceed 3 000 characters total.
+ * @returns {Promise<{ answer: string, explanation: string }>} The AI result.
+ * @throws {ExtractiaError} 400 if a required parameter is missing/too long or the prompt limit is exceeded.
+ * @throws {TierError} 402 if the document quota or AI credits are exhausted.
+ */
+export async function runOcrTool(id, base64Image, options = {}) {
+  const body = { image: base64Image };
+  if (options.params && Object.keys(options.params).length > 0) {
+    body.params = options.params;
+  }
+  const res = await api.post(`/ocr-tools/${id}/run`, body);
+  return res.data;
+}

package/src/subusers.js

@@ -0,0 +1,85 @@
+// src/subusers.js
+import api from "./apiClient.js";
+
+/**
+ * Returns all sub-users for the authenticated account.
+ *
+ * Sub-users can log in to the web app and perform actions within the
+ * permissions granted by the owner. This endpoint is only available on
+ * plans that support sub-users (Pro and above).
+ *
+ * @returns {Promise<Array<{
+ *   username: string,
+ *   permissions: string[],
+ *   suspended: boolean,
+ *   lastKnownLocation?: string,
+ *   lastLocationAt?: string
+ * }>>} Array of sub-user objects. Password hashes are never returned.
+ */
+export async function getSubUsers() {
+  const res = await api.get("/me/subusers");
+  return res.data;
+}
+
+/**
+ * Creates a new sub-user for the authenticated account.
+ *
+ * Available permissions: `"upload"`, `"view"`, `"template"`, `"settings"`,
+ * `"export"`, `"api"`.
+ *
+ * @param {Object}   subUser              - Sub-user definition.
+ * @param {string}   subUser.username     - Unique username (must not be an existing account email).
+ * @param {string}   subUser.password     - Initial password (must differ from the owner's password).
+ * @param {string[]} subUser.permissions  - List of permission strings to grant.
+ * @returns {Promise<{ username: string, permissions: string[] }>} Confirmation object.
+ * @throws {ForbiddenError}   403 if the plan does not allow sub-users or the limit is reached.
+ * @throws {ExtractiaError}   409 if the username is already taken.
+ */
+export async function createSubUser({ username, password, permissions }) {
+  const res = await api.post("/me/subusers", { username, password, permissions });
+  return res.data;
+}
+
+/**
+ * Deletes a sub-user by username.
+ *
+ * @param {string} username - The sub-user's username.
+ * @returns {Promise<{ deleted: string }>} Confirmation with the deleted username.
+ * @throws {NotFoundError} 404 if the sub-user does not exist.
+ */
+export async function deleteSubUser(username) {
+  const res = await api.delete(`/me/subusers/${encodeURIComponent(username)}`);
+  return res.data;
+}
+
+/**
+ * Updates the permissions and/or password of a sub-user.
+ *
+ * Pass only the fields you want to change. Omitting `password` leaves it unchanged.
+ *
+ * @param {string}    username                  - The sub-user's username.
+ * @param {Object}    updates                   - Fields to update.
+ * @param {string[]}  [updates.permissions]     - New permission set (replaces existing).
+ * @param {string}    [updates.password]        - New password (must differ from owner's password).
+ * @returns {Promise<{ username: string, updated: boolean }>}
+ * @throws {NotFoundError} 404 if the sub-user does not exist.
+ */
+export async function updateSubUser(username, updates = {}) {
+  const res = await api.put(`/me/subusers/${encodeURIComponent(username)}`, updates);
+  return res.data;
+}
+
+/**
+ * Toggles the suspended state of a sub-user.
+ *
+ * A suspended sub-user cannot log in until unsuspended. Their permissions
+ * are retained and restored on unsuspension.
+ *
+ * @param {string} username - The sub-user's username.
+ * @returns {Promise<{ username: string, suspended: boolean }>} New suspension state.
+ * @throws {NotFoundError} 404 if the sub-user does not exist.
+ */
+export async function toggleSuspendSubUser(username) {
+  const res = await api.put(`/me/subusers/${encodeURIComponent(username)}/suspend`);
+  return res.data;
+}

package/src/templates.js

@@ -1,39 +1,94 @@
 // src/templates.js
-import api from './apiClient.js';
+import api from "./apiClient.js";
 
+/**
+ * Returns all templates belonging to the authenticated user.
+ * @returns {Promise<Object[]>} Array of template objects.
+ */
 export async function getTemplates() {
-  const res = await api.get('/templates');
+  const res = await api.get("/templates");
   return res.data;
 }
 
+/**
+ * Returns a single template by its ID.
+ * @param {string} id - The template ID.
+ * @returns {Promise<Object>} Template object.
+ */
 export async function getTemplateById(id) {
   const res = await api.get(`/templates/${id}`);
   return res.data;
 }
 
+/**
+ * Returns a template by its label name.
+ * @param {string} name - The template label.
+ * @returns {Promise<Object>} Template object.
+ */
 export async function getTemplateByName(name) {
   const res = await api.get(`/templates/name`, {
-    params: { name }
+    params: { name },
   });
   return res.data;
 }
 
+/**
+ * Creates a new template.
+ * @param {Object} template - Template definition object.
+ * @returns {Promise<Object>} The created template.
+ */
 export async function createTemplate(template) {
-  const res = await api.post('/templates', template);
+  const res = await api.post("/templates", template);
   return res.data;
 }
 
+/**
+ * Updates an existing template.
+ * @param {string} id       - The template ID to update.
+ * @param {Object} template - Partial or full template definition.
+ * @returns {Promise<Object>} The updated template.
+ */
 export async function updateTemplate(id, template) {
   const res = await api.put(`/templates/${id}`, template);
   return res.data;
 }
 
+/**
+ * Deletes a template by its ID.
+ * @param {string} id - The template ID to delete.
+ * @returns {Promise<void>}
+ */
 export async function deleteTemplate(id) {
   const res = await api.delete(`/templates/${id}`);
   return res.data;
 }
 
+/**
+ * Deletes all documents associated with a template.
+ * @param {string} id - The template ID.
+ * @returns {Promise<void>}
+ */
 export async function deleteAllTemplateDocuments(id) {
   const res = await api.delete(`/templates/${id}/documents`);
   return res.data;
 }
+
+/**
+ * Uses AI to suggest extraction field definitions for a given document type.
+ *
+ * Returns an array of field definitions that you can use directly when creating
+ * or updating a FormTemplate.
+ *
+ * @param {string} templateName          - Document type name (e.g. "Invoice", "Receipt").
+ * @param {string} [extractionContext]   - Optional natural-language description of what
+ *                                         to extract (e.g. "I need all line items with
+ *                                         product name and quantity").
+ * @returns {Promise<Array<{ label: string, type: string, required: boolean, listLabel?: string }>>}
+ */
+export async function suggestFields(templateName, extractionContext = "") {
+  const res = await api.post("/templates/suggest-fields", {
+    templateName,
+    extractionContext,
+  });
+  return res.data;
+}