@mandaitor/sdk

TypeScript SDK for the Mandaitor Delegation Mandate Registry API.

Installation

npm install @mandaitor/sdk
# or
pnpm add @mandaitor/sdk

Quick Start

import { MandaitorClient } from "@mandaitor/sdk";

const client = new MandaitorClient({
  apiKey: "mk_live_...",
  tenantId: "tnt_acme_prod",
});

// Create a mandate
const mandate = await client.createMandate({
  principal: { id: "user-123", type: "NATURAL_PERSON" },
  delegate: { id: "agent-456", type: "AGENT" },
  scope: {
    actions: ["construction.validation.approve"],
    resources: ["project:proj-1/zone:EG/installation:stk_01"],
    effect: "ALLOW",
  },
  constraints: {
    validFrom: new Date().toISOString(),
    validUntil: new Date(Date.now() + 86400000).toISOString(),
  },
});

// Verify a delegation claim
const result = await client.verify({
  delegateId: "agent-456",
  action: "construction.validation.approve",
  resource: "project:proj-1/zone:EG/installation:stk_01",
});

console.log(result.decision); // "ALLOW" or "DENY"

API Reference

MandaitorClient

| Method | Description | |--------|-------------| | createMandate(request) | Create a new delegation mandate | | getMandate(id) | Retrieve a mandate by ID | | listMandates(options?) | List mandates with optional pagination | | revokeMandate(id, reason?) | Permanently revoke a mandate | | suspendMandate(id, reason?) | Temporarily suspend a mandate | | reactivateMandate(id) | Reactivate a suspended mandate | | verify(request, options?) | Verify a delegation claim | | getEvents(mandateId?) | Query audit events |

Configuration

interface MandaitorClientConfig {
  apiKey: string;       // API key issued during tenant onboarding
  tenantId: string;     // Tenant identifier, e.g. "tnt_acme_prod"
  baseUrl?: string;     // API base URL (defaults to production)
  timeout?: number;     // Request timeout in ms (default: 5000)
}

Error Handling

The SDK provides typed error classes for all API error scenarios:

| Error Class | HTTP Status | Description | |-------------|-------------|-------------| | MandaitorAuthError | 401 | Invalid or missing API key | | MandaitorForbiddenError | 403 | Insufficient permissions | | MandaitorNotFoundError | 404 | Resource not found | | MandaitorConflictError | 409 | State conflict (e.g., revoking an already revoked mandate) | | MandaitorRateLimitError | 429 | Rate limit exceeded | | MandaitorValidationError | 400 | Invalid request payload | | MandaitorTimeoutError | - | Request timed out |

Development

# Build
pnpm build

# Run unit tests
pnpm test:unit

# Run integration tests (requires testing stage credentials)
pnpm test:integration