---
title: "Exploring endpoints, parameters, and fields"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Exploring endpoints, parameters, and fields}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE,
  purl = FALSE  # The TCE-PE API is geo-restricted (Brazil-only). Skip code
                # extraction so R CMD check does not try to run it on CRAN
                # machines outside Brazil.
)
```

> **Note** — Code chunks are shown but not executed at build time
> (`eval = FALSE`). The discovery snippets (`tce_catalog()`,
> `tce_params()`, `tce_fields()`) work offline anywhere and can be run
> as-is from any network. The query snippets require a Brazilian IP
> (the TCE-PE API is geo-restricted).

This vignette shows how to *discover* endpoints and their input/output
metadata using the built-in catalog shipped with **tceper**.

## Discover endpoints with `tce_catalog()`

```{r catalog}
library(tceper)

tce_catalog()
```

Filter by keyword:

```{r catalog-search}
tce_catalog(search = "licit")
```

## Inspect one endpoint

Pick an endpoint name from `tce_catalog()`. For instance, `LicitacaoUG`:

### Input parameters

```{r params}
tce_params("LicitacaoUG")
```

`api_name` is the exact query name expected by the API.

`r_name` is the `snake_case` name you can pass to the R wrapper.

### Output fields

```{r fields}
tce_fields("LicitacaoUG")
```

## Query using `snake_case` arguments

Once you know which parameters exist, you can query with `snake_case`
arguments (the package maps them to `api_name` internally).

```{r query}
tce_bids(anomodalidade = "2025")
```

## Parameter validation

`tceper` validates query parameters against the endpoint catalog. If you pass
a parameter that does not exist for that endpoint, it aborts and shows the
allowed parameter list.

```{r invalid, eval = FALSE}
# Example (invalid parameter name for this endpoint):
tce_contracts(fog = "510101", verbose = TRUE)
```

To avoid this, inspect allowed parameters first:

```{r inspect-first}
tce_params("Contratos")
```

## Working with cache

Many wrapper functions can cache results in-memory for faster repeated calls.

You can inspect cache state with:

```{r cache-info}
tce_cache_info()
```

And clear it with:

```{r cache-clear}
tce_cache_clear()
```

When `verbose = TRUE`, cache hits may print a short message indicating the
returned object comes from cache.