Functions to manipulate shared links

[Zedseayou]

I've needed to add some shared links to a lot of files recently, so I was wondering whether there's appetite to add some functions to boxr that wrap that endpoint and related ones. Somewhat related to #218 but it's a different endpoint.

Here's a bare bones function based off the API docs and reading some of the existing boxr code. This does what I want it to but I haven't tested it very thoroughly, and thought I'd raise an issue for discussion before trying to wrap it into a PR. Specifically, I'd like to think/get some feedback about:

• Should there be separate user-level functions for add, update and removing shared links, or attempt to consolidate?
• Whether to ignore bad param combinations as i currently do or throw errors
• Including the unshared at and vanity name request options
• What should be an internal vs external function in boxr
• I haven't done anything to wrap the httr result into a boxr object, so need to figure out which ones are available/whether we need a new one
• Is there anything more opinionated that we could do? Some vague ideas include combining the file and folder endpoints, or adding auto share to some of the upload functions.
• Naming, as always!

#' Add a shared link on a Box file
#'
#' @param file_id `numeric` or `character`, file ID at Box.
#' @param access Level of access for the shared link. This can be restricted to
#'   anyone with the link (`open`), only people within the company (`company`),
#'   and only those who have been invited to the folder (`collaborators`). The
#'   `company` access level is only available to paid accounts.
#' @param password `character`, the password required to access the shared link.
#'   If `NULL`, passwords will not be enabled. A password can only be set when
#'   `access` is set to `open`; it is ignored otherwise.
#' @param can_download `logical`, indicates whether the shared link allows for
#'   downloading of files. This can only be set when `access` is set to `open`
#'   or `company`, it is ignored otherwise.
#'
#' @return The [httr()] object returned by the API call
#' @export
box_add_shared_link_file <- function(file_id,
                                access = c("open", "company", "collaborators"),
                                password = NULL,
                                can_download = TRUE) {
  access = rlang::arg_match(access)
  request_body <- list(shared_link = list(access = access))
  if (access == "open") {
    if (is.null(password)) {
      password <- "null"
    }
    request_body[["shared_link"]][["password"]] <- password
  }
  if (access %in% c("open", "company")) {
    request_body[["shared_link"]][["permissions"]][["can_download"]] <- can_download
  }

  httr::RETRY(
    verb = "PUT",
    url = paste0("https://api.box.com/2.0/files/", boxr:::box_id(file_id)),
    boxr:::get_token(),
    query = list(fields = "shared_link"),
    body = request_body,
    encode = "json",
    terminate_on = boxr:::box_terminal_http_codes()
  )
}

[nathancday]

Absolutely! Would love to get some more API endpoints wrapped with R code.

My thoughts to your bullets:

Should there be separate user-level functions for add, update and removing shared links, or attempt to consolidate?

I think there are probably at least 7 functions.
3 internal: GET _shared_link, GET _shared_link/file_id, PUT _shared_link/file_id
4 external: find_folder, get_link, add_link, delete_link

Whether to ignore bad param combinations as i currently do or throw errors

I think boxr should faithfully return the APIs response here. If there is an error throw it, if not carry on.

Including the unshared at and vanity name request options

We should be exposing as much of the API as possible for users to manipulate. I think these should be included

What should be an internal vs external function in boxr

Externals are nice human readables that collect arguments for the Internals, like get tokens and paths, maybe decorate with classes.
Internals are the cURL commands, doing the RETRY logic, the GET / PUT path the API wants.

I haven't done anything to wrap the httr result into a boxr object, so need to figure out which ones are available/whether we need a new one

Lets save this for last

Is there anything more opinionated that we could do? Some vague ideas include combining the file and folder endpoints, or adding auto share to some of the upload functions.

Combining endpoints might be less verbose if the two APIs are identical. But the API separated for them for a reason, keeping them separated for our wrappers is safer in case things change in the future.

Naming, as always!

Save this for last, last!

Does any of that not make sense?
I think starting with the code you have and adding some unit test cases for this would be the best place to start a PR.