extractia-sdk 1.3.0 → 1.4.0

package/src/errors.js

@@ -1,95 +1,333 @@
 /**
- * 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;
 }

package/src/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;