# App Version Check API

Clients (mobile and TV apps) should call this endpoint on app startup to determine if the user needs to update their app.

## Endpoint

```
GET /client/v1/app-version?platform={platform}&currentVersion={version}
```

No authentication required.

## Parameters

| Parameter        | Type   | Description                          |
|------------------|--------|--------------------------------------|
| `platform`       | int    | The client platform (see table below)|
| `currentVersion` | string | The app's current version (e.g. `1.2.3`) |

### Platform Values

| Value | Platform   |
|-------|------------|
| 0     | Android    |
| 1     | iOS        |
| 2     | LG TV      |
| 3     | Samsung TV |
| 4     | Apple TV   |
| 5     | Android TV |

## Response

```json
{
  "minimumVersion": "2.1.0",
  "forceUpdate": true,
  "updateRequired": true
}
```

| Field            | Type    | Description                                                                 |
|------------------|---------|-----------------------------------------------------------------------------|
| `minimumVersion` | string  | The minimum version required by the backend                                 |
| `forceUpdate`    | boolean | If `true`, the user must update before using the app                        |
| `updateRequired` | boolean | If `true`, the user's current version is below the minimum required version |

## Implementation

### 1. Call the endpoint on app startup

Send a GET request before the user interacts with the app.

```
GET /client/v1/app-version?platform=0&currentVersion=1.0.0
```

### 2. Handle the response

- **`updateRequired` is `false`**: No action needed. Proceed normally.
- **`updateRequired` is `true` and `forceUpdate` is `false`**: Show a dismissible prompt suggesting the user update.
- **`updateRequired` is `true` and `forceUpdate` is `true`**: Block the app with a full-screen message and a button linking to the app store. Do not let the user proceed.

### 3. Handle errors

If the request fails (network error, timeout, server error), let the user continue using the app. Do not block the user because of a failed version check.

## Example (TypeScript)

```typescript
const response = await fetch(
  `${API_BASE_URL}/client/v1/app-version?platform=${platform}&currentVersion=${appVersion}`
);
const data = await response.json();

if (data.updateRequired) {
  if (data.forceUpdate) {
    showForceUpdateScreen(); // blocks the app
  } else {
    showOptionalUpdateDialog(); // dismissible
  }
}
```

## Admin: Setting Version Requirements

Admins update version requirements per platform via:

```
PUT /admin/v1/app-version
```

Request body:

```json
{
  "platform": 0,
  "minimumVersion": "2.1.0",
  "forceUpdate": true
}
```

This sets the minimum required version for the given platform. If `forceUpdate` is `true`, any client below that version will be forced to update.