TypeScript SDK

The TypeScript SDK is published as @certscore/sdk. Use version 0.2.8 or newer for API v2 scan creation in EU-Germany, EU-Ireland, and California, typed no-account allowance, completed-limited no-go results, API v2 scan timing fields, and client attribution headers. Source and examples live in packages/certscore-sdk.

npm install @certscore/sdk

SDK requests identify themselves with X-CertScore-Client: sdk by default. The optional clientName setting is reserved for trusted integrations that share the SDK runtime with MCP.

A scan that reached a blocked, placeholder, prelaunch, error, or otherwise unusable page resolves normally withstatus: completed_limited. Inspect the typed noGo object for customer-safe messaging, attribution, retry guidance, and a bounded evidence excerpt.

const scan = await certscore.scans.wait(created);

if (scan.resultDisposition === "no_go" && scan.noGo) {
  console.log(scan.noGo.title);
  console.log(scan.noGo.explanation);
  console.log(scan.noGo.limitationKind);
  console.log(scan.noGo.recommendedNextAction);
  console.log(scan.noGo.evidenceExcerpt ?? "No excerpt retained");
}

import { CertScoreClient } from "@certscore/sdk";

const certscore = new CertScoreClient({
  apiKey: process.env.CERTSCORE_API_KEY
});

const created = await certscore.scans.create("https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html", {
  freshness: "latest",
  scanFrom: "eu_ie"
});

const completed = await certscore.scans.wait(created);
const scanId = completed.scanId;

const status = await certscore.scans.status(scanId);
const findings = await certscore.findings.list(scanId);
const preConsentTable = await certscore.scans.preConsentCookiesTrackers(scanId);
const latest = await certscore.domains.latest("ergoveritas.com");
const latestPreConsentTable = await certscore.domains.latestPreConsentCookiesTrackers("ergoveritas.com");

console.log(status.status, findings.findings.length, preConsentTable.summary.rowCount, latest.scan?.scanId, latestPreConsentTable.summary.rowCount);

API v2 scan resources and status responses include startedAt, completedAt, and scanTimeSeconds when timing evidence is available. Treat null as unavailable rather than zero.

const scan = await certscore.scans.get(scanId);
const status = await certscore.scans.status(scanId);

console.log(scan.startedAt, scan.completedAt, scan.scanTimeSeconds);
console.log(status.startedAt, status.completedAt, status.scanTimeSeconds);