@agentbuy/sdk

AgentBuy Agent SDK - TypeScript SDK for AI Agent integration with the AgentBuy intelligent procurement platform.

Installation

npm install @agentbuy/sdk

Quick Start

import { AgentBuyClient } from '@agentbuy/sdk';

const client = new AgentBuyClient({
  baseUrl: 'https://agentbuy.top',
  did: 'did:example:your-agent-did',
  privateKey: `-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBg...
-----END PRIVATE KEY-----`,
});

// Authenticate using DID challenge-response
await client.authenticate();

// Search for products
const products = await client.searchProducts('laptop', {
  category: 'electronics',
  maxPrice: 10000,
  inStock: true,
});

// Compare prices across suppliers
const comparison = await client.compareProducts(['SKU-001', 'SKU-002']);

// Create a procurement order
const order = await client.createOrder({
  supplierDID: 'did:example:supplier-did',
  category: 'office-supplies',
  items: [
    { sku: 'SKU-001', name: 'A4 Paper', quantity: 100, unitPrice: 25, totalPrice: 2500 },
  ],
  requestedDeliveryDate: '2026-04-15',
});

console.log('Order created:', order.id, order.orderNo);

Authentication

The SDK uses W3C DID challenge-response authentication. The agent's private key is used to sign a server-provided challenge:

// This is handled automatically by authenticate()
// Internally:
// 1. POST /api/auth/challenge  →  get challenge + nonce
// 2. Sign challenge with RSA private key (RS256)
// 3. POST /api/auth/login/agent  →  receive JWT token

Products

// Search products
const products = await client.searchProducts('keyboard', {
  page: 1,
  pageSize: 20,
});

// Compare prices for specific SKUs
const result = await client.compareProducts(['KB-001', 'KB-002']);

// Enhanced comparison with quantity-based pricing
const enhanced = await client.compareProductsEnhanced(['KB-001'], 50);
// Returns: supplier prices, availability, price history, and recommendation

Orders

// Create order (idempotency key auto-generated if not provided)
const order = await client.createOrder({
  supplierDID: 'did:example:supplier',
  category: 'electronics',
  items: [
    { sku: 'KB-001', name: 'Keyboard', quantity: 10, unitPrice: 199, totalPrice: 1990 },
  ],
  idempotencyKey: 'unique-key-123',
});

// List orders
const orders = await client.getOrders({ page: 1, pageSize: 10, status: 'pending' });

// Get single order
const orderDetail = await client.getOrder(42);

// Cancel order
await client.cancelOrder(42, 'No longer needed');

// Confirm delivery
await client.confirmDelivery('order-id');

// Accept delivery (triggers payment)
await client.acceptDelivery('order-id');

Budget

const budget = await client.getBudgetStatus();
console.log(`Remaining: ¥${budget.remaining} / ¥${budget.total}`);

// Request additional budget (requires approval)
const request = await client.requestBudget(5000, 'Q2 procurement needs');

RFQ (Request for Quotation)

const rfq = await client.createRFQ({
  title: 'Office Furniture Q2',
  description: 'Need desks and chairs for new office space',
  items: [
    { name: 'Standing Desk', quantity: 20, unit: 'piece' },
    { name: 'Ergonomic Chair', quantity: 20, unit: 'piece' },
  ],
  supplierDIDs: ['did:example:supplier1', 'did:example:supplier2'],
  validForHours: 72,
});

// List RFQs
const rfqs = await client.getRFQs({ status: 'open' });

Event Subscription (SSE)

const subscription = client.subscribeEvents({
  onOrderCreated: (data) => console.log('New order:', data),
  onOrderShipped: (data) => console.log('Order shipped:', data),
  onBudgetWarning: (data) => console.warn('Budget low:', data),
  onBudgetExhausted: (data) => console.error('Budget exhausted:', data),
  onApprovalRequired: (data) => console.log('Approval needed:', data),
  onConnected: () => console.log('SSE connected'),
  onDisconnected: () => console.log('SSE disconnected - reconnecting...'),
  onError: (err) => console.error('SSE error:', err),
});

// Unsubscribe when done
subscription.unsubscribe();

Contracts

const contracts = await client.getContracts({ page: 1, pageSize: 10 });
const expiring = await client.getExpiringContracts(30); // contracts expiring within 30 days

Error Handling

import { AgentBuyClient } from '@agentbuy/sdk';
import type { AgentBuyError } from '@agentbuy/sdk';

const client = new AgentBuyClient({ ... });

try {
  await client.authenticate();
  await client.createOrder({ ... });
} catch (err: any) {
  const error = err as AgentBuyError;
  console.error(`Error [${error.code}]: ${error.message}`);
  // Handle specific error codes
  switch (error.code) {
    case 'TIMEOUT':
      // retry logic
      break;
    case 'NETWORK_ERROR':
      // check connectivity
      break;
    case 'FORBIDDEN':
      // check authorization
      break;
  }
}

TypeScript Types

All major entities have full TypeScript definitions:

• AgentBuyClientConfig - Client configuration
• Product - Product information
• Order, OrderItem, CreateOrderRequest - Order management
• BudgetStatus, BudgetRequest - Budget operations
• RFQ, CreateRFQRequest, RFQQuote - Request for quotation
• Contract - Supplier contracts
• CompareResult, EnhancedCompareResult - Price comparison results
• EventHandlers, EventSubscription - SSE event handling
• PaginatedResult<T>, PaginationOptions, SearchOptions - Query utilities
• AgentBuyError - Error structure

Direct Auth (Low-Level)

For advanced use cases, you can use the auth utilities directly:

import { signChallenge, hexFromJws } from '@agentbuy/sdk';

// Sign a challenge
const jws = await signChallenge(challengeString, privateKeyPem);
const signatureHex = await hexFromJws(jws);

License

MIT