TypeScript SDK

npm install github:PedroTrincheiras/kraty-sdk-typescript#v0.18.1
# or with pnpm:
pnpm add github:PedroTrincheiras/kraty-sdk-typescript#v0.18.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}`);
  },
});

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 / requests / presence / blocks
kraty.catalog           // items + currencies for display

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);
}

// 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 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);
  }
}

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 catalog = await kraty.catalog.read();
catalog.items;       // [{ key, name, description, iconUrl, kind, rarity, tags }, ...]
catalog.currencies;  // [{ key, name, description, iconUrl, kind }, ...]

// 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 });

// 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');

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}`);
  },
});