feat: implement function wos_search

DESCRIPTION

@@ -19,6 +19,10 @@ License: GPL (>= 2)
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.2.3
+Imports: 
+    httr,
+    jsonlite,
+    utils
 Suggests: 
     knitr,
     rmarkdown

NAMESPACE

@@ -1,2 +1,3 @@
 # Generated by roxygen2: do not edit by hand
 
+export(wos_search)

R/wos_search.R

@@ -0,0 +1,115 @@
+#' Retrieve the number of records that match a given WOS query
+#' 
+#' @description
+#' This function sends a query to the Web Of Science Starter API 
+#' (\url{https://developer.clarivate.com/apis/wos-starter}) and returns the 
+#' total number of records that match this query.
+#' 
+#' To learn how to write a WOS query, users can read the WOS documentation 
+#' available at:
+#' \url{https://images.webofknowledge.com/images/help/WOK/contents.html}.
+#' A list of WOS field tags is available at: 
+#' \url{https://images.webofknowledge.com/images/help/WOS/hs_wos_fieldtags.html}.
+#' 
+#' @param query a `character` of length 1. The query to send to the WOS Starter 
+#'   API. Visit the WOS documentation at:
+#'   \url{https://images.webofknowledge.com/images/help/WOK/contents.html} on 
+#'   how to write a WOS query.
+#' 
+#' @param database a `character` of length 1. One among `BCI` (BIOSIS Citation 
+#'   Index), `BIOABS` (Biological Abstracts), `BIOSIS` (BIOSIS Previews), 
+#'   `CCC` (Current Contents Connect), `DIIDW` (Derwent Innovations Index), 
+#'   `DRCI ` (Data Citation Index), `MEDLINE` (Medline), `PPRN` (Preprint 
+#'   Citation Index), `WOS` (Web of Science Core Collection), `ZOOREC` 
+#'   (Zoological Record), and `WOK` (all databases).
+#'   Default is `WOS` (all databases).
+#'
+#' @return The total number of records (`integer` of length 1) that match the 
+#'   query.
+#'   
+#' @export
+#'
+#' @examples
+#' \dontrun{
+#' ## Search in TOPIC an exact expression ----
+#' query <- "TS=\"salmo salar\""
+#' wos_search(query)
+#' 
+#' ## Search in TOPIC an exact expression and another term ----
+#' query <- "TS=(\"salmo salar\" AND conservation)"
+#' wos_search(query)
+#' 
+#' ## Search for a specific year ----
+#' query <- "TS=(\"salmo salar\" AND conservation) AND PY=2021"
+#' wos_search(query)
+#' 
+#' ## Search for a time span ----
+#' query <- "TS=(\"salmo salar\" AND conservation) AND PY=2010-2021"
+#' wos_search(query)
+#' 
+#' ## Search for an author ----
+#' query <- "AU=(\"Casajus N\")"
+#' wos_search(query)
+#' }
+
+wos_search <- function(query, database = "WOS") {
+
+
+  ## Checks ----
+
+  if (!is.character(query)) {
+    stop("Argument 'query' must be a character", call. = FALSE)
+  }
+
+  if (length(query) != 1) {
+    stop("Argument 'query' must be a character of length 1", call. = FALSE)
+  }
+
+  if (!is.character(database)) {
+    stop("Argument 'database' must be a character", call. = FALSE)
+  }
+
+  if (length(database) != 1) {
+    stop("Argument 'database' must be a character of length 1", call. = FALSE)
+  }
+
+  database <- toupper(database)
+
+  valid_databases <- c("BCI", "BIOABS", "BIOSIS", "CCC", "DIIDW", "DRCI", 
+                       "MEDLINE", "PPRN", "WOK", "WOS", "ZOOREC")
+
+  if (!(database %in% valid_databases))
+    stop("Invalid 'database' value", call. = FALSE)
+
+
+  ## URL encoding ----
+
+  query <- utils::URLencode(query, reserved = TRUE)
+
+
+  ## Write query ----
+
+  request <- paste0(api_url(), "/documents", "?db=", database, "&q=", query,
+                    "&limit=", 1, "&page=", 1)
+
+
+  ## Send query ----
+
+  response <- httr::GET(url    = request, 
+                        config = httr::add_headers(
+                          `accept`   = 'application/json',
+                          `X-ApiKey` = get_token()))
+
+
+  ## Check response ----
+
+  httr::stop_for_status(response)
+
+
+  ## Extract total number of records ----
+
+  content <- httr::content(response, as = "text", encoding = "UTF-8")
+  content <- jsonlite::fromJSON(content)
+
+  content$"metadata"$"total"
+}