Flutter SDK

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

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  // 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

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

// includeSelf resolves to the active player automatically.
final board = await kraty.leaderboards.read(
  start.leaderboardId,
  options: 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 stream = await kraty.leaderboards.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();

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