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 (server-driven effects), and storage.

- 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 the effects client (30s pending heartbeat + wait deadlines) 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` |
| `Effects` | `EffectsService` | `On*` effect events; complete via methods on the effect objects |
| `Storage` | `StorageService` | `GetAsync`, `ListAllAsync`, `SaveAsync`, `DeleteAsync` |

## 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 `QuestEffect` (`Effects.OnQuest`).

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

// 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(offerSlug)` / `QuestMetrics.PurchaseItem(itemId)`
name the format (`purchase.offer:<offerSlug>`, `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

The server owns scenario execution. Trigger with `client.Scenario.TriggerAsync`,
subscribe to typed effects on `client.Effects`, and call `client.Update` every
frame:

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

Complete an effect with the methods on the object (`DoneAsync`,
`PurchaseAsync`/`DeclineAsync`, `EndAsync`/`ClaimAsync`, …) or the run
stalls. `unknown_run` / `run_expired` drop the run and fire
`OnScenarioFailed`.

## Tests

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