initial commit

4 years ago · 2442f08034
18 changed files with 485 additions and 6 deletions
--- a/6
+++ b/6
@ -1,6 +1,6 @@
 Package: bacharach
 Type: Package
-Title: bacharach title goes here otherwise CRAN checks fail
+Title: Tools to Work with the Raindrop API
 Version: 0.1.0
 Date: 2020-04-21
 Authors@R: c(
@ -8,7 +8,9 @@ Authors@R: c(
           comment = c(ORCID = "0000-0001-5670-2640"))
  )
 Maintainer: Bob Rudis <bob@rud.is>
-Description: A good description goes here otherwise CRAN checks fail.
+Description: Raindrop <https://raindrop.io> provides a URL bookmarking service
+    and an API for working with that service and more. Tools are provided to
+    work with the Raindrop API. A Raindrop API key (free) is required.
 URL: https://git.rud.is/hrbrmstr/bacharach
 BugReports: https://gitlab.com/hrbrmstr/bacharach/issues
 Encoding: UTF-8
--- a/8
+++ b/8
@ -1,4 +1,12 @@
 # Generated by roxygen2: do not edit by hand

+export(get_child_collections)
+export(get_collection)
+export(get_raindrop)
+export(get_raindrops)
+export(get_root_collections)
+export(get_user)
+export(raindrop_api_token)
+export(raindrop_parse_url)
 import(httr)
 importFrom(jsonlite,fromJSON)
--- a/R/aaa.R
+++ b/R/aaa.R
@ -0,0 +1,15 @@
+set_names <- function (object = nm, nm) { names(object) <- nm ; object }
+
+httr::user_agent(
+  sprintf(
+    "{bacharach} package v%s: (<%s>)",
+    utils::packageVersion("bacharach"),
+    utils::packageDescription("bacharach")$URL
+  )
+) -> .RAINDROP_UA
+
+raindrop_auth <- function(api_key = raindrop_api_token()) {
+  httr::add_headers(
+    `Authorization` = sprintf("Bearer %s", api_key)
+  )
+}
--- a/R/api-key.R
+++ b/R/api-key.R
@ -0,0 +1,39 @@
+#' Get or set RAINDROP_API_TOKEN value
+#'
+#' The API wrapper functions in this package all rely on a Raindrop
+#' token residing in the environment variable `RAINDROP_API_TOKEN`.
+#' The easiest way to accomplish this is to set it
+#' in the `.Renviron` file in your home directory.
+#'
+#' You can obtain an Raindrop token by going visiting
+#' <https://app.raindrop.io/#/settings/apps/dev>. Use the
+#' **test token**.
+#'
+#' @md
+#' @param force Force setting a new Raindrop key for the current environment?
+#' @return atomic character vector containing the Raindrop token
+#' @export
+raindrop_api_token <- function(force = FALSE) {
+
+  env <- Sys.getenv('RAINDROP_API_TOKEN')
+  if (!identical(env, "") && !force) return(env)
+
+  if (!interactive()) {
+    stop("Please set env var RAINDROP_API_TOKEN to your Raindrop token",
+         call. = FALSE)
+  }
+
+  message("Couldn't find env var RAINDROP_API_TOKEN See ?raindrop_api_token for more details.")
+  message("Please enter your API token:")
+  pat <- readline(": ")
+
+  if (identical(pat, "")) {
+    stop("Raindrop token entry failed", call. = FALSE)
+  }
+
+  message("Updating RAINDROP_API_TOKEN env var")
+  Sys.setenv(RAINDROP_API_TOKEN = pat)
+
+  pat
+
+}
--- a/R/bacharach-package.R
+++ b/R/bacharach-package.R
@ -1,5 +1,9 @@
-#' ...
-#' 
+#' Tools to Work with the Raindrop API
+#'
+#' Raindrop <https://raindrop.io> provides a URL bookmarking service
+#' and an API for working with that service and more. Tools are provided to
+#' work with the Raindrop API.nA Raindrop API key (free) is required.
+#'
 #' @md
 #' @name bacharach
 #' @keywords internal
