npm package: @mediaplatform/basketball-sdk
Description: ### Installation
Author: smp@sportal.bg
Latest version: 1.2.10

# JavaScript Basketball SDK

### Installation

Install Basketball SDK dependency

```sh
npm install @mediaplatform/sportal365-basketball-sdk --save
```

or

```sh
yarn add @mediaplatform/sportal365-basketball-sdk
```

### Usage

Import Basketball SDK dependency

```sh
import Core from "@mediaplatform/sportal365-basketball-sdk"
```

Initialize Basketball SDK

```sh
const SDK = new Core(config);
```

The **config** argument is an object with the following properties:

- **dataConfigApiUrl** - API URL (required)
- **dataConfigApiKey** - API KEY (required)
- **dataConfigPlayoffApiUrl** - API url for playoff data (required if you want to use .playoff module)
- **dataConfigLang** - example: 'en'
- **dataConfigProject** - Project name (required)
- **dataConfigOddClient** - default value: 'sportal' (optional)
- **dataConfigTimezone** - example: 'Europe/Sofia' (required)
- **dataConfigCompetitionList** - example: 'default' (required)

## Game Module

Initialize module

```sh
const gameModule = SDK.game(gameId);
```

**gameId** - the argument is required (gameId: string). It defines the required game.

### Usage

```sh
gameModule
  .withDateConfig({ dateFormat: 'string'} )
  .withOdds({ bettingId: 'string', market: 'string', oddFormat: 'string', preEventOddsOnly: 'boolean' })
  .get();
```

Corresponding output should be:

```sh
{
 	 game: GameModel
};
```

Module methods

- **withDateConfig({ dateFormat: string })** - Use this method to format the date by specific dateFormat.

  - dateFormat - Default value "dd.MM".

- **withOdds({ bettingId: string, market: string, oddFormat: string, preEventOddsOnly: boolean })**

  - bettingId - the argument is a string. If no bettingId is provided, the result will be filtered by the first provider from the response
  - market - the argument is a string. Example: "1x2"- will return only "1x2" markets data (if there is one).
  - oddFormat - the argument is a string ( FRACTIONAL, DECIMAL, MONEYLINE ). Default value: "DECIMAL". You could pass an odds format to
    format odds values.
  - preEventOddsOnly - the argument is a boolean which shows odds only when the game has not started yet. The default value of the argument
    is **false**.

- **get()** - the method is mandatory - Based on called methods, it returns the built object with all requested information for the game and
  filtered odds by the given providers id, markets and formated odds values.

## Games Module

Initialize module

```sh
const gamesModule = SDK.games({
	competitionIds: string[];
	seasonIds: string[];
	stageIds: string[];
	sortDirection: string;
	limit: string;
	roundFilter: [ {roundId: string, stageId: string } ];
});
```

### Usage 1

```sh
gamesModule
  .groupGamesByCompetition()
  .withDateConfig({ date: 'string', dateFormat: 'string'} )
  .withStatusFilter(statusType: 'string')
  .withOddsOnly(oddsOnly: 'boolean')
  .withOdds({ bettingId: 'string', market: 'string', oddFormat: 'string', preEventOddsOnly: 'boolean' })
  .get();
```

Corresponding output should be:

```sh
{
  games: [{
	 competition: CompetitionModel,
	 games: [{ game: GameModel  }]
	}]
};
```

Module methods

- **competitionIds(string[])** - (optional) Use this method to filter by competition.

- **seasonIds(string[])** - (optional) Use this method to filter by season.

- **stageIds(string[])** - (optional) Use this method to filter by stage.

- **roundFilter([ {roundId: string, stageId} ])** - (optional) Use this method to filter by roundIds.

- **limit(string)** - (optional) Use this method to limit the number of matches.

- **sortDirection(string)** - (optional) Use this method to set the direction in which the programme matches are sorted - 'asc'/'desc'.

- **groupGamesByCompetitions()** - Use this method to group the games by competitions.

