# SDKs and CLI
Install the Klarefi TypeScript SDK and CLI
Source: https://www.klarefi.com/docs/api/sdks

Use the TypeScript SDK in application code. Use the CLI to check credentials,
create test sessions, scaffold webhook handlers, and work with connector
manifests.

> **Canonical API base URL**
>
> Production integrations use `https://www.klarefi.com`. A workspace-specific
> Convex HTTP URL shown in **Settings → Developer** remains valid for direct
> regional access.

<span id="current-setup" />

## Install

```bash
npm install @klarefi/node
npx klarefi --help
```

For repeated CLI use:

```bash
npm install -g klarefi
klarefi --help
```

The packages are:

| Package         | Use for                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------- |
| `@klarefi/node` | Server-side TypeScript calls, webhook signature helpers, and the applicant-plane intake client |
| `klarefi`       | Local setup, diagnostics, webhook tests, connector manifests                                   |
| `@klarefi/mcp`  | Local fallback for the hosted stateless MCP endpoint at `https://www.klarefi.com/mcp`          |

To drive a hosted intake session with an agent, over REST, the SDK, or MCP,
see [Agent intake](/docs/guides/agent-intake).

## Configure

Set your API key in the environment:

```bash
export KLAREFI_API_KEY="sk_test_..."
export KLAREFI_BASE_URL="https://www.klarefi.com"
export KLAREFI_API_BASE_URL="https://www.klarefi.com"
```

Then verify the key:

```bash
npx klarefi whoami
npx klarefi doctor
```

The TypeScript SDK reads `KLAREFI_BASE_URL`; the CLI reads
`KLAREFI_API_BASE_URL`. Set both to the dashboard value. The SDK resolves its
URL as constructor `baseUrl`, then `KLAREFI_BASE_URL`, then
`https://www.klarefi.com` as the production fallback.

You can also store the key for local CLI use:

```bash
npx klarefi login --api-key sk_test_...
```

## Create a hosted intake session

Create the session from your backend and redirect the applicant to
`signed_url`:

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

const klarefi = new Klarefi({
  apiKey: process.env.KLAREFI_API_KEY!,
});

const session = await klarefi.sessions.create({
  case_type_id: "motor_claim",
  external_case_id: "claim_12345",
  external_applicant_id: "applicant_789",
  idempotency_key: "session_claim_12345",
  locale: "nl",
});

console.log(session.signed_url);
```

For a quick local check:

```bash
npx klarefi sessions create \
  --case-type motor_claim \
  --external-case-id claim_12345 \
  --url-only
```

## Read the case

```ts
const caseFile = await klarefi.cases.retrieve(session.session_id);
const events = await klarefi.cases.events(session.session_id, {
  afterCursor: 0,
  limit: 100,
});
if (events.has_more) {
  // Poll again with afterCursor: events.next_cursor.
}
const pkg = await klarefi.cases.getPackage(session.session_id);
```

The operator and workflow surface is also available in the SDK:

```ts
// cases:read
const workspace = await klarefi.cases.getWorkspace(session.session_id);

// cases:review. The SDK generates an idempotency key when omitted.
// API keys cannot complete or reopen cases.
const command = await klarefi.cases.review(session.session_id, {
  command_type: "approve_fact",
  payload: { fact_id: "incident_date" },
});

// cases:read
const result = await klarefi.cases.getCommand(
  session.session_id,
  command.command_id,
);

// cases:review
const queue = await klarefi.operator.listQueue({ limit: 25 });

// workflows:read and workflows:write
const { workflows } = await klarefi.workflows.list();
const draft = await klarefi.workflows.saveDraft(workflowDeclaration);

// privacy:erase
const receipt = await klarefi.documents.erase("doc_def456");
```

`workflows.saveDraft()` validates and saves a draft. It cannot publish or
activate a workflow; publishing remains human-controlled.

CLI equivalents:

```bash
npx klarefi cases get 550e8400-e29b-41d4-a716-446655440000
npx klarefi cases events 550e8400-e29b-41d4-a716-446655440000
npx klarefi cases package 550e8400-e29b-41d4-a716-446655440000
```

## Webhook verification

Scaffold a receiver:

```bash
npx klarefi webhooks init --framework next
```

Verify signatures in code with the raw request body:

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

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

  try {
    const event = constructEvent(
      rawBody,
      request.headers.get("X-Klarefi-Signature"),
      process.env.KLAREFI_WEBHOOK_SECRET!,
    );

    if (event.event_type === "v1.case.completed") {
      // Read the case package and update your system of record.
    }

    return Response.json({ received: true });
  } catch (error) {
    if (error instanceof KlarefiWebhookSignatureError) {
      return new Response("Invalid signature", { status: 401 });
    }
    throw error;
  }
}
```

Send a signed test delivery:

```bash
npx klarefi webhooks test \
  --endpoint-url https://your-app.example.com/webhooks/klarefi \
  --signing-secret whsec_your_signing_secret
```

Verify a captured payload locally:

```bash
npx klarefi webhooks verify \
  --payload payload.json \
  --signature "t=1704067200,v1=..." \
  --secret whsec_your_signing_secret
```

## Connectors

Connector CLI commands shown below build, validate, and test local manifests;
they do not install them. The public connector API and TypeScript SDK can
create, import, list, inspect, and delete active remote connectors. Connector
create/import calls go live immediately, so review functions and credentials
before routing traffic.

```bash
npx klarefi connectors init --name "Claims API"
npx klarefi connectors infer --from .
npx klarefi connectors validate klarefi.connector.json
npx klarefi connectors test klarefi.connector.json \
  --function lookup_record \
  --input fixtures/connector-input.json
```

Use `--send` with `connectors test` only when the manifest points at a safe test
endpoint.

## Errors

Non-2xx API responses throw `KlarefiApiError` with `status`, `code`, `type`,
and `requestId`. Network failures throw `KlarefiConnectionError`.

## Use with AI

Agents can read the docs as plain text:

```bash
export KLAREFI_DOCS_URL="https://www.klarefi.com"

curl "$KLAREFI_DOCS_URL/llms.txt"
curl "$KLAREFI_DOCS_URL/llms-full.txt"
curl "$KLAREFI_DOCS_URL/docs-source/api/quickstart"
```