TypeScript SDK

npm install @parmana/sdk

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

const endpoint = "http://localhost:3000";
const apiKey = "my-secret-api-key";

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

const health = await client.health(); // GET /health, no key required

import {
  ValidationError,
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  ConflictError,
  ExecutionRejectedError,
  InternalServerError,
  NetworkError,
  TimeoutError,
} from "@parmana/sdk";

try {
  await client.execute(transaction);
} catch (error) {
  if (error instanceof ExecutionRejectedError) {
    console.log(error.message); // "Execution rejected: <policy-specific reason>"
  } else if (error instanceof ValidationError) {
    // 400, malformed request
  }
}

try {
  await parmana.execute(transaction);
} catch (error) {
  if (error instanceof InternalServerError) {
    if (error.serverCode === "EXECUTION_RECORD_INCOMPLETE") {
      // The action ran. Reconcile, never resubmit under a new id.
    } else if (error.serverCode === "EXECUTION_OUTCOME_UNKNOWN") {
      // The action may have run. Reconcile, never resubmit under a new id.
    } else if (
      error.serverCode === "SIGNING_UNAVAILABLE" ||
      error.serverCode === "EXECUTION_INTENT_UNAVAILABLE"
    ) {
      // Nothing ran. Safe to retry later with a NEW businessTransactionId.
    }
  }
  throw error;
}

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

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

// The approver's signed approval for this action and resource, made with
// signApproval() on the approver's machine and passed to the agent.
const approval = pendingApprovals.get("vendor/vendor-123");

const transaction = createBusinessTransaction({
  principalId: "alice@example.com", // must match your key's allowedPrincipalIds
  purpose: "Vendor payment approval",
  action: "vendor-payment",
  target: "vendor/vendor-123",
  parameters: { amount: 100, currency: "USD" },
  policy: { name: "vendor-payment", version: "2.1.0", schemaVersion: "1.0.0" },
  signals: {
    // No agent action is authorized without a signed human approval: a trusted
    // approver signs one for this target up to this amount (signApproval), and
    // the agent attaches it. Without it the request is refused.
    humanApproved: true,
    approvalArtifact: approval,
    vendorVerified: true,
    invoiceVerified: true,
    paymentApproved: true,
    sufficientFunds: true,
    paymentAmount: 100,
    riskScore: 5,
    vendorId: "vendor/vendor-123", // boundSignals: SignalIntentBinder rejects this
    // request unless this exactly equals `target` above
  },
});

const trustRecord = await client.execute(transaction);

const inEffect = await client.policyInEffect("paytm:refund");

inEffect.policy; // { name: "customer-refund", version: "1.2.0", schemaVersion: "1.0.0" }
inEffect.signals.facts; // ["fraudCheckPassed", "managerApproved", "refundAmount", "refundEligible"]
inEffect.signals.approval; // { managerApproved: { resourceId: "parameters.orderId", value: "parameters.amount" } }

const change = await maker.proposeExternalConnectorChange({
  action: "register",
  capability: "erp:create-invoice",
  endpointUrl: "https://erp.example.com/parmana/release",
  policy: "erp-invoice",
  allowedParameters: ["amount", "currency"],
  reason: "Finance creates invoices in the ERP through Parmana.",
});

await checker.approveExternalConnectorChange(
  change.changeId,
  signPolicyChangeStepUp({
    pendingPolicyChangeId: change.changeId,
    action: "approve",
    privateKeyPem: readFileSync("step-up.private.pem", "utf8"),
    keyId: "checker-step-up-1",
  }),
);

await checker.externalConnectors(); // [{ capability: "erp:create-invoice", status: "active", ... }]

import { readFileSync } from "node:fs";
import { signApproval } from "@parmana/sdk";

const approval = signApproval({
  privateKeyPem: readFileSync(
    "manager-priya__manager-priya-key-1.private.pem",
    "utf8",
  ),
  approverId: "manager-priya",
  keyId: "manager-priya-key-1",
  capability: "paytm:refund",
  resourceId: "ORD-1042",
  maxAmount: 75000, // leave out when the policy declares no amount
});

// The agent sends it in signals.approvalArtifact on a new request.

import { ParmanaClient, signPolicyChangeStepUp } from "@parmana/sdk";

// The proposer
const change = await proposer.proposeApproverChange({
  action: "add",
  approverId: "manager-priya",
  keyId: "manager-priya-key-1",
  publicKeyPem, // the approver's .public.pem file
  reason: "Priya approves refunds for the West region from October.",
});

