JavaScript / TypeScript SDK

npm install @agentsecretstore/sdk
# or
yarn add @agentsecretstore/sdk
# or
pnpm add @agentsecretstore/sdk

# .env (local dev only — never commit!)
ASS_AGENT_KEY=ass_your_key_here

import { AgentVault } from '@agentsecretstore/sdk';

const vault = new AgentVault({
  agentKey: process.env.ASS_AGENT_KEY!,
  baseUrl: 'https://api.agentsecretstore.com', // default; do not include /v1
  defaultTtl: '1h',
  timeout: 30_000,
  retries: 3,
});

// ── getSecret ───────────────────────────────────────────────
// Retrieves a secret value by path.

const value = await vault.getSecret('production/gemini/GEMINI_API_KEY');
const metadata = await vault.getSecretWithMetadata('production/gemini/GEMINI_API_KEY');

console.log(value);                // "gemini-api-key-example"
console.log(metadata.version);     // 1
console.log(metadata.secret_type); // "api_key"
console.log(metadata.access_tier); // "sensitive"

// ── setSecret ───────────────────────────────────────────────
// Creates or updates a secret.

const result = await vault.setSecret('production/gemini/GEMINI_API_KEY', 'gemini-api-key-example', {
  secretType: 'api_key',
  accessTier: 'sensitive',
  metadata: { team: 'ml', env: 'prod' },
});

// Minimal – just path + value (tier defaults to 'standard')
await vault.setSecret('staging/config/feature-flag', 'true');
console.log(result.version);

// ── listSecrets ─────────────────────────────────────────────
// Lists secrets in a namespace (values not included).

const result = await vault.listSecrets('production/gemini');

console.log(result.total); // total matching secrets

for (const item of result.items) {
  console.log(`${item.namespace}/${item.key}`);
  console.log(item.access_tier);  // "sensitive"
  console.log(item.version);      // 3
  console.log(item.updated_at);   // ISO timestamp
  console.log(item.expired);      // false
}

// ── importEnv ───────────────────────────────────────────────
// Bulk-imports KEY=VALUE pairs from a .env-formatted string into a namespace.
// Each line becomes a separate secret. Blank lines and # comments are ignored.

import { readFileSync } from 'node:fs';

const content = readFileSync('.env.production', 'utf8');

const result = await vault.importEnv(content, 'production/gemini', {
  secretType: 'api_key',
  accessTier: 'sensitive',
  metadata: { source: '.env.production' },
});

console.log(result.imported_count);  // 4
console.log(result.imported);        // ["GEMINI_API_KEY", "DATABASE_URL", ...]
console.log(result.namespace);       // "production/gemini"

// ── requestToken ─────────────────────────────────────────────
// Issues a scoped, short-lived token.

const token = await vault.requestToken({
  scopes: ['secrets:read:production/gemini/*'],
  ttl: '1h',
  ipAllowlist: ['10.0.1.50'],
  maxUses: 10,
});

console.log(token.token);      // JWT bearer token
console.log(token.expires_at); // ISO timestamp

// ── deleteSecret ─────────────────────────────────────────────
// Deletion is intentionally human-only. The SDK method throws HUMAN_AUTH_REQUIRED.

await vault.deleteSecret('staging/gemini/GEMINI_TEST_KEY');

import {
  ApprovalRequiredError,
  AuthError,
  NetworkError,
  RateLimitError,
  ScopeError,
  SecretNotFoundError,
  ValidationError,
  VaultError,
} from '@agentsecretstore/sdk';

try {
  const value = await vault.getSecret('production/stripe/STRIPE_SECRET_KEY');
} catch (err) {
  if (err instanceof AuthError) {
    console.error('Auth failed:', err.message);
  } else if (err instanceof ScopeError) {
    console.error('Scope violation:', err.message);
  } else if (err instanceof SecretNotFoundError) {
    console.error('Secret not found:', err.message);
  } else if (err instanceof ApprovalRequiredError) {
    console.log('Pending approval ID:', err.approvalId);
  } else if (err instanceof RateLimitError) {
    console.log('Retry after:', err.retryAfter, 'seconds');
  } else if (err instanceof ValidationError) {
    console.error('Invalid request:', err.message);
  } else if (err instanceof NetworkError) {
    console.error('Network error:', err.cause);
  } else if (err instanceof VaultError) {
    console.error('Vault error:', err.message, err.code, err.status);
  }
}

// ── TypeScript types reference ──────────────────────────────

type AccessTier = 'standard' | 'sensitive' | 'critical';
type SecretType = 'api_key' | 'oauth_token' | 'db_credential' | 'ssh_key' | 'certificate' | 'custom';

interface SecretResponse {
  value: string;
  secret_type: SecretType;
  access_tier: AccessTier;
  metadata: Record<string, unknown>;
  version: number;
}

interface SecretListItem {
  namespace: string;
  key: string;
  version: number;
  secret_type: SecretType;
  access_tier: AccessTier;
  metadata: Record<string, unknown>;
  created_at: string;
  updated_at: string;
  expired: boolean;
}

interface SecretListResponse {
  namespace: string;
  items: SecretListItem[];
  total: number;
}

interface TokenResponse {
  token?: string;
  token_id?: string;
  expires_at?: string;
  requires_approval?: boolean;
  approval_id?: string;
}

interface AgentVaultOptions {
  agentKey: string;
  baseUrl?: string;        // Defaults to https://api.agentsecretstore.com
  autoToken?: boolean;     // Default: true
  defaultTtl?: string;     // Default: '1h'
  timeout?: number;        // Default: 30000
  retries?: number;        // Default: 3
}