TypeScript SDK

# Pin to a specific version (recommended):
npm install github:PedroTrincheiras/kraty-sdk-typescript#v0.1.0
# or with pnpm:
pnpm add github:PedroTrincheiras/kraty-sdk-typescript#v0.1.0

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

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  // read + live SSE stream
kraty.grants        // pending / claim / open / collectAll
kraty.lobbies       // read (with botSlots projection)
kraty.inventory     // list / consume
kraty.wallet        // list / debit
kraty.players       // register / rotate
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' });

// 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 can't afford it.
const start = await kraty.events.start(
  available[0].eventKey,
  { country: 'PT', level: 7 },
);

// 3) Push progress. `set` writes; `increment` adds.
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`);
}

// 4) Attempt completed?
if (update.attempt.status === 'completed') {
  await kraty.grants.collectAll();
}

// `includeSelf` resolves to the active player by default — no
// need to repeat the id.
const board = await kraty.leaderboards.read(start.leaderboardId, {
  limit: 50,
  includeSelf: true,
});

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

// Top 50 of an unsegmented all-time board. The active player's
// rank is included automatically.
const allTime = await kraty.leaderboards.readShared('all_time_global', {
  limit: 50,
  includeSelf: true,
});

const leagueBoard = await kraty.leaderboards.readShared('season_league', {
  segment: 'diamond',          // the player's bucket
  limit: 20,
  includeSelf: true,
});

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

const stream = await kraty.leaderboards.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();
}

// 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 }, ...]

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