- **withStatusFilter(statusType: string)** - Use this method to get games by specific statusType.

  - statusType -The argument should be a string ( 'LIVE', 'UPCOMING', 'FINISHED', 'INTERRUPTED', 'CANCELLED', 'UNKNOWN', 'DELETED')

- **withDateConfig({ date: string, dateFormat: string })** - Use this method to format the date by specific dateFormat.

  - date -The argument should be a string('yyyy.MM.dd'). Use this method to get games from specific start date.
  - dateFormat - Default value "dd.MM".

- **withOdds({ bettingId: string, market: string, oddFormat: string, preEventOddsOnly: boolean })**

  - bettingId - the argument is a string. If no bettingId is provided, the result will be filtered by the first provider from the response.
  - market - the argument is a string. Example: "1x2"- will return only "1x2" markets data (if there is one).
  - oddFormat - the argument is a string ( FRACTIONAL, DECIMAL, MONEYLINE ). Default value: "DECIMAL". You could pass an odds format to
    format odds values.
  - preEventOddsOnly - the argument is a boolean which shows odds only when the game has not started yet. The default value of the argument
    is **false**.

- **withOddsOnly(oddsOnly:boolean)** - Use this method to filter out matches that don't have odds. The default value of the oddsOnly
  argument is **false**.

### Usage 2

```sh
gamesModule
  .withDateConfig({ date: 'string', dateFormat: 'string'} )
  .withOdds({ bettingId: 'string', market: 'string', oddFormat: 'string', preEventOddsOnly: 'boolean' })
  .get();
```

Corresponding output should be:

```sh
{
  games: [
		{ game: GameModel  }
	]
};
```

- **get()** - the method is mandatory - Based on called methods, it returns the built object with all requested information for the games
  from specific date, grouped by competitions and filtered odds by the given providers id, markets and formated odds values.

## Standing Module

Initialize module

```sh
const standingModule = SDK.standing(competitionId);
```

**competitionId** - the argument is required (competitionId: string).

### Usage 1

```sh
standingModule.get();
```

If the competition has response the output should be:

```sh
{
	seasons: [ SeasonModel ],
	stagesForActiveSeason: [ StageModel ],
	standingsGroupTypes: [StandingsGroupModel],
	standings: [StandingObjectModel]
};
```

### Usage 2

```sh
standingModule
	.getSeason(seasonId)
	.get();
```

Corresponding output should be:

```sh
{
	seasons: [ SeasonModel ],
	stagesForActiveSeason: [ StageModel ],
	standingsGroupTypes: [StandingsGroupModel],
	standings: [StandingObjectModel]
};
```

Module methods:

- **getSeason(seasonId: string)**
  - seasonId - The seasonId argument should be a string. The following example will return available stage and standing data (if there is
    one) for a given season.

### Usage 3

```sh
standingModule
	.getSeason(seasonId)
	.withStageType(type)
	.get();
```

Corresponding output should be:

```sh
{
	seasons: [ SeasonModel ],
	stagesForActiveSeason: [ StageModel ],
	standingsGroupTypes: [StandingsGroupModel],
	standings: [StandingObjectModel]
};
```

Module methods:

- **withStageType(type: string)**
  - type - The type argument should be a string. The following example will return all stages with this type (if there is one).

### Usage 4

```sh
standingModule
	.getStage(stageId)
	.get();
```

Corresponding output should be:

```sh
{
	stagesForActiveSeason: [ StageModel ],
	standingsGroupTypes: [StandingsGroupModel],
	standings: [StandingObjectModel]
};
```

Module methods:

- **getStage(stageId: string)**

  - stageId - The stageId argument should be a string. The following example will return available standing data (if there is one) for a
    given stage. The method cannot be called if the **getSeason()** has been called.

- **get()** - the method is mandatory - Based on called methods, it returns the built object with seasons, stagesForActiveSeason and
  standings.

## Stage Module

Initialize module

