npm package: @scoutscore/sdk
Description: Official TypeScript SDK for ScoutScore - Agent Trust Intelligence API
Author: ScoutScore
Latest version: 0.1.1

# ScoutScore TypeScript SDK

Official TypeScript SDK for [ScoutScore](https://scoutscore.ai) - Agent Trust Intelligence API.

[![npm version](https://img.shields.io/npm/v/@scoutscore/sdk.svg)](https://www.npmjs.com/package/@scoutscore/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
npm install @scoutscore/sdk
```

or

```bash
yarn add @scoutscore/sdk
```

## Quick Start

```typescript
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

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
// 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):

```typescript
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

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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

```typescript
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

```typescript
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

```typescript
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:

```typescript
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](https://github.com/scoutscore/scout/blob/main/CONTRIBUTING.md) for details.

## License

MIT - ScoutScore

## Support

- **Issues:** https://github.com/scoutscore/scout/issues

---

Made by the ScoutScore team