budgent-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+export interface BudgentConfig {
+    baseUrl: string;
+    keyId?: string;
+    hmacSecret?: string;
+    bearer?: string;
+}
+export interface PayInput {
+    amount: number;
+    domain?: string;
+    recipient?: string;
+    url?: string;
+    resource?: string;
+    taskId?: string;
+    idempotencyKey?: string;
+    metadata?: Record<string, any>;
+    model?: 'PUSH' | 'INVOICE';
+}
+export interface PaymentResult {
+    id: string;
+    status: 'SETTLED' | 'APPROVED' | 'REVERTED' | 'HELD' | 'DENIED' | 'FAILED' | 'CREATED';
+    reason: string;
+    amount: number;
+    asset: string;
+    recipient: string;
+    context: {
+        domain: string;
+        url: string;
+        resource: string;
+        taskId: string;
+    };
+    contextHash: string;
+    signature: string | null;
+    explorer: string | null;
+    ruleResults?: {
+        rule: string;
+        status: string;
+        detail: string;
+    }[];
+}
+/**
+ * Budgent agent SDK. The agent pays through explicit REST calls — no x402, no transport
+ * games — and the on-chain program enforces the budget. The agent never holds the wallet's
+ * keys, only a scoped API key.
+ */
+export declare class BudgentClient {
+    private cfg;
+    constructor(cfg: BudgentConfig);
+    private sign;
+    private req;
+    /** Create + execute a payment (push model). Returns the on-chain verdict. */
+    pay(input: PayInput): Promise<PaymentResult>;
+    getPayment(id: string): Promise<PaymentResult>;
+    /** The agent's own budget snapshot (policy + balance + spend). */
+    me(): Promise<any>;
+}
+export default BudgentClient;

