> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parmanasystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK Quickstart

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

<Note>
  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](/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.
</Note>

## 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:

```bash theme={null}
npm install
```

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

```bash theme={null}
npm run generate:gateway-keys
```

Start the server fully locally, no external database:

```bash theme={null}
NODE_ENV=test \
  PARMANA_STORAGE=memory \
  PARMANA_POLICY_DIR=/absolute/path/to/policies \
  npm run dev
```

Confirm it's up:

```bash theme={null}
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`:

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

See [Deploy patterns](/guides/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):

```bash theme={null}
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`:

```typescript theme={null}
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:

```bash theme={null}
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):

```json theme={null}
{
  "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": "alice@example.com",
      "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](/guides/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](/guides/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](/guides/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](/sdks/typescript#createbusinesstransaction-no-more-hand-synced-ids)
for exactly which three id pairs the server cross-checks.

## Next

<CardGroup cols={2}>
  <Card title="TypeScript SDK for AI Agents" icon="robot" href="/guides/typescript-sdk-ai-agents">
    Wire this exact call into LangChain.js, the Vercel AI SDK, or a server
    endpoint.
  </Card>

  <Card title="End-to-end: agent → Parmana → Paytm" icon="route" href="/guides/end-to-end-paytm-flow">
    The same flow against a real connector and real infrastructure, not the
    local test fixture.
  </Card>

  <Card title="Verify independently" icon="check-double" href="/guides/verify-independently">
    Read back or re-verify the `ExecutionTrustRecord` you just created.
  </Card>

  <Card title="TypeScript SDK reference" icon="js" href="/sdks/typescript">
    The full error taxonomy, model types, and test suite.
  </Card>
</CardGroup>