Coverage / app/src/main/java/io/oxygenhub/android/api/Models.kt 88.0%

package io.oxygenhub.android.api

import kotlinx.serialization.SerialName

import kotlinx.serialization.Serializable

// The hub's JSON, by hand from oxygenhub's crates/hub-api/src/lib.rs (and

// the device flow's answers in crates/hub/src/api/device.rs). Field names

// are the hub's own, snake case; times are milliseconds since the epoch.

// Every field has a default, so an added or missing field never breaks the

// app: the hub's types may still change before 1.0.

/** `GET /api/v1/user`. */

@Serializable

data class User(

    val username: String,

    @SerialName("display_name") val displayName: String = "",

    @SerialName("is_admin") val isAdmin: Boolean = false,

    val keys: List<String> = emptyList(),

    @SerialName("created_ms") val createdMs: Long = 0,

) {

    /** The name to greet: the display name, or the username without one. */

    val shownName: String get() = displayName.ifBlank { username }

}

@Serializable

enum class Visibility {

    @SerialName("public") Public,

    @SerialName("internal") Internal,

    @SerialName("private") Private,

}

/** A repository as `GET /api/v1/repos` lists it. */

@Serializable

data class Repository(

    val owner: String,

    val name: String,

    val description: String = "",

    @SerialName("default_bookmark") val defaultBookmark: String = "main",

    val visibility: Visibility = Visibility.Public,

    @SerialName("created_ms") val createdMs: Long = 0,

    @SerialName("updated_ms") val updatedMs: Long = 0,

    @SerialName("clone_url") val cloneUrl: String = "",

) {

    val slug: String get() = "$owner/$name"

}

@Serializable

data class Label(

    val name: String,

    /** `#rrggbb`. */

    val colour: String = "",

    val description: String = "",

)

/** `GET /api/v1/repos/{owner}/{name}/issues`. */

@Serializable

data class Issue(

    val number: Long,

    val title: String,

    val body: String = "",

    val author: String = "",

    /** `open` or `closed`. */

    val state: String = "open",

    /** Why it closed: `completed`, `not_planned`, … (empty while open). */

    val reason: String = "",

    val labels: List<Label> = emptyList(),

    val assignees: List<String> = emptyList(),

    val milestone: String? = null,

    val comments: Long = 0,

    val locked: Boolean = false,

    val pinned: Boolean = false,

    @SerialName("created_ms") val createdMs: Long = 0,

    @SerialName("updated_ms") val updatedMs: Long = 0,

    @SerialName("closed_ms") val closedMs: Long? = null,

    val url: String = "",

) {

    val isOpen: Boolean get() = state == "open"

}

/** A release of a repository: its tag, notes and files. */

@Serializable

data class Release(

    val tag: String,

    val title: String = "",

    val notes: String = "",

    val prerelease: Boolean = false,

    val latest: Boolean = false,

    val author: String = "",

    val signer: String? = null,

    val assets: List<ReleaseAsset> = emptyList(),

    @SerialName("created_ms") val createdMs: Long = 0,

    val url: String = "",

)

@Serializable

data class ReleaseAsset(val name: String, val size: Long = 0, val hash: String = "", val downloads: Long = 0, val url: String = "")

/** An issue or proposal search found (`GET /search?q=`). */

@Serializable

data class SearchHit(

    /** `issue` or `proposal`. */

    val kind: String = "issue",

    val repository: String = "",

    val number: Long = 0,

    val title: String = "",

    val snippet: String = "",

) {

    val owner: String get() = repository.substringBefore('/')

    val name: String get() = repository.substringAfter('/')

}

/** A Flow run of a repository's pipeline (#5). */

@Serializable

data class FlowRun(

    val number: Long,

    val bookmark: String = "",

    /** `queued`, `running`, `passed`, `failed`, `error` or `cancelled`. */

    val status: String = "queued",

    /** `push`, `manual`, `schedule`, `proposal` or `rerun:N`. */

    val trigger: String = "",

    val actor: String = "",

    val error: String = "",

    @SerialName("created_ms") val createdMs: Long = 0,

    @SerialName("finished_ms") val finishedMs: Long? = null,

    val url: String = "",

    @SerialName("queue_position") val queuePosition: Long? = null,

    val jobs: List<FlowJob> = emptyList(),

) {

    val live: Boolean get() = status == "queued" || status == "running"

}

/** A job of a run. */

@Serializable

