Repository Public
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