extractia-sdk 1.3.0 → 1.5.0

package/src/utils.js

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

package/vitest.integration.config.js

@@ -0,0 +1,27 @@
+import { defineConfig } from "vitest/config";
+
+/**
+ * Vitest config for integration tests against the real ExtractIA API.
+ *
+ * Required env vars:
+ *   EXTRACTIA_API_TOKEN     — valid bearer token (all integration tests)
+ *   EXTRACTIA_ALLOW_WRITE   — "true" to enable create/update/delete tests
+ *   EXTRACTIA_ALLOW_CREDITS — "true" to enable tests that consume doc/AI credits
+ *
+ * Run:
+ *   EXTRACTIA_API_TOKEN=sk_xxx EXTRACTIA_ALLOW_WRITE=true EXTRACTIA_ALLOW_CREDITS=true \
+ *     npm run test:integration
+ */
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["tests/integration/**/*.integration.test.js"],
+    // Real HTTP calls — 30 s per test, 30 s for setup/teardown hooks
+    testTimeout: 30_000,
+    hookTimeout: 30_000,
+    // Sequential: avoid hammering the API and triggering rate-limits
+    sequence: { concurrent: false },
+    reporters: ["verbose"],
+  },
+});