Web Integration Guide

Web Integration Guide | Sport SDK | API Hub

This guide covers the JavaScript / TypeScript API exposed by the generated sport-sdk package.

The most important integration details for Web are:

initialize the SDK before fetching data
use CommonResult<T> (data, errorMessage, isSuccess)
convert Kotlin KtList values to JS arrays when needed
use bigint for most domain identifiers (sportId, seasonId, matchId, ...)

Reference implementation:

jsApp/
generated package typings in build/js/packages/sport-sdk/kotlin/sport-sdk.d.mts

Quick start

Install sport-sdk, call SportSdkJs.init(...) once with clientId, appKey, and appIdentifier, then verify the setup with SportSdkJs.getSports().

#Start here

Install

Use your team’s npm distribution channel or a locally packed .tgz during repository development.

Initialize

Call SportSdkJs.init(...) before any data request and wait for the promise to resolve.

Normalize

Convert KtList<T> values with asJsReadonlyArrayView() at your app boundary.

Keep IDs precise

Most domain identifiers are bigint, not number.

#Prerequisites

Web requirements

a modern ESM-capable toolchain
browser/runtime support for

#Installation

If your team consumes a published package, install sport-sdk from your configured npm registry.

bash

npm install sport-sdk

note

If the package is hosted in a private GitLab/npm registry, configure your .npmrc according to your organization’s release instructions before running .

#Quick start

#Understanding the Web API shape

`CommonResult<T>`

Every SDK call returns a result wrapper. Always inspect:

result.isSuccess
result.data
result.errorMessage

`KtList<T>`

SDK lists are Kotlin collections, not plain JS arrays. Convert them with asJsReadonlyArrayView().

`bigint`

Most domain IDs are bigint. Keep them that way unless you are certain downcasting is safe.

#`KtList<T>` conversion examples

const sports = result.data?.asJsReadonlyArrayView() ?? [];
const categories = sport.categories.asJsReadonlyArrayView();
const tournaments = category.tournaments.asJsReadonlyArrayView();
const matches = tournament.matches.asJsReadonlyArrayView();

#`bigint` examples

const sportId = 1n;
const seasonId = 123456789n;
const matchId = 987654321n;

warning

If you serialize these IDs, remember that JSON.stringify() does not support bigint directly without conversion.

#Available methods

Top-level function exports also exist, for example:

topLvlGetSportsList()
topLvlGetSportMatchesForDate(timestamp)
topLvlGetTournamentSeasons(uniqueTournamentId)

#Sports feed example

import { SportSdkJs } from 'sport-sdk';

export async function loadSports(): Promise<void> {
  const result = await SportSdkJs.getSports();

  if (!result.isSuccess) {
    console.error('Error loading sports:', result.

#Seasons, standings, fixtures, and squad

#Match details

const statisticsResult = await SportSdkJs.getMatchStatistics(matchId);
const lineupsResult = await SportSdkJs.getMatchLineups(matchId);
const timelineResult = await SportSdkJs.getSoccerMatchTimelineEvents(matchId);

const statistics = statisticsResult.data?.asJsReadonlyArrayView() ?? [];
const lineups =

#Framework examples

#Angular service example

import { Injectable } from '@angular/core';
import { BehaviorSubject } from 'rxjs';
import { ClientConfig, SportSdkJs, Sport } from 'sport-sdk';

@Injectable({

#Environment configuration

#Keep credentials in one config object

export const environment = {
  production: false,
  sportSdk: {
    clientId: YOUR_CLIENT_ID,
    appKey: 'YOUR_APP_KEY',
    appIdentifier: 'com.example.webapp',
  },
};

#Best practices

Initialize before rendering data screens

Whether you use Angular, React, Vue, or vanilla JS, wait for SportSdkJs.init(...) before making controller calls.

Normalize `KtList` at your app boundary

Convert SDK collections to plain arrays once, then pass arrays through your UI state/store.

Keep `bigint` IDs as `bigint`

Do not downcast IDs to number unless you are certain precision is safe.

Use milliseconds for date queries

getSportMatchesForDate(timestamp) expects milliseconds since epoch.

#Troubleshooting

#TypeScript says a list is not iterable

You are probably working with KtList<T>. Convert it first:

const items = result.data?.asJsReadonlyArrayView() ?? [];

#TypeScript rejects `number` IDs

Use bigint literals for domain IDs:

const matchId = 123456789n;

#SDK initializes but no data appears

Check:

result.errorMessage
package credentials / registry access
timestamp units (milliseconds)
that initialization completed before the request fired

#Browser/build issues with `BigInt`

Make sure your target runtime and bundler output support ES2020+ BigInt.

#Package not found