R/read.R

In giocomai/zoteror: Access the Zotero API in R

#' Read details of a Zotero item
#'
#' Read details of a Zotero item
#'
#'
#' @param id Id code of a zotero item
#' @param user Zotero userId
#' @param credentials Either an R object created with AuthZot(store = TRUE), or
#'   an API secret key with write access created at
#'   https://www.zotero.org/settings/keys
#' @return A list including all available details on a given item.
#' @export
#' @examples
#' \dontrun{
#' item <- zot_read_item()
#' }
zot_read_item <- function(id, user = NULL, credentials = NULL) {
  if (is.null(user) == TRUE) {
    user <- zot_options("user")
  }
  if (is.null(credentials) == TRUE) {
    credentials <- zot_options("credentials")
  }
  if (class(credentials)[1] == "OAuth") {
    secret <- credentials$oauthSecret
  } else {
    secret <- credentials
  }
  jsonlite::fromJSON(
    txt = paste0(
      "https://api.zotero.org/users/",
      user, "/items/",
      id,
      "?key=",
      secret
    )
  )
}

#' Read details of all children of a Zotero item
#'
#' Read details of all children of a Zotero item
#'
#'
#' @param id Id code of a zotero item
#' @param user Zotero userId
#' @param credentials Either an R object created with AuthZot(store = TRUE), or an API secret key with write access created at https://www.zotero.org/settings/keys
#' @return A data.frame including details on all children of a given parent item.
#' @export
#' @examples
#' \dontrun{
#' item <- zot_read_children(id = "<ID>")
#' }
zot_read_children <- function(id, user = NULL, credentials = NULL) {
  if (is.null(user) == TRUE) {
    user <- zot_options("user")
  }
  if (is.null(credentials) == TRUE) {
    credentials <- zot_options("credentials")
  }
  if (class(credentials)[1] == "OAuth") {
    secret <- credentials$oauthSecret
  } else {
    secret <- credentials
  }
  jsonlite::fromJSON(
    txt = paste0(
      "https://api.zotero.org/users/",
      user,
      "/items/",
      id,
      "/children",
      "?key=",
      secret
    ),
    flatten = TRUE
  )
}


#' Read IDs of all children of a Zotero item
#'
#' Read IDs of all children of a Zotero item
#'
#'
#' @param id Id code of a zotero item
#' @param user Zotero userId
#' @param credentials Either an R object created with AuthZot(store = TRUE), or
#'   an API secret key with write access created at
#'   https://www.zotero.org/settings/keys
#' @return A vector including the ID of all children
#' @export
#' @examples
#' \dontrun{
#' item_id <- zot_read_children_id(id = "<ID>")
#' }
zot_read_children_id <- function(id, user = NULL, credentials = NULL) {
  if (is.null(user) == TRUE) {
    user <- zot_options("user")
  }
  if (is.null(credentials) == TRUE) {
    credentials <- zot_options("credentials")
  }
  zot_read_children(id = id, user = user, credentials = credentials)$key
}

#' Extract collections in which given item is included
#'
#' Extract collections in which given item is included
#'
#'
#' @param user Zotero userId
#' @param credentials Either an R object created with AuthZot(store = TRUE), or an API secret key with write access created at https://www.zotero.org/settings/keys
#' @return A charachter vector including all categories in which given item is included.
#' @export
#' @examples
#' \dontrun{
#' categories <- zot_which_collection(item = "X1X2X3")
#' }
zot_which_collection <- function(id, user = NULL, credentials = NULL) {
  if (is.null(user) == TRUE) {
    user <- zot_options("user")
  }
  if (is.null(credentials) == TRUE) {
    credentials <- zot_options("credentials")
  }
  if (class(credentials)[1] == "OAuth") {
    secret <- credentials$oauthSecret
  } else {
    secret <- credentials
  }
  item <- zot_read_item(id = id, user = user, credentials = secret)
  if (is.null(item$data$collections) == TRUE) {
    id <- item$data$parentItem
    item <- zot_read_item(id = id, user = user, credentials = secret)
  }
  item$data$collections
}

#' Find and show all valid item types
#'
#' Find and show all valid item types
#'
#'
#' @param item_type Defaults to "book". It must correspond to a valid item type.
#'   You can chech which item types are valid with the function
#'   `zot_get_item_types()`
#' @param cache Logical, defaults to TRUE.  If TRUE, it stores the list of valid
#'   item types in a "zot_cache" folder in the current working directory.
#' @param locale Defaults to English. If given, it should correspond to a
#'   language code such as "it" or "fr-FR"
#' @return A charachter vector including all categories in which given item is
#'   included.
#' @export
#' @examples
#' \dontrun{
#' item_types <- zot_get_item_types()
#' }
zot_get_item_types <- function(cache = TRUE, locale = NULL) {
  if (cache == TRUE) {
    dir.create(path = "zot_cache", showWarnings = FALSE)
    if (is.null(locale) == TRUE) {
      file_location <- fs::path("zot_cache", "item_types.rds")
    } else {
      file_location <- fs::path(
        "zot_cache",
        paste0(
          "item_types-",
          locale,
          ".rds"
        )
      )
    }

    if (fs::file_exists(file_location)) {
      return(readRDS(file_location))
    } else {
      if (is.null(locale)) {
        item_types <- jsonlite::fromJSON(txt = "https://api.zotero.org/itemTypes")
      } else {
        item_types <- jsonlite::fromJSON(txt = paste0("https://api.zotero.org/itemTypes?locale=", locale))
      }
      readr::write_rds(x = item_types, path = file_location)
    }
  } else {
    if (is.null(locale)) {
      item_types <- jsonlite::fromJSON(txt = "https://api.zotero.org/itemTypes")
    } else {
      item_types <- jsonlite::fromJSON(txt = paste0("https://api.zotero.org/itemTypes?locale=", locale))
    }
  }
  return(item_types)
}

