valta-sdk 2.1.7 → 2.2.2

package/README.md

@@ -1,236 +1,127 @@
 # valta-sdk
 
-Official JavaScript/TypeScript SDK for [Valta](https://valta.co) — AI agent financial infrastructure.
+Official TypeScript SDK for [Valta](https://valta.co), financial governance infrastructure for autonomous AI agents.
+
+## Installation
 
-Give your AI agents their own wallets, spending policies, kill switches, and audit logs.
 ```bash
 npm install valta-sdk
 ```
 
----
-
 ## Quick Start
-```typescript
-import Valta from 'valta-sdk';
 
-const valta = new Valta('vk_live_your_api_key');
+```ts
+import { Valta } from 'valta-sdk'
 
-// Create an agent
-const agent = await valta.agents.create({
-  name: 'My Trading Agent',
-  type: 'trading',
-});
-
-// Assign a spend policy
-await valta.policies.create({
-  agentId: agent.id,
-  name: 'Daily limit',
-  maxSpendPerDay: 500,
-  currency: 'USDC',
-});
-
-// Check wallet balance
-const wallet = await valta.wallets.get(agent.id);
-console.log(wallet.balance); // { usdc: '245.00' }
-
-// Freeze agent instantly
-await valta.agents.freeze(agent.id);
-
-// Pull immutable audit log
-const logs = await valta.audit.list({ agentId: agent.id });
-```
+const valta = new Valta({
+  apiKey: process.env.VALTA_API_KEY!
+})
 
----
-
-## Get an API Key
+const agent = await valta.agents.create({
+  name: 'Research Agent',
+  wallet: {
+    initialBalance: 100,
+    dailyLimit: 50
+  },
+  policy: {
+    requireApprovalAbove: 25,
+    blockedCategories: ['gambling']
+  }
+})
 
-**Option 1 — Dashboard:**
-1. Go to [valta.co/dashboard](https://valta.co/dashboard)
-2. Navigate to API Keys
-3. Click Generate Key
+const run = await valta.agents.run(agent.id, {
+  task: 'Analyse last month spend and identify top cost drivers'
+})
 
-**Option 2 — CLI (no dashboard needed):**
-```bash
-npx valta-sdk login
+const { data: entries } = await valta.audit.list({ agentId: agent.id })
+console.log(agent.id, run.status, entries.length)
 ```
 
----
-
 ## CLI
 
-The SDK ships with a terminal CLI. Use Valta entirely without a browser.
 ```bash
-# Authenticate
 valta login
-
-# List your agents
 valta agents list
-
-# Freeze an agent
-valta agents freeze ag_abc123
-
-# Log out
-valta logout
+valta agents create "Research Agent"
+valta agents run agent_123 "Review Q4 vendor spend"
+valta wallets get agent_123
+valta wallets balance agent_123
+valta wallets transactions agent_123
+valta keys create "Production Server"
+valta audit agent_123
 ```
 
----
-
-## Agents
-```typescript
-// List all agents
-const { agents } = await valta.agents.list();
-
-// Get one agent
-const agent = await valta.agents.get('ag_abc123');
+## API Reference
 
-// Create an agent
-const agent = await valta.agents.create({
-  name: 'Portfolio Watcher',
-  type: 'analytics',
-});
+### `valta.auth`
 
-// Freeze an agent (stops all spending)
-await valta.agents.freeze('ag_abc123');
+- `login(email, password)` returns `{ token, user }`
+- `logout()` clears the server session when supported
+- `whoami()` returns the authenticated user profile
+- `refreshToken()` returns a fresh API token
 
-// Unfreeze
-await valta.agents.unfreeze('ag_abc123');
+### `valta.agents`
 
-// Delete
-await valta.agents.delete('ag_abc123');
-```
+- `create(params)` creates a governed agent
+- `list(params?)` lists agents with `{ data, pagination }`
+- `get(agentId)` fetches one agent with wallet and policy
+- `update(agentId, params)` updates metadata
+- `delete(agentId)` deletes an agent
+- `freeze(agentId)` blocks runs and transactions
+- `unfreeze(agentId)` restores active status
+- `run(agentId, params)` starts a run
+- `getRun(agentId, runId)` fetches a run
+- `listRuns(agentId, params?)` lists runs
 
----
-
-## Wallets
-```typescript
-// Get wallet balance
-const wallet = await valta.wallets.get('ag_abc123');
-// { usdc: '500.00', usdcPending: '0.00' }
-
-// Transfer funds between agents
-await valta.wallets.transfer('ag_abc123', {
-  toAgentId: 'ag_def456',
-  amount: '100.00',
-  currency: 'USDC',
-  note: 'Fund allocation',
-});
-```
+### `valta.wallets`
 
----
-
-## Policies
-```typescript
-// Create a spend policy
-await valta.policies.create({
-  agentId: 'ag_abc123',
-  name: 'Conservative limit',
-  maxSpendPerDay: 200,
-  maxSpendPerTransaction: 50,
-  currency: 'USDC',
-});
-
-// List policies for an agent
-const policies = await valta.policies.list('ag_abc123');
-
-// Update a policy
-await valta.policies.update('pol_xyz', {
-  maxSpendPerDay: 500,
-});
-```
+- `get(agentId)` returns balance, spend, limits, and address
+- `getBalance(agentId)` returns the USDC balance as a number
+- `getDepositAddress(agentId)` returns a Base USDC address and QR data URL
+- `listTransactions(agentId, params?)` lists wallet transactions
+- `transfer(params)` transfers funds between agent wallets
 
----
-
-## Audit Logs
-```typescript
-// Get full audit trail for an agent
-const { logs } = await valta.audit.list({
-  agentId: 'ag_abc123',
-  limit: 50,
-});
-
-// Each log entry is immutable and hash-chained
-console.log(logs[0]);
-// {
-//   id: 'log_001',
-//   action: 'transfer',
-//   amount: '100.00',
-//   hash: '0xabc...',
-//   previousHash: '0xdef...',
-//   createdAt: '2026-03-21T...'
-// }
-```
+### `valta.policies`
 
----
+- `create(params)` creates a spending policy
+- `get(agentId)` returns a policy or `null`
+- `update(agentId, params)` updates a policy
+- `delete(agentId)` removes a policy
+- `list()` lists policies
 
-## API Keys
-```typescript
-// List your API keys
-const keys = await valta.keys.list();
+### `valta.audit`
 
-// Create a new key
-const { key } = await valta.keys.create('production');
-console.log(key); // shown once — save it now
+- `list(params?)` lists audit entries
+- `get(entryId)` fetches one entry
+- `export(params?)` auto-paginates all matching entries
+- `verify(agentId)` verifies audit chain integrity
 
-// Revoke a key
-await valta.keys.revoke('key_abc123');
-```
+### `valta.keys`
 
----
+- `create({ name })` creates an API key and returns `fullKey` once
+- `list()` lists key metadata
+- `revoke(keyId)` revokes a key
 
 ## Error Handling
 
-The SDK throws typed errors so you always know what went wrong.
-```typescript
-import Valta, { AuthError, TierError, RateLimitError } from 'valta-sdk';
+```ts
+import { Valta, ValtaError } from 'valta-sdk'
 
 try {
-  await valta.agents.create({ name: 'Agent', type: 'trading' });
+  await valta.agents.get('missing')
 } catch (err) {
-  if (err instanceof TierError) {
-    console.log(`Upgrade required: ${err.requiredTier}`);
-    console.log(`Upgrade at: ${err.upgradeUrl}`);
-  } else if (err instanceof AuthError) {
-    console.log('Invalid API key');
-  } else if (err instanceof RateLimitError) {
-    console.log('Slow down — rate limit hit');
+  if (err instanceof ValtaError) {
+    console.log(err.code)
+    console.log(err.status)
+    console.log(err.message)
   }
 }
 ```
 
-| Error | Status | When |
-|---|---|---|
-| `AuthError` | 401 | Invalid or missing API key |
-| `TierError` | 403 | Feature requires a higher tier |
-| `RateLimitError` | 429 | Too many requests |
-| `NotFoundError` | 404 | Agent/resource not found |
-| `ValtaError` | 5xx | Server error |
-
----
-
-## Tier Limits
-
-| Feature | Free | Builder | Startup | Enterprise |
-|---|---|---|---|---|
-| Agent wallets | 1 | 10 | Unlimited | Unlimited |
-| Policies | 1 | Unlimited | Unlimited | Unlimited |
-| API calls/day | 100 | 1,000 | Unlimited | Unlimited |
-| Audit export | ✗ | ✗ | ✓ | ✓ |
-| Team members | 1 | 1 | 5 | Unlimited |
-
----
-
-## TypeScript
-
-The SDK is written in TypeScript. All types are included — no `@types` package needed.
-```typescript
-import Valta, { Agent, Policy, WalletBalance } from 'valta-sdk';
-
-const agent: Agent = await valta.agents.get('ag_abc123');
-const wallet: WalletBalance = await valta.wallets.get(agent.id);
-```
+## Documentation
 
----
+[valta.co/docs](https://valta.co/docs)
 
 ## License
 
-MIT — built by [Valta](https://valta.co)
+MIT

package/bin/valta.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
-import { pathToFileURL } from 'url';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const cliPath = join(__dirname, '..', 'dist', 'cli', 'index.mjs');
-
-import(pathToFileURL(cliPath).href).catch((err) => {
-  console.error('Valta CLI failed to start:', err.message);
-  process.exit(1);
+import { pathToFileURL } from 'url';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const cliPath = join(__dirname, '..', 'dist', 'cli', 'index.js');
+
+import(pathToFileURL(cliPath).href).catch((err) => {
+  console.error('Valta CLI failed to start:', err.message);
+  process.exit(1);
 });