type Timestamp = string   // ISO 8601 UTC, "2026-07-31T16:57:28.186Z"; hiányzó = "0001-01-01T00:00:00Z"
type Path = string        // szerver-relatív, "/file/…" vagy "/api/image/7"; a katalógus bázis-URL-je elé

interface Service {
  engine: "warp_engine"
  version: string                 // motorverzió, ugyanaz, mint a WarpEngine-Version fejléc
  api: {
    version: number               // alakverzió, minden boríték `api` mezője (2)
    catalog: {
      pageSize: number            // per_page, ha az olvasó nem mondja
      maxPageSize: number         // a legtöbb, amit egy olvasó kérhet
    }
  }
  catalog: {
    gated: boolean                // kívánhat-e bármelyik itteni cím jogosultságot
  }
  auth: null | {
    schemes: ["bearer"]
    device: {                     // device authorization grant, RFC 8628
      authorizeUrl: string        // ide POST a bejelentkezés indításához
      tokenUrl: string            // ide POST a token pollozásához
      revokeUrl: string | null    // ide DELETE a kijelentkezéshez
      verificationUrl: string     // ahová a személy beírja a user code-ot
      interval: number            // másodperc két poll között
    }
  }
}

interface SoftwareQuery {
  page?: number                   // 1-től; hiányzik = minden
  per_page?: number               // maxPageSize a plafon
  status?: string                 // vesszővel elválasztott státuszkulcsok
  platform?: string               // egy platformnév
  category?: string               // egy kategóriakulcs
  q?: string                      // címre és névre illesztve
  owner_id?: number               // egy kiadó szoftverei
  sort?: "title" | "updated" | "newest"
}

interface Catalog {
  api: number                     // 2; 0.13 előtti motoron hiányzik (sima lista)
  page: number
  perPage: number
  total: number                   // a szűrőkre illő szoftverek, minden lapon
  totalPages: number
  nextPage: number | null         // null-ig követni
  softwares: Entry[]
}

interface Entry {
  software: Software
  releases: Release[]             // legújabb elöl
  latestRelease: Release | null   // a legújabb, amelynek verziója nem "dev-…"
  webPlayableRelease: Release | null   // a latestRelease, ha van "html" assetje
  totalDownloads: number
  access: Access                  // 0.5-től, nyitott szabályzat alatt is ott van
}

interface Software {
  id: number
  ownerId: number
  name: string                    // a cím kulcsa
  title: string
  author: string
  desc: string                    // rövid leírás
  story: string                   // hosszú leírás
  license: string
  platform: string                // slug: "c64", "tic80", "godot", …; címkék az /api/builds-ben
  status: string                  // kulcs az /api/software/vocabulary-ból
  category: string | null         // 0.12-től; kulcs az /api/software/vocabulary-ból
  highlighted: boolean
  imageUrl: Path | null           // alapértelmezett borító
  images: { url: Path, isDefault: boolean, position: number }[]
  externalLinks: { id: number, softwareId: number, label: string, url: string }[]
  platformLinks: { name: string, url: string }[]
  createdAt: Timestamp
  updatedAt: Timestamp
  deletedAt: Timestamp | null
}

interface Release {
  id: number
  softwareId: number
  version: string                 // "1.0.0", vagy "dev-1.0.0-branch" a fő ágon kívül
  assets: Asset[]                 // ebből telepít egy áruház
  cartridgePath: Path | ""        // örökölt lapos mezők, ugyanazok az útvonalak, mint a megfelelő assetek
  sourcePath: Path | ""
  htmlFolderPath: Path | ""
  docsFolderPath: Path | ""
  downloadCount: number
  createdAt: Timestamp
  updatedAt: Timestamp
  deletedAt: Timestamp | null
}

interface Asset {
  kind: "html" | "win_x86" | "win_x64" | "linux_x64" | "linux_arm64"
      | "mac_universal" | "mac_x64" | "mac_arm64" | "cartridge" | "source" | "docs"
  path: Path                      // ezt add a GET /api/download?path= -nak
}

interface Access {
  gated: boolean                  // ez a cím kívánhat jogosultságot
  entitled: boolean | null        // true: letöltheti; false: nem; null: anonim hívó
  price: { amountCents: number, currency: string } | null
  purchaseUrl: string | null
  webUrl: string | null
}

interface Facets {
  api: number
  total: number                   // minden szűrőre illő
  statuses: Record<string, number>     // státuszkulcs → darab
  platforms: Record<string, number>    // platform → darab
  categories: Record<string, number>   // kategóriakulcs → darab; "" a kategória nélkülieknek
}

interface Vocabulary {
  api: number
  statuses: {
    key: string                   // az érték, amit egy szoftver status-a hordoz
    label: string
    position: number
    defaultVisible: boolean       // saját preferencia nélküli áruház ezt listázza
    badge: string | null          // stílusjavaslat
  }[]
  categories: {
    key: string                   // az érték, amit egy szoftver category-ja hordoz
    label: string
    position: number
    count: number                 // hány látható szoftver viseli
  }[]
}

type Highlighted = Entry | null

interface Builds {
  platforms: Record<string, {     // platform slug →
    label: string                 // "TIC-80", "Plus/4", "LÖVE"
    kinds: Asset["kind"][]        // mit hordozhat egy kiadás ezen a platformon
  }>
  allKinds: Asset["kind"][]
}

interface SoftwareBuilds {
  platform: string
  expected: Asset["kind"][]
  releases: Record<string, {      // verzió →
    actual: Asset["kind"][]
    missing: Asset["kind"][]
  }>
}

interface DeviceRequest {
  client_name?: string            // hogyan hívják ezt az eszközt a személy fiókjában
}

interface DeviceCode {
  deviceCode: string              // ezzel pollozz
  userCode: string                // ezt mutasd meg, "WXYZ-1234"
  verificationUrl: string         // ide küldd a személyt
  interval: number                // másodperc két poll között; a leíróé fölött nyer
  expiresIn: number               // másodperc
}

interface TokenRequest {
  device_code: string
}

interface TokenPoll {
  state: "pending" | "approved" | "denied" | "expired"
  token?: string                  // pontosan egyszer, azon a pollon, amely jóváhagyva találja
}