Skip to main content

Achievement SDK

The Achievement SDK provides methods to manage achievements for your applications on the GetJar platform.

Initialization​

import { Configuration, Achievement } from '@eightpointio/getjar-iap-sdk';

const config = new Configuration({
  basePath: 'url',
  headers: { 'x-api-key': 'key' }
});

const achievementClient = new Achievement(config);

Methods​

getAchievementById​

Retrieves a specific achievement by its ID.

Parameters:

  • appId (string): Application ID
  • achievementId (string): Achievement ID

Returns: Promise<IAchievement>

const achievement = await achievementClient.getAchievementById('app-123', 'achievement-789');

getAppAchievements​

Retrieves all achievements for a specific application with optional filtering and pagination.

Parameters:

  • appId (string): Application ID
  • props (IQueryAchievementsRequest, optional): Query parameters
    • limit (number): Items per page
    • page (number): Page number
    • isActive (boolean): Filter by active status
    • type (AchievementType): Filter by achievement type
    • rarity (AchievementRarity): Filter by rarity
    • search (string): Search term
    • sortOrder (SortOrderEnum): Sort order (ASC/DESC)
    • startDate (string): Filter from date
    • endDate (string): Filter to date

Returns: Promise<PaginatedResponse<IAchievement>>

const achievements = await achievementClient.getAppAchievements('app-123', {
  limit: 20,
  page: 1,
  isActive: true,
  type: AchievementType.STANDARD,
  rarity: AchievementRarity.RARE
});

unlockAchievement​

Unlocks an achievement for a user, awarding XP and currency rewards.

Parameters:

  • appId (string): Application ID
  • achievementId (string): Achievement ID to unlock
  • userId (string): User ID to unlock the achievement for
  • metadata (Record<string, any>, optional): Metadata to attach to the unlock

Returns: Promise<IAchievementUnlockResponse>

const result = await achievementClient.unlockAchievement(
  'app-123',
  'achievement-789',
  'user-456',
  { source: 'quest_completion', questId: 'quest-1' }
);

console.log(result.unlocked);
console.log(result.xpAwarded);
console.log(result.currencyAwarded);
console.log(result.message);

getUserUnlocks​

Gets all achievement unlocks for a user in a specific app.

Parameters:

  • userId (string): User ID
  • appId (string): Application ID
  • pagination (IPagination, optional): Pagination parameters
    • page (number): Page number
    • limit (number): Items per page

Returns: Promise<PaginatedResponse<IUserAchievementLedger>>

const unlocks = await achievementClient.getUserUnlocks('user-456', 'app-123', {
  page: 1,
  limit: 20
});

unlocks.items.forEach(unlock => {
  console.log(`Unlocked: ${unlock.achievement.name}`);
  console.log(`Unlocked at: ${unlock.unlockedAt}`);
  console.log(`XP awarded: ${unlock.xpAwarded}`);
});

getAchievementUnlockHistory​

Gets the unlock history for a specific achievement showing all users who have unlocked it.

Parameters:

  • appId (string): Application ID
  • achievementId (string): Achievement ID
  • pagination (IPagination, optional): Pagination parameters

Returns: Promise<PaginatedResponse<IAchievementUnlockHistoryItem>>

const history = await achievementClient.getAchievementUnlockHistory(
  'app-123',
  'achievement-789',
  { page: 1, limit: 50 }
);

history.items.forEach(item => {
  console.log(`User: ${item.userId}`);
  console.log(`Unlocked: ${item.unlockedAt}`);
});

hasUnlocked​

Checks if a user has unlocked a specific achievement.

Parameters:

  • userId (string): User ID to check
  • achievementId (string): Achievement ID to check

Returns: Promise<boolean>

const unlocked = await achievementClient.hasUnlocked('user-456', 'achievement-789');

if (unlocked) {
  console.log('User has already unlocked this achievement');
} else {
  console.log('Achievement is still locked');
}

Types​

AchievementType​

enum AchievementType {
  STANDARD = 'STANDARD',
  PROGRESSIVE = 'PROGRESSIVE',
  SECRET = 'SECRET',
  MILESTONE = 'MILESTONE',
  DAILY = 'DAILY',
  WEEKLY = 'WEEKLY',
  SEASONAL = 'SEASONAL'
}

AchievementRarity​

enum AchievementRarity {
  COMMON = 'COMMON',
  UNCOMMON = 'UNCOMMON',
  RARE = 'RARE',
  EPIC = 'EPIC',
  LEGENDARY = 'LEGENDARY'
}

IAchievement​

interface IAchievement {
  achievementId: string;
  appId: string;
  developerId: string;
  name: string;
  description: string;
  detailedDescription?: string;
  category?: string;
  tags?: string[];
  type: AchievementType;
  rarity: AchievementRarity;
  points: number;
  stats?: IAchievementStats;
  xpReward?: number;
  currencyReward?: number;
  isActive: boolean;
  metadata?: Record<string, any>;
  createdAt: Date;
  updatedAt: Date;
}

IAchievementUnlockResponse​

interface IAchievementUnlockResponse {
  unlocked: boolean;
  alreadyUnlocked: boolean;
  xpAwarded: number;
  currencyAwarded: number;
  message: string;
  achievement: IAchievement;
}

IUserAchievementLedger​

interface IUserAchievementLedger {
  ledgerId: string;
  userId: string;
  achievementId: string;
  achievement: IAchievement;
  unlockedAt: Date;
  xpAwarded: number;
  currencyAwarded: number;
  metadata?: Record<string, any>;
  createdAt: Date;
}

IAchievementUnlockHistoryItem​

interface IAchievementUnlockHistoryItem {
  userId: string;
  achievementId: string;
  unlockedAt: Date;
  xpAwarded: number;
  currencyAwarded: number;
  metadata?: Record<string, any>;
}

IPagination​

interface IPagination {
  page?: number;
  limit?: number;
}

PaginatedResponse​

interface PaginatedResponse<T> {
  items: T[];
  pagination: {
    total: number;
    page: number;
    limit: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
  };
}