> ## 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 Quick Start

> Perform your first authority verification using ParmanaClient in under 10 lines

## Using the HTTP client (recommended)

The HTTP client (`@parmanasystems/sdk-client`) calls a running Parmana server. This is the standard integration pattern for application services.

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

```typescript theme={null}
import { ParmanaClient, ParmanaApiError } from "@parmanasystems/sdk-client";

const client = new ParmanaClient({
  baseUrl: process.env.PARMANA_URL ?? "http://localhost:3000",
  apiKey: process.env.PARMANA_API_KEY,
});

async function main() {
  // Perform authority verification
  const attestation = await client.execute({
    executionId: "txn-20240115-001",   // unique per business transaction
    policyId: "payment-approval",
    policyVersion: "1.0.0",
    signals: {
      amount: 4500,
      currency: "USD",
      accountAge: 730,
      fraudScore: 0.02,
    },
  });

  console.log(attestation.decision.action);         // "approve" | "reject"
  console.log(attestation.execution_state);         // "completed" | "pending_override"
  console.log(attestation.execution_fingerprint);   // SHA-256 of canonical signals
  console.log(attestation.signature);               // Ed25519 signature

  // Verify independently
  const result = await client.verify(attestation);
  console.log(result.valid);  // true
}

main().catch(console.error);
```

***

## Using the core SDK (in-process)

Run the governance engine directly in your process — no server required.

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

```typescript theme={null}
import crypto from "crypto";
import {
  executeFromSignals,
  verifyAttestation,
  LocalSigner,
  LocalVerifier,
  MemoryReplayStore,
} from "@parmanasystems/core";

async function main() {
  // Generate keys — use stored keys in production
  const { privateKey, publicKey } = crypto.generateKeyPairSync("ed25519", {
    privateKeyEncoding: { type: "pkcs8", format: "pem" },
    publicKeyEncoding:  { type: "spki",  format: "pem" },
  });

  const signer   = new LocalSigner(privateKey);
  const verifier = new LocalVerifier(publicKey);
  const store    = new MemoryReplayStore();  // use RedisReplayStore in production

  const { attestation } = await executeFromSignals(
    {
      executionId:   "txn-20240115-001",
      policyId:      "payment-approval",
      policyVersion: "1.0.0",
      signals: {
        amount:      4500,
        currency:    "USD",
        accountAge:  730,
        fraudScore:  0.02,
      },
    },
    signer,
    verifier,
    undefined,    // runtimeEnvironment — undefined uses default paths
    store         // required — throws [INV-REPLAY-001] if omitted
  );

  console.log(attestation.decision.action);  // "approve"
  console.log(attestation.signature);        // Ed25519 signature

  // Verify
  const result = verifyAttestation(attestation, verifier);
  console.log(result.valid);  // true
}

main().catch(console.error);
```

<Warning>
  `MemoryReplayStore` loses all state on process restart and does not work across multiple processes. In production, use `RedisReplayStore`.
</Warning>

***

## Production replay store

```typescript theme={null}
import { RedisReplayStore } from "@parmanasystems/core";

const store = new RedisReplayStore(
  process.env.REDIS_URL!,   // e.g. "redis://localhost:6379"
  {
    reservationTtlSeconds: 300,   // default
    failedTtlSeconds: 30,         // default
  }
);
```

***

## Client method reference

All methods on `ParmanaClient`:

```typescript theme={null}
// Runtime
client.health()                     → Promise<HealthResult>
client.runtimeManifest()            → Promise<RuntimeManifestResult>
client.runtimeCapabilities()        → Promise<RuntimeCapabilitiesResult>

// Decisions
client.execute(request)             → Promise<ExecutionAttestation>
client.verify(attestation)          → Promise<VerificationResult>
client.evaluate(request)            → Promise<EvaluateResult>      // dry run — no attestation
client.simulate(request)            → Promise<SimulateResult>      // full pipeline dry run

// Post-execution
client.confirmExecution(request)    → Promise<ExecutionIntegrityProof>

// Audit (sub-namespace)
client.audit.decisions(params?)     → Promise<DecisionRow[]>
client.audit.decision(executionId)  → Promise<DecisionDetail>
client.audit.stats()                → Promise<AuditStats>
client.audit.security(params?)      → Promise<SecurityEventRow[]>
```

<Note>
  There is no `client.override()` method. To approve or reject a pending override, call `POST /override` directly using `client._request()` or `fetch`. See [Override Workflow](/override/pending).
</Note>

***

## Error handling

```typescript theme={null}
try {
  const attestation = await client.execute({ ... });
} catch (err) {
  if (err instanceof ParmanaApiError) {
    console.error(`HTTP ${err.status}: ${err.message}`);

    if (err.status === 422) {
      // Execution failed — check error message for [INV-*] error code
    } else if (err.status === 429) {
      // Rate limited — back off and retry
    } else if (err.status === 401) {
      // Bad or missing API key
    }
  }
}
```

See [Error Handling](/sdk/error-handling) for the full error code reference.

***

## Troubleshooting

**`ParmanaApiError: HTTP 503`** — The server's signer is not configured. Check `GET /health` — `verification` should be `"ok"`.

**`ParmanaApiError: HTTP 422` with `[INV-013@replay]`** — The `executionId` was already used. Use a new, unique ID. Do not retry with the same ID.

**`result.valid` is `false`** — Do not proceed with the authorized action. Check `result.checks` to identify which verification check failed.

**Network error (not `ParmanaApiError`)** — The server is unreachable. Check that the server is running and `baseUrl` is correct.

***

<Cards>
  <Card title="Insurance Claims Example" href="/sdk/examples/insurance-claims">
    Full TypeScript example with signals, execution, and verification
  </Card>

  <Card title="Error Handling" href="/sdk/error-handling">
    All error codes and retry strategies
  </Card>

  <Card title="Best Practices" href="/sdk/best-practices">
    ExecutionId design, signal validation, retry patterns
  </Card>
</Cards>