npm install altsportsleagues
# or
yarn add altsportsleagues
# or
pnpm add altsportsleagues

import { AltSportsLeagues } from 'altsportsleagues';

const client = new AltSportsLeagues({
  apiKey: process.env.ASL_API_KEY,
  timeout: 30000, // optional, in milliseconds
});

// List leagues
const leagues = await client.leagues.list({
  tier: 'tier-2',
  sport: 'Soccer',
  limit: 10
});

console.log(leagues.data);

interface ClientOptions {
  apiKey: string;              // Required: Your API key
  baseUrl?: string;            // Optional: API base URL
  timeout?: number;            // Optional: Request timeout (ms)
  retries?: number;            // Optional: Max retry attempts
  retryDelay?: number;         // Optional: Delay between retries (ms)
  headers?: Record<string, string>; // Optional: Custom headers
}

const client = new AltSportsLeagues({
  apiKey: 'your_api_key',
  timeout: 30000,
  retries: 3,
  retryDelay: 1000,
});

const leagues = await client.leagues.list({
  sportType?: string;
  archetype?: string;
  tier?: 'tier-1' | 'tier-2' | 'tier-3' | 'tier-4';
  country?: string;
  limit?: number;   // default: 100
  offset?: number;  // default: 0
});

// Response type
interface LeagueListResponse {
  data: LeagueBasic[];
  meta: {
    total: number;
    page: number;
    limit: number;
    has_more: boolean;
    api_version: string;
    timestamp: string;
  };
}

const league = await client.leagues.get('league_001');

// Response type
interface LeagueDetailResponse {
  data: LeagueDetailed;
  meta: MetaInfo;
}

const stats = await client.leagues.stats();

// Response includes tier_breakdown, sport_bucket_breakdown, etc.

const results = await client.discovery.search({
  query: 'professional pickleball leagues in North America',
  minConfidence?: number;  // 0-1, default: 0.5
  limit?: number;          // default: 10
});

// Each result includes confidence_score

const similar = await client.discovery.similar('league_001', {
  limit?: number;  // default: 10
});

// Each result includes similarity_score

const valuation = await client.valuation.evaluate({
  leagueId: 'league_001',
  includeApiAssessment?: boolean;   // default: false
  includeDataQuality?: boolean;     // default: false
});

// Response includes:
// - composite_score (0-100)
// - tier classification
// - dimensional breakdown
// - estimated_annual_value
// - reasoning

const score = await client.qualification.score({
  leagueId: 'league_001',
  mappings: [
    {
      source: 'match_id',
      target: 'event.id',
      confirmed: true
    }
  ],
  qualityMetrics: {
    overallScore: 85,
    mappedPercentage: 90,
    confirmedPercentage: 80,
    recommendation: 'accept'
  }
});

// Response includes:
// - qualified (boolean)
// - qualification_score (0-100)
// - recommendation
// - estimated_tier
// - engineering_effort estimate

import { AltSportsLeagues, APIError } from 'altsportsleagues';

const client = new AltSportsLeagues({ apiKey: 'demo-0001' });

try {
  const league = await client.leagues.get('invalid_id');
} catch (error) {
  if (error instanceof APIError) {
    console.error('API Error:', error.message);
    console.error('Status:', error.status);
    console.error('Code:', error.code);
    console.error('Details:', error.details);
  } else {
    console.error('Unexpected error:', error);
  }
}

class APIError extends Error {
  status: number;        // HTTP status code
  code: string;          // Error code (e.g., 'RESOURCE_NOT_FOUND')
  details?: any;         // Additional error details
}

class RateLimitError extends APIError {
  retryAfter: number;    // Seconds until rate limit resets
}

class AuthenticationError extends APIError {
  // Thrown for 401 responses
}

class ValidationError extends APIError {
  fields: Record<string, string>;  // Field-level validation errors
}

import type {
  LeagueBasic,
  LeagueDetailed,
  LeagueListResponse,
  SearchResult,
  ValuationResult,
  QualificationResult,
} from 'altsportsleagues';

const leagues: LeagueListResponse = await client.leagues.list();
const league: LeagueDetailed = leagues.data[0];

async function* paginateLeagues(
  client: AltSportsLeagues,
  options: any = {}
) {
  let offset = 0;
  const limit = options.limit || 100;

  while (true) {
    const response = await client.leagues.list({
      ...options,
      limit,
      offset,
    });

    yield* response.data;

    if (!response.meta.has_more) break;
    offset += limit;
  }
}

// Usage
for await (const league of paginateLeagues(client, { tier: 'tier-2' })) {
  console.log(league.name);
}

const client = new AltSportsLeagues({
  apiKey: 'your_api_key',
  headers: {
    'X-Custom-Header': 'value',
    'User-Agent': 'MyApp/1.0'
  }
});

const client = new AltSportsLeagues({
  apiKey: 'your_api_key',
  retries: 3,           // Max 3 retries
  retryDelay: 1000,     // 1 second between retries
});

const client = new AltSportsLeagues({
  apiKey: 'your_api_key',
  timeout: 10000,  // 10 second timeout
});

try {
  const leagues = await client.leagues.list();
} catch (error) {
  if (error.code === 'ETIMEDOUT') {
    console.error('Request timed out');
  }
}

const tier1Leagues = await client.leagues.list({ tier: 'tier-1' });
const tier2Leagues = await client.leagues.list({ tier: 'tier-2' });

console.log(`Tier 1: ${tier1Leagues.data.length} leagues`);
console.log(`Tier 2: ${tier2Leagues.data.length} leagues`);

// Search for leagues
const results = await client.discovery.search({
  query: 'professional pickleball',
  minConfidence: 0.7
});

// Evaluate top result
if (results.data.length > 0) {
  const topLeague = results.data[0];
  const valuation = await client.valuation.evaluate({
    leagueId: topLeague.id
  });
  
  console.log(`${topLeague.name}:`);
  console.log(`  Score: ${valuation.data.composite_score}/100`);
  console.log(`  Tier: ${valuation.data.tier}`);
  console.log(`  Value: $${valuation.data.estimated_annual_value}`);
}

const [league1, league2] = await Promise.all([
  client.valuation.evaluate({ leagueId: 'league_001' }),
  client.valuation.evaluate({ leagueId: 'league_002' })
]);

console.log('Comparison:');
console.log(`League 1: ${league1.data.composite_score}/100`);
console.log(`League 2: ${league2.data.composite_score}/100`);