@klarefi/node

@klarefi/node

TypeScript SDK for the Klarefi API. Create hosted intake sessions, read case files, and verify signed webhooks. Zero runtime dependencies; Node 18+.

The API surface is documented at klarefi.com/docs/api.

Install

npm install @klarefi/node

Usage

import { Klarefi } from "@klarefi/node";

const klarefi = new Klarefi({
  apiKey: process.env.KLAREFI_API_KEY!, // sk_live_... or sk_test_...
  baseUrl: process.env.KLAREFI_API_BASE_URL, // Optional; defaults to https://api.klarefi.com
  maxRetries: 2, // Optional; retries only safe requests
});

// Hosted intake session (Stripe Checkout pattern): create, then redirect.
const session = await klarefi.sessions.create({
  case_type_id: "pilot_intake",
  external_case_id: "crm-12345",
  prefill: {
    field_values: {
      applicant_name: "Ada Lovelace",
      prior_reference: null,
    },
  },
});
// -> session.signed_url

// Mark your customer-side handoff complete and issue a fresh applicant token.
const handoff = await klarefi.sessions.handoff(session.session_id);
// -> handoff.signed_url, handoff.access_token

// Case status and resolved facts.
const caseFile = await klarefi.cases.retrieve(session.session_id);

// Decision-ready handoff package once the case completes.
const pkg = await klarefi.cases.getPackage(session.session_id);

Connectors

Configure the HTTP APIs the runtime calls to verify facts. Connectors are active as soon as you create or import them. There is no draft/review step, so review the functions before routing live traffic. OpenAPI import is JSON only; convert YAML specs to JSON first.

// Import from a public OpenAPI JSON URL.
await klarefi.connectors.importOpenApi({
  connector_key: "claims_api",
  openapi_url: "https://example.com/openapi.json",
});

// List, inspect, and delete.
const { connectors } = await klarefi.connectors.list();
const one = await klarefi.connectors.get("claims_api");
await klarefi.connectors.delete("claims_api");

Requires an API key with connectors:write scope (connectors:read covers the list and get calls).

Applicant agents

Applicant-plane drivers use either the signed hosted-intake URL or a per-session bearer token returned by sessions.create() or sessions.handoff(). This plane does not use a sk_live_... or sk_test_... API key.

import { IntakeSession } from "@klarefi/node/intake";

const intake = klarefi.sessions.driver({
  sessionId: handoff.session_id,
  accessToken: handoff.access_token,
});

const intakeFromSignedUrl = IntakeSession.fromSignedUrl(
  "https://app.klarefi.com/s/sess_123?token=1700000000.abcdef",
);

let state = await intake.getState();

while (state.next_action.type !== "none") {
  if (state.next_action.type === "fill_form") {
    state = await intake.saveDraft({
      claimant_name: "Ada Lovelace",
    });
  } else if (state.next_action.type === "answer") {
    state = await intake.answer("The claim number is CLM-123.");
  } else if (state.next_action.type === "upload") {
    state = await intake.uploadDocument({
      file: "./policy-card.pdf",
      mimeType: "application/pdf",
    });
  } else {
    const result = await intake.nextAction();
    state = result.state;
  }
}

getView() returns the raw hosted view context when an agent needs the full escape hatch. getState() distills that view into the current phase, next action, open tasks, progress, submit readiness, and uploaded documents.

Webhooks

Register an endpoint in the dashboard (Developer tab), store the signing secret, then verify deliveries with constructEvent, the same pattern as Stripe:

import { constructEvent, KlarefiWebhookSignatureError } from "@klarefi/node";

export async function POST(request: Request) {
  const rawBody = await request.text();

  let event;
  try {
    event = constructEvent(
      rawBody,
      request.headers.get("X-Klarefi-Signature"),
      process.env.KLAREFI_WEBHOOK_SECRET!,
    );
  } catch (error) {
    if (error instanceof KlarefiWebhookSignatureError) {
      return new Response("Invalid signature", { status: 401 });
    }
    throw error;
  }

  if (event.event_type === "v1.case.completed") {
    // Fetch the package, then acknowledge the delivery.
  }

  return Response.json({ received: true });
}

The same helpers are available on a client instance as klarefi.webhooks.constructEvent and klarefi.webhooks.verifySignature.

Errors

Every non-2xx response throws KlarefiApiError with status, code, type, and requestId. Network failures throw KlarefiConnectionError. Both extend KlarefiError.

Retries

The client automatically retries 429, 5xx, and network failures for GET requests and requests carrying an idempotency_key. It uses exponential backoff with jitter and respects Retry-After when the API sends it.

maxRetries defaults to 2, which means up to 3 total attempts. Set maxRetries: 0 to disable automatic retries.

Idempotency

sessions.create and cases.submitDocument generate an idempotency_key automatically when you do not pass one. Pass your own to make retries safe across process restarts.