valta-sdk 2.1.0 → 2.1.2

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/dist/chunk-LBY67QV7.js

@@ -0,0 +1,244 @@
+// src/errors/index.ts
+var ValtaError = class extends Error {
+  constructor(message, code, status) {
+    super(message);
+    this.name = "ValtaError";
+    this.code = code;
+    this.status = status;
+  }
+};
+var AuthError = class extends ValtaError {
+  constructor(message = "Invalid or missing API key") {
+    super(message, "UNAUTHORIZED", 401);
+    this.name = "AuthError";
+  }
+};
+var TierError = class extends ValtaError {
+  constructor(message, requiredTier) {
+    super(message, "TIER_LIMIT", 403);
+    this.name = "TierError";
+    this.requiredTier = requiredTier;
+    this.upgradeUrl = "https://valta.co/upgrade";
+  }
+};
+var RateLimitError = class extends ValtaError {
+  constructor(message = "Rate limit exceeded. Slow down your requests.") {
+    super(message, "RATE_LIMIT", 429);
+    this.name = "RateLimitError";
+  }
+};
+var NotFoundError = class extends ValtaError {
+  constructor(resource) {
+    super(`${resource} not found`, "NOT_FOUND", 404);
+    this.name = "NotFoundError";
+  }
+};
+
+// src/http/requester.ts
+var DEFAULT_BASE_URL = "https://valta.co/api/v1";
+var Requester = class {
+  constructor(apiKey, baseUrl) {
+    if (!apiKey || typeof apiKey !== "string") {
+      throw new AuthError("An API key is required. Get one at https://valta.co/dashboard/api-keys");
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl ?? DEFAULT_BASE_URL;
+  }
+  async request(path, options = {}) {
+    const { method = "GET", body } = options;
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: {
+        "x-api-key": this.apiKey,
+        "Content-Type": "application/json",
+        "X-Valta-SDK": "0.2.0"
+      },
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      let errorData = {};
+      try {
+        errorData = await res.json();
+      } catch {
+      }
+      const message = errorData.message ?? "An unknown error occurred";
+      switch (res.status) {
+        case 401:
+          throw new AuthError(message);
+        case 403:
+          throw new TierError(message, errorData.requiredTier ?? "builder");
+        case 404:
+          throw new NotFoundError(path);
+        case 429:
+          throw new RateLimitError(message);
+        default:
+          throw new ValtaError(message, "SERVER_ERROR", res.status);
+      }
+    }
+    return res.json();
+  }
+};
+
+// src/resources/agents.ts
+var AgentsResource = class {
+  constructor(requester) {
+    this.requester = requester;
+  }
+  // Get all agents
+  async list(params = {}) {
+    const query = new URLSearchParams();
+    if (params.limit) query.set("limit", String(params.limit));
+    if (params.offset) query.set("offset", String(params.offset));
+    if (params.status) query.set("status", params.status);
+    const qs = query.toString();
+    return this.requester.request(
+      `/agents${qs ? `?${qs}` : ""}`
+    );
+  }
+  // Get one agent by ID
+  async get(agentId) {
+    return this.requester.request(`/agents/${agentId}`);
+  }
+  // Create a new agent
+  async create(params) {
+    return this.requester.request("/agents", {
+      method: "POST",
+      body: params
+    });
+  }
+  // Update an agent
+  async update(agentId, params) {
+    return this.requester.request(`/agents/${agentId}`, {
+      method: "PATCH",
+      body: params
+    });
+  }
+  // Freeze an agent (stops it from spending)
+  async freeze(agentId) {
+    return this.requester.request(`/agents/${agentId}/freeze`, {
+      method: "POST"
+    });
+  }
+  // Unfreeze an agent
+  async unfreeze(agentId) {
+    return this.requester.request(`/agents/${agentId}/unfreeze`, {
+      method: "POST"
+    });
+  }
+  // Delete an agent
+  async delete(agentId) {
+    return this.requester.request(
+      `/agents/${agentId}`,
+      { method: "DELETE" }
+    );
+  }
+};
+
+// src/resources/wallets.ts
+var WalletsResource = class {
+  constructor(requester) {
+    this.requester = requester;
+  }
+  // Get wallet balance for an agent
+  async get(agentId) {
+    return this.requester.request(
+      `/agents/${agentId}/wallet`
+    );
+  }
+  // Transfer funds from one agent wallet to another
+  async transfer(agentId, params) {
+    return this.requester.request(
+      `/agents/${agentId}/wallet/transfer`,
+      { method: "POST", body: params }
+    );
+  }
+};
+
+// src/resources/policies.ts
+var PoliciesResource = class {
+  constructor(requester) {
+    this.requester = requester;
+  }
+  async list(agentId) {
+    const qs = agentId ? `?agentId=${agentId}` : "";
+    return this.requester.request(`/policies${qs}`);
+  }
+  async create(params) {
+    return this.requester.request("/policies", {
+      method: "POST",
+      body: params
+    });
+  }
+  async update(policyId, params) {
+    return this.requester.request(`/policies/${policyId}`, {
+      method: "PATCH",
+      body: params
+    });
+  }
+  async delete(policyId) {
+    return this.requester.request(`/policies/${policyId}`, {
+      method: "DELETE"
+    });
+  }
+};
+
+// src/resources/audit.ts
+var AuditResource = class {
+  constructor(requester) {
+    this.requester = requester;
+  }
+  async list(params = {}) {
+    const query = new URLSearchParams();
+    if (params.agentId) query.set("agentId", params.agentId);
+    if (params.limit) query.set("limit", String(params.limit));
+    if (params.offset) query.set("offset", String(params.offset));
+    if (params.from) query.set("from", params.from);
+    if (params.to) query.set("to", params.to);
+    const qs = query.toString();
+    return this.requester.request(`/audit${qs ? `?${qs}` : ""}`);
+  }
+};
+
+// src/resources/keys.ts
+var KeysResource = class {
+  constructor(requester) {
+    this.requester = requester;
+  }
+  async list() {
+    return this.requester.request("/keys");
+  }
+  async create(name) {
+    return this.requester.request("/keys", {
+      method: "POST",
+      body: { name }
+    });
+  }
+  async revoke(keyId) {
+    return this.requester.request(`/keys/${keyId}`, {
+      method: "DELETE"
+    });
+  }
+};
+
+// src/client.ts
+var ValtaClient = class {
+  constructor(config) {
+    const apiKey = typeof config === "string" ? config : config.apiKey;
+    const baseUrl = typeof config === "object" ? config.baseUrl : void 0;
+    const requester = new Requester(apiKey, baseUrl);
+    this.agents = new AgentsResource(requester);
+    this.wallets = new WalletsResource(requester);
+    this.policies = new PoliciesResource(requester);
+    this.audit = new AuditResource(requester);
+    this.keys = new KeysResource(requester);
+  }
+};
+
+export {
+  ValtaError,
+  AuthError,
+  TierError,
+  RateLimitError,
+  NotFoundError,
+  ValtaClient
+};

