SPB Git

Repository Public

NotesAPI+Timeline.swift 3.8 KB 58 lines swift

1// SP Notes Core2// File: Sources/SPNotesAPI/NotesAPI+Timeline.swift3// Description: Routes of the events journal and of the time machine (API-NEXT §4.4).4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai7import Foundation89extension NotesAPI {10    // MARK: - Events1112    /// `GET /api/events` — the journal, newest first. Call again with `nextCursor` as `cursor` until it is `nil`:13    /// the cursor is a position in (time, id) order, so new events never shift a page already read.14    /// `400 bad_kinds` (`APIError.validKinds`), `400 bad_cursor`, `400 bad_request`, `404` unknown `projectId`.15    public func events(_ query: JournalQuery = JournalQuery()) async throws -> EventPage {16        var items: [URLQueryItem] = []17        if let pageId = query.pageId { items.append(URLQueryItem(name: "pageId", value: pageId)) }18        if let projectId = query.projectId { items.append(URLQueryItem(name: "projectId", value: projectId)) }19        if let from = query.from { items.append(URLQueryItem(name: "from", value: APIDate.string(from: from))) }20        if let to = query.to { items.append(URLQueryItem(name: "to", value: APIDate.string(from: to))) }21        if !query.kinds.isEmpty { items.append(URLQueryItem(name: "kinds", value: query.kinds.joined(separator: ","))) }22        if let limit = query.limit { items.append(URLQueryItem(name: "limit", value: String(limit))) }23        if let cursor = query.cursor { items.append(URLQueryItem(name: "cursor", value: cursor)) }24        return try await client.decode(EventPage.self, .get("/api/events", query: items))25    }2627    // MARK: - Time machine2829    private func timeMachine(_ scope: URLQueryItem, at date: Date, content: Bool?) async throws -> TimeMachineSnapshot {30        var items = [URLQueryItem(name: "at", value: APIDate.string(from: date)), scope]31        if let content { items.append(URLQueryItem(name: "content", value: content ? "1" : "0")) }32        return try await client.decode(TimeMachineSnapshot.self, .get("/api/timemachine", query: items))33    }3435    /// `GET /api/timemachine?at=&pageId=` — one page as it was at `date`, with the relations and references of that36    /// time. `includeContent`: `nil` = the server default (content included for a page).37    public func timeMachine(pageID: String, at date: Date, includeContent: Bool? = nil) async throws -> TimeMachineSnapshot {38        try await timeMachine(URLQueryItem(name: "pageId", value: pageID), at: date, content: includeContent)39    }4041    /// `GET /api/timemachine?at=&projectId=` — a page and all its sub-pages as they were at `date`.42    /// `includeContent`: `nil` = the server default (content omitted for a project).43    public func timeMachine(projectID: String, at date: Date, includeContent: Bool? = nil) async throws -> TimeMachineSnapshot {44        try await timeMachine(URLQueryItem(name: "projectId", value: projectID), at: date, content: includeContent)45    }4647    private struct RestoreBody: Encodable { var baseVersion: Int? }4849    /// `POST /api/pages/<id>/versions/<versionId>/restore` — brings the page back to a history entry (`versionID`:50    /// the entry id of `TimeMachinePage.versionId` / `PageVersionSummary.id`, or a version number). The current state51    /// is saved in the history first. With `baseVersion`, throws `APIError.conflict(server:message:)` when the page52    /// changed meanwhile (nothing is written). `404` unknown entry, `400` malformed.53    public func restoreHistoryEntry(pageID: String, versionID: String, baseVersion: Int? = nil, idempotencyKey: String? = nil) async throws -> HistoryRestoreResult {54        let path = "/api/pages/\(HTTPRequest.segment(pageID))/versions/\(HTTPRequest.segment(versionID))/restore"55        return try await client.decode(HistoryRestoreResult.self, .json(.post, path, body: RestoreBody(baseVersion: baseVersion), idempotencyKey: idempotencyKey))56    }57}58
Files main
Menu

Theme