data class FlowJob(

    val name: String,

    val status: String = "queued",

    @SerialName("depends_on") val dependsOn: List<String> = emptyList(),

    val runner: String = "",

    @SerialName("exit_code") val exitCode: Long? = null,

    val error: String = "",

    @SerialName("started_ms") val startedMs: Long? = null,

    @SerialName("finished_ms") val finishedMs: Long? = null,

    @SerialName("log_lines") val logLines: Long = 0,

    val waiting: String = "",

    /** Its approval gate: `waiting` while it waits for a person, `approved` or `rejected` after (OxygenHub 0.9.10). */

    val approval: String = "",

) {

    val live: Boolean get() = status == "queued" || status == "running"

    /** Queued and waiting for someone to approve or reject it (#5). */

    val waitsForPerson: Boolean get() = status == "queued" && approval == "waiting"

    /** How long it ran, or has been running, in seconds. */

    fun seconds(now: Long = System.currentTimeMillis()): Long? = startedMs?.let { ((finishedMs ?: now) - it) / 1000 }

}

/** A line of a job's log: `stdout`, `stderr` or `flow` (the runner's own). */

@Serializable

data class LogLine(val seq: Long, val t: Long = 0, val stream: String = "stdout", val text: String = "")

/** A project board's summary (`GET /projects/{owner}`). */

@Serializable

data class Project(

    val owner: String,

    val number: Long,

    val title: String = "",

    val description: String = "",

    val public: Boolean = true,

    val closed: Boolean = false,

    @SerialName("updated_ms") val updatedMs: Long = 0,

    val url: String = "",

)

/** A card on a board: an issue, a proposal or a note. */

@Serializable

data class ProjectCard(

    val id: Long,

    /** `issue`, `proposal` or `note`. */

    val kind: String = "note",

    /** `owner/name#N`; empty for a note. */

    val reference: String = "",

    val title: String = "",

    val state: String = "",

    val labels: List<String> = emptyList(),

    val assignees: List<String> = emptyList(),

) {

    /** The repository and number a card refers to, or null for a note. */

    val target: Triple<String, String, Long>? get() {

        val slug = reference.substringBefore('#', "")

        val n = reference.substringAfter('#', "").toLongOrNull() ?: return null

        val (owner, name) = slug.split('/').takeIf { it.size == 2 } ?: return null

        return Triple(owner, name, n)

    }

}

@Serializable

data class ProjectColumn(val id: Long, val name: String, val cards: List<ProjectCard> = emptyList())

/** A board, its columns in order (`GET /projects/{owner}/{n}`). */

@Serializable

data class Board(val project: Project, val columns: List<ProjectColumn> = emptyList())

/** A comment on an issue or proposal. */

@Serializable

data class Comment(

    val id: Long = 0,

    val author: String = "",

    val body: String = "",

    @SerialName("created_ms") val createdMs: Long = 0,

)

/** Which issues to list: the hub's `?state=`. */

enum class IssueState(val query: String) { Open("open"), Closed("closed"), All("all") }

/**

 * A proposal (`GET /api/v1/repos/{owner}/{name}/proposals`, `…/proposals/{n}`):

 * changes asking to join a target bookmark. The hub decides whether it may

 * land, and says why not in [blockers], in its own words.

 */

@Serializable

data class Proposal(

    val number: Long,

    val title: String,

    val body: String = "",

    val author: String = "",

    /** `draft`, `open`, `landed` or `closed`. */

    val state: String = "open",

    /** The bookmark it lands on. */

    val target: String = "main",

    /** The changes it adds, in dependency order, newest last. */

    val changes: List<ProposalChange> = emptyList(),

    val conflicted: Boolean = false,

    val approvals: List<Approval> = emptyList(),

    val landable: Boolean = false,

    val blockers: List<String> = emptyList(),

    @SerialName("created_ms") val createdMs: Long = 0,

    @SerialName("updated_ms") val updatedMs: Long = 0,

    val url: String = "",

    val landed: Landed? = null,

    /** Who set it to land by itself when its checks pass, while set. */

    @SerialName("auto_land") val autoLand: String? = null,

    @SerialName("requested_reviewers") val requestedReviewers: List<String> = emptyList(),

    val labels: List<Label> = emptyList(),

) {

    val isOpen: Boolean get() = state == "open" || state == "draft"

    val isDraft: Boolean get() = state == "draft"

}

/** `GET /api/v1/user/proposals`: the proposals to act on, as the hub's dashboard lists them. */

