---
title: "Quick Start Guide"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Quick Start Guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

This vignette demonstrates a typical workflow using the **bunddev** package to discover an API, inspect its parameters, set up authentication (if needed), retrieve tidy data, and visualise it.

## 1. Install and load the package

```r
# Install the development version (if not already installed)
# remotes::install_github("mchlbckr/bunddev")

library(bunddev)
```

## 2. List available APIs

```r
# Show the first few entries in the bundled registry
available <- bunddev_registry()
head(available)
```

You can filter by tag or authentication type, for example:

```r
bunddev_list(tag = "jobs")          # APIs related to job searching
bunddev_list(auth = "api_key")      # APIs that require an API key
```

## 3. Inspect parameters for a chosen API

Suppose we are interested in the **SMARD** electricity market API.

```r
bunddev_parameters("smard")                     # All parameters
bunddev_parameters("smard", name = "resolution")  # Specific parameter details
```

## 4. Set up authentication (if required)

You can store your API keys securely in a `.Renviron` file, which R loads automatically at startup. Add a line like the following to `~/.Renviron` (or a project‑specific `.Renviron` in the package root):

```text
SMARD_API_KEY=your-secret-key
```

Then reference the variable in R without hard‑coding the key:

```r
bunddev_auth_set("smard", type = "api_key", env_var = "SMARD_API_KEY", scheme = "Bearer")
```

Alternatively, for a quick session you can set the variable directly with `Sys.setenv()` as shown earlier.


## 5. Retrieve tidy data

Fetch a time‑series from SMARD and flatten list‑columns:

```r
# Get hourly electricity generation for region DE, series ID 410
ts <- smard_timeseries(410, region = "DE", resolution = "hour")
head(ts)
```

## 6. Visualise the result

```r
library(ggplot2)
ggplot(ts, aes(x = time, y = value)) +
  geom_line() +
  labs(title = "SMARD Time Series", x = "Time", y = "MW")
```

## 7. Rate‑limit handling

If you need to enforce a custom rate limit:

```r
bunddev_rate_limit_set("smard", max_per_hour = 60)
```

## 8. Further help

All functions come with detailed help pages (e.g., `?smard_timeseries`). Use `bunddev_parameters()` and `bunddev_parameter_values()` to explore allowed enum values.

---

*This vignette is intentionally simple and runs without contacting any live API (except when you actually execute the examples). It is designed to work during package checks and as a quick reference for users.*