R/notion_search.R

In Songyosr/Rnotion: What the Package Does (One Line, Title Case)

#' Notion's Search API
#'
#' @description Wrapper function for Notion's Search API'
#'
#' @param query a length 1 character vector. When supplied, limits which pages
#' are returned by comparing the query to the page title.
#'
#' @param sort a notion sort object generated by \code{\link{sort_notion}} function.
#' When supplied, sorts the results based on the provided criteria.
#'
#' @param filter a notion filter object generated by \code{\link{filter_notion}} function.
#' When supplied, filters the results based on the provided criteria.
#'
#' @param start_cursor a length 1 character vector. If supplied, this endpoint
#' will return a page of results starting after the cursor provided.
#' If not supplied, this endpoint will return the first page of results.
#'
#' @param page_size a length 1 integer vector. The number of items from the full
#' list desired in the response. Maximum: 100
#'
#' @param api_rate_limited The rate limit for incoming requests is an average of
#' 3 requests per second. Some bursts beyond the average rate are allowed.
#'
#' @details please check: \url{https://developers.notion.com/reference/post-search}
#'
#' @examples
#' notion_search()
#' @export
notion_search <- function(query = NULL, sort = NULL, filter = NULL,
                          start_cursor = NULL, page_size = NULL,
                          api_rate_limited = 1 / 3, ...) {
  # Check query terms
  ## scalar
  query <- query %|null|% assertive.types::assert_is_a_string(query)
  start_cursor <- start_cursor %|null|% assertive.types::assert_is_a_string(start_cursor)
  page_size <- page_size %|null|% (assertive.types::assert_is_a_number(page_size) |> as.integer())

  ## object
  sort <- sort %|null|% (validate_notion_sort(sort) |> unpack_notion())
  filter <- filter %|null|% (validate_filter_conditions(filter) |> unpack_notion())

  # Coerce argument into a list
  args <- tibble::lst(
    query, sort, filter,
    start_cursor, page_size, ...
  ) |> rlist::list.clean()

  Sys.sleep(api_rate_limited)
  #print(jsonlite::toJSON(args, auto_unbox = TRUE, pretty = T))

  # Result
  result <- httr::POST("https://api.notion.com/v1/search",
    notion_header(),
    body = jsonlite::toJSON(args, auto_unbox = TRUE),
    encode = "raw"
  )
  httr::stop_for_status(result)
}