TypeScript SDK

npm install github:Kraty-Org/kraty-sdk-typescript#v0.29.1
# or with pnpm:
pnpm add github:Kraty-Org/kraty-sdk-typescript#v0.29.1

import { Kraty } from '@kraty/sdk';

const kraty = new Kraty({ apiKey: '<your-client-sdk-key>' });

// Every call below auto-resolves the player identity. The SDK
// generates one, persists it, and reuses it across launches.
const events = await kraty.events.listForPlayer();
await kraty.events.start(events[0].eventKey);

const kraty = new Kraty({
  apiKey: '<your-client-sdk-key>',
  activeExternalPlayerId: 'player_42',
});

// First call registers `player_42` and persists the secret.
// All subsequent boots restore the same identity transparently.
await kraty.events.listForPlayer();

import { Kraty, LocalStorageSecretStore } from '@kraty/sdk';

const secretStore = new LocalStorageSecretStore();

const kraty = await Kraty.connectAsPlayer({
  options: { apiKey: '<your-client-sdk-key>' },
  externalPlayerId: 'player_42',
  secretStore,
});

// Ready to use: the secret is already attached to every request.
await kraty.events.listForPlayer();

const stored = await Kraty.readStoredIdentity(secretStore);
if (stored) {
  // Returning player: resume immediately.
  const kraty = new Kraty({
    apiKey: '<your-client-sdk-key>',
    playerSecret: stored.secret,
    activeExternalPlayerId: stored.externalPlayerId,
  });
  startGame(stored.externalPlayerId, kraty);
} else {
  // Fresh install / post-logout: show "tap to play".
  showOnboarding();
}

const secret = await myBackend.linkDevice(playerId);
await kraty.signIn({ externalPlayerId: playerId, secret });

await kraty.logout();
// Next player-scoped call lazily registers a fresh player.

// Or sign in as someone else immediately:
await kraty.signIn({
  externalPlayerId: 'player_99',
  secret: '<from your auth backend>',
});

// Returns null until the first player-scoped call resolves
// (or you await ensureIdentity directly).
const id = kraty.activeExternalPlayerId;

// Force a resolve up-front (rare, usually unnecessary).
const { externalPlayerId } = await kraty.ensureIdentity();

import { Kraty } from '@kraty/sdk';

const kraty = new Kraty({
  apiKey: process.env.KRATY_API_KEY!,
  timeoutMs: 10_000,
  retry: {
    attempts: 5,
    initialDelayMs: 200,
    maxDelayMs: 10_000,
    jitter: 0.25,
  },
  onRequest: (info) => {           // optional telemetry
    console.log(`${info.method} ${info.url} → ${info.status}`);
  },
});

import { Platform } from 'react-native';

const kraty = new Kraty({
  apiKey: '...',
  platform: Platform.OS,          // 'ios' | 'android'; or a key from Settings → Platforms
  appVersion: '1.4.2',            // your build version
});

kraty.events            // event list / start / progress
kraty.leaderboards      // cross-event boards by key: read / listPeriods
kraty.eventLeaderboards // per-event attempt board by UUID: read + live/subscribe SSE
kraty.grants            // pending / claim / open / collectAll
kraty.lobbies           // read (with botSlots projection)
kraty.inventory         // list / consume
kraty.wallet            // list / debit
kraty.players           // register / rotate / setIdentity / getIdentity / getAnonymizedIdentity / setMetadata / mergeMetadata
kraty.friends           // friend codes / search / suggestions / requests / presence / blocks
kraty.catalog           // items + currencies for display
kraty.dailyLogin        // read: the daily login calendar (see Daily login)
kraty.guilds            // guilds: found / join / roles / help requests (see Guilds)

const kraty = new Kraty({ apiKey: '<your-client-sdk-key>' });

// All of these target the active player implicitly:
await kraty.events.listForPlayer();
await kraty.grants.listPending();
await kraty.inventory.list();
await kraty.wallet.list();

await kraty.grants.listPending({ as: 'other_player' });

const kraty = await Kraty.connectAsPlayer({ options, externalPlayerId, secretStore });
const real = await kraty.players.getIdentity();               // display name if set, else pool
const anon = await kraty.players.getAnonymizedIdentity();     // always the immutable pool value
greet(real?.name ?? 'Player');
publicScoreboard(anon?.name, anon?.country);                  // render a flag next to the alias