@Serializable

data class UserProposals(

    /** Open ones by others in the caller's repositories, not yet reviewed by them. */

    val review: List<ProposalBrief> = emptyList(),

    /** The caller's own open ones and drafts. */

    val authored: List<ProposalBrief> = emptyList(),

    /** Asked for with `landable=true`: open ones the caller can land now. */

    val landable: List<ProposalBrief> = emptyList(),

)

/**

 * `GET /api/v1/user/sky` (#23): what the hub's dashboard backdrop draws, the

 * caller's repositories and their events of the last 30 days.

 */

@Serializable

data class UserSky(

    /** The hub's clock (ms), to age the events by. */

    val now: Long = 0,

    /** `owner/name` of each. */

    val repos: List<String> = emptyList(),

    /** `[repo, kind, at_ms, n]`: an index into [repos]; kind 0 a push of n changes, 1 a proposal event, 2 an issue event, 3 a release, 4 a Flow run. */

    val events: List<List<Long>> = emptyList(),

)

/** An organisation (`GET /orgs/{name}`). */

@Serializable

data class Organisation(

    val name: String,

    @SerialName("display_name") val displayName: String = "",

    val description: String = "",

    val members: List<String> = emptyList(),

)

/** An account or an organisation, as its page shows it. */

sealed interface Owner {

    val name: String

    val shownName: String

    data class Person(val user: User) : Owner {

        override val name get() = user.username

        override val shownName get() = user.shownName

    }

    data class Org(val org: Organisation) : Owner {

        override val name get() = org.name

        override val shownName get() = org.displayName.ifBlank { org.name }

    }

}

/** A proposal in a list across repositories. */

@Serializable

data class ProposalBrief(

    /** `owner/name`. */

    val repository: String,

    val number: Long,

    val title: String = "",

    val author: String = "",

    val state: String = "open",

    val conflicted: Boolean = false,

    @SerialName("updated_ms") val updatedMs: Long = 0,

    val url: String = "",

) {

    val owner: String get() = repository.substringBefore('/')

    val name: String get() = repository.substringAfter('/')

}

/** `POST /api/v1/user/runner-token`: a one-time token that registers a runner for [owner]'s repositories. */

@Serializable

data class RunnerToken(val token: String, val owner: String = "") {

    // The token is a secret until it is used.

    override fun toString(): String = "RunnerToken(owner=$owner, token=<redacted>)"

}

/** A change a proposal adds. */

@Serializable

data class ProposalChange(

    val hash: String,

    val message: String = "",

    /** One that nothing else in the proposal depends on. */

    val head: Boolean = false,

) {

    /** The message's first line. */

    val subject: String get() = message.lineSequence().firstOrNull().orEmpty()

}

/** A file or directory of a repository's tree at some reference (the code browser, #3). */

@Serializable

data class TreeEntry(

    val name: String,

    val path: String,

    /** `file`, `dir`, `symlink` or `subrepo`. */

    val kind: String = "file",

    val exec: Boolean = false,

    val size: Long? = null,

    val conflicted: Boolean = false,

) {

    val isDir: Boolean get() = kind == "dir"

}

/** Who made a change, as the hub knows them. */

@Serializable

data class ChangeAuthor(val name: String = "", val email: String = "", val account: String? = null)

/** A change in a history or a proposal. */

@Serializable

data class ChangeSummary(

    val hash: String,

    val message: String = "",

    val author: ChangeAuthor = ChangeAuthor(),

    @SerialName("when_ms") val whenMs: Long = 0,

) {

    val subject: String get() = message.lineSequence().firstOrNull().orEmpty()

    val short: String get() = hash.take(12)

}

/** A page of a reference's history (`GET …/history/{r}`), newest first. */

@Serializable

data class History(

    val reference: String = "",

    val total: Int = 0,

    val offset: Int = 0,

    val changes: List<ChangeSummary> = emptyList(),

)

/** A file a change touched, and how. */

@Serializable

data class FileChange(

    val path: String,

    /** `added`, `modified`, `removed` or `renamed`. */

    val kind: String = "modified",

    val from: String? = null,

    val added: Int = 0,

    val removed: Int = 0,

    /** The diff with three lines of context (hub #320), cut at 2000 lines. */

    val lines: List<DiffLine> = emptyList(),

    val truncated: Boolean = false,

)

/** A line of a file's diff: `context`, `add`, `del`, or `gap` for lines left out between hunks. */