--- a/R/collections.R
+++ b/R/collections.R
@ -0,0 +1,84 @@
+# https://api.raindrop.io/rest/v1/collections
+
+#' @export
+get_root_collections <- function(api_key = raindrop_api_token()) {
+
+  httr::GET(
+    url = "https://api.raindrop.io/rest/v1/collections",
+    .RAINDROP_UA,
+    raindrop_auth()
+  ) -> res
+
+  httr::stop_for_status(res)
+
+  out <- httr::content(res, as = "text")
+
+  out <- jsonlite::fromJSON(out)
+
+  if (out$result) {
+
+    out <- out$items
+
+    colnames(out) <- c(
+      "title", "public", "view", "count", "cover", "expanded",
+      "id",  "user", "creator", "created", "last_update",
+      "sort", "access",  "author"
+    )
+
+    class(out) <- c("tbl_df", "tbl", "data.frame")
+
+  }
+
+  out
+
+}
+
+#' @export
+get_child_collections <- function(api_key = raindrop_api_token()) {
+
+  httr::GET(
+    url = "https://api.raindrop.io/rest/v1/collections/childrens",
+    .RAINDROP_UA,
+    raindrop_auth()
+  ) -> res
+
+  httr::stop_for_status(res)
+
+  out <- httr::content(res, as = "text")
+
+  out <- jsonlite::fromJSON(out)
+
+  out
+
+}
+
+#' Get a collection
+#'
+#' @param id collection id
+#' @export
+get_collection <- function(id, api_key = raindrop_api_token()) {
+
+  sprintf(
+    "https://api.raindrop.io/rest/v1/collection/%s",
+    id[1]
+  ) -> get_collection_url
+
+  httr::GET(
+    url = get_collection_url,
+    .RAINDROP_UA,
+    raindrop_auth()
+  ) -> res
+
+  httr::stop_for_status(res)
+
+  out <- httr::content(res, as = "text")
+
+  out <- jsonlite::fromJSON(out)
+
+  out
+
+}
+
+
+
+
--- a/R/import.R
+++ b/R/import.R
@ -0,0 +1,41 @@
+# https://api.raindrop.io/rest/v1/import/url/parse
+
+#' Parse and extract useful info from any URL
+#'
+#' @param url a URL
+#' @export
+raindrop_parse_url <- function(url, api_key = raindrop_api_token()) {
+
+  httr::GET(
+    url = "https://api.raindrop.io/rest/v1/import/url/parse",
+    .RAINDROP_UA,
+    raindrop_auth(),
+    query = list(
+      url = url[1]
+    )
+  ) -> res
+
+  httr::stop_for_status(res)
+
+  out <- httr::content(res, as = "text")
+
+  out <- jsonlite::fromJSON(out)
+
+  if (out$result) {
+
+    rownames(out$item$media) <- NULL
+    rownames(out$item$meta) <- NULL
+
+    out$item$media <- I(list(out$item$media))
+    out$item$meta <- I(list(out$item$meta))
+
+    out <- data.frame(out$item, stringsAsFactors = FALSE)
+
+    class(out) <- c("tbl_df", "tbl", "data.frame")
+
+  }
+
+  out
+
+}
+
--- a/R/raindrops.R
+++ b/R/raindrops.R
@ -0,0 +1,82 @@
+# https://api.raindrop.io/rest/v1/raindrop/{id}
+
+#' Get a single raindrop
+#'
+#' @param id raindrop id
+#' @export
+get_raindrop <- function(id, api_key = raindrop_api_token()) {
+
+  sprintf(
+    "https://api.raindrop.io/rest/v1/raindrop/%s",
+    id[1]
+  ) -> get_raindrop_url
+
+  httr::GET(
+    url = get_raindrop_url,
+    .RAINDROP_UA,
+    raindrop_auth()
+  ) -> res
+
+  httr::stop_for_status(res)
+
+  out <- httr::content(res, as = "text")
+
+  out <- jsonlite::fromJSON(out)
+
+  out
+
+}
+
+#' Get all raindrops from a collection (TODO pagination)
+#'
+#' TODO pagination
+#'
+#' @param id collection id
+#' @export
+get_raindrops <- function(id, api_key = raindrop_api_token()) {
+
+  sprintf(
+    "https://api.raindrop.io/rest/v1/raindrops/%s",
+    id[1]
+  ) -> get_raindrop_url
+
+  httr::GET(
+    url = get_raindrop_url,
+    .RAINDROP_UA,
+    raindrop_auth()
+  ) -> res
+
+  httr::stop_for_status(res)
+
+  out <- httr::content(res, as = "text")
+
+  out <- jsonlite::fromJSON(out)
+
+  if (out$result) {
+
+    out <- out$items
+
+    colnames(out) <- c(
+      "excerpt", "type", "cover", "tags", "removed", "id", "title",
+      "media", "link", "collection", "cover_id", "user", "created",
+      "last_update", "domain", "creator", "sort", "cache",
+      "collection_id"
+    )
+
+    out$tags <- I(list(out$tags))
+    out$media <- I(list(out$media))
+    out$collection <- I(list(out$collection))
+    out$user <- I(list(out$user))
+    out$creator <- I(list(out$creator))
+    out$cache <- I(list(out$cache))
+
+    class(out) <- c("tbl_df", "tbl", "data.frame")
+
+  }
+
+  out
+
+}
+
+
+
--- a/R/user.R
+++ b/R/user.R
@ -0,0 +1,24 @@
+# https://api.raindrop.io/rest/v1/user
+
+#' Get currently authenticated user details
+#'
+#' @export
+get_user <- function(api_key = raindrop_api_token()) {
+
+  httr::GET(
+    url = "https://api.raindrop.io/rest/v1/user",
+    .RAINDROP_UA,
+    raindrop_auth()
+  ) -> res
+
+  httr::stop_for_status(res)
+
+  out <- httr::content(res, as = "text")
+
+  out <- jsonlite::fromJSON(out)
+
+  out
+
+}
+
+
--- a/README.Rmd
+++ b/README.Rmd
@ -23,6 +23,11 @@ The following functions are implemented:
 hrbrpkghelpr::describe_ingredients()
 ```

+NOTE: This is a woefully incomplete wrapper (so far). You are def encouraged
+to contribute if you use Raindrop and the package will be a full wrapper. This
+skeleton was made to remind myself to make this package and have something to
+hack on during long-running Athena queries or tedious conference calls.
+
 ## Installation

 ```{r install-ex, results='asis', echo=FALSE, cache=FALSE}
