extractia-sdk 1.1.0 → 1.2.0

package/src/ocrTools.js

@@ -14,11 +14,15 @@ export async function getOcrTools() {
 /**
  * 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 to evaluate against each image.
+ * @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'. List of possible labels.
+ * @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) {
@@ -55,11 +59,26 @@ export async function deleteOcrTool(id) {
  * 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).
+ * @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) {
-  const res = await api.post(`/ocr-tools/${id}/run`, { image: base64Image });
+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;
+}