npm package: @mediaplatform/sportal365-tennis-sdk
Description: ### Installation
Author: smp@sportal.bg
Latest version: 1.2.13

# JavaScript Tennis SDK

### Installation

Install Tennis SDK dependency

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

or

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

### Usage

Import Tennis SDK dependency

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

Initialize Tennis 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)
- **dataConfigStandingsApiUrl** - API url for ranking data (required if you want to use .ranking module)
- **dataConfigLang** - example: 'en'
- **dataConfigProject** - Project name (required)
- **dataConfigOddClient** - default value: 'sportal' (optional)
- **dataConfigTimezone** - example: 'Europe/Sofia' (required)
- **dataConfigCompetitionList** - example: 'default' (required)

## Match Module

Initialize module

```sh
const matchModule = SDK.match(matchId);
```

**matchId** - the argument is required (matchId: string). It defines the required match.

### Usage

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

Corresponding output should be:

```sh
{
 	 match: MatchModel
};
```

Module methods

- **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 match 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 match
  and filtered odds by the given providers id, markets and formated odds values.

## Matches Module

Initialize module

```sh
const matchesModule = SDK.matches({
	competitionIds: string[];
	seasonIds: string[];
	tournamentIds: string[];
	sortDirection: string;
	limit: string;
	roundFilter: [ {roundId: string, tournamentId: string } ];
});
```

### Usage 1

```sh
matchesModule
  .groupMatchesByTournament()
  .withDateConfig({ date: 'string'} )
  .withStatusFilter({ statusType: 'string', competitionList: 'string' })
  .withType(type: 'string')
  .withGender(gender: 'string')
  .withOdds({ bettingId: 'string', market: 'string', oddFormat: 'string', showWithOddsOnly: boolean, preEventOddsOnly: 'boolean' })
  .get();
```

Corresponding output should be:

```sh
{
  matches: [{
	 tournament: TournamentModel,
	 matches: [{ match: MatchModel  }]
	}]
};
```

Module methods

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

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

- **tournamentIds(string[])** - (optional) Use this method to filter by tournaments.

