feat: Client Integration Support

Signed-off-by: Iva Horn <iva.horn@nextcloud.com>

Author: i2h3

Sources/NextcloudCapabilitiesKit/Capabilities.swift

@@ -7,6 +7,7 @@ public struct Capabilities: Equatable, Sendable {
     public let major: Int64
     public let minor: Int64
     public let patch: Int64
+    public let clientIntegration: ClientIntegration?
     public let core: Core?
     public let bruteForce: BruteForce?
     public let files: Files?
@@ -51,6 +52,7 @@ public struct Capabilities: Equatable, Sendable {
         minor = Int64(minorValue)
         patch = Int64(microValue)
 
+        clientIntegration = ClientIntegration(capabilities: capabilities)
         core = Core(capabilities: capabilities)
         bruteForce = BruteForce(capabilities: capabilities)
         files = Files(capabilities: capabilities)

Sources/NextcloudCapabilitiesKit/ClientIntegration/ClientIntegration.swift

@@ -0,0 +1,45 @@
+//  SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+//  SPDX-License-Identifier: LGPL-3.0-or-later
+
+import Foundation
+
+///
+/// The capability of client integration.
+///
+/// The presence of this capability indicates that clients can offer file context menu actions defined by and run on the server.
+///
+public struct ClientIntegration: Equatable, Sendable {
+    ///
+    /// Server apps and what context menu items they offer.
+    ///
+    public let apps: [ClientIntegrationApp]
+
+    ///
+    /// Try to parse the server response for client integration capabilities.
+    ///
+    /// - Parameters:
+    ///     - capabilities: The `capabilities` dictionary as returned in the JSON from the server.
+    ///
+    /// - Returns: `nil`, if the parsing failed.
+    ///
+    init?(capabilities: [String: Any]) {
+        guard let capabilities = capabilities["client_integration"] as? [String: Any] else {
+            debugPrint("No client_integration data in received capabilities.")
+            return nil
+        }
+
+        var apps = [ClientIntegrationApp]()
+
+        for key in capabilities.keys.sorted() {
+            guard let data = capabilities[key] as? [String: Any] else {
+                continue
+            }
+
+            if let app = ClientIntegrationApp(app: key, data: data) {
+                apps.append(app)
+            }
+        }
+
+        self.apps = apps
+    }
+}

Sources/NextcloudCapabilitiesKit/ClientIntegration/ClientIntegrationApp.swift

@@ -0,0 +1,61 @@
+//  SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+//  SPDX-License-Identifier: LGPL-3.0-or-later
+
+import Foundation
+
+///
+/// Data model for a server app offering client integration.
+///
+public struct ClientIntegrationApp: Equatable, Sendable {
+    ///
+    /// The app identifier.
+    ///
+    public let identifier: String
+
+    ///
+    /// Context menu items offered by this app.
+    ///
+    public let contextMenuItems: [ClientIntegrationContextMenuItem]
+
+    ///
+    /// The server app version.
+    ///
+    public let version: Double
+
+    init?(app: String, data: [String: Any]) {
+        identifier = app
+
+        let versionValue = data["version"]
+        let parsedVersion: Double? = if let version = versionValue as? Double {
+            version
+        } else if let version = versionValue as? Int {
+            Double(version)
+        } else if let version = versionValue as? NSNumber {
+            version.doubleValue
+        } else {
+            nil
+        }
+
+        guard let version = parsedVersion else {
+            return nil
+        }
+
+        self.version = version
+
+        guard let contextMenuItems = data["context-menu"] as? [[String: Any]] else {
+            return nil
+        }
+
+        var items = [ClientIntegrationContextMenuItem]()
+
+        for contextMenuItem in contextMenuItems {
+            guard let item = ClientIntegrationContextMenuItem(data: contextMenuItem) else {
+                continue
+            }
+
+            items.append(item)
+        }
+
+        self.contextMenuItems = items
+    }
+}

Sources/NextcloudCapabilitiesKit/ClientIntegration/ClientIntegrationContextMenuItem.swift

@@ -0,0 +1,93 @@
+//  SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+//  SPDX-License-Identifier: LGPL-3.0-or-later
+
+import Foundation
+
+///
+/// Data model for a context menu item.
+///
+public struct ClientIntegrationContextMenuItem: Equatable, Sendable {
+    ///
+    /// A list of filters for MIME types.
+    ///
+    public let filters: [String]
+
+    ///
+    /// An absolute path for an image to display in the context menu.
+    ///
+    public let icon: String
+
+    ///
+    /// The HTTP verb to use when opening the ``path``.
+    ///
+    public let method: String
+
+    ///
+    /// The user-visible label for the context menu item.
+    ///
+    public let name: String
+
+    ///
+    /// Query parameters for the URL to open.
+    ///
+    /// Values might contain placeholders which must be substituted by the client.
+    ///
+    public let parameters: [String: String]
+
+    ///
+    /// The server address to open when this item is invoked.
+    ///
+    /// This is an absolute path on the server and not a fully qualified URL.
+    ///
+    public let path: String
+
+    init?(data: [String: Any]) {
+        // filters
+
+        guard let filters = data["mimetype_filters"] as? String else {
+            return nil
+        }
+
+        self.filters = filters.split(separator: ",").map { $0.trimmingCharacters(in: .whitespaces) }
+
+        // icon
+
+        guard let icon = data["icon"] as? String else {
+            return nil
+        }
+
+        self.icon = icon
+
+        // method
+
+        guard let method = data["method"] as? String else {
+            return nil
+        }
+
+        self.method = method
+
+        // name
+
+        guard let name = data["name"] as? String else {
+            return nil
+        }
+
+        self.name = name
+
+        // parameters
+
+        if let params = data["params"] as? [String: String] {
+            parameters = params
+        } else {
+            parameters = [:]
+        }
+
+        // path
+
+        guard let path = data["url"] as? String else {
+            return nil
+        }
+
+        self.path = path
+    }
+}

Tests/NextcloudCapabilitiesKitTests/ClientIntegration/ClientIntegrationAppTests.swift

@@ -0,0 +1,97 @@
+//  SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+//  SPDX-License-Identifier: LGPL-3.0-or-later
+
+@testable import NextcloudCapabilitiesKit
+import Testing
+
+@Suite("Client Integration App Tests")
+struct ClientIntegrationAppTests {
+    @Test("Decode with double version")
+    func decodeWithDoubleVersion() throws {
+        let data: [String: Any] = [
+            "version": 1.2,
+            "context-menu": [
+                [
+                    "icon": "/apps/assistant/img/client_integration/summarize.svg",
+                    "method": "POST",
+                    "mimetype_filters": "text/, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.oasis.opendocument.text, application/pdf",
+                    "name": "Summarize using AI",
+                    "url": "/ocs/v2.php/apps/assistant/api/v1/file-action/{fileId}/core:text2text:summary"
+                ]
+            ]
+        ]
+
+        let result = ClientIntegrationApp(app: "example", data: data)
+        #expect(result != nil)
+
+        let app = try #require(result)
+
+        // Verify identifier
+        #expect(app.identifier == "example")
+
+        // Verify version
+        #expect(app.version == 1.2)
+    }
+
+    @Test("Decode with integer version")
+    func decodeWithIntegerVersion() throws {
+        let data: [String: Any] = [
+            "version": 2,
+            "context-menu": []
+        ]
+
+        let result = ClientIntegrationApp(app: "test-app", data: data)
+        #expect(result != nil)
+
+        let app = try #require(result)
+
+        // Verify integer version is converted to double
+        #expect(app.version == 2.0)
+        #expect(app.identifier == "test-app")
+        #expect(app.contextMenuItems.isEmpty)
+    }
+
+    // MARK: - Negative Tests
+
+    @Test("Decode fails with missing version")
+    func decodeFailsWithMissingVersion() {
+        let data: [String: Any] = [
+            "context-menu": []
+        ]
+
+        let result = ClientIntegrationApp(app: "no-version", data: data)
+        #expect(result == nil)
+    }
+
+    @Test("Decode fails with invalid version type")
+    func decodeFailsWithInvalidVersionType() {
+        let data: [String: Any] = [
+            "version": "1.2.3",
+            "context-menu": []
+        ]
+
+        let result = ClientIntegrationApp(app: "invalid-version", data: data)
+        #expect(result == nil)
+    }
+
+    @Test("Decode fails with missing context-menu")
+    func decodeFailsWithMissingContextMenu() {
+        let data: [String: Any] = [
+            "version": 1.0
+        ]
+
+        let result = ClientIntegrationApp(app: "no-context-menu", data: data)
+        #expect(result == nil)
+    }
+
+    @Test("Decode fails with invalid context-menu type")
+    func decodeFailsWithInvalidContextMenuType() {
+        let data: [String: Any] = [
+            "version": 1.0,
+            "context-menu": "not an array"
+        ]
+
+        let result = ClientIntegrationApp(app: "invalid-context-menu", data: data)
+        #expect(result == nil)
+    }
+}