# 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 workflowDeclaration = workflows[0];
if (!workflowDeclaration) throw new Error("No workflow available to update");
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 can build, validate, test, and install connector
manifests. The public connector API and TypeScript SDK can also create, import,
list, inspect, and delete remote connectors. When connector approvals are
enabled, create, import, and delete operations are staged until an operator
approves them.

```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
npx klarefi connectors push klarefi.connector.json
npx klarefi connectors import-openapi \
  --key claims-api \
  --url https://example.com/openapi.json
```

Use `--send` with `connectors test` only when the manifest points at a safe test
endpoint. OpenAPI imports accept JSON only; convert YAML documents to JSON
first. Check `approval_required` and `approval_status` after a remote connector
operation before routing verification traffic.

## 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"
```