--- a/README.md
+++ b/README.md
@ -0,0 +1,81 @@
+
+[![Project Status: Active – The project has reached a stable, usable
+state and is being actively
+developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
+[![Signed
+by](https://img.shields.io/badge/Keybase-Verified-brightgreen.svg)](https://keybase.io/hrbrmstr)
+![Signed commit
+%](https://img.shields.io/badge/Signed_Commits-100%25-lightgrey.svg)
+[![Linux build
+Status](https://travis-ci.org/hrbrmstr/bacharach.svg?branch=master)](https://travis-ci.org/hrbrmstr/bacharach)  
+![Minimal R
+Version](https://img.shields.io/badge/R%3E%3D-3.2.0-blue.svg)
+![License](https://img.shields.io/badge/License-AGPL-blue.svg)
+
+# bacharach
+
+Tools to Work with the Raindrop API
+
+## Description
+
+Raindrop <https://raindrop.io> provides a URL bookmarking service and an
+API for working with that service and more. Tools are provided to work
+with the Raindrop API. A Raindrop API key (free) is required.
+
+## What’s Inside The Tin
+
+The following functions are implemented:
+
+  - `get_collection`: Get a collection
+  - `get_raindrop`: Get a single raindrop
+  - `get_raindrops`: Get all raindrops from a collection (TODO
+    pagination)
+  - `get_user`: Get currently authenticated user details
+  - `raindrop_api_token`: Get or set RAINDROP\_API\_TOKEN value
+  - `raindrop_parse_url`: Parse and extract useful info from any URL
+
+NOTE: This is a woefully incomplete wrapper (so far). You are def
+encouraged to contribute if you use Raindrop and the package will be a
+full wrapper. This skeleton was made to remind myself to make this
+package and have something to hack on during long-running Athena queries
+or tedious conference calls.
+
+## Installation
+
+``` r
+remotes::install_git("https://git.rud.is/hrbrmstr/bacharach.git")
+# or
+remotes::install_git("https://git.sr.ht/~hrbrmstr/bacharach")
+# or
+remotes::install_gitlab("hrbrmstr/bacharach")
+# or
+remotes::install_bitbucket("hrbrmstr/bacharach")
+# or
+remotes::install_github("hrbrmstr/bacharach")
+```
+
+NOTE: To use the ‘remotes’ install options you will need to have the
+[{remotes} package](https://github.com/r-lib/remotes) installed.
+
+## Usage
+
+``` r
+library(bacharach)
+
+# current version
+packageVersion("bacharach")
+## [1] '0.1.0'
+```
+
+## bacharach Metrics
+
+| Lang | \# Files |  (%) | LoC |  (%) | Blank lines |  (%) | \# Lines |  (%) |
+| :--- | -------: | ---: | --: | ---: | ----------: | ---: | -------: | ---: |
+| R    |        8 | 0.89 | 159 | 0.95 |          90 | 0.85 |       54 | 0.63 |
+| Rmd  |        1 | 0.11 |   8 | 0.05 |          16 | 0.15 |       32 | 0.37 |
+
+## Code of Conduct
+
+Please note that this project is released with a Contributor Code of
+Conduct. By participating in this project you agree to abide by its
+terms.
--- a/man/bacharach.Rd
+++ b/man/bacharach.Rd
@ -4,9 +4,11 @@
 \name{bacharach}
 \alias{bacharach}
 \alias{bacharach-package}
-\title{...}
+\title{Tools to Work with the Raindrop API}
 \description{
-A good description goes here otherwise CRAN checks fail.
+Raindrop \url{https://raindrop.io} provides a URL bookmarking service
+and an API for working with that service and more. Tools are provided to
+work with the Raindrop API.nA Raindrop API key (free) is required.
 }
 \seealso{
 Useful links:
--- a/man/get_collection.Rd
+++ b/man/get_collection.Rd
@ -0,0 +1,14 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/collections.R
+\name{get_collection}
+\alias{get_collection}
+\title{Get a collection}
+\usage{
+get_collection(id, api_key = raindrop_api_token())
+}
+\arguments{
+\item{id}{collection id}
+}
+\description{
+Get a collection
+}
--- a/man/get_raindrop.Rd
+++ b/man/get_raindrop.Rd
@ -0,0 +1,14 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/raindrops.R
+\name{get_raindrop}
+\alias{get_raindrop}
+\title{Get a single raindrop}
+\usage{
+get_raindrop(id, api_key = raindrop_api_token())
+}
+\arguments{
+\item{id}{raindrop id}
+}
+\description{
+Get a single raindrop
+}
--- a/man/get_raindrops.Rd
+++ b/man/get_raindrops.Rd
@ -0,0 +1,14 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/raindrops.R
+\name{get_raindrops}
+\alias{get_raindrops}
+\title{Get all raindrops from a collection (TODO pagination)}
+\usage{
+get_raindrops(id, api_key = raindrop_api_token())
+}
+\arguments{
+\item{id}{collection id}
+}
+\description{
+TODO pagination
+}
--- a/man/get_user.Rd
+++ b/man/get_user.Rd
@ -0,0 +1,11 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/user.R
+\name{get_user}
+\alias{get_user}
+\title{Get currently authenticated user details}
+\usage{
+get_user(api_key = raindrop_api_token())
+}
+\description{
+Get currently authenticated user details
+}
--- a/man/raindrop_api_token.Rd
+++ b/man/raindrop_api_token.Rd
@ -0,0 +1,25 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/api-key.R
+\name{raindrop_api_token}
+\alias{raindrop_api_token}
+\title{Get or set RAINDROP_API_TOKEN value}
+\usage{
+raindrop_api_token(force = FALSE)
+}
+\arguments{
+\item{force}{Force setting a new Raindrop key for the current environment?}
+}
+\value{
+atomic character vector containing the Raindrop token
+}
+\description{
+The API wrapper functions in this package all rely on a Raindrop
+token residing in the environment variable \code{RAINDROP_API_TOKEN}.
+The easiest way to accomplish this is to set it
+in the \code{.Renviron} file in your home directory.
+}
+\details{
+You can obtain an Raindrop token by going visiting
+\url{https://app.raindrop.io/#/settings/apps/dev}. Use the
+\strong{test token}.
+}
--- a/man/raindrop_parse_url.Rd
+++ b/man/raindrop_parse_url.Rd
@ -0,0 +1,14 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/import.R
+\name{raindrop_parse_url}
+\alias{raindrop_parse_url}
+\title{Parse and extract useful info from any URL}
+\usage{
+raindrop_parse_url(url, api_key = raindrop_api_token())
+}
+\arguments{
+\item{url}{a URL}
+}
+\description{
+Parse and extract useful info from any URL
+}