SPB Git

Repository Public

TimelineModels.swift 9.8 KB 243 lines swift

1// SP Notes Core2// File: Sources/SPNotesAPI/TimelineModels.swift3// Description: Models of the events journal and of the time machine (API-NEXT §4.4): journal events and their paging,4//              the state of a page or a project at a date, restoring a history entry.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation910// MARK: - Events1112/// The kinds of the journal (30). Families are written `page.*`, `task.*`… in the `kinds` filter.13public enum EventKind {14    public static let pageCreated = "page.created"15    public static let pageRenamed = "page.renamed"16    public static let pageEdited = "page.edited"17    public static let pageMoved = "page.moved"18    public static let pageArchived = "page.archived"19    public static let pageUnarchived = "page.unarchived"20    public static let pageTrashed = "page.trashed"21    public static let pageRestored = "page.restored"22    public static let pagePurged = "page.purged"23    public static let pageVersion = "page.version"24    public static let tagAdded = "tag.added"25    public static let tagRemoved = "tag.removed"26    public static let linkAdded = "link.added"27    public static let linkRemoved = "link.removed"28    public static let relationCreated = "relation.created"29    public static let relationAccepted = "relation.accepted"30    public static let relationRejected = "relation.rejected"31    public static let relationRemoved = "relation.removed"32    public static let referenceAdded = "reference.added"33    public static let referenceLinked = "reference.linked"34    public static let attachmentAdded = "attachment.added"35    public static let taskCreated = "task.created"36    public static let taskCompleted = "task.completed"37    public static let taskReopened = "task.reopened"38    public static let captureCreated = "capture.created"39    public static let captureFiled = "capture.filed"40    public static let aiApplied = "ai.applied"41    public static let agentApplied = "agent.applied"42    public static let decisionRecorded = "decision.recorded"43    public static let canvasEdited = "canvas.edited"4445    public static let all = [46        pageCreated, pageRenamed, pageEdited, pageMoved, pageArchived, pageUnarchived, pageTrashed, pageRestored, pagePurged, pageVersion,47        tagAdded, tagRemoved, linkAdded, linkRemoved, relationCreated, relationAccepted, relationRejected, relationRemoved,48        referenceAdded, referenceLinked, attachmentAdded, taskCreated, taskCompleted, taskReopened, captureCreated, captureFiled,49        aiApplied, agentApplied, decisionRecorded, canvasEdited,50    ]5152    /// The family filter of a prefix: `family("task")` → `task.*`.53    public static func family(_ prefix: String) -> String { prefix + ".*" }54}5556/// `actor` of an event.57public enum EventActor {58    public static let user = "user"59    public static let agent = "agent"60    public static let ai = "ai"61    public static let system = "system"62}6364/// One event of the journal (`GET /api/events`, `removedSince` of the time machine).65public struct KnowledgeEvent: Codable, Sendable, Equatable, Identifiable {66    public var id: String67    public var at: Date68    /// `EventKind` (unknown kinds decode as they are).69    public var kind: String70    public var pageId: String?71    /// The **current** title of the page (`nil` once the page is purged).72    public var pageTitle: String?73    public var pageIcon: String?74    /// `page`, `page_version`, `tag`, `edge`, `reference`, `attachment`, `task`, `block`, `execution`, `canvas`.75    public var entityKind: String?76    /// A uuid, except for a tag (its name) and a block (its block id).77    public var entityId: String?78    /// `EventActor`.79    public var actor: String?80    /// The device label of the session (`SP Notes · Mac`); `nil` for jobs.81    public var device: String?82    /// The title or the name at the time of the event.83    public var summary: String?84    /// Depends on `kind` (API-NEXT §4.4 table).85    public var data: RawJSON?8687    /// The family of the kind: `page`, `task`, `relation`…88    public var family: String { kind.split(separator: ".").first.map(String.init) ?? kind }8990    /// A string field of `data` (`relationId`, `toId`, `tag`, `from`, `to`…).91    public func dataString(_ key: String) -> String? {92        guard let data, let json = try? JSONValue(parsing: data.data) else { return nil }93        return json[key]?.stringValue94    }95}9697/// `GET /api/events` — newest first.98public struct EventPage: Codable, Sendable, Equatable {99    public var events: [KnowledgeEvent]100    /// Pass it back as `cursor` until it is `nil`.101    public var nextCursor: String?102}103104/// Parameters of `GET /api/events`.105public struct JournalQuery: Sendable, Equatable {106    /// One page. Not together with `projectId` (`400 bad_request`).107    public var pageId: String?108    /// A page and all its sub-pages, trashed ones included (`404` unknown).109    public var projectId: String?110    public var from: Date?111    public var to: Date?112    /// Exact kinds (`EventKind`) or families (`page.*`); `400 bad_kinds` for an unknown one.113    public var kinds: [String]114    /// 1…200 (server default 50).115    public var limit: Int?116    /// `nextCursor` of the previous answer (`400 bad_cursor` when unusable).117    public var cursor: String?118119    public init(pageId: String? = nil, projectId: String? = nil, from: Date? = nil, to: Date? = nil, kinds: [String] = [], limit: Int? = nil, cursor: String? = nil) {120        self.pageId = pageId121        self.projectId = projectId122        self.from = from123        self.to = to124        self.kinds = kinds125        self.limit = limit126        self.cursor = cursor127    }128}129130// MARK: - Time machine131132/// `source` of a page of the time machine: where its state at the date comes from.133public enum TimeMachineSource {134    /// Unchanged since the date: the present state (`exact`).135    public static let current = "current"136    /// The most recent history entry taken at or before the date (edits after that entry are not in it).137    public static let version = "version"138    /// No entry at or before the date: the first one taken after it.139    public static let versionAfter = "version_after"140    /// Created after the date (`existed == false`), or no history covers that date.141    public static let none = "none"142}143144/// One page of `GET /api/timemachine` (the root first, then by creation date).145public struct TimeMachinePage: Codable, Sendable, Equatable, Identifiable {146    public var id: String147    /// The title at that date.148    public var title: String?149    public var icon: String?150    public var section: String?151    /// The **current** parent.152    public var parentId: String?153    public var existed: Bool154    /// Set when the page was in the trash at that date.155    public var trashedAt: Date?156    /// `TimeMachineSource`.157    public var source: String158    /// Whether the state is proven to be exactly the one at the date.159    public var exact: Bool?160    public var version: Int?161    /// The history entry to give to `restoreHistoryEntry` (`nil` for `current` and `none`).162    public var versionId: String?163    public var versionAt: Date?164    public var wordCount: Int?165    public var currentTitle: String?166    public var currentVersion: Int?167    public var changedSince: Bool?168    /// The document at that date, when included (`content=1`, the default for a page scope).169    public var content: RawJSON?170    public var properties: RawJSON?171}172173/// An edge as it stood at the date (`relations` of the time machine): the edge keys plus the titles.174public struct HistoricalRelation: Codable, Sendable, Equatable, Identifiable {175    public var id: String176    public var fromId: String177    public var toId: String178    public var sourceKind: String?179    public var targetKind: String?180    /// `RelationKind`.181    public var kind: String182    public var relType: String?183    public var origin: String?184    public var note: String?185    public var validFrom: Date?186    public var validTo: Date?187    public var sourceBlockId: String?188    public var targetBlockId: String?189    public var createdAt: Date?190    public var fromTitle: String?191    public var toTitle: String?192}193194/// A reference that existed at the date (`references` of the time machine).195public struct HistoricalReference: Codable, Sendable, Equatable, Identifiable {196    public var id: String197    public var citeKey: String?198    public var title: String?199    public var authors: [String]?200    public var year: Int?201    public var pageId: String?202    public var createdAt: Date?203}204205/// `scope` of the time machine: exactly one of the two.206public struct TimeMachineScope: Codable, Sendable, Equatable {207    public var pageId: String?208    public var projectId: String?209}210211/// `GET /api/timemachine`.212public struct TimeMachineSnapshot: Codable, Sendable, Equatable {213    public var at: Date214    public var scope: TimeMachineScope?215    public var pages: [TimeMachinePage]216    public var relations: [HistoricalRelation]217    public var references: [HistoricalReference]218    /// `link.removed` / `relation.removed` events after the date: what existed then and is gone now (events with219    /// `id`, `at`, `kind`, `pageId`, `summary`, `data` only).220    public var removedSince: [KnowledgeEvent]221    /// Date of the first real event of the journal: nothing is known before it except creations and versions.222    public var journalSince: Date?223}224225/// `POST /api/pages/<id>/versions/<versionId>/restore` → 200.226public struct HistoryRestoreResult: Codable, Sendable, Equatable {227    public var ok: Bool228    /// The version of the page after the restoration.229    public var version: Int230    /// The version number that was restored.231    public var restored: Int?232}233234// MARK: - Typed errors235236extension APIError {237    /// `400 bad_kinds` (`/api/events`, `/api/sync`): the kinds the server accepts.238    public var validKinds: [String]? {239        guard code == NextCode.badKinds else { return nil }240        return try? detail("kinds")?.decode([String].self)241    }242}243
Files main
Menu

Theme