# Kotlin SDK

> Add com.shopsavvy:shopsavvy-sdk-kotlin to Android or JVM projects for coroutine-based product lookups, retailer offers and price history.

*Source: https://shopsavvy.com/data/documentation/sdk-kotlin* · Part of the [ShopSavvy Data API documentation](https://shopsavvy.com/data/documentation.md)

---

Our official Kotlin SDK provides native Android integration with coroutines support and modern Kotlin idioms.

- [View on GitHub](https://github.com/shopsavvy/sdk-kotlin)
- [Maven Central](https://central.sonatype.com/artifact/com.shopsavvy/shopsavvy-sdk-kotlin)

## Installation

```kotlin
// build.gradle.kts
dependencies {
    implementation("com.shopsavvy:shopsavvy-sdk-kotlin:1.1.0")
}
```

## Quick Start

```kotlin
import com.shopsavvy.sdk.*
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    // Create a new client
    val client = ShopSavvyClient("ss_live_your_api_key_here")

    try {
        // Get product details
        val product = client.getProductDetails("012345678901")
        println("Product: ${product.data.name}")

        // Get current offers
        val offers = client.getCurrentOffers("012345678901")
        offers.data.forEach { offer ->
            println("${offer.retailer}: $${offer.price}")
        }

        // Get price history
        val history = client.getPriceHistory(
            "012345678901",
            "2024-01-01",
            "2024-01-31"
        )

    } catch (e: Exception) {
        println("Error: ${e.message}")
    }
}
```

## Android Integration

```kotlin
class ProductRepository(private val client: ShopSavvyClient) {

    suspend fun getProduct(barcode: String): Result<Product> =
        try {
            val response = client.getProductDetails(barcode)
            Result.success(response.data)
        } catch (e: Exception) {
            Result.failure(e)
        }
}

// In your ViewModel
class ProductViewModel(
    private val repository: ProductRepository
) : ViewModel() {

    private val _product = MutableLiveData<Product?>()
    val product: LiveData<Product?> = _product

    fun loadProduct(barcode: String) {
        viewModelScope.launch {
            repository.getProduct(barcode)
                .onSuccess { _product.value = it }
                .onFailure { /* handle error */ }
        }
    }
}
```

## Features

- Full coroutines support
- Null safety with Kotlin types
- Android lifecycle awareness
- OkHttp-based HTTP client
- Serialization with kotlinx.serialization
- Support for Android API 21+