@parmanasystems/sdk-client

Type-safe TypeScript HTTP client for the Parmana runtime API. Wraps fetch with typed request/response interfaces matching the server's OpenAPI contract. Provides a client.audit.* sub-namespace for the decision timeline and stats endpoints. Throws ParmanaApiError on non-2xx responses with the server's error message.

Public API

/** Construction options. */
interface ParmanaClientOptions {
  /** Base URL of the Parmana server, e.g. "http://localhost:3001". */
  baseUrl: string;
  /** Bearer token — required when the server has PARMANA_API_KEY set. */
  apiKey?: string;
}

class ParmanaClient {
  readonly audit: AuditNamespace;

  constructor(options: ParmanaClientOptions)

  /** GET /health */
  async health(): Promise<HealthResult>

  /** GET /runtime/manifest */
  async runtimeManifest(): Promise<RuntimeManifestResult>

  /** GET /runtime/capabilities */
  async runtimeCapabilities(): Promise<RuntimeCapabilitiesResult>

  /** POST /execute — governed execution, returns signed attestation. */
  async execute(request: ExecuteRequest): Promise<ExecutionAttestation>

  /** POST /verify — verify an attestation signature and runtime integrity. */
  async verify(attestation: ExecutionAttestation): Promise<VerificationResult>

  /** POST /evaluate — dry-run policy evaluation, no attestation produced. */
  async evaluate(request: EvaluateRequest): Promise<EvaluateResult>

  /** POST /simulate — full pipeline dry-run with attestation preview. */
  async simulate(request: SimulateRequest): Promise<SimulateResult>

  /** POST /confirm-execution — prove a real action matched its authorization. */
  async confirmExecution(request: {
    attestation: ExecutionAttestation;
    executedAction: ExecutedAction;
    timeWindowSeconds?: number;
  }): Promise<ExecutionIntegrityProof>
}

class AuditNamespace {
  /** GET /audit/decisions — paginated decision timeline. */
  async decisions(params?: DecisionListParams): Promise<DecisionRow[]>

  /** GET /audit/decisions/:id — single decision detail. */
  async decision(executionId: string): Promise<DecisionDetail>

  /** GET /audit/stats — aggregate counts. */
  async stats(): Promise<AuditStats>

  /** GET /audit/security — security event dashboard. */
  async security(params?: { from?: string; to?: string; limit?: number }): Promise<SecurityEventRow[]>
}

/** Thrown on non-2xx HTTP responses. */
class ParmanaApiError extends Error {
  readonly status: number;
  constructor(status: number, message: string)
}

// ── Request types ───────────────────────────────────────────────────────────

interface ExecuteRequest {
  policyId: string;
  policyVersion: string;
  signals: Record<string, unknown>;
}

interface EvaluateRequest {
  policyId: string;
  policyVersion: string;
  signals: Record<string, unknown>;
}

interface SimulateRequest {
  policyId: string;
  policyVersion: string;
  signals: Record<string, unknown>;
}

// ── Response types ──────────────────────────────────────────────────────────

interface HealthResult {
  status: string;
  runtimeVersion: string;
  runtimeHash: string;
  verification: string;
  audit_db: boolean;
  signing_mode: "env" | "disk";
  capabilities: string[];
  supportedSchemaVersions: string[];
}

interface EvaluateResult {
  wouldDecide: "approve" | "reject" | string;
  ruleMatched: string;
  reason: string;
  signalsValidated: boolean;
}

interface SimulateResult {
  simulation: true;
  decision: { action: "approve" | "reject" | string; reason: string; ruleMatched: string };
  signalsValidated: boolean;
  policyLoaded: boolean;
  wouldSign: boolean;
  attestationPreview: Record<string, unknown>;
}

interface DecisionListParams {
  limit?: number;
  offset?: number;
  policyId?: string;
  decision?: "approve" | "deny" | "any";
  from?: string;
  to?: string;
}

interface AuditStats {
  total_decisions: string;
  decisions_today: string;
  total_verifications: string;
  valid_verifications: string;
  invalid_verifications: string;
  total_security_events: string;
  total_api_calls: string;
}

Environment variables

None. The client is configured via constructor arguments.

Usage example

import { ParmanaClient } from "@parmanasystems/sdk-client";

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

const attestation = await client.execute({
  policyId: "loan-approval",
  policyVersion: "1.0.0",
  signals: { amount: 50000, credit_score: 720 },
});

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

Package wiring

@parmanasystems/sdk-client has no internal @parmanasystems dependencies — it communicates exclusively over HTTP. It is the only dependency of @parmanasystems/dashboard. Callers embedding governance workflows in their applications can use it as a standalone package without installing the full runtime stack.