extractia-sdk 1.3.0 → 1.5.0

package/src/apiClient.js

@@ -1,46 +1,215 @@
 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;

package/src/errors.js

@@ -1,95 +1,336 @@
 /**
- * Base error for all Extractia SDK errors.
- * Always carries the HTTP `status` code and a human-readable `message`.
+ * SDK error classes — every error is a typed class that extends `ExtractiaError`.
+ *
+ * Every instance carries:
+ *   • `status`       — HTTP status code (0 for network / timeout errors)
+ *   • `message`      — Technical detail (may be a raw server string)
+ *   • `userMessage`  — Always a polished, user-facing English sentence
+ *   • `code`         — Short machine-readable string (e.g. "AUTH_ERROR")
+ *   • `requestId`    — X-Request-Id / X-Correlation-Id header when present
  */
+
+// ─── Human-readable defaults per status ──────────────────────────────────────
+const STATUS_MESSAGES = {
+  400: "The request contains invalid data. Please check your input.",
+  401: "Your API token is invalid or has expired. Please check your credentials.",
+  402: "Your current plan does not support this feature or your document quota is exhausted.",
+  403: "You do not have permission to perform this action.",
+  404: "The requested resource could not be found.",
+  409: "A resource with this identifier already exists.",
+  429: "Too many requests. Please wait a moment and try again.",
+  500: "The server encountered an unexpected error. Please try again in a moment.",
+  502: "The server received an unexpected response. Please try again.",
+  503: "The service is temporarily unavailable. Please try again in a few minutes.",
+  504: "The server timed out while processing the request. Please try again.",
+};
+
+// ─── Base class ───────────────────────────────────────────────────────────────
 export class ExtractiaError extends Error {
-  /** @param {string} message @param {number} status */
-  constructor(message, status) {
+  /**
+   * @param {string} message    — Technical detail string.
+   * @param {number} [status]   — HTTP status code (0 = no response).
+   * @param {string} [userMessage] — Human-friendly sentence shown to end users.
+   * @param {string} [code]     — Machine-readable error code.
+   */
+  constructor(message, status = 0, userMessage = null, code = "SDK_ERROR") {
     super(message);
     this.name = "ExtractiaError";
     this.status = status;
+    this.userMessage = userMessage ?? message;
+    this.code = code;
+    /** @type {string|null} Populated from X-Request-Id / X-Correlation-Id response header. */
+    this.requestId = null;
+  }
+
+  /** Returns true if automatically retrying the same request may succeed. */
+  isRetryable() {
+    return this.status === 429 || this.status >= 500;
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      status: this.status,
+      message: this.message,
+      userMessage: this.userMessage,
+      requestId: this.requestId,
+    };
   }
 }
 
