SPB Git

Repository Public

NotesAPI+GraphLinks.swift 4.5 KB 80 lines swift

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

Theme