```sh
const stageModule = SDK.stage(stageId);
```

**stageId** - the argument is required (stageId: string).

### Usage

```sh
stageModule
	.withRules()
	.get();
```

Corresponding output should be:

```sh
{
	standingsGroupTypes: [StandingsGroupModel],
	standings: [StandingObjectModel]
};
```

Module methods:

- **withRules()** - Use this method to include extracted data of all existing rules in the standings.
- **get()** - the method is mandatory - Based on called methods, it returns the built object with standingsGroupTypes and standings.

## Stage list Module

Initialize module

```sh
const stageListModule = SDK.stageList(competitionId);
```

**competitionId** - the argument is required (competitionId: string).

### Usage 1

```sh
stageListModule.get();
```

If the competition has response the output should be:

```sh
{
	stageList: [ StageModel ],
};
```

### Usage 2

```sh
stageListModule
	.getSeason(seasonId)
	.get();
```

Corresponding output should be:

```sh
{
	stageList: [ StageModel ],
};
```

Module methods:

- **getSeason(seasonId: string)**
  - seasonId - The seasonId argument should be a string. The following example will return available stage data (if there is one) for a
    given season.

### Usage 3

```sh
stageListModule
	.getSeason(seasonId)
	.withStageType(type)
	.get();
```

Corresponding output should be:

```sh
{
	stageList: [ StageModel ],
};
```

Module methods:

- **withStageType(type: string)**
  - type - The type argument should be a string. The following example will return all stages with this type (if there is one).

## Competition module

Initialize module

```sh
const competitionModule = SDK.competition(competitionId);
```

**competitionId** - the argument is required (competitionId: string).

### Usage

```sh
competitionModule
  .withSeasons([seasonIds])
  .get()
```

Corresponding output should be:

```sh
{
  competition: CompetitionModel
  seasons: SeasonModel[],
};
```

Module methods:

- **withSeason(seasonIds: string[])** - The seasonIds argument is optional and should be an array of strings. If no season ids were passed
  or are an empty array, the output should include all seasons. If there are passed seasons ids, the result should include only them.
- The method Output is:

```sh
{ seasons: SeasonModel[] };
```

## Playoff Module

Initialize module

```sh
const playoffModule = SDK.playoff({ stageId: 'string', competition: { id: 'string', status: 'string' } });
```

**stageId** - the argument is optional and it is nested in object property ({ stageId: string }). At least stageId or competition should be
passed.

**competition** - the argument is optional and it is nested in object property as its own object ({ id: string, status: string }). At least
stageId or competition should be passed.

### Usage

```sh
playoffModule
  .playoff({ stageId: 'string', competition: { id: 'string', status: 'string' } })
  .get();
```

Corresponding output should be:

```sh
{
 	 playoff: PlayoffFormattedModel
};
```

Module methods

- **playoff({ stageId: 'string', competition: { id: 'string', status: 'string' } })**

  - stageId - the argument is a string. If no stageId is provided, the request will be sent with competition.
  - competition - the argument is a object with properties 'id' and 'status' ({ id: 'string', status: 'string' }). If stageId is passed, the
    request will be sent with stageId, NOT competition data.

- **get()** - the method is mandatory - Based on called methods, it returns the built object with all requested information for the playoff.

## Tournament programme module

Initialize module

```sh
const tournamentProgrammeModule = SDK.tournamentProgramme({
	competitionId: string,
	seasonId: string,
	stageId: string,
	filterType: string,
	sortDirection: string,
	limit: string,
	roundFilter: [ {roundId: string, stageId: string} ],
});
```

Corresponding output should be:

```sh
{
	programme: [{
		stage: StageModel,
		games: [{ round: RoundModel, games: GameModel[] }] }],
	competition: CompetitionModel,
};
```

Module methods:

- **competitionId(string)** - Use this method to filter by competition.

- **seasonId(string)** - Use this method to filter by season.

- **stageId(string)** - Use this method to filter by stage.

