extractia-sdk 1.2.0 → 1.4.0

package/src/index.js

@@ -4,14 +4,28 @@ 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 +33,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 +43,11 @@ const extractia = {
   ...analytics,
   ...ocrTools,
   ...subusers,
+  ...utils,
+  getToken,
+  hasToken,
+  clearToken,
+  getConfig,
 };
 
 export default extractia;

package/src/subusers.js

@@ -11,6 +11,7 @@ import api from "./apiClient.js";
  * @returns {Promise<Array<{
  *   username: string,
  *   permissions: string[],
+ *   allowedFormIds: string[] | null,
  *   suspended: boolean,
  *   lastKnownLocation?: string,
  *   lastLocationAt?: string
@@ -25,24 +26,40 @@ export async function getSubUsers() {
  * Creates a new sub-user for the authenticated account.
  *
  * Available permissions: `"upload"`, `"view"`, `"template"`, `"settings"`,
- * `"export"`, `"api"`.
+ * `"export"`, `"ocr_tools"`, `"gallery"`, `"smart_scan"`, `"ia_agent"`.
  *
- * @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.
+ * @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.
+ * @param {string[]?} subUser.allowedFormIds     - Optional list of form template IDs this sub-user may access.
+ *                                                 When omitted or null, the sub-user can access all forms.
+ * @returns {Promise<{ username: string, permissions: string[], allowedFormIds?: 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 });
+export async function createSubUser({
+  username,
+  password,
+  permissions,
+  allowedFormIds,
+}) {
+  const res = await api.post("/me/subusers", {
+    username,
+    password,
+    permissions,
+    ...(allowedFormIds !== undefined ? { allowedFormIds } : {}),
+  });
   return res.data;
 }
 
 /**
  * Deletes a sub-user by username.
  *
+ * @note The deleted sub-user's JWT token is immediately rejected by the server
+ *       on every subsequent request — no grace period. Token revocation happens
+ *       automatically via the authentication filter.
+ *
  * @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.
@@ -53,19 +70,24 @@ export async function deleteSubUser(username) {
 }
 
 /**
- * Updates the permissions and/or password of a sub-user.
+ * Updates the permissions, allowed forms, and/or password of a sub-user.
  *
- * Pass only the fields you want to change. Omitting `password` leaves it unchanged.
+ * Pass only the fields you want to change. Omitting a field 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).
+ * @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.allowedFormIds]      - New allowed form ID list (replaces existing).
+ *                                                     Pass an empty array to remove all restrictions.
+ * @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);
+  const res = await api.put(
+    `/me/subusers/${encodeURIComponent(username)}`,
+    updates,
+  );
   return res.data;
 }
 
@@ -80,6 +102,8 @@ export async function updateSubUser(username, updates = {}) {
  * @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`);
+  const res = await api.put(
+    `/me/subusers/${encodeURIComponent(username)}/suspend`,
+  );
   return res.data;
 }

package/src/utils.js

@@ -0,0 +1,219 @@
+/**
+ * ExtractIA SDK — utility helpers
+ *
+ * All helpers are pure / side-effect-free and safe to import in both
+ * browser and Node.js environments (FileReader is guarded).
+ */
+
+// ─── Base64 helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Converts a browser `File` (or `Blob`) to a base64 data-URL string.
+ *
+ * The returned string includes the MIME prefix, e.g.:
+ *   `data:image/jpeg;base64,/9j/4AAQ…`
+ *
+ * @param {File|Blob} file
+ * @returns {Promise<string>} Base64 data-URL.
+ * @throws {Error} In non-browser environments where `FileReader` is unavailable.
+ */
+export function fileToBase64(file) {
+  if (typeof FileReader === "undefined") {
+    return Promise.reject(
+      new Error(
+        "fileToBase64: FileReader is not available in this environment. " +
+          "In Node.js, read the file manually and encode it with Buffer.from(data).toString('base64').",
+      ),
+    );
+  }
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(/** @type {string} */ (reader.result));
+    reader.onerror = () =>
+      reject(new Error(`fileToBase64: failed to read file "${file.name ?? "unknown"}".`));
+    reader.readAsDataURL(file);
+  });
+}
+
+/**
+ * Strips the data-URL prefix from a base64 string.
+ * If the string is already a raw base64 value, it is returned unchanged.
+ *
+ * @param {string} base64OrDataUrl — `"data:image/jpeg;base64,ABC…"` or `"ABC…"`.
+ * @returns {string} Raw base64 characters without the `data:…;base64,` prefix.
+ * @throws {TypeError} If the argument is not a string.
+ */
+export function stripDataUrlPrefix(base64OrDataUrl) {
+  if (typeof base64OrDataUrl !== "string") {
+    throw new TypeError(
+      "stripDataUrlPrefix: argument must be a string.",
+    );
+  }
+  const idx = base64OrDataUrl.indexOf(";base64,");
+  return idx !== -1 ? base64OrDataUrl.slice(idx + 8) : base64OrDataUrl;
+}
+
+/**
+ * Returns the MIME type embedded in a data-URL prefix, or `null`.
+ *
+ * @param {string} dataUrl — e.g. `"data:image/png;base64,…"`.
+ * @returns {string|null}
+ */
+export function getMimeType(dataUrl) {
+  if (typeof dataUrl !== "string") return null;
+  const match = dataUrl.match(/^data:([^;]+);base64,/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Returns `true` if the string is a valid base64-encoded value
+ * (with or without a data-URL prefix).
+ *
+ * @param {string} str
+ * @returns {boolean}
+ */
+export function isBase64(str) {
+  if (typeof str !== "string" || !str.trim()) return false;
+  const raw = stripDataUrlPrefix(str);
+  // Must be divisible by 4 and only contain valid base64 characters
+  return raw.length > 0 && raw.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(raw);
+}
+
+/**
+ * Accepts either a browser `File` / `Blob` or a base64 string and
+ * always resolves to a base64 string (data-URL for files, unchanged for strings).
+ *
+ * Useful for SDK functions that accept both `File` inputs (browser) and
+ * pre-encoded base64 strings (Node.js / server-side).
+ *
+ * @param {File|Blob|string} fileOrBase64
+ * @returns {Promise<string>}
+ * @throws {TypeError} If the argument is neither a string nor a File/Blob.
+ */
+export async function ensureBase64(fileOrBase64) {
+  if (typeof fileOrBase64 === "string") return fileOrBase64;
+  if (
+    (typeof File !== "undefined" && fileOrBase64 instanceof File) ||
+    (typeof Blob !== "undefined" && fileOrBase64 instanceof Blob)
+  ) {
+    return fileToBase64(fileOrBase64);
+  }
+  throw new TypeError(
+    "ensureBase64: argument must be a File, Blob, or a base64 string.",
+  );
+}
+
+// ─── Pagination helpers ───────────────────────────────────────────────────────
+
+/**
+ * Async generator that wraps any paginated SDK function following the Spring
+ * `Page` contract (`{ content: T[], totalPages: number }`) and yields
+ * individual items across all pages.
+ *
+ * @template T
+ * @param {(opts: { page: number; size: number }) => Promise<{ content: T[]; totalPages: number }>} fn
+ *   A paginated SDK function (e.g. `getCreditsHistory`, `getDocumentHistory`).
+ * @param {object}  [opts]
+ * @param {number}  [opts.size=50]       — Items per request (max depends on endpoint).
+ * @param {number}  [opts.startPage=0]   — Zero-based page index to start from.
+ * @param {number}  [opts.maxPages=1000] — Safety ceiling: stop after this many pages.
+ * @yields {T}
+ *
+ * @example
+ * for await (const entry of paginate(getCreditsHistory, { size: 100 })) {
+ *   console.log(entry.creditsConsumed);
+ * }
+ */
+export async function* paginate(
+  fn,
+  { size = 50, startPage = 0, maxPages = 1_000 } = {},
+) {
+  let page = startPage;
+  let pagesRead = 0;
+
+  while (pagesRead < maxPages) {
+    const result = await fn({ page, size });
+    const items = Array.isArray(result?.content) ? result.content : [];
+
+    for (const item of items) yield item;
+
+    const totalPages = result?.totalPages ?? 1;
+    if (items.length === 0 || page + 1 >= totalPages) break;
+
+    page++;
+    pagesRead++;
+  }
+}
+
+/**
+ * Collects all pages of a paginated SDK function into a flat array.
+ *
+ * @template T
+ * @param {(opts: { page: number; size: number }) => Promise<{ content: T[]; totalPages: number }>} fn
+ * @param {Parameters<typeof paginate>[1]} [opts]
+ * @returns {Promise<T[]>}
+ */
+export async function paginateAll(fn, opts) {
+  const items = [];
+  for await (const item of paginate(fn, opts)) items.push(item);
+  return items;
+}
+
+// ─── Async helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Returns a Promise that resolves after `ms` milliseconds.
+ *
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+export function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Calls an async function and retries it with exponential back-off when it
+ * throws a retryable `ExtractiaError` (i.e. `error.isRetryable()` returns `true`).
+ *
+ * This is useful when you have disabled the SDK's built-in automatic retry
+ * (`configure({ retries: 0 })`) and want finer control per call.
+ *
+ * @template T
+ * @param {() => Promise<T>}  fn            — Async function to call.
+ * @param {object}            [opts]
+ * @param {number}            [opts.retries=3]           — Max additional attempts after the first failure.
+ * @param {number}            [opts.initialDelay=500]    — Initial back-off delay (ms); doubles each attempt.
+ * @param {(err: Error) => boolean} [opts.shouldRetry]   — Custom predicate; defaults to `err.isRetryable()`.
+ * @returns {Promise<T>}
+ *
+ * @example
+ * const doc = await withRetry(() => processImage(templateId, base64), { retries: 3 });
+ */
+export async function withRetry(
+  fn,
+  { retries = 3, initialDelay = 500, shouldRetry } = {},
+) {
+  const isRetryable =
+    shouldRetry ??
+    ((err) => typeof err.isRetryable === "function" && err.isRetryable());
+
+  let lastErr;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (attempt < retries && isRetryable(err)) {
+        // Honour Retry-After for rate-limit errors
+        const wait =
+          err.retryAfter != null
+            ? err.retryAfter * 1_000
+            : initialDelay * 2 ** attempt;
+        await delay(wait);
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw lastErr;
+}