Repository Public
1// SP Notes Core2// File: Sources/SPNotesAPI/WorkspaceModels.swift3// Description: Models of the home dashboard, the settings (profile, preferences, audit log), the page lists (recent,4// pinned, archived, trash, section, children) and the trash purge.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation910// MARK: - Page lists1112/// The lists of `GET /api/pages?view=`.13public enum PageListView: Sendable, Equatable {14 /// Recently opened or edited (captures still in the inbox left out).15 case recent16 case pinned17 /// Trashed pages, most recently deleted first.18 case trash19 case archived20 /// The pages of a section (database rows left out), most recently edited first.21 case section(PageSection)22 /// The live, non-archived sub-pages of a page, in position order.23 case children(String)2425 public var queryValue: String {26 switch self {27 case .recent: return "recent"28 case .pinned: return "pinned"29 case .trash: return "trash"30 case .archived: return "archived"31 case .section(let section): return "section:\(section.rawValue)"32 case .children(let id): return "children:\(id)"33 }34 }35}3637/// A page in a list: `GET /api/pages?view=` and the page lists of the dashboard (which omit `parentId`,38/// `deletedAt` and `databaseId`). No document: fetch the page to read it.39public struct PageListItem: Codable, Sendable, Equatable, Identifiable {40 public var id: String41 public var title: String42 public var icon: String?43 public var section: String?44 public var type: String?45 public var parentId: String?46 public var updatedAt: Date?47 public var lastOpenedAt: Date?48 /// Set in the trash list.49 public var deletedAt: Date?50 public var wordCount: Int?51 public var pinned: Bool?52 /// The page properties (raw JSON object).53 public var properties: RawJSON?54 /// Set for the page of a database row.55 public var databaseId: String?56}5758/// Answer of `POST /api/trash` `{ action: "purge-old" }`.59public struct TrashPurgeResult: Codable, Sendable, Equatable {60 public var ok: Bool61 /// Pages permanently deleted.62 public var purged: Int?63 /// Pages still in the trash.64 public var remaining: Int?65 public var autoPurgeDays: Int?66}6768// MARK: - Dashboard6970/// The widget types of the home dashboard (`DashboardWidget.type`).71public enum DashboardWidgetType {72 public static let quickCapture = "quick_capture"73 public static let recentPages = "recent_pages"74 public static let pinned = "pinned"75 public static let tasksDue = "tasks_due"76 public static let activeProjects = "active_projects"77 public static let researchActivity = "research_activity"78 public static let recentlyModified = "recently_modified"79 public static let aiSummary = "ai_summary"80 public static let graphHighlights = "graph_highlights"81 public static let aiChat = "ai_chat"82 public static let usage = "usage"83 public static let all = [quickCapture, recentPages, pinned, tasksDue, activeProjects, researchActivity, recentlyModified, aiSummary, graphHighlights, aiChat, usage]84}8586/// A widget of the dashboard layout.87public struct DashboardWidget: Codable, Sendable, Equatable, Identifiable {88 /// 1…64 characters, chosen by the client.89 public var id: String90 /// See `DashboardWidgetType` (the server refuses unknown types).91 public var type: String92 /// `half`, `wide` or `third`.93 public var size: String94 /// Free-form JSON object.95 public var config: RawJSON?9697 public init(id: String, type: String, size: String, config: RawJSON? = nil) {98 self.id = id99 self.type = type100 self.size = size101 self.config = config102 }103}104105/// The layout: `layout` of the dashboard and the answer of `PUT /api/dashboard`.106public struct DashboardLayout: Codable, Sendable, Equatable {107 public var widgets: [DashboardWidget]108 /// `false`: the default layout of the server.109 public var custom: Bool?110}111112public struct DashboardUser: Codable, Sendable, Equatable {113 public var displayName: String?114 public var username: String?115 public var preferences: RawJSON?116}117118/// An open task due within 7 days (or overdue).119public struct DashboardTask: Codable, Sendable, Equatable, Identifiable {120 public var id: String121 public var title: String122 public var status: String?123 public var priority: String?124 public var dueAt: Date?125 public var project: String?126 public var pageId: String?127 public var pageTitle: String?128}129130public struct DashboardExperiment: Codable, Sendable, Equatable, Identifiable {131 public var id: String132 public var name: String?133 public var status: String?134 public var pageId: String?135 public var updatedAt: Date?136}137138public struct DashboardResearchCounts: Codable, Sendable, Equatable {139 public var references: Int?140 public var experiments: Int?141 public var researchPages: Int?142}143144public struct DashboardResearch: Codable, Sendable, Equatable {145 public var pages: [PageListItem]?146 public var experiments: [DashboardExperiment]?147 public var counts: DashboardResearchCounts?148}149150/// A highly connected page.151public struct DashboardGraphPage: Codable, Sendable, Equatable, Identifiable {152 public var id: String153 public var title: String?154 public var icon: String?155 public var section: String?156 public var degree: Int?157}158159public struct DashboardGraph: Codable, Sendable, Equatable {160 public var top: [DashboardGraphPage]?161 /// Link suggestions waiting for review.162 public var suggested: Int?163 /// Accepted edges.164 public var edges: Int?165}166167public struct DashboardUsageToday: Codable, Sendable, Equatable {168 public var calls: Int?169 public var costUsd: Double?170 public var errors: Int?171}172173/// AI usage of the day against the daily budget.174public struct DashboardUsage: Codable, Sendable, Equatable {175 public var today: DashboardUsageToday?176 public var budgetUsd: Double?177}178179/// The stored weekly AI digest (`GET /api/dashboard/summary`). Only `null` was observed on the scratch server (no180/// digest generated): every field is optional.181public struct DashboardSummary: Codable, Sendable, Equatable {182 /// Markdown.183 public var text: String?184 public var model: String?185 public var provider: String?186 public var costUsd: Double?187 public var latencyMs: Double?188 public var at: Date?189 /// Pages and tasks the digest was written from.190 public var pages: Int?191 public var tasks: Int?192 public var reason: String?193}194195public struct DashboardStats: Codable, Sendable, Equatable {196 public var editedThisWeek: Int?197}198199/// `GET /api/dashboard` — everything the home widgets need in one round trip.200public struct Dashboard: Codable, Sendable, Equatable {201 public var layout: DashboardLayout?202 public var user: DashboardUser?203 public var recent: [PageListItem]?204 public var pinned: [PageListItem]?205 public var modified: [PageListItem]?206 public var projects: [PageListItem]?207 public var tasks: [DashboardTask]?208 public var research: DashboardResearch?209 public var graph: DashboardGraph?210 public var usage: DashboardUsage?211 public var summary: DashboardSummary?212 public var stats: DashboardStats?213}214215// MARK: - Settings216217public struct SettingsWorkspace: Codable, Sendable, Equatable, Identifiable {218 public var id: String219 public var name: String?220}221222/// `GET /api/settings` — the profile, the preferences and a few workspace-level settings.223public struct UserSettings: Codable, Sendable, Equatable, Identifiable {224 /// The user id.225 public var id: String226 public var username: String?227 public var displayName: String?228 public var email: String?229 /// Free-form JSON object shared by every client of the account: namespace your keys.230 public var preferences: RawJSON?231 public var createdAt: Date?232 public var workspace: SettingsWorkspace?233 /// The daily AI budget.234 public var aiBudgetUsd: Double?235 /// The current session.236 public var sessionId: String?237}238239/// Body of `PATCH /api/settings`. `preferences` is merged key by key into the stored object (a key cannot be240/// removed, only set to `null`).241public struct SettingsChanges: Encodable, Sendable, Equatable {242 /// 1…100 characters.243 public var displayName: String?244 /// `.null` removes the address.245 public var email: PatchValue<String>?246 public var preferences: RawJSON?247248 public init(displayName: String? = nil, email: PatchValue<String>? = nil, preferences: RawJSON? = nil) {249 self.displayName = displayName250 self.email = email251 self.preferences = preferences252 }253254 enum CodingKeys: String, CodingKey { case displayName, email, preferences }255256 public func encode(to encoder: Encoder) throws {257 var c = encoder.container(keyedBy: CodingKeys.self)258 try c.encodeIfPresent(displayName, forKey: .displayName)259 try c.encodePatch(email, forKey: .email)260 try c.encodeIfPresent(preferences, forKey: .preferences)261 }262}263264/// Answer of `PATCH /api/settings`.265public struct SettingsUpdateResult: Codable, Sendable, Equatable {266 public var displayName: String?267 public var email: String?268 /// The whole preferences object after the merge.269 public var preferences: RawJSON?270}271272/// An entry of the audit log (`GET /api/settings/audit`).273public struct AuditEntry: Codable, Sendable, Equatable, Identifiable {274 public var id: String275 /// `page.create`, `settings.update`, `trash.empty`…276 public var action: String277 public var targetType: String?278 public var targetId: String?279 /// Ids, counts and key names only (raw JSON object).280 public var detail: RawJSON?281 public var ip: String?282 public var createdAt: Date?283}284