Kairo SDK (TypeScript/JavaScript)

The official TypeScript SDK for Kairo Payment Orchestration. Integrates cleanly with Node.js, Next.js, and browser environments.

Installation

npm install @kairo/sdk

Usage

Initialize Client

import { Kairo } from "@kairo/sdk";

const kairo = new Kairo({
  apiKey: "pk_dev_xxxxxx",
  // baseUrl: "http://localhost:8080" // Optional: default is https://api.kairo.dev
});

Payments

Create a Payment

try {
  const payment = await kairo.payments.create({
    amount: 1000, // in cents (e.g. 10.00 USD)
    currency: "usd",
    metadata: { orderId: "123" }
  });
  console.log("Payment Created:", payment.id, payment.status);
} catch (err) {
  console.error("Error creating payment:", err);
}

Retrieve a Payment

try {
  const payment = await kairo.payments.retrieve("payment_uuid");
  console.log("Payment details:", payment.id, payment.status, "Refunded:", payment.refunded_amount);
} catch (err) {
  console.error("Error getting payment:", err);
}

Refunds

Create a Refund (Full or Partial)

try {
  const refund = await kairo.refunds.create({
    payment_id: "payment_uuid",
    amount: 500 // Optional: amount in cents for partial refund. Defaults to full amount.
  });
  console.log("Refund details:", refund.id, refund.status, refund.amount);
} catch (err) {
  console.error("Error creating refund:", err);
}

Retrieve a Refund

try {
  const refund = await kairo.refunds.retrieve("refund_uuid");
  console.log("Refund details:", refund);
} catch (err) {
  console.error("Error retrieving refund:", err);
}

List Refunds for a Payment

try {
  const refunds = await kairo.refunds.list("payment_uuid");
  console.log("Refunds list:", refunds);
} catch (err) {
  console.error("Error listing refunds:", err);
}

Usage & Plans

Retrieve API Usage Stats

try {
  const usage = await kairo.usage.get();
  console.log("Usage stats:", usage.payments_used, "/", usage.payment_limit);
} catch (err) {
  console.error("Error getting usage stats:", err);
}

Retrieve API Plan Details

try {
  const plan = await kairo.plan.get();
  console.log("Current Plan:", plan.plan, "Features:", plan.features);
} catch (err) {
  console.error("Error getting plan:", err);
}

Backwards Compatibility

Legacy flat methods remain available but are marked as @deprecated and will be removed in a future major version:

// Legacy style - still functional:
const payment = await kairo.createPayment({ amount: 1000, currency: "usd" });
const fetched = await kairo.getPayment(payment.id);
const refund = await kairo.refund(payment.id);

Error Handling

The SDK exposes specific typed errors mapped from API responses:

import { 
  ValidationError, 
  AuthenticationError, 
  ForbiddenError, 
  NotFoundError, 
  RateLimitError, 
  ServerError, 
  NetworkError 
} from "@kairo/sdk";

try {
  await kairo.payments.create({ amount: 1000, currency: "usd" });
} catch (err) {
  if (err instanceof ValidationError) {
    console.error("Validation error:", err.message);
  } else if (err instanceof AuthenticationError) {
    console.error("Authentication failed:", err.message);
  } else if (err instanceof ForbiddenError) {
    console.error("Forbidden action:", err.message);
  } else if (err instanceof NotFoundError) {
    console.error("Resource not found:", err.message);
  } else if (err instanceof NetworkError) {
    console.error("Network or timeout error:", err.message);
  } else {
    console.error("An unexpected error occurred:", err);
  }
}