SDK Reference

// Installation
// npm install @permitnetworks/sdk

import { PermitClient, Decision, Policy, AuthorizeRequest } from "@permitnetworks/sdk";

// ─── Client Initialization ───────────────────────────────────────────────────

const permit = new PermitClient({
  apiKey: process.env.PERMIT_API_KEY!,  // required
  agentId: "my-agent",                  // required: unique agent identifier
  pdp: "https://api.permitnetworks.com",// optional: default PDP endpoint
  timeout: 2000,                        // optional: request timeout in ms (default: 2000)
  retries: 2,                           // optional: retry count on network errors (default: 2)
});

// ─── Methods ─────────────────────────────────────────────────────────────────

// permit.authorize(request) → Promise<Decision>
// Submit an authorization request. Returns a Decision.
const decision = await permit.authorize({
  action: "payment.create",           // required: semantic action verb
  resource: "account:acct_9kx2m",     // optional: target resource
  context: {                          // optional: arbitrary key-value context
    amount: 4500,
    currency: "USD",
    ip: "203.0.113.42",
  },
});

// permit.confirm(decisionId) → Promise<void>
// Report that the action described in the decision was executed successfully.
// Increments budget counters and moves decision to "confirmed" state.
await permit.confirm(decision.id);

// permit.reject(decisionId, reason?) → Promise<void>
// Report that the action was NOT executed (e.g., downstream error, user cancelled).
// Does NOT increment budget counters. Moves decision to "rejected" state.
await permit.reject(decision.id, "downstream_error");

// permit.listPolicies() → Promise<Policy[]>
// Fetch all policies visible to this API key.
const policies = await permit.listPolicies();

// permit.onDecision(callback) → () => void
// Stream decision events via server-sent events. Returns an unsubscribe function.
const unsubscribe = permit.onDecision((event) => {
  console.log("New decision:", event.decision.id, event.decision.effect);
});
// Call unsubscribe() to stop receiving events.

// ─── Types ───────────────────────────────────────────────────────────────────

interface AuthorizeRequest {
  action: string;
  resource?: string;
  context?: Record<string, unknown>;
}

interface Decision {
  id: string;
  effect: "allow" | "deny" | "review" | "log";
  reason: string | null;          // null when effect is "allow"
  policy_id: string | null;       // null if no policy matched (default deny)
  agent_id: string;
  action: string;
  resource: string | null;
  latency_ms: number;
  evaluated_at: string;           // ISO 8601
  expires_at: string | null;      // ISO 8601, null if effect is "deny"
  permit_token: string | null;    // Ed25519-signed JWT, present when effect is "allow"
}

interface Policy {
  id: string;
  name: string;
  priority: number;
  enabled: boolean;
  agents: string[] | null;        // null = applies to all agents
  rules: PolicyRule[];
  rate_limit: RateLimit | null;
  budget: Budget | null;
  created_at: string;
  updated_at: string;
}

interface PolicyRule {
  action: string;                 // exact, wildcard (*), or regex (/pattern/)
  resource: string | null;
  effect: "allow" | "deny" | "review" | "log";
  conditions: Record<string, unknown> | null;
}

interface RateLimit {
  per_second: number | null;
  per_minute: number | null;
  per_hour: number | null;
  per_day: number | null;
}

interface Budget {
  limit: number;
  unit: string;                   // "USD", "api_calls", or custom
  period: "hourly" | "daily" | "monthly";
  threshold_alert: number | null; // 0.0 – 1.0, e.g. 0.8 = alert at 80%
}