HTTP API reference.

EnvironmentStatus   = "available" | "beta" | "experimental" | "planned"
EnvironmentKind     = "runtime" | "mod_platform"   // mod_platform: a layer on top of an existing game
PlatformRules       = "no_restriction" | "restricts_paid" | "unsettled"
                    // what the platform's own rights holder says about paid scripts (ADR-0037): information
                    // for the operator who runs a script there, never a SCRIPT//GO rule; it gates nothing
AdapterState        = "verified" | "written" | "none"   // a real run passed | adapter code, no real run yet | no code yet
IntegrationType     = "cli" | "library" | "addon" | "mod" | "plugin" | "program" | "shim" | "kit"
CapabilitySupport   = "supported" | "partial" | "fallback" | "unavailable"
CompatibilityStatus = "verified" | "failing" | "stale" | "not_tested" | "unsupported"
ReleaseStatus       = "draft" | "validating" | "validation_failed" | "ready" | "published" | "deprecated" | "yanked"
Visibility          = "private" | "unlisted" | "public"
ListingStatus       = "active" | "restricted" | "suspended"
OfferInterval       = "free" | "month" | "year" | "perpetual"
Classification      = "free" | "software_license" | "seller_declared" | "authorized_app_feature"
                    | "undeclared" | "on_hold" | "rejected"   // see "Selling rules" below
LicenseStatus       = "active" | "grace" | "cancelled_active" | "expired" | "revoked" | "refunded"
LicenseSource       = "provider" | "admin" | "creator"   // a payment event | a staff grant | a free grant by the package's creator
GrantRecipientKind  = "account" | "server_key"
PerkInterval        = "month" | "perpetual"            // player perks (ADR-0038, docs/spec/perks.md)
PerkEventKind       = "granted" | "updated" | "removed"
ActivationStatus    = "pending" | "active" | "offline_grace" | "deactivated" | "blocked"
StoreStatus         = "not_connected" | "sandbox" | "checkout_off" | "live" | "needs_attention" | "suspended"
CaseStatus          = "received" | "under_review" | "action_taken" | "no_action" | "escalated" | "appeal_open" | "closed"
Category            = "inventory" | "permissions" | "economy" | "events" | "ui" | "admin" | "framework"
                    | "vehicles" | "housing" | "quests" | "library" | "other"
VerifyFailureReason = "expired" | "revoked" | "refunded" | "environment_not_covered" | "deployment_limit"
                    | "unknown_key" | "deactivated"
KeyReleaseFailureReason = VerifyFailureReason | "unbound" | "server_key_mismatch" | "not_escrowed"
ProtectionTier      = "escrow" | "license" | "none"   // what a server gets in an environment (ADR-0027); "none": the adapter has no licence check
ProtectionState     = "available" | "planned"

// On every Environment (list and detail). The tier follows what the adapter can do, never a selling
// rule: "none" means the adapter has no licence check, so a package runs there without one.
EnvironmentProtection = { tier: ProtectionTier, state: ProtectionState, optIn: boolean, note: string }
// On a published release (Release, PackageVersion). Verify with GET /v1/signing-keys.
ReleaseSignature  = { alg: "ed25519", keyId, payload, signature }
                    // payload: canonical JSON { v: 1, package, version, sha256, size, escrow, publishedAt }
// Public facts of a release's encrypted variant; null when the release is not protected. Never a key.
ReleaseEscrowInfo = { format, cipher, kdf, aad, signerPublicKey, signerKeyId, signerOrigin: "master" | "creator" | null,
                      allowlist: string[], clearFiles: string[], encryptedFiles: string[], watermarked: boolean,
                      builtBy: "cli" | "server", sealedKeyPresent: boolean }

GET  /v1/health                                  → { ok: true, version }
GET  /v1/environments                            → Environment[]   (listed environments only)
GET  /v1/environments/:slug                      → EnvironmentDetail (also for an unlisted one, by direct link)
GET  /v1/packages?q&environment&capability&category&pricing=free|paid&sort=updated|downloads|name&page&pageSize
                                                 → Page<PackageSummary>
