Repository Public
1// SP Notes Core2// File: Sources/SPNotesAPI/NotesAPI+Knowledge.swift3// Description: Routes of knowledge health, the brief, living blocks and semantic zoom (API-NEXT §4.5, §4.6, §4.7,4// §4.9; AI synopsis: API-NEXT-AI §4).5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation910extension NotesAPI {11 // MARK: - Knowledge health1213 /// `GET /api/health/knowledge[?inactiveDays=]` — orphans, broken links, missing references, duplicates, untitled14 /// pages, inactive projects, open tasks. Authenticated (the public probe is `health()`).15 /// - Parameter inactiveDays: 1…3650 (server default 30).16 public func knowledgeHealth(inactiveDays: Int? = nil) async throws -> KnowledgeHealth {17 let query = inactiveDays.map { [URLQueryItem(name: "inactiveDays", value: String($0))] } ?? []18 return try await client.decode(KnowledgeHealth.self, .get("/api/health/knowledge", query: query))19 }2021 // MARK: - Brief2223 /// `GET /api/brief[?tz=]` — the daily brief; no model is called. `400 bad_request` for an unknown zone.24 /// - Parameter timeZone: IANA identifier (`TimeZone.current.identifier`); `nil` = the server's zone.25 public func brief(timeZone: String? = nil) async throws -> DailyBrief {26 let query = timeZone.map { [URLQueryItem(name: "tz", value: $0)] } ?? []27 return try await client.decode(DailyBrief.self, .get("/api/brief", query: query))28 }2930 private struct BriefSummaryBody: Encodable { var tz: String? }3132 /// `POST /api/brief/summary` — **one paid model call** over the titles and counts of the brief (never the note33 /// contents); call it only on an explicit user request. The result is stored and returned by `brief()` as34 /// `aiSummary`. `502 ai_empty` when the model returns nothing, `503` without a usable model.35 public func summarizeBrief(timeZone: String? = nil) async throws -> BriefSummary {36 try await client.decode(BriefSummary.self, .json(.post, "/api/brief/summary", body: BriefSummaryBody(tz: timeZone)))37 }3839 // MARK: - Living blocks4041 /// `POST /api/query` — resolves a `queryView` (or the live data of a `chart`). Read-only and safe to repeat.42 /// `400 bad_request` (missing `databaseId` / `pageId`, bad `status`, bad date), `404` unknown database or view.43 public func query(_ query: LiveQuery) async throws -> LiveQueryResult {44 try await client.decode(LiveQueryResult.self, .json(.post, "/api/query", body: query))45 }4647 // MARK: - Semantic zoom4849 /// `GET /api/pages/<id>/zoom?level=` — level 2 (the outline, no model; the server default), 3 (the document) or50 /// 1 (the AI synopsis, `PageZoom.synopsis`: `501 not_implemented` on a server without it). Works on a trashed51 /// page. `400 bad_request` for another level.52 public func pageZoom(pageID: String, level: Int = 2) async throws -> PageZoom {53 try await client.decode(PageZoom.self, .get("/api/pages/\(HTTPRequest.segment(pageID))/zoom", query: [URLQueryItem(name: "level", value: String(level))]))54 }5556 /// `GET /api/pages/<id>/zoom/ai` — the AI synopsis. Generated when missing or stale (**one paid model call**)57 /// unless `cachedOnly` (`status: "missing"` then, never a provider call). `503 no_model`,58 /// `502 provider_error | refused`.59 /// - Parameter model: a model id of the catalogue, for a manual choice.60 public func pageSynopsis(pageID: String, cachedOnly: Bool = false, model: String? = nil) async throws -> ZoomSynopsis {61 var items: [URLQueryItem] = []62 if cachedOnly { items.append(URLQueryItem(name: "cachedOnly", value: "1")) }63 if let model { items.append(URLQueryItem(name: "model", value: model)) }64 return try await client.decode(ZoomSynopsis.self, .get("/api/pages/\(HTTPRequest.segment(pageID))/zoom/ai", query: items))65 }6667 private struct SynopsisBody: Encodable { var model: String? }6869 /// `POST /api/pages/<id>/zoom/ai` `{model?}` — regenerates the synopsis (**one paid model call**).70 public func regeneratePageSynopsis(pageID: String, model: String? = nil) async throws -> ZoomSynopsis {71 try await client.decode(ZoomSynopsis.self, .json(.post, "/api/pages/\(HTTPRequest.segment(pageID))/zoom/ai", body: SynopsisBody(model: model)))72 }73}74