atrrr

AT Protocol (Authenticated Transfer Protocol behind Bluesky) R package

https://github.com/jbgruber/atrrr

Keywords

Repository

AT Protocol (Authenticated Transfer Protocol behind Bluesky) R package

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  message = FALSE,
  warning = FALSE,
  fig.path = "man/figures/README-",
  out.width = "100%"
)
knitr::knit_hooks$set(document = function(x, options) 
  gsub("(figures/", "(vignettes/figures/", x, fixed = TRUE))

library(dplyr)
library(purrr)
```

# atrrr 


[![CRAN status](https://www.r-pkg.org/badges/version/atrrr)](https://CRAN.R-project.org/package=atrrr)
[![CRAN_Download_Badge](https://cranlogs.r-pkg.org/badges/grand-total/atrrr)](https://cran.r-project.org/package=atrrr)
[![R-CMD-check](https://github.com/JBGruber/atrrr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/JBGruber/atrrr/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/JBGruber/atrrr/branch/main/graph/badge.svg)](https://app.codecov.io/gh/JBGruber/atrrr?branch=main)


The goal of atrrr[^1] is to wrap the AT Protocol (Authenticated Transfer Protocol) behind Bluesky. [*And we have actually already fulfilled this goal!*](#want-to-help).

The entire protocol is open and documented in so-called [lexicons](https://atproto.com/guides/lexicon), from which we autogenerated `R` functions.

These are not exported, however, since dealing with them is a bit advanced.
Rather we have some nice human-generated functions with documentation and examples.

## Installation

You can install atrrr from CRAN with:

``` r
install.packages("atrrr")
```

You can install the development version of `atrrr` like so (install the `remotes` package first, with `install.packages("remotes")`, if you don't have that yet):

``` r
# install.packages("remotes")
remotes::install_github("JBGruber/atrrr")
```

## Load the package

```{r setup}
library(atrrr)
```


## Authentication

The first time you make a request, you will be prompted automatically to enter your user handle and an app password to authenticate `atrrr` to communicate with BlueSky for you.

![RStudio Popup](figures/password_popup.png)

The page to generate app passwords is also automatically opened for you.

![page to create new app passwords](figures/app_password.png)

However, you can also trigger this process manually:

```{r eval=FALSE}
auth("jbgruber.bsky.social")
```

This can be useful if you want to replace an old token as it is permanently stored encrypted on disk.



## Retrieve Skeets (`get_skeets_authored_by`)

To fetch all the skeets by a specific user, use the `get_skeets_authored_by` function. *Note this also includes quote skeets and reskeets.* You can also opt not to parse the result by setting `parse = FALSE`, however it is recommended to use the default parse option which results in a (more) tidy tibble.

```{r}
get_skeets_authored_by(actor = "benguinaudeau.bsky.social", parse = TRUE) |>
  dplyr::glimpse()
```




## Analyzing Feeds on Blue Sky

On Blue Sky users have the ability to create custom feeds based on specific keywords. These feeds aggregate content, for instance, a user might curate a feed around the hashtag `#rstats` to gather all relevant content about. Let's delve into the dynamics of such feeds.


Our starting point is to extract the posts from the `#rstats` feed created by "andrew.heiss.phd".


```{r}
# Fetching the feed posts
feeds <- get_feeds_created_by(actor = "andrew.heiss.phd") 

# Filtering for a specific keyword, for example "#rstats"
rstat_feed <- feeds |>
  filter(displayName == "#rstats")

# Extracting posts from this curated feed
rstat_posts <- get_feed(rstat_feed$uri, limit = 200) |>
  dplyr::glimpse()
```

## Learn More?

Start with the [Basic Usage](https://jbgruber.github.io/atrrr/articles/Basic_Usage.html) vignette to learn more.

# Want to help?

You can help by creating an [issue](https://github.com/JBGruber/atrrr/issues/new/choose) requesting new features or reporting bugs.

If you are a developer, we are happy to accept pull requests.
It should be fairly straightforward, as all endpoints are already covered by automatically generated function.
For example, the endpoint [app.bsky.actor.getProfiles](https://docs.bsky.app/docs/api/app-bsky-actor-get-profiles) is accessible via `atrrr:::app_bsky_actor_get_profiles()`.
The function `get_user_info()` is just a thin wrapper around that and calls an optional parsing function:

```
get_user_info <- function(actor,
                          parse = TRUE,
                          .token = NULL) {

  # we need to use do.call so objects are passed to the right environment
  res <- do.call( 
    what = app_bsky_actor_get_profiles,
    args = list(
      actor,
      .token = .token, # tokens are handled automatically under the hood
      .return = "json"
    )) |>
    purrr::pluck("profiles")

  if (parse) {
    res <- parse_actors(res)
  }
  return(res)
}
```
If you find an endpoint at  that interests you, you can write a similar wrapper and contribute it to the package (or build something new on top of it).
But please open an [issue](https://github.com/JBGruber/atrrr/issues) first, so we don't do duplicated work.

[^1]: before 2024-01-04, this package was [called `atr`](https://github.com/JBGruber/atrrr/issues/12), meaning an R package for the AT protocol (similar to httr, which is a package for the HTTProtocol).
  Unfortunatley, when we wanted to release the package on CRAN, the name `atr` was rejected, as a package of the same name existed some time ago.
  So we added two "r" to make the package go brrr anyway!

Owner

GitHub Events

Issues and Pull Requests

Last synced: 10 months ago

Packages