TypeScript SDK in Production

Your service
  → @parmana/sdk (ParmanaClient)
    → Parmana Runtime (Execution Gateway, Policy Engine)
      → registered Connector
        → downstream system (Paytm, HubSpot, your own API, ...)

import {
  ParmanaClient,
  HttpTransport,
  RetryStrategy,
  type Configuration,
} from "@parmana/sdk";

function createParmanaClient(): ParmanaClient {
  const endpoint = requireEnv("PARMANA_ENDPOINT");
  const apiKey = requireEnv("PARMANA_API_KEY");

  const configuration: Configuration = {
    endpoint,
    apiKey,
    timeout: Number(process.env.PARMANA_TIMEOUT_MS ?? 30_000),
    retryPolicy: {
      enabled: true,
      maxAttempts: 3,
      initialDelayMs: 1_000,
      maxDelayMs: 10_000,
      strategy: RetryStrategy.EXPONENTIAL,
    },
    transport: new HttpTransport({ endpoint, apiKey }),
  };

  return new ParmanaClient(configuration);
}

function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing required environment variable: ${name}`);
  }
  return value;
}

export const parmana = createParmanaClient();

import {
  ValidationError,
  AuthenticationError,
  AuthorizationError,
  ExecutionRejectedError,
  NotFoundError,
  ConflictError,
  InternalServerError,
  NetworkError,
  TimeoutError,
} from "@parmana/sdk";

async function executeOrFailClosed(transaction: BusinessTransaction) {
  try {
    return await parmana.execute(transaction);
  } catch (error) {
    if (error instanceof ExecutionRejectedError) {
      // A real, final policy decision — do not retry, do not proceed.
      logDenial(transaction, error.message);
      throw error;
    }
    if (
      error instanceof AuthenticationError ||
      error instanceof AuthorizationError
    ) {
      // A credentials/permissions problem, not a policy decision — page someone.
      alertOnCallEngineer("Parmana auth failure", error);
      throw error;
    }
    if (error instanceof ValidationError) {
      // Your request was malformed — a bug in your own code, not the Runtime's.
      logBug("Malformed BusinessTransaction", error);
      throw error;
    }
    // NetworkError / TimeoutError / InternalServerError / ConflictError / NotFoundError:
    // the Runtime's answer is unknown. Treat as not-approved. Never treat "we couldn't
    // reach Parmana" as "the action is authorized."
    logUnknownState(transaction, error);
    throw error;
  }
}

interface AuditLogEntry {
  businessTransactionId: string;
  principalId: string;
  action: string;
  outcome: "approved" | "denied" | "error";
  trustRecordId?: string;
  policyName: string;
  policyVersion: string;
  timestamp: string;
}

async function logExecution(
  transaction: BusinessTransaction,
  outcome: AuditLogEntry["outcome"],
  trustRecordId?: string,
) {
  const entry: AuditLogEntry = {
    businessTransactionId: transaction.businessTransactionId,
    principalId: transaction.authority.principalId,
    action: transaction.intent.action,
    outcome,
    trustRecordId,
    policyName: transaction.policy.name,
    policyVersion: transaction.policy.version,
    timestamp: new Date().toISOString(),
  };

  await db.insertInto("agent_audit_log").values(entry).execute();
}

CREATE TABLE agent_audit_log (
  id                     BIGSERIAL PRIMARY KEY,
  business_transaction_id TEXT NOT NULL UNIQUE,
  principal_id           TEXT NOT NULL,
  action                 TEXT NOT NULL,
  outcome                TEXT NOT NULL,
  trust_record_id        TEXT,
  policy_name            TEXT NOT NULL,
  policy_version         TEXT NOT NULL,
  created_at             TIMESTAMPTZ NOT NULL DEFAULT now()
);

function recordExecutionMetric(
  outcome: "approved" | "denied" | "error",
  durationMs: number,
) {
  metrics.increment(`parmana.execution.${outcome}`);
  metrics.histogram("parmana.execution.duration_ms", durationMs);
}

class TokenBucketLimiter {
  private tokens: number;
  private readonly capacity: number;
  private readonly refillPerMs: number;
  private lastRefill = Date.now();

  constructor(capacity: number, refillPerSecond: number) {
    this.capacity = capacity;
    this.tokens = capacity;
    this.refillPerMs = refillPerSecond / 1000;
  }

  async acquire(): Promise<void> {
    this.refill();
    while (this.tokens < 1) {
      await new Promise((resolve) => setTimeout(resolve, 50));
      this.refill();
    }
    this.tokens -= 1;
  }

  private refill() {
    const now = Date.now();
    const elapsed = now - this.lastRefill;
    this.tokens = Math.min(
      this.capacity,
      this.tokens + elapsed * this.refillPerMs,
    );
    this.lastRefill = now;
  }
}

const limiter = new TokenBucketLimiter(10, 5); // burst of 10, 5/sec sustained

async function executeRateLimited(transaction: BusinessTransaction) {
  await limiter.acquire();
  return parmana.execute(transaction);
}

async function smokeTest() {
  const health = await parmana.health();
  if (health.status !== "UP") {
    throw new Error(`Parmana health check failed: ${JSON.stringify(health)}`);
  }

  const version = await parmana.version();
  console.log("Deployed against Parmana version:", version);
}