const reg = await kraty.players.register('player_42');
reg.displayIdentity?.name;        // real name (or the pool value, if never renamed)
reg.anonymizedIdentity?.name;     // e.g. "Crazy Panda" — always the pool value
reg.anonymizedIdentity?.country;  // ISO-3166 alpha-2, for a flag icon

await kraty.players.setIdentity({ name: 'CaptainAlice', avatar: 'https://…/alice.png' });

// Replace: player's metadata becomes exactly { vip: true, tier: 'gold' }.
await kraty.players.setMetadata({ vip: true, tier: 'gold' });

// Merge: only the `preferredLanguage` key is touched.
await kraty.players.mergeMetadata({ preferredLanguage: 'pt' });

// 0) Connect. The first player-scoped call auto-registers + persists
//    the active player.
const kraty = new Kraty({ apiKey: '<your-client-sdk-key>' });

// Show a result screen exactly once when a board the player is on ends:
// live over SSE while subscribed, and on catch-up after a cold start.
kraty.onFinalized((result) => {
  const placed = result.self ? `#${result.self.rank}` : '—';
  showResultScreen(result.ref.leaderboardId, result.reason, placed);
  void kraty.dismiss(result.ref);
});

// 1) What can the active player play right now?
const available = await kraty.events.listForPlayer();

for (const e of available) {
  console.log(`${e.eventKey} (${e.type})`);
  if (e.entryCost?.currencies?.length) {
    for (const c of e.entryCost.currencies) {
      console.log(`  cost: ${c.amount} ${c.key}`);
    }
  }
}

// 2) Start an attempt. Pays entryCost atomically; throws on
//    insufficient_entry_cost if the player cannot afford it.
const start = await kraty.events.start(
  available[0].eventKey,
  { country: 'PT', level: 7 },
);

// 3) Subscribe to the attempt's live board. `subscribe(...)` is the
//    high-level helper; it composes the SSE stream with a background
//    poll so bots tick and deltas are deduped for you. (The raw
//    `live(...)` primitive is available if you want to drive the poll
//    yourself.)
const sub = kraty.eventLeaderboards.subscribe(start.leaderboardId, (ev) => {
  if (ev.kind === 'score_update') repaint(ev.data);
});

// 4) Push progress. `set` writes; `increment` adds. The board repaints
//    via the subscription above.
const update = await kraty.events.progress(
  available[0].eventKey,
  start.attempt.id,
  { mode: 'increment', metricValue: 1 },
);
for (const fired of update.milestonesFired) {
  showToast(`Milestone ${fired.key} → ${fired.grants.length} grants`);
}

// 5) Attempt completed? Tear down the stream and collect rewards.
if (update.attempt.status === 'completed') {
  await sub.close();
  await kraty.grants.collectAll();
}

async function onEndRun() {
  const { attempt, outcome } = await kraty.events.finish(
    'score_attack',
    activeAttemptId,
  );
  await sub.close(); // tear down the live board
  if (outcome === 'completed') {
    // No target (or target already met) → completion rewards rolled.
    await kraty.grants.collectAll();
  }
  // 'expired' → event had a target the player did not meet;
  // participation rewards only, same as a timeout.
  showResultScreen(attempt);
}

const res = await kraty.events.progress('team_chest', attemptId, {
  mode: 'increment',
  metricValue: 3,
});
const [team] = res.teams ?? [];
if (team) {
  renderGoalBar(team.score, team.goal?.target);
  for (const m of team.milestones) if (m.unlocked && m.paid) showChestOpened(m.key);
}

// Roster view: teammates in rank order, `isSelf` on your row.
const page = await kraty.events.teamMembers(team.eventTeamId);

const [team] = res.teams ?? [];
if (team?.leaderboardId) {
  const board = await kraty.eventLeaderboards.read(team.leaderboardId, {
    includeSelf: true,
    externalId: playerId,
  });
  // board.participantScope === 'team'; board.self is your TEAM's rank.
  for (const e of board.entries) {
    // Team rows are `kind: 'player'` with a `team` object; rival bot teams
    // are `kind: 'bot'` with `team: null`.
    renderRow(e.rank, e.name, e.score, e.team?.badge, e.team?.memberCount, e.isSelf);
  }
}

const { eventTeamId, teams } = await kraty.events.matchTeam('team_race');

// Invite by external id or friend code; a pending invite holds a slot on both sides.
const invite = await kraty.events.invitePartner('train_journey', { friendCode: 'K7P2QX' });

