TypeScript SDK for Kivel

What the SDK covers

@kivel.io/sdk is a small, dependency-free TypeScript client for the Kivel HTTP API. It works in Node.js and any runtime with fetch. Use it when you want typed methods for utilities and resources instead of building requests by hand.

Install the SDK beta with npm install @kivel.io/sdk@beta. The ESM package includes JavaScript and TypeScript declarations, requires Node.js 22.13+ and uses import rather than CommonJS require. Use an explicit beta tag or version until a latest release is promoted.

Create a client

All options are optional. baseUrl defaults to https://kivel.io and must be an origin; remote origins must use HTTPS. timeoutMs defaults to 25000. You can pass your own fetch implementation.

import { Kivel, KivelError } from '@kivel.io/sdk';

const kivel = new Kivel({
  apiKey: process.env.KIVEL_API_KEY,
});

const result = await kivel.run('json', '{"hello":true}', { action: 'format' });
console.log(result.output, result.usage.used);

Methods

Most resource creation methods default to private visibility. Webhook receivers are public by default, and OAuth test endpoints are always public while their management and logs stay private. Methods that take a token send it in X-Resource-Token, so they work alongside an API key.

Work with resources

Webhook, mock, mock MCP and file settings accept ttlSeconds, persistent and visibility; upload also accepts maxDownloads. Email requires an account and accepts activeDays (1–7, default 3) on Free, or an optional paid localPart. Free allows one active inbox; Pro 10 and Team 50 addresses that stay active while subscribed. emailInboxes() lists owned addresses; emailForwarding(id, url) configures a public webhook. inspectResource reads metadata. Use request() for other /api/ operations and /mock/ caller requests; its token is a caller access token for /mock/ paths.

const inbox = await kivel.createInbox({ ttlSeconds: 1800 });
// inbox.webhookUrl, inbox.accessToken; manage with your API key

const history = await kivel.inspectInbox(inbox.id);

const file = await kivel.upload('report.txt', new TextEncoder().encode('hello'), {
  maxDownloads: 1,
});
const bytes = await kivel.downloadFile(file.id, file.accessToken);

const mock = await kivel.inspectResource('mocks', 'MOCK_ID');
await kivel.remove('inboxes', inbox.id);

Errors

Failed requests throw KivelError with message, status, requestId (from X-Request-Id) and retryAfter (from Retry-After, in seconds). The SDK does not retry requests itself and does not follow redirects.

try {
  await kivel.run('json', input);
} catch (error) {
  if (error instanceof KivelError && error.status === 429 && error.retryAfter) {
    // wait error.retryAfter seconds, then try again
  }
  throw error;
}