#' Get Path to Sample PMTiles File
#'
#' @description
#' Returns the path to a sample PMTiles file for demos and testing.
#' On first use, downloads a small regional extract to the user's cache
#' directory.
#'
#' @param region Character. Region to download. Currently only "sf-bay"
#'   (San Francisco Bay Area) is available. Default is "sf-bay".
#' @param cache_dir Character. Directory to cache the downloaded file.
#'   Default uses \code{tools::R_user_dir()}.
#' @param force_download Logical. Force re-download even if cached.
#'   Default is FALSE.
#'
#' @return Character. Path to the PMTiles file.
#'
#' @details
#' The sample tiles are hosted on GitHub releases and downloaded on first use.
#' Subsequent calls use the cached file. The SF Bay Area extract is
#' approximately 10-15MB and covers the greater San Francisco region at all
#' zoom levels.
#'
#' For production use, consider self-hosting your own PMTiles file. See
#' \code{vignette("getting-started")} for options.
#'
#' @examples
#' \dontrun{
#' library(leaflet)
#' library(protomapr)
#'
#' # Use sample tiles for demos (downloads on first use)
#' leaflet() %>%
#'   setView(lng = -122.4, lat = 37.8, zoom = 12) %>%
#'   addProtomaps(url = protomaps_sample_tiles())
#' }
#'
#' @seealso \code{\link{protomaps_clear_cache}}, \code{\link{protomaps_url}}
#' @export
protomaps_sample_tiles <- function(region = "sf-bay",
                                   cache_dir = NULL,
                                   force_download = FALSE) {

  region <- match.arg(region, choices = c("sf-bay"))

  if (is.null(cache_dir)) {
    cache_dir <- tools::R_user_dir("protomapr", which = "cache")
  }

  if (!dir.exists(cache_dir)) {
    dir.create(cache_dir, recursive = TRUE)
  }

  filename <- sprintf("protomapr-sample-%s.pmtiles", region)
  local_path <- file.path(cache_dir, filename)

  if (file.exists(local_path) && !force_download) {
    message("Using cached sample tiles: ", local_path)
    return(local_path)
  }

  base_url <- "https://github.com/evmo/protomapr/releases/download"
  version <- "sample-tiles-v1"
  download_url <- sprintf("%s/%s/%s", base_url, version, filename)

  message("Downloading sample tiles (~10MB)...")
  message("Source: ", download_url)

 tryCatch({
    utils::download.file(
      url = download_url,
      destfile = local_path,
      mode = "wb",
      quiet = FALSE
    )
    message("Downloaded to: ", local_path)
  }, error = function(e) {
    stop(
      "Failed to download sample tiles.\n",
      "Error: ", conditionMessage(e), "\n",
      "Try again later or use protomaps_url() with an API key instead.",
      call. = FALSE
    )
  })

  local_path
}


#' Clear Cached Sample Tiles
#'
#' @description
#' Removes cached sample PMTiles files to free disk space.
#'
#' @param cache_dir Character. Cache directory. Default uses same as
#'   \code{\link{protomaps_sample_tiles}}.
#'
#' @return Invisibly returns TRUE if files were removed, FALSE otherwise.
#'
#' @examples
#' \dontrun{
#' # Clear all cached tiles
#' protomaps_clear_cache()
#' }
#'
#' @seealso \code{\link{protomaps_sample_tiles}}
#' @export
protomaps_clear_cache <- function(cache_dir = NULL) {
  if (is.null(cache_dir)) {
    cache_dir <- tools::R_user_dir("protomapr", which = "cache")
  }

  if (!dir.exists(cache_dir)) {
    message("Cache directory does not exist: ", cache_dir)
    return(invisible(FALSE))
  }

  files <- list.files(cache_dir, pattern = "\\.pmtiles$", full.names = TRUE)

  if (length(files) == 0) {
    message("No cached tiles found.")
    return(invisible(FALSE))
  }

  unlink(files)
  message(sprintf("Removed %d cached file(s).", length(files)))

  invisible(TRUE)
}