kooltab-backoffice/docs/flutter-app-version-prompt.md

KoolTap Flutter App — Send the App Version, Ask to Update When It's Too Old

The backoffice now refuses terminals running an app that is too old. Every call to /devices/... (register, sync, image upload, command ack) must carry the app version in a header:

X-App-Version: 1.4.2+37

Use the version from pubspec.yaml (read it at runtime with package_info_plus: version + + + buildNumber, or just version). The build number after + is ignored by the backoffice.

When the app is older than the backoffice's minimum version, or sends no header (every app from before this change), the call fails before the token is checked with:

HTTP 426
{ "error": { "code": "app_update_required", "message": "Update the app to version 1.4.0 or newer" } }

What to Change

1. Send the header on every request to the backoffice: add it where the HTTP client sets the Authorization header (e.g. a shared client or interceptor in lib/services/remote_sync_service.dart), so register, sync, image uploads and acks all carry it.
2. Handle 426 / app_update_required in the sync loop and on the registration screen:
   • Stop syncing (don't retry in a loop); keep the till working offline exactly as when the backoffice is unreachable, and keep every outbox (tab events, stock outcomes, acks) so nothing is lost once the app is updated.
   • Show a clear, persistent banner/dialog: "This app is out of date. Update it to keep syncing with the backoffice", with the server's message.
   • Don't treat it as an auth error: never unpair or throw away the device token.
   • Retry after the app restarts (an updated app restarts anyway).
3. Bump the app version in pubspec.yaml for the release that adds this, and tell the backoffice that version: it is set as MIN_APP_VERSION (env var, or the constant in apps/api/src/devices/app-version.ts).