Developers · Node.js SDK

@aegis-os/sdk — Node.js

The official TypeScript SDK for AegisOS Comply. Zero runtime dependencies. Full type safety. Works with any Node.js AI agent framework.

✓ Zero dependencies
✓ Full TypeScript types
✓ Node.js 18+
✓ ESM + CJS

On this page

Installation

Terminal
npm install @aegis-os/sdk
# or: yarn add @aegis-os/sdk  |  pnpm add @aegis-os/sdk

Initialisation

Create one client instance per application and reuse it. The client is stateless and safe for concurrent use.

client.ts
import { AegisClient } from '@aegis-os/sdk';

export const aegis = new AegisClient({
  apiKey:  process.env.AEGIS_API_KEY,   // required
  baseUrl: process.env.AEGIS_API_URL,   // optional — defaults to production
  timeout: 10000,                        // optional — ms, default 10000
});

Submitting intents

Call aegis.intents.submit() before any AI-driven payment. The call returns immediately with a pending intent — policy evaluation happens asynchronously.

agent.ts
const intent = await aegis.intents.submit({
  agentId:         'your-agent-uuid',
  amount:          12500,
  currency:        'INR',
  reason:          'Monthly SaaS subscription renewal',
  confidence:      0.97,           // AI confidence (0–1)
  merchant:        'Notion',
  merchantCategory:'saas',
  metadata:        { invoiceId: 'INV-2026-0341' },
});

console.log(intent.id);      // "int_9f3a2b..."
console.log(intent.status);  // "pending"

Polling for a decision

Use aegis.intents.waitForDecision() to poll until the policy engine resolves the intent. Configure the timeout and polling interval to suit your workflow.

agent.ts
const resolved = await aegis.intents.waitForDecision(intent.id, {
  pollIntervalMs: 500,   // default 500ms
  timeoutMs:      15000, // default 15s
});

switch (resolved.status) {
  case 'approved':
    await executePayment(resolved.id);
    break;
  case 'pending_approval':
    // Notify user; finance team will act via dashboard
    break;
  case 'denied':
    throw new Error(`Spend denied: ${resolved.policyDecision}`);
}
Tip: For long-running approval flows, use webhooks instead of polling to avoid holding open connections.

Receiving webhook events

Configure a webhook endpoint in the dashboard. AegisOS will POST signed events to your endpoint when intent status changes.

webhook-handler.ts
import { AegisClient } from '@aegis-os/sdk';

// Verify the webhook signature before trusting the payload
const isValid = AegisClient.verifyWebhookSignature({
  payload:   rawBody,
  signature: req.headers['x-aegis-signature'],
  secret:    process.env.AEGIS_WEBHOOK_SECRET,
});

if (!isValid) {
  res.status(401).send('Invalid signature');
  return;
}

const event = JSON.parse(rawBody);
if (event.type === 'intent.approved') {
  await executePayment(event.data.intentId);
}

Error handling

The SDK throws typed errors. Wrap calls in try/catch and check the error type to handle specific scenarios.

agent.ts
import { AegisClient, AegisError, AegisTimeoutError } from '@aegis-os/sdk';

try {
  const intent = await aegis.intents.submit({ /* ... */ });
} catch (err) {
  if (err instanceof AegisTimeoutError) {
    // Policy engine did not respond in time — safe to retry
  } else if (err instanceof AegisError) {
    console.error(err.statusCode, err.message, err.code);
  } else {
    throw err;
  }
}

TypeScript types

All request and response shapes are fully typed. Import types directly for use in your own interfaces.

types.ts
import type {
  SubmitIntentInput,
  IntentResponse,
  IntentStatus,    // 'pending' | 'approved' | 'denied' | 'pending_approval'
  PolicyDecision,  // 'allow' | 'deny' | 'require_approval'
  WebhookEvent,
} from '@aegis-os/sdk';

All methods

intents.submit(input)

Submit a new spend intent for policy evaluation.

intents.get(id)

Retrieve the current state of an intent by ID.

intents.list(filters)

List intents with optional status / agent / date filters.

intents.waitForDecision(id, opts)

Poll until the intent reaches a terminal status.

approvals.list()

List pending approval requests for the current user.

approvals.respond(id, decision)

Approve or reject a pending intent.

agents.list()

List all registered agents in the organisation.

agents.get(id)

Get agent details, risk level, and wallet balance.

AegisClient.verifyWebhookSignature(opts)

Static method — verify an inbound webhook payload signature.