# SMMODS API v1 Static Contracts

This folder contains static JSON files that publish the manager-facing API and
the staged publishing-backend contract. File-backed catalog, runtime, framework,
manager, mod, and readiness endpoints are live static contracts; dynamic
account, upload, moderation, catalog-publish, and audit routes remain gated
until the production backend is deployed.

API routes from the distribution model:

```text
GET  /api/v1/framework/latest.json
GET  /api/v1/runtime/latest.json
GET  /api/v1/game-builds/latest.json
GET  /api/v1/readiness.json
GET  /api/v1/mods
GET  /api/v1/mods/{modId}
GET  /api/v1/mods/{modId}/versions
GET  /api/v1/manager/latest.json
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/magic-link/request
POST /api/v1/auth/magic-link/confirm
GET  /api/v1/auth/session
DELETE /api/v1/auth/session
POST /api/v1/auth/api-keys
GET  /api/v1/auth/api-keys
DELETE /api/v1/auth/api-keys/{apiKeyId}
GET  /api/v1/downloads/mods/{modId}/{version}/{fileName}
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 contract 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 deployed
account, magic-link, API-key download, upload, moderation, durable-storage, and live-backend
smoke work is incomplete.

`publishing/workflow.json` is a static contract for the authenticated account,
passwordless magic-link session, API-key download, upload, background
validation-worker, moderation, and publication state machine. It is not a live upload service; `liveBackend` must
remain `false` until backend services are deployed and smoke-tested. Its
`backendRequirements` block lists the concrete services that must be deployed
before account/upload/moderation pages can move from truthful gated copy to
live-service copy.

`publishing/backend-contract.json` is the public backend route and data
contract for those services. The executable slice exists locally in
`backend/server.mjs`, but the tracked JSON remains
`planned-static-contract` until deployment evidence promotes it. 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,
magic-link login uses the same email delivery path, API keys provide the
manager fast-download lane after an account has a verified session, 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, magic-link, API-key,
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. It includes portal-owned AV/deep-inspection gates for
`antivirus_scan`, `file_signature`, and `archive_content_policy` alongside the
framework package checks. Its required check ids come from the Starminer
Modding framework repo and portal backend contract; the site should publish a
fresh copy when framework releases or upload inspection policy update.

`publishing/upload-submission.schema.json` defines the gated authenticated
upload status response for `GET /api/v1/uploads/{submissionId}`. It is the
contract modders will use to read validation checks, review state, hashes,
generated detail-page requirements, 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 published as GitLab release assets, not from
`public/downloads/manager/`. The ecosystem sync job reads GitLab's latest manager
and framework releases, verifies the manager ZIP hash from the latest-release
download permalink, records that GitLab asset URL and expected SHA256, publishes
the tracked framework ZIP, and refreshes game-build compatibility.

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.