API Reference

This reference covers all methods available on the FunticoSDK class. All methods should be called on an initialized SDK instance.

SDK Initialization

Before using any of the methods below, initialize the SDK:

import { FunticoSDK } from '@funtico/gameloop-sdk';

const sdk = new FunticoSDK({
  authClientId: 'your-auth-client-id',
  env: 'sandbox' // or 'production'
});

Methods

All methods below are called on the initialized sdk instance.

sdk.signInWithFuntico()

Initiates the OAuth authentication flow with Funtico. This method redirects the user to Funtico’s authentication page where they can log in or create an account. After successful authentication, users are redirected back to your specified callback URL.

sdk.signInWithFuntico(callbackUrl: string): Promise<void>

Parameters:

• callbackUrl (string): The URL where users will be redirected after successful authentication

Returns:

• Promise<void>: Resolves when the authentication flow is initiated (redirects to auth provider)

Throws:

• SDKError: When authentication setup fails

Example:

// Redirect to authentication flow
await sdk.signInWithFuntico(
  window.location.href
);

---

sdk.getUserInfo()

Retrieves the authenticated user’s information. This method returns the current user’s profile data including their ID, username, and profile picture. The user must be authenticated before calling this method.

sdk.getUserInfo(): Promise<GetUserInfoResponse>

Parameters: None

Returns:

• Promise<GetUserInfoResponse>: User information object

Response Type:

interface GetUserInfoResponse {
  user_id: number;
  picture: string | null;
  username: string;
}

Throws:

• SDKError: When user is not authenticated or request fails

Example:

// Get current user's profile information
const userInfo = await sdk.getUserInfo();
console.log(`Welcome ${userInfo.username}!`);

---

sdk.saveScore()

Saves a player’s score to the current game session. This method submits the player’s score to Funtico’s leaderboard system. The score will be used for ranking and rewards distribution.

sdk.saveScore(score: number): Promise<void>

Parameters:

• score (number): The numerical score to save

Returns:

• Promise<void>: Resolves when the score is successfully saved

Throws:

• SDKError: When score is invalid, user is not authenticated, or save fails

Example:

// Submit player's final score
const finalScore = 1500;
await sdk.saveScore(finalScore);

---

sdk.getLeaderboard()

Retrieves the current game leaderboard with top players’ scores, rankings, and profile information. This method returns an array of leaderboard entries sorted by rank.

sdk.getLeaderboard(): Promise<GetLeaderboardResponse>

Parameters: None

Returns:

• Promise<GetLeaderboardResponse>: Array of leaderboard entries

Response Type:

type GetLeaderboardResponse = {
  place: number;
  score: number;
  points: number;
  user: {
    username: string;
    profile_picture_url: string;
    border_url: string | null;
    is_kyc_verified: boolean;
  };
}[];

Throws:

• SDKError: When user is not authenticated or request fails

Example:

// Get top players and their scores
const leaderboard = await sdk.getLeaderboard();
leaderboard.forEach((entry, index) => {
  console.log(`${entry.place}. ${entry.user.username}: ${entry.score} points`);
});

---

sdk.signOut()

Signs out the current user and redirects to a specified URL. This method clears the user’s authentication tokens and session data, then redirects them to your specified post-logout URL.

sdk.signOut(postSignOutRedirectUrl: string): Promise<void>

Parameters:

• postSignOutRedirectUrl (string): The URL to redirect to after sign out

Returns:

• Promise<void>: Resolves when sign out is initiated (redirects user)

Throws:

• SDKError: When sign out process fails

Example:

// Sign out and redirect to login page
await sdk.signOut('/login');

Helper Functions

isSDKError

Type guard function to check whether an unknown value is an SDKError.

isSDKError(error: unknown): error is SDKError

Parameters:

• error (unknown): The value to check

Returns:

• boolean: true if the error is an instance of SDKError

Example:

import { isSDKError } from '@funtico/gameloop-sdk';

try {
  await sdk.getUserInfo();
} catch (error) {
  if (isSDKError(error)) {
    console.log(`SDK Error: ${error.name} (${error.status})`);
  }
}