Flutter SDK

# pubspec.yaml
dependencies:
  kraty:
    git:
      url: https://github.com/PedroTrincheiras/kraty-sdk-flutter.git
      ref: v0.18.1

import 'package:kraty/kraty.dart';

final kraty = Kraty(KratyClientOptions(apiKey: '<your-client-sdk-key>'));

// First player-scoped call below: the SDK generates a kp_<uuid>
// id, calls POST /sdk/v1/players/:id/register, persists the
// secret + id, and attaches X-Player-Secret on every call.
final events = await kraty.events.listForPlayer();
await kraty.events.start(events.first.eventKey);

final kraty = Kraty(KratyClientOptions(
  apiKey: '<your-client-sdk-key>',
  activeExternalPlayerId: 'player_42',
));

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

final secret = await myBackend.linkDevice(playerId);
await kraty.signIn(externalPlayerId: playerId, secret: secret);

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

await kraty.signIn(
  externalPlayerId: 'player_99',
  secret: '<from your auth backend>',
);

// null until the first player-scoped call resolves.
final id = kraty.activeExternalPlayerId;

// Force an early resolve (rare, usually unnecessary):
final (externalPlayerId: pid, secret: _) = await kraty.ensureIdentity();

final kraty = Kraty(KratyClientOptions(
  apiKey: '<your-client-sdk-key>',
  timeout: Duration(seconds: 10),
  retry: KratyRetryConfig(
    attempts: 5,
    initialDelay: Duration(milliseconds: 200),
    maxDelay: Duration(seconds: 10),
    jitter: 0.25,
  ),
  onRequest: (info) {                     // optional telemetry
    print('${info.method} ${info.url} → ${info.status}');
  },
));

kraty.events             // event list / start / progress
kraty.leaderboards       // dashboard-configured cross-event boards (by key)
kraty.eventLeaderboards  // per-event-window boards (by UUID) + SSE live 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 / setIdentity / getIdentity / getAnonymizedIdentity / setMetadata / mergeMetadata

final kraty = Kraty(KratyClientOptions(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 this player play right now?
final available = await kraty.events.listForPlayer();

for (final e in available) {
  print('${e.eventKey} (${e.type})');
  print('  cost: ${e.entryCost?.currencies ?? []}');
  print('  metrics: ${e.metrics.map((m) => m['key']).toList()}');
}

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

// 3) Push progress. `set` writes; `increment` adds.
//    The response carries any milestones whose threshold crossed.
final update = await kraty.events.progress(
  available.first.eventKey,
  start.attempt.id,
  const ProgressInput(mode: 'increment', metricValue: 1),
);
for (final fired in update.milestonesFired) {
  showToast('Milestone ${fired.key} → ${fired.grants.length} grants');
}

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

final res = await kraty.events.finish('score_attack', start.attempt.id);
// res.attempt: the finalized attempt
// res.outcome: 'completed' | 'expired'
if (res.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.

final board = await kraty.leaderboards.read(
  'weekly_global',
  options: const LeaderboardReadOptions(limit: 50, includeSelf: true),
);

for (final e in board.entries) {
  print('#${e.rank} ${e.name} ${e.score} (${e.kind})'); // kind: player | bot
}
if (board.self != null) {
  print('You: #${board.self!.rank} score ${board.self!.score}');
}

final eventLeaderboard = await kraty.eventLeaderboards.read(
  start.attempt.leaderboardId,
  options: const EventLeaderboardReadOptions(limit: 50, includeSelf: true),
);

// Unsegmented / progression-segmented board: no segment.
final result = await kraty.leaderboards.submitScore('daily_steps', 8421);
print('${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.
final board = await kraty.leaderboards.join('weekly_region', segment: 'EU');
final evBoard = await kraty.eventLeaderboards.join(start.leaderboardId);

final mine = await kraty.leaderboards.standings(
  'season_league',
  options: const StandingsReadOptions(scope: 'self_segment', externalId: 'player_alice'),
);
print(mine.segments.first.selfRank); // caller's rank in their division

final periods = await kraty.leaderboards.listPeriods('season_league');
final past = await kraty.leaderboards.standings(
  'season_league',
  options: StandingsReadOptions(scope: 'all', period: periods.periods.first.periodStartedAt),
);

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

stream.events.listen((event) {
  switch (event.kind) {
    case 'ready':       // initial handshake
      break;
    case 'score_update': // someone climbed
      refreshUi(event.data);
      break;
    case 'closed':       // server finalized
      break;
  }
});

stream.errors.listen((err) {
  // Transport drop: re-call .live() after a backoff
});

// Stop streaming:
await stream.cancel();

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

// On app foreground / reconnect: cheap when nothing ended.
final ended = await kraty.checkFinalizations();
debugPrint('${ended.length} board(s) finalized while away');

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.
final pending = await kraty.grants.listPending();
for (final g in pending) {
  if (g.kind == 'crate') {
    await kraty.grants.open(g.id);
  } else {
    await kraty.grants.claim(g.id);
  }
}

// Or in one call:
final result = await kraty.grants.collectAll();
print('Opened ${result.opened.length} crates, claimed ${result.claimed.length}');
if (result.hasFailures) {
  for (final f in result.failures) {
    print('${f.grant.id} failed: ${f.error}');
  }
}

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

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

try {
  final start = await kraty.events.start('quick_brawl');
  // Got an attempt: lobby was already full or a slot opened.
} on KratyApiError catch (err) {
  if (err.isLobbyForming) {
    final lobbyId = (err.details as Map)['lobbyId'] as String;
    final lobby = await pollLobbyUntilActive(kraty.lobbies, lobbyId);
    // Now safe to retry events.start:
    final start = await kraty.events.start('quick_brawl');
  }
}

final lobby = await kraty.lobbies.read(lobbyId);
print('${lobby.participantCount} humans + ${lobby.botSlots} bots'
      ' / ${lobby.capacity}');
print('filled (clamped to capacity): ${lobby.filledSlots}');

// Adaptive grants polling: grows interval while empty, snaps
// back to the floor when grants land.
final stop = Completer<void>();
unawaited(pollPendingGrants(
  kraty.grants,
  options: PollPendingGrantsOptions(
    start: Duration(seconds: 2),
    grow: 1.5,
    max: Duration(seconds: 30),
    onBatch: (batch) => print('${batch.length} pending'),
  ),
  signal: stop.future,
));
// later: stop.complete();

// Fixed-interval lobby poll with a TimeoutException after
// `timeout`.
final lobby = await pollLobbyUntilActive(
  kraty.lobbies,
  lobbyId,
  options: PollLobbyOptions(
    interval: Duration(seconds: 1),
    timeout: Duration(seconds: 60),
  ),
);

try {
  await kraty.events.start('bounty_hunt');
} on KratyApiError catch (err) {
  if (err.isLobbyForming) {
    // matchmaking
  } 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 KratyErrorCode.noActiveWindow:
        // event is between windows
        break;
      case KratyErrorCode.maxAttemptsReached:
        // player burned all attempts for this window
        break;
      default:
        rethrow;
    }
  }
} on KratyNetworkError {
  // backend unreachable
}

final kraty = Kraty(KratyClientOptions(
  apiKey: '...',
  onRequest: (info) {
    metrics.timing('kraty.${info.url}', info.duration.inMilliseconds);
    if (!info.ok) metrics.increment('kraty.error.${info.status}');
  },
));