Metadata-Version: 2.4
Name: sonicbit
Version: 0.3.1
Summary: An unofficial Python SDK for SonicBit which uses the internal API to interact with the application.
Project-URL: Homepage, https://github.com/viperadnan-git/sonicbit-python-sdk
Project-URL: Repository, https://github.com/viperadnan-git/sonicbit-python-sdk
Author-email: Adnan Ahmad <viperadnan@gmail.com>
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: python,sdk,sonicbit
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: tenacity>=9.1.4
Description-Content-Type: text/markdown

# SonicBit Python SDK

An unofficial Python SDK for SonicBit which uses the internal API to interact with the application.

> [!WARNING]  
> This SDK is provided as-is and is not officially supported by SonicBit. The author is not responsible for any damages or losses caused by the use of this SDK. Use it at your own risk. Please use it responsibly and with the understanding that it may not be fully functional or reliable. Check SonicBit's terms of service for more information.

## Installation

Install the package using pip:

```bash
pip install sonicbit
```

Install bleeding edge version:

```bash
pip install git+https://github.com/viperadnan-git/sonicbit-python-sdk.git
```

## Usage

> [!IMPORTANT]  
> This SDK is still in development and may not be fully functional. Please report any issues or bugs you encounter.
> The below documentation is generated by AI and is subject to change as the SDK evolves.

To use the SDK, you need to create an instance of the `SonicBit` class and provide your email and password:

```python
from sonicbit import SonicBit

sb = SonicBit(email='your_email@example.com', password='your_password')
```

Once you have an instance of `SonicBit`, you can use its various methods to interact with the application. For example, to list the files in your storage:

```python
files = sb.list_files()
print(files)
```

### Token Handling

By default, the SDK will store your authentication token in a file named `.sonicbit.cache` in the current working directory. If you want to specify a different location for the token file, you can pass a `token_handler` argument to the `SonicBit` constructor:

```python
sb = SonicBit(email='your_email@example.com', password='your_password', token_handler=MyTokenHandler())
```

The `token_handler` should implement the following methods:

-   `read(email: str) -> str | None`: Reads the token for the given email from the token file.
-   `write(email: str, token: str) -> None`: Writes the token for the given email to the token file.

The `token_handler` is optional and will default to a `TokenFileHandler` if not provided.

> [!TIP]  
> You can use the `TokenHandler` class to store and update tokens in a database or other storage mechanism. Simply implement the `read` and `write` methods and pass an instance of your custom class to the `SonicBit` constructor. This will allow you to store tokens in a secure location and easily update them as needed.

### User Module

The `User` module provides methods for interacting with the user's account, such as getting their user details and storage details.

#### User Details

To get the user's details, you can use the `get_user_details` method:

```python
details = sb.get_user_details()
print(details)
```

This will print a `UserDetails` object containing information about the user's account, such as their email, plan name, and more.

#### Storage Details

To get the storage details, you can use the `get_storage_details` method:

```python
details = sb.get_storage_details()
print(details)
```

This will print a `StorageDetails` object containing information about the user's storage, such as their total storage size, free space, and more.

#### Clear Storage

To clear the user's storage, you can use the `clear_storage` method:

```python
success = sb.clear_storage()
print(success)
```

This will return `True` if the storage was successfully cleared, or `False` if there was an error.

### Torrent Management

The `Torrent` module provides methods for interacting with the user's torrents, such as adding, listing, and deleting torrents.

#### Add Torrent

To add a torrent, you can use the `add_torrent` method:

```python
torrents = sb.add_torrent("https://example.com/torrent.torrent")
print(torrents)
```

This will return a list of torrent hashes that were added.

#### List Torrents

To list the user's torrents, you can use the `list_torrents` method:

```python
torrents = sb.list_torrents()
print(torrents)
```

This will print a `TorrentList` object containing information about each torrent in the user's storage, such as the torrent name, hash, size, progress, and more.

#### Get Torrent Details

To get the details of a torrent, you can use the `get_torrent_details` method:

```python
details = sb.get_torrent_details("hash")
print(details)
```

This will print a `TorrentDetails` object containing information about the torrent, such as the files it contains, the download rate, and more.

#### Delete Torrent

To delete a torrent, you can use the `delete_torrent` method:

```python
success = sb.delete_torrent("hash")
print(success)
```

This will return `True` if the torrent was successfully deleted, or `False` if there was an error.

### Remote Download Management

The `RemoteDownload` module provides methods for interacting with the user's remote downloads, such as adding, listing, and deleting remote downloads.

#### Add Remote Download

To add a remote download, you can use the `add_remote_download` method:

```python
success = sb.add_remote_download("https://example.com/file.torrent", PathInfo.root())
print(success)
```

This will return `True` if the remote download was successfully added, or `False` if there was an error.

#### List Remote Downloads

To list the user's remote downloads, you can use the `list_remote_downloads` method:

```python
downloads = sb.list_remote_downloads()
print(downloads)
```

This will print a `RemoteTaskList` object containing information about each remote download in the user's storage, such as the download URL, progress, and more.

#### Delete Remote Download

To delete a remote download, you can use the `delete_remote_download` method:

```python
success = sb.delete_remote_download(id)
print(success)
```

This will return `True` if the remote download was successfully deleted, or `False` if there was an error.

### File Management

The `File` module provides methods for interacting with the user's files, such as listing, deleting, and moving files.

#### List Files

To list the user's files, you can use the `list_files` method:

```python
files = sb.list_files()
print(files)
```

This will print a `FileList` object containing information about each file in the user's storage, such as the file name, size, and more.

#### Delete File

To delete a file, you can use the `delete_file` method:

```python
success = sb.delete_file("path/to/file")
print(success)
```

This will return `True` if the file was successfully deleted, or `False` if there was an error.

### Sign Up

The `Signup` module provides methods for signing up to SonicBit.

#### Sign Up

To sign up to SonicBit, you can use the `signup` method:

```python
def otp_callback(email):
    return input(f"Enter OTP for {email}: ")

success = SonicBit.signup("John Doe", "email@example.com", "password", otp_callback)
print(success)
```

This will return `True` if the signup was successful, or `False` if there was an error.

> [!NOTE]  
> If `otp_callback` is provided the `signup` method will automatically complete the signup process by submitting the OTP code and skipping tutorial. If `otp_callback` is not provided, the user will need to manually complete the signup process by submitting the OTP code and skipping tutorial. Once signup is complete, the user can use the `submit_otp` method to submit the OTP code.

#### Submit OTP

To submit the OTP code, you can use the `submit_otp` method:

```python
success = SonicBit.submit_otp("123456")
print(success)
```

This will return `True` if the OTP code was successfully submitted, or `False` if there was an error.

#### Complete Signup Tutorial (Optional)

To complete the signup tutorial, you can use the `_complete_tutorial` method:

```python
SonicBit._complete_tutorial("token")
```

This will mark the tutorial as completed and allow the user to access their account.

## Contributing

Contributions are welcome! If you find a bug or have a suggestion for a new feature, please open an issue or submit a pull request on the GitHub repository.

## License

This project is licensed under the GNU General Public License v3.0. See the [LICENSE](LICENSE) file for more details.
