SDK de JavaScript y TypeScript

npm i @constaia/sdk
# o: pnpm add @constaia/sdk · yarn add @constaia/sdk · bun add @constaia/sdk

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

const constaia = new Constaia(); // lee CONSTAIA_API_KEY del entorno

// o con opciones explícitas
const constaia2 = new Constaia({
  apiKey: process.env.CONSTAIA_API_KEY,
  timeout: 60_000, // ms por intento (por defecto 60 000)
  maxRetries: 2,   // reintentos en 429, 5xx y errores de red (por defecto 2)
});

constaia.livemode; // true con ck_live_, false con ck_test_

import { Constaia } from "@constaia/sdk";
import { fromPath } from "@constaia/sdk/node"; // solo Node, Bun y Deno

const constaia = new Constaia();

const analysis = await constaia.analyze(await fromPath("dni_valid.jpg"), {
  expect: "es_dni",
  checks: { notExpired: true, holder: { fullName: "María García López" } },
  storage: "none",
  language: "es",
});

analysis.verdict?.status;               // "valid" | "invalid" | "review"
analysis.verdict?.reasons;              // [{ code, severity, message }]
analysis.fields.document_number?.value; // "12345678Z"
analysis.warnings;                      // ["blurry", …]

const result = await constaia.classify(await fromPath("passport.jpg"), { expect: ["es_dni", "passport"] });
result.document.type;   // "passport"
result.candidates;      // [{ type, confidence }, …]
result.verdict?.status; // solo si pasas expect

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

// Una página
const page = await constaia.analyses.list({ limit: 20, status: "completed", type: "es_dni" });
page.data; page.has_more;

// Todas las páginas: el SDK sigue el cursor por ti
for await (const a of constaia.analyses.list({ metadata: { registration_id: "123" } })) {
  console.log(a.id);
}
const first100 = await constaia.analyses.list().toArray(100);

await constaia.analyses.delete("an_01J…"); // { id, deleted: true }

const res = await constaia.analyses.export("an_01J…", "xlsx"); // Response
const bytes = await res.arrayBuffer();

const batch = await constaia.batches.create({
  files: [await fromPath("dni_valid.jpg"), await fromPath("nie.jpg")],
  options: { expect: ["es_dni", "es_nie"], export: ["xlsx"] },
});

// o con URLs y opciones por documento
await constaia.batches.create({
  items: [{ fileUrl: "https://example.com/1.jpg", options: { expect: "es_dni" } }],
});

await constaia.batches.get(batch.id);

const types = await constaia.documentTypes.list();   // DocumentTypeInfo[]
const dni = await constaia.documentTypes.get("es_dni");

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

// Alta de endpoints
const endpoint = await constaia.webhookEndpoints.create({
  url: "https://tuapp.example/webhooks/constaia",
  events: ["analysis.completed", "analysis.failed"],
});
endpoint.secret; // whsec_… (solo en la creación)

// Verificación (Standard Webhooks, tolerancia de 5 minutos)
const event = await constaia.webhooks.verify(rawBody, request.headers, process.env.CONSTAIA_WEBHOOK_SECRET!);

const controller = new AbortController();

await constaia.analyze(file, { expect: "es_dni" }, {
  idempotencyKey: `registration-123-dni`, // si no la pasas, el SDK genera una
  timeout: 90_000,
  maxRetries: 0,
  signal: controller.signal,
  headers: { "X-Trace": "abc" },
});

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

try {
  await constaia.analyze(file, { expect: "es_dni" });
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    // avisa al administrador, compra un pack
  } else if (err instanceof InvalidRequestError && err.code === "unsupported_file_type") {
    // pide otro formato al usuario
  } else if (err instanceof RateLimitError) {
    console.log(`Reintenta en ${err.retryAfter} s`);
  } else {
    throw err;
  }
}