---
output: rmarkdown::github_document
editor_options: 
  chunk_output_type: console
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(message=FALSE, warning=FALSE)
options(width=120)
```

![](man/figures/venus-fly-trap.jpg)

# seymour

Tools to Work with the 'Feedly' 'API'

## Description

'Feedly' is a news aggregator application for various web browsers and mobile devices running 'iOS' and 'Android', also available as a cloud-based service. It compiles news feeds from a variety of online sources for the user to customize and share with others. Methods are provided to retrieve information about and contents of 'Feedly' collections and streams.

## What's Inside The Tin

The following API functions are implemented:

- `feedly_access_token`:	Retrieve the Feedly Developer Token
- `feedly_collections`:	Retrieve Feedly Connections
- `feedly_categories`:  Show Feedly Categories
- `feedly_entry`:  Get a single entry by id
- `feedly_enterprise_profile`:	Retrieve Your Feedly Enterprise Profile
- `feedly_feed_meta`:	Retrieve Metadata for a Feed
- `feedly_opml`:	Retrieve Your Feedly OPML File
- `feedly_profile`:	Retrieve Your Feedly Profile
- `feedly_refresh_token`:	Generate a Feedly Refresh Token
- `feedly_search_contents`:	Search content of a stream
- `feedly_search_title`:	Find feeds based on title, url or '#topic'
- `feedly_stream`:	Retrieve contents of a Feedly "stream"
- `feedly_subscribe`:	Subscribe to an RSS feed
- `feedly_subscriptions`: Retrieve Feedly Subscriptions
- `feedly_tags`:	Retrieve List of Tags

The following helper functions are available:

- `feedly_continue`: Helper function to iterate through a `feedly_stream()` result set
- `render_stream`:  Render a Feedly Stream Data Frame to R Markdown

The following helper references are available:

- `global_resource_ids`:	Global Resource Ids Helper Reference

## Authentication (README)

You need a developer token to access most of the API endpoints. You can do that via links provdied by (<https://developer.feedly.com/v3/auth/>). There are no plans to support OAuth or token refreshing unless there is sufficient demand via Git[la|hu]b issues & issue votes.

### NOT ALL ENDPOINTS REQUIRE AUTHENTICATION

Neither `feedly_search_title()` nor `feedly_stream()` require authentication (i.e. you do not need a developer token) to retrieve the contents of the API call. For `feedly_stream()` You _do_ need to know the Feedly-structured feed id which is (generally) `feed/FEED_URL` (e.g. `feed/http://feeds.feedburner.com/RBloggers`).

## Installation

```{r eval=FALSE}
devtools::install_github("hrbrmstr/seymour")
```

```{r message=FALSE, warning=FALSE, error=FALSE, include=FALSE}
options(width=120)
```

## Usage

```{r message=FALSE, warning=FALSE, error=FALSE}
library(seymour)
library(tidyverse) # mostly for printing

# current verison
packageVersion("seymour")

```

### Collections

```{r collections, cache=TRUE}
coll <- feedly_collections()

filter(coll, title == "R-bloggers") %>% 
  glimpse()
```

### Streams

```{r streams, cache=TRUE}
feedly_stream(
  stream_id = "feed/http://feeds.feedburner.com/RBloggers",
) -> rbloggers

glimpse(rbloggers$items)

rbloggers$items
```

### Feed Metadata

```{r feed_metadata, cache=TRUE}
feedly_feed_meta("https://feeds.feedburner.com/rweeklylive") %>% 
  glimpse()
```

### OPML Retrieval

```{r opml_retrieval, cache=TRUE}
feedly_opml(as = "parsed")
```

### Title Search

```{r title_search, cache=TRUE}
rst <- feedly_search_title("data science")
glimpse(rst$results)
```

### Contents Search

```{r contents_search, cache=TRUE}
rsc <- feedly_search_contents("data science")
glimpse(rsc$results)
```

### API Usage Rate Limit Info

```{r rate_limit, cache=TRUE}
fp <- feedly_profile()
fp[grepl("rate_limit", names(fp))]
```

### Sample Stream Report

```{r sample_stream_report, eval=FALSE}
fp <- feedly_profile() # get profile to get my id

# use the id to get my "security" category feed
fs <- feedly_stream(sprintf("user/%s/category/security", fp$id))

# get the top 10 items with engagement >= third quartile of all posts
# and don't include duplicates in the report
mutate(fs$items, published = as.Date(published)) %>% 
  filter(published >= as.Date("2018-12-01")) %>%
  filter(engagement > fivenum(engagement)[4]) %>% 
  filter(!is.na(summary_content)) %>% 
  mutate(alt_url = map_chr(alternate, ~.x[[1]])) %>% 
  distinct(alt_url, .keep_all = TRUE) %>% 
  slice(1:10) -> for_report

# render the report
render_stream(
  feedly_stream = for_report, 
  title = "Cybersecurity News", 
  include_visual = TRUE,
  browse = TRUE
)
```

Click on the following to see the complete render or view the [Rmd](https://rud.is/seymour/sample-report.Rmd) or [HTML](https://rud.is/seymour/sample-report.html) in your browser:

<center><a href="sample-report.jpg"><img src="report-thumb.png"/></a></center>

## Package Code Metrics

```{r pkg_metrics}
cloc::cloc_pkg_md()
```

## Code of Conduct
 
Please note that the [34m'seymour'[39m project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.

## Image Credit
<!-- HTML Credit Code for Can Stock Photo -->
<a href="https://www.canstockphoto.com">(c) Can Stock Photo / lineartestpilot</a>