The endpoint is public, so an app can call it at launch. What the response contains depends on the key: files and release notes appear only for a license that is valid for this product. The release docs describe every field. This page is the Swift side: parse it, decide, download, and open the result. The license check itself is in license key validation in Swift.
Check for updates
import Foundation
struct Release: Decodable {
struct File: Decodable { let id: Int; let filename: String; let size: Int; let platform: String?; let url: URL? }
let version: String
let notes: String?
let published_at: String
let files: [File]?
}
enum UpdateCheck {
case upToDate
case available(Release) // newer, and files carry a signed url
case availableButLocked(String) // newer, but the key is missing or not valid: only the version came back
case noRelease // 404
case failed(String)
}
struct Updater {
let base = URL(string: "https://clavem.io")!
let productID = 75 // from your product page
let currentVersion: String // Bundle.main CFBundleShortVersionString
var session: URLSession = .shared
func check(licenseKey: String?) async -> UpdateCheck {
var c = URLComponents(url: base.appendingPathComponent("v1/releases/\(productID)/latest"), resolvingAgainstBaseURL: false)!
c.queryItems = [URLQueryItem(name: "platform", value: "macos")]
var request = URLRequest(url: c.url!)
request.timeoutInterval = 8
if let licenseKey { request.setValue(licenseKey, forHTTPHeaderField: "X-License-Key") }
guard let (data, response) = try? await session.data(for: request),
let http = response as? HTTPURLResponse else { return .failed("offline") }
switch http.statusCode {
case 200: break
case 404: return .noRelease
case 429: return .failed("retry after \(http.value(forHTTPHeaderField: "Retry-After") ?? "60") s")
default: return .failed("HTTP \(http.statusCode)")
}
guard let release = try? JSONDecoder().decode(Release.self, from: data) else { return .failed("unreadable reply") }
guard release.version.compare(currentVersion, options: .numeric) == .orderedDescending else { return .upToDate }
return release.files?.contains { $0.url != nil } == true ? .available(release) : .availableButLocked(release.version)
}
}
The key goes in a header, not the query string, which keeps it out of proxy logs. The platform=macos filter returns files labelled macos plus files with no label. The label is whatever you chose when you uploaded.
What came back
Results from a local stub that returns the documented responses, with a release 3.2.1 and the app on 3.2.0, plus one live call:
with key: available 3.2.1 files=["Inkwell-3.2.1.dmg", "inkwell-3.2.1.zip"]
without key: availableButLocked 3.2.1
already on 3.10.0: upToDate
other product: noRelease
live demo product: noRelease
The live call is the real one: the demo product has no published release, and the API answers 404 with {"error":{"code":"not_found","message":"This product has no published release yet."}}. Handle it as “nothing to offer”, not as an error. Note that the .dmg and the universal .zip both came back: a file with no platform label is offered to every platform.
The locked case is useful. A lapsed customer still learns that version 3.2.1 exists, and you can link them to renew or to your site. Only a valid key adds links.
Download when the customer clicks
Signed links last one hour. An update prompt can sit on screen longer, so call check again when the customer clicks Download, then download the file from that fresh response. This version streams to a .part file, resumes with Range, and moves the finished file into place only when the size matches the size field:
extension Updater {
func download(_ file: Release.File, to destination: URL) async throws {
guard let url = file.url else { throw URLError(.userAuthenticationRequired) }
let part = destination.appendingPathExtension("part")
let fm = FileManager.default
var have = (try? fm.attributesOfItem(atPath: part.path)[.size] as? Int) ?? 0
if have > file.size { try? fm.removeItem(at: part); have = 0 }
if have < file.size {
var request = URLRequest(url: url)
if have > 0 { request.setValue("bytes=\(have)-", forHTTPHeaderField: "Range") }
let (bytes, response) = try await session.bytes(for: request)
guard let http = response as? HTTPURLResponse else { throw URLError(.badServerResponse) }
switch http.statusCode {
case 206: break
case 200: try? fm.removeItem(at: part) // Range ignored: start over
case 403: throw URLError(.userAuthenticationRequired) // link expired: call check again
default: throw URLError(.badServerResponse)
}
if !fm.fileExists(atPath: part.path) { fm.createFile(atPath: part.path, contents: nil) }
let handle = try FileHandle(forWritingTo: part)
defer { try? handle.close() }
try handle.seekToEnd()
var buffer = Data()
for try await byte in bytes {
buffer.append(byte)
if buffer.count >= 1 << 16 { try handle.write(contentsOf: buffer); buffer.removeAll(keepingCapacity: true) }
}
try handle.write(contentsOf: buffer)
}
guard (try fm.attributesOfItem(atPath: part.path)[.size] as? Int) == file.size else { throw URLError(.cannotParseResponse) }
try? fm.removeItem(at: destination)
try fm.moveItem(at: part, to: destination)
}
}
Test: with 1 MiB already in the .part file of a 3 MiB download, the call resumed with 206 and finished with 3,145,728 bytes. A link with a bad signature threw userAuthenticationRequired, the 403 path. The response has no checksum field, so size is the only integrity check the API gives you. What protects the install is your code signature and notarization.
Install on a Mac
An app cannot replace itself while it runs without a helper, and that helper is what Sparkle provides. With Clavem’s JSON, the simple route is to download the disk image to ~/Downloads and open it with NSWorkspace.shared.open(url), so the customer drags the new app over the old one. Sign and notarize the DMG as you would for a download from your site.
A file your app writes has no quarantine attribute unless the app is marked to create quarantined files. In the test run, the downloaded file had no extended attributes at all. Apple documents LSFileQuarantineEnabled in Info.plist as the key that makes the files an app creates quarantined by default, which is what makes Gatekeeper assess a downloaded DMG on first open. Decide that on purpose.
Limits and timing
The releases endpoint allows 120 requests per minute per IP address, counted apart from validation, so an update check never uses up your validation budget. Check once at launch or once a day, not on a timer. “Latest” means the most recently published release, not the highest version number: if you publish a backport after 3.2.1, the backport is what the endpoint returns, so a customer on 3.2.1 sees nothing newer and a customer on 3.0.0 is offered only the backport.
Doing this with Clavem
You upload a build once in the dashboard and publish it. Buyers get it on their order page, and your app gets it through this endpoint with the same key. Imported licenses have no order page, so for those customers this endpoint is the way to deliver downloads. Storage and file limits are in the releases docs.
Questions
Can I use Sparkle with Clavem?
Sparkle reads an appcast feed, and Clavem serves a JSON release object, not an appcast. You can run the check yourself as shown here and open the disk image, or generate an appcast on your own server from the same data.
How do I compare version strings in Swift?
Use String.compare with the .numeric option, so 3.10.0 is newer than 3.9.0. It does not understand pre-release tags like 4.0.0-beta.2, so use a semantic version package if you ship those.
Do download links expire?
Yes. A signed link is valid for one hour. Request the release again when the customer clicks Download instead of storing the link from the earlier check.