Android & TV Integration

This example uses kotlinx.serialization throughout. It includes the DTOs used by the Retrofit interface, a raw refresh client, a bearer interceptor, and the bulk-history result handling. There are no Moshi annotations in this example.

Dependencies

The following is a small JVM/Android-compatible Gradle setup. Pin the versions in your own dependency catalog and update them as a unit when you upgrade Kotlin:

plugins {
    kotlin("jvm") version "2.0.21"
    kotlin("plugin.serialization") version "2.0.21"
}

repositories { mavenCentral() }

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
    implementation("com.squareup.retrofit2:retrofit:2.11.0")
    implementation("com.squareup.retrofit2:converter-kotlinx-serialization:2.11.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
}

DTOs and API

Use @SerialName for the API’s snake-case fields. Response objects such as nextCursor, resourceId, and changedAt are camelCase, so they keep their Kotlin property names.

import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.sync.Mutex
import kotlinx.coroutines.sync.withLock
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonObject
import okhttp3.Interceptor
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.Response
import okhttp3.MediaType.Companion.toMediaType
import retrofit2.Retrofit
import retrofit2.converter.kotlinx.serialization.asConverterFactory
import retrofit2.http.Body
import retrofit2.http.GET
import retrofit2.http.Header
import retrofit2.http.POST
import retrofit2.http.Query

@Serializable
data class DeviceCodeRequest(
    @SerialName("client_id") val clientId: String,
    val scope: String,
)

@Serializable
data class DeviceCodeResponse(
    @SerialName("user_code") val userCode: String,
    @SerialName("device_code") val deviceCode: String,
    @SerialName("verification_uri") val verificationUri: String,
    @SerialName("verification_uri_complete") val verificationUriComplete: String? = null,
    @SerialName("verification_uri_qr") val verificationUriQr: String? = null,
    @SerialName("expires_in") val expiresIn: Long,
    val scope: String,
)

@Serializable
data class RefreshRequest(
    @SerialName("client_id") val clientId: String,
    @SerialName("refresh_token") val refreshToken: String,
)

@Serializable
data class Tokens(
    @SerialName("access_token") val accessToken: String,
    @SerialName("refresh_token") val refreshToken: String,
    @SerialName("token_type") val tokenType: String,
    @SerialName("expires_in") val expiresIn: Long,
    @SerialName("refresh_expires_in") val refreshExpiresIn: Long,
    val scope: String,
    val username: String? = null,
)

@Serializable
data class SyncChange(
    val cursor: String,
    val resource: String,
    val resourceId: String,
    val operation: String,
    val changedAt: String,
    val data: JsonObject? = null,
)

@Serializable
data class SyncChanges(
    val changes: List<SyncChange>,
    val hasMore: Boolean,
    val nextCursor: String,
    val resetRequired: Boolean,
    val resources: List<String>,
)

@Serializable
data class SyncSnapshot(
    val items: List<JsonObject?>,
    val hasMore: Boolean,
    val nextAfter: Long? = null,
    val resource: String,
)

@Serializable
data class BulkHistoryItem(
    @SerialName("client_item_id") val clientItemId: String,
    val kind: String,
    @SerialName("tmdb_id") val tmdbId: Int? = null,
    @SerialName("imdb_id") val imdbId: String? = null,
    @SerialName("tvdb_id") val tvdbId: Int? = null,
    @SerialName("mal_id") val malId: Int? = null,
    @SerialName("watched_at") val watchedAt: String,
    val title: String? = null,
    val year: Int? = null,
    val season: Int? = null,
    val episode: Int? = null,
)

@Serializable
data class BulkHistoryRequest(val items: List<BulkHistoryItem>)

@Serializable
data class BulkMutationResult(
    @SerialName("client_item_id") val clientItemId: String?,
    val index: Int,
    val status: String,
    val reason: String? = null,
    @SerialName("resolved_tmdb_id") val resolvedTmdbId: Int? = null,
    val error: String? = null,
)

@Serializable
data class BulkMutationResponse(val results: List<BulkMutationResult>)

interface PunchPlayApi {
    @POST("api/platform/v1/auth/device/code")
    suspend fun createDeviceCode(@Body body: DeviceCodeRequest): DeviceCodeResponse

    @POST("api/platform/v1/auth/refresh")
    suspend fun refresh(@Body body: RefreshRequest): Tokens