// A different person, the checker
const pending = await checker.approverChanges("PENDING_APPROVAL");
await checker.approveApproverChange(
  change.changeId,
  signPolicyChangeStepUp({
    pendingPolicyChangeId: change.changeId,
    action: "approve",
    privateKeyPem: checkerStepUpKeyPem,
    keyId: "checker-step-up-1",
  }),
);

const approvers = await checker.approvers();

import { ParmanaClient } from "@parmana/sdk";

const client = new ParmanaClient({
  endpoint: "http://127.0.0.1:3000",
  apiKey: "pk_local_...",
});

const me = await client.caller();
// { callerId: "local-operator", allowedPrincipalIds: ["local-operator"], allowedCapabilities: ["paytm:refund"], unrestrictedCapabilities: false }

const key = await client.publicKey("default");
// key.pem is the SPKI PEM that signs Trust Records, Refusal Records and Execution Intents

import {
  ParmanaClient,
  verifyExecutionIntentOffline,
  verifyExecutionTrustRecordOffline,
} from "@parmana/sdk";

const client = new ParmanaClient({
  endpoint: "http://127.0.0.1:3000",
  apiKey: "pk_local_...",
});
const { pem } = await client.publicKey("default");

const record = await client.trustRecord("5015499d-b7ba-48fe-a9ad-821862d70ad0");
const result = verifyExecutionTrustRecordOffline(record, { default: pem });
// { valid: true, hashValid: true, legacySignatureValid: true, algorithmsChecked: ["ed25519"], errors: [] }

const view = await client.executionIntent(
  "5015499d-b7ba-48fe-a9ad-821862d70ad0",
);
verifyExecutionIntentOffline(view.intent, { default: pem });

import { verifyParmanaRelease } from "@parmana/sdk";

const result = await verifyParmanaRelease(body, {
  publicKeys: { default: pem }, // client.publicKey("default")
  audience: "https://erp.example.com/parmana/release", // this endpoint, as registered
  isAlreadyExecuted: (businessTransactionId) =>
    answers.has(businessTransactionId),
});

if (!result.valid) {
  // Act on nothing. result.errors says why.
} else if (result.alreadyExecuted) {
  // Answer with the first result again; do not act twice.
} else {
  // Act on result.release.capability, target and parameters only, then answer
  // { businessTransactionId, capability, success, result, executedAt }.
}

import { readFileSync } from "node:fs";

import { ParmanaClient, signPolicyChangeStepUp } from "@parmana/sdk";

const endpoint = "http://127.0.0.1:3000";
const proposer = new ParmanaClient({
  endpoint,
  apiKey: "pk_local_... (alice)",
});
const approver = new ParmanaClient({ endpoint, apiKey: "pk_local_... (bob)" });

const change = await proposer.proposePolicyChange("customer-refund", "1.2.0", {
  proposedContent: JSON.parse(
    readFileSync("policies/customer-refund/1.2.0/policy.json", "utf8"),
  ),
  reason: "Adopt the shipped customer-refund policy.",
});

const open = await approver.policyChanges("PENDING_APPROVAL");
// each entry has diff.current and diff.proposed

const stepUp = signPolicyChangeStepUp({
  pendingPolicyChangeId: change.pendingPolicyChangeId,
  action: "approve",
  privateKeyPem: readFileSync("approver/step-up.private.pem", "utf8"),
  keyId: "bob",
});

const approved = await approver.approvePolicyChange(
  change.pendingPolicyChangeId,
  stepUp,
);
// approved.status === "APPROVED"

import { ParmanaClient } from "@parmana/sdk";

const client = new ParmanaClient({
  endpoint: "http://127.0.0.1:3000",
  apiKey: "pk_local_...",
});

const records = await client.trustRecords(1, 25, {
  since: "2026-09-01T00:00:00Z",
});
const receipt = await client.latestReceipt(
  "5015499d-b7ba-48fe-a9ad-821862d70ad0",
);

import { InternalServerError, ParmanaClient } from "@parmana/sdk";

const client = new ParmanaClient({
  endpoint: "http://127.0.0.1:3000",
  apiKey: "pk_local_...",
});

try {
  await client.execute(transaction); // a BusinessTransaction, see createBusinessTransaction()
} catch (error) {
  if (
    error instanceof InternalServerError &&
    error.serverCode === "CONNECTOR_NOT_REGISTERED"
  ) {
    // error.statusCode === 503: authorized, but nothing was executed
  }
}

npm install --workspace=typescript
npm run build   # typescript/
npm run test    # vitest