Metadata-Version: 2.4
Name: eyeriss-plugin-sdk
Version: 0.1.2
Summary: Official Python SDK for building plugins for the Eyeriss API Gateway. Provides the base class, hook types, and data structures for Python and WASM plugin development.
Author-email: Eyeriss <dev@eyeriss.io>
License: MIT
Project-URL: Homepage, https://eyeriss.io
Project-URL: Documentation, https://eyeriss.io/docs/plugin-development/
Project-URL: Repository, https://eyeriss.io/marketplace/
Project-URL: Quick Start, https://eyeriss.io/docs/plugin-quickstart/
Project-URL: Changelog, https://eyeriss.io/docs/plugins-overview/
Keywords: eyeriss,api-gateway,plugin,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: System :: Networking
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Eyeriss Plugin SDK

Official Python SDK for building plugins for the [Eyeriss API Gateway](https://eyeriss.io).

## Installation

```bash
pip install eyeriss-plugin-sdk
```

## Quick Start

Create a plugin directory with `manifest.json`, `plugin.py`, and `eyeriss.sig`:

```python
from eyeriss_plugin_sdk import EyerissPlugin
from eyeriss_plugin_sdk.types import PluginContext, PluginResult

class Plugin(EyerissPlugin):
    @property
    def plugin_id(self) -> str:
        return "my-plugin"  # Must match manifest.json id

    async def pre_request(self, context: PluginContext) -> PluginResult:
        return PluginResult(
            proceed=True,
            modified_headers={"X-Custom-Header": "value"},
        )
```

Or use the built-in scaffold:

```bash
docker compose exec django python manage.py plugin new my-plugin --type python
```

## Hooks

| Hook | When | Can Block? | Can Modify? |
|------|------|------------|-------------|
| `pre_request` | After auth, before proxying | Yes (`proceed=False`) | Headers, body |
| `post_response` | After backend response | No | Headers, body |
| `on_error` | On gateway error | No | Nothing (observational) |

## Lifecycle

| Method | Purpose |
|--------|---------|
| `initialize()` | One-time setup at gateway startup |
| `configure(config)` | Apply config from admin UI |
| `cleanup()` | Teardown on shutdown or removal |

## Blocking a Request

```python
from eyeriss_plugin_sdk.types import PluginResult, ErrorResponse

async def pre_request(self, context: PluginContext) -> PluginResult:
    if should_block(context):
        return PluginResult(
            proceed=False,
            error_response=ErrorResponse(
                status_code=403,
                body={"error": "Request denied"},
            ),
        )
    return PluginResult(proceed=True)
```

## Configuration

Define `config_schema` in your `manifest.json` to expose settings in the Management UI.
Supported field types: `text`, `number`, `boolean`, `select`, `textarea`, `file`.

See the [Config Schema Reference](https://eyeriss.io/docs/plugin-config-schema/) for details.

## Documentation

- [Quick Start](https://eyeriss.io/docs/plugin-quickstart/) — build your first plugin in 5 minutes
- [Development Guide](https://eyeriss.io/docs/plugin-development/) — full Python plugin reference
- [Config Schema](https://eyeriss.io/docs/plugin-config-schema/) — config field types and options
- [Testing Guide](https://eyeriss.io/docs/plugin-testing/) — test your plugins with pytest
- [Marketplace](https://eyeriss.io/marketplace/) — browse plugins and templates

## License

MIT