GET  /v1/packages/:creator/:name                 → PackageDetail
GET  /v1/packages/:creator/:name/versions/:version/download   → zip stream, header X-Sha256
GET  /v1/creators/:username                      → CreatorProfile
POST /v1/reports  (multipart: fields + evidence[]) → { caseId: "RPT-2026-000123", status: "received" }
GET  /v1/stats                                   → { packages, creators, environmentsVerified }  (real counts only: demo
                                                   data excluded, environmentsVerified counts listed environments)
GET  /v1/compatibility-runs/:runId/evidence/:index → stored evidence file (screenshot or log)
POST /v1/licenses/verify, /v1/licenses/activate, /v1/licenses/key, /v1/licenses/deactivate, GET /v1/licenses/public-key  (see Licensing)

Environment = {
  slug: "standalone" | "love2d" | "godot" | "luanti" | "open77" | string,
  name: string,                       // "LÖVE"
  kind: EnvironmentKind,
  status: EnvironmentStatus,
  platformRules: PlatformRules,       // the platform's own terms on paid scripts; never blocks or conditions a sale
  platformRulesNote: string,          // one factual sentence with its source; "" when there is nothing to report
  luaDialects: string[],              // as sdk/environments.json writes them: "5.1", "5.4", "LuaJIT"
  languages: string[],                // guest languages its host runs: ["lua"], or ["lua", "ts", "js"] on dotnet
  sides: string[],                    // ["server"] or ["server", "client"]
  adapterState: AdapterState,         // read from the repository and verification/reports, never declared
  blockedOn: string,                  // adapterState "written": what the first real run waits for; "" otherwise
  runtimeVersions: string[],          // ["11.5"]
  adapterVersion: string,
  summary: string,
  capabilities: Record<Capability, CapabilitySupport>,
  capabilityNotes: Record<Capability, string>,   // only for capabilities with a caveat
  verifiedPackages: number,
  lastRun: { status: CompatibilityStatus, ranAt: string, runId: string } | null
}
EnvironmentDetail = Environment & {
  setupMarkdown: string, limitations: string[], packages: PackageSummary[],
  integration: { type: IntegrationType, runtime: string, summary: string } | null,   // null: no adapter code yet
  proof: {                            // verified runs from verification/reports: newest version of each package, per runtime
    package: string, version: string, runtime: string, lua: string, adapterVersion: string,
    checksPassed: number, checks: number, ranAt: string
  }[]
}

PackageSummary = {
  id: string,
  identifier: string,                 // "kestrel//inventory-pro"
  creator: { username: string, displayName: string, firstParty: boolean },
  name: string,                       // "inventory-pro" (URL segment)
  resourceName: string,               // "inventory_pro" (manifest `resource`)
  title: string, summary: string, category: Category,
  latestVersion: string | null, license: string,
  environments: { slug: string, status: CompatibilityStatus }[],
  capabilities: string[],
  pricing: { kind: "free" } | { kind: "paid", from: Money, interval: OfferInterval, checkoutEnabled: boolean },
  downloads: number, updatedAt: string, listingStatus: ListingStatus
}
PackageDetail = PackageSummary & {
  description: string, readme: string, repository: string | null,
  manifest: ParsedManifest,           // output of packages/manifest
  versions: { version, status: ReleaseStatus, publishedAt, sha256, size, changelog }[],
  compatibility: {
    environment: string, status: CompatibilityStatus, version: string,
    runtimeVersion: string | null, adapterVersion: string | null,
    ranAt: string | null, runId: string | null, log: string | null,
    evidence: { kind: "screenshot" | "log", url: string }[],
    missingCapability: string | null
  }[],
  offers: Offer[],
  rights: { declaredAt, ownsCode: boolean, targetsProprietaryGame: boolean,
            thirdPartyAssets: { path, source, license }[], dependencies: { name, license }[] } | null,
  seller: { creator: string, provider: "tebex" | "mock" | null } 
}
Offer = { id, packageId, name, interval: OfferInterval, price: Money | null,
          classification: Classification, environments: string[], deployments: number,
          provider: "tebex" | "mock" | null, checkoutEnabled: boolean, checkoutDisabledReason: string | null }