// The other player sees it and answers.
const [incoming] = await kraty.events.partnerInvites('train_journey', { direction: 'in' });
const accepted = await kraty.events.acceptInvite('train_journey', incoming.eventTeamId);
// …or kraty.events.declineInvite(…); the inviter can kraty.events.cancelInvite(…).

// No friend around: pair with someone waiting, or wait for a partner.
const random = await kraty.events.randomPartner('train_journey'); // status: 'paired' | 'waiting'

// Who to invite: friends first, then recently active players with a free slot.
const suggestions = await kraty.events.partnerSuggestions('train_journey', { limit: 10 });

// Play for one bar.
await kraty.events.progress('train_journey', attemptId, {
  mode: 'increment',
  metricValue: 1,
  eventTeamId: accepted.eventTeamId,
});

// Every non-archived board configured for this game, so the UI can
// discover keys instead of hard-coding them.
const boards = await kraty.leaderboards.list();
for (const b of boards) {
  // b.key, b.name, b.resetCadence, b.nextResetAt (ISO, null = never resets),
  // b.acceptClientScores (false = only your server may submit),
  // b.contextSegments (playerContext fields to pass as `segment`)
}

// Top 50 of an unsegmented all-time board. `includeSelf` resolves
// to the active player by default, so there's no need to repeat the id.
const allTime = await kraty.leaderboards.read('all_time_global', {
  limit: 50,
  includeSelf: true,
});

for (const e of allTime.entries) {
  console.log(`#${e.rank} ${e.name} ${e.score} (${e.kind})`); // kind: player | bot
}
if (allTime.self) {
  console.log(`You: #${allTime.self.rank} score ${allTime.self.score}`);
}

const leagueBoard = await kraty.leaderboards.read('season_league', {
  segment: 'diamond',
  limit: 20,
  includeSelf: true,
});

const { periods } = await kraty.leaderboards.listPeriods('weekly_global');
const lastWeek = periods[0]; // newest snapshot
const snap = await kraty.leaderboards.read('weekly_global', {
  period: lastWeek.periodStartedAt,
  limit: 10,
});

const eventLeaderboard = await kraty.eventLeaderboards.read(start.leaderboardId, {
  limit: 50,
  includeSelf: true,
});

// Unsegmented / progression-segmented board: no segment.
const result = await kraty.leaderboards.submitScore('daily_steps', 8421);
console.log(result.leaderboardId, result.score, result.rank);

// context-segmented board: pass the bucket the client owns.
await kraty.leaderboards.submitScore('weekly_region', 8421, {
  segment: 'EU',
  idempotencyKey: 'steps_2026_06_29', // optional; dedupes retries
});

// Appear on the board at 0 without scoring; returns current standings.
const board = await kraty.leaderboards.join('weekly_region', { segment: 'EU' });
const evBoard = await kraty.eventLeaderboards.join(start.leaderboardId);

const mine = await kraty.leaderboards.standings('season_league', {
  scope: 'self_segment',            // or 'mine' | 'all' | 'segment'
  externalId: 'player_alice',
});
mine.segments[0].selfRank;          // caller's rank in their division
mine.segments[0].participated;      // true

const { periods } = await kraty.leaderboards.listPeriods('season_league');
const past = await kraty.leaderboards.standings('season_league', {
  scope: 'all',
  period: periods[0].periodStartedAt,
});

const board = await kraty.leaderboards.read('weekly', { progression: ['level'] });
board.entries[0].progression;   // { level: 12 }

const stream = await kraty.eventLeaderboards.live(leaderboardId);

try {
  for await (const ev of stream.events) {
    switch (ev.kind) {
      case 'ready':        break; // initial handshake
      case 'score_update': repaint(ev.data); break;
      case 'closed':       break; // server finalized
    }
  }
} catch (err) {
  // Transport drop: call live() again after a backoff.
} finally {
  await stream.close();
}

// Register once (e.g. at app boot). Returns an unsubscribe fn.
const off = kraty.onFinalized((result) => {
  const placed = result.self ? `#${result.self.rank}` : '—';
  showResultScreen(result.ref.leaderboardId, result.reason, placed);
  // Acknowledge so it never resurfaces and leaves storage.
  void kraty.dismiss(result.ref);
});

// On app foreground / reconnect: cheap when nothing ended.
const ended = await kraty.checkFinalizations();
console.log(`${ended.length} board(s) finalized while away`);

import { FinalizationReason } from '@kraty/sdk';