    @GET("api/platform/v1/me/sync/changes")
    suspend fun changes(
        @Query("cursor") cursor: String? = null,
        @Query("limit") limit: Int = 100,
    ): SyncChanges

    @GET("api/platform/v1/me/sync/snapshot")
    suspend fun snapshot(
        @Query("resource") resource: String,
        @Query("after") after: Long = 0,
        @Query("limit") limit: Int = 100,
    ): SyncSnapshot

    @POST("api/platform/v1/sync/history")
    suspend fun pushHistory(
        @Header("Idempotency-Key") idempotencyKey: String,
        @Body body: BulkHistoryRequest,
    ): BulkMutationResponse
}

Refresh without recursive interception

Build two Retrofit clients. The raw client has no bearer interceptor and is used for device authorization and refresh. Only the authenticated client installs the interceptor. This matters because a refresh request must still work when the access token that triggered the refresh is expired.

interface TokenStorage {
    fun load(): Tokens
    fun save(tokens: Tokens)
}

class TokenStore(
    private val refreshApi: PunchPlayApi,
    private val clientId: String,
    private val storage: TokenStorage,
) {
    private val mutex = Mutex()
    private var tokens = storage.load()

    suspend fun accessToken(): String = mutex.withLock { tokens.accessToken }

    /** Returns the current token when another request already refreshed it. */
    suspend fun refreshAfter(stale: String): String? = mutex.withLock {
        if (tokens.accessToken != stale) return@withLock tokens.accessToken

        val next = runCatching {
            refreshApi.refresh(
                RefreshRequest(clientId = clientId, refreshToken = tokens.refreshToken),
            )
        }.getOrNull() ?: return@withLock null

        // Persist before returning: refresh tokens rotate and the old value
        // stops working immediately.
        tokens = next
        storage.save(next)
        next.accessToken
    }
}

class AuthInterceptor(private val store: TokenStore) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val used = runBlocking { store.accessToken() }
        val response = chain.proceed(chain.request().withBearer(used))
        if (response.code != 401) return response

        val refreshed = runBlocking { store.refreshAfter(used) }
            ?: return response
        response.close()
        return chain.proceed(chain.request().withBearer(refreshed))
    }
}

private fun Request.withBearer(token: String): Request = newBuilder()
    .header("Authorization", "Bearer $token")
    .build()

private val json = Json { ignoreUnknownKeys = true }
private val jsonMediaType = "application/json".toMediaType()

private fun retrofit(client: OkHttpClient): Retrofit = Retrofit.Builder()
    .baseUrl("https://punchplay.tv/")
    .client(client)
    .addConverterFactory(json.asConverterFactory(jsonMediaType))
    .build()

data class ApiClients(
    val raw: PunchPlayApi,
    val authenticated: PunchPlayApi,
    val tokens: TokenStore,
)

fun buildApiClients(clientId: String, storage: TokenStorage): ApiClients {
    val raw = retrofit(OkHttpClient()).create(PunchPlayApi::class.java)
    val tokens = TokenStore(raw, clientId, storage)
    val authenticated = retrofit(
        OkHttpClient.Builder()
            .addInterceptor(AuthInterceptor(tokens))
            .build(),
    ).create(PunchPlayApi::class.java)
    return ApiClients(raw, authenticated, tokens)
}

Call clients.raw.refresh(...) only through TokenStore; call protected sync methods on clients.authenticated. Retry a 401 once. If the replay fails, send the user through device authorization again. Because refresh tokens rotate, the mutex and the raw refresh client are both required.

Initial sync and cursor ownership

Keep one encrypted token record, mirror, and cursor per PunchPlay account and app. A cursor is also scoped by the read permissions available to that token. If the user later grants additional read scopes, request a new cursor and snapshot the newly visible resources; an older cursor is not a backfill for data that was previously hidden.

interface MirrorStore {
    fun <T> transaction(block: () -> T): T
    fun replaceResource(resource: String, items: List<JsonObject?>)
    fun applyChange(change: SyncChange)
    fun saveCursor(cursor: String)
}

private suspend fun replayChanges(
    api: PunchPlayApi,
    mirror: MirrorStore,
    firstPage: SyncChanges,
) {
    var page = firstPage
    while (true) {
        mirror.transaction {
            page.changes.forEach(mirror::applyChange)
            mirror.saveCursor(page.nextCursor)
        }
        if (!page.hasMore) break
        page = api.changes(cursor = page.nextCursor)
    }
}

