# API reference

The package exposes a single `gamma` object. All methods are promise-first.

```js
import {gamma} from '@swiftware/gamma-sdk';
// drop-in: global `gamma`
```

## Lifecycle

| Member | Signature | Description |
|---|---|---|
| `gamma.configure(config)` | `(config: GammaConfig) => void` | Set options **before** the first call (timeout, storage key, dev mock). |
| `gamma.ready()` | `() => Promise<void>` | Resolve once the SDK has settled (real host, or fallback outside the app). Idempotent. |
| `gamma.isInApp` | `boolean` | `true` only when the real Gamma Games host is present. Check after `ready()`. |

```ts
interface GammaConfig {
  readyTimeoutMs?: number;            // default 1500
  storageKey?: string;                // default 'gamma_save'
  mock?: boolean | {                  // off by default
    coins?: number;
    player?: Partial<Player>;
    coinValue?: Partial<CoinValue>;
  };
}
```

## Coins

| Method | Signature |
|---|---|
| `getCoins()` | `() => Promise<number>` |
| `spendCoins(amount, reason)` | `(number, string) => Promise<SpendResult>` |
| `earnCoins(amount, reason)` | `(number, string) => Promise<EarnResult>` |

```ts
interface SpendResult { ok: boolean; newBalance?: number; spent?: number; balance?: number; error?: GammaErrorCode }
interface EarnResult  { ok: boolean; newBalance?: number; earned?: number; error?: GammaErrorCode }
```

- `spendCoins` amount: `1..10000`. `earnCoins` amount: `1..100`.
- `reason`: `^[a-z0-9_]+$`, ≤ 64 chars.

## Coin value

| Method | Signature |
|---|---|
| `getCoinValue()` | `() => Promise<CoinValue>` |
| `coinsToUsd(amount)` | `(number) => Promise<number>` |
| `formatCoins(amount)` | `(number) => Promise<string>` |

```ts
interface CoinValue {
  usdPerCoin: number;
  currencyCode: string;
  displayName: string;
  symbol: string;
  iconUrl: string | null;
}
```

## Player

| Method | Signature |
|---|---|
| `getPlayer()` | `() => Promise<Player \| null>` |

```ts
interface Player {
  id: string;
  displayName: string;
  avatar: string | null;
  frame: string | null;
  isSubscribed: boolean;
}
```

## Progress

| Member | Signature | Notes |
|---|---|---|
| `gamma.storage.init()` | `() => Promise<boolean>` | Resolve host once; returns `isInApp`. |
| `gamma.storage.ready()` | `() => boolean` | Whether the host is resolved. |
| `gamma.storage.load()` | `() => Promise<ProgressData \| null>` | Account in-app, `localStorage` outside. |
| `gamma.storage.save(state)` | `(ProgressData) => Promise<boolean>` | Returns `true` on success. |
| `gamma.loadProgress()` | `() => Promise<ProgressData \| null>` | Low-level, account-only. |
| `gamma.saveProgress(data)` | `(ProgressData) => Promise<boolean>` | Low-level, account-only. Max 100 KB encoded. |

`ProgressData` is any JSON-serialisable object — include an integer
`schemaVersion`.

## Raw bridge equivalents

The package wraps `window.GammaSDK` (callback-style). If you integrate manually,
see [Manual integration](./manual-integration.md) for the raw method shapes and the
underlying `{success, ...}` result objects.