Metadata-Version: 2.4
Name: veilio-sdk
Version: 1.1.1
Summary: Official Veilio SDK for Python - Data tokenization and cyber-resilience API client
Home-page: https://github.com/veilio/veilio-sdk-python
Author: Veilio
Author-email: support@veilio.xyz
Project-URL: Documentation, https://docs.veilio.xyz
Project-URL: Source, https://github.com/VeilioAPI/veilio-sdk-python
Project-URL: Support, https://veilio.xyz/contact
Keywords: veilio tokenization data-protection cyber-resilience privacy security api-client
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: mypy>=0.991; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# veilio-sdk

Official Python SDK for Veilio - Data tokenization and cyber-resilience API.

## Installation

```bash
pip install veilio-sdk
```

## Quick Start

```python
from veilio_sdk import VeilioClient

# Initialize client
client = VeilioClient(
    api_key="veil_dev_your-api-key-here",
    base_url="https://app.veilio.xyz/api"  # Optional, defaults to production
)

# Tokenize sensitive data
result = client.tokenize(
    data="john@example.com",
    type="email"
)

print(f"Token: {result['token']}")

# Detokenize when needed
original = client.detokenize(
    token=result["token"],
    reason="Send email notification"
)

print(f"Original: {original['data']}")
```

## Features

- ✅ **Simple tokenization** - Tokenize single fields
- ✅ **Bulk operations** - Tokenize/detokenize multiple fields at once
- ✅ **Multi-format support** - JSON, CSV, SQL formats
- ✅ **Crypto shredding** - Immediate token shredding (`shred_token`)
- ✅ **Retention policies** - Automatic shredding via `retention`
- ✅ **Automatic retries** - Handles rate limits and network errors
- ✅ **Error handling** - Clear error messages and types
- ✅ **Type hints** - Full type annotations included

## API Reference

### Constructor

```python
client = VeilioClient(
    api_key: str,              # Required: Your Veilio API key
    base_url: str = "https://app.veilio.xyz/api",  # Optional
    timeout: int = 30,         # Optional: Request timeout in seconds
    max_retries: int = 3       # Optional: Max retries for failed requests
)
```

### Methods

#### `tokenize(data, type=None, metadata=None, retention=None)`

Tokenize a single field.

```python
result = client.tokenize(
    data="john@example.com",
    type="email",              # Optional
    metadata={"source": "form"},  # Optional
    retention={                  # Optional
        "ttlDays": 30
        # or "retentionUntil": "2026-12-31T23:59:59.000Z"
    }
)

# Returns: {"token": str, "createdAt": str, "retentionUntil": str | None}
```

#### `tokenize_bulk(fields)`

Tokenize multiple fields in one request.

```python
result = client.tokenize_bulk([
    {"data": "john@example.com", "type": "email"},
    {"data": "+33612345678", "type": "phone"}
])

# Returns: {
#     "tokens": [...],
#     "summary": {"total": int, "success": int, "failed": int},
#     "errors": [...],  # Optional
#     "createdAt": str
# }
```

#### `detokenize(token, reason=None)`

Detokenize a single token.

```python
result = client.detokenize(
    token="tok_abc123...",
    reason="Send email"  # Optional
)

# Returns: {"data": str, "accessedAt": str}
```

#### `shred_token(token, reason=None)`

Shred a token immediately (cryptographic erasure).

```python
result = client.shred_token(
    token="tok_abc123...",
    reason="GDPR delete request"  # Optional
)

# Returns: {"token": str, "shreddedAt": str}
```

#### `detokenize_bulk(tokens)`

Detokenize multiple tokens in one request.

```python
result = client.detokenize_bulk([
    {"token": "tok_abc123...", "reason": "Processing"},
    {"token": "tok_def456...", "reason": "Processing"}
])

# Returns: {
#     "results": [...],
#     "summary": {"total": int, "success": int, "failed": int},
#     "errors": [...],  # Optional
#     "accessedAt": str
# }
```

#### `tokenize_format(data, format=None, options=None)`

Tokenize structured data (JSON, CSV, SQL).

```python
json_data = '{"email": "john@example.com"}'

result = client.tokenize_format(
    data=json_data,
    format="json",  # Optional: auto-detected if omitted
    options={
        "fields": ["email"]  # Optional: tokenize only specific fields
    }
)

# Returns: {
#     "format": str,
#     "tokenizedData": str,
#     "tokens": [...],
#     "metadata": {...},
#     "summary": {"totalFields": int, "tokenizedFields": int}
# }
```

#### `detokenize_format(tokenized_data, format, tokens)`

Detokenize structured data.

```python
result = client.detokenize_format(
    tokenized_data='{"email": "tok_abc123..."}',
    format="json",
    tokens=[{"path": "email", "token": "tok_abc123..."}]
)

# Returns: {
#     "format": str,
#     "detokenizedData": str,
#     "summary": {"tokensProcessed": int}
# }
```

## Examples

### Basic Usage

```python
from veilio_sdk import VeilioClient
import os

client = VeilioClient(api_key=os.getenv("VEILIO_API_KEY"))

# Tokenize
token = client.tokenize(data="sensitive@data.com", type="email")

# Store token in your database
# db.execute("INSERT INTO users (email) VALUES (?)", (token["token"],))

# Later, detokenize when needed
user = db.get_user(user_id)
email = client.detokenize(token=user.email, reason="Send notification")
```

### Bulk Operations

```python
# Tokenize multiple fields at once
result = client.tokenize_bulk([
    {"data": "john@example.com", "type": "email"},
    {"data": "+33612345678", "type": "phone"},
    {"data": "123-45-6789", "type": "ssn"}
])

# Check for errors
if result["summary"]["failed"] > 0:
    print(f"Errors: {result.get('errors', [])}")

# Use the tokens
for token_result in result["tokens"]:
    print(f"Token: {token_result['token']}")
```

### Format Tokenization

```python
# Tokenize JSON data
json_data = json.dumps({
    "users": [
        {"email": "john@example.com", "phone": "+33612345678"}
    ]
})

result = client.tokenize_format(data=json_data, format="json")

# Store tokenized JSON
# db.save(result["tokenizedData"])

# Later, detokenize
recovered = client.detokenize_format(
    tokenized_data=result["tokenizedData"],
    format="json",
    tokens=[{"path": t["path"], "token": t["token"]} for t in result["tokens"]]
)
```

## Error Handling

```python
from veilio_sdk import (
    VeilioClient,
    VeilioError,
    AuthenticationError,
    RateLimitError,
    TokenShreddedError,
)

try:
    result = client.tokenize(data="test")
except AuthenticationError as e:
    print(f"Auth error: {e.message}")
except RateLimitError as e:
    print(f"Rate limit: {e.message}, retry after {e.retry_after}s")
except TokenShreddedError as e:
    print(f"Token shredded: {e.message}")
except VeilioError as e:
    print(f"API error: {e.code} - {e.message}")
```

## Error Codes

- `AUTH_ERROR` - Invalid or missing API key
- `VALIDATION_ERROR` - Invalid request data
- `RATE_LIMIT_ERROR` - Rate limit exceeded
- `PLAN_LIMIT` - Plan limit exceeded
- `TOKEN_SHREDDED` - Token has been cryptographically shredded
- `INTERNAL_ERROR` - Server error

## Requirements

- Python 3.8+
- `requests` library

## License

MIT

## Support

- Documentation: https://docs.veilio.xyz
- Support: support@veilio.xyz
