fansunited-data-layer

A TypeScript library for fetching and transforming sports data from multiple API providers. Returns clean, canonical types that are provider-agnostic.

Installation

npm install fansunited-data-layer

Quick Start

import { setConfig, getFootballMatch } from "fansunited-data-layer";

// Configure the library (once at app startup)
setConfig({
    sportal365Sports: {
        username: "your-username",
        password: "your-password",
        projectId: "your-project-id",
    },
});

// Fetch a match
const match = await getFootballMatch("7576255");
console.log(match.competitorOne.name); // "Manchester United"
console.log(match.score?.competitorOne); // "2"

API Reference

Configuration

setConfig(config)

Initialize the library with your API credentials.

setConfig({
  sportal365Sports: {
    username: string;      // API username
    password: string;      // API password
    projectId: string;     // Your project ID
    languageCode?: string; // Default language (default: 'en')
    oddClient?: string;    // Odd client identifier for odds
    timeout?: number;      // Request timeout in ms
  }
});

Football Endpoints

getFootballMatch(matchId, options?)

Get a single match by ID, UUID, or slug.

const match = await getFootballMatch("7576255");

// With optional data
const match = await getFootballMatch("7576255", {
    optionalData: ["MAIN_EVENTS", "LINEUP_STATUS", "REFEREES"],
});

Options:

• optionalData - Array of: 'MAIN_EVENTS', 'LINEUP_STATUS', 'REFEREES', 'PENALTY_SHOOTOUT_EVENTS'
• languageCode - Override default language

getFootballMatchEvents(matchId, options?)

Get all events for a match (goals, cards, substitutions).

const events = await getFootballMatchEvents("7576255");
events.forEach((e) => console.log(`${e.minute}' - ${e.type}`));

getFootballMatchLineups(matchId, options?)

Get match lineups with formations and player details.

const lineups = await getFootballMatchLineups("7576255");
console.log(lineups.competitorOne.formation); // "4-3-3"
console.log(lineups.competitorOne.starters); // Player[]

getFootballMatchStatistics(matchId, options?)

Get match statistics (possession, shots, corners, etc.).

const stats = await getFootballMatchStatistics("7576255");
stats.competitorOne.statistics.forEach((s) => {
    console.log(`${s.label}: ${s.value}${s.unit || ""}`);
});

getFootballMatchOdds(matchId, options?)

Get betting odds from various operators.

const odds = await getFootballMatchOdds("7576255", {
    oddType: "PREMATCH",
    marketTypes: ["1X2", "OVER_UNDER"],
});

getFootballMatchCommentary(matchId, options?)

Get live text commentary for a match.

const commentary = await getFootballMatchCommentary("7576255");
commentary.forEach((c) => {
    console.log(`${c.minute}' - ${c.text}`);
});

getFootballTeam(teamId, options?)

Get team details.

const team = await getFootballTeam("1234");
console.log(team.name);
console.log(team.assets?.logo);

React Providers (Client Components)

For React Server Components (RSC) compatibility, client-side exports are available from a separate entry point:

"use client";

import { CompetitionProvider, useCompetition } from "fansunited-data-layer/client";

function MatchList() {
    const { matches, getUpcomingMatches } = useCompetition();
    const upcoming = getUpcomingMatches();

    return (
        <ul>
            {upcoming.map((match) => (
                <li key={match.id}>{match.competitorOne.name} vs {match.competitorTwo.name}</li>
            ))}
        </ul>
    );
}

// Wrap your app with the provider
function App() {
    return (
        <CompetitionProvider
            competitionId="123"
            matches={matches}
            standings={standings}
        >
            <MatchList />
        </CompetitionProvider>
    );
}

Available client exports:

• CompetitionProvider - React context provider for competition data
• useCompetition - Hook to access competition context
• CompetitionContext - Raw context (for advanced use cases)

Note: Server-safe functions (setConfig, getFootballMatch, etc.) should be imported from the main entry point 'fansunited-data-layer', not from '/client'.

Canonical Types

All responses are transformed to provider-agnostic canonical types prefixed with FUSports:

• FUSportsMatch - Full match data
• FUSportsMatchEvent - Goals, cards, substitutions
• FUSportsMatchLineups - Team lineups and formations
• FUSportsMatchStatistics - Match statistics
• FUSportsMatchOdds - Betting odds
• FUSportsCommentaryItem - Commentary entries
• FUSportsCompetitor - Team/competitor data
• FUSportsCompetition - Tournament/league data
• FUSportsPlayer - Player data

TypeScript

Full TypeScript support with exported types:

import type { FUSportsMatch, FUSportsMatchEvent, FUSportsCompetitor } from "fansunited-data-layer";

License

MIT