# SMMODS API v1 Prototype

This folder contains static JSON files that model the first manager-facing API.
They are prototype data, not a live backend.

Planned API routes from the distribution model:

```text
GET  /api/v1/framework/latest
GET  /api/v1/runtime/latest
GET  /api/v1/game-builds/latest
GET  /api/v1/readiness
GET  /api/v1/mods
GET  /api/v1/mods/{modId}
GET  /api/v1/mods/{modId}/versions
GET  /api/v1/manager/latest
GET  /api/v1/publishing/workflow
GET  /api/v1/publishing/backend-contract
GET  /api/v1/publishing/backend-contract.schema.json
GET  /api/v1/publishing/starminer-publishing-validation.v1.json
GET  /api/v1/publishing/starminer-publishing-validation.schema.json
GET  /api/v1/publishing/upload-submission.schema.json
GET  /api/v1/publishing/mod-release-submission.schema.json
GET  /api/v1/backend/health
POST /api/v1/accounts
POST /api/v1/accounts/{accountId}/verify-email
POST /api/v1/auth/session
GET  /api/v1/auth/session
DELETE /api/v1/auth/session
POST /api/v1/uploads
GET  /api/v1/uploads/{submissionId}
POST /api/v1/uploads/{submissionId}/cancel
GET  /api/v1/moderation/releases
POST /api/v1/moderation/releases/{submissionId}/decision
POST /api/v1/catalog/publish
GET  /api/v1/audit/events
```

Static prototype files:

```text
/api/v1/catalog.json
/api/v1/readiness.json
/api/v1/runtime/latest.json
/api/v1/framework/latest.json
/api/v1/game-builds/latest.json
/api/v1/mods/index.json
/api/v1/mods/example.hello-lua/index.json
/api/v1/mods/example.hello-lua/versions.json
/api/v1/mods/example.hello-lua-companion/index.json
/api/v1/mods/example.hello-lua-companion/versions.json
/api/v1/mods/starminer.object-catalog-export/index.json
/api/v1/mods/starminer.object-catalog-export/versions.json
/api/v1/manager/latest.json
/api/v1/publishing/workflow.json
/api/v1/publishing/backend-contract.json
/api/v1/publishing/backend-contract.schema.json
/api/v1/publishing/starminer-publishing-validation.v1.json
/api/v1/publishing/starminer-publishing-validation.schema.json
/api/v1/publishing/upload-submission.schema.json
/api/v1/publishing/mod-release-submission.schema.json
```

`runtime/latest.json` is the pinned UE4SS payload/layout contract consumed by
the manager. The manager should not resolve upstream UE4SS latest directly for
public installs.

`game-builds/latest.json` is the generated Starminer build compatibility matrix
for the current framework/runtime pair. It lists known Steam build IDs,
manifest IDs, validation status, and the supported builds that also appear in
`catalog.json` as `supportedGameBuilds`. The endpoint is refreshed by
`tools/Sync-GameBuildCompatibility.ps1` and consumed by managers that need to
warn users when their installed game build is not currently validated.

`readiness.json` is the public production-readiness status. It must keep
`overallStatus: not_release_ready` and expose concrete blockers while account,
upload, moderation, and final production manager release work is incomplete.

`publishing/workflow.json` is a static contract for the future authenticated
account, upload, validation, moderation, and publication state machine. It is
not a live upload service; `liveBackend` must remain `false` until backend
services actually exist. Its `backendRequirements` block lists the concrete
services that must be deployed before account/upload/moderation copy can stop
being placeholder copy.

`publishing/backend-contract.json` is the planned backend route and data
contract for those services. It defines the account/session, upload,
moderation, catalog publication, and audit endpoints that must exist before
`liveBackend` can become `true`. Account creation fails closed with
`email_delivery_unavailable` unless verification email delivery is configured,
and authenticated upload creation is guarded by `SMMODS_LIVE_UPLOADS`; while
that flag is `0`, `POST /api/v1/uploads` returns `uploads_disabled` before
accepting package bytes. Backend write routes also return
`rate_limit_exceeded` with `Retry-After` when account, session, upload, or
moderation traffic crosses the configured bucket. Its public JSON Schema is
`publishing/backend-contract.schema.json`.

`publishing/starminer-publishing-validation.v1.json` is the framework-owned
upload validation contract consumed by the backend and checked by site
validation. Its required check ids come from the Starminer Modding framework
repo; the site should publish a fresh copy when framework releases update.

`publishing/upload-submission.schema.json` defines the planned authenticated
upload status response for `GET /api/v1/uploads/{submissionId}`. It is the
contract modders will use to read validation checks, review state, hashes, and
publication links after a ZIP is submitted.

Artifacts stay omitted or marked as planned until real release ZIPs and SHA256
values are published. Do not publish fake package URLs or zero hashes for
unreleased versions.

Only manager-installable mod records belong in `catalog.json` and
`mods/index.json`. Planned examples can appear on public HTML pages, but should
stay out of the API until they have a detail endpoint, a releasable artifact,
and real hash metadata.

`catalog.json` stays strict-manager-compatible. Mod release notes are required
on `/api/v1/mods/{modId}/versions.json`, while catalog version records carry
the manager-readable update fields: version, target game build, artifact URL,
`packageSizeBytes`, SHA256, artifact state, download state, dependencies,
entrypoints, `publishedAt`, and `status`. Framework releases also expose
`packageSizeBytes`; the pinned runtime profile exposes `asset.sizeBytes`.
Catalogs also carry `gameBuildCompatibilityUrl` and `supportedGameBuilds` so the
manager can link install decisions to the current compatibility endpoint.

Until the production backend catalog publisher exists, approved mod releases
enter the catalog through the manual importer:

```powershell
.\tools\Import-ModRelease.ps1 -PackagePath "E:\path\to\mod-1.2.3.zip" -MetadataPath "E:\path\to\mod-1.2.3.release.json"
```

The sidecar metadata shape is defined by
`publishing/mod-release-submission.schema.json`, with examples in
`docs/mod-release-submission.example.json`. The full review lane is in
`docs/manual-publishing.md`.

## Artifact Publication Rule

For each downloadable framework or mod artifact:

1. Place the immutable ZIP under `public/downloads/`.
2. Compute SHA256 from that exact tracked file.
3. Compute package byte size from that exact tracked file.
4. Update every matching `packageUrl` or `downloadUrl`.
5. Update every matching `sha256` and package size field.
6. Change `artifactStatus` from `placeholder` only after the URL and hash are real.
7. Set `downloadEnabled: true` only after static JSON parsing and manager catalog
   parsing both pass.
8. Do not edit catalog/detail/version JSON by hand for approved releases; use
   `tools/Import-ModRelease.ps1` so hash, version, manifest, and endpoint
   alignment checks run together.

Manager ZIPs are the exception: publish them from the GitLab `smmodmanager`
release as versioned release assets. The ecosystem sync job reads GitLab's
latest manager and framework releases, records the direct versioned manager
asset URL and expected SHA256, publishes the tracked framework ZIP, and refreshes
game-build compatibility without hosting manager ZIPs.

The catalog remains the manager's canonical public index. Detail endpoints should
not drift from `catalog.json`, and versions endpoints must carry non-empty
release notes for every catalog version.