KDownloader

A lightweight Kotlin Multiplatform download manager for Android and iOS. Uses platform-native APIs with no external dependencies.

Features

• Kotlin DSL for easy configuration
• Progress tracking with callbacks
• State management (pending, downloading, paused, completed, failed, cancelled)
• Authentication support (Bearer token, Basic auth)
• Custom headers
• Network type restrictions (WiFi only)
• Platform-native implementations:
  • Android: DownloadManager (system-managed, survives app kill, shows notifications)
  • iOS: NSURLSession (background download support)

Installation

Add the dependency to your KMP module:

// build.gradle.kts
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("dev.onexeor:kdownloader:1.0.0")
        }
    }
}

Android Setup

Initialize KDownloader in your Application class:

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        KDownloader.init(this)
    }
}

Usage

Basic Download

val downloader = KDownloader()

downloader.download("https://example.com/file.pdf") {
    fileName = "document.pdf"

    onProgress { progress ->
        println("${progress.percentage}%")
    }

    onComplete { filePath ->
        println("Downloaded to: $filePath")
    }

    onError { error ->
        println("Failed: ${error.message}")
    }
}

With Authentication

downloader.download("https://api.example.com/private/file.zip") {
    fileName = "data.zip"

    auth {
        bearer("your-access-token")
    }

    onComplete { println("Done: $it") }
}

With Custom Headers

downloader.download("https://example.com/file.pdf") {
    headers {
        "X-Custom-Header" to "value"
        "Accept" to "application/octet-stream"
    }
}

WiFi Only Download

downloader.download("https://example.com/large-file.zip") {
    wifiOnly()

    onStateChange { state ->
        when (state) {
            is DownloadState.Paused -> println("Waiting: ${state.reason}")
            is DownloadState.Downloading -> println("Progress: ${state.progress.percentage}%")
            is DownloadState.Completed -> println("Done!")
            else -> {}
        }
    }
}

Task Control

val task = downloader.download("https://example.com/file.zip")

// Add listeners after creation (fluent API)
task.onProgress { println("${it.percentage}%") }
    .onComplete { println("Done: $it") }
    .onError { println("Error: ${it.message}") }

// Check current state
println("State: ${task.currentState}")
println("Progress: ${task.currentProgress.percentage}%")

// Cancel if needed
task.cancel()

Configuration

val downloader = KDownloader(
    KDownloaderConfig(
        defaultDirectory = "MyApp/Downloads",
        defaultNetworkType = NetworkType.ANY
    )
)

API Reference

KDownloader

Method	Description
download(url, builder)	Start a download with DSL configuration
download(request)	Start a download with pre-built request
getTask(id)	Get an existing download task by ID
cancelAll()	Cancel all active downloads

DownloadState

State	Description
Pending	Download is queued
Downloading(progress)	Download is in progress
Paused(reason)	Download is paused
Completed(filePath)	Download completed successfully
Failed(error)	Download failed with an error
Cancelled	Download was cancelled

DownloadError Types

Type	Description
Network	Connection failed, timeout, etc.
Http	HTTP error response (4xx, 5xx)
Storage	Disk full, permission denied, etc.
InvalidUrl	Malformed URL
Cancelled	User cancelled the download
Unknown	Unexpected error

Auth

auth {
    bearer("token")           // Bearer token authentication
    basic("user", "password") // Basic authentication
}

Platform Requirements

Platform	Minimum Version
Android	API 24 (7.0)
iOS	13.0

Roadmap

• Authentication support (Bearer, Basic)
• Custom headers
• Kotlin DSL API
• Download queue management
• Resume/pause support
• Download speed tracking

License

Copyright 2024 Viktor Savchik

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.