-/**
- * Thrown when the API token is missing or invalid (HTTP 401).
- */
+// ─── Typed subclasses ─────────────────────────────────────────────────────────
+
+/** HTTP 401 — token missing, expired, or malformed. */
 export class AuthError extends ExtractiaError {
-  constructor(message = "Unauthorized. Check your API token.") {
-    super(message, 401);
+  constructor(message = STATUS_MESSAGES[401]) {
+    super(message, 401, STATUS_MESSAGES[401], "AUTH_ERROR");
     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.
+ * HTTP 403 — authenticated but lacking required permission.
+ * Common causes: unconfirmed email, sub-user permission not granted, plan restriction.
  */
 export class ForbiddenError extends ExtractiaError {
-  constructor(message = "Forbidden. Insufficient permissions.") {
-    super(message, 403);
+  constructor(message = STATUS_MESSAGES[403]) {
+    super(message, 403, STATUS_MESSAGES[403], "FORBIDDEN");
     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).
- */
+/** HTTP 402 — plan tier does not include this feature. */
 export class TierError extends ExtractiaError {
+  constructor(message = STATUS_MESSAGES[402], status = 402) {
+    super(message, status, STATUS_MESSAGES[402], "TIER_LIMIT");
+    this.name = "TierError";
+  }
+}
+
+/** HTTP 402 — document processing quota exhausted for this billing period. */
+export class QuotaError extends ExtractiaError {
   constructor(
-    message = "Tier limit reached. Upgrade your plan.",
-    status = 402,
+    message = "You have reached your document processing quota for this billing period. Please upgrade or wait for the next cycle.",
   ) {
-    super(message, status);
-    this.name = "TierError";
+    super(message, 402, message, "QUOTA_EXCEEDED");
+    this.name = "QuotaError";
   }
 }
 
 /**
- * Thrown when the API rate limit is exceeded (HTTP 429).
+ * HTTP 429 — requests sent too fast.
+ * Check `error.retryAfter` (seconds) from the `Retry-After` header when available.
  */
 export class RateLimitError extends ExtractiaError {
-  constructor(message = "Too many requests. Please slow down.") {
-    super(message, 429);
+  /**
+   * @param {string} [message]
+   * @param {number|null} [retryAfter] — Seconds to wait before retrying (from Retry-After header).
+   */
+  constructor(message = STATUS_MESSAGES[429], retryAfter = null) {
+    super(message, 429, STATUS_MESSAGES[429], "RATE_LIMITED");
     this.name = "RateLimitError";
+    /** @type {number|null} */
+    this.retryAfter = retryAfter;
+  }
+  isRetryable() {
+    return true;
   }
 }
 
-/**
- * Thrown when a requested resource was not found (HTTP 404).
- */
+/** HTTP 404 — the requested resource does not exist. */
 export class NotFoundError extends ExtractiaError {
-  constructor(message = "Resource not found.") {
-    super(message, 404);
+  constructor(message = STATUS_MESSAGES[404]) {
+    super(message, 404, STATUS_MESSAGES[404], "NOT_FOUND");
     this.name = "NotFoundError";
   }
 }
 
+/**
+ * HTTP 400 — request body / parameters failed server-side validation.
+ * May include per-field errors in `error.fields`.
+ */
+export class ValidationError extends ExtractiaError {
+  /**
+   * @param {string}                    [message]
+   * @param {Record<string,string>|null} [fields] — Field-level errors, if the server provides them.
+   */
+  constructor(message = STATUS_MESSAGES[400], fields = null) {
+    super(message, 400, STATUS_MESSAGES[400], "VALIDATION_ERROR");
+    this.name = "ValidationError";
+    /** @type {Record<string,string>|null} */
+    this.fields = fields;
+  }
+}
+
+/** HTTP 409 — a resource with the same unique identifier already exists. */
+export class ConflictError extends ExtractiaError {
+  constructor(message = STATUS_MESSAGES[409]) {
+    super(message, 409, STATUS_MESSAGES[409], "CONFLICT");
+    this.name = "ConflictError";
+  }
+}
+
+/** HTTP 5xx — unexpected server-side failure. Always retryable. */
+export class ServerError extends ExtractiaError {
+  constructor(message = STATUS_MESSAGES[500], status = 500) {
+    super(
+      message,
+      status,
+      STATUS_MESSAGES[status] ?? STATUS_MESSAGES[500],
+      "SERVER_ERROR",
+    );
+    this.name = "ServerError";
+  }
+  isRetryable() {
+    return true;
+  }
+}
+
+/** No HTTP response — connection refused, DNS failure, etc. */
+export class NetworkError extends ExtractiaError {
+  constructor(
+    message = "Unable to reach the Extractia API. Please check your network connection and try again.",
+  ) {
+    super(message, 0, message, "NETWORK_ERROR");
+    this.name = "NetworkError";
+  }
+  isRetryable() {
+    return true;
+  }
+}
+
+/** Request timed out before the server responded. */
+export class TimeoutError extends ExtractiaError {
+  constructor(
+    message = "The request timed out. The server may be under heavy load — please try again in a moment.",
+  ) {
+    super(message, 0, message, "TIMEOUT");
+    this.name = "TimeoutError";
+  }
+  isRetryable() {
+    return true;
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Extracts a developer-friendly detail string from any server response body.
+ * Handles plain strings, `{ message }`, `{ error }`, `{ detail }`, `{ title }`,
+ * `{ errors[] }`, and Spring `{ fieldErrors[] }`.
+ *
+ * @param {any} data
+ * @returns {string|null}
+ */
+function extractServerDetail(data) {
+  if (!data) return null;
+  if (typeof data === "string" && data.trim()) return data.trim();
+  if (typeof data === "object") {
+    const msg = data.message ?? data.error ?? data.detail ?? data.title;
+    if (msg && typeof msg === "string") return msg.trim();
+    if (Array.isArray(data.errors) && data.errors.length > 0) {
+      const first = data.errors[0];
+      return typeof first === "string"
+        ? first
+        : (first.message ?? first.msg ?? JSON.stringify(first));
+    }
+    if (Array.isArray(data.fieldErrors) && data.fieldErrors.length > 0) {
+      return data.fieldErrors
+        .map((e) => `${e.field ?? "field"}: ${e.message ?? e.defaultMessage}`)
+        .join("; ");
+    }
+  }
+  return null;
+}
+
 /**
  * Maps an Axios error to the appropriate typed SDK error.
- * Falls back to a generic `ExtractiaError` for unexpected status codes.
+ * Always returns an `ExtractiaError` subclass — never re-throws.
  *
  * @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;
+  // Network / DNS / connection error — no HTTP response at all
+  if (!err.response) {
+    if (
+      err.code === "ECONNABORTED" ||
+      err.code === "ETIMEDOUT" ||
+      (err.message && err.message.toLowerCase().includes("timeout"))
+    ) {
+      return new TimeoutError();
+    }
+    return new NetworkError(err.message || undefined);
+  }
+
+  const status = err.response.status;
+  const detail = extractServerDetail(err.response.data);
+  const userMessage =
+    STATUS_MESSAGES[status] ??
+    (status >= 500
+      ? STATUS_MESSAGES[500]
+      : "Something went wrong. Please try again.");
+
+  let error;
 
   switch (status) {
+    case 400: {
+      // Collect field-level errors if available
+      const body = err.response.data;
+      const fields =
+        body?.fields ??
+        (Array.isArray(body?.fieldErrors)
+          ? Object.fromEntries(
+              body.fieldErrors.map((f) => [
+                f.field,
+                f.message ?? f.defaultMessage,
+              ]),
+            )
+          : null);
+      error = new ValidationError(detail ?? STATUS_MESSAGES[400], fields);
+      break;
+    }
     case 401:
-      return new AuthError(detail);
+      error = new AuthError(detail ?? undefined);
+      break;
     case 402:
-      return new TierError(detail);
+      // Distinguish document quota exhaustion from a plan-tier restriction
+      if (
+        detail &&
+        (detail.toLowerCase().includes("quota") ||
+          detail.toLowerCase().includes("document") ||
+          detail.toLowerCase().includes("limit reached"))
+      ) {
+        error = new QuotaError(detail);
+      } else {
+        error = new TierError(detail ?? undefined);
+      }
+      break;
     case 403:
-      return new ForbiddenError(detail);
+      error = new ForbiddenError(detail ?? undefined);
+      break;
     case 404:
-      return new NotFoundError(detail);
-    case 429:
-      return new RateLimitError(detail);
+      error = new NotFoundError(detail ?? undefined);
+      break;
+    case 409:
+      error = new ConflictError(detail ?? undefined);
+      break;
+    case 429: {
+      const retryAfterHeader = err.response.headers?.["retry-after"];
+      const retryAfter =
+        retryAfterHeader != null ? parseInt(retryAfterHeader, 10) : null;
+      error = new RateLimitError(
+        detail ?? undefined,
+        isNaN(retryAfter) ? null : retryAfter,
+      );
+      break;
+    }
     default:
-      return new ExtractiaError(detail ?? err.message, status ?? 0);
+      if (status >= 500) {
+        error = new ServerError(
+          detail ?? STATUS_MESSAGES[status] ?? STATUS_MESSAGES[500],
+          status,
+        );
+      } else {
+        error = new ExtractiaError(
+          detail ?? err.message,
+          status,
+          userMessage,
+          `HTTP_${status}`,
+        );
+      }
   }
+
+  // Always set the polished user message
+  error.userMessage = userMessage;
+
+  // Attach request correlation ID if the server provided one
+  const reqId =
+    err.response.headers?.["x-request-id"] ??
+    err.response.headers?.["x-correlation-id"] ??
+    null;
+  if (reqId) error.requestId = reqId;
+
+  return error;
 }