CreatorProfile = { username, displayName, bio, links: string[], joinedAt, firstParty, packages: PackageSummary[] }

GET  /v1/me                                      → { user, creatorProfile | null, roles: Role[] }
POST /v1/me/tokens { name, expiresInDays? }     → 201 { id, token: "sg_pat_...", name, expiresAt }
                                                   (shown once; browser session only, a PAT cannot mint PATs)
GET  /v1/me/tokens                               → { id, name, preview, createdAt, lastUsedAt, expiresAt }[]
DELETE /v1/me/tokens/:id                         → 204
GET  /v1/me/library                              → PackageSummary[]
GET  /v1/me/licenses                             → LicenseSummary[]
GET  /v1/me/licenses/:id                         → LicenseDetail
POST /v1/me/licenses/:id/reveal                  → { key }   the key issued with the license, shown once (then 409)
POST /v1/me/licenses/:id/rotate                  → { key }   new key, shown once; the old key stops working
POST /v1/me/licenses/:id/deployments  { name, environment }  → 201 { activation, deploymentToken }
DELETE /v1/me/licenses/:id/deployments/:activationId         → 204
GET  /v1/me/notices                              → Notice[]
POST /v1/me/notices/:id/appeal { statement }     → Notice
POST /v1/checkout { offerId }                    → 201 { checkoutId, redirectUrl }
       409 offer_free | already_licensed | checkout_disabled (message = checkoutDisabledReason), 502 provider_error
GET  /v1/checkout/:checkoutId                    → { checkoutId, status: "pending" | "completed" | "failed" | "expired",
                                                     licenseId | null, offerId, createdAt }

LicenseSummary = { id, package: PackageSummary,
                   offer: Offer | null,           // null for a license granted by the creator: nothing was sold
                   origin: { source: LicenseSource,
                             grantedBy: string | null,              // creator grants: the creator's username
                             recipient: GrantRecipientKind | null },// creator grants: an account, or a server key
                   status: LicenseStatus,
                   currentPeriodEnd: string | null, deploymentsUsed: number, deploymentsAllowed: number }
LicenseDetail = LicenseSummary & {
  keyPreview: string,                 // "sg_live_…a91c"
  environments: string[],
  activations: { id, name, environment, adapterVersion, lastVerifiedAt, status: ActivationStatus, offlineGraceUntil }[],
  history: { at, event, source: "provider" | "user" | "admin" | "system" | "creator", reference }[],
                                      // "creator": the creator who granted the license (the grant, its revocation)
  keyRevealAvailable: boolean,        // POST .../reveal can still show the issued key
  seller: { creator: string, provider: "tebex" | "mock" | null },
  revokedReason: string | null,
  revokedBy: "creator" | "staff" | "provider" | null,   // the granting creator, staff, or a lost payment dispute
  graceUntil: string | null
}

POST /v1/creator/profile { username, displayName, bio }       → 201 { username, displayName, ... }
GET  /v1/creator/packages                        → PackageSummary[] (incl. private/draft)
POST /v1/creator/packages { name, title, summary, category, license, visibility, repository }  → 201 CreatorPackageDetail
GET  /v1/creator/packages/:name                  → CreatorPackageDetail
PATCH /v1/creator/packages/:name                 → CreatorPackageDetail
POST /v1/creator/packages/:name/releases  (multipart: archive=zip)  → Release (status "validating")
     + escrow=true [allowlist=<globs, one per line or comma-separated>]   → Release (status "ready" | "validation_failed")
       the master builds the encrypted bundle from the plain archive, signs escrow.json with the creator's
       master-held key, validates in the request (no worker) and keeps no plaintext
     + archive=<escrow bundle> contentKey=<base64, 32 bytes>               → Release (status "ready" | "validation_failed")
       a bundle built by `scriptgo publish --escrow`: the master checks the signature, opens it in memory with
       the key, validates the plaintext, stores the bundle and seals the key
       422 escrow_key_required | escrow_key_invalid | escrow_key_mismatch | escrow_bundle_invalid |
           escrow_signature_invalid | escrow_package_mismatch | escrow_version_mismatch |
           escrow_nothing_to_encrypt | escrow_reserved_file | invalid_allowlist | signer_retired
