Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
package de.markusressel.mkdocsrestclient

import de.markusressel.mkdocsrestclient.dashboard.FeedPageModel
import de.markusressel.mkdocsrestclient.history.HistoryEntryModel
import de.markusressel.mkdocsrestclient.dashboard.PinScope
import de.markusressel.mkdocsrestclient.dashboard.PinsModel
import de.markusressel.mkdocsrestclient.reference.AuthorshipModel
Expand Down Expand Up @@ -275,6 +276,18 @@ class DummyMkDocsRestClient : IMkDocsRestClient {
override suspend fun getFeed(before: String?, limit: Int): Result<FeedPageModel, FuelError> =
Result.success(FeedPageModel())

override suspend fun getDocumentHistory(documentId: String, limit: Int): Result<List<HistoryEntryModel>, FuelError> =
Result.success(emptyList())

override suspend fun getDocumentRevisionContent(documentId: String, revision: String): Result<String, FuelError> =
Result.success("")

override suspend fun getDocumentRevisionDiff(documentId: String, from: String, to: String): Result<String, FuelError> =
Result.success("")

override suspend fun restoreDocumentRevision(documentId: String, revision: String): Result<String, FuelError> =
Result.success("")

override suspend fun getQrCode(key: String, scan: Boolean): Result<QrCodeModel, FuelError> =
Result.error(FuelError.wrap(UnsupportedOperationException("not in the demo")))

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,16 @@ import com.github.kittinunf.fuel.core.FuelError
import com.github.kittinunf.result.Result
import de.markusressel.mkdocsrestclient.dashboard.DashboardApi
import de.markusressel.mkdocsrestclient.document.DocumentApi
import de.markusressel.mkdocsrestclient.history.HistoryApi
import de.markusressel.mkdocsrestclient.mkdocs.MkDocsApi
import de.markusressel.mkdocsrestclient.qr.QrCodeApi
import de.markusressel.mkdocsrestclient.reference.ReferenceApi
import de.markusressel.mkdocsrestclient.resource.ResourceApi
import de.markusressel.mkdocsrestclient.section.SectionApi
import de.markusressel.mkdocsrestclient.section.SectionModel

interface IMkDocsRestClient : MkDocsApi, SectionApi, DocumentApi, ResourceApi, ReferenceApi, DashboardApi, QrCodeApi {
interface IMkDocsRestClient : MkDocsApi, SectionApi, DocumentApi, ResourceApi, ReferenceApi, DashboardApi, QrCodeApi,
HistoryApi {

/**
* Check if the server is alive and reachable
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ import de.markusressel.mkdocsrestclient.dashboard.DashboardApi
import de.markusressel.mkdocsrestclient.dashboard.DashboardApiImpl
import de.markusressel.mkdocsrestclient.document.DocumentApi
import de.markusressel.mkdocsrestclient.document.DocumentApiImpl
import de.markusressel.mkdocsrestclient.history.HistoryApi
import de.markusressel.mkdocsrestclient.history.HistoryApiImpl
import de.markusressel.mkdocsrestclient.mkdocs.MkDocsApi
import de.markusressel.mkdocsrestclient.mkdocs.MkDocsApiImpl
import de.markusressel.mkdocsrestclient.qr.QrCodeApi
Expand All @@ -33,14 +35,16 @@ class MkDocsRestClient constructor(
referenceApi: ReferenceApi = ReferenceApiImpl(requestManager),
dashboardApi: DashboardApi = DashboardApiImpl(requestManager),
qrCodeApi: QrCodeApi = QrCodeApiImpl(requestManager),
historyApi: HistoryApi = HistoryApiImpl(requestManager),
) : IMkDocsRestClient,
MkDocsApi by mkDocsApi,
SectionApi by sectionApi,
DocumentApi by documentApi,
ResourceApi by resourceApi,
ReferenceApi by referenceApi,
DashboardApi by dashboardApi,
QrCodeApi by qrCodeApi {
QrCodeApi by qrCodeApi,
HistoryApi by historyApi {

override suspend fun isHostAlive(): Result<String, FuelError> {
return requestManager.doStatusRequest("/alive/", Method.GET)
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
package de.markusressel.mkdocsrestclient.history

import com.github.kittinunf.fuel.core.FuelError
import com.github.kittinunf.fuel.core.Method
import com.github.kittinunf.result.Result
import com.github.kittinunf.result.map
import de.markusressel.mkdocsrestclient.RequestKind
import de.markusressel.mkdocsrestclient.RequestManager

/** Names the live text of a document in a diff */
const val REVISION_CURRENT = "current"

/**
* The revision history of a document, from the git history of its file. A backend without `git.enabled` answers 404.
*/
interface HistoryApi {

/**
* @param limit 1 to 1000
* @return the commits that touched the document, newest first
*/
suspend fun getDocumentHistory(documentId: String, limit: Int = 100): Result<List<HistoryEntryModel>, FuelError>

/** @return the text of the document at [revision] */
suspend fun getDocumentRevisionContent(documentId: String, revision: String): Result<String, FuelError>

/**
* @param from a revision or [REVISION_CURRENT]
* @param to a revision or [REVISION_CURRENT]
* @return a unified diff, empty if both texts are equal
*/
suspend fun getDocumentRevisionDiff(
documentId: String,
from: String,
to: String = REVISION_CURRENT,
): Result<String, FuelError>

/** Sets the live text to the one of [revision], as an edit of the signed in account. Editors and admins only. */
suspend fun restoreDocumentRevision(documentId: String, revision: String): Result<String, FuelError>
}

class HistoryApiImpl(
private val requestManager: RequestManager,
) : HistoryApi {

override suspend fun getDocumentHistory(documentId: String, limit: Int): Result<List<HistoryEntryModel>, FuelError> =
requestManager.doRequest<Array<HistoryEntryModel>>(
url = "/document/$documentId/history/",
urlParameters = listOf("limit" to limit),
method = Method.GET,
).map { it.toList() }

override suspend fun getDocumentRevisionContent(documentId: String, revision: String): Result<String, FuelError> =
requestManager.doRequest(url = "/document/$documentId/history/$revision/content/", method = Method.GET)

override suspend fun getDocumentRevisionDiff(documentId: String, from: String, to: String): Result<String, FuelError> =
requestManager.doRequest(
url = "/document/$documentId/history/diff/",
urlParameters = listOf("from" to from, "to" to to),
method = Method.GET,
)

override suspend fun restoreDocumentRevision(documentId: String, revision: String): Result<String, FuelError> =
requestManager.doRequest(
url = "/document/$documentId/history/$revision/restore/",
method = Method.POST,
kind = RequestKind.LongAction,
)
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
package de.markusressel.mkdocsrestclient.history

import com.squareup.moshi.JsonClass
import java.util.Date

/**
* An author of a commit. The backend sends empty strings, not null, for an author who is not an account, like the
* initial import.
*
* @param username the current username of the account
*/
@JsonClass(generateAdapter = true)
data class HistoryAuthorModel(
val name: String,
val email: String,
val username: String = "",
val accountId: String = "",
) {
val isAccount: Boolean get() = accountId.isNotEmpty()
}

/**
* A commit that touched a document, from `GET /document/{id}/history/`
*
* @param revision the full commit hash
* @param path the path of the file in that commit, which differs from today's after a rename
* @param appTokens the names of the app tokens (AI agents) the changes were made with
*/
@JsonClass(generateAdapter = true)
data class HistoryEntryModel(
val revision: String,
val time: Date,
val author: HistoryAuthorModel,
val coAuthors: List<HistoryAuthorModel> = emptyList(),
val message: String,
val path: String,
val appTokens: List<String> = emptyList(),
)
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
package de.markusressel.mkdocsrestclient.history

import de.markusressel.mkdocsrestclient.toEntity
import java.time.Instant
import java.util.Date
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFalse
import kotlin.test.assertTrue

class HistoryModelsTest {

/** the answer of a real backend (TestHistory setup in MkDocsEditor-Backend), only the account ids changed */
private val history = """
[
{
"revision": "bfc59905fcb742f8160345f1047b33056386ff17",
"time": "2026-11-14T03:45:33+01:00",
"author": {
"name": "alice",
"email": "alice@mkdocseditor.invalid",
"username": "alice",
"accountId": "a1"
},
"coAuthors": [
{
"name": "bob",
"email": "bob@mkdocseditor.invalid",
"username": "bob",
"accountId": "a2"
}
],
"message": "Update guide/setup.md",
"path": "guide/setup.md",
"appTokens": ["Claude Code"]
},
{
"revision": "9d8af80923338d9e86ebbdf016f547b96089cc07",
"time": "2026-11-14T03:45:32+01:00",
"author": {
"name": "Test",
"email": "test@example.com",
"username": "",
"accountId": ""
},
"coAuthors": [],
"message": "Initial",
"path": "guide/setup.md",
"appTokens": []
}
]
""".trimIndent()

@Test
fun `a history of the backend is read with all its fields`() {
val entries = history.toEntity<Array<HistoryEntryModel>>().toList()

val update = entries[0]
assertEquals("bfc59905fcb742f8160345f1047b33056386ff17", update.revision)
assertEquals(Date.from(Instant.parse("2026-11-14T02:45:33Z")), update.time)
assertEquals("alice", update.author.username)
assertTrue(update.author.isAccount)
assertEquals(listOf("bob"), update.coAuthors.map { it.username })
assertEquals(listOf("Claude Code"), update.appTokens)
assertEquals("guide/setup.md", update.path)
}

@Test
fun `an author who is not an account comes with empty strings`() {
val initial = history.toEntity<Array<HistoryEntryModel>>()[1]

assertFalse(initial.author.isAccount)
assertEquals("", initial.author.username)
assertEquals(emptyList(), initial.coAuthors)
assertEquals(emptyList(), initial.appTokens)
}
}
Loading