TypeScript SDK Quickstart

Install to your first authorized execution with the TypeScript SDK, in under 10 minutes, using the in-memory server.

This walkthrough uses test:fixture-execute, a generic, credential-free capability built for local testing, evaluated against a policy named vendor-payment. That policy name is unrelated to any connector, it’s just the example policy this transaction runs against. See Quickstart for the same flow driven from the repository directly rather than an installed package; this page installs @parmana/sdk as a real dependency the way you would in your own project.

Prerequisites

• Node.js installed (node --version)
• A running Parmana Runtime to talk to: either your own deployment, or the local in-memory server this walkthrough starts from a clone of this repository

1. Start a local Runtime

   From a clone of this repository:

   npm install
   

   Generate a local Gateway signing keypair (the Execution Gateway signs its own attestations with a keypair separate from the authorization-verification key):

   npm run generate:gateway-keys
   

   Start the server fully locally, no external database:

   NODE_ENV=test \
     PARMANA_STORAGE=memory \
     PARMANA_POLICY_DIR=/absolute/path/to/policies \
     npm run dev
   

   Confirm it’s up:

   curl http://localhost:3000/health
   # {"status":"UP"}
   

   With NODE_ENV=test, a generic, credential-free test connector (test-fixture) registers automatically, no connector credentials required for this walkthrough. Every other route, including /version, fails closed with a 401 until you send the demo bearer key the committed .env ships for local development, raw key my-secret-api-key:

   curl http://localhost:3000/version -H "Authorization: Bearer my-secret-api-key"
   # {"name":"Parmana","version":"0.4.0","api":"v1"}
   

   See Deploy patterns for running against something other than the in-memory local server.

2. Install the SDK

   In a separate project (or a new terminal, same repo):

   npm install @parmana/sdk
   

   Real, published package. npm view @parmana/sdk version confirms the current version directly from npm.

3. Build and execute a Business Transaction

   Create quickstart.ts:

   import {
     ParmanaClient,
     HttpTransport,
     createBusinessTransaction,
     ExecutionRejectedError,
   } 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 transaction = createBusinessTransaction({
     principalId: "typescript-sdk-quickstart",
     purpose: "Quickstart demo",
     action: "test:fixture-execute",
     target: "vendor://payments",
     parameters: { amount: 1000, currency: "USD" },
     policy: { name: "vendor-payment", version: "2.0.0", schemaVersion: "1.0.0" },
     signals: {
       vendorVerified: true,
       invoiceVerified: true,
       paymentApproved: true,
       sufficientFunds: true,
       paymentAmount: 1000,
       riskScore: 5,
       vendorId: "vendor://payments", // must exactly equal `target`
     },
   });
   
   async function main() {
     try {
       const trustRecord = await client.execute(transaction);
       console.log("Business Transaction ID:", transaction.businessTransactionId);
       console.log("Trust Record ID:        ", trustRecord.trustRecordId);
       console.log("Signature Algorithm:    ", trustRecord.signature.algorithm);
       console.log(JSON.stringify(trustRecord, null, 2));
     } catch (error) {
       if (error instanceof ExecutionRejectedError) {
         console.error("Rejected:", error.message);
         process.exitCode = 1;
         return;
       }
       throw error;
     }
   }
   
   main();
   

   Run it:

   npx tsx quickstart.ts
   
4. Real output

   Captured from an actual run against a local server, using the same createBusinessTransaction() call this page documents (see typescript/examples/06-create-business-transaction.ts in this repository for the exact source, and typescript/test/integration/examples.integration.test.ts for the test that proves it stays runnable):

   {
     "trustRecordId": "2d26aaec-e274-4255-8415-d93b672747b4",
     "businessTransactionId": "435e1c86-d2ed-4f4d-8549-aee574d1c77d",
     "transaction": {
       "businessTransactionId": "435e1c86-d2ed-4f4d-8549-aee574d1c77d",
       "authority": {
         "authorityId": "5c6df777-3685-4b5e-9378-3433388cf9d6",
         "authorityType": "SERVICE",
         "principalId": "[e-mail]",
         "issuedAt": "2026-09-14T17:12:04.538Z"
       },
       "intent": {
         "action": "test:fixture-execute",
         "target": "vendor/vendor-123",
         "parameters": { "amount": 100, "currency": "USD" }
       },
       "policy": {
         "name": "vendor-payment",
         "version": "2.0.0",
         "schemaVersion": "1.0.0"
       },
       "status": "RECEIVED"
     }
   }
   

   The full ExecutionTrustRecord also includes executions[0].decision (outcome: "APPROVED"), executions[0].evidence (what the connector actually did), and the signature block covered in Verify independently. Field names are camelCase here; the same record from the Python SDK uses snake_case for the same fields (see Python SDK Quickstart).

Troubleshooting

NetworkError: connect ECONNREFUSED: the Runtime isn’t running, or you’re pointed at the wrong endpoint. Confirm step 1’s curl http://localhost:3000/health succeeds first.

AuthenticationError on every call: either you omitted apiKey against a server that doesn’t have PARMANA_AUTH_DISABLED=true set, or the key is wrong. The demo key above, my-secret-api-key, only works against a server started exactly as shown in step 1.

ExecutionRejectedError: Execution rejected: ...: the policy evaluated your signals and declined. The message names which rule failed; check Write your first policy for how vendor-payment@2.0.0 reads its signals, or loosen the signals in your own test transaction to see it pass.

A 400 about a mismatched id: you built the BusinessTransaction object by hand instead of through createBusinessTransaction(). See createBusinessTransaction(), no more hand-synced ids for exactly which three id pairs the server cross-checks.

Next

TypeScript SDK Overview

The concepts behind what you just ran: transactions, decisions, proofs.

TypeScript SDK for AI Agents

Wire this exact call into LangChain.js, the Vercel AI SDK, or a server endpoint.

End-to-end: agent → Parmana → Paytm

The same flow against a real connector and real infrastructure, not the local test fixture.

Verify independently

Read back or re-verify the ExecutionTrustRecord you just created.

TypeScript SDK reference

The full error taxonomy, model types, and test suite.