Google Cloud Functions

{
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "gcp-build": "tsc",
    "start": "functions-framework --target=verifyDni"
  }
}

printf 'ck_test_...' | gcloud secrets create constaia-api-key --data-file=-
printf 'whsec_...' | gcloud secrets create constaia-webhook-secret --data-file=-

import {
  AuthenticationError,
  Constaia,
  ConstaiaError,
  InsufficientCreditsError,
  InvalidRequestError,
  PermissionError,
  RateLimitError,
  type Analysis,
  type WebhookEvent,
} from "@constaia/sdk";

// Reads CONSTAIA_API_KEY from the environment.
export const constaia = new Constaia();

// What you send back to the browser (and what the widget renders): no extracted fields.
export function publicResult(analysis: Analysis) {
  const { id, object, status, document, verdict, warnings } = analysis;
  return { id, object, status, document, verdict, warnings };
}

export type HttpError = {
  status: number;
  body: { error: { code: string; message: string } };
  retryAfter?: number;
};

const httpError = (status: number, code: string, message: string, retryAfter?: number): HttpError => ({
  status,
  body: { error: { code, message } },
  retryAfter,
});

export function toHttpError(error: unknown): HttpError {
  if (error instanceof InvalidRequestError) {
    // Unreadable file, unsupported format, too many pages…: the user can fix it.
    return httpError(error.status === 413 ? 413 : 422, error.code ?? "invalid_request", error.message);
  }
  if (error instanceof RateLimitError) {
    const wait = Math.ceil(error.retryAfter ?? 1);
    return httpError(429, "rate_limited", "Too many requests. Try again in a few seconds.", wait);
  }
  if (error instanceof InsufficientCreditsError) {
    console.error("[constaia] Out of credits. Top up at https://app.constaia.com", error.requestId);
    return httpError(503, "unavailable", "Document validation is temporarily unavailable.");
  }
  if (error instanceof AuthenticationError || error instanceof PermissionError) {
    console.error("[constaia] Check CONSTAIA_API_KEY", error.code, error.requestId);
    return httpError(500, "misconfigured", "Server configuration error.");
  }
  if (error instanceof ConstaiaError) {
    // APIError (5xx), APIConnectionError, APITimeoutError
    console.error("[constaia]", error.name, error.code, error.requestId);
    return httpError(502, "upstream_error", "The document could not be analysed. Please try again.");
  }
  console.error(error);
  return httpError(500, "internal_error", "Internal error.");
}

// Dedupe by webhook-id. In production, use a table with a unique key.
const processed = new Set<string>();
export const alreadyProcessed = (webhookId: string) => processed.has(webhookId);
export const markProcessed = (webhookId: string) => void processed.add(webhookId);

export async function handleEvent(event: WebhookEvent) {
  switch (event.type) {
    case "analysis.completed":
      // event.data is the full analysis (with fields). Store it by event.data.id.
      console.log("analysis.completed", event.data.id, event.data.verdict?.status);
      break;
    case "analysis.review_required":
      console.log("Needs manual review", event.data.id);
      break;
    case "analysis.failed":
      console.warn("analysis.failed", event.data.id, event.data.error?.code);
      break;
    case "credits.low":
      console.warn("Credits running low: top up at https://app.constaia.com");
      break;
  }
}

import * as functions from "@google-cloud/functions-framework";
import busboy from "busboy";
import { WebhookVerificationError, type AnalyzeInput } from "@constaia/sdk";
import {
  alreadyProcessed,
  constaia,
  handleEvent,
  markProcessed,
  publicResult,
  toHttpError,
} from "./constaia.js";

type Upload = { buffer: Buffer; filename: string; truncated: boolean; fields: Record<string, string> };

function parseMultipart(req: functions.Request): Promise<Upload | null> {
  return new Promise((resolve, reject) => {
    const bb = busboy({ headers: req.headers, limits: { fileSize: 20 * 1024 * 1024, files: 1 } });
    const fields: Record<string, string> = {};
    let upload: Upload | null = null;

    bb.on("field", (name, value) => {
      fields[name] = value;
    });
    bb.on("file", (name, stream, info) => {
      if (name !== "file") return void stream.resume();
      const chunks: Buffer[] = [];
      stream.on("data", (chunk: Buffer) => chunks.push(chunk));
      stream.on("end", () => {
        upload = { buffer: Buffer.concat(chunks), filename: info.filename, truncated: Boolean(stream.truncated), fields };
      });
    });
    bb.on("close", () => resolve(upload));
    bb.on("error", reject);
    bb.end(req.rawBody);
  });
}

