@scoutscore/sdk

ScoutScore TypeScript SDK

Official TypeScript SDK for ScoutScore - Agent Trust Intelligence API.

Installation

npm install @scoutscore/sdk

or

yarn add @scoutscore/sdk

Quick Start

import { ScoutScore } from '@scoutscore/sdk';

// Initialize the client
const scout = new ScoutScore();

// Score a Bazaar service
const service = await scout.scoreBazaarService('api.example.com');
console.log(`Service score: ${service.score}/100 (${service.level})`);
console.log(`Uptime: ${service.reliability?.uptime7d}%`);

// Check fidelity (does the service do what it advertises?)
const fidelity = await scout.getFidelity('api.example.com');
console.log(`Fidelity: ${fidelity.fidelityScore}/100`);

// Browse the leaderboard
const board = await scout.getLeaderboard({ limit: 10 });
for (const svc of board.services) {
  console.log(`#${svc.rank} ${svc.domain} - ${svc.score}/100 (${svc.level})`);
}

Features

• Full TypeScript Support - Complete type definitions with IntelliSense
• Automatic Retries - Built-in exponential backoff for failed requests
• Fast & Lightweight - Zero dependencies, <15KB packed
• Error Handling - Custom error classes for precise error handling
• Well Documented - Comprehensive JSDoc comments

API Reference

Client Initialization

import { ScoutScore } from '@scoutscore/sdk';

// Simple initialization (public endpoints)
const scout = new ScoutScore();

// With custom configuration
const scout = new ScoutScore({
  baseUrl: 'https://scoutscore.ai',  // Custom base URL
  timeout: 15000,                     // Request timeout (ms)
  retries: 5,                         // Retry attempts
  apiKey: process.env.SCOUT_API_KEY  // For future paid tier
});

Score a Bazaar Service

Score a service from the x402 Bazaar:

const service = await scout.scoreBazaarService('api.example.com');

console.log(service.score);             // 75
console.log(service.level);             // "HIGH" | "MEDIUM" | "LOW" | "VERY_LOW"
console.log(service.endpointHealth);    // { status: "UP", latencyMs: 245, ... }
console.log(service.reliability);       // { uptime7d: 99.8, trend: "improving", ... }
console.log(service.recommendation.escrowAdvised);  // true | false | "optional"

Check Fidelity

Verify whether a service's actual behavior matches its advertised contract:

const fidelity = await scout.getFidelity('api.example.com');

console.log(fidelity.fidelityScore);                    // 100
console.log(fidelity.level);                            // "HIGH"
console.log(fidelity.layers.protocolCompliance.score);  // 100
console.log(fidelity.layers.contractConsistency.score); // 100
console.log(fidelity.layers.responseStructure.score);   // 100
console.log(fidelity.flags);                            // ["PROTOCOL_COMPLIANT", ...]

Browse the Leaderboard

Get a paginated, filterable list of all scored services:

// Top 10 services
const board = await scout.getLeaderboard({ limit: 10 });
console.log(`Total services: ${board.stats.totalServices}`);
for (const svc of board.services) {
  console.log(`#${svc.rank} ${svc.domain} - ${svc.score}/100 (${svc.level})`);
}

// Search and filter
const ai = await scout.getLeaderboard({
  search: 'image',
  category: 'AI & ML',
  limit: 20,
  offset: 0
});

Batch Score Services

Score multiple Bazaar services in one request (max 20):

const result = await scout.scoreBazaarBatch([
  'api.example.com',
  'service.example.com',
  'another.example.com'
]);

console.log(result.batch.averageScore);  // 68
console.log(result.batch.scored);        // 3
console.log(result.batch.distribution);  // { HIGH: 1, MEDIUM: 2, LOW: 0, VERY_LOW: 0 }
console.log(result.results);            // Array of scores

Get Bazaar Statistics

const stats = await scout.getBazaarStats();
console.log(stats.stats.services.total);        // 13681
console.log(stats.stats.pricing.averagePriceUSD); // 14.96
console.log(stats.stats.schemas.coveragePercent); // 18

Health Check

Check API health status:

const health = await scout.getHealth();
console.log(health.status);     // "ok" | "degraded" | "down"
console.log(health.version);    // "3.0"
console.log(health.endpoints);  // Available API endpoints

Error Handling

The SDK provides custom error classes for precise error handling:

import {
  ServiceNotFoundError,
  RateLimitError,
  ValidationError,
  NetworkError,
  TimeoutError
} from '@scoutscore/sdk';

try {
  const score = await scout.scoreBazaarService('nonexistent.com');
} catch (error) {
  if (error instanceof ServiceNotFoundError) {
    console.error('Service not found');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof TimeoutError) {
    console.error('Request timed out');
  } else if (error instanceof ValidationError) {
    console.error(`Invalid input: ${error.message}`);
  } else {
    console.error('Unexpected error:', error);
  }
}

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type {
  BazaarScore,
  FidelityResponse,
  LeaderboardResponse,
  TrustLevel
} from '@scoutscore/sdk';

// Type-safe responses
const service: BazaarScore = await scout.scoreBazaarService('api.example.com');
const level: TrustLevel = service.level;  // "HIGH" | "MEDIUM" | "LOW" | "VERY_LOW"

// IntelliSense autocomplete for all fields
if (service.recommendation.verdict === 'RECOMMENDED') {
  console.log(`Max transaction: $${service.recommendation.maxTransaction}`);
}

Examples

Check Service Reliability

const service = await scout.scoreBazaarService('api.example.com');

if (service.reliability?.sufficientData) {
  console.log(`7-day uptime: ${service.reliability.uptime7d}%`);
  console.log(`Avg latency: ${service.reliability.avgLatency7d}ms`);
  console.log(`Trend: ${service.reliability.trend}`);
} else {
  console.log('Not enough data for reliability metrics');
}

Handle Escrow Recommendations

const service = await scout.scoreBazaarService('untrusted.example.com');

if (service.recommendation.escrowAdvised === true) {
  console.log('Escrow required');
  console.log(`Reason: ${service.recommendation.escrowReason}`);
  console.log(`Suggested provider: ${service.recommendation.suggestedEscrowProvider?.name}`);
} else if (service.recommendation.escrowAdvised === 'optional') {
  console.log('Escrow optional (moderate risk)');
} else {
  console.log('Direct payment acceptable (trusted service)');
}

Batch Process Services

const domains = [
  'api1.example.com',
  'api2.example.com',
  'api3.example.com',
  // ... up to 20
];

const batch = await scout.scoreBazaarBatch(domains);

// Filter by trust level
const highTrust = batch.results.filter(r => r.level === 'HIGH');

console.log(`${highTrust.length} high-trust services found`);

Requirements

• Node.js 18 or higher (requires native fetch)
• TypeScript 5.0+ (for TypeScript projects)

Browser Support

The SDK works in modern browsers that support the Fetch API and ES2020:

import { ScoutScore } from '@scoutscore/sdk';

const scout = new ScoutScore();
const service = await scout.scoreBazaarService('api.example.com');
// Works in Chrome, Firefox, Safari, Edge

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

MIT - ScoutScore

Support

• Issues: https://github.com/scoutscore/scout/issues

Made by the ScoutScore team