- **roundFilter([ {roundId: string, tournamentId: string} ])** - (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'.

- **groupMatchesByTournament()** - Use this method to group the matches by tournament.

- **withStatusFilter({statusType: string, competitionList?: string})** - Use this method to get matches by specific statusType.

  - statusType - The argument should be a string ( 'LIVE', 'UPCOMING', 'FINISHED', 'INTERRUPTED', 'CANCELLED', 'POSTPONED', 'POPULAR' )
  - competitionList - The argument is an optional string that should be used in conjunction with the statusType argument when statusType is
    set to 'POPULAR'. Note that it overrides the dataConfigCompetitionList supplied to the SDK's Core.

- **withType(type: string)** - Use this method to get matches by specific type.

  - type -The argument should be a string ( 'SINGLE', 'DOUBLE', 'TEAM' )

- **withGender(gender: string)** - Use this method to get matches by specific gender.

  - gender -The argument should be a string ( 'MALE', 'FEMALE', 'MIXED' )

- **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 matches from specific start date.
  - dateFormat - Default value "dd.MM".

- **withOdds({ bettingId: string, market: string, oddFormat: string, showWithOddsOnly: boolean, 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.
  - showWithOddsOnly - the argument is a boolean ( true / false ). You could pass a showWithOddsOnly to filter matches with odds values.
  - preEventOddsOnly - the argument is a boolean which shows odds only when the match has not started yet. The default value of the argument
    is **false**.

### Usage 2

```sh
matchesModule
  .withDateConfig({ date: 'string', dateFormat: 'string'} )
  .withStatusFilter({ statusType: 'string', competitionList: 'string' })
  .withType(type: 'string')
  .withGender(gender: 'string')
  .withOdds({ bettingId: 'string', market: 'string', oddFormat: 'string', preEventOddsOnly: 'boolean' })
  .get();
```

Corresponding output should be:

```sh
{
  matches: [
		{ match: MatchModel  }
	]
};
```

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

## 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.

## Ranking Module

Initialize module

```sh
const rankingModule = SDK.ranking({rankingId: string, offset: string, limit: string});
```

### Usage 1

```sh
SDK.ranking({ rankingId: 'string', offset: 'string', limit: 'string' })
	.getAvailableRankings({ scope: 'string', standingTypeSubcategory: string })
	.get();
```

Corresponding output should be:

```sh
{
	ranking: RankingModel,
	availableRankings: [ AvailableRankingsModel ]
};
```

**rankingId** - The argument is a string and it is required to get a single ranking by the unique id. The request will not be sent if no
rankingId is provided. The request return a single ranking by the unique id.

**offset **and** limit** - the arguments are optional. The default values wiil be applied (**offset: 0, limit: 100**) if no offset and limit
are provided. They could be used to implement pagination.

### Usage 2

```sh
SDK.ranking()
	.getAvailableRankings({ scope: 'string', standingTypeSubcategory: 'string' })
	.get();
```

Corresponding output should be:

```sh
{
	availableRankings: [ AvailableRankingsModel ]
};
```

**standingTypeSubcategory** - The argument is optional ('ATP_SINGLES_RANKING'/ 'WTA_SINGLES_RANKING' and etc. ). The request returns a
standing for a given subcategory.

**scope** - the argument is a string and it is optional (**CURRENT** or **CONTINUOUS**). If no scope is provided the default value will be
applied (scope: CURRENT).

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

## Competition Module

### Usage 1

```sh
SDK.competition({ competitionId: string}).get();
```

Corresponding output should be:

```sh
{
	competition: CompetitionDetailsModel
};
```

**competitionId** - The argument is a string and it is required to get a single competition details by the unique id and default season:
"**CURRENT**". The request will not be sent if no competitionId is provided.

### Usage 2

```sh
SDK.competition({ competitionId: "string", season: "string" }).get();
```

Corresponding output should be:

```sh
{
	competition: CompetitionDetailsModel
};
```

**seasonId** - The argument is a string and it is optional to get a single competition details by given season.

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

  ## Tournament programme module

Initialize module

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

Corresponding output should be:

```sh
{
	programme: [{
		tournament: TournamentModel,
		matches: [{ round: RoundModel, games: MatchModel[] }] }],
	competition: CompetitionModel,
};
```

Module methods:

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

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

- **tournamentId(string)** - Use this method to filter by tournament.

- **roundFilter([ {roundId: string, tournamentId: string} ])** - Use this method to filter by roundIds. Cannot be applied with tournamentId
  property.

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

- **fiilterType(string)** - Use this metod to filter upcoming matches or matches 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'.

Module methods

- **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 match 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 programme information for specific
  competition.

## Athlete programme module

Initialize module

```sh
const athleteProgrammeModule = SDK.athleteProgramme({
	playerId: string,
	seasonYear: string,
	competitionId: string,
	tournamentId: string,
	filterType: string,
	sortDirection: string,
	limit: string,
	roundFilter: [ {roundId: string, tournamentId: string} ],
});
```

Corresponding output should be:

```sh
{
	programme: [{
		competition: CompetitionModel,
		matches: [{ round: RoundModel, matches: MatchModel[] }] }],
	athlete: AthleteModel,
};
```

Module methods:

- **playerId(string)** - Use this method to filter by player.

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

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

- **tournamentId(string)** - Use this method to filter by tournament.

- **roundFilter([ {roundId: string, tournamentId: string} ])** - Use this method to filter by roundIds. It cannot be applied if tournamentId
  is provided.

- **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 athlete programme information for specific
  player.

## Modules Errors

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

Example:

```sh
{
   matchError: "Request failed with status code 500",
   rankingError: If the ranking method is invoked with an empty object 'Ranking module initialization failed. You must provide a valid "rankingId".' error will be returned.
   ...
}
```

## Module with no data

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