SPB Git

Repository Public

PageModels.swift 15.7 KB 425 lines swift

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
Files main
Menu

Theme