Secure and Intuitive Access to 'Plug' Interface

Provides a secure and user-friendly interface to interact with the 'Plug' < https://plugbytpf.com.br> 'API'. It enables developers to store and manage credentials and tokens securely using the 'keyring' package, and to retrieve data from 'API' endpoints with the 'httr2' package, using 'SQL' queries built safely from templates. Designed for simplicity and security, the package facilitates seamless integration with the 'Plug' ecosystem.

plug

The Plug API Integration Package provides an intuitive and secure interface to interact with the Plug API. It enables developers to store user credentials securely, fetch data using custom SQL queries, and manage authentication tokens automatically.

Note: To access the Plug API, you must have valid credentials (username and password) provided by the API administrators.

Note: Plug uses Microsoft SQL as its database system, so SQL queries must adhere to Microsoft SQL Server syntax (e.g., SELECT TOP 1 instead of LIMIT).

Installation

You can install the released version of the package from CRAN:

install.packages("plug")

Or the development version from GitHub:

# install.packages("remotes")
remotes::install_github("StrategicProjects/plug")

Features

• Secure Credential Storage: Safely store and retrieve user credentials with keyring.
• Token Management: Automatically handle API token generation and expiration.
• Query Execution: Execute custom SQL queries using the Plug API, with values safely inserted in query templates.
• Data Download: Retrieve all data from specific tables with ease.

Getting Started

Before using the package, you need to store your Plug API credentials securely:

library(plug)

# Store your username and password
plug_store_credentials("your_username", "your_password")

Fetching a Token

The package automatically fetches and caches an authentication token. If you need to retrieve it manually, use:

# Fetch a valid token
token <- plug_get_valid_token()

Listing and Removing Stored Credentials and Tokens

You can list stored credentials and tokens:

# List credentials (the password is returned in plain text)
credentials <- plug_list_credentials()

# List tokens
tokens <- plug_list_tokens()

And remove them from the keyring:

# Remove only the cached token
plug_clear_credentials(credentials = FALSE)

# Remove credentials and token
plug_clear_credentials()

Executing SQL Queries

You can execute custom SQL queries on the Plug API:

# Example: Execute a query
data <- plug_execute_query("SELECT TOP 1 * FROM Contratos_VIEW")

Values can be safely inserted in the query with placeholders, using the same syntax as glue::glue_sql():

data <- plug_execute_query(
  "SELECT * FROM {`base`} WHERE Ano IN ({years*}) AND Situacao = {status}",
  base = "Contratos_VIEW",
  years = c(2023, 2024),
  status = "Ativo"
)

Downloading a Table

# Example: Download All Data from a Table
data <- plug_download_base(base_name = "Contratos_VIEW")

Development

This package is under active development. Contributions are welcome! If you encounter any issues, please open an issue on GitHub.

License

This package is licensed under the MIT License.