feat: improve pairing flow, heartbeat, and demo header

Pairing:
- Auto-check on launch: fires register immediately; shows device ID screen only on 404
- Persist pairing token in SharedPreferences to resume sessions across restarts
- Pair-status now called as POST with pairing_token in request body
- Fix DisposableEffect closure bug that cancelled new session on retry
- Add button loading state on "Pair this device" tap

Network:
- Add X-Demo-Bypass: true header to all API calls via DemoBypassInterceptor
- Add PairingTokenStore for pairing token persistence

Heartbeat:
- Move heartbeat from WorkManager (15-min minimum clamp) to coroutine loop
  inside the foreground service — now respects configured interval immediately
- Fix CPU usage: /proc/stat is blocked on API 26+; use /proc/self/stat delta instead

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: FitzAfful

sample-app/src/main/kotlin/io/squarescreen/sample/ui/PairingScreen.kt

@@ -4,6 +4,7 @@ import com.jakewharton.retrofit2.converter.kotlinx.serialization.asConverterFact
 import io.squarescreen.core.config.SquareScreenConfig
 import io.squarescreen.core.datasource.NetworkDataSource
 import io.squarescreen.network.api.SquareScreenApiService
+import io.squarescreen.network.interceptor.DemoBypassInterceptor
 import io.squarescreen.network.interceptor.DeviceAuthInterceptor
 import kotlinx.serialization.json.Json
 import okhttp3.MediaType.Companion.toMediaType
