JavaScript and TypeScript SDK

import { Constaia } from "@constaia/sdk";

export const constaia = new Constaia({
  apiKey: process.env.CONSTAIA_API_KEY, // default: process.env.CONSTAIA_API_KEY
  baseUrl: "https://api.constaia.com", // default; or CONSTAIA_BASE_URL
  timeout: 60_000, // ms per attempt
  maxRetries: 2, // on 429, 408, 409 idempotency_in_progress, 5xx and network errors
  maxConcurrency: 4, // requests in flight at once; the rest wait in a queue
});

import { Constaia } from "@constaia/sdk";
import { fromPath } from "@constaia/sdk/node";

const constaia = new Constaia();

const analysis = await constaia.analyze(await fromPath("./dni_valid.jpg"), {
  expect: ["es_dni", "es_nie", "passport"],
  checks: {
    notExpired: true,
    minAgeYears: 18,
    holder: { fullName: "María García López", documentNumber: "12345678Z" },
  },
  storage: "none",
  metadata: { registration_id: "123" },
  language: "en",
});

switch (analysis.verdict?.status) {
  case "valid":
    console.log("OK", analysis.fields.document_number?.value);
    break;
  case "invalid":
    console.log(analysis.verdict.reasons.filter((r) => r.severity === "error").map((r) => r.message));
    break;
  case "review":
    console.log("Manual review", analysis.warnings);
    break;
}

const c = await constaia.classify(await fromPath("./invoice.pdf"), { expect: "invoice" });
console.log(c.document?.type, c.candidates, c.verdict?.status);

const one = await constaia.analyses.get("an_01J…");

// One page (await) …
const page = await constaia.analyses.list({ limit: 50, status: "completed", metadata: { event: "42" } });
console.log(page.data.length, page.has_more);

// … or every page (for await)
for await (const a of constaia.analyses.list({ type: "es_dni" })) {
  console.log(a.id, a.verdict?.status);
}

// The 200 most recent
const recent = await constaia.analyses.list().toArray(200);

await constaia.analyses.delete("an_01J…");

import { writeFile } from "node:fs/promises";

const res = await constaia.analyses.export("an_01J…", "xlsx"); // Response
await writeFile("analysis.xlsx", Buffer.from(await res.arrayBuffer()));

const batch = await constaia.batches.create({
  items: [
    { fileUrl: "https://example.com/receipt-1.pdf" },
    { fileUrl: "https://example.com/receipt-2.pdf", options: { checks: { expectedAmount: 45 } } },
  ],
  options: { expect: "payment_receipt", export: ["xlsx"] },
});

// Or uploading files (multipart files[])
const batch2 = await constaia.batches.create({
  files: [await fromPath("./a.pdf"), await fromPath("./b.pdf")],
  options: { expect: "invoice" },
});

const current = await constaia.batches.get(batch.id);

const types = await constaia.documentTypes.list({ language: "en" }); // array
const dni = await constaia.documentTypes.get("es_dni", { language: "en" });

const balance = await constaia.balance();
console.log(balance.credits_available + balance.free_tier_remaining);

const usage = await constaia.usage({ from: "2026-09-01", to: "2026-09-30" });

const endpoint = await constaia.webhookEndpoints.create({
  url: "https://example.com/webhooks/constaia",
  events: ["analysis.completed", "analysis.review_required", "batch.completed"],
});
console.log(endpoint.secret); // whsec_… — only shown now: store it

const endpoints = await constaia.webhookEndpoints.list(); // array
const same = await constaia.webhookEndpoints.get(endpoint.id);
await constaia.webhookEndpoints.delete(endpoint.id);

import { Constaia, WebhookVerificationError } from "@constaia/sdk";

const constaia = new Constaia();

export async function POST(request: Request) {
  const raw = await request.text();
  try {
    const event = await constaia.webhooks.verify(raw, request.headers, process.env.CONSTAIA_WEBHOOK_SECRET!);
    if (event.type === "analysis.completed") {
      console.log(event.data.id, event.data.verdict?.status);
    }
    return new Response(null, { status: 204 });
  } catch (err) {
    if (err instanceof WebhookVerificationError) return new Response("invalid signature", { status: 400 });
    throw err;
  }
}

import { signWebhook, verifyWebhook } from "@constaia/sdk";

const event = await verifyWebhook(raw, headers, secret, { tolerance: 300 });

// In your tests: build signed headers like Constaia's
const body = JSON.stringify({ type: "analysis.completed", created_at: new Date().toISOString(), data: {} });
const signed = await signWebhook(body, "whsec_…");

import {
  ConstaiaError,
  InsufficientCreditsError,
  InvalidRequestError,
  RateLimitError,
} from "@constaia/sdk";

try {
  await constaia.analyze(file, { expect: "es_dni" });
} catch (err) {
  if (err instanceof InvalidRequestError) console.log(err.code, err.param);
  else if (err instanceof InsufficientCreditsError) alertBilling();
  else if (err instanceof RateLimitError) console.log(`retry in ${err.retryAfter} s`);
  else if (err instanceof ConstaiaError) console.log(err.status, err.type, err.requestId);
  else throw err;
}

const controller = new AbortController();

await constaia.analyze(file, { expect: "es_dni" }, {
  idempotencyKey: "registration-123-id", // your own, to dedupe across processes
  timeout: 90_000,
  maxRetries: 4,
  signal: controller.signal,
  headers: { "X-Trace": "abc" },
});