extractia-sdk 1.2.0 → 1.4.0

package/dist/index.d.ts

@@ -206,45 +206,94 @@ export interface OcrRunResult {
 
 /** Base error class for all Extractia SDK errors. */
 export class ExtractiaError extends Error {
-  /** HTTP status code associated with the error. */
+  /** HTTP status code (0 = no response). */
   status: number;
-  constructor(message: string, status: number);
+  /** Polished, user-facing English sentence always suitable for display. */
+  userMessage: string;
+  /** Machine-readable error code (e.g. "AUTH_ERROR", "QUOTA_EXCEEDED"). */
+  code: string;
+  /** X-Request-Id / X-Correlation-Id from the server response header, when present. */
+  requestId: string | null;
+  constructor(message: string, status?: number, userMessage?: string, code?: string);
+  /** Returns true if automatically retrying the same request may succeed. */
+  isRetryable(): boolean;
+  toJSON(): { name: string; code: string; status: number; message: string; userMessage: string; requestId: string | null };
 }
 
-/** Thrown when the API token is missing or invalid (HTTP 401). */
+/** HTTP 401 — token missing, expired, or malformed. */
 export class AuthError extends ExtractiaError {
   constructor(message?: string);
 }
 
-/** Thrown when the account lacks permission to perform the action (HTTP 403). */
+/** HTTP 403 — authenticated but lacking required permission. */
 export class ForbiddenError extends ExtractiaError {
   constructor(message?: string);
 }
 
-/** Thrown when the active plan does not allow the requested operation (HTTP 402). */
+/** HTTP 402 — plan tier does not include this feature. */
 export class TierError extends ExtractiaError {
   constructor(message?: string, status?: number);
 }
 
-/** Thrown when the API rate limit is exceeded (HTTP 429). */
-export class RateLimitError extends ExtractiaError {
-  /** Seconds to wait before the next request. */
-  retryAfter?: number;
+/** HTTP 402 — document processing quota exhausted for this billing period. */
+export class QuotaError extends ExtractiaError {
   constructor(message?: string);
 }
 
-/** Thrown when a requested resource was not found (HTTP 404). */
+/** HTTP 429 — requests sent too fast. Check `retryAfter` for the suggested wait time. */
+export class RateLimitError extends ExtractiaError {
+  /** Seconds to wait before retrying (from the Retry-After header), or null. */
+  retryAfter: number | null;
+  constructor(message?: string, retryAfter?: number | null);
+  isRetryable(): true;
+}
+
+/** HTTP 404 — the requested resource does not exist. */
 export class NotFoundError extends ExtractiaError {
   constructor(message?: string);
 }
 
+/** HTTP 400 — request body / parameters failed server-side validation. */
+export class ValidationError extends ExtractiaError {
+  /** Field-level errors, if the server provided them. */
+  fields: Record<string, string> | null;
+  constructor(message?: string, fields?: Record<string, string> | null);
+}
+
+/** HTTP 409 — a resource with the same unique identifier already exists. */
+export class ConflictError extends ExtractiaError {
+  constructor(message?: string);
+}
+
+/** HTTP 5xx — unexpected server-side failure. Always retryable. */
+export class ServerError extends ExtractiaError {
+  constructor(message?: string, status?: number);
+  isRetryable(): true;
+}
+
+/** No HTTP response — connection refused, DNS failure, etc. */
+export class NetworkError extends ExtractiaError {
+  constructor(message?: string);
+  isRetryable(): true;
+}
+
+/** Request timed out before the server responded. */
+export class TimeoutError extends ExtractiaError {
+  constructor(message?: string);
+  isRetryable(): true;
+}
+
+/** Maps an Axios error to the appropriate typed SDK error. */
+export function mapAxiosError(err: unknown): ExtractiaError;
+
 // ─── Setup ────────────────────────────────────────────────────────────────────
 
 /**
  * Sets the Bearer API token used for all subsequent requests.
  * **Must be called before any SDK method.**
  *
- * @param token Your Extractia API token (from Account → API Tokens).
+ * @param token Your Extractia API key (from Account → API Tokens).
+ * @throws {Error} If the token is empty or not a string.
  *
  * @example
  * import { setToken } from 'extractia-sdk';
@@ -252,12 +301,59 @@ export class NotFoundError extends ExtractiaError {
  */
 export function setToken(token: string): void;
 
+/** Returns the currently configured API token, or `null` if not set. */
+export function getToken(): string | null;
+
+/** Returns `true` if an API token has been set. */
+export function hasToken(): boolean;
+
+/** Clears the stored API token. Useful for logout flows or test teardown. */
+export function clearToken(): void;
+
+/** Returns a snapshot of the current SDK configuration (token excluded). */
+export function getConfig(): {
+  baseURL: string;
+  timeout: number;
+  retries: number;
+  retryDelay: number;
+  debug: boolean;
+  defaultHeaders: Record<string, string>;
+  onBeforeRequest: Function | null;
+  onAfterResponse: Function | null;
+  onError: Function | null;
+};
+
 /**
- * Configures SDK options.
- * @param opts
- * @param [opts.baseURL] Override the default API base URL (useful for self-hosted instances).
+ * Configures SDK behaviour. All properties are optional.
+ *
+ * @example
+ * configure({
+ *   timeout: 30_000,
+ *   retries: 2,
+ *   debug: true,
+ *   onError: (err) => sentryCapture(err),
+ * });
  */
-export function configure(opts: { baseURL?: string }): void;
+export function configure(opts: {
+  /** Override the API base URL (useful for staging or proxies). */
+  baseURL?: string;
+  /** Request timeout in milliseconds. Default: 60 000. */
+  timeout?: number;
+  /** Automatic retries on retryable errors (429 / 5xx / network). Default: 1. */
+  retries?: number;
+  /** Base delay (ms) between retries; multiplied by attempt number. Default: 1 000. */
+  retryDelay?: number;
+  /** Log requests / responses / retries to console.debug. Default: false. */
+  debug?: boolean;
+  /** Extra headers merged into every request. */
+  defaultHeaders?: Record<string, string>;
+  /** Hook called before each request. Return a modified config or void. */
+  onBeforeRequest?: (config: unknown) => unknown | void;
+  /** Hook called after each successful response. */
+  onAfterResponse?: (response: unknown) => void;
+  /** Hook called with the mapped SDK error whenever a request fails (after retries). */
+  onError?: (error: ExtractiaError) => void;
+}): void;
 
 // ─── Auth / Profile ───────────────────────────────────────────────────────────
 
@@ -694,11 +790,87 @@ export function toggleSuspendSubUser(username: string): Promise<{ username: stri
 
 // ─── Default export ───────────────────────────────────────────────────────────
 
+// ─── Utilities ───────────────────────────────────────────────────────────────
+
+/**
+ * Converts a browser `File` or `Blob` to a base64 data-URL string.
+ * @throws {Error} In Node.js environments where `FileReader` is unavailable.
+ */
+export function fileToBase64(file: File | Blob): Promise<string>;
+
+/**
+ * Strips the `data:…;base64,` prefix from a base64 string.
+ * Safe to call on a plain base64 string — returns it unchanged.
+ */
+export function stripDataUrlPrefix(base64OrDataUrl: string): string;
+
+/**
+ * Returns the MIME type embedded in a data-URL prefix, or `null`.
+ * @example getMimeType('data:image/png;base64,...') // → 'image/png'
+ */
+export function getMimeType(dataUrl: string): string | null;
+
+/**
+ * Returns `true` if the string is a valid base64-encoded value
+ * (with or without a data-URL prefix).
+ */
+export function isBase64(str: string): boolean;
+
+/**
+ * Accepts a `File`, `Blob`, or base64 string and always resolves to a
+ * base64 string — the data-URL for files and the string as-is otherwise.
+ */
+export function ensureBase64(fileOrBase64: File | Blob | string): Promise<string>;
+
+/**
+ * Async generator that yields individual items across all pages of a
+ * paginated SDK function.
+ *
+ * @example
+ * for await (const entry of paginate(getCreditsHistory, { size: 100 })) {
+ *   console.log(entry);
+ * }
+ */
+export function paginate<T>(
+  fn: (opts: { page: number; size: number }) => Promise<{ content: T[]; totalPages: number }>,
+  opts?: { size?: number; startPage?: number; maxPages?: number }
+): AsyncGenerator<T>;
+
+/**
+ * Collects all pages of a paginated SDK function into a flat array.
+ */
+export function paginateAll<T>(
+  fn: (opts: { page: number; size: number }) => Promise<{ content: T[]; totalPages: number }>,
+  opts?: { size?: number; startPage?: number; maxPages?: number }
+): Promise<T[]>;
+
+/** Returns a Promise that resolves after `ms` milliseconds. */
+export function delay(ms: number): Promise<void>;
+
+/**
+ * Calls an async function and retries it with exponential back-off on
+ * retryable `ExtractiaError`s.
+ */
+export function withRetry<T>(
+  fn: () => Promise<T>,
+  opts?: {
+    retries?: number;
+    initialDelay?: number;
+    shouldRetry?: (err: Error) => boolean;
+  }
+): Promise<T>;
+
+// ─── Default export ───────────────────────────────────────────────────────────
+
 /** Namespace object bundling all SDK methods for UMD / CommonJS consumers. */
 declare const extractia: {
   // Setup
   setToken: typeof setToken;
+  getToken: typeof getToken;
+  hasToken: typeof hasToken;
+  clearToken: typeof clearToken;
   configure: typeof configure;
+  getConfig: typeof getConfig;
   // Auth
   getMyProfile: typeof getMyProfile;
   updateWebhook: typeof updateWebhook;
@@ -741,6 +913,16 @@ declare const extractia: {
   deleteSubUser: typeof deleteSubUser;
   updateSubUser: typeof updateSubUser;
   toggleSuspendSubUser: typeof toggleSuspendSubUser;
+  // Utilities
+  fileToBase64: typeof fileToBase64;
+  stripDataUrlPrefix: typeof stripDataUrlPrefix;
+  getMimeType: typeof getMimeType;
+  isBase64: typeof isBase64;
+  ensureBase64: typeof ensureBase64;
+  paginate: typeof paginate;
+  paginateAll: typeof paginateAll;
+  delay: typeof delay;
+  withRetry: typeof withRetry;
 };
 
 export default extractia;

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "extractia-sdk",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "JavaScript SDK for the ExtractIA API — document extraction, OCR tools, AI summaries, templates & more",
   "type": "module",
   "author": "ExtractIA Team",
   "license": "MIT",
+  "homepage": "https://www.extractia.info/docs/sdk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/extractia/extractia-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/extractia/extractia-sdk/issues",
+    "email": "support@extractia.info"
+  },
   "keywords": [
     "sdk",
     "extractia",
@@ -14,7 +23,10 @@
     "client",
     "document-extraction",
     "ai",
-    "gemini"
+    "gemini",
+    "document-ai",
+    "typescript",
+    "data-extraction"
   ],
   "main": "dist/extractia-sdk.cjs.js",
   "module": "dist/extractia-sdk.esm.js",
@@ -34,12 +46,18 @@
   },
   "scripts": {
     "build": "node build.js",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:ui": "vitest --ui"
   },
   "dependencies": {
     "axios": "^1.10.0"
   },
   "devDependencies": {
-    "esbuild": "^0.25.6"
+    "@vitest/coverage-v8": "^2.1.9",
+    "axios-mock-adapter": "^2.1.0",
+    "esbuild": "^0.25.6",
+    "vitest": "^2.1.9"
   }
 }

package/src/apiClient.js

@@ -1,46 +1,212 @@
 import axios from "axios";
-import { mapAxiosError } from "./errors.js";
+import {
+  mapAxiosError,
+  ExtractiaError,
+  NetworkError,
+  TimeoutError,
+} from "./errors.js";
 
-let token = null;
+// ─── Internal state ───────────────────────────────────────────────────────────
 
-const DEFAULT_BASE_URL = "https://api.extractia.info/api/public";
+let _token = null;
 
-const api = axios.create({
-  baseURL: DEFAULT_BASE_URL,
-  timeout: 60000, // 60s — AI processing can take 10–30s
+/** @type {SDKConfig} */
+const _config = {
+  baseURL: "https://api.extractia.info/api/public",
+  timeout: 60_000,
+  retries: 1,
+  retryDelay: 1_000,
+  debug: false,
+  defaultHeaders: {},
+  onBeforeRequest: null,
+  onAfterResponse: null,
+  onError: null,
+};
+
+// ─── Axios instance ───────────────────────────────────────────────────────────
+
+export const _api = axios.create({
+  baseURL: _config.baseURL,
+  timeout: _config.timeout,
 });
 
-api.interceptors.request.use((config) => {
-  if (!token) {
-    throw new Error(
-      "API token is required. Call setToken(yourApiToken) before making requests.",
+// ── Request interceptor ──────────────────────────────────────────────────────
+_api.interceptors.request.use((config) => {
+  if (!_token) {
+    const err = new ExtractiaError(
+      "API token not set. Call setToken(token) before making requests.",
+      0,
+      "API token not set. Call setToken(token) before making requests.",
+      "TOKEN_MISSING",
+    );
+    return Promise.reject(err);
+  }
+
+  config.headers = config.headers ?? {};
+  config.headers["Authorization"] = `Bearer ${_token}`;
+
+  // Apply default headers
+  Object.assign(config.headers, _config.defaultHeaders);
+
+  if (_config.debug) {
+    console.debug(
+      `[ExtractIA SDK] → ${(config.method ?? "GET").toUpperCase()} ${config.baseURL ?? ""}${config.url ?? ""}`,
+      config.params ?? "",
     );
   }
-  config.headers.Authorization = `Bearer ${token}`;
+
+  if (typeof _config.onBeforeRequest === "function") {
+    const modified = _config.onBeforeRequest(config);
+    return modified ?? config;
+  }
+
   return config;
 });
 
-api.interceptors.response.use(
-  (response) => response,
-  (err) => Promise.reject(mapAxiosError(err)),
+// ── Response interceptor ─────────────────────────────────────────────────────
+_api.interceptors.response.use(
+  (response) => {
+    if (_config.debug) {
+      console.debug(
+        `[ExtractIA SDK] ← ${response.status} ${response.config?.url ?? ""}`,
+      );
+    }
+    if (typeof _config.onAfterResponse === "function") {
+      _config.onAfterResponse(response);
+    }
+    return response;
+  },
+  async (err) => {
+    // If already a typed ExtractiaError (e.g. from request interceptor), pass through
+    if (err instanceof ExtractiaError) {
+      if (typeof _config.onError === "function") _config.onError(err);
+      return Promise.reject(err);
+    }
+
+    const mapped = mapAxiosError(err);
+    const cfg = err.config;
+
+    // Automatic retry for retryable errors (429 / 5xx / network / timeout)
+    if (
+      cfg &&
+      mapped.isRetryable() &&
+      (cfg._retryCount ?? 0) < _config.retries
+    ) {
+      cfg._retryCount = (cfg._retryCount ?? 0) + 1;
+
+      // Honour Retry-After header for rate limits, otherwise exponential back-off
+      const delayMs =
+        mapped.retryAfter != null
+          ? mapped.retryAfter * 1_000
+          : _config.retryDelay * cfg._retryCount;
+
+      if (_config.debug) {
+        console.debug(
+          `[ExtractIA SDK] retrying (${cfg._retryCount}/${_config.retries}) in ${delayMs}ms…`,
+        );
+      }
+
+      await new Promise((r) => setTimeout(r, delayMs));
+      return _api(cfg);
+    }
+
+    if (typeof _config.onError === "function") _config.onError(mapped);
+    return Promise.reject(mapped);
+  },
 );
 
+// ─── Public API ───────────────────────────────────────────────────────────────
+
 /**
  * Sets the API token used for all subsequent requests.
  * Must be called before any SDK method.
- * @param {string} newToken - Your Extractia API token.
+ *
+ * @param {string} token - Your Extractia API key.
+ * @throws {Error} If the token is empty or not a string.
  */
-export function setToken(newToken) {
-  token = newToken;
+export function setToken(token) {
+  if (!token || typeof token !== "string" || !token.trim()) {
+    throw new Error("setToken: token must be a non-empty string.");
+  }
+  _token = token.trim();
+}
+
+/**
+ * Returns the currently configured API token, or `null` if not set.
+ * @returns {string|null}
+ */
+export function getToken() {
+  return _token;
+}
+
+/**
+ * Returns `true` if an API token has been set.
+ * @returns {boolean}
+ */
+export function hasToken() {
+  return Boolean(_token);
+}
+
+/**
+ * Clears the stored API token.
+ * Useful for logout flows or test teardown.
+ */
+export function clearToken() {
+  _token = null;
+}
+
+/**
+ * Configures SDK behaviour. All properties are optional; unspecified properties
+ * retain their current value.
+ *
+ * @param {object}   opts
+ * @param {string}   [opts.baseURL]
+ *   Override the API base URL (useful for staging environments or proxies).
+ * @param {number}   [opts.timeout]
+ *   Request timeout in milliseconds. Default: 60 000 (60 s).
+ * @param {number}   [opts.retries]
+ *   Number of automatic retries on retryable errors (429 / 5xx / network). Default: 1.
+ * @param {number}   [opts.retryDelay]
+ *   Base delay (ms) between retries; multiplied by the attempt number. Default: 1 000.
+ * @param {boolean}  [opts.debug]
+ *   Log request/response/retry info to `console.debug`. Default: false.
+ * @param {Record<string,string>} [opts.defaultHeaders]
+ *   Extra HTTP headers merged into every request (e.g. `{ "X-App-Version": "2.0" }`).
+ * @param {(config: import('axios').InternalAxiosRequestConfig) => import('axios').InternalAxiosRequestConfig|void} [opts.onBeforeRequest]
+ *   Hook called with the Axios request config before each request.
+ *   Return a modified config or `void` to keep the original.
+ * @param {(response: import('axios').AxiosResponse) => void} [opts.onAfterResponse]
+ *   Hook called after each successful response. Useful for logging or metrics.
+ * @param {(error: import('./errors.js').ExtractiaError) => void} [opts.onError]
+ *   Hook called with the mapped SDK error whenever a request fails.
+ *   Called after retries are exhausted.
+ */
+export function configure(opts = {}) {
+  if (opts.baseURL) {
+    _config.baseURL = opts.baseURL;
+    _api.defaults.baseURL = opts.baseURL;
+  }
+  if (opts.timeout != null) {
+    _config.timeout = opts.timeout;
+    _api.defaults.timeout = opts.timeout;
+  }
+  if (opts.retries != null) _config.retries = opts.retries;
+  if (opts.retryDelay != null) _config.retryDelay = opts.retryDelay;
+  if (opts.debug != null) _config.debug = Boolean(opts.debug);
+  if (opts.defaultHeaders) {
+    _config.defaultHeaders = { ..._config.defaultHeaders, ...opts.defaultHeaders };
+  }
+  if (opts.onBeforeRequest) _config.onBeforeRequest = opts.onBeforeRequest;
+  if (opts.onAfterResponse) _config.onAfterResponse = opts.onAfterResponse;
+  if (opts.onError) _config.onError = opts.onError;
 }
 
 /**
- * Configures SDK options.
- * @param {object} opts
- * @param {string} [opts.baseURL] - Override the default API base URL.
+ * Returns a snapshot of the current SDK configuration (token excluded).
+ * @returns {Readonly<typeof _config>}
  */
-export function configure({ baseURL } = {}) {
-  if (baseURL) api.defaults.baseURL = baseURL;
+export function getConfig() {
+  return { ..._config };
 }
 
-export default api;
+export default _api;

package/src/browser-entry.js

@@ -3,6 +3,23 @@ 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";
+import * as utils from "./utils.js";
+import { getToken, hasToken, clearToken, getConfig } from "./apiClient.js";
+import {
+  ExtractiaError,
+  AuthError,
+  ForbiddenError,
+  TierError,
+  QuotaError,
+  RateLimitError,
+  NotFoundError,
+  ValidationError,
+  ConflictError,
+  ServerError,
+  NetworkError,
+  TimeoutError,
+} from "./errors.js";
 
 const extractia = {
   ...auth,
@@ -10,6 +27,24 @@ const extractia = {
   ...documents,
   ...analytics,
   ...ocrTools,
+  ...subusers,
+  ...utils,
+  getToken,
+  hasToken,
+  clearToken,
+  getConfig,
+  ExtractiaError,
+  AuthError,
+  ForbiddenError,
+  TierError,
+  QuotaError,
+  RateLimitError,
+  NotFoundError,
+  ValidationError,
+  ConflictError,
+  ServerError,
+  NetworkError,
+  TimeoutError,
 };
 
 export default extractia;