v0.5.0: batch-first API, player/leaderboard handles, unified naming, Storage is global project storage, catalog list methods

README.md

@@ -39,15 +39,162 @@ if err != nil {
 }
 
 players, err := client.Players.List(ctx, rudder.ListPlayersParameters{Limit: 100})
-entries, err := client.Leaderboards.ListEntries(ctx, "weekly")
-wallet, err := client.Wallet.Adjust(ctx, playerID, rudder.AdjustWalletParameters{
-    CurrencyCode: "coins",
-    Amount:       100,
-    Reason:       "compensation",
-})
 metrics, err := client.Metrics.Get(ctx)
 ```
 
+## Handles
+
+`client.Player(id)` и `client.Leaderboard(slug)` создают handle без
+HTTP-запроса. Handles — сахар над batch-методами сервисов: каждая операция
+отправляет batch из одного элемента с подставленным playerID/slug.
+
+```go
+player := client.Player("p1")
+
+wallet, err := player.Wallet().Adjust(ctx, rudder.AdjustPlayerWalletParameters{
+    IdempotencyKey: "grant-001",
+    CurrencyCode:   "coins",
+    Amount:         100,
+    Reason:         "compensation",
+})
+history, err := player.Wallet().History(ctx, rudder.WalletHistoryParameters{Limit: 50})
+
+item, err := player.Inventory().Adjust(ctx, rudder.AdjustPlayerInventoryParameters{
+    Slug:   "sword",
+    Amount: 1,
+    Reason: "quest reward",
+})
+inventory, err := player.Inventory().List(ctx, rudder.ListInventoryParameters{Limit: 50})
+
+storage, err := player.Storage().Get(ctx, "settings")
+updated, err := player.Storage().Upsert(ctx, rudder.UpsertPlayerStorageParameters{
+    Type: "settings",
+    Data: `{"lang":"ru"}`,
+})
+err = player.Storage().Delete(ctx, rudder.DeletePlayerStorageParameters{Type: "settings"})
+
+quests, err := player.Quests().List(ctx)
+err = player.Quests().Reset(ctx, rudder.PlayerQuestParameters{QuestID: "daily-1"})
+// ForceComplete и ForceClaim — аналогично
+
+updatedPlayer, err := player.Update(ctx, rudder.UpdatePlayerParameters{Nickname: "Neo"})
+banned, err := player.Ban(ctx, rudder.BanPlayerParameters{
+    Reason:      "cheating",
+    BannedUntil: "2030-01-01T00:00:00Z",
+})
+unbanned, err := player.Unban(ctx, "")
+err = player.Delete(ctx, "")
+
+board := client.Leaderboard("weekly")
+
+entries, err := board.List(ctx, rudder.ListLeaderboardEntriesParameters{Limit: 100})
+// entries.Entries []models.RankEntry, entries.NextCursor
+
+entry, err := board.Get(ctx, "p1")            // *models.RankEntry с rank
+around, err := board.GetAround(ctx, "p1", 10) // []models.RankEntry вокруг игрока
+
+err = board.Submit(ctx, []models.BatchLeaderboardEntry{{PlayerID: "p1", Score: 1500}})
+err = board.Update(ctx, []models.BatchLeaderboardEntry{{PlayerID: "p1", Score: 1600}})
+err = board.Delete(ctx, []string{"p1", "p2"})
+```
+
+## Batch-first API
+
+Все мутирующие операции верхнего уровня — batch-only: тело
+`{idempotencyKey?, items:[...]}` (`playerId` внутри элементов), до 100
+элементов, all-or-nothing в одной транзакции, один idempotency key на батч.
+
+```go
+wallets, err := client.Wallet.Adjust(ctx, rudder.AdjustWalletParameters{
+    IdempotencyKey: "grant-001",
+    Items: []models.BatchAdjustPlayerWalletsItem{
+        {PlayerID: "p1", CurrencyCode: "coins", Amount: 100, Reason: "compensation"},
+        {PlayerID: "p2", CurrencyCode: "coins", Amount: 100, Reason: "compensation"},
+    },
+})
+
+items, err := client.Inventory.Adjust(ctx, rudder.AdjustInventoryParameters{
+    Items: []models.BatchAdjustPlayerInventoryItemsItem{
+        {PlayerID: "p1", Slug: "sword", Amount: 1, Reason: "quest reward"},
+    },
+})
+
+updated, err := client.Players.Update(ctx, rudder.UpdatePlayersParameters{
+    Items: []models.BatchUpdatePlayersItem{
+        {PlayerID: "p1", Nickname: "Neo"},
+    },
+})
+
+banned, err := client.Players.Ban(ctx, rudder.BanPlayersParameters{
+    Items: []models.BatchBanPlayersItem{
+        {PlayerID: "p2", Reason: "cheating", BannedUntil: "2030-01-01T00:00:00Z"},
+    },
+})
+
+unbanned, err := client.Players.Unban(ctx, rudder.UnbanPlayersParameters{
+    Items: []models.BatchPlayerItem{{PlayerID: "p2"}},
+})
+
+err = client.Players.Delete(ctx, rudder.DeletePlayersParameters{
+    Items: []models.BatchPlayerItem{{PlayerID: "p3"}},
+})
+
+err = client.Quests.Reset(ctx, rudder.ResetPlayerQuestsParameters{
+    Items: []models.BatchPlayerQuestsItem{
+        {PlayerID: "p1", QuestID: "daily-1"},
+    },
+})
+// ForceComplete и ForceClaim — аналогично
+
+err = client.Leaderboards.Submit(ctx, "weekly", []models.BatchLeaderboardEntry{
+    {PlayerID: "p1", Score: 1500},
+})
+// Update и Delete — аналогично
+
+err = client.Storage.Upsert(ctx, rudder.UpsertStorageParameters{
+    Items: []models.AdminProjectStorageItem{
+        {Type: "config", Data: `{"event":"x2"}`},
+    },
+})
+
+err = client.Storage.Delete(ctx, rudder.DeleteStorageParameters{
+    Types: []string{"config"},
+})
+```
+
+## Каталоги и read-операции
+
+Курсорная пагинация: передавайте `Limit`/`Cursor`, следующую страницу
+запрашивайте по `NextCursor` из ответа.
+
+```go
+boards, err := client.Leaderboards.List(ctx, rudder.ListLeaderboardsParameters{Limit: 100})
+// boards.Items []models.LeaderboardDefinition, boards.NextCursor
+
+quests, err := client.Quests.List(ctx, rudder.ListQuestsParameters{
+    Status: &status, // "active" или "archived", optional
+    Limit:  100,
+})
+// quests.Items []models.QuestDefinition, quests.NextCursor
+
+history, err := client.Wallet.History(ctx, playerID, rudder.WalletHistoryParameters{
+    Currency: &currency, // optional
+    Limit:    50,
+})
+// history.Entries []models.WalletAudit, history.NextCursor
+
+inventory, err := client.Inventory.List(ctx, playerID, rudder.ListInventoryParameters{
+    Limit: 50,
+})
+// inventory.Items []models.InventoryItem, inventory.NextCursor
+
+storage, err := client.Storage.List(ctx, rudder.ListStorageParameters{
+    Limit:  100,
+    Search: "config", // optional
+})
+item, err := client.Storage.Get(ctx, "config")
+```
+
 ## Ошибки
 
 ```go