@truce/sdk

TypeScript SDK for TRUCE CORE -- Trust Infrastructure for Agent Commerce. Zero runtime dependencies, uses native fetch (Node 18+).

Installation

npm install @truce/sdk

Quickstart

import { TruceClient } from '@truce/sdk';

const client = new TruceClient('http://localhost:8000');

// Register and authenticate
const agent = await client.registerAgent('FIRM001', 'Acme Corp', 'bot-1');
const session = await client.authenticate(agent.agent_id);
// Bearer token is now set automatically

// Submit an offer
const offer = await client.submitOffer('Selling 500 MT wheat at $320/MT FOB');

// Find matches
const result = await client.findMatches(offer.offer_id);
console.log(`Found ${result.total_found} matches`);

// Execute a match and manage escrow
if (result.matches.length > 0) {
  const execution = await client.executeMatch(
    result.matches[0].buyer_offer_id,
    result.matches[0].seller_offer_id,
  );
  await client.confirmEscrow(execution.match.match_id, 'buyer');
  await client.confirmEscrow(execution.match.match_id, 'seller');
}

// Compute trust score
const alpha = await client.computeAlpha(agent.agent_id);
console.log(`ALPHA score: ${alpha.score}`);

API Reference

Constructor

new TruceClient(baseUrl: string, apiKey?: string, timeout?: number)

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | baseUrl | string | -- | API root URL | | apiKey | string | undefined | Pre-existing Bearer token | | timeout | number | 30000 | Request timeout (ms) |

KYA Gateway

| Method | Returns | |--------|---------| | registerAgent(firmId, firmName, agentName, publicKey?, agentId?) | RegisteredAgent | | authenticate(agentId, ttlMinutes?, requestFeatures?) | AuthSession | | getBaseline(agentId) | AgentBaseline | | getAnomalyScore(agentId) | AnomalyScore |

Sanitization Engine

| Method | Returns | |--------|---------| | extractClaims(rawText, agentId, context?) | ExtractionResult | | validateTcos(offerData) | ValidationResult | | notarize(rawText, agentId, firmId) | NotarizedOffer |

Offers

| Method | Returns | |--------|---------| | submitOffer(rawText, agentId?, firmId?) | Offer | | getOffer(offerId) | Offer | | listOffers(options?) | OfferList | | cancelOffer(offerId) | OfferCancellation |

Matching Engine

| Method | Returns | |--------|---------| | findMatches(offerId) | FindMatchesResult | | executeMatch(buyerOfferId, sellerOfferId) | MatchExecution | | getMatch(matchId) | Match |

Escrow

| Method | Returns | |--------|---------| | getEscrow(matchId) | EscrowState | | confirmEscrow(matchId, side) | EscrowState | | releaseEscrow(matchId, reason) | EscrowState |

AVX (Agent Volatility Index)

| Method | Returns | |--------|---------| | ingestAvxEvents(events) | IngestResult | | getAvx(sector, baselineCancellationRate?) | AVXScore | | getAvxHistory(sector) | Record<string, unknown> | | listAvxSectors() | Record<string, unknown> |

ALPHA (Trust Score)

| Method | Returns | |--------|---------| | computeAlpha(agentId, counterpartyId?, sector?) | AlphaScore | | getAlphaHistory(agentId) | AlphaScore[] |

Webhooks

| Method | Returns | |--------|---------| | registerWebhook(url, events, secret?) | Webhook | | listWebhooks() | Webhook[] | | unregisterWebhook(webhookId) | void | | getWebhookDeliveries(webhookId) | WebhookDelivery[] |

Review Queue

| Method | Returns | |--------|---------| | listPendingReviews() | ReviewItem[] | | listAllReviews() | ReviewItem[] | | getReview(reviewId) | ReviewItem | | approveReview(reviewId, notes?) | ReviewItem | | rejectReview(reviewId, reason?) | ReviewItem |

RISK (Data Product)

| Method | Returns | |--------|---------| | assessRisk(agentId, sector?) | AgentRiskProfile | | assessPortfolioRisk(agentIds, sector?) | PortfolioRiskSummary | | analyzeSectorRisk(sector, topN?) | SectorRiskAnalysis | | configureRiskAlert(agentId, threshold?) | Record<string, unknown> | | getRiskAlerts(agentId?) | RiskAlert[] |

Error Handling

All API errors throw typed exceptions:

import { TruceClient, NotFoundError, ValidationError } from '@truce/sdk';

try {
  await client.getOffer('nonexistent');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Offer not found');
  } else if (err instanceof ValidationError) {
    console.log('Invalid input:', err.detail);
  }
}

| Error Class | HTTP Status | |-------------|-------------| | AuthenticationError | 401 | | ForbiddenError | 403 | | NotFoundError | 404 | | ConflictError | 409 | | ValidationError | 422 | | ServerError | 5xx | | TruceError | any other |

License

Apache 2.0 -- see LICENSE for details.

Links

• Documentation
• Repository
• Issue Tracker