TypeScript SDK

Modern async/await API for Node.js and browser environments

Installation

# npm
npm install @avp-protocol/sdk

# yarn
yarn add @avp-protocol/sdk

# pnpm
pnpm add @avp-protocol/sdk

Quick Start

import { AVPClient, FileBackend } from '@avp-protocol/sdk';

// Create client with file backend
const client = new AVPClient({
  backend: new FileBackend({
    path: './vault.enc',
    password: 'your-secure-password'
  })
});

// Authenticate to a workspace
const session = await client.authenticate({ workspace: 'my-agent' });

// Store a secret
await client.store({
  sessionId: session.sessionId,
  name: 'OPENAI_API_KEY',
  value: Buffer.from('sk-...')
});

// Retrieve a secret
const secret = await client.retrieve({
  sessionId: session.sessionId,
  name: 'OPENAI_API_KEY'
});

console.log(secret.value.toString()); // sk-...

Client Configuration

interface AVPClientOptions {
  backend: Backend;           // Storage backend instance
  logger?: Logger;            // Optional custom logger
  defaultTtl?: number;        // Default session TTL in seconds
}

const client = new AVPClient({
  backend: new FileBackend({ path: './vault.enc', password: 'pass' }),
  defaultTtl: 3600
});

Backends

import { MemoryBackend } from '@avp-protocol/sdk';

const backend = new MemoryBackend();

import { FileBackend } from '@avp-protocol/sdk';

const backend = new FileBackend({
  path: './vault.enc',      // Path to encrypted vault file
  password: 'your-password' // Encryption password
});

import { KeychainBackend } from '@avp-protocol/sdk';

// First install keytar
// npm install keytar

const backend = new KeychainBackend({
  serviceName: 'my-app-avp'  // Service identifier in keychain
});

Operations

const info = await client.discover();

console.log(info.version);      // "0.1.0"
console.log(info.backends);     // ["memory", "file", "keychain"]
console.log(info.operations);   // ["DISCOVER", "AUTHENTICATE", ...]

const session = await client.authenticate({
  workspace: 'production',
  ttlSeconds: 7200  // 2 hours
});

console.log(session.sessionId);  // "sess_abc123..."
console.log(session.expiresAt);  // Date object

await client.store({
  sessionId: session.sessionId,
  name: 'DATABASE_URL',
  value: Buffer.from('postgres://...'),
  labels: { environment: 'production', service: 'api' },
  expiresAt: new Date('2025-12-31')
});

const secret = await client.retrieve({
  sessionId: session.sessionId,
  name: 'DATABASE_URL'
});

console.log(secret.value.toString());  // postgres://...
console.log(secret.version);           // 1
console.log(secret.labels);            // { environment: 'production', ... }

await client.delete({
  sessionId: session.sessionId,
  name: 'OLD_API_KEY'
});

const secrets = await client.list({
  sessionId: session.sessionId,
  labelFilter: { environment: 'production' }  // Optional filter
});

for (const secret of secrets) {
  console.log(secret.name, secret.version);
}

const result = await client.rotate({
  sessionId: session.sessionId,
  name: 'API_KEY',
  newValue: Buffer.from('sk-new-key-...')
});

console.log(result.previousVersion);  // 1
console.log(result.newVersion);       // 2

Error Handling

import { AVPError, ErrorCode } from '@avp-protocol/sdk';

try {
  await client.retrieve({ sessionId, name: 'UNKNOWN_KEY' });
} catch (error) {
  if (error instanceof AVPError) {
    switch (error.code) {
      case ErrorCode.NOT_FOUND:
        console.log('Secret not found');
        break;
      case ErrorCode.SESSION_EXPIRED:
        console.log('Session expired, re-authenticate');
        break;
      case ErrorCode.UNAUTHORIZED:
        console.log('Not authorized for this workspace');
        break;
      default:
        console.log('AVP Error:', error.message);
    }
  }
}

TypeScript Types

import type {
  AVPClient,
  Backend,
  Session,
  Secret,
  StoreOptions,
  RetrieveOptions,
  ListOptions,
  RotateResult,
  DiscoverInfo,
  AVPError,
  ErrorCode
} from '@avp-protocol/sdk';

Browser Usage

// Browser bundle
import { AVPClient, MemoryBackend } from '@avp-protocol/sdk/browser';

const client = new AVPClient({
  backend: new MemoryBackend()
});

Complete Example

import { AVPClient, FileBackend } from '@avp-protocol/sdk';

async function main() {
  // Initialize client
  const client = new AVPClient({
    backend: new FileBackend({
      path: './my-agent-vault.enc',
      password: process.env.VAULT_PASSWORD!
    })
  });

  // Create session
  const session = await client.authenticate({
    workspace: 'openai-agent'
  });

  // Store credentials
  await client.store({
    sessionId: session.sessionId,
    name: 'OPENAI_API_KEY',
    value: Buffer.from(process.env.OPENAI_API_KEY!),
    labels: { provider: 'openai' }
  });

  // Use in your agent
  const apiKey = await client.retrieve({
    sessionId: session.sessionId,
    name: 'OPENAI_API_KEY'
  });

  // Pass to OpenAI client
  const openai = new OpenAI({
    apiKey: apiKey.value.toString()
  });

  // Rotate when needed
  await client.rotate({
    sessionId: session.sessionId,
    name: 'OPENAI_API_KEY',
    newValue: Buffer.from('sk-new-key-...')
  });
}

main().catch(console.error);