valta-sdk 2.0.1 → 2.1.1

package/README.md

@@ -1,158 +1,236 @@
-# Valta SDK
+# valta-sdk
 
-Official TypeScript SDK for [Valta](https://valta.co) - Programmable AI Agent Spending Controls.
-
-## Installation
+Official JavaScript/TypeScript SDK for [Valta](https://valta.co) — AI agent financial infrastructure.
 
+Give your AI agents their own wallets, spending policies, kill switches, and audit logs.
 ```bash
 npm install valta-sdk
 ```
 
-## Quick Start
+---
 
+## Quick Start
 ```typescript
-import { Valta } from "valta-sdk";
+import Valta from 'valta-sdk';
 
-const valta = new Valta({
-  apiKey: "sk_valta_...", // Your API key from valta.co/dashboard/api-keys
+const valta = new Valta('vk_live_your_api_key');
+
+// Create an agent
+const agent = await valta.agents.create({
+  name: 'My Trading Agent',
+  type: 'trading',
 });
 
-// Request agent spending permission
-const result = await valta.requestSpend({
-  agentId: "research-agent",
-  amount: 20,
-  category: "api_calls",
-  description: "Purchase dataset access",
+// Assign a spend policy
+await valta.policies.create({
+  agentId: agent.id,
+  name: 'Daily limit',
+  maxSpendPerDay: 500,
+  currency: 'USDC',
 });
 
-if (result.approved) {
-  console.log("Approved! TX:", result.tx_id);
-} else if (result.requires_approval) {
-  console.log("Pending human approval:", result.request_id);
-} else {
-  console.log("Denied:", result.reason);
-}
-```
+// Check wallet balance
+const wallet = await valta.wallets.get(agent.id);
+console.log(wallet.balance); // { usdc: '245.00' }
 
-## Features
+// Freeze agent instantly
+await valta.agents.freeze(agent.id);
 
-- **Spending Controls** - Request permission before agents spend money
-- **Spending Policies** - Set per-transaction, daily, and monthly limits
-- **Human Approval Mode** - Require manual approval above thresholds
-- **Kill Switch** - Instantly freeze agent spending
-- **Agent Tools** - Configure and execute agent tools
-- **Agent Chains** - Create agent-to-agent workflows
-- **Balance Queries** - Check wallet balance programmatically
+// Pull immutable audit log
+const logs = await valta.audit.list({ agentId: agent.id });
+```
 
-## API Reference
+---
 
-### Initialize
+## Get an API Key
 
-```typescript
-const valta = new Valta({
-  apiKey: "sk_valta_...",
-  baseUrl: "https://valta.co", // optional, defaults to production
-});
+**Option 1 — Dashboard:**
+1. Go to [valta.co/dashboard](https://valta.co/dashboard)
+2. Navigate to API Keys
+3. Click Generate Key
+
+**Option 2 — CLI (no dashboard needed):**
+```bash
+npx valta-sdk login
 ```
 
-### Spending
+---
 
-```typescript
-// Request a spend action
-const result = await valta.requestSpend({
-  agentId: "my-agent",
-  amount: 10,
-  category: "api_calls",
-  description: "Call external API",
-});
+## CLI
+
+The SDK ships with a terminal CLI. Use Valta entirely without a browser.
+```bash
+# Authenticate
+valta login
+
+# List your agents
+valta agents list
 
-// Check balance
-const { balance, currency } = await valta.getBalance();
+# Freeze an agent
+valta agents freeze ag_abc123
+
+# Log out
+valta logout
 ```
 
-### Policies
+---
 
+## Agents
 ```typescript
-// Create a spending policy
-const policy = await valta.createPolicy({
-  agentId: "research-agent",
-  name: "Research Budget",
-  dailyLimit: 100,
-  monthlyLimit: 1000,
-  maxPerTransaction: 50,
-  requireApprovalAbove: 25,
-  allowedCategories: ["api_calls", "datasets"],
+// List all agents
+const { agents } = await valta.agents.list();
+
+// Get one agent
+const agent = await valta.agents.get('ag_abc123');
+
+// Create an agent
+const agent = await valta.agents.create({
+  name: 'Portfolio Watcher',
+  type: 'analytics',
 });
 
-// List all policies
-const policies = await valta.listPolicies();
+// Freeze an agent (stops all spending)
+await valta.agents.freeze('ag_abc123');
+
+// Unfreeze
+await valta.agents.unfreeze('ag_abc123');
+
+// Delete
+await valta.agents.delete('ag_abc123');
 ```
 
-### Approvals
+---
 
+## Wallets
 ```typescript
-// Get pending approvals
-const pending = await valta.getPendingApprovals();
-
-// Approve or reject
-await valta.approveRequest(requestId);
-await valta.rejectRequest(requestId, "Too expensive");
+// 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',
+});
 ```
 
-### Kill Switch
+---
 
+## Policies
 ```typescript
-// Freeze an agent immediately
-await valta.freezeAgent("rogue-agent", "Suspicious activity detected");
+// Create a spend policy
+await valta.policies.create({
+  agentId: 'ag_abc123',
+  name: 'Conservative limit',
+  maxSpendPerDay: 200,
+  maxSpendPerTransaction: 50,
+  currency: 'USDC',
+});
 
-// Unfreeze when resolved
-await valta.unfreezeAgent("rogue-agent");
+// List policies for an agent
+const policies = await valta.policies.list('ag_abc123');
+
+// Update a policy
+await valta.policies.update('pol_xyz', {
+  maxSpendPerDay: 500,
+});
 ```
 
-### Agent Tools
+---
 
+## Audit Logs
 ```typescript
-// Get tools configured for an agent
-const tools = await valta.getAgentTools("my-agent");
-
-// Toggle a tool on/off
-await valta.toggleTool(toolId, false);
+// Get full audit trail for an agent
+const { logs } = await valta.audit.list({
+  agentId: 'ag_abc123',
+  limit: 50,
+});
 
-// Execute a tool
-const result = await valta.executeTool("my-agent", toolId, { query: "data" });
+// 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...'
+// }
 ```
 
-### Agent Chains
+---
 
+## API Keys
 ```typescript
-// Create an agent chain (agent-to-agent workflow)
-const chain = await valta.createChain({
-  name: "Research Pipeline",
-  steps: [
-    { order: 1, agent_id: "research", agent_name: "Research Agent", action: "gather_data", input_from: "user" },
-    { order: 2, agent_id: "analysis", agent_name: "Analysis Agent", action: "analyze", input_from: "previous" },
-    { order: 3, agent_id: "report", agent_name: "Report Agent", action: "generate_report", input_from: "previous" },
-  ],
-});
+// List your API keys
+const keys = await valta.keys.list();
+
+// Create a new key
+const { key } = await valta.keys.create('production');
+console.log(key); // shown once — save it now
 
-// Execute a chain
-await valta.executeChain(chain.chain_id);
+// Revoke a key
+await valta.keys.revoke('key_abc123');
 ```
 
+---
+
 ## Error Handling
 
+The SDK throws typed errors so you always know what went wrong.
 ```typescript
-import { ValtaError } from "valta-sdk";
+import Valta, { AuthError, TierError, RateLimitError } from 'valta-sdk';
 
 try {
-  await valta.requestSpend({ agentId: "agent", amount: 1000 });
-} catch (error) {
-  if (error instanceof ValtaError) {
-    console.error(`Valta error (${error.status}):`, error.message);
+  await valta.agents.create({ name: 'Agent', type: 'trading' });
+} 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');
   }
 }
 ```
 
+| 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);
+```
+
+---
+
 ## License
 
-MIT
+MIT — built by [Valta](https://valta.co)

package/bin/valta.js

@@ -1,159 +1,14 @@
 #!/usr/bin/env node
+import { pathToFileURL } from 'url';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
 
-import { readFileSync, writeFileSync, existsSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
 
-const CONFIG_FILE = join(homedir(), ".valta", "config.json");
-const VERSION = "2.0.0";
+const cliPath = join(__dirname, '..', 'dist', 'cli', 'index.mjs');
 
-function loadConfig() {
-  if (!existsSync(CONFIG_FILE)) return {};
-  try { return JSON.parse(readFileSync(CONFIG_FILE, "utf8")); } catch { return {}; }
-}
-
-function saveConfig(data) {
-  const dir = join(homedir(), ".valta");
-  if (!existsSync(dir)) {
-    const { mkdirSync } = await import("fs");
-    mkdirSync(dir, { recursive: true });
-  }
-  writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2));
-}
-
-const args = process.argv.slice(2);
-const command = args[0];
-
-const help = `
-  Valta CLI v${VERSION}
-
-  COMMANDS
-    valta init              Initialize a new Valta project
-    valta login             Save your API key
-    valta create-agent      Generate an agent starter file
-    valta run               Run a quick agent query
-    valta --version         Show CLI version
-    valta help              Show this help
-
-  EXAMPLES
-    valta login
-    valta create-agent trading
-    valta run "What is BTC doing today?" --agent trading_signal
-`;
-
-async function main() {
-  switch (command) {
-    case "init": {
-      const template = `// Valta project starter
-// https://valta.co/docs
-
-import { ValtaClient } from "valta-sdk";
-
-const valta = new ValtaClient({
-  apiKey: process.env.VALTA_API_KEY,
-});
-
-// List available agents
-const agents = await valta.listAgents();
-console.log("Available agents:", agents.map(a => a.name));
-
-// Chat with the Trading Signal agent
-const agent = valta.createAgent("trading_signal");
-const response = await agent.chat("What is BTC doing today?");
-console.log(response.message);
-`;
-      writeFileSync("valta-starter.js", template);
-      console.log("✓ Created valta-starter.js");
-      console.log("  Run: node valta-starter.js");
-      break;
-    }
-
-    case "login": {
-      const { createInterface } = await import("readline");
-      const rl = createInterface({ input: process.stdin, output: process.stdout });
-      rl.question("Enter your Valta API key (from /dashboard/api-keys): ", (key) => {
-        rl.close();
-        const trimmed = key.trim();
-        if (!trimmed) { console.error("✗ No API key provided"); process.exit(1); }
-        const cfg = loadConfig();
-        cfg.apiKey = trimmed;
-        try { saveConfig(cfg); } catch {
-          const { mkdirSync } = require("fs");
-          mkdirSync(join(homedir(), ".valta"), { recursive: true });
-          saveConfig(cfg);
-        }
-        console.log(`✓ API key saved to ${CONFIG_FILE}`);
-        console.log("  You can now import it as: VALTA_API_KEY from your environment.");
-      });
-      break;
-    }
-
-    case "create-agent": {
-      const type = args[1] || "general";
-      const fileName = `${type}Agent.js`;
-      const agentTemplate = `// ${type.charAt(0).toUpperCase() + type.slice(1)} Agent — Valta SDK
-import { ValtaClient } from "valta-sdk";
-
-const valta = new ValtaClient({ apiKey: process.env.VALTA_API_KEY });
-const agent = valta.createAgent("${type}_agent");
-
-const response = await agent.chat("Your question here");
-console.log(response.message);
-`;
-      writeFileSync(fileName, agentTemplate);
-      console.log(`✓ Created ${fileName}`);
-      break;
-    }
-
-    case "run": {
-      const message = args[1];
-      const agentFlag = args.indexOf("--agent");
-      const agentId = agentFlag !== -1 ? args[agentFlag + 1] : "financial_advisor";
-
-      if (!message) {
-        console.error("Usage: valta run \"your question\" --agent <agent_id>");
-        process.exit(1);
-      }
-
-      const cfg = loadConfig();
-      const apiKey = cfg.apiKey || process.env.VALTA_API_KEY;
-      if (!apiKey) {
-        console.error("✗ No API key. Run: valta login");
-        process.exit(1);
-      }
-
-      console.log(`Running ${agentId}...`);
-      const res = await fetch(`https://valta.co/api/bot/${encodeURIComponent(agentId)}/chat`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` },
-        body: JSON.stringify({ message }),
-      });
-      const data = await res.json();
-      if (!res.ok) { console.error("✗", data.error || "Request failed"); process.exit(1); }
-      console.log("\n" + (data.message || data.response || JSON.stringify(data)));
-      break;
-    }
-
-    case "--version":
-    case "-v":
-      console.log(`valta-sdk v${VERSION}`);
-      break;
-
-    case "help":
-    case "--help":
-    case "-h":
-    case undefined:
-      console.log(help);
-      break;
-
-    default:
-      console.error(`Unknown command: ${command}`);
-      console.log(help);
-      process.exit(1);
-  }
-}
-
-main().catch((err) => {
-  console.error("✗", err.message);
+import(pathToFileURL(cliPath).href).catch((err) => {
+  console.error('Valta CLI failed to start:', err.message);
   process.exit(1);
-});
+});