Metadata-Version: 2.4
Name: envbee-sdk
Version: 1.8.0
Summary: envbee SDK for Python
Home-page: https://github.com/envbee/envbee-python-sdk
Author: envbee
Author-email: info@envbee.dev
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: diskcache
Requires-Dist: platformdirs
Requires-Dist: requests
Requires-Dist: cryptography
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# envbee Python SDK

envbee SDK is a Python client for interacting with the envbee API (see [https://envbee.dev](https://envbee.dev)).
This SDK provides methods to retrieve variables and manage caching for improved performance.

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
- [Methods](#methods)
- [Encryption](#encryption)
- [Logging](#logging)
- [Caching](#caching)
- [API Documentation](#api-documentation)
- [License](#license)

## Installation

To install the envbee SDK, use pip:

```bash
pip install envbee-sdk
```

## Usage

Instantiate the `Envbee` class with your API credentials:

```python
from envbee_sdk import Envbee

client = Envbee(
    api_key="your_api_key",
    api_secret=b"your_api_secret",
    enc_key=b"32-byte-encryption-key-goes-here"  # optional, could be a string or a 32 bytes buffer
)

# Retrieve a variable
value = client.get("VariableName")

# Retrieve multiple variables
variables, metadata = client.get_variables()
```

## Methods

- `get(variable_name: str) -> any`: fetch a variable value.
- `get_variables(offset: int = None, limit: int = None) -> tuple[list[dict], Metadata]`: fetch multiple variable definitions with pagination.

## Encryption

Some variables stored in envbee are encrypted using AES-256-GCM (via the [cryptography](https://cryptography.io/en/latest/) library). Encrypted values are prefixed with `envbee:enc:v1:`.

- If an encrypted variable is fetched and you provide a correct decryption key (`enc_key`), the SDK will decrypt it automatically.
- If no key or a wrong key is provided, a `RuntimeError` will be raised on decryption.
- The encryption key is never sent to the API; all decryption is performed locally.
- Cached values are stored exactly as received from the API (encrypted or plain-text).

Example with encryption key:

```python
client = Envbee(
    api_key="your_api_key",
    api_secret=b"your_api_secret",
    enc_key=b"32-byte-encryption-key-goes-here"
)
```

## Logging

Configure logging as needed. The SDK logger name is `envbee_sdk`. Example:

```python
import logging

logging.basicConfig(level=logging.ERROR)

sdk_logger = logging.getLogger("envbee_sdk")
sdk_logger.setLevel(logging.DEBUG)  # for detailed logs

# Example usage within the SDK
sdk_logger.debug("This is a debug message from the SDK.")
sdk_logger.info("Informational message from the SDK.")
```

## Caching

The SDK caches variables locally to provide fallback data when offline or the API is unreachable. The cache is updated after each successful API call. Local cache stores variables as received from the API, encrypted or plain.

- Encryption key is never stored in cache or sent to API.
- All encryption/decryption happens locally with AES-256-GCM.

## API Documentation

For more information on envbee API endpoints and usage, visit the [official API documentation](https://docs.envbee.dev).

## License

This project is licensed under the MIT License. See the LICENSE file for details.
