TypeScript SDK Overview

​

What it solves, in 30 seconds

1. Proposes the action to Parmana as a Business Transaction (what, why, who, and the facts a policy needs to decide).
2. Parmana decides, synchronously, evaluating a named policy version against those facts (amount limits, verification state, risk score, whatever the policy declares).
3. Your system executes only if the decision is APPROVED — the SDK call throws ExecutionRejectedError otherwise, there’s no path where a rejected transaction silently proceeds.
4. Proof is recorded: an ExecutionTrustRecord, signed (Ed25519 or ML-DSA-65, see Choose a signature provider), independently verifiable without trusting Parmana itself.

​

When to use it

• You have an AI agent (LangChain.js, the Vercel AI SDK, a custom loop) that takes actions with real consequences.
• You need a durable, signed record of who did what, when, and under which policy — not just an application log line.
• You want a named, versioned policy to decide, instead of an if/else chain buried in the agent’s own code.
• You’re wiring an agent to a real system — a payment provider, a CRM, a vendor API — and don’t want that system’s credentials anywhere near agent-generated text.

​

Core concepts

BusinessTransaction  →  Runtime decision   →  Execution   →  ExecutionTrustRecord
(what you propose)      (policy evaluates)    (if approved)  (signed proof, returned
                                                               from the same call)

• BusinessTransaction — the request: an authority (who), an authorization (why — the stated purpose), an intent (what — action, target, parameters), a policy reference (name + version + schema version), and signals (the facts the policy evaluates). You build one with createBusinessTransaction() rather than assembling these five nested objects and their cross-referenced ids by hand.
• ExecutionTrustRecord — the response: the transaction as accepted, the decision (outcome: "APPROVED" | "REJECTED", which policy rule matched), the execution outcome and evidence if it ran, and a signature block you or anyone else can verify independently (see Verify independently).
• Policy — a named, versioned document your Runtime deployment loads (PARMANA_POLICY_DIR), not something the SDK defines. See Write your first policy.
• Signals — the facts a policy’s rules reference. Every signal a rule needs must be present, and any boundSignals a policy declares are cross-checked against the matching intent field before evaluation runs at all — a mismatch is rejected as a binding-tamper attempt, not silently ignored (see Content binding & TOCTOU).

​

Install

npm install @parmana/sdk

​

Quick example

import {
  ParmanaClient,
  HttpTransport,
  createBusinessTransaction,
  ExecutionRejectedError,
} from "@parmana/sdk";

const endpoint = "http://localhost:3000";
const apiKey = process.env.PARMANA_API_KEY; // omit only for local dev against a server
// started with PARMANA_AUTH_DISABLED=true

const client = new ParmanaClient({
  endpoint,
  apiKey,
  transport: new HttpTransport({ endpoint, apiKey }),
});

const transaction = createBusinessTransaction({
  principalId: "ai-agent-001",
  purpose: "Vendor payment approval",
  action: "vendor-payment",
  target: "vendor/vendor-123",
  parameters: { amount: 100, currency: "USD" },
  policy: { name: "vendor-payment", version: "2.0.0", schemaVersion: "1.0.0" },
  signals: {
    vendorVerified: true,
    invoiceVerified: true,
    paymentApproved: true,
    sufficientFunds: true,
    paymentAmount: 100,
    riskScore: 5,
    vendorId: "vendor/vendor-123", // must exactly equal `target`, see Core concepts above
  },
});

try {
  const trustRecord = await client.execute(transaction);
  console.log(trustRecord.trustRecordId, trustRecord.signature.algorithm);
} catch (error) {
  if (error instanceof ExecutionRejectedError) {
    console.log("Rejected:", error.message);
  }
  throw error;
}

​

Real-world example: a payment refund

const refund = createBusinessTransaction({
  principalId: "ai-customer-service-agent",
  purpose: "Customer-requested refund",
  action: "paytm:refund",
  target: "paytm/order-8842",
  parameters: {
    orderId: "order-8842",
    amount: 500,
    reason: "customer_requested",
  },
  policy: { name: "customer-refund", version: "1.0.0", schemaVersion: "1.0.0" },
  signals: {
    refundAmount: 500,
    orderId: "order-8842",
    customerVerified: true,
    withinRefundWindow: true,
  },
});

const trustRecord = await client.execute(refund);
// trustRecord.executions[0].evidence carries what the Paytm connector actually did;
// trustRecord.signature is the independently verifiable proof.

​

What Parmana guarantees

• The agent never holds the downstream credential — only a registered Connector does, and only for connectors currently configured (see Credential isolation).
• The decision is made by a named, versioned policy, not by agent reasoning.
• A rejected transaction throws ExecutionRejectedError — there is no code path where a rejection is silently treated as success.
• Every execution produces a signed ExecutionTrustRecord, verifiable without trusting Parmana itself.
• Signal-to-intent binding is checked before policy evaluation runs, closing the gap where an agent could satisfy a policy’s signals while pointing the actual execution somewhere else.
• Full audit trail: who proposed it, what was decided, what ran, and proof of both.

​

Next