TypeScript SDK

Use @tansohq/sdk with your self-hosted Tanso instance

The official @tansohq/sdk package is typed, dependency-free, and supports Node.js 18 or newer.

npm install @tansohq/sdk

import { TansoClient } from "@tansohq/sdk";

const tanso = new TansoClient(process.env.TANSO_API_KEY!, {
  baseUrl: process.env.TANSO_BASE_URL ?? "http://localhost:8080",
});

Create the client only in server-side code. A Tanso API key authenticates the whole account and must never enter a browser bundle.

Tanso is self-hosted, so baseUrl points at your own instance. From SDK 0.2.2 the default is http://localhost:8080 — the quickstart compose stack — so local development works with no configuration.

The integration loop

const requestId = crypto.randomUUID();

// 1. Check before incurring provider cost.
const decision = await tanso.entitlements.evaluate({
  customerReferenceId: "demo-user",
  featureKey: "ai.chat",
  usage: {
    eventName: "ai.chat.generate",
    usageUnits: 1,
    model: "gpt-4.1-mini", // selects the credit weight row (sdk >= 0.3.0)
  },
  context: {
    idempotencyKey: `check-${requestId}`,
    flowId: requestId,
  },
});

if (!decision.allowed) {
  return deny(decision.meta?.reason?.description);
}
// decision.creditQuote holds what this would burn — a quote, not a promise;
// the charge resolves at the event's occurredAt. See /credit-weights.

// 2. Perform the billable work.
const result = await runModel();

// 3. Record usage, unit economics, and one credit deduction.
await tanso.events.ingest({
  customerReferenceId: "demo-user",
  featureKey: "ai.chat",
  eventName: "ai.chat.completed",
  eventIdempotencyKey: `usage-${requestId}`,
  flowId: requestId,
  usageUnits: 1,
  costAmount: result.providerCost,
  revenueAmount: 0.02,
  costInput: {
    model: "gpt-4.1-mini",
    modelProvider: "openai",
    inputTokens: result.inputTokens,   // requires @tansohq/sdk >= 0.2.1
    outputTokens: result.outputTokens,
  },
});

Surface

Resource	Methods
customers	create, get, update
subscriptions	create, cancel, revertCancellation, changePlan, cancelScheduledChange
entitlements	check, evaluate, list
events	ingest
plans	list
features	list, get
credits	listPools, getPool, listGrants, listTransactions
billing	listInvoices, markPaid, createCheckoutSession

Errors are typed

import {
  TansoApiError,
  TansoAuthenticationError,
  TansoConflictError,
  TansoNetworkError,
  TansoNotFoundError,
} from "@tansohq/sdk";

try {
  await tanso.events.ingest(event);
} catch (error) {
  if (error instanceof TansoConflictError) {
    // A duplicate eventIdempotencyKey or depleted hard-limit pool.
  } else if (error instanceof TansoApiError) {
    console.error(error.statusCode, error.detail);
  }
}

TansoApiError exposes statusCode and optional detail. Authentication, not-found, conflict, and network failures have their own subclasses.

The included Next.js example uses the published package and is the canonical integration.

List responses return { items, pagination }. The client unwraps Tanso’s top-level { success, data, error } envelope and throws on non-success responses.