GET  /v1/creator/packages/:name/key-activity?days=30  → KeyActivity   (counts from the key endpoint's log)
GET  /v1/creator/releases/:id                    → Release with validation report
POST /v1/creator/releases/:id/rights { ownsCode, targetsProprietaryGame, thirdPartyAssets[] }
POST /v1/creator/releases/:id/publish            → Release (409 publish_blocked, details.blockers: string[])
                                                 (publishing puts the package's paid offers on the rights declaration of the new release:
                                                  they can be bought at once, with no review, whatever environments the release lists)
POST /v1/creator/releases/:id/deprecate { reason } → Release
POST /v1/creator/releases/:id/yank { reason }    → Release   (its download then answers 410)
POST /v1/creator/packages/:name/offers { name, interval, price, environments, deployments, providerProductId, provider? }
                                                 → 201 Offer   (provider defaults to the creator's Tebex store, else mock)
                                                 (no environment refuses a paid offer; the offer is `undeclared`, with no purchase path,
                                                  until a published release carries the creator's rights declaration)
DELETE /v1/creator/offers/:id                    → 204   (offer withdrawn; licenses already sold are unaffected)
GET  /v1/creator/stores                          → Store[]
POST /v1/creator/stores { provider: "mock" | "tebex", credentials }  → Store
POST /v1/creator/stores/:id/test-event           → { delivered: boolean, status: number }  (mock store only)
GET  /v1/creator/packages/:name/grants           → GrantList
POST /v1/creator/packages/:name/grants { to | serverKey, environments?, environment?, deploymentName?,
                                         deployments?, expiresInDays?, note? }
                                                 → 201 { grant: GrantRow, deploymentToken: string | null }
       400 (neither or both of to/serverKey; serverKey without environment; a malformed key)
       404 recipient_not_found   409 grant_blocked (details.reason) | package_private | already_granted
       422 grant_to_self | unknown_environment | environment_not_declared | environment_unprotected
       429 grant_limit
POST /v1/creator/grants/:id/revoke { reason }    → GrantRow   (404 for a license that was not granted by you)
GET  /v1/creator/customers                       → { license, customer: { username }, offer: Offer | null, source: LicenseSource }[]
                                                 (a grant to a server key is held by the creator: it is in GrantList, not here)
GET  /v1/creator/analytics?days=30&package=      → { downloads: Series, activations: Series, verifications: Series }

KeyActivity = { days, released, refused, refusalsByReason: Record<KeyReleaseFailureReason, number>,
                deployments,            // distinct deployments that received a key in the window
                lastReleasedAt, lastRefusedAt }

// POST body. Exactly one of `to` and `serverKey`.
{ to?: string,             // the recipient's account id (GET /v1/me → user.id; shown in Dashboard → Settings and by
                           // `scriptgo login`), or a creator username. Never an e-mail address.
  serverKey?: string,      // the server's X25519 public key, base64url, 43 characters (`scriptgo escrow identity`)
  environments?: string[], // account grants: environments covered; default: what the latest release declares
  environment?: string,    // server-key grants: the environment of that server (required)
  deploymentName?: string, // server-key grants: default "server"
  deployments?: number,    // account grants: 1..100, default 1. A server-key grant is always 1
  expiresInDays?: number | null,   // 1..3650; null (default) = until revoked
  note?: string }          // the creator's own note, up to 200 characters; not shown to the holder

GrantRow  = { id,                      // the license id
              package: "creator//name", status: LicenseStatus, createdAt, expiresAt, revokedAt, revokedReason,
              recipient: { kind: GrantRecipientKind,
                           name,                       // account: the holder's display name; server_key: the deployment's name
                           serverKeyFingerprint },     // server_key: fingerprint of the bound key, else null
              environments: string[], deploymentsUsed, deploymentsAllowed, lastKeyReleaseAt, note }
GrantList = { grants: GrantRow[], canGrant: boolean, blockedCode: string | null, blockedReason: string | null,
              perDay: number, grantedToday: number }

Release = { id, packageName, version, status: ReleaseStatus, createdAt, sha256, size,
            checks: { stage: "archive" | "manifest" | "integrity" | "static" | "unit" | "environment" | "rights",
                      name: string, status: "pending" | "running" | "passed" | "failed" | "skipped",
                      required: boolean, durationMs: number | null, message: string | null, log: string | null }[],
            blockers: string[] }
CreatorPackageDetail = PackageSummary & { description, repository, releases: Release[], offers: Offer[] }
Store = { id, provider, status: StoreStatus,
          suspended: boolean, suspendedReason: string | null,   // suspended by staff after a report (ADR-0037); no staff approval exists
          checkoutEnabled: boolean, checkoutDisabledReason: string | null,
          webhookUrl: string,                 // where to point the provider's webhooks
          webhook: { lastEventAt, deliveries24h, failures24h },
          products: { providerProductId, offerId, syncStatus: "synced" | "unverified" | "error" }[],
          recentDeliveries: { eventId, type, status, receivedAt, error }[], createdAt }

POST /v1/licenses/activate   { licenseKey, package, environment, deploymentName, adapterVersion, serverPublicKey? }
                             → 201 { activationId, deploymentToken }
                               404 unknown_key, 409 deployment_limit | deployment_exists | <license status, e.g. expired>,
                               422 environment_not_covered   (activating the same name again rotates its token)
                               // serverPublicKey: the server's X25519 public key (base64url) for escrow binding
POST /v1/licenses/verify     { licenseKey | deploymentToken, package, environment, adapterVersion }
                             → 200 { valid, reason: VerifyFailureReason | null, status: LicenseStatus | null,
                                     activationStatus: ActivationStatus | null, expiresAt, offlineGraceUntil,
                                     environments: string[], token: string }   // ed25519-signed, short-lived
POST /v1/licenses/key        { licenseKey | deploymentToken, package, version?, environment, adapterVersion, serverPublicKey? }
                             → 200 { valid, reason: KeyReleaseFailureReason | null, final: boolean,
                                     wrappedKey: {epk,nonce,wrapped} | null,
                                     aad, signerPublicKey, deliveryWatermark, offlineGraceUntil, expiresAt }
                               // final: true on revoked | refunded | expired | deactivated (the right to run is
                               // over: a loader stops at once); false otherwise (the offline grace applies).
                               // escrow: content key wrapped to the bound server. Gated like verify, plus binding +
                               // escrowed release. Reasons add unbound, server_key_mismatch, not_escrowed.
                               // Cache-Control: no-store. 4xx/5xx → loader offline grace. 300/min per IP and
                               // 60/min per key or token (429). Every answer is logged with its reason.
                               // See docs/spec/escrow.md.
POST /v1/licenses/deactivate { licenseKey, activationId }  → { ok: true }
GET  /v1/licenses/:id        (owner session only)          → LicenseDetail
GET  /v1/licenses/public-key                               → { alg: "ed25519", publicKey, kid }
(activate and deactivate: 30/min per IP)

GET  /v1/signing-keys                                      → { keys: { keyId, alg: "ed25519", publicKey, status: "current" | "retired" }[] }
                                                             // the registry's RELEASE-signing keys (raw public key, base64url);
                                                             // not the license-token key above
GET  /v1/creators/:username/signing-keys                   → { keys: { keyId, alg, publicKey, origin: "master" | "creator", createdAt, retiredAt }[] }
                                                             // the keys that sign this creator's escrow manifests
POST /v1/me/licenses/:id/deployments/:activationId/reset-server-key   (owner; 10/min)
                             → 200 Activation   404 not_found, 409 not_bound, 429 reset_limit (3 per deployment per 24 h)
                               // unbinds the server key; the next key request binds the server that makes it. Audited.

POST /v1/webhooks/tebex            raw body, header X-Signature, platform secret (TEBEX_WEBHOOK_SECRET)
POST /v1/webhooks/tebex/:storeId   same, verified with that store's own webhook secret (Store.webhookUrl)
POST /v1/webhooks/mock             raw body, header X-SG-Signature (HMAC-SHA256 of the raw body, hex)

# The operator (session or PAT; requires a creator profile)
GET    /v1/creator/perks                       → Perk[]
POST   /v1/creator/perks                       CreatePerkBody → 201 Perk
POST   /v1/creator/perks/:id/declare           PerkRights → Perk
DELETE /v1/creator/perks/:id                   → 204 (no longer sold; holders keep it)
GET    /v1/creator/perk-holders[?perk=key]     → PerkHolder[]
GET    /v1/creator/server-links                → ServerLink[]
POST   /v1/creator/server-links                { name } → 201 { link: ServerLink, token }   (token shown once)
POST   /v1/creator/server-links/:id/revoke     → ServerLink

# The game server (Authorization: Bearer sg_srv_…; 401 unknown_server_link without a valid link)
POST   /v1/perks/check                         { player, environment?, adapterVersion? } → { player, perks: HeldPerk[], serverTime }
GET    /v1/perks/events[?after=seq][&limit=n]  → { events: PerkEvent[], cursor, more, serverTime }
POST   /v1/perks/events/ack                    { upTo } → { acked }
GET    /v1/perks/catalog                       → PerkCatalogEntry[]
POST   /v1/perks/purchase-link                 { player, perk } → 201 { url, expiresAt }

# The player who follows a purchase link (no account; the signed link is the authorisation)
GET    /v1/perks/purchase?token=…              → PerkPurchaseInfo        404 invalid_link, 410 link_expired
POST   /v1/perks/purchase/checkout             { token } → 201 { checkoutId, redirectUrl }   409 checkout_disabled
GET    /v1/perks/checkouts/:id                 → { checkoutId, status, perk, operator, player }

# Staff, after a report
GET    /v1/admin/perks[?operator=username]     → StaffPerk[]   (on hold or withdrawn; with operator: all of theirs)
POST   /v1/admin/perks/:id/decision            { decision: "on_hold" | "rejected" | "lift", reason, caseId? } → StaffPerk

Perk        = { id, key, name, description, interval: PerkInterval, price: Money, provider, providerProductId,
                classification: Classification, classificationReason, declared, active,
                purchasable, notPurchasableReason, holders, createdAt }
CreatePerkBody = { key, name, description?, interval, price: Money, provider?, providerProductId?,
                   rights?: { ownsCode, targetsProprietaryGame } }
ServerLink  = { id, name, tokenPreview, environment, adapterVersion, lastSeenAt, pendingEvents, revoked, createdAt }
PerkHolder  = { id, perkKey, perkName, player, status: LicenseStatus, has, currentPeriodEnd, cancelledAt, refundedAt,
                revokedReason, disputed, provider, paymentRef, subscriptionRef, serverLinkName, createdAt }
HeldPerk    = { key, status: LicenseStatus, expiresAt: Timestamp | null, offlineGraceUntil: Timestamp }
PerkEvent   = { seq, kind: PerkEventKind, perk, player, reason, status: LicenseStatus,
                expiresAt: Timestamp | null, offlineGraceUntil: Timestamp | null, at: Timestamp }

GET  /v1/admin/review/offers?status=on_hold|all&package=creator//name  → ReviewOffer[]
                                       (on_hold, the default: the offers staff put on hold after a report; nothing
                                        enters this list by itself. package: the offers of one package, any state)
POST /v1/admin/review/offers/:id/decision { classification: "on_hold" | "rejected" | "software_license" | "seller_declared"
                                            | "authorized_app_feature" | "free", reason, caseId? }      → ReviewOffer
                                       (on_hold, rejected: no purchase path; the creator gets a notice and can appeal;
                                        caseId names the report, 422 unknown_case. software_license, seller_declared:
                                        lift a hold, back on the seller's declaration. Audited)
GET  /v1/admin/review/releases?status=open|all         → ReviewRelease[]
POST /v1/admin/review/releases/:reviewId/decision { decision: "approve" | "restrict" | "reinstate", reason }
                                                       → ReviewRelease
GET  /v1/admin/reports?status                          → CaseSummary[]
GET  /v1/admin/reports/:id                             → CaseDetail   (:id = report id or case id RPT-YYYY-NNNNNN)
POST /v1/admin/reports/:id/review                      → CaseDetail   (moves it to under_review)
POST /v1/admin/reports/:id/decision    { action: "no_action" | "restrict_release" | "restrict_sales" | "suspend_listing"
                                                 | "suspend_store",
                                         reasons: string, escalate: boolean }  → CaseDetail
                                       (suspend_store: every store of the reported package's creator; 422 no_store when
                                        there is none to suspend. Like every decision but no_action: a notice, an appeal
                                        window, and a reversal on appeal undoes it)
GET  /v1/admin/reports/:id/evidence/:evidenceId        → file (attachment, nosniff)
POST /v1/admin/appeals/:id/decision { outcome: "upheld" | "reversed", reasons } → CaseDetail
                                       409 same_reviewer when the caller took the decision under appeal
                                       (CaseDetail.appeals[].decisionId → decisions[].decidedBy)
GET  /v1/admin/audit?subject=<type>:<id>&actor&action&limit               → AuditEntry[]
GET  /v1/admin/payment-events?status&provider&limit    (admin) → PaymentEventRow[]
GET  /v1/admin/errors?limit                            (admin) → OperationalError[]
POST /v1/admin/compatibility-runs      (CI ingest token, or admin session) CompatibilityRun
                                       → 201 { id, releaseId, created: true }, 200 on replay of the same runId
POST /v1/admin/licenses/grant          (admin) { userId, offerId, reason } → 201 LicenseDetail (audited grant)
POST /v1/admin/licenses/:id/revoke     (admin) { reason }                  → { ok: true }
GET  /v1/admin/stores                  (admin) → (Store & { creator })[]
POST /v1/admin/stores/:id/reinstate    (admin) { reason }                  → Store & { creator }
                                       (lifts a suspension without an appeal; audited, the seller is told;
                                        409 not_suspended. No route suspends or approves a store: a
                                        suspension is the `suspend_store` decision on a report)
POST /v1/admin/ingest-tokens           (admin, browser session) { name }  → 201 { id, token: "sg_adm_..." } (shown once)
GET  /v1/admin/ingest-tokens           (admin) → { id, name, preview, createdAt, lastUsedAt }[]
DELETE /v1/admin/ingest-tokens/:id     (admin) → 204
GET  /v1/admin/users?email             (admin) → { id, email, name, createdAt, roles, creator }[]
POST /v1/admin/roles                   (admin, browser session) { userId, role: "admin" | "moderator", grant, reason }
                                       → { userId, roles }   (409 last_admin)

CompatibilityRun = { runId, package: "scriptgo//event-bus" | "sg_eventbus", version, environment, status: "verified" | "failing",
                     runtimeVersion, adapterVersion, luaVersion, ranAt, durationMs, log, checks: { name, status, message }[],
                     evidence: { kind, path }[] }

POST /v1/creator/packages/:name/releases   (multipart, unchanged) — a release whose manifest declares assets is
                                       streamed to storage (413 archive_too_large above the platform's cap, read from
                                       Content-Length first), inspected entry by entry (data only, sizes, delivery rules)
                                       and refused with every inspection error in its checks; a buyer's fingerprinted
                                       copy is refused (asset_fingerprinted). Release.assets carries the report.
POST /v1/creator/releases/:id/rights { ownsCode, targetsProprietaryGame, thirdPartyAssets, assetRights }
                                       assetRights: "original" | "game_edits" | "game_extracted"; publishing a release
                                       with assets needs it (a blocker, not a review).
GET  /v1/packages/:creator/:name/versions/:version/download
                                       for a release with assets: the caller's own copy. Licence holder (session or
                                       token), X-ScriptGo-Deployment-Token or X-ScriptGo-License-Key, otherwise 403
                                       license_required. The creator and staff get a copy fingerprinted to their own
                                       account; staff may ask ?variant=original (audited). Headers: X-Sha256 (the copy),
                                       X-ScriptGo-Artifact: plain, X-ScriptGo-Fingerprint: <marker>, the copy's signature
                                       (payload adds release: { sha256 } and fingerprint), Cache-Control: private, no-store.
POST /v1/creator/assets/lookup  { sha256 } | { record }   → AssetLookupResult   (own packages; account = null)
POST /v1/assets/reports         CreateAssetReportBody     → 201 AssetReportRow  (signed in; goodFaith and accuracy
                                       statements required; opens a compliance case)
GET  /v1/admin/assets/reports?status=open|actioned|rejected|all  (staff) → AssetReportRow[]
GET  /v1/admin/assets/reports/:id                         (staff) → AssetReportRow
POST /v1/admin/assets/lookup    { sha256 } | { record }   (staff) → AssetLookupResult   (audited)
POST /v1/admin/assets/reports/:id/resolve { deliveryId }  (staff) → AssetReportRow
POST /v1/admin/assets/reports/:id/action  AssetReportActionBody (staff) → AssetReportRow
                                       revoke_license / deactivate_deployment need a resolved copy (422 not_resolved);
                                       restrict_release decides the linked case (notice and appeal); takedown_notice
                                       records a notice a person sent to a third-party host; reject closes it.

GET  /v1/admin/escrow/key-events?limit=&outcome=released|refused&reason=&license=   (staff)
                             → KeyEventRow[]   // every answer of POST /v1/licenses/key, newest first
POST /v1/admin/escrow/marker-lookup { marker, reason }                              (staff; 30/min)
                             → MarkerLookupResult   // audited as escrow.marker_lookup with the reason

KeyEventRow = { id, at, outcome: "released" | "refused", reason: string | null, packageRef, package: string | null,
                version, environment, licenseId, deploymentId, deploymentName, serverKeyFingerprint }
// marker: the bare token, the .scriptgo-escrow file a loader stamps into a decrypted copy, or an escrow.json
MarkerLookupResult = { kind: "delivery" | "release" | "unknown", marker,
                       release: { package, version } | null,
                       license: { id, status, holderUserId, holderName, holderEmail } | null,
                       deployment: { id, name, environment, status, serverKeyFingerprint } | null,
                       deliveries: { count, firstAt, lastAt, recent: Timestamp[] } }

GET /v1/creator/stores/:id/readiness   (creator, own store) → StoreReadiness
                                       404 not_found (not your store), 409 sandbox_store (a mock store)
GET /v1/admin/commerce/readiness       (admin) → CommerceReadiness

ReadinessCheck    = { id: string, label: string, status: "ok" | "missing" | "warning" | "blocked",
                      detail: string, fix: string | null }
ReadinessSummary  = { ready: boolean, remaining: string[] }
StoreReadiness    = { storeId, provider: "tebex", creator: string, webhookUrl: string, suspended: boolean,
                      checks: ReadinessCheck[], summary: ReadinessSummary, generatedAt: Timestamp }
CommerceReadiness = { platform: { checks: ReadinessCheck[], summary: ReadinessSummary },
                      stores: StoreReadiness[], generatedAt: Timestamp }