Metadata-Version: 2.4
Name: sinkron
Version: 1.0.2
Summary: Python client library for Sinkron - Give your agent permanent email addresses through Clawhub
Author-email: Web3 Hungry <rakawidhiantoro@gmail.com>
Maintainer-email: Web3 Hungry <rakawidhiantoro@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Sinkron
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://www.sinkron.id
Project-URL: Repository, https://github.com/zororaka00/sinkron
Project-URL: Issues, https://github.com/zororaka00/sinkron/issues
Project-URL: Documentation, https://docs.sinkron.id
Keywords: email,inbox,api,ai,agent,permanent-email,clawhub,sinkron
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3.0.0,>=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: bandit>=1.7.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: types-requests>=2.28.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: requests-mock>=1.10.0; extra == "test"
Dynamic: license-file

# Sinkron Python Library

Python library and CLI for Sinkron API - Give your agent permanent email addresses through Clawhub.

## Features

- **Full API Support**: Access all Sinkron API endpoints
- **CLI Interface**: Easy-to-use command line tool
- **Configuration Management**: Save tokens and API URLs
- **Input Validation**: Robust validation for all inputs
- **Error Handling**: Detailed error messages
- **Modular Design**: Use as a library or CLI

## Installation

### From source

```bash
cd library
pip install -e .
```

### From PyPI (when published)

```bash
pip install sinkron
```

## Quick Start

### Using CLI

```bash
# Register a new agent
sinkron register --username john --name "John Doe" --save-token

# Check your inbox
sinkron inbox

# Check a specific page
sinkron inbox --page 2

# Search messages
sinkron inbox --search "verification"

# Get a specific message
sinkron message 123

# Check if email exists
sinkron check john@sinkron.id

# Delete messages
sinkron delete-messages --ids 1,2,3

# Delete entire inbox
sinkron delete-inbox

# Get agent info
sinkron agent john

# Config management
sinkron config --show
sinkron config --token YOUR_TOKEN
sinkron config --api-url https://api.sinkron.id
```

### Using as Library

```python
from sinkron import SinkronClient

# Initialize client
client = SinkronClient()

# Register new agent
result = client.register("john", "John Doe")
print(f"Token: {result.token}")

# Set token for authenticated requests
client.token = result.token

# Get inbox
inbox = client.get_inbox(page=1)
print(f"Total messages: {inbox.total}")

# Get specific message
message = client.get_message(123)
print(f"Subject: {message.subject}")

# Check email exists
check = client.check_email("john@sinkron.id")
print(f"Exists: {check.exists}")
```

## Configuration

### Environment Variables

- `SINKRON_API_URL` - API base URL (default: https://api.sinkron.id)
- `SINKRON_TOKEN` - Authentication token

### Config File

The CLI stores configuration in `~/.sinkron.json`:

```json
{
  "api_url": "https://api.sinkron.id",
  "token": "your_token_here"
}
```

### CLI Options

All CLI commands accept these global options:

- `--api-url URL` - Override API URL
- `--token TOKEN` - Override authentication token
- `--version` - Show version

## Local Development

For local development, you can use the Cloudflare Workers local server:

```bash
# Start local development server
cd /home/zororaka/Project/sinkron/be
wrangler dev
```

Then use the local URL in your commands:

```bash
# Register using local server
sinkron register --username john --name "John Doe" --save-token --api-url http://localhost:8787

# Or save the local URL to config
sinkron config --api-url http://localhost:8787
sinkron register --username john --name "John Doe" --save-token
```

### Setting Custom Domain

If you have a custom domain configured:

```bash
sinkron config --api-url https://your-custom-domain.com
```

## API Reference

### Client Methods

| Method | Description | Auth Required |
|--------|-------------|--------------|
| `health_check()` | Check API health | No |
| `register(username, name)` | Register new agent | No |
| `get_agent_info(username)` | Get agent info | Yes |
| `get_inbox(page, search)` | Get inbox messages | Yes |
| `delete_inbox()` | Delete entire inbox | Yes |
| `get_message(id)` | Get message by ID | Yes |
| `delete_messages(ids)` | Delete messages | Yes |
| `check_email(address)` | Check email exists | No |

## CLI Commands

```
sinkron health                              # Check API health
sinkron register --username USER --name NAME # Register new agent
sinkron inbox [--page N] [--search KEYWORD] # Get inbox
sinkron check ADDRESS                       # Check email exists
sinkron message ID                          # Get message
sinkron delete-messages --ids 1,2,3         # Delete messages
sinkron delete-inbox [--force]              # Delete inbox
sinkron agent USERNAME                      # Get agent info
sinkron config --show                       # Show config
sinkron config --token TOKEN                # Set token
sinkron config --clear-token                # Clear token
```

## Error Handling

```python
from sinkron import SinkronClient
from sinkron.exceptions import (
    SinkronError,
    SinkronAuthError,
    SinkronNotFoundError,
    SinkronRateLimitError,
    SinkronValidationError,
)

client = SinkronClient()

try:
    result = client.register("john", "John Doe")
except SinkronValidationError as e:
    print(f"Validation error: {e}")
except SinkronAuthError as e:
    print(f"Auth error: {e}")
except SinkronRateLimitError as e:
    print(f"Rate limited: {e}")
except SinkronError as e:
    print(f"API error: {e}")
```

## Development

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black sinkron/

# Lint
flake8 sinkron/
```

## License

MIT License - see LICENSE file for details.

## Links

- Website: https://sinkron.id
- API Documentation: https://docs.sinkron.id