- **roundFilter([ {roundId: string, stageId} ])** - Use this method to filter by roundIds.

- **limit(string)** - Use this method to limit the number of matches.

- **fiilterType(string)** - Use this metod to filter upcoming games or games that were already played or postponed - 'fixtures'/'results'.

- **sortDirection(string)** - Use this method to set the direction in which the programme matches are sorted - 'asc'/'desc'.

- **withOdds(options: { bettingId: string, preEventOddsOnly: boolean; oddFormat: string; })** - the argument is an object where:

  - bettingId property should be astring to filter odds result. Example: "43" - will return available odds data (if there is one) only for
    odds with the given provider.
  - market - the argument is a string. Example: "1x2"- will return only "1x2" markets data (if there is one).
  - preEventOddsOnly is a property which shows odds only when the match has not started yet. The default value of the argument is **false**.
  - oddFormat is a property which sets the type of the odds. The type argument is a string with one of the following string values:
    'FRACTIONAL'/'MONEYLINE'/'DECIMAL'. The default value is set to 'DECIMAL'.

- **get()** - the method is mandatory - Based on called methods, it returns the built object with programme information for specific
  competition.

## Team programme module

Initialize module

```sh
const teamProgrammeModule = SDK.teamProgramme({
	teamId: string,
	seasonId: string,
	stageId: string,
	teamType: string,
	filterType: string,
	sortDirection: string,
	limit: string,
	roundFilter: [ {roundId: string, stageId: string} ],
});
```

Corresponding output should be:

```sh
{
	programme: [{
		competition: CompetitionModel,
		games: [{ round: RoundModel, games: GameModel[] }] }],
	team: TeamModel,
};
```

Module methods:

- **teamId(string)** - Use this method to filter by team.

- **seasonId(string)** - Use this method to filter by season.

- **stageId(string)** - Use this method to filter by stage.

- **teamType(string)** - Use this metod to filter by team type- 'home'/'away'.

- **roundFilter([ {roundId: string, stageId} ])** - Use this method to filter by roundIds.

- **limit(string)** - Use this method to limit the number of matches.

- **fiilterType(string)** - Use this metod to filter upcoming games or games that were already played or postponed - 'fixtures'/'results'.

- **sortDirection(string)** - Use this method to set the direction in which the programme matches are sorted - 'asc'/'desc'.

- **withOdds(options: { bettingId: string, preEventOddsOnly: boolean; oddFormat: string; })** - the argument is an object where:

  - bettingId property should be astring to filter odds result. Example: "43" - will return available odds data (if there is one) only for
    odds with the given provider.
  - market - the argument is a string. Example: "1x2"- will return only "1x2" markets data (if there is one).
  - preEventOddsOnly is a property which shows odds only when the match has not started yet. The default value of the argument is **false**.
  - oddFormat is a property which sets the type of the odds. The type argument is a string with one of the following string values:
    'FRACTIONAL'/'MONEYLINE'/'DECIMAL'. The default value is set to 'DECIMAL'.

- **get()** - the method is mandatory - Based on called methods, it returns the built object with programme information for specific team.

## Seasons module

Initialize module

```sh
const seasonsModule = SDK.seasons({ competitionId: string, teamId: string, limit: string, offset: string });
```

**competitionId** - the argument is optional (competitionId: string) **teamId** - the argument is optional (teamId: string). **limit** - the
argument is optional (limit: string). **offset** - the argument is optional (offset: string).

Corresponding output should be:

```sh
{
  seasons: SeasonModel[],
};
```

- **get()** - the method is mandatory - Based on called methods, it returns the built object with seasons.

## Modules Errors

If some of the modules' requests were not successful, the corresponding module should return an error message.

Example:

```sh
{
   gamesError: "Request failed with status code 500",
   gameError: "Request failed with status code 500",
   standingsError: "Request failed with status code 500",
   ...
}
```

## Module with no data

If the API response has no data, the module should not return anything.