@karta.sh/sdk

Lightweight TypeScript SDK for the Karta API. No runtime dependencies — uses native fetch (Node ≥ 18.17 or any modern browser). The full machine-readable OpenAPI description is served by the Karta backend at https://karta.sh/openapi.json.

Install

npm install @karta.sh/sdk

Quick start

import { Karta } from "@karta.sh/sdk";

const karta = new Karta({
  apiKey: process.env.KARTA_API_KEY!, // "kt_live_…"
  // baseUrl is optional; defaults to https://karta.sh (the control API)
});

// List API keys
const keys = await karta.apiKeys.list();

// Create one (the plaintext `secret` is returned exactly once)
const { api_key, secret } = await karta.apiKeys.create("ci-runner", ["write"]);
console.log("Store this now, it won't be shown again:", secret);

// Store a BYOK provider key (encrypted at rest server-side)
await karta.modelKeys.create("anthropic", process.env.ANTHROPIC_API_KEY!, "primary");

// Manage webhook endpoints
const { webhook_endpoint, secret: signingSecret } = await karta.webhookEndpoints.create({
  url: "https://example.com/karta-webhook",
  event_types: ["subscription.created", "invoice.paid"],
});

// Usage + billing
const usage = await karta.usage.summary();
const billing = await karta.billing.status();

Errors

Every 4xx/5xx response throws a typed KartaError subclass that preserves status and the parsed JSON body:

import { KartaValidationError } from "@karta.sh/sdk";

try {
  await karta.apiKeys.create("");
} catch (e) {
  if (e instanceof KartaValidationError) {
    console.warn(e.body); // { error: "validation_failed", message: "Name is required" }
  } else {
    throw e;
  }
}

Subclasses: KartaAuthError (401), KartaForbiddenError (403), KartaNotFoundError (404), KartaValidationError (422). Anything else throws the base KartaError.

Development

npm install
npm run build   # tsc → ./dist
npm test        # vitest against a stub fetch

Surface

| Resource | Methods | | -------------------- | ---------------------------------------------------------------------- | | apiKeys | list(), create(name, scopes?), revoke(id) | | modelKeys | list(), create(provider, plaintext, name?), revoke(id) | | webhookEndpoints | list(), create(params), update(id, params), delete(id) | | usage | summary() | | billing | status() |

Auth is Bearer-only here. The browser dashboard talks to the same endpoints over a Devise session cookie — see the OpenAPI doc.