#' Find and show all valid creator types
#'
#' Find and show all valid creator types
#'
#'
#' @param cache Logical, defaults to TRUE.  If TRUE, it stores the list of valid
#'   item types in a "zot_cache" folder in the current working directory.
#' @param locale Defaults to English. If given, it should correspond to a
#'   language code such as "it" or "fr-FR"
#' @return A list including all valid creator types for given item type.
#' @export
#' @examples
#' \dontrun{
#' creator_types <- zot_get_creator_types()
#' }
zot_get_creator_types <- function(item_type = "book",
                                  cache = TRUE,
                                  locale = NULL) {
  if (cache == TRUE) {
    fs::dir_create(path = "zot_cache")
    if (is.null(locale) == TRUE) {
      file_location <- fs::path("zot_cache", paste0(item_type, "_creator_types.rds"))
    } else {
      file_location <- fs::path("zot_cache", paste0(item_type, "_creator_types", locale, ".rds"))
    }
    if (fs::file_exists(file_location)) {
      return(readr::read_rds(path = file_location))
    } else {
      if (is.null(locale)) {
        creator_types <- jsonlite::fromJSON(txt = paste0("https://api.zotero.org/itemTypeCreatorTypes?itemType=", item_type))
      } else {
        creator_types <- jsonlite::fromJSON(txt = paste0("https://api.zotero.org/itemTypeCreatorTypes?itemType=", item_type, "&locale=", locale))
      }
      readr::write_rds(x = creator_types, path = file_location)
    }
  } else {
    if (is.null(locale)) {
      creator_types <- jsonlite::fromJSON(txt = paste0("https://api.zotero.org/itemTypeCreatorTypes?itemType=", item_type))
    } else {
      creator_types <- jsonlite::fromJSON(txt = paste0("https://api.zotero.org/itemTypeCreatorTypes?itemType=", item_type, "&locale=", locale))
    }
  }
  return(creator_types)
}


#' Get an item template for a valid item type
#'
#' Get an item template for a valid item type
#'
#'
#' @param item_type Defaults to "book". It must correspond to a valid item type.
#'   You can chech which item types are valid with the function
#'   `zot_get_item_types()`
#' @param cache Logical, defaults to TRUE. If TRUE, it stores the template in a
#'   "zot_cache" folder in the current working directory.
#' @return A list. A template for creating items of the given item_type.
#' @export
#' @examples
#' \dontrun{
#' item_templates <- zot_get_item_template()
#' }
zot_get_item_template <- function(item_type = "book", cache = TRUE) {
  if (cache == TRUE) {
    dir.create(path = "zot_cache", showWarnings = FALSE)
    template_location <- file.path("zot_cache", paste0(paste("item", item_type, "template", sep = "_"), ".rds"))
    if (file.exists(template_location)) {
      return(readRDS(template_location))
    } else {
      item_template <- jsonlite::fromJSON(txt = paste0("https://api.zotero.org/items/new?itemType=", item_type))
      saveRDS(object = item_template, file = template_location)
      return(item_template)
    }
  } else {
    jsonlite::fromJSON(txt = paste0("https://api.zotero.org/items/new?itemType=", item_type))
  }
}




#' Find and show all valid fields for a given item type
#'
#' Find and show all valid fields for a given item type
#'
#'
#' @param item_type Defaults to "book". It must correspond to a valid item type.
#'   You can chech which item types are valid with the function
#'   `zot_get_item_types()`
#' @param cache Logical, defaults to TRUE. If TRUE, it stores the list of valid
#'   item types in a "zot_cache" folder in the current working directory.
#' @param locale Defaults to English. If given, it should correspond to a
#'   language code such as "it" or "fr-FR"
#' @return A data frame including all valid fields for given item type.
#' @export
#' @examples
#' \dontrun{
#' zot_get_item_types_fields()
#' }
zot_get_item_types_fields <- function(item_type = "book",
                                      cache = TRUE,
                                      locale = NULL) {
  if (cache == TRUE) {
    fs::dir_create(path = "zot_cache")
    if (is.null(locale) == TRUE) {
      file_location <- fs::path("zot_cache", paste0(item_type, "_item_types_fields.rds"))
    } else {
      file_location <- fs::path("zot_cache", paste0(item_type, "_item_types_fields", locale, ".rds"))
    }
    if (fs::file_exists(file_location)) {
      return(readr::read_rds(file_location))
    } else {
      if (is.null(locale)) {
        item_types_fields <- jsonlite::fromJSON(txt = paste0("https://api.zotero.org/itemTypeFields?itemType=", item_type))
      } else {
        item_types_fields <- jsonlite::fromJSON(txt = paste0("https://api.zotero.org/itemTypeFields?itemType=", item_type, "&locale=", locale))
      }
      readr::write_rds(x = item_types_fields, path = file_location)
    }
  } else {
    if (is.null(locale)) {
      item_types_fields <- jsonlite::fromJSON(txt = paste0("https://api.zotero.org/itemTypeFields?itemType=", item_type))
    } else {
      item_types_fields <- jsonlite::fromJSON(txt = paste0("https://api.zotero.org/itemTypeFields?itemType=", item_type, "&locale=", locale))
    }
  }
  return(item_types_fields)
}