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

# SDK Installation

> Install and configure the Parmana SDK packages

## Two SDK packages

Parmana provides two packages depending on how you want to integrate:

| Package                      | Use when                                                                                 |
| ---------------------------- | ---------------------------------------------------------------------------------------- |
| `@parmanasystems/sdk-client` | You are running the Parmana server (Docker) and want an HTTP client to call it           |
| `@parmanasystems/core`       | You want to run the governance engine directly in your Node.js process, without a server |

Most production deployments use both: `@parmanasystems/core` inside the governance server, and `@parmanasystems/sdk-client` in the application services that call the server.

***

## @parmanasystems/sdk-client

The HTTP client. Wraps all server endpoints with typed request/response interfaces.

```bash theme={null}
npm install @parmanasystems/sdk-client
```

### Exports

```typescript theme={null}
import {
  ParmanaClient,          // The HTTP client class
  ParmanaApiError,        // Thrown on non-2xx responses
} from "@parmanasystems/sdk-client";

import type {
  ParmanaClientOptions,
  ExecuteRequest,
  ExecutionAttestation,
  VerificationResult,
  HealthResult,
  RuntimeManifestResult,
  RuntimeCapabilitiesResult,
  EvaluateRequest,
  EvaluateResult,
  SimulateRequest,
  SimulateResult,
  DecisionListParams,
  DecisionRow,
  DecisionDetail,
  AuditStats,
  SecurityEventRow,
  ExecutedAction,
  ExecutionIntegrityProof,
} from "@parmanasystems/sdk-client";
```

### Client construction

```typescript theme={null}
const client = new ParmanaClient({
  baseUrl: "http://localhost:3000",  // required
  apiKey: "your-api-key",            // optional — sent as Bearer token
});
```

***

## @parmanasystems/core

The full SDK — policy lifecycle, execution engine, verification, replay protection, and canonical types. Use this when running the governance engine in-process.

```bash theme={null}
npm install @parmanasystems/core
```

<Note>
  `@parmanasystems/core` bundles CJS dependencies. Do NOT set `"type": "module"` in `package.json`. Wrap async calls in an `async` function — do not use top-level `await` in CommonJS modules.
</Note>

### Key exports

```typescript theme={null}
// Execution
import {
  executeFromSignals,    // main entry point — runs full governance pipeline
  executeDecision,       // lower-level — takes a pre-built token
  confirmExecution,      // post-execution integrity proof
} from "@parmanasystems/core";

// Replay stores
import {
  MemoryReplayStore,     // in-process — for development only
  RedisReplayStore,      // distributed — required for production
} from "@parmanasystems/core";

// Signing and verification
import {
  LocalSigner,           // Ed25519 signer using a PEM private key
  LocalVerifier,         // Ed25519 verifier using a PEM public key
  verifyAttestation,     // verify an ExecutionAttestation
  verifyBundle,          // verify a policy bundle
  verifyRuntime,         // verify runtime integrity
} from "@parmanasystems/core";

// Policy lifecycle
import {
  createPolicy,
  upgradePolicy,
  validatePolicy,
  generateBundle,
  signBundle,
} from "@parmanasystems/core";

// Override authority
import {
  approveOverride,
} from "@parmanasystems/core";

// Canonical serialization
import {
  canonicalize,
  canonicalizeForSigning,
  SIGNING_DOMAINS,
} from "@parmanasystems/core";

// Signal provenance
import {
  withProvenance,
  withoutProvenance,
  validateProvenance,
  documentProvenance,
  accountAggregatorProvenance,
  voiceTranscriptProvenance,
  hashEvidence,
  hashProvenance,
} from "@parmanasystems/core";
```

***

## Other packages

Install individually if you need specific capabilities:

```bash theme={null}
npm install @parmanasystems/governance    # policy lifecycle only
npm install @parmanasystems/verifier      # standalone verification only
npm install @parmanasystems/audit-db      # PostgreSQL audit storage
npm install @parmanasystems/crypto        # Ed25519 primitives
npm install @parmanasystems/canonical     # canonical JSON serialization
npm install @parmanasystems/provenance    # signal provenance types
npm install @parmanasystems/bundle        # bundle read/write
```

***

## TypeScript configuration

All packages ship type declarations. No additional `@types/` packages are needed.

Recommended `tsconfig.json`:

```json theme={null}
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true
  }
}
```

***

## Requirements

* Node.js 18 or later
* For `RedisReplayStore`: a running Redis 6+ instance
* For `@parmanasystems/audit-db`: PostgreSQL 14+

***

## Troubleshooting

**`Cannot find module '@parmanasystems/sdk-client'`** Run `npm install @parmanasystems/sdk-client` in your project directory.

**`Error: require is not defined`** You are running in an ES module context. `@parmanasystems/core` uses CommonJS. Remove `"type": "module"` from `package.json`, or use dynamic `import()` within an async context.

**TypeScript errors on import** Ensure `"moduleResolution": "node"` is set in `tsconfig.json`. The `"bundler"` resolution strategy is not supported.

***

<Cards>
  <Card title="SDK Quick Start" href="/sdk/quickstart">
    ParmanaClient in 10 lines
  </Card>

  <Card title="Examples" href="/sdk/examples/insurance-claims">
    Complete industry examples
  </Card>

  <Card title="Error Handling" href="/sdk/error-handling">
    ParmanaApiError and all error codes
  </Card>
</Cards>