@Serializable

data class DiffLine(

    val kind: String = "context",

    val old: Int? = null,

    val new: Int? = null,

    val text: String = "",

)

/** One change, whole (`GET …/changes/{hash}`). */

@Serializable

data class ChangeDetail(

    val change: ChangeSummary,

    val body: String = "",

    @SerialName("in_bookmarks") val inBookmarks: List<String> = emptyList(),

    @SerialName("in_tags") val inTags: List<String> = emptyList(),

    val files: List<FileChange> = emptyList(),

)

/** A bookmark or tag to browse at. */

@Serializable

data class NamedRef(val name: String)

/** A reviewer's approval; it counts only when [sealed] (a seal over every change, by a key linked to them). */

@Serializable

data class Approval(val account: String, val sealed: Boolean = false)

/** Who landed a proposal, how (`web`, or `api (token NAME)`), and when. */

@Serializable

data class Landed(val by: String, val via: String = "", @SerialName("when_ms") val whenMs: Long = 0)

/** Which proposals to list. `Open` includes drafts, as the hub's own list does. */

enum class ProposalState(val query: String) { Open("open"), Landed("landed"), Closed("closed"), All("all") }

/** A check on a state (`GET …/proposals/{n}/checks`): a Flow job, or another reporter's. */

@Serializable

data class Check(

    val name: String,

    /** `queued`, `running`, `passed`, `failed`, `cancelled` or `skipped`. */

    val status: String = "queued",

    val summary: String = "",

    val url: String = "",

    @SerialName("started_ms") val startedMs: Long = 0,

    @SerialName("finished_ms") val finishedMs: Long? = null,

)

/** One entry in the caller's inbox. */

@Serializable

data class Notification(

    val id: Long,

    @SerialName("at_ms") val atMs: Long = 0,

    /** `issue.opened`, `proposal.comment`, `mention`, `review`, … */

    val kind: String = "",

    val title: String = "",

    /** The page on the hub, absolute. */

    val url: String = "",

    val actor: String = "",

    val read: Boolean = false,

)

/** `GET /api/v1/notifications`: the unread count and the newest entries, unread first. */

@Serializable

data class Inbox(

    val unread: Long = 0,

    val items: List<Notification> = emptyList(),

)

/** An RFC 7807 problem: what the API answers with on an error. */

@Serializable

data class Problem(

    val status: Int = 0,

    val title: String = "",

    val detail: String = "",

)

/** The device flow's errors, RFC 8628's shape: `{"error": …, "error_description": …}`. */

@Serializable

data class OAuthError(

    val error: String = "",

    @SerialName("error_description") val description: String = "",

)

/** `POST /api/v1/device/code`'s answer. */

@Serializable

data class DeviceCode(

    @SerialName("device_code") val deviceCode: String,

    @SerialName("user_code") val userCode: String,

    @SerialName("verification_uri") val verificationUri: String,

    @SerialName("verification_uri_complete") val verificationUriComplete: String = "",

    @SerialName("expires_in") val expiresIn: Long = 900,

    val interval: Long = 5,

) {

    /** The page to open: with the code filled in when the hub offers it. */

    val pageToOpen: String get() = verificationUriComplete.ifBlank { verificationUri }

    // The device code is a secret until it is used: never in logs.

    override fun toString(): String = "DeviceCode(userCode=$userCode, verificationUri=$verificationUri)"

}

/** `POST /api/v1/device/token`'s answer once the user approved. */

@Serializable

data class TokenGrant(

    @SerialName("access_token") val accessToken: String,

    @SerialName("token_type") val tokenType: String = "bearer",

    /** The scopes the user allowed, space separated (they may untick some). */

    val scope: String = "",

    val username: String = "",

    @SerialName("expires_in") val expiresIn: Long = 0,

) {

    val scopes: List<String> get() = scope.split(' ').filter { it.isNotBlank() }

    override fun toString(): String = "TokenGrant(username=$username, scope=$scope, accessToken=<redacted>)"

}

/** What `PUT /user/push` answers (#16): whether the hub sends alerts at all. */

@Serializable

data class PushRegistered(val alerts: Boolean = false)

/** What `POST …/reviews` answers; the app only needs that it was taken. */

@Serializable

data class ReviewPosted(val verdict: String = "")

/** What `POST …/flow/runs/N/expedite` answers. */

@Serializable

data class Expedited(val expedited: Boolean = false)