kraty.onFinalized((result) => {
  switch (result.reason) {
    case FinalizationReason.SessionTerminated: // your lobby ended early
    case FinalizationReason.WindowClosed:       // the whole event ended
    case FinalizationReason.Finalized:          // ended, exact cause unknown
  }
});

// Manual loop.
const pending = await kraty.grants.listPending();
for (const g of pending) {
  if (g.kind === 'crate') {
    await kraty.grants.open(g.id);
  } else {
    await kraty.grants.claim(g.id);
  }
}

// Or in one call:
const result = await kraty.grants.collectAll();
console.log(`Opened ${result.opened.length}, claimed ${result.claimed.length}`);
if (result.hasFailures) {
  for (const f of result.failures) {
    console.warn(`${f.grant.id} failed:`, f.error);
  }
}

await kraty.grants.grant({
  entries: [{ type: 'item', itemKey: 'gold_sword', quantity: 1 }],
});

const items  = await kraty.inventory.list();
const wallet = await kraty.wallet.list();

// Spend.
await kraty.inventory.consume('health_potion', { quantity: 1 });
await kraty.wallet.debit('gold', { amount: 100 });

const res = await kraty.wallet.progress('xp', { amount: 250 });
res.balance;   // 250
res.derived;   // [{ economyKey: 'level', previous: 1, current: 3, delta: 2, grantIds: [...] }]

const levelUp = res.derived.find((d) => d.economyKey === 'level');
if (levelUp && levelUp.delta > 0) {
  showLevelUp(levelUp.current);
  await kraty.grants.collectAll();   // claim the per-level rewards
}

const stop = await kraty.inventory.watch(
  (ev) => {
    if (ev.kind === 'inventory_changed') refreshBackpack();
    if (ev.kind === 'wallet_changed') setBalance(ev.economyKey, ev.balance);
    if (ev.kind === 'grant_created') showRewardPopup(ev.contents);
  },
  { ignoreOwnWrites: true },
);

// on scene teardown / logout
await stop();

const stop = await kraty.inventory.watch(onEvent, {
  onError: (err) => scheduleReconnect(err),
});

const catalog = await kraty.catalog.read();
catalog.items;       // [{ key, name, description, iconUrl, kind, rarity, tags }, ...]
catalog.currencies;  // [{ key, name, description, iconUrl, kind, derived }, ...]

// A derived progression item (a level from XP) carries its curve:
const level = catalog.currencies.find((c) => c.key === 'level');
level?.derived; // { sourceKey: 'xp', levels: [{ level: 1, sourceRequired: 0 }, { level: 2, sourceRequired: 101 }, ...] }

// Your shareable 6-char code (stable for the player's lifetime).
const { friendCode } = await kraty.friends.getCode();

// Find players by display name; each hit carries your relationship.
const hits = await kraty.friends.search('shadow', { limit: 10 });

// "People you may want to add": recently-active non-friends, a weighted
// random sample so it varies each call (default 5, up to 25).
const suggested = await kraty.friends.suggestions({ limit: 5 });

// Add by code or by externalPlayerId (exactly one).
const sent = await kraty.friends.add({ friendCode: 'K7F2Q9' });
await kraty.friends.add({ externalPlayerId: 'player_88' });
// sent.status is 'pending' (they must accept) or 'accepted'
// (reciprocal auto-accept when they'd already requested you).

// Pending requests, both directions.
const { incoming, outgoing } = await kraty.friends.listRequests();
await kraty.friends.accept(incoming[0].requestId);        // → Friend
await kraty.friends.decline(incoming[1]?.requestId);
await kraty.friends.cancelRequest(outgoing[0]?.requestId); // your own outgoing one

// Your friends, enriched with online / lastActiveAt / status.
const friends = await kraty.friends.list();

// Broadcast presence on a ~30s timer; it expires when beats stop.
await kraty.friends.heartbeat({ status: 'in_match' });

// Remove a friend by their externalPlayerId.
await kraty.friends.remove('player_88');

// Blocking tears down any friendship/request and hides you both.
await kraty.friends.block({ externalPlayerId: 'player_99' });
const blocked = await kraty.friends.listBlocks();
await kraty.friends.unblock('player_99');

// The studio's allowlist + the game's cooldown / daily-limit config.
const catalog = await kraty.friends.giftCatalog();
// catalog.resources: { type: 'item' | 'currency', key, maxAmount, costsSender, … }
// 'currency' covers progression resources like XP too.

