@kalir/sdk

Official TypeScript SDK for the Kalir Public API: your organization's digital-risk intelligence (incidents, credential and infostealer exposure, phishing impersonation, dark-web and Telegram mentions) plus signed webhooks.

• Every path, parameter and response is typed from the OpenAPI spec.
• Errors throw KalirError with a stable type.
• Rate-limited requests (429) are retried automatically, honoring retry_after.
• Webhook signature verification works in Node 18+, Deno, Bun and edge runtimes.

npm install @kalir/sdk

Quickstart

Create an API key at app.kalir.io → Developers → API Keys.

import { createKalirClient } from "@kalir/sdk";

const kalir = createKalirClient({ apiKey: process.env.KALIR_API_KEY! });

// Whole posture in one call
const { data: overview } = await kalir.GET("/v1/overview");
console.log(overview?.risk_score, overview?.incidents?.open_critical);

// Open incidents
const { data: incidents } = await kalir.GET("/v1/incidents", {
  params: { query: { bucket: "open", limit: 20 } },
});

// Domains impersonating you, confirmed only
const { data: phishing } = await kalir.GET("/v1/phishing", {
  params: { query: { verdict: "confirmed" } },
});

// Dark-web mentions since a date
const { data: mentions } = await kalir.GET("/v1/mentions", {
  params: { query: { source: "darkweb", since: "2026-09-01T00:00:00Z" } },
});

Errors

import { KalirError } from "@kalir/sdk";

try {
  await kalir.GET("/v1/phishing");
} catch (err) {
  if (err instanceof KalirError) {
    console.error(err.type, err.status, err.message); // e.g. "permission_error" 403
  }
}

| type | Meaning | |---|---| | authentication_error | Missing, invalid or expired key | | permission_error | Key lacks the required scope | | plan_limit_error | Your plan doesn't include this capability | | rate_limit_error | Too many requests (auto-retried up to maxRetries) | | invalid_request_error / not_found_error / api_error | See message |

Webhooks

Verify every delivery before trusting it. Pass the raw body:

import { constructWebhookEvent, WebhookSignatureError } from "@kalir/sdk";

// Express example — use express.raw() for this route
app.post("/kalir-webhooks", express.raw({ type: "application/json" }), async (req, res) => {
  try {
    const event = await constructWebhookEvent(
      req.body,                                  // Buffer / raw string
      req.header("X-Kalir-Signature"),
      process.env.KALIR_WEBHOOK_SECRET!,         // whsec_…
    );
    switch (event.type) {
      case "incident.created":
        // open a ticket, page on-call, …
        break;
      case "phishing.detected":
        break;
    }
    res.sendStatus(200);
  } catch (err) {
    if (err instanceof WebhookSignatureError) return res.sendStatus(400);
    throw err;
  }
});

Respond 2xx within 15 seconds. Failed deliveries are retried with exponential backoff for ~20 hours; deduplicate on X-Kalir-Event-Id.

Options

createKalirClient({
  apiKey: "klr_…",
  baseUrl: "https://api.kalir.io", // default
  maxRetries: 2,                   // 429 retries; 0 disables
  fetch: customFetch,              // optional
});

Full reference: https://app.kalir.io/developers/docs