# mod.io Integration

Task: `TODOS.phase-72.72.14.2.2`

The V2 mod distribution layer exposes mod.io as the non-Steam cross-platform
provider through `FV2ModIoPolicy`, `FV2ModIoRequest`, and `FV2ModIoOperation`.
The implementation plans REST calls against `https://api.mod.io/v1` and keeps
credentials, OAuth state, terms disclosure, and platform targeting explicit so
console and alternate PC storefront flows can be validated before network
submission.

References:

- https://docs.mod.io/restapi
- https://docs.mod.io/restapi/docs/add-mod
- https://docs.mod.io/restapi/docs/add-modfile
- https://docs.mod.io/restapi/docs/get-modfiles
- https://docs.mod.io/restapi/docs/subscribe-to-mod
- https://docs.mod.io/restapi/docs/edit-mod
- https://docs.mod.io/restapi/docs/edit-modfile
- https://docs.mod.io/restapi/docs/add-mod-rating

## Runtime Contract

`BuildDefaultModIoPolicy` declares these REST endpoints:

- `POST /games/:game-id/mods` to create the mod profile.
- `POST /games/:game-id/mods/:mod-id/files` to upload a packaged `.mayamod`
  modfile.
- `GET /games/:game-id/mods/:mod-id/files` to retrieve modfile records and the
  API-issued download URL.
- `POST /games/:game-id/mods/:mod-id/subscribe` plus `GET /me/subscribed` to
  subscribe and refresh the authenticated user's collection.
- `POST /games/:game-id/mods/:mod-id` and
  `PUT /games/:game-id/mods/:mod-id/files/:file-id` to update metadata and file
  release details.
- `POST /games/:game-id/mods/:mod-id/ratings` to submit a positive or negative
  rating.

Production configuration must provide a positive mod.io game id, an API key, and
OAuth for write operations. Submissions must show the mod.io terms link before
creating mod records or uploading files.

## Non-Steam Platforms

`EV2ModIoPortal` covers `EpicGamesStore`, `GOG`, `PlayStation`, `Xbox`,
`Switch`, `Mobile`, and `Oculus`. Creation, upload, download, subscription, and
update requests require explicit platform targets so platform-filtered modfiles
cannot be published or installed accidentally.

## Operation Builders

Use the Blueprint helpers to create typed requests:

- `BuildModIoCreateModRequest`
- `BuildModIoUploadFileRequest`
- `BuildModIoDownloadRequest`
- `BuildModIoSubscribeRequest`
- `BuildModIoUpdateRequest`
- `BuildModIoRateRequest`

`EvaluateModIoRequest` returns the REST call sequence, blocking validation
issues, install/staging paths, platform-target flags, and whether the request is
ready for the mod.io API client. Upload requests above 100 MiB are marked for
multipart orchestration; uploads above the configured direct upload cap are
blocked until multipart support is supplied by the calling client.

## Local State Projection

`ApplyModIoOperationToState` updates `FV2ModIoItemState` after a REST response
succeeds. Subscription operations mark the mod subscribed and pending download,
download operations mark the package installed, and rating operations preserve
the chosen positive or negative vote for local browser state.

## Verification

Run:

```bash
python3 V2/ue/Tools/check-v2-modio-integration.py
python3 -m json.tool V2/ue/Content/V2/Modding/ModIoIntegration_V2_Contract.json
```

The focused checker verifies the contract, runtime declarations, REST endpoint
mapping, automation assertions, docs, CI/Horde wiring, and TODO evidence for
`72.14.2.2`.