@@ -33,6 +34,7 @@ object NetworkClientFactory {
 
     private fun buildOkHttpClient(config: SquareScreenConfig): OkHttpClient {
         return OkHttpClient.Builder()
+            .addInterceptor(DemoBypassInterceptor())
             .addInterceptor(DeviceAuthInterceptor(config.deviceId, config.deviceToken))
             .connectTimeout(30, TimeUnit.SECONDS)
             .readTimeout(30, TimeUnit.SECONDS)

squarescreen-network/src/main/kotlin/io/squarescreen/network/NetworkClientFactory.kt

@@ -6,6 +6,8 @@ import io.squarescreen.core.model.PairingStatus
 import io.squarescreen.core.result.SquareScreenError
 import io.squarescreen.core.result.SquareScreenResult
 import io.squarescreen.network.api.PairingApiService
+import io.squarescreen.network.interceptor.DemoBypassInterceptor
+import io.squarescreen.network.dto.PairStatusRequestDto
 import io.squarescreen.network.dto.RegisterRequestDto
 import kotlinx.serialization.json.Json
 import okhttp3.MediaType.Companion.toMediaType
@@ -30,6 +32,7 @@ class PairingNetworkClient {
     }
 
     private val okHttpClient = OkHttpClient.Builder()
+        .addInterceptor(DemoBypassInterceptor())
         .connectTimeout(30, TimeUnit.SECONDS)
         .readTimeout(30, TimeUnit.SECONDS)
         .writeTimeout(30, TimeUnit.SECONDS)
@@ -86,8 +89,11 @@ class PairingNetworkClient {
      * [PairingStatus.Expired], or [PairingStatus.Error] for unexpected failures.
      */
     suspend fun getPairStatus(pairingToken: String): PairingStatus {
+        if (pairingToken.isBlank()) {
+            return PairingStatus.Error(IllegalStateException("Pairing token is missing — cannot check pair status"))
+        }
         return try {
-            val response = api.getPairStatus("Bearer $pairingToken")
+            val response = api.getPairStatus(PairStatusRequestDto(pairingToken))
             when {
                 response.isSuccessful -> {
                     val body = response.body()

squarescreen-network/src/main/kotlin/io/squarescreen/network/PairingNetworkClient.kt

@@ -1,12 +1,11 @@
 package io.squarescreen.network.api
 
+import io.squarescreen.network.dto.PairStatusRequestDto
 import io.squarescreen.network.dto.PairStatusResponseDto
 import io.squarescreen.network.dto.RegisterRequestDto
 import io.squarescreen.network.dto.RegisterResponseDto
 import retrofit2.Response
 import retrofit2.http.Body
-import retrofit2.http.GET
-import retrofit2.http.Header
 import retrofit2.http.POST
 
 internal interface PairingApiService {
@@ -16,8 +15,8 @@ internal interface PairingApiService {
         @Body body: RegisterRequestDto
     ): Response<RegisterResponseDto>
 
-    @GET("screen/pair-status")
+    @POST("screen/pair-status")
     suspend fun getPairStatus(
-        @Header("Authorization") authHeader: String
+        @Body body: PairStatusRequestDto
     ): Response<PairStatusResponseDto>
 }

squarescreen-network/src/main/kotlin/io/squarescreen/network/api/PairingApiService.kt

@@ -15,6 +15,11 @@ internal data class RegisterResponseDto(
     val message: String? = null
 )
 
+@Serializable
+internal data class PairStatusRequestDto(
+    @SerialName("pairing_token") val pairingToken: String
+)
+
 @Serializable
 internal data class PairStatusResponseDto(
     val status: String,

squarescreen-network/src/main/kotlin/io/squarescreen/network/dto/PairingDto.kt

@@ -0,0 +1,13 @@
+package io.squarescreen.network.interceptor
+
+import okhttp3.Interceptor
+import okhttp3.Response
+
+internal class DemoBypassInterceptor : Interceptor {
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val request = chain.request().newBuilder()
+            .header("X-Demo-Bypass", "true")
+            .build()
+        return chain.proceed(request)
+    }
+}

squarescreen-network/src/main/kotlin/io/squarescreen/network/interceptor/DemoBypassInterceptor.kt

@@ -186,7 +186,6 @@ class SquareScreen private constructor(
             SquareScreenServiceLocator.nowPlayingState.value = result
         }
 
-        workScheduler.scheduleHeartbeat(config.heartbeatIntervalSeconds)
         workScheduler.scheduleEmergencyPoll(config.emergencyPollIntervalSeconds)
         workScheduler.scheduleCommandPoll()
 

squarescreen-player/src/main/kotlin/io/squarescreen/player/SquareScreen.kt

@@ -1,10 +1,12 @@
 package io.squarescreen.player
 
+import android.content.Context
 import io.squarescreen.core.logging.SquareScreenLogger
 import io.squarescreen.core.model.PairingStatus
 import io.squarescreen.core.result.SquareScreenError
 import io.squarescreen.core.result.SquareScreenResult
 import io.squarescreen.network.PairingNetworkClient
+import io.squarescreen.player.internal.PairingTokenStore
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.SupervisorJob
@@ -21,38 +23,43 @@ private const val TAG = "SquareScreenPairing"
 /**
  * Manages the device pairing flow before [SquareScreen.init] can be called.
  *
+ * On first collection of [pairingStatus]:
+ * - If a pairing token is stored from a previous session, skips register and goes
+ *   straight to polling `pair-status`.
+ * - Otherwise calls `register`, persists the returned token, then polls `pair-status`.
+ *
+ * The pairing token is cleared automatically on [PairingStatus.Approved],
+ * [PairingStatus.Expired], and [PairingStatus.InvalidToken].
+ *
  * Usage:
  * ```kotlin
- * val pairing = SquareScreenPairing.create(osIdentifier = androidId)
+ * val pairing = SquareScreenPairing.create(context, osIdentifier = androidId)
  *
- * // Automatic — observe status changes with backoff polling
  * pairing.pairingStatus.collect { status ->
  *     when (status) {
  *         is PairingStatus.Approved -> {
  *             credentialStore.save(status.deviceId, status.deviceToken)
  *             initializeSdk(status.deviceId, status.deviceToken)
  *         }
- *         PairingStatus.Pending      -> showAwaitingApprovalUI()
+ *         PairingStatus.Pending        -> showAwaitingApprovalUI()
  *         PairingStatus.DeviceNotFound -> showDeviceNotFoundError()
  *         PairingStatus.AlreadyPaired  -> showAlreadyPairedError()
- *         PairingStatus.Expired      -> showExpiredError()
- *         PairingStatus.InvalidToken -> showInvalidTokenError()
- *         is PairingStatus.Error     -> showGenericError(status.throwable)
+ *         PairingStatus.Expired        -> showExpiredError()
+ *         PairingStatus.InvalidToken   -> showInvalidTokenError()
+ *         is PairingStatus.Error       -> showGenericError(status.throwable)
  *     }
  * }
  *
- * // Manual — trigger an immediate check (e.g. from a "Check now" button)
- * val status = pairing.checkPairStatus()
- *
- * // Cancel when done (e.g. in onDestroy or DisposableEffect)
- * pairing.cancel()
+ * val status = pairing.checkPairStatus() // manual one-shot check
+ * pairing.cancel()                       // call in onDestroy / DisposableEffect
  * ```
  *
  * @param osIdentifier A stable device identifier pre-registered by an admin (e.g. Android ID).
  */
 class SquareScreenPairing private constructor(
     private val osIdentifier: String,
     private val networkClient: PairingNetworkClient,
+    private val tokenStore: PairingTokenStore,
     private val logger: SquareScreenLogger? = null
 ) {
     private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
@@ -62,32 +69,37 @@ class SquareScreenPairing private constructor(
     /**
      * Flow of [PairingStatus] updates.
      *
-     * On first collection: calls `POST /screen/register`, then polls `GET /screen/pair-status`
-     * with exponential backoff (5 s × 3 → 10 s × 3 → 30 s thereafter).
-     * Terminates automatically on [PairingStatus.Approved], [PairingStatus.InvalidToken],
-     * [PairingStatus.Expired], [PairingStatus.DeviceNotFound], [PairingStatus.AlreadyPaired],
-     * or [PairingStatus.Error].
+     * On first collection:
+     * - Stored token found → skips register, polls pair-status immediately.
+     * - No stored token → calls register, stores token, then polls pair-status.
      *
-     * The last emitted value is replayed to new collectors via [shareIn].
+     * Polls with exponential backoff (5 s × 3 → 10 s × 3 → 30 s thereafter).
+     * Terminates automatically on any terminal [PairingStatus].
+     * The last emitted value is replayed to new collectors.
      */
     val pairingStatus: Flow<PairingStatus> = callbackFlow<PairingStatus> {
-        logger?.debug(TAG, "Registering device with identifier: $osIdentifier")
+        val storedToken = tokenStore.get()
 
-        when (val reg = networkClient.register(osIdentifier)) {
-            is SquareScreenResult.Error -> {
-                val status = reg.error.toPairingStatus()
-                logger?.debug(TAG, "Register failed: $status")
-                send(status)
-                close()
-                return@callbackFlow
-            }
-            is SquareScreenResult.Success -> {
-                currentPairingToken = reg.data.pairingToken
-                logger?.debug(
-                    TAG,
-                    "Registered — awaiting admin approval (token expires in ${reg.data.expiresIn}s)"
-                )
-                send(PairingStatus.Pending)
+        if (storedToken != null) {
+            logger?.debug(TAG, "Resuming pairing with stored token")
+            currentPairingToken = storedToken
+            send(PairingStatus.Pending)
+        } else {
+            logger?.debug(TAG, "Registering device with identifier: $osIdentifier")
+            when (val reg = networkClient.register(osIdentifier)) {
+                is SquareScreenResult.Error -> {
+                    val status = reg.error.toPairingStatus()
+                    logger?.debug(TAG, "Register failed: $status")
+                    send(status)
+                    close()
+                    return@callbackFlow
+                }
+                is SquareScreenResult.Success -> {
+                    currentPairingToken = reg.data.pairingToken
+                    tokenStore.save(reg.data.pairingToken)
+                    logger?.debug(TAG, "Registered — token stored (expires in ${reg.data.expiresIn}s)")
+                    send(PairingStatus.Pending)
+                }
             }
         }
 
@@ -96,15 +108,20 @@ class SquareScreenPairing private constructor(
             delay(backoffDelay(attempt))
             attempt++
             val token = currentPairingToken ?: break
-            logger?.debug(TAG, "Polling pair status (attempt $attempt, delay ${backoffDelay(attempt - 1)}ms)")
+            logger?.debug(TAG, "Polling pair status (attempt $attempt)")
             val status = networkClient.getPairStatus(token)
             send(status)
             when (status) {
                 is PairingStatus.Approved,
                 PairingStatus.InvalidToken,
-                PairingStatus.Expired,
+                PairingStatus.Expired -> {
+                    logger?.debug(TAG, "Pairing terminal: $status — clearing stored token")
+                    tokenStore.clear()
+                    close()
+                    return@callbackFlow
+                }
                 is PairingStatus.Error -> {
-                    logger?.debug(TAG, "Pairing terminal: $status")
+                    logger?.debug(TAG, "Pairing error: ${status.throwable.message}")
                     close()
                     return@callbackFlow
                 }
@@ -119,7 +136,7 @@ class SquareScreenPairing private constructor(
      * Performs a one-shot pair-status check outside the automatic polling cycle.
      *
      * Only valid after [pairingStatus] has been collected and the register call has completed.
-     * Returns [PairingStatus.Error] if called before an active pairing session exists.
+     * Returns [PairingStatus.Error] if there is no active pairing token.
      */
     suspend fun checkPairStatus(): PairingStatus {
         val token = currentPairingToken
@@ -130,14 +147,13 @@ class SquareScreenPairing private constructor(
     }
 
     /**
-     * Cancels the polling coroutine scope. Call this when the pairing screen is destroyed
-     * to avoid leaking the polling loop.
+     * Cancels the polling coroutine scope. Call this when the pairing screen is destroyed.
      */
     fun cancel() {
         scope.cancel()
     }
 
-    // Backoff schedule: attempts 0-2 → 5s, attempts 3-5 → 10s, attempts 6+ → 30s
+    // Backoff: attempts 0–2 → 5s, 3–5 → 10s, 6+ → 30s
     private fun backoffDelay(attempt: Int): Long = when {
         attempt < 3 -> 5_000L
         attempt < 6 -> 10_000L
@@ -146,18 +162,25 @@ class SquareScreenPairing private constructor(
 
     companion object {
         /**
-         * Creates a [SquareScreenPairing] instance for the given OS identifier.
+         * Creates a [SquareScreenPairing] instance.
          *
+         * @param context Application or Activity context used for persisting the pairing token.
          * @param osIdentifier Stable device identifier pre-registered by an admin.
          *   On Android, use `Settings.Secure.getString(contentResolver, Settings.Secure.ANDROID_ID)`.
-         * @param logger Optional logger for debug output. Pass null (default) for silence.
+         * @param logger Optional logger for debug output. Null (default) = silent.
          */
         fun create(
+            context: Context,
             osIdentifier: String,
             logger: SquareScreenLogger? = null
         ): SquareScreenPairing {
             require(osIdentifier.isNotBlank()) { "osIdentifier must not be blank" }
-            return SquareScreenPairing(osIdentifier, PairingNetworkClient(), logger)
+            return SquareScreenPairing(
+                osIdentifier = osIdentifier,
+                networkClient = PairingNetworkClient(),
+                tokenStore = PairingTokenStore(context.applicationContext),
+                logger = logger
+            )
         }
     }
 }

squarescreen-player/src/main/kotlin/io/squarescreen/player/SquareScreenPairing.kt

@@ -12,23 +12,45 @@ private const val TAG = "DeviceMetricsCollector"
 internal class DeviceMetricsCollector(private val context: Context) {
 
     /**
-     * Reads CPU usage from /proc/stat.
-     * Computes (total - idle) / total as a percentage.
-     * Returns null if /proc/stat is unavailable or unreadable.
+     * Estimates this process's CPU usage by sampling /proc/self/stat twice with a
+     * short delay and computing the delta in jiffies.
+     *
+     * /proc/stat (system-wide) is blocked on API 26+, but /proc/self/stat (process-level)
+     * remains accessible. The result reflects the player process's CPU consumption rather
+     * than device-wide usage — appropriate for a signage SDK heartbeat.
+     *
+     * Returns null if the file is unreadable or the delta is zero (no time has elapsed).
      */
     fun getCpuUsage(): Float? {
         return try {
-            val lines = java.io.File("/proc/stat").readLines()
-            val cpuLine = lines.firstOrNull { it.startsWith("cpu ") } ?: return null
-            val parts = cpuLine.trim().split("\\s+".toRegex()).drop(1).mapNotNull { it.toLongOrNull() }
-            if (parts.size < 4) return null
-            val idle = parts[3]
-            val total = parts.sum()
-            if (total == 0L) return null
-            ((total - idle).toFloat() / total.toFloat() * 100f).coerceIn(0f, 100f)
+            val sample1 = readProcessJiffies() ?: return null
+            Thread.sleep(200)
+            val sample2 = readProcessJiffies() ?: return null
+
+            val processDelta = (sample2.first - sample1.first).toFloat()
+            val totalDelta = (sample2.second - sample1.second).toFloat()
+
+            if (totalDelta <= 0f) return null
+            (processDelta / totalDelta * 100f).coerceIn(0f, 100f)
+        } catch (e: Exception) {
+            SquareScreenServiceLocator.log(TAG, "CPU usage unavailable: ${e.message}")
+            null
+        }
+    }
+
+    // Returns Pair(processJiffies, totalJiffies) from /proc/self/stat and /proc/stat uptime.
+    // Falls back to wall-clock total if /proc/stat is unavailable.
+    private fun readProcessJiffies(): Pair<Long, Long>? {
+        return try {
+            val parts = java.io.File("/proc/self/stat").readText().trim().split(" ")
+            if (parts.size < 17) return null
+            // Fields 13,14 = utime, stime; 15,16 = cutime, cstime (all in jiffies)
+            val utime = parts[13].toLongOrNull() ?: return null
+            val stime = parts[14].toLongOrNull() ?: return null
+            val processJiffies = utime + stime
+            val totalJiffies = System.nanoTime() / 10_000_000L // nanoseconds → centiseconds (jiffies at 100Hz)
+            Pair(processJiffies, totalJiffies)
         } catch (e: Exception) {
-            // /proc/stat is restricted on API 26+ — this is expected, not an error.
-            SquareScreenServiceLocator.log(TAG, "CPU usage unavailable (restricted on API 26+): ${e.message}")
             null
         }
     }

squarescreen-player/src/main/kotlin/io/squarescreen/player/internal/DeviceMetricsCollector.kt

@@ -0,0 +1,16 @@
+package io.squarescreen.player.internal
+
+import android.content.Context
+
+private const val PREFS_FILE = "squarescreen_pairing"
+private const val KEY_PAIRING_TOKEN = "pairing_token"
+
+internal class PairingTokenStore(context: Context) {
+    private val prefs = context.getSharedPreferences(PREFS_FILE, Context.MODE_PRIVATE)
+
+    fun get(): String? = prefs.getString(KEY_PAIRING_TOKEN, null)
+
+    fun save(token: String) = prefs.edit().putString(KEY_PAIRING_TOKEN, token).apply()
+
+    fun clear() = prefs.edit().remove(KEY_PAIRING_TOKEN).apply()
+}