Repository Public
1// SP Notes Core2// File: Sources/SPNotesSync/Repositories/KnowledgeRepository.swift3// Description: Server-computed read models for the apps — knowledge health, daily brief, living blocks (queries), semantic zoom — fetched from the server and cached with their fetch date for offline reading. Nothing is recomputed on the device.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai7import Foundation8import SPNotesAPI9import SPNotesStore1011public struct KnowledgeRepository: Sendable {12 let context: RepositoryContext13 public init(context: RepositoryContext) { self.context = context }1415 public func health(inactiveDays: Int? = nil, policy: CachePolicy = .networkFirst) async throws -> Cached<KnowledgeHealth> {16 try await context.require(ServerFeature.health)17 return try await context.read(CacheKey.health + (inactiveDays.map { ".\($0)" } ?? ""), policy: policy) { try await context.api.knowledgeHealth(inactiveDays: inactiveDays) }18 }1920 /// The brief of the day in the device's time zone (no model is called).21 public func brief(timeZone: TimeZone = .current, policy: CachePolicy = .networkFirst) async throws -> Cached<DailyBrief> {22 try await context.require(ServerFeature.brief)23 return try await context.read(CacheKey.brief, policy: policy) { try await context.api.brief(timeZone: timeZone.identifier) }24 }2526 /// Asks for the AI summary of the brief: **one paid model call, only on an explicit user action**. The result is27 /// marked AI (`ai: true`, `model`) and must be shown as such.28 public func summarizeBrief(timeZone: TimeZone = .current) async throws -> BriefSummary {29 let summary = try await context.online { try await context.api.summarizeBrief(timeZone: timeZone.identifier) }30 try? await context.store.setCached(CacheKey.briefSummary, json: (try? APIJSON.encoder().encode(summary)) ?? Data("null".utf8))31 return summary32 }3334 /// The cache key of a living-view query (`kv_cache`): lets an app or a test seed or look up the stored result of35 /// `query(_:policy:)` without a network attempt.36 public static func cacheKey(for query: LiveQuery) -> String {37 CacheKey.query(SyncEngine.fingerprint((try? APIJSON.encoder().encode(query)) ?? Data()))38 }3940 /// Resolves a living block (`queryView`, or a `chart` with a source). Cached per query, so the block still shows41 /// its last rows offline (with their date).42 public func query(_ query: LiveQuery, policy: CachePolicy = .networkFirst) async throws -> Cached<LiveQueryResult> {43 try await context.require(ServerFeature.query)44 return try await context.read(Self.cacheKey(for: query), policy: policy) { try await context.api.query(query) }45 }4647 /// Semantic zoom. Level 2 (outline) and 3 (full) are computed without a model; level 1 is the AI synopsis48 /// (`pageSynopsis`). A server without level 1 → `.unsupported`.49 public func zoom(pageId: String, level: Int = 2, policy: CachePolicy = .networkFirst) async throws -> Cached<PageZoom> {50 try await context.require(ServerFeature.zoom)51 return try await context.read(CacheKey.zoom(pageId: pageId, level: level), policy: policy) { try await context.api.pageZoom(pageID: pageId, level: level) }52 }5354 /// The AI synopsis of a page (zoom level 1). `cachedOnly: true` (default) never spends: `status == "missing"`55 /// when nothing valid is cached on the server. `cachedOnly: false` may make one cheap model call — on an explicit56 /// user action only. Always shown as AI.57 public func synopsis(pageId: String, cachedOnly: Bool = true, model: String? = nil, policy: CachePolicy = .networkFirst) async throws -> Cached<ZoomSynopsis> {58 do {59 return try await context.read(CacheKey.zoom(pageId: pageId, level: 1), policy: policy) { try await context.api.pageSynopsis(pageID: pageId, cachedOnly: cachedOnly, model: model) }60 } catch RepositoryError.server(let error) where error.isRouteMissing {61 throw RepositoryError.unsupported(feature: "zoom-ai")62 } catch RepositoryError.notFound where true {63 throw RepositoryError.unsupported(feature: "zoom-ai")64 }65 }66}67