suspend fun initialSync(api: PunchPlayApi, mirror: MirrorStore) {
    val first = api.changes(cursor = null)
    if (first.resetRequired) {
        for (resource in first.resources) {
            val items = buildList<JsonObject?> {
                var after = 0L
                while (true) {
                    val page = api.snapshot(resource = resource, after = after)
                    addAll(page.items)
                    if (!page.hasMore) break
                    after = page.nextAfter
                        ?: error("snapshot page is missing nextAfter")
                }
            }
            // Replace only after all pages are assembled; replacing each page
            // would discard the rows from earlier pages.
            mirror.transaction { mirror.replaceResource(resource, items) }
        }

        // The first cursor is the snapshot high-water mark. Replay changes that
        // arrived while the snapshots were running.
        replayChanges(api, mirror, api.changes(cursor = first.nextCursor))
    } else {
        // With no reset, the first response is already the first page. Do not
        // skip it by starting a second request from its cursor.
        replayChanges(api, mirror, first)
    }
}

Change delivery is at least once. Apply upserts and tombstones idempotently by resource plus resourceId, and save the cursor only in the same transaction as the page. A cursor can remain valid for 90 days; after that the API asks for a reset and a fresh snapshot.

Bulk history with stable idempotency

Use one stable client_item_id per source watch. Persist one fresh UUID as the Idempotency-Key for each logical batch before the first request. If the request times out, retry the same body with the same persisted key. If you change the body, generate and persist a new key.

data class LocalWatch(
    val stableId: String,
    val punchPlayTmdbId: Int?,
    val imdbId: String?,
    val isEpisode: Boolean,
    val watchedAt: String,
    val season: Int?,
    val episode: Int?,
)

interface WatchDatabase {
    fun markSynced(watch: LocalWatch, tmdbId: Int?, note: String? = null)
    fun markRejected(watch: LocalWatch, reason: String)
    fun markPending(watch: LocalWatch, reason: String)
}

data class PendingHistoryBatch(
    val idempotencyKey: String,
    val watches: List<LocalWatch>,
)

// Persist this batch before the first call. Reuse the same object after a
// timeout; do not generate a new key inside the retrying function.
suspend fun pushHistory(
    api: PunchPlayApi,
    database: WatchDatabase,
    batch: PendingHistoryBatch,
) {
    val watches = batch.watches
    val response = api.pushHistory(
        idempotencyKey = batch.idempotencyKey,
        body = BulkHistoryRequest(
            watches.map { watch ->
                BulkHistoryItem(
                    clientItemId = watch.stableId,
                    kind = if (watch.isEpisode) "episode" else "movie",
                    tmdbId = watch.punchPlayTmdbId,
                    imdbId = watch.imdbId.takeIf { watch.punchPlayTmdbId == null },
                    watchedAt = watch.watchedAt,
                    season = watch.season,
                    episode = watch.episode,
                )
            },
        ),
    )

    response.results.forEach { result ->
        val watch = watches.getOrNull(result.index) ?: return@forEach
        when (result.status) {
            "inserted", "updated", "removed", "skipped" ->
                database.markSynced(watch, result.resolvedTmdbId)
            "deferred" ->
                database.markSynced(watch, result.resolvedTmdbId, result.reason)
            "invalid" ->
                database.markRejected(watch, result.error ?: "invalid item")
            else ->
                database.markPending(watch, "unknown bulk status: ${result.status}")
        }
    }
}

deferred means PunchPlay stored the item and will retry resolution; do not place it in your retry queue. For 409 request_in_progress, wait and retry the same key. For 409 idempotency_indeterminate, reconcile through the change feed and retry the unresolved remainder with a new key. See Partner Sync for scope combinations, identifier formats, and the complete outcome table.

Getting Started

Guides

Reference

Android & TV Integration

Dependencies

DTOs and API

Refresh without recursive interception

Initial sync and cursor ownership

Bulk history with stable idempotency

​Dependencies

​DTOs and API

​Refresh without recursive interception

​Initial sync and cursor ownership

​Bulk history with stable idempotency

Dependencies

DTOs and API

Refresh without recursive interception

Initial sync and cursor ownership

Bulk history with stable idempotency