package/dist/index.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BudgentClient = void 0;
+const crypto_1 = require("crypto");
+/**
+ * Budgent agent SDK. The agent pays through explicit REST calls — no x402, no transport
+ * games — and the on-chain program enforces the budget. The agent never holds the wallet's
+ * keys, only a scoped API key.
+ */
+class BudgentClient {
+    constructor(cfg) {
+        this.cfg = cfg;
+        if (!cfg.baseUrl)
+            throw new Error('baseUrl required');
+    }
+    sign(method, path, body) {
+        if (this.cfg.keyId && this.cfg.hmacSecret) {
+            const ts = Math.floor(Date.now() / 1000).toString();
+            const base = `${ts}.${method}.${path}.${body}`;
+            const sig = (0, crypto_1.createHmac)('sha256', this.cfg.hmacSecret).update(base).digest('hex');
+            return {
+                'X-Budgent-Key': this.cfg.keyId,
+                'X-Budgent-Timestamp': ts,
+                'X-Budgent-Signature': sig,
+            };
+        }
+        if (this.cfg.bearer)
+            return { Authorization: `Bearer ${this.cfg.bearer}` };
+        throw new Error('provide keyId+hmacSecret or bearer');
+    }
+    async req(method, path, payload) {
+        const body = payload != null ? JSON.stringify(payload) : '';
+        const res = await fetch(this.cfg.baseUrl + path, {
+            method,
+            headers: { 'Content-Type': 'application/json', ...this.sign(method, path, body) },
+            body: method === 'GET' ? undefined : body,
+        });
+        const text = await res.text();
+        const json = text ? JSON.parse(text) : {};
+        if (!res.ok)
+            throw new Error(`${res.status} ${json.message || text}`);
+        return json;
+    }
+    /** Create + execute a payment (push model). Returns the on-chain verdict. */
+    pay(input) {
+        return this.req('POST', '/v1/payments', input);
+    }
+    getPayment(id) {
+        return this.req('GET', `/v1/payments/${id}`);
+    }
+    /** The agent's own budget snapshot (policy + balance + spend). */
+    me() {
+        return this.req('GET', '/v1/me');
+    }
+}
+exports.BudgentClient = BudgentClient;
+exports.default = BudgentClient;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "budgent-sdk",
+  "version": "0.1.0",
+  "description": "Budgent agent SDK — pay autonomously through a REST API, bounded by a non-custodial on-chain program (per-tx cap, daily limit, allow/block lists, co-sign).",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "tsc -p tsconfig.json"
+  },
+  "keywords": [
+    "budgent",
+    "solana",
+    "ai-agents",
+    "agents",
+    "payments",
+    "wallet",
+    "x402"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,89 @@
+import { createHmac } from 'crypto';
+
+export interface BudgentConfig {
+  baseUrl: string;
+  keyId?: string;
+  hmacSecret?: string;
+  bearer?: string; // alternative simple auth
+}
+
+export interface PayInput {
+  amount: number;
+  domain?: string; // resolved via the vault's resource registry
+  recipient?: string; // or a direct pubkey
+  url?: string;
+  resource?: string;
+  taskId?: string;
+  idempotencyKey?: string;
+  metadata?: Record<string, any>;
+  model?: 'PUSH' | 'INVOICE';
+}
+
+export interface PaymentResult {
+  id: string;
+  status: 'SETTLED' | 'APPROVED' | 'REVERTED' | 'HELD' | 'DENIED' | 'FAILED' | 'CREATED';
+  reason: string;
+  amount: number;
+  asset: string;
+  recipient: string;
+  context: { domain: string; url: string; resource: string; taskId: string };
+  contextHash: string;
+  signature: string | null;
+  explorer: string | null;
+  ruleResults?: { rule: string; status: string; detail: string }[];
+}
+
+/**
+ * Budgent agent SDK. The agent pays through explicit REST calls — no x402, no transport
+ * games — and the on-chain program enforces the budget. The agent never holds the wallet's
+ * keys, only a scoped API key.
+ */
+export class BudgentClient {
+  constructor(private cfg: BudgentConfig) {
+    if (!cfg.baseUrl) throw new Error('baseUrl required');
+  }
+
+  private sign(method: string, path: string, body: string): Record<string, string> {
+    if (this.cfg.keyId && this.cfg.hmacSecret) {
+      const ts = Math.floor(Date.now() / 1000).toString();
+      const base = `${ts}.${method}.${path}.${body}`;
+      const sig = createHmac('sha256', this.cfg.hmacSecret).update(base).digest('hex');
+      return {
+        'X-Budgent-Key': this.cfg.keyId,
+        'X-Budgent-Timestamp': ts,
+        'X-Budgent-Signature': sig,
+      };
+    }
+    if (this.cfg.bearer) return { Authorization: `Bearer ${this.cfg.bearer}` };
+    throw new Error('provide keyId+hmacSecret or bearer');
+  }
+
+  private async req(method: string, path: string, payload?: any): Promise<any> {
+    const body = payload != null ? JSON.stringify(payload) : '';
+    const res = await fetch(this.cfg.baseUrl + path, {
+      method,
+      headers: { 'Content-Type': 'application/json', ...this.sign(method, path, body) },
+      body: method === 'GET' ? undefined : body,
+    });
+    const text = await res.text();
+    const json = text ? JSON.parse(text) : {};
+    if (!res.ok) throw new Error(`${res.status} ${json.message || text}`);
+    return json;
+  }
+
+  /** Create + execute a payment (push model). Returns the on-chain verdict. */
+  pay(input: PayInput): Promise<PaymentResult> {
+    return this.req('POST', '/v1/payments', input);
+  }
+
+  getPayment(id: string): Promise<PaymentResult> {
+    return this.req('GET', `/v1/payments/${id}`);
+  }
+
+  /** The agent's own budget snapshot (policy + balance + spend). */
+  me(): Promise<any> {
+    return this.req('GET', '/v1/me');
+  }
+}
+
+export default BudgentClient;