// Send to an accepted friend. Arrives as a PENDING grant they must claim.
const gift = await kraty.friends.sendGift({
  to: { externalPlayerId: 'player_88' },   // or { friendCode: 'K7F2Q9' }
  type: 'item',
  resourceKey: 'energy_refill',
  amount: 1,
  message: 'good luck out there',
  idempotencyKey: 'daily-2026-08-17-player_88', // retry-safe
});

// The inbox / outbox; { pendingOnly: true } for unclaimed rows only.
const inbox = await kraty.friends.gifts({ pendingOnly: true });
const outbox = await kraty.friends.sentGifts({ pendingOnly: true });

// Claiming is what actually credits the player.
await kraty.friends.claimGift(inbox[0].giftId);

const config = await kraty.guilds.config();      // unlock gate, cost, role permissions, help + score settings
const mine = await kraty.guilds.mine();          // MyGuild | null: roster, role, permissions, week
const other = await kraty.guilds.get(guildId);   // any guild with its roster

// Discovery
const hits = await kraty.guilds.search('owls', { country: 'US', limit: 20 }); // first page
const page = await kraty.guilds.searchPage('owls', { offset: 20 });            // { guilds, nextOffset }
const picks = await kraty.guilds.recommended({ limit: 10 });   // friends' guilds first

// Found or join
const created = await kraty.guilds.create({ name: 'Night Owls', joinType: 'request' });
const result = await kraty.guilds.join(guildId, { message: 'hi!' }); // { status: 'joined' | 'requested' }
const pending = await kraty.guilds.myRequests();
await kraty.guilds.cancelRequest(pending[0].requestId);

// Officers (permissions per role come from the config)
const inbox = await kraty.guilds.requests();
await kraty.guilds.acceptRequest(inbox[0].requestId);
await kraty.guilds.declineRequest(inbox[1].requestId);
await kraty.guilds.promote('player_88');
await kraty.guilds.demote('player_88');
await kraty.guilds.kick('player_99');
await kraty.guilds.transferLeadership('player_88');
await kraty.guilds.updateProfile({ description: 'Raids at 8 pm', joinType: 'open' });
await kraty.guilds.leave();

// Help requests
const help = await kraty.guilds.help();
const req = await kraty.guilds.requestHelp({ type: 'item', resourceKey: 'life', amount: 5 });
await kraty.guilds.donate(help.requests[0].requestId, { amount: 1 });
await kraty.guilds.cancelHelp(req.requestId);

import { pollLobbyUntilActive, KratyApiError } from '@kraty/sdk';

try {
  const start = await kraty.events.start('quick_brawl');
} catch (err) {
  if (err instanceof KratyApiError && err.isLobbyForming) {
    const lobbyId = (err.details as { lobbyId: string }).lobbyId;
    const lobby = await pollLobbyUntilActive(kraty.lobbies, lobbyId);
    // Now safe to retry events.start
    const start = await kraty.events.start('quick_brawl');
  }
}

import { lobbyFilledSlots } from '@kraty/sdk';

const lobby = await kraty.lobbies.read(lobbyId);
console.log(`${lobby.participantCount} humans + ${lobby.botSlots ?? 0} bots / ${lobby.capacity}`);
console.log(`filled (clamped): ${lobbyFilledSlots(lobby)}`);

import { pollPendingGrants } from '@kraty/sdk';

const ctrl = new AbortController();
void pollPendingGrants(kraty.grants, {
  startMs: 2_000,
  growMs: 1.5,
  maxMs: 30_000,
  signal: ctrl.signal,
  onBatch: (batch) => { /* claim / open / queue for UI */ },
});
// later: ctrl.abort();

import { KratyApiError, KratyNetworkError } from '@kraty/sdk';

try {
  await kraty.events.start('bounty_hunt');
} catch (err) {
  if (err instanceof KratyApiError) {
    if (err.isLobbyForming) {
      // matchmaking lobby still filling: poll and retry
    } else if (err.isInsufficientEntryCost) {
      // player cannot afford: err.message has the resource detail
    } else if (err.isPlayerSecretInvalid) {
      // re-register or surface to the user
    } else {
      switch (err.code) {
        case 'no_active_window':
          // event is between windows
          break;
        case 'max_attempts_reached':
          // player burned all attempts for this window
          break;
      }
    }
  } else if (err instanceof KratyNetworkError) {
    // backend unreachable
  }
}

new Kraty({
  apiKey: '...',
  onRequest: (info) => {
    metrics.timing(`kraty.${info.url}`, info.durationMs);
    if (!info.ok) metrics.increment(`kraty.error.${info.status}`);
  },
});