TypeScript SDK

Install

npm install neltava

Zero dependencies; Node 18+, Bun, Deno and edge runtimes. The client reads NELTAVA_AGENT_KEY and NELTAVA_API_URL from the environment when you don’t pass them. Use the agent’s own key — it can only ask for decisions as that agent.

Authorize a spend

One call, right before the agent pays:

import { Neltava } from "neltava";

const neltava = new Neltava(); // NELTAVA_AGENT_KEY

const d = await neltava.authorize({
  task: "Q4 pipeline: enterprise developer leads",
  action: {
    merchant: "Platform Weekly",
    amount: 90.00,
    currency: "USD",
    description: "Sponsored slot reaching platform engineers at enterprise companies",
  },
});

if (d.proceed) {
  // pay d.amount — in Enforce, through your payment adapter with d.capability
}

The decision

Attach the steps

Purpose checks are sharper with the agent’s own account of how it got here. A run collects steps (kinds: search, evaluate, select, tool_call, purchase, other) and sends them with the request. They are evidence, never instructions.

const run = neltava.run("Find enterprise developer leads");
run
  .step("Compared three data vendors", "evaluate")
  .step("Picked Clearbit", "select", "vendor_search");

const d = await run.authorize({
  action: { merchant: "Clearbit", amount: 49, currency: "USD", description: "Enrichment credits" },
});

Report outcomes

After paying — or failing to — report what happened, so budgets and the report reflect real spend:

await neltava.reportOutcome(d.decisionId!, {
  type: "SPEND_EXECUTED",   // SPEND_FAILED · SPEND_CANCELLED · REFUNDED · PARTIALLY_REFUNDED
  amount: 49,
  currency: "USD",
  externalReference: charge.id, // makes a retried report idempotent
});

An agent’s report is recorded as CLIENT_REPORTED. It never releases reserved budget; a payment adapter’s PAYMENT_RAIL report does. See outcomes and budget.

When Neltava can’t be reached

Requests retry network errors, timeouts, 429 and 5xx with the same idempotency key, so a retry never creates a second decision. After that, onUnavailable decides:

A response that doesn’t look like a decision is treated as unavailable — it never lets money move. Fallback decisions carry source: "fallback" and reasonCode: "NELTAVA_UNAVAILABLE".

Errors

import { Neltava, NeltavaError, NeltavaUnavailableError } from "neltava";

try {
  const d = await neltava.authorize({ action });
} catch (err) {
  if (err instanceof NeltavaUnavailableError) {
    // network, timeout, 5xx or 429 after retries (err.rateLimited on 429)
  } else if (err instanceof NeltavaError) {
    // the API refused the request: err.status, err.code, err.requestId
  }
}

Error codes are listed in the HTTP API reference.

Options

amount follows the currency’s minor unit (USD 49.99, JPY 5000, KWD 1.250); pass amountMinor for exact integers.

More methods

neltava.authority(slug)

The agent’s current authority and its version — for an agent that plans within its limits.

neltava.agent(slug)

The agent’s record: status, mode, current authority version.

neltava.consumeCapability(…)

For your payment service, with a Payment adapter key — never the agent’s: spends the capability for the exact payment you’re about to make, or throws (capability_used, payee_mismatch, amount_exceeds_capability…). See Enforce at the payment point.