rudder-csharp-sdk/README.md

# Rudder.Core

.NET client SDK for the Rudder LiveOps platform: authentication, player
profile, stores, battle pass, quests, leaderboards, inventory, remote config,
scenarios, storage and realtime.

- Target framework: `netstandard2.1` (works in Unity, .NET, Xamarin).
- JSON: Newtonsoft.Json.
- Naming follows the cross-SDK glossary: `.spec/sdk-glossary.md` in the
  monorepo root.

## Install

```
dotnet add package Rudder.Core
```

## Quickstart

```csharp
using RudderSdk.Core;

var client = new RudderClient(new RudderClientOptions
{
    BaseUrl = "https://api.example.com",
    ProjectKey = "your-project-key"
});

// Sign in with the device id.
await client.Auth.LoginWithDeviceAsync(region: "en", language: "en");

// First call: read the player profile.
var profile = await client.Player.GetProfileAsync();
Console.WriteLine(profile.Player.Id);

// Buy an offer (idempotency key is generated when omitted).
var purchase = await client.Stores.PurchaseAsync("main-store", "offer-1");

// Pump time-dependent services (scenarios, realtime) every frame.
client.Update(deltaTime);
```

Only `BaseUrl` and `ProjectKey` are required. `Transport`,
`TokenStore` and `DeviceIdProvider` default to `HttpClientTransport`,
`InMemoryTokenStore` and `GuidDeviceIdProvider`; inject your own
implementations via `RudderClientOptions` for persistence or a custom HTTP
stack.

## Services

| Property | Service | Main operations |
|---|---|---|
| `Auth` | `AuthService` | `LoginWithDeviceAsync`, `RefreshAsync`, `Logout`, `AuthStateChanged` |
| `Player` | `PlayerService` | `GetProfileAsync` |
| `BattlePass` | `BattlePassService` | `GetProgressAsync`, `AddXpAsync`, `ClaimRewardAsync`, `PurchasePremiumAsync` |
| `Quests` | `QuestsService` | `ListAsync`, `ClaimAsync`, `ReportProgressAsync` |
| `Stores` | `StoresService` | `ListAsync`, `GetAsync`, `PurchaseAsync` |
| `Inventory` | `InventoryService` | `GetAsync` |
| `Leaderboards` | `LeaderboardsService` | `FindBySlug(slug)` → handle: `SubmitAsync`, `ListAsync` |
| `RemoteConfig` | `RemoteConfigService` | `LoadAsync`, `Get<T>`, `GetAsync<T>` |
| `Scenario` | `ScenarioService` | `TriggerAsync`, `RestoreAsync`, `On*` effect events |
| `Storage` | `StorageService` | `GetAsync`, `ListAllAsync`, `SaveAsync`, `DeleteAsync` |
| `Realtime` | `RealtimeService` | `ConnectAsync`, `DisconnectAsync` |

## Quests

`client.Quests` covers the player's global quests — list with per-objective
progress, claim, and metric reports. These are distinct from scenario quest
nodes, which advance through `QuestSession` (`Scenario.OnQuest`).

```csharp
var quests = await client.Quests.ListAsync();
foreach (var quest in quests)
{
    if (quest.Status == "completed")
        await client.Quests.ClaimAsync(quest.Id);
}

// Custom metrics advance matching objectives server-side; the call returns
// the ids of quests completed by this report.
var completedIds = await client.Quests.ReportProgressAsync("kills", 1);
```

Purchase metrics are reported automatically by store purchases;
`QuestMetrics.PurchaseOffer(offerId)` / `QuestMetrics.PurchaseItem(itemId)`
name the format (`purchase.offer:<offerId>`, `purchase.item:<itemId>`) so
quest configs and client code agree on it.

## Sessions

Every API call goes through the client's session pipeline: a 401 triggers a
single-flight token refresh and one transparent retry. When the refresh fails,
tokens are cleared and `Auth.AuthStateChanged` fires with
`RudderAuthState.SignedOut`.

## Errors

Transport maps failures to typed exceptions:

- `RudderAuthException` — HTTP 401
- `RudderNotFoundException` — HTTP 404
- `RudderRateLimitException` — HTTP 429
- `RudderNetworkException` — no response (connectivity, timeout)
- `RudderApiException` — base class, any other status

All of them carry `StatusCode` (`int`), the machine-readable `Code`
(see `RudderErrorCodes`) and the server-issued `RequestId` when available.

## Scenario effects

Subscribe to typed sessions on `client.Scenario`:

`OnNotification`, `OnStoreOffer`, `OnLeaderboard`, `OnConfigChanged`,
`OnWait`, `OnQuest`, `OnBattlePass`, `OnBattlePassLevel`,
`OnScenarioCompleted`, `OnScenarioFailed`.

## Tests

```
dotnet test tests/Rudder.Core.Tests
```