Clavem

Check for updates and download builds from a Flutter app

Call GET /v1/releases/:productId/latest with your license key in the X-License-Key header, compare the version with pub_semver, and fetch a fresh download link only when the customer clicks Update. Clavem delivers the files; running the installer is up to your app.

The two calls

Updates take two requests, not one. The check runs at launch and only needs the version. The second runs on click and needs a link. The documented response for a valid license looks like this, with a signed url per file:

{ "version": "3.2.1", "notes": "Fixes a crash when importing large files.",
  "published_at": "2026-11-19T08:30:00.000Z",
  "files": [ { "id": 12, "filename": "Inkwell-3.2.1.dmg", "size": 50540748,
               "platform": "macos", "url": "https://clavem.io/d/12?exp=...&sig=..." } ] }

With no key, or a key that does not qualify, you get only version and published_at. If nothing is published, the endpoint answers 404 with not_found. I captured that last one from the live API on 19 November 2026.

Check and compare

// pubspec.yaml: http, package_info_plus, pub_semver
import 'dart:convert';
import 'dart:ffi' show Abi;
import 'dart:io';
import 'package:http/http.dart' as http;
import 'package:package_info_plus/package_info_plus.dart';
import 'package:pub_semver/pub_semver.dart';

const _base = 'https://clavem.io';
const _productId = 75; // from your product page

class Latest {
  Latest(this.version, this.notes, this.fileName, this.size, this.url);
  final Version version;
  final String? notes;
  final String? fileName, url; // null unless the license may download
  final int? size;
}

class UpdateCheckFailed implements Exception {
  UpdateCheckFailed(this.status, this.retryAfter);
  final int status;
  final int? retryAfter; // seconds, from the Retry-After header
}

/// Newest published release, or null when nothing is published or the version is not semver.
Future<Latest?> fetchLatest(String licenseKey) async {
  final platform = Abi.current().toString(); // for example macos_arm64: label your files the same way
  final res = await http.get(
    Uri.parse('$_base/v1/releases/$_productId/latest?platform=$platform'),
    headers: {'X-License-Key': licenseKey}, // the header keeps the key out of logs and URLs
  ).timeout(const Duration(seconds: 8));
  if (res.statusCode == 404) return null;
  if (res.statusCode != 200) {
    throw UpdateCheckFailed(res.statusCode, int.tryParse(res.headers['retry-after'] ?? ''));
  }
  final j = jsonDecode(res.body) as Map<String, dynamic>;
  final withLink = ((j['files'] as List?) ?? const [])
      .cast<Map<String, dynamic>>()
      .where((f) => f['url'] != null)
      .toList();
  try {
    return Latest(
      Version.parse(j['version'] as String),
      j['notes'] as String?,
      withLink.isEmpty ? null : withLink.first['filename'] as String,
      withLink.isEmpty ? null : withLink.first['size'] as int,
      withLink.isEmpty ? null : withLink.first['url'] as String,
    );
  } on FormatException {
    return null; // "2026.11" or "4.0" is not a three-part version
  }
}

Future<bool> isNewer(Latest latest) async {
  final current = Version.parse((await PackageInfo.fromPlatform()).version);
  if (latest.version.isPreRelease && !current.isPreRelease) return false; // a beta never replaces a stable install
  return latest.version > current;
}

Three details matter here.

  • Latest means most recently published, not highest version. If you publish a 3.2.2 backport after 3.3.0, the endpoint returns 3.2.2, and latest.version > current keeps a 3.3.0 user from being offered a downgrade.
  • Versions must parse. Clavem accepts versions up to 64 characters with letters, digits, dots, dashes, plus signs and underscores. pub_semver wants major.minor.patch. Keep your release versions in that shape.
  • PackageInfo.version comes from version: in pubspec.yaml, without the +build part, so 3.2.1+7 reads as 3.2.1.

Platform labels

A label is any string you chose when you uploaded the file, such as macos_arm64. Abi.current() already names the architecture, so a label per ABI needs no mapping table. A file with no label is offered to every platform. If you use only macos for both Apple Silicon and Intel disk images, you have to pick between two files in the response yourself.

Download on click, and resume

Future<File> download(Latest l, Directory dir, void Function(int got, int? total) onProgress) async {
  final target = File('${dir.path}/${l.fileName}');
  final part = File('${target.path}.part'); // the name carries the version, so a stale partial never matches
  final have = await part.exists() ? await part.length() : 0;
  if (have > 0 && have == l.size) return part.rename(target.path); // finished earlier, never renamed

  final client = http.Client();
  try {
    final request = http.Request('GET', Uri.parse(l.url!))..headers['Range'] = 'bytes=$have-';
    final res = await client.send(request);
    if (res.statusCode != 200 && res.statusCode != 206) {
      throw HttpException('Download failed: HTTP ${res.statusCode}');
    }
    final resumed = res.statusCode == 206; // the server honoured the range
    final sink = part.openWrite(mode: resumed ? FileMode.append : FileMode.write);
    var got = resumed ? have : 0;
    final length = res.contentLength;
    final total = length == null ? null : length + (resumed ? have : 0);
    await for (final chunk in res.stream) {
      sink.add(chunk);
      got += chunk.length;
      onProgress(got, total);
    }
    await sink.close();
    return part.rename(target.path);
  } finally {
    client.close();
  }
}

Call fetchLatest again right before download. The link from the launch check may be older than the hour it lives for. Downloads support byte ranges, so a dropped connection resumes. A 403 means the link expired, and the answer is a fresh fetchLatest, not a retry.

Applying the update

Clavem has no updater and no delta updates, and the release response has no checksum field, so verification is yours. On desktop, open the downloaded installer and quit:

Future<void> openInstaller(File f) async {
  if (Platform.isMacOS) {
    await Process.run('open', [f.path]);
  } else if (Platform.isWindows) {
    await Process.start(f.path, [], mode: ProcessStartMode.detached);
  } else {
    await Process.run('xdg-open', [f.parent.path]);
  }
  exit(0); // a running Windows executable cannot be overwritten
}

This file imports dart:io and dart:ffi, so it is desktop-only: keep it out of web builds with a conditional import. On iOS, and on Android builds from Google Play, the store delivers updates. This endpoint is for builds you distribute yourself. On web, you deploy the new bundle, so there is nothing to download.

Rate limits and failures

The releases endpoint allows 120 requests per minute per IP address, counted apart from validation, so a launch check never eats your validation budget. A 429 carries Retry-After: 60. For an automatic check at launch, swallow UpdateCheckFailed and try again next launch. For a button the customer pressed, show “try again in a minute”. Do not poll.

Doing this with Clavem

Upload each build once on the product page, give it a platform label, and publish. Buyers get the same files from their order page. The full endpoint, with limits and imported-license behavior, is in Releases and downloads. The key check that decides whether a link comes back is described in validation in Flutter.

Questions

Does the releases endpoint need a license key?

No. Without a valid key it still returns the newest version and its publish date, which is enough to say an update exists. Release notes and file links appear only for a key that belongs to this product and is neither expired nor disabled.

Why does the download link stop working?

Links are signed and last one hour. Ask the endpoint for a new one when the customer clicks Update, not when the version check runs.

Sources

  1. package_info_plus, PackageInfo.version (checked November 2026)
  2. pub_semver, Version class (checked November 2026)