Repository Public
1// SP Notes Core2// File: Sources/SPNotesAPI/NotesAPI+GraphLinks.swift3// Description: The 2.x graph routes: backlinks and unlinked mentions, page neighbourhood, AI link suggestions.4// (`/api/graph?view=`, relations, concepts and insights are the 3.0 graph: another file.)5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation910extension NotesAPI {11 // MARK: - Backlinks1213 /// `GET /api/graph/backlinks[?q=&pageId=]` — pages ranked by incoming links (`search` filters by title) and the14 /// unlinked mentions (`pageID` keeps those that involve that page).15 public func backlinks(search: String? = nil, pageID: String? = nil) async throws -> BacklinksOverview {16 try await client.decode(BacklinksOverview.self, .get("/api/graph/backlinks", query: Self.item("q", search) + Self.item("pageId", pageID)))17 }1819 private struct MentionBody: Encodable {20 var action: MentionAction21 var fromId: String22 var toId: String23 }2425 /// `POST /api/graph/backlinks` `{ action, fromId, toId }` — links, dismisses or restores an unlinked mention.26 /// `fromID` = the mentioning page. `400` (no code) to link a page to itself, `404` unknown page.27 @discardableResult28 public func resolveMention(_ action: MentionAction, fromID: String, toID: String, idempotencyKey: String? = nil) async throws -> OKResult {29 try await client.decode(OKResult.self, .json(.post, "/api/graph/backlinks", body: MentionBody(action: action, fromId: fromID, toId: toID), idempotencyKey: idempotencyKey))30 }3132 // MARK: - Neighbourhood3334 /// `GET /api/graph/neighbors?pageId=&depth=&suggestions=&linked=` — the mini graph around a page.35 /// - Parameters:36 /// - depth: 1…3 hops (server default 1).37 /// - includeSuggestions: `false` leaves the pending AI suggestions out of the graph.38 /// - includeLinked: also returns `linked` (the linked pages) and `suggestions` (pending, for that page).39 public func graphNeighbors(pageID: String, depth: Int? = nil, includeSuggestions: Bool = true, includeLinked: Bool = false) async throws -> GraphNeighborhood {40 var query = [URLQueryItem(name: "pageId", value: pageID)] + Self.item("depth", depth.map(String.init))41 if !includeSuggestions { query.append(URLQueryItem(name: "suggestions", value: "0")) }42 query += Self.flag("linked", includeLinked)43 return try await client.decode(GraphNeighborhood.self, .get("/api/graph/neighbors", query: query))44 }4546 // MARK: - Suggestions4748 /// `GET /api/graph/suggestions[?status=&pageId=]` — the AI link suggestions in one status, and the counts.49 public func linkSuggestions(status: LinkSuggestionStatus = .suggested, pageID: String? = nil) async throws -> LinkSuggestionList {50 let query = [URLQueryItem(name: "status", value: status.rawValue)] + Self.item("pageId", pageID)51 return try await client.decode(LinkSuggestionList.self, .get("/api/graph/suggestions", query: query))52 }5354 private struct DecisionBody: Encodable {55 var id: String56 var status: LinkSuggestionStatus57 }5859 /// `PATCH /api/graph/suggestions` `{ id, status }` — `.accepted` turns the suggestion into a real link,60 /// `.rejected` discards it for good, `.suggested` undoes a decision. `404` (no code) for an unknown suggestion.61 @discardableResult62 public func decideLinkSuggestion(id: String, status: LinkSuggestionStatus, idempotencyKey: String? = nil) async throws -> LinkSuggestionDecision {63 try await client.decode(LinkSuggestionDecision.self, .json(.patch, "/api/graph/suggestions", body: DecisionBody(id: id, status: status), idempotencyKey: idempotencyKey))64 }6566 private struct SuggestBody: Encodable {67 var action = "suggest"68 var pageId: String?69 var inline: Bool?70 }7172 /// `POST /api/graph/suggestions` `{ action: "suggest", pageId?, inline? }` — asks for link suggestions.73 /// **Calls a paid model** as soon as the page has semantically close candidates (a page without embeddings is74 /// skipped for free). `inline` (with a page) runs now and returns `result`; otherwise a job is queued (the whole75 /// workspace when `pageID` is nil).76 public func requestLinkSuggestions(pageID: String? = nil, inline: Bool = false) async throws -> LinkSuggestRequestResult {77 try await client.decode(LinkSuggestRequestResult.self, .json(.post, "/api/graph/suggestions", body: SuggestBody(pageId: pageID, inline: inline ? true : nil)))78 }79}80