package/dist/cli/index.cjs

@@ -101,7 +101,7 @@ var Requester = class {
     const res = await fetch(`${this.baseUrl}${path}`, {
       method,
       headers: {
-        "Authorization": `Bearer ${this.apiKey}`,
+        "x-api-key": this.apiKey,
         "Content-Type": "application/json",
         "X-Valta-SDK": "0.2.0"
       },

package/dist/cli/index.js

@@ -1,6 +1,6 @@
 import {
   ValtaClient
-} from "../chunk-LPBJPXJO.js";
+} from "../chunk-LBY67QV7.js";
 
 // src/cli/commands/login.ts
 import { createInterface } from "readline";

package/dist/index.cjs

@@ -81,7 +81,7 @@ var Requester = class {
     const res = await fetch(`${this.baseUrl}${path}`, {
       method,
       headers: {
-        "Authorization": `Bearer ${this.apiKey}`,
+        "x-api-key": this.apiKey,
         "Content-Type": "application/json",
         "X-Valta-SDK": "0.2.0"
       },

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   TierError,
   ValtaClient,
   ValtaError
-} from "./chunk-LPBJPXJO.js";
+} from "./chunk-LBY67QV7.js";
 export {
   AuthError,
   NotFoundError,

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "valta-sdk",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Official SDK for Valta — AI agent financial infrastructure",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "exports": {
+    
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",