Repository Public
1// SP Notes Core2// File: Sources/SPNotesAPI/PageModels.swift3// Description: Codable transfer objects of the change feed and of the page routes (rows, drafts, patches with4// null-versus-absent fields, versions, conflict resolution, tags).5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation910// Identifiers are the server's lower-case UUID strings. `NotesAPI.newID()` creates one on the client.1112// MARK: - Change feed1314public struct WorkspaceInfo: Codable, Sendable, Equatable {15 public var id: String16 public var name: String17}1819public struct UserInfo: Codable, Sendable, Equatable {20 public var displayName: String?21}2223/// One answer of `GET /api/sync`.24public struct SyncPage: Codable, Sendable, Equatable {25 /// Send back unchanged as `since` next time.26 public var cursor: Int6427 /// Highest revision on the server at the time of the answer.28 public var head: Int6429 /// More changes are waiting: call again with `cursor`.30 public var more: Bool31 /// The cursor was ahead of the server (database restored): start again from 0.32 public var reset: Bool33 public var serverTime: Date34 public var workspace: WorkspaceInfo35 public var user: UserInfo36 public var pages: [Page]37 public var attachments: [SyncAttachment]38 public var tombstones: [Tombstone]39 /// The complete tag list of the workspace (on every call).40 public var tags: [TagColor]41 /// 3.0, only when `kinds` was asked: one list per requested kind (`task`, `database`, … see `SyncKind`), windowed42 /// like the pages. `nil` = the server did not send the key (2.x answer, or no `kinds`).43 public var entities: [String: [SyncEntityRow]]?4445 /// Tolerant decoding: the `reset` answer of the server is abbreviated (no `user`, empty lists).46 public init(from decoder: Decoder) throws {47 let c = try decoder.container(keyedBy: CodingKeys.self)48 cursor = try c.decode(Int64.self, forKey: .cursor)49 head = try c.decodeIfPresent(Int64.self, forKey: .head) ?? cursor50 more = try c.decodeIfPresent(Bool.self, forKey: .more) ?? false51 reset = try c.decodeIfPresent(Bool.self, forKey: .reset) ?? false52 serverTime = try c.decode(Date.self, forKey: .serverTime)53 workspace = try c.decode(WorkspaceInfo.self, forKey: .workspace)54 user = try c.decodeIfPresent(UserInfo.self, forKey: .user) ?? UserInfo(displayName: nil)55 pages = try c.decodeIfPresent([Page].self, forKey: .pages) ?? []56 attachments = try c.decodeIfPresent([SyncAttachment].self, forKey: .attachments) ?? []57 tombstones = try c.decodeIfPresent([Tombstone].self, forKey: .tombstones) ?? []58 tags = try c.decodeIfPresent([TagColor].self, forKey: .tags) ?? []59 entities = try c.decodeIfPresent([String: [SyncEntityRow]].self, forKey: .entities)60 }61}6263/// A page row. The feed carries every field; the page routes omit `tags`.64public struct Page: Codable, Sendable, Equatable, Identifiable {65 public var id: String66 public var parentId: String?67 public var databaseId: String?68 /// `page`, `database`, `research` (see `PageType`).69 public var type: String70 /// `notes`, `documents`, `databases`, `projects`, `research` (see `PageSection`).71 public var section: String72 public var title: String73 public var icon: String?74 public var cover: String?75 /// The document (raw JSON, parsed by `SPNotesDocument`).76 public var content: RawJSON77 /// The properties (raw JSON object): `favorite`, `folder`, database cells…78 public var properties: RawJSON79 public var position: Double80 public var pinned: Bool81 public var archived: Bool82 /// Version of the versioned fields (`title`, `content`, `properties`): the `baseVersion` of the next write.83 public var version: Int84 public var wordCount: Int85 public var createdAt: Date86 public var updatedAt: Date87 public var lastOpenedAt: Date?88 /// Non-nil = in the trash.89 public var deletedAt: Date?90 /// Non-nil = in the capture inbox.91 public var inboxAt: Date?92 public var captureKind: String?93 /// Position in the change feed.94 public var rev: Int64?95 /// Sorted tag names. Only present in the change feed.96 public var tags: [String]?97 public var workspaceId: String?98 /// Plain text of the document. Only present in the answers of the page routes.99 public var plainText: String?100}101102/// An attachment row of the change feed.103public struct SyncAttachment: Codable, Sendable, Equatable, Identifiable {104 public var id: String105 public var pageId: String?106 public var filename: String107 public var mime: String108 public var size: Int64109 public var sha256: String?110 public var pageCount: Int?111 public var createdAt: Date112 /// Non-nil = deleted (soft delete).113 public var deletedAt: Date?114 public var rev: Int64115}116117/// A permanently deleted object.118public struct Tombstone: Codable, Sendable, Equatable {119 public var id: String120 /// `page` or `attachment`.121 public var kind: String122 public var rev: Int64123 public var deletedAt: Date124125 public static let pageKind = "page"126 public static let attachmentKind = "attachment"127}128129public struct TagColor: Codable, Sendable, Equatable {130 public var name: String131 public var color: String?132}133134// MARK: - Page routes135136public enum PageSection: String, Codable, Sendable, CaseIterable {137 case notes, documents, databases, projects, research138}139140public enum PageType: String, Codable, Sendable, CaseIterable {141 /// `canvas` (3.0): a page whose body is a canvas (`GET /api/canvases/<pageId>`); a 2.x server refuses it (400).142 case page, database, research, canvas143}144145/// Body of `POST /api/pages`. Every field is optional; give an `id` so that a retry can never create a duplicate.146public struct PageDraft: Encodable, Sendable, Equatable {147 public var id: String?148 public var title: String?149 public var parentId: String?150 public var section: PageSection?151 public var type: PageType?152 public var content: RawJSON?153 public var icon: String?154 /// A JSON object.155 public var properties: RawJSON?156 /// 3.0: the page is a capture waiting in the inbox since this date (a 2.x server ignores the field).157 public var inboxAt: Date?158 /// 3.0: what kind of capture it is (`note`, `link`, `audio`…; open string).159 public var captureKind: String?160161 public init(id: String? = nil, title: String? = nil, parentId: String? = nil, section: PageSection? = nil, type: PageType? = nil, content: RawJSON? = nil, icon: String? = nil, properties: RawJSON? = nil,162 inboxAt: Date? = nil, captureKind: String? = nil) {163 self.id = id164 self.title = title165 self.parentId = parentId166 self.section = section167 self.type = type168 self.content = content169 self.icon = icon170 self.properties = properties171 self.inboxAt = inboxAt172 self.captureKind = captureKind173 }174}175176/// The answer of a creation with a client-chosen identifier.177public struct Created<Value: Sendable>: Sendable {178 public var value: Value179 /// `true` when the identifier already existed on the server (`x-existing: 1`): `value` is the stored object as it180 /// is, the request changed nothing.181 public var existing: Bool182183 public init(value: Value, existing: Bool) {184 self.value = value185 self.existing = existing186 }187}188189extension Created: Equatable where Value: Equatable {}190191/// A field of a patch that can be set to a value or explicitly to `null`. An absent field is a `nil` optional.192public enum PatchValue<Value: Encodable & Sendable & Equatable>: Sendable, Equatable {193 /// Send JSON `null` (remove the parent, the icon, the cover…).194 case null195 case value(Value)196197 /// `.value` for a non-nil argument, `.null` for `nil`.198 public init(_ value: Value?) {199 self = value.map(PatchValue.value) ?? .null200 }201}202203/// Body of `PATCH /api/pages/<id>`. Only the fields that are set are sent. `title`, `content` and `properties` are204/// versioned: with `baseVersion` they are only written if the page is still at that version (`409 conflict` otherwise).205public struct PagePatch: Encodable, Sendable, Equatable {206 public var title: String?207 public var content: RawJSON?208 public var icon: PatchValue<String>?209 public var cover: PatchValue<String>?210 /// A JSON object replacing the properties.211 public var properties: RawJSON?212 /// `.null` moves the page to the root.213 public var parentId: PatchValue<String>?214 public var section: PageSection?215 public var position: Double?216 public var pinned: Bool?217 public var archived: Bool?218 /// Label of the history snapshot (`autosave` by default on the server).219 public var versionReason: String?220 public var baseVersion: Int?221222 public init(223 title: String? = nil, content: RawJSON? = nil, icon: PatchValue<String>? = nil, cover: PatchValue<String>? = nil,224 properties: RawJSON? = nil, parentId: PatchValue<String>? = nil, section: PageSection? = nil, position: Double? = nil,225 pinned: Bool? = nil, archived: Bool? = nil, versionReason: String? = nil, baseVersion: Int? = nil226 ) {227 self.title = title228 self.content = content229 self.icon = icon230 self.cover = cover231 self.properties = properties232 self.parentId = parentId233 self.section = section234 self.position = position235 self.pinned = pinned236 self.archived = archived237 self.versionReason = versionReason238 self.baseVersion = baseVersion239 }240241 /// No field to write (`versionReason` and `baseVersion` alone change nothing).242 public var isEmpty: Bool {243 title == nil && content == nil && icon == nil && cover == nil && properties == nil && parentId == nil244 && section == nil && position == nil && pinned == nil && archived == nil245 }246247 /// Whether the patch touches a version-guarded field.248 public var touchesVersionedFields: Bool { title != nil || content != nil || properties != nil }249250 enum CodingKeys: String, CodingKey {251 case title, content, icon, cover, properties, parentId, section, position, pinned, archived, versionReason, baseVersion252 }253254 public func encode(to encoder: Encoder) throws {255 var c = encoder.container(keyedBy: CodingKeys.self)256 try c.encodeIfPresent(title, forKey: .title)257 try c.encodeIfPresent(content, forKey: .content)258 try c.encodePatch(icon, forKey: .icon)259 try c.encodePatch(cover, forKey: .cover)260 try c.encodeIfPresent(properties, forKey: .properties)261 try c.encodePatch(parentId, forKey: .parentId)262 try c.encodeIfPresent(section, forKey: .section)263 try c.encodeIfPresent(position, forKey: .position)264 try c.encodeIfPresent(pinned, forKey: .pinned)265 try c.encodeIfPresent(archived, forKey: .archived)266 try c.encodeIfPresent(versionReason, forKey: .versionReason)267 try c.encodeIfPresent(baseVersion, forKey: .baseVersion)268 }269}270271extension KeyedEncodingContainer {272 /// absent → nothing, `.null` → JSON null, `.value` → the value.273 mutating func encodePatch<V>(_ value: PatchValue<V>?, forKey key: Key) throws {274 switch value {275 case nil: break276 case .some(.null): try encodeNil(forKey: key)277 case .some(.value(let v)): try encode(v, forKey: key)278 }279 }280}281282/// Answer of `PATCH /api/pages/<id>`.283public struct PagePatchResult: Codable, Sendable, Equatable {284 public var id: String285 /// The new version: a feed row carrying this version is the echo of this write.286 public var version: Int287 public var updatedAt: Date288 public var title: String289 public var wordCount: Int?290}291292/// Answer of `GET /api/pages/<id>?head=1`.293public struct PageHead: Codable, Sendable, Equatable {294 public var id: String295 public var version: Int296 public var updatedAt: Date297 public var deletedAt: Date?298}299300/// A link to a page (breadcrumb element, backlink).301public struct PageReference: Codable, Sendable, Equatable, Identifiable {302 public var id: String303 public var title: String?304 public var icon: String?305 public var section: String?306 public var updatedAt: Date?307}308309/// Answer of `GET /api/pages/<id>`: the row, its ancestors (root first, the page itself last) and the pages linking to it.310public struct PageDetail: Codable, Sendable, Equatable {311 public var page: Page312 public var breadcrumb: [PageReference]313 public var backlinks: [PageReference]314315 enum CodingKeys: String, CodingKey { case breadcrumb, backlinks }316317 public init(from decoder: Decoder) throws {318 page = try Page(from: decoder)319 let c = try decoder.container(keyedBy: CodingKeys.self)320 breadcrumb = try c.decodeIfPresent([PageReference].self, forKey: .breadcrumb) ?? []321 backlinks = try c.decodeIfPresent([PageReference].self, forKey: .backlinks) ?? []322 }323324 public func encode(to encoder: Encoder) throws {325 try page.encode(to: encoder)326 var c = encoder.container(keyedBy: CodingKeys.self)327 try c.encode(breadcrumb, forKey: .breadcrumb)328 try c.encode(backlinks, forKey: .backlinks)329 }330}331332// MARK: - Conflict resolution333334public enum ConflictChoice: String, Codable, Sendable, CaseIterable {335 /// Keep the local copy (the server copy stays in the history).336 case mine337 /// Keep the server copy (the local copy is stored in the history).338 case theirs339 /// Keep the server copy and create a sibling page "… (conflict copy)" with the local one.340 case both341}342343/// The local copy sent to `POST /api/pages/<id>/resolve`.344public struct ConflictMine: Encodable, Sendable, Equatable {345 public var title: String?346 public var content: RawJSON?347348 public init(title: String? = nil, content: RawJSON? = nil) {349 self.title = title350 self.content = content351 }352}353354/// Answer of `POST /api/pages/<id>/resolve`: the state of the page after the resolution.355public struct ResolvedPage: Codable, Sendable, Equatable {356 public var id: String357 public var version: Int358 public var title: String359 public var content: RawJSON360 public var properties: RawJSON361 public var updatedAt: Date362 /// The sibling page created by the choice `both`.363 public var copyId: String?364}365366// MARK: - Trash367368public struct TrashResult: Codable, Sendable, Equatable {369 public var ok: Bool370 /// Number of pages moved to the trash (the page and its descendants).371 public var trashed: Int?372}373374public struct PurgeResult: Codable, Sendable, Equatable {375 public var ok: Bool376 /// Number of pages permanently deleted (`DELETE /api/trash`).377 public var purged: Int?378}379380/// `{ ok: true }`.381public struct OKResult: Codable, Sendable, Equatable {382 public var ok: Bool383}384385// MARK: - Versions386387public struct PageVersionSummary: Codable, Sendable, Equatable, Identifiable {388 public var id: String389 public var version: Int390 public var title: String391 public var reason: String?392 public var createdAt: Date393 public var wordCount: Int?394}395396/// A full history snapshot (`GET /api/pages/<id>/versions?v=<n>`).397public struct PageVersionSnapshot: Codable, Sendable, Equatable, Identifiable {398 public var id: String399 public var pageId: String?400 public var version: Int401 public var title: String402 public var content: RawJSON403 public var properties: RawJSON?404 public var reason: String?405 public var createdAt: Date406 public var wordCount: Int?407}408409public struct VersionRestoreResult: Codable, Sendable, Equatable {410 public var ok: Bool411 /// The version of the page after the restoration.412 public var version: Int413}414415// MARK: - Tags416417/// A tag of the workspace (`GET /api/tags`).418public struct TagSummary: Codable, Sendable, Equatable, Identifiable {419 public var id: String420 public var name: String421 public var color: String?422 /// Number of pages carrying the tag.423 public var pages: Int?424}425