Repository Public
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