release 0.8.0

- Add Attachment model with isImage computed property
- Add assets field to Issue, IssueComment, and PullRequest
- Add multipart/form-data upload support to ForgejoClient
- Add uploadIssueAttachment and uploadCommentAttachment to IssueService

.swiftformat

@@ -1,2 +1,3 @@
 --swiftversion 6.2
 --disable redundantMemberwiseInit
+--disable swiftTestingTestCaseNames

README.md

@@ -17,7 +17,7 @@ Add ForgejoKit as a dependency in your `Package.swift`:
 
 ```swift
 dependencies: [
-    .package(url: "https://codeberg.org/secana/ForgejoKit.git", from: "0.7.0"),
+    .package(url: "https://codeberg.org/secana/ForgejoKit.git", from: "0.8.0"),
 ],
 targets: [
     .target(

Sources/ForgejoKit/Models/Attachment.swift

@@ -0,0 +1,41 @@
+import Foundation
+
+public struct Attachment: Codable, Identifiable, Sendable {
+    public let id: Int
+    public let uuid: String
+    public let name: String
+    public let size: Int
+    public let browserDownloadUrl: String
+    public let type: String?
+    public let created: Date
+
+    public init(
+        id: Int, uuid: String, name: String, size: Int,
+        browserDownloadUrl: String,
+        type: String?, created: Date,
+    ) {
+        self.id = id
+        self.uuid = uuid
+        self.name = name
+        self.size = size
+        self.browserDownloadUrl = browserDownloadUrl
+        self.type = type
+        self.created = created
+    }
+
+    public var isImage: Bool {
+        if let type, type.hasPrefix("image/") { return true }
+        let ext = (name as NSString).pathExtension.lowercased()
+        return ["png", "jpg", "jpeg", "gif", "webp", "heic", "heif", "svg"].contains(ext)
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case uuid
+        case name
+        case size
+        case browserDownloadUrl = "browser_download_url"
+        case type
+        case created = "created_at"
+    }
+}

Sources/ForgejoKit/Models/Issue.swift

@@ -17,6 +17,7 @@ public struct Issue: Codable, Identifiable, Sendable {
     public let pullRequest: IssuePullRequest?
     public let comments: Int
     public let repository: Repository?
+    public let assets: [Attachment]?
 
     public init(
         id: Int, number: Int, title: String,
@@ -28,6 +29,7 @@ public struct Issue: Codable, Identifiable, Sendable {
         closedAt: Date? = nil, dueDate: Date? = nil,
         pullRequest: IssuePullRequest? = nil,
         comments: Int = 0, repository: Repository? = nil,
+        assets: [Attachment]? = nil,
     ) {
         self.id = id
         self.number = number
@@ -45,6 +47,7 @@ public struct Issue: Codable, Identifiable, Sendable {
         self.pullRequest = pullRequest
         self.comments = comments
         self.repository = repository
+        self.assets = assets
     }
 
     enum CodingKeys: String, CodingKey {
@@ -64,6 +67,7 @@ public struct Issue: Codable, Identifiable, Sendable {
         case pullRequest = "pull_request"
         case comments
         case repository
+        case assets
     }
 }
 

Sources/ForgejoKit/Models/IssueComment.swift

@@ -6,13 +6,19 @@ public struct IssueComment: Codable, Identifiable, Sendable {
     public let user: User
     public let createdAt: Date
     public let updatedAt: Date
+    public let assets: [Attachment]?
 
-    public init(id: Int, body: String, user: User, createdAt: Date, updatedAt: Date) {
+    public init(
+        id: Int, body: String, user: User,
+        createdAt: Date, updatedAt: Date,
+        assets: [Attachment]? = nil,
+    ) {
         self.id = id
         self.body = body
         self.user = user
         self.createdAt = createdAt
         self.updatedAt = updatedAt
+        self.assets = assets
     }
 
     enum CodingKeys: String, CodingKey {
@@ -21,5 +27,6 @@ public struct IssueComment: Codable, Identifiable, Sendable {
         case user
         case createdAt = "created_at"
         case updatedAt = "updated_at"
+        case assets
     }
 }

Sources/ForgejoKit/Models/PullRequest.swift

@@ -23,6 +23,7 @@ public struct PullRequest: Codable, Identifiable, Sendable {
     public let closedAt: Date?
     public let mergedAt: Date?
     public let htmlUrl: String?
+    public let assets: [Attachment]?
 
     public init(
         id: Int, number: Int, title: String,
@@ -38,6 +39,7 @@ public struct PullRequest: Codable, Identifiable, Sendable {
         createdAt: Date, updatedAt: Date,
         closedAt: Date? = nil, mergedAt: Date? = nil,
         htmlUrl: String? = nil,
+        assets: [Attachment]? = nil,
     ) {
         self.id = id
         self.number = number
@@ -61,6 +63,7 @@ public struct PullRequest: Codable, Identifiable, Sendable {
         self.closedAt = closedAt
         self.mergedAt = mergedAt
         self.htmlUrl = htmlUrl
+        self.assets = assets
     }
 
     enum CodingKeys: String, CodingKey {
@@ -86,6 +89,7 @@ public struct PullRequest: Codable, Identifiable, Sendable {
         case closedAt = "closed_at"
         case mergedAt = "merged_at"
         case htmlUrl = "html_url"
+        case assets
     }
 }
 

Sources/ForgejoKit/Models/WorkflowRun.swift

@@ -3,7 +3,7 @@ import Foundation
 /// Represents a single Forgejo Actions run.
 ///
 /// Mirrors the Forgejo `ActionRun` schema. Note: Forgejo merges status and
-/// conclusion into a single `status` field — values are
+/// conclusion into a single `status` field, values are
 /// `success`, `failure`, `cancelled`, `skipped`, `running`, `waiting`,
 /// `blocked`, `unknown`.
 public struct WorkflowRun: Codable, Identifiable, Sendable {

Sources/ForgejoKit/Models/WorkflowRunView.swift

@@ -3,7 +3,7 @@ import Foundation
 /// Response from Forgejo's internal web route
 /// `POST /{owner}/{repo}/actions/runs/{runIndex}/jobs/{jobIndex}`.
 ///
-/// **Experimental.** This endpoint is the web UI's own JSON contract — it is
+/// **Experimental.** This endpoint is the web UI's own JSON contract, it is
 /// not part of `/api/v1` and may change between Forgejo releases without
 /// notice. Use only for surfaces where graceful degradation is acceptable.
 public struct WorkflowRunView: Codable, Sendable {

Sources/ForgejoKit/Networking/URLSessionManager.swift

@@ -3,7 +3,7 @@ import Foundation
 public class URLSessionManager: NSObject, @unchecked Sendable {
     public let allowSelfSignedCertificates: Bool
     private let trustedHost: String?
-    // Initialized eagerly in init — safe for concurrent access as it's only written once.
+    // Initialized eagerly in init, safe for concurrent access as it's only written once.
     private var _session: URLSession!
     public var session: URLSession {
         _session

Sources/ForgejoKit/Services/ForgejoClient.swift

@@ -4,7 +4,7 @@ public final class ForgejoClient: Sendable {
     public let serverURL: String
     public let username: String
 
-    private enum AuthCredential: Sendable {
+    private enum AuthCredential {
         case basic(base64: String)
         case token(String)
         case bearer(String)
@@ -204,7 +204,7 @@ public final class ForgejoClient: Sendable {
             else { throw AuthenticationError.invalidResponse }
             return sha1
         case 400, 422:
-            // Token name already taken — Forgejo returns 400, some versions use 422
+            // Token name already taken, Forgejo returns 400, some versions use 422
             let body = String(data: data, encoding: .utf8) ?? ""
             guard body.contains("name") else {
                 throw AuthenticationError.from(statusCode: httpResponse.statusCode, body: body)
@@ -372,6 +372,53 @@ extension ForgejoClient {
         try JSONEncoder().encode(body)
     }
 
+    /// Builds a multipart/form-data body with a single file part named "attachment".
+    static func buildMultipartBody(
+        fileData: Data,
+        fileName: String,
+        mimeType: String,
+        boundary: String,
+    ) -> Data {
+        var body = Data()
+        body.append(contentsOf: "--\(boundary)\r\n".utf8)
+        let disposition = "Content-Disposition: form-data; name=\"attachment\"; filename=\"\(fileName)\"\r\n"
+        body.append(contentsOf: disposition.utf8)
+        body.append(contentsOf: "Content-Type: \(mimeType)\r\n\r\n".utf8)
+        body.append(fileData)
+        body.append(contentsOf: "\r\n--\(boundary)--\r\n".utf8)
+        return body
+    }
+
+    func performMultipartRequest<T: Decodable>(
+        url: URL,
+        fileData: Data,
+        fileName: String,
+        mimeType: String,
+        boundary: String = UUID().uuidString,
+        responseType: T.Type,
+    ) async throws -> T {
+        let body = Self.buildMultipartBody(
+            fileData: fileData, fileName: fileName, mimeType: mimeType, boundary: boundary,
+        )
+        var request = authenticatedRequest(url: url, method: "POST")
+        request.setValue("multipart/form-data; boundary=\(boundary)", forHTTPHeaderField: "Content-Type")
+        request.httpBody = body
+
+        let (data, response) = try await urlSessionManager.session.data(for: request)
+        guard let httpResponse = response as? HTTPURLResponse else {
+            throw ServiceError.invalidResponse
+        }
+        try validateStatus(httpResponse, data: data)
+
+        let decoder = JSONDecoder()
+        decoder.dateDecodingStrategy = forgejoDateDecodingStrategy
+        do {
+            return try decoder.decode(responseType, from: data)
+        } catch let error as DecodingError {
+            throw ServiceError.decodingFailed(detail: describeDecodingError(error))
+        }
+    }
+
     public static func normalizeServerURL(_ url: String) -> String {
         var normalized = url.trimmingCharacters(in: .whitespacesAndNewlines)
         while normalized.hasSuffix("/") {

Sources/ForgejoKit/Services/IssueService.swift

@@ -184,4 +184,37 @@ public final class IssueService: Sendable {
             responseType: IssueComment.self,
         )
     }
+
+    // swiftlint:disable:next function_parameter_count
+    public func uploadIssueAttachment(
+        owner: String, repo: String, index: Int,
+        fileData: Data, fileName: String, mimeType: String,
+    ) async throws -> Attachment {
+        let url = try client.makeRepoURL(owner: owner, repo: repo, path: "/issues/\(index)/assets")
+        return try await client.performMultipartRequest(
+            url: url,
+            fileData: fileData,
+            fileName: fileName,
+            mimeType: mimeType,
+            responseType: Attachment.self,
+        )
+    }
+
+    // swiftlint:disable:next function_parameter_count
+    public func uploadCommentAttachment(
+        owner: String, repo: String, commentId: Int,
+        fileData: Data, fileName: String, mimeType: String,
+    ) async throws -> Attachment {
+        let url = try client.makeRepoURL(
+            owner: owner, repo: repo,
+            path: "/issues/comments/\(commentId)/assets",
+        )
+        return try await client.performMultipartRequest(
+            url: url,
+            fileData: fileData,
+            fileName: fileName,
+            mimeType: mimeType,
+            responseType: Attachment.self,
+        )
+    }
 }

Sources/ForgejoKit/Services/WorkflowService.swift

@@ -1,7 +1,7 @@
 import Foundation
 
 /// Forgejo Actions API. Forgejo's Actions API is much smaller than Gitea's
-/// or GitHub's — there is no public endpoint to list workflow definitions,
+/// or GitHub's, there is no public endpoint to list workflow definitions,
 /// fetch jobs of a run, or stream job logs. Only run listing and run detail
 /// are exposed.
 public final class WorkflowService: Sendable {
@@ -114,7 +114,7 @@ public final class WorkflowService: Sendable {
         )
         // Forgejo's POST handler at this base path uses `attempt=0` which fails
         // for any run whose tasks are stored with the (1-based) attempt number.
-        // The matching GET endpoint 307-redirects to the latest-attempt URL —
+        // The matching GET endpoint 307-redirects to the latest-attempt URL,
         // resolve that first, then POST to the resolved attempt-suffixed URL.
         let postURL = await (try? client.discoverRedirectLocation(url: baseURL)) ?? baseURL
         let body = try client.encodeRequestBody(ViewRequestBody(logCursors: logCursors))

Tests/ForgejoKitTests/AttachmentTests.swift

@@ -0,0 +1,249 @@
+@testable import ForgejoKit
+import Foundation
+import Testing
+
+struct AttachmentTests {
+    private func decoder() -> JSONDecoder {
+        let dec = JSONDecoder()
+        dec.dateDecodingStrategy = forgejoDateDecodingStrategy
+        return dec
+    }
+
+    // MARK: - Model decoding
+
+    @Test func decodesAttachment() throws {
+        let json = """
+        {
+            "id": 1,
+            "uuid": "ee01801f-ffdb-4154-856b-77eab52aaad2",
+            "name": "screenshot.png",
+            "size": 222208,
+            "browser_download_url": "https://codeberg.org/attachments/ee01801f-ffdb-4154-856b-77eab52aaad2",
+            "type": "image/png",
+            "created_at": "2026-06-14T17:49:26Z"
+        }
+        """
+        let attachment = try decoder().decode(Attachment.self, from: Data(json.utf8))
+        #expect(attachment.id == 1)
+        #expect(attachment.uuid == "ee01801f-ffdb-4154-856b-77eab52aaad2")
+        #expect(attachment.name == "screenshot.png")
+        #expect(attachment.size == 222_208)
+        #expect(attachment.browserDownloadUrl == "https://codeberg.org/attachments/ee01801f-ffdb-4154-856b-77eab52aaad2")
+        #expect(attachment.type == "image/png")
+        #expect(attachment.isImage == true)
+    }
+
+    @Test func decodesAttachmentWithoutTypeField() throws {
+        // Forgejo API does not always include a type field, isImage falls back to file extension.
+        let json = """
+        {
+            "id": 3,
+            "uuid": "no-type-uuid",
+            "name": "photo.jpg",
+            "size": 10000,
+            "browser_download_url": "https://codeberg.org/attachments/no-type-uuid",
+            "created_at": "2026-01-01T00:00:00Z"
+        }
+        """
+        let attachment = try decoder().decode(Attachment.self, from: Data(json.utf8))
+        #expect(attachment.type == nil)
+        #expect(attachment.isImage == true)
+    }
+
+    @Test func decodesNonImageAttachment() throws {
+        let json = """
+        {
+            "id": 2,
+            "uuid": "abc123",
+            "name": "report.pdf",
+            "size": 50000,
+            "browser_download_url": "https://forgejo.example.com/attachments/abc123",
+            "type": "application/pdf",
+            "created_at": "2026-01-01T00:00:00Z"
+        }
+        """
+        let attachment = try decoder().decode(Attachment.self, from: Data(json.utf8))
+        #expect(attachment.name == "report.pdf")
+        #expect(attachment.type == "application/pdf")
+        #expect(attachment.isImage == false)
+    }
+
+    @Test func decodesIssueWithAssets() throws {
+        let json = """
+        {
+            "id": 1,
+            "number": 42,
+            "title": "Bug report",
+            "state": "open",
+            "user": { "id": 1, "login": "alice" },
+            "labels": [],
+            "created_at": "2026-01-01T00:00:00Z",
+            "updated_at": "2026-01-01T00:00:00Z",
+            "comments": 0,
+            "assets": [
+                {
+                    "id": 10,
+                    "uuid": "uuid-1",
+                    "name": "bug.png",
+                    "size": 1024,
+                    "browser_download_url": "https://forgejo.example.com/attachments/uuid-1",
+                    "type": "image/png",
+                    "created_at": "2026-01-01T00:00:00Z"
+                }
+            ]
+        }
+        """
+        let issue = try decoder().decode(Issue.self, from: Data(json.utf8))
+        #expect(issue.assets?.count == 1)
+        #expect(issue.assets?.first?.name == "bug.png")
+        #expect(issue.assets?.first?.isImage == true)
+    }
+
+    @Test func decodesIssueWithNoAssets() throws {
+        let json = """
+        {
+            "id": 1,
+            "number": 1,
+            "title": "No attachments",
+            "state": "open",
+            "user": { "id": 1, "login": "alice" },
+            "labels": [],
+            "created_at": "2026-01-01T00:00:00Z",
+            "updated_at": "2026-01-01T00:00:00Z",
+            "comments": 0
+        }
+        """
+        let issue = try decoder().decode(Issue.self, from: Data(json.utf8))
+        #expect(issue.assets == nil)
+    }
+
+    @Test func decodesIssueCommentWithAssets() throws {
+        let json = """
+        {
+            "id": 5,
+            "body": "See attached screenshot",
+            "user": { "id": 2, "login": "bob" },
+            "created_at": "2026-01-01T00:00:00Z",
+            "updated_at": "2026-01-01T00:00:00Z",
+            "assets": [
+                {
+                    "id": 20,
+                    "uuid": "uuid-2",
+                    "name": "comment-image.jpg",
+                    "size": 2048,
+                    "browser_download_url": "https://forgejo.example.com/attachments/uuid-2",
+                    "type": "image/jpeg",
+                    "created_at": "2026-01-01T00:00:00Z"
+                }
+            ]
+        }
+        """
+        let comment = try decoder().decode(IssueComment.self, from: Data(json.utf8))
+        #expect(comment.assets?.count == 1)
+        #expect(comment.assets?.first?.name == "comment-image.jpg")
+    }
+
+    // MARK: - isImage
+
+    @Test func isImageForVariousMimeTypes() {
+        let makeAttachment = { (type: String) in
+            Attachment(
+                id: 1, uuid: "u", name: "f.bin", size: 0,
+                browserDownloadUrl: "https://example.com/f",
+                type: type, created: Date(),
+            )
+        }
+        #expect(makeAttachment("image/png").isImage == true)
+        #expect(makeAttachment("image/jpeg").isImage == true)
+        #expect(makeAttachment("image/gif").isImage == true)
+        #expect(makeAttachment("image/webp").isImage == true)
+        #expect(makeAttachment("application/pdf").isImage == false)
+        #expect(makeAttachment("text/plain").isImage == false)
+        #expect(makeAttachment("application/zip").isImage == false)
+    }
+
+    @Test func isImageFallsBackToFileExtensionWhenTypeIsNil() {
+        let makeAttachment = { (name: String) in
+            Attachment(
+                id: 1, uuid: "u", name: name, size: 0,
+                browserDownloadUrl: "https://example.com/f",
+                type: nil, created: Date(),
+            )
+        }
+        #expect(makeAttachment("photo.png").isImage == true)
+        #expect(makeAttachment("photo.jpg").isImage == true)
+        #expect(makeAttachment("photo.jpeg").isImage == true)
+        #expect(makeAttachment("photo.gif").isImage == true)
+        #expect(makeAttachment("photo.webp").isImage == true)
+        #expect(makeAttachment("document.pdf").isImage == false)
+        #expect(makeAttachment("archive.zip").isImage == false)
+        #expect(makeAttachment("readme.txt").isImage == false)
+    }
+
+    @Test func isImageFallsBackToExtensionWhenTypeIsNotAMimeType() {
+        // Forgejo returns "type": "attachment" for all uploads, not an actual MIME type.
+        // isImage must fall through to the extension check in this case.
+        let makeAttachment = { (name: String) in
+            Attachment(
+                id: 1, uuid: "u", name: name, size: 0,
+                browserDownloadUrl: "https://example.com/f",
+                type: "attachment", created: Date(),
+            )
+        }
+        #expect(makeAttachment("photo.png").isImage == true)
+        #expect(makeAttachment("photo.jpg").isImage == true)
+        #expect(makeAttachment("photo.gif").isImage == true)
+        #expect(makeAttachment("document.pdf").isImage == false)
+        #expect(makeAttachment("archive.zip").isImage == false)
+    }
+
+    // MARK: - Upload URL construction
+
+    @Test func uploadIssueAttachmentURL() throws {
+        let client = ForgejoClient(serverURL: "https://forgejo.example.com", username: "u", password: "p")
+        let url = try client.makeRepoURL(owner: "alice", repo: "myrepo", path: "/issues/42/assets")
+        #expect(url.absoluteString == "https://forgejo.example.com/api/v1/repos/alice/myrepo/issues/42/assets")
+    }
+
+    @Test func uploadCommentAttachmentURL() throws {
+        let client = ForgejoClient(serverURL: "https://forgejo.example.com", username: "u", password: "p")
+        let url = try client.makeRepoURL(owner: "alice", repo: "myrepo", path: "/issues/comments/99/assets")
+        #expect(url.absoluteString == "https://forgejo.example.com/api/v1/repos/alice/myrepo/issues/comments/99/assets")
+    }
+
+    @Test func uploadURLEncodesOwnerAndRepo() throws {
+        let client = ForgejoClient(serverURL: "https://forgejo.example.com", username: "u", password: "p")
+        let url = try client.makeRepoURL(owner: "my org", repo: "my repo", path: "/issues/1/assets")
+        #expect(url.absoluteString == "https://forgejo.example.com/api/v1/repos/my%20org/my%20repo/issues/1/assets")
+    }
+
+    // MARK: - Multipart body
+
+    @Test func buildMultipartBodyStructure() {
+        let fileData = Data("hello".utf8)
+        let boundary = "test-boundary-123"
+        let body = ForgejoClient.buildMultipartBody(
+            fileData: fileData,
+            fileName: "test.png",
+            mimeType: "image/png",
+            boundary: boundary,
+        )
+        let bodyString = String(data: body, encoding: .utf8) ?? ""
+        #expect(bodyString.contains("--\(boundary)\r\n"))
+        #expect(bodyString.contains("Content-Disposition: form-data; name=\"attachment\"; filename=\"test.png\""))
+        #expect(bodyString.contains("Content-Type: image/png"))
+        #expect(bodyString.contains("hello"))
+        #expect(bodyString.hasSuffix("--\(boundary)--\r\n"))
+    }
+
+    @Test func buildMultipartBodyContainsFileData() {
+        let fileData = Data([0xFF, 0xD8, 0xFF, 0xE0]) // JPEG header bytes
+        let boundary = "b"
+        let body = ForgejoClient.buildMultipartBody(
+            fileData: fileData, fileName: "img.jpg", mimeType: "image/jpeg", boundary: boundary,
+        )
+        let jpegHeader = Data([0xFF, 0xD8, 0xFF, 0xE0])
+        let range = body.range(of: jpegHeader)
+        #expect(range != nil)
+    }
+}