---
title: "User-and-Website-APIs"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{User-and-Website-APIs}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## User APIs, Apps APIs

The web interface of Piwik Pro is good for manual setup. But if you need to check
which permissions a specific user has it gets disgusting.

That's when you want to use the various APIs Piwik Pro offers to solve this 
problem programmatically. 

So `piwikproR` was extended by some parts of the users-API and apps-API.

## Which Websites are tracked?

So first, let's fetch a list of websites (called apps in Piwik Pro API).

```{r, eval = FALSE}
library(piwikproR)
# Piwik credentials
piwik_pro_credentials <- list(
  client_id = "my_client_id",
  client_secret = "my_client_secret",
  url = "https://my_site.piwik.pro"
 )
# Fetch a Piwik token
token <- get_login_token(piwik_pro_credentials)
```

There are two kinds of 'websites' being tracked: **Apps** are single instances
of websites. These can be combined to **metasites**. 
See https://help.piwik.pro/support/reports/meta-sites/ for more about metasites.

Therefore there are two
different ways to fetch the list of those apps/metasites.

### Apps

```{r, eval = FALSE}
apps <- get_apps_list(token) 
```

```{r, echo = FALSE}
apps <- tibble::tribble(
  ~type, ~id, ~name, ~addedAt, ~updatedAt,
  "ppms/meta-site", "some-hex-id-number-1", "site-name-1.com", lubridate::ymd_hms("2022-01-02 08:10:20"), lubridate::ymd_hms("2022-01-04 10:08:10"),
  "ppms/meta-site", "some-hex-id-number-2", "site-name-2.org", lubridate::ymd_hms("2022-02-02 08:10:20"), lubridate::ymd_hms("2022-02-04 10:08:10"),
  "ppms/meta-site", "some-hex-id-number-3", "site-name-3.net", lubridate::ymd_hms("2022-03-02 08:10:20"), lubridate::ymd_hms("2022-03-04 10:08:10")
)
```

The result of `get_apps_list()` is a data.frame containing the available
apps with some information, esp. an id.

```{r}
apps
```

The id can be used for further queries.

### Metasites

Metasites can be fetched similarly:

```{r, eval = FALSE}
metasites <- get_metasites_list(token)
```

```{r, echo = FALSE}
metasites <- tibble::tribble(
  ~type, ~id, ~name, ~created_at, ~updated_at,
  "ppms/apps", "some-hex-id-meta-1", "Meta site 1", lubridate::ymd_hms("2022-01-02 08:10:20"), lubridate::ymd_hms("2022-01-04 10:08:10"),
  "ppms/apps", "some-hex-id-meta-2", "Meta site 2", lubridate::ymd_hms("2022-02-02 08:10:20"), lubridate::ymd_hms("2022-02-04 10:08:10"),
  "ppms/apps", "some-hex-id-meta-3", "Meta site 3", lubridate::ymd_hms("2022-03-02 08:10:20"), lubridate::ymd_hms("2022-03-04 10:08:10")
)
```

The result looks similar. Unfortunately Piwik Pro named the fields slightly differently.

```{r}
metasites
```
# App Details

Knowing the id of an app you can use `get_app_detail()` to fetch the configuration
and detailed information of this app.

This function may be useful if you want to check whether all of your apps are 
configured the same way or you're looking for all apps with enabled ecommerce
extension.

# Users and Permissions

As mentioned above it can be tedeous if you're looking for all permissions a
user has.
So a good way to solve this problem is the API by calling `get_permissions_for_app()`.

Let's create a function which gets for a given app all users who have permission
and add the app-id into column site.

```{r, eval = FALSE}
permissions_per_site <- function(app) {
  get_permissions_for_app(token, app) %>% 
    mutate(site = app)
}
```

The result looks like this

```{r, echo = FALSE}
permissions <- tibble::tribble(
  ~type, ~id, ~email, ~permission, ~group_permissions, ~overall_permissions, ~site,
  'app/permission/user', 'some-hex-id-1', 'email@user-1.com', 'no-access', 'edit-publish', 'edit-publish', 'some_app_id',
  'app/permission/user', 'some-hex-id-2', 'email@user-2.com', 'manage', 'no-access', 'manage', 'some_app_id'
)
```

```{r, eval = FALSE}
permissions <- permissions_per_site('some_app_id')
```
```{r}
permissions
```

There are two ways to give permissions to a user: direct on the app-basis or using
usergroups (see https://help.piwik.pro/support/account/site-app-permissions/).
Both are returned in column `permission` resp. `group_permissions`. The resulting
permission is returned in column `overall_permissions`.

So now it's easy to iterate over all apps, get the permissions of each user and
filter for only the users who have permissions.

```{r, eval = FALSE}
complete_permissions <- apps %>% 
  pull(id) %>% 
  map_dfr(permissions_per_site) %>% 
  left_join(apps, by = c("site" = "id")) %>% 
  filter(overall_permissions != "no-access")
```