Metadata-Version: 2.4
Name: horizondesk_sdk
Version: 1.3.0
Summary: SDK and CLI for building Horizon Desk AI Plugins
Author: Rapnss Team
Author-email: Rapnss Team <admin@rapnss.in>
License: MIT
Project-URL: Homepage, https://github.com/rapnss/horizondesk-sdk
Project-URL: Issues, https://github.com/rapnss/horizondesk-sdk/issues
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: requests
Requires-Dist: pywebview
Requires-Dist: colorama
Requires-Dist: python-dotenv
Requires-Dist: psutil
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# Horizon Desk SDK v1.3.0 🚀

The official Python SDK for building, testing, and publishing plugins for **Horizon Desk**.

## What's New in v1.3.0
- **Externally Hosted Plugins**: Support for plugins hosted on custom local ports (e.g., Flask, Django backends) using the `hosted_url` manifest field.
- **Package Renaming**: The SDK is now officially `horizondesk_sdk`.
- **Strict Navigation Policy**: Built-in support for the new Horizon Desk security model which forces external links to the system browser.

## Installation

```bash
pip install horizondesk_sdk
```

## Quick Start

1. **Initialize**:
   ```bash
   horizondesk_sdk init MyPlugin
   ```

2. **Develop**:
   Edit `main.py` and add your tools. Use `HorizonPlugin` to register them.

3. **Link UI**:
   Set `custom_ui=True` and provide a `custom_ui_path` (for static HTML) or `hosted_url` (for Flask/Django).

---

## CLI Command Reference

Execute commands using `horizondesk_sdk <command>`.

| Command | Arguments | Description |
| :--- | :--- | :--- |
| `init` | `<name>` | Scaffolds a new plugin directory with a template. |
| `run` | `<file.raf>` | Launches the **Workshop GUI** to visually debug your plugin. |
| `test` | `[--prompt]` | Runs a rapid CLI test using a MockAgent. |
| `install` | — | Installs the current plugin into the local Horizon Desk app. |
| `login` | — | Authenticates your workstation with the Rapnss Store. |
| `logout` | — | Clears local authentication credentials. |
| `whoami` | — | Displays current developer profile and ad balance. |
| `publish` | — | Packages and uploads your plugin to the Horizon Store. |
| `status` | — | Lists your published plugins and their approval status. |

---

## Manifest Reference (`horizon_plugin.raf`)

The `.raf` file is a JSON manifest that defines your plugin's identity and capabilities.

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `name` | `string` | Yes | The unique name of your plugin (PascalCase preferred). |
| `version` | `string` | Yes | Semantic version (e.g., `"1.3.0"`). |
| `developer` | `string` | Yes | Your developer name or handle. |
| `description`| `string` | Yes | A short summary of what the plugin does. |
| `entry_point`| `string` | Yes | The main Python file (usually `"main.py"`). |
| `category` | `string` | No | `general`, `utilities`, `productivity`, `creative`, `system`. |
| `custom_ui` | `boolean` | No | Set to `true` to enable a sidebar tab. |
| `custom_ui_path`| `string` | No | Relative path to the folder containing `index.html`. |
| `hosted_url` | `string` | No | **(New in v1.3.0)** Local URL for Flask/Django UIs (e.g. `http://localhost:5000`). |
| `icon` | `string` | No | Relative path to a 128x128 PNG sidebar icon. |

---

## Security & Best Practices

- **SecretStorage**: Never hardcode API keys. Use `SecretStorage.get_secret("MY_KEY")`.
- **PII Redaction**: Use `SecretStorage.redact_pii(text)` to sanitize data before sending to external LLMs.
- **Timeouts**: Always use `timeout=` in network requests (e.g., `requests.get(url, timeout=10)`).

## Support
- **Issues**: [GitHub Issues](https://github.com/rapnss/horizondesk-sdk/issues)
- **Developer Portal**: [horizon.rapnss.in/dev](https://horizon.rapnss.in/dev)
