SPB Git

Repository Public

NotesAPI+NextCore.swift 4.4 KB 85 lines swift

1// SP Notes Core2// File: Sources/SPNotesAPI/NotesAPI+NextCore.swift3// Description: Routes of the 3.0 foundation used by the sync engine: meta, the entity change feed, tasks with4//              client-chosen ids, canvases (API-NEXT §1, §3, §4.2, §4.8).5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation910extension NotesAPI {11    // MARK: - Meta1213    /// `GET /api/meta`. A 2.x server answers 404: `.legacy` (`api: 2`, no feature) is returned, never an error.14    public func meta() async throws -> ServerMeta {15        do {16            return try await client.decode(ServerMeta.self, .get("/api/meta"))17        } catch let error as APIError where error.isNotFound {18            return .legacy19        }20    }2122    // MARK: - Entity feed2324    /// `GET /api/sync?kinds=…` — the change feed with the entity kinds (API-NEXT §3). `kinds` empty = the 2.x answer.25    /// **A cursor is only valid for the set of kinds it was obtained with.**26    public func sync(since: Int64, limit: Int? = nil, kinds: [String]) async throws -> SyncPage {27        var query = [URLQueryItem(name: "since", value: String(since))]28        if let limit { query.append(URLQueryItem(name: "limit", value: String(limit))) }29        if !kinds.isEmpty { query.append(URLQueryItem(name: "kinds", value: kinds.joined(separator: ","))) }30        return try await client.decode(SyncPage.self, .get("/api/sync", query: query))31    }3233    // MARK: - Tasks (3.0)3435    /// `GET /api/tasks` with the 3.0 filters. `since` = delta by revision (deleted tasks included, whatever `includeDone`).36    public func tasks(includeDone: Bool = false, pageId: String?, since: Int64? = nil) async throws -> [TaskItem] {37        var query: [URLQueryItem] = []38        if includeDone { query.append(URLQueryItem(name: "done", value: "1")) }39        if let pageId { query.append(URLQueryItem(name: "pageId", value: pageId)) }40        if let since { query.append(URLQueryItem(name: "since", value: String(since))) }41        return try await client.decode([TaskItem].self, .get("/api/tasks", query: query))42    }4344    /// `POST /api/tasks` with a client-chosen `draft.id`: idempotent on the id (`existing` = the stored task came45    /// back untouched, whatever its state now — edited, done or deleted).46    public func createTaskIdempotent(_ draft: TaskDraft) async throws -> Created<TaskItem> {47        let response = try await client.send(.json(.post, "/api/tasks", body: draft))48        return Created(value: try response.decode(TaskItem.self), existing: response.isExisting)49    }5051    /// `GET /api/tasks/<id>` — in any state (a deleted task answers 200 with `deletedAt`).52    public func task(id: String) async throws -> TaskItem {53        try await client.decode(TaskItem.self, .get("/api/tasks/\(HTTPRequest.segment(id))"))54    }5556    /// `PATCH /api/tasks/<id>`. `404` for an unknown or deleted task.57    public func updateTask(id: String, _ changes: TaskChanges, idempotencyKey: String? = nil) async throws -> TaskItem {58        try await client.decode(TaskItem.self, .json(.patch, "/api/tasks/\(HTTPRequest.segment(id))", body: changes, idempotencyKey: idempotencyKey))59    }6061    /// `DELETE /api/tasks/<id>` — soft delete, idempotent (`deleted: false` when it already was). `404` unknown id.62    @discardableResult63    public func removeTask(id: String) async throws -> TaskDeleteResult {64        try await client.decode(TaskDeleteResult.self, HTTPRequest(method: .delete, path: "/api/tasks/\(HTTPRequest.segment(id))"))65    }6667    // MARK: - Canvas6869    /// `GET /api/canvases/<pageId>` (readable in the trash too). `404 not_found | not_canvas`.70    public func canvas(pageID: String) async throws -> CanvasEnvelope {71        try await client.decode(CanvasEnvelope.self, .get("/api/canvases/\(HTTPRequest.segment(pageID))"))72    }7374    private struct CanvasBody: Encodable {75        var data: RawJSON76        var baseVersion: Int77    }7879    /// `PUT /api/canvases/<pageId>` — written only if the canvas is still at `baseVersion`. On `409 conflict` the80    /// thrown error carries the server copy (`APIError.canvasConflict`): merge by node / edge id and send again.81    public func saveCanvas(pageID: String, data: RawJSON, baseVersion: Int) async throws -> CanvasSaveResult {82        try await client.decode(CanvasSaveResult.self, .json(.put, "/api/canvases/\(HTTPRequest.segment(pageID))", body: CanvasBody(data: data, baseVersion: baseVersion)))83    }84}85
Files main
Menu

Theme