// Protect this function (IAM or a token from your login system): every call spends credits.
functions.http("verifyDni", async (req, res) => {
  if (req.method !== "POST") {
    res.status(405).end();
    return;
  }

  let input: AnalyzeInput;
  let fullName = "";

  if (req.is("multipart/form-data")) {
    const upload = await parseMultipart(req);
    if (!upload) {
      res.status(400).json({ error: { code: "missing_file", message: "No file received." } });
      return;
    }
    if (upload.truncated) {
      res.status(413).json({ error: { code: "file_too_large", message: "20 MB maximum." } });
      return;
    }
    input = { file: upload.buffer, filename: upload.filename };
    fullName = (upload.fields.full_name ?? "").trim();
  } else if (req.is("application/json") && typeof req.body?.base64 === "string") {
    input = { base64: req.body.base64, filename: String(req.body.filename ?? "document.jpg") };
    fullName = String(req.body.full_name ?? "").trim();
  } else {
    res.status(400).json({ error: { code: "missing_file", message: "Send multipart or JSON with base64." } });
    return;
  }

  try {
    const analysis = await constaia.analyze(input, {
      expect: "es_dni",
      checks: { notExpired: true, ...(fullName ? { holder: { fullName } } : {}) },
      storage: "none",
      language: "en",
    });
    // Store analysis.id and analysis.verdict in your database.
    res.status(analysis.status === "completed" ? 200 : 202).json(publicResult(analysis));
  } catch (error) {
    const { status, body, retryAfter } = toHttpError(error);
    if (retryAfter) res.set("Retry-After", String(retryAfter));
    res.status(status).json(body);
  }
});

functions.http("constaiaWebhook", async (req, res) => {
  let event;
  try {
    // req.rawBody holds the exact bytes; req.body is already parsed and useless for the signature.
    event = await constaia.webhooks.verify(req.rawBody ?? "", req.headers, process.env.CONSTAIA_WEBHOOK_SECRET!);
  } catch (error) {
    if (!(error instanceof WebhookVerificationError)) throw error;
    res.status(400).send("Invalid signature");
    return;
  }

  const webhookId = req.get("webhook-id")!;
  if (!alreadyProcessed(webhookId)) {
    await handleEvent(event);
    markProcessed(webhookId);
  }
  res.status(204).end();
});

npm run build

gcloud functions deploy verify-dni --gen2 --runtime=nodejs22 --region=europe-west1 \
  --source=. --entry-point=verifyDni --trigger-http --timeout=120s \
  --set-secrets=CONSTAIA_API_KEY=constaia-api-key:latest

gcloud functions deploy constaia-webhook --gen2 --runtime=nodejs22 --region=europe-west1 \
  --source=. --entry-point=constaiaWebhook --trigger-http --allow-unauthenticated \
  --set-secrets=CONSTAIA_API_KEY=constaia-api-key:latest,CONSTAIA_WEBHOOK_SECRET=constaia-webhook-secret:latest

{
  "id": "an_01J…",
  "object": "analysis",
  "status": "completed",
  "document": { "type": "es_dni", "label": "Spanish ID card (DNI)", "confidence": 0.97, "side": "both", "country": "ESP" },
  "verdict": {
    "expected": ["es_dni"],
    "match": true,
    "status": "valid",
    "reasons": [
      { "code": "type_match", "severity": "info", "message": "The document is Spanish ID card (DNI)." },
      { "code": "not_expired", "severity": "info", "message": "Valid until 12/03/2031." },
      { "code": "holder", "severity": "info", "message": "…" }
    ]
  },
  "warnings": []
}

npm run build && npx functions-framework --target=verifyDni --port=8080
curl -F "file=@dni_valid.jpg" -F "full_name=María García López" http://localhost:8080

curl -H "content-type: application/json" http://localhost:8080 \
  -d "{\"filename\":\"dni_valid.jpg\",\"base64\":\"$(base64 < dni_valid.jpg | tr -d '\n')\"}"