planelet-sdk 0.1.0__py3-none-any.whl

planelet_sdk/__init__.py

@@ -0,0 +1,52 @@
+from .planelet import Planelet
+from .types import (
+    ActionContext,
+    CleanupContext,
+    HttpResponse,
+    Param,
+    ParamOption,
+    SetupContext,
+    WebhookContext,
+    WebhookError,
+    WebhookInfo,
+    WebhookRequest,
+    WebhookResult,
+    WebhookSkip,
+)
+from .trigger import TriggerBuilder
+
+
+def create_planelet(
+    *,
+    id: str,
+    label: str,
+    icon: str | None = None,
+    icon_url: str | None = None,
+    description: str | None = None,
+) -> Planelet:
+    return Planelet(
+        id=id,
+        label=label,
+        icon=icon,
+        icon_url=icon_url,
+        description=description,
+    )
+
+
+__all__ = [
+    "create_planelet",
+    "ActionContext",
+    "CleanupContext",
+    "HttpResponse",
+    "Param",
+    "ParamOption",
+    "Planelet",
+    "SetupContext",
+    "TriggerBuilder",
+    "WebhookContext",
+    "WebhookError",
+    "WebhookInfo",
+    "WebhookRequest",
+    "WebhookResult",
+    "WebhookSkip",
+]

planelet_sdk/planelet.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Awaitable
+
+from .trigger import TriggerBuilder
+from .types import ActionContext, Param
+
+
+ActionHandler = Callable[[ActionContext], Awaitable[dict[str, Any]]]
+
+
+class _ActionDef:
+    def __init__(
+        self,
+        id: str,
+        *,
+        label: str,
+        description: str | None,
+        icon: str | None,
+        icon_url: str | None,
+        parameters: dict[str, Param],
+        handler: ActionHandler,
+    ) -> None:
+        self.id = id
+        self.label = label
+        self.description = description
+        self.icon = icon
+        self.icon_url = icon_url
+        self.parameters = parameters
+        self.handler = handler
+
+
+class Planelet:
+    def __init__(
+        self,
+        *,
+        id: str,
+        label: str,
+        icon: str | None = None,
+        icon_url: str | None = None,
+        description: str | None = None,
+    ) -> None:
+        self.id = id
+        self.label = label
+        self.icon = icon
+        self.icon_url = icon_url
+        self.description = description
+
+        self._actions: dict[str, _ActionDef] = {}
+        self._triggers: dict[str, TriggerBuilder] = {}
+
+    def action(
+        self,
+        id: str,
+        *,
+        label: str,
+        description: str | None = None,
+        icon: str | None = None,
+        icon_url: str | None = None,
+        parameters: dict[str, Param] | None = None,
+    ) -> Callable[[ActionHandler], ActionHandler]:
+        params = parameters or {}
+
+        def decorator(fn: ActionHandler) -> ActionHandler:
+            self._actions[id] = _ActionDef(
+                id=id,
+                label=label,
+                description=description,
+                icon=icon,
+                icon_url=icon_url,
+                parameters=params,
+                handler=fn,
+            )
+            return fn
+
+        return decorator
+
+    def trigger(
+        self,
+        id: str,
+        *,
+        label: str,
+        description: str | None = None,
+        icon: str | None = None,
+        icon_url: str | None = None,
+        parameters: dict[str, Param] | None = None,
+    ) -> TriggerBuilder:
+        builder = TriggerBuilder(
+            id,
+            label=label,
+            description=description,
+            icon=icon,
+            icon_url=icon_url,
+            parameters=parameters,
+        )
+        self._triggers[id] = builder
+        return builder
+
+    def listen(self, port: int = 3000) -> None:
+        from .server import build_app
+
+        import uvicorn
+
+        app = build_app(self)
+        uvicorn.run(app, host="0.0.0.0", port=port)

planelet_sdk/server.py

@@ -0,0 +1,268 @@
+from __future__ import annotations
+
+import base64
+from typing import Any, TYPE_CHECKING
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from .types import (
+    ActionContext,
+    CleanupContext,
+    HttpResponse,
+    SetupContext,
+    WebhookContext,
+    WebhookError,
+    WebhookInfo,
+    WebhookRequest,
+    WebhookResult,
+    WebhookSkip,
+)
+
+if TYPE_CHECKING:
+    from .planelet import Planelet
+
+
+def _serialize_params(parameters: dict[str, Any]) -> list[dict[str, Any]]:
+    result = []
+    for param_id, param in parameters.items():
+        entry: dict[str, Any] = {
+            "id": param_id,
+            "label": param.label,
+            "type": param.type,
+        }
+        if param.description is not None:
+            entry["description"] = param.description
+        if param.required:
+            entry["required"] = True
+        if param.default is not None:
+            entry["default"] = param.default
+        if param.options is not None:
+            entry["options"] = [
+                {"label": o.label, "value": o.value} for o in param.options
+            ]
+        result.append(entry)
+    return result
+
+
+def _serialize_http_response(resp: HttpResponse | None) -> dict[str, Any] | None:
+    if resp is None:
+        return None
+    out: dict[str, Any] = {"status": resp.status}
+    if resp.headers:
+        out["headers"] = resp.headers
+    if resp.body is not None:
+        out["body"] = resp.body
+    return out
+
+
+def build_app(planelet: Planelet) -> FastAPI:
+    app = FastAPI(title=planelet.label)
+
+    @app.get("/manifest")
+    async def manifest() -> dict[str, Any]:
+        actions = []
+        for action_def in planelet._actions.values():
+            entry: dict[str, Any] = {
+                "id": action_def.id,
+                "label": action_def.label,
+                "parameters": _serialize_params(action_def.parameters),
+            }
+            if action_def.description:
+                entry["description"] = action_def.description
+            if action_def.icon:
+                entry["icon"] = action_def.icon
+            if action_def.icon_url:
+                entry["iconUrl"] = action_def.icon_url
+            actions.append(entry)
+
+        triggers = []
+        for trigger in planelet._triggers.values():
+            entry = {
+                "id": trigger.id,
+                "label": trigger.label,
+                "parameters": _serialize_params(trigger.parameters),
+                "webhook": {"setup": "plugin"},
+            }
+            if trigger.description:
+                entry["description"] = trigger.description
+            if trigger.icon:
+                entry["icon"] = trigger.icon
+            if trigger.icon_url:
+                entry["iconUrl"] = trigger.icon_url
+            triggers.append(entry)
+
+        result: dict[str, Any] = {
+            "id": planelet.id,
+            "label": planelet.label,
+            "actions": actions,
+            "triggers": triggers,
+        }
+        if planelet.icon:
+            result["icon"] = planelet.icon
+        if planelet.icon_url:
+            result["iconUrl"] = planelet.icon_url
+        if planelet.description:
+            result["description"] = planelet.description
+        return result
+
+    @app.post("/actions/{action_id}/execute")
+    async def execute_action(action_id: str, request: Request) -> JSONResponse:
+        action_def = planelet._actions.get(action_id)
+        if not action_def:
+            return JSONResponse(
+                {"success": False, "error": f'Action "{action_id}" not found'},
+                status_code=404,
+            )
+
+        body = await request.json()
+        ctx = ActionContext(
+            parameters=body.get("parameters", {}),
+            input=body.get("input"),
+        )
+
+        try:
+            data = await action_def.handler(ctx)
+            return JSONResponse({"success": True, "data": data})
+        except Exception as exc:
+            return JSONResponse(
+                {"success": False, "error": str(exc)},
+                status_code=500,
+            )
+
+    @app.post("/triggers/{trigger_id}/setup")
+    async def setup_trigger(trigger_id: str, request: Request) -> JSONResponse:
+        trigger = planelet._triggers.get(trigger_id)
+        if not trigger:
+            return JSONResponse(
+                {"success": False, "error": f'Trigger "{trigger_id}" not found'},
+                status_code=404,
+            )
+        if not trigger._setup:
+            return JSONResponse(
+                {"success": False, "error": f'Trigger "{trigger_id}" has no setup handler'},
+                status_code=501,
+            )
+
+        body = await request.json()
+        webhook_data = body.get("webhook", {})
+        ctx = SetupContext(
+            parameters=body.get("parameters", {}),
+            webhook=WebhookInfo(
+                url=webhook_data.get("url", ""),
+                secret=webhook_data.get("secret"),
+            ),
+        )
+
+        try:
+            metadata = await trigger._setup(ctx)
+            result: dict[str, Any] = {"success": True}
+            if metadata:
+                result["metadata"] = metadata
+            return JSONResponse(result)
+        except Exception as exc:
+            return JSONResponse(
+                {"success": False, "error": str(exc)},
+                status_code=500,
+            )
+
+    @app.post("/triggers/{trigger_id}/cleanup")
+    async def cleanup_trigger(trigger_id: str, request: Request) -> JSONResponse:
+        trigger = planelet._triggers.get(trigger_id)
+        if not trigger:
+            return JSONResponse(
+                {"success": False, "error": f'Trigger "{trigger_id}" not found'},
+                status_code=404,
+            )
+        if not trigger._cleanup:
+            return JSONResponse(
+                {"success": False, "error": f'Trigger "{trigger_id}" has no cleanup handler'},
+                status_code=501,
+            )
+
+        body = await request.json()
+        ctx = CleanupContext(
+            parameters=body.get("parameters", {}),
+            metadata=body.get("metadata"),
+        )
+
+        try:
+            await trigger._cleanup(ctx)
+            return JSONResponse({"success": True})
+        except Exception as exc:
+            return JSONResponse(
+                {"success": False, "error": str(exc)},
+                status_code=500,
+            )
+
+    @app.post("/triggers/{trigger_id}/webhook")
+    async def handle_webhook(trigger_id: str, request: Request) -> JSONResponse:
+        trigger = planelet._triggers.get(trigger_id)
+        if not trigger:
+            return JSONResponse(
+                {"success": False, "error": f'Trigger "{trigger_id}" not found'},
+                status_code=404,
+            )
+        if not trigger._webhook:
+            return JSONResponse(
+                {"success": False, "error": f'Trigger "{trigger_id}" has no webhook handler'},
+                status_code=501,
+            )
+
+        body = await request.json()
+        req_data = body.get("request", {})
+        raw_body_b64 = req_data.get("rawBodyBase64", "")
+        raw_body = base64.b64decode(raw_body_b64) if raw_body_b64 else b""
+
+        ctx = WebhookContext(
+            parameters=body.get("parameters", {}),
+            metadata=body.get("metadata"),
+            request=WebhookRequest(
+                method=req_data.get("method", "POST"),
+                headers=req_data.get("headers", {}),
+                query=req_data.get("query"),
+                raw_body=raw_body,
+            ),
+        )
+
+        try:
+            result = await trigger._webhook(ctx)
+        except Exception as exc:
+            return JSONResponse(
+                {"success": False, "error": str(exc)},
+                status_code=500,
+            )
+
+        if isinstance(result, WebhookResult):
+            resp: dict[str, Any] = {
+                "success": True,
+                "emit": True,
+                "eventType": result.event_type,
+                "payload": result.payload,
+            }
+            http_resp = _serialize_http_response(result.response)
+            if http_resp:
+                resp["response"] = http_resp
+            return JSONResponse(resp)
+
+        if isinstance(result, WebhookSkip):
+            resp = {"success": True, "emit": False}
+            if result.reason:
+                resp["reason"] = result.reason
+            http_resp = _serialize_http_response(result.response)
+            if http_resp:
+                resp["response"] = http_resp
+            return JSONResponse(resp)
+
+        if isinstance(result, WebhookError):
+            err_resp: dict[str, Any] = {"success": False, "error": result.error}
+            if result.status is not None:
+                err_resp["status"] = result.status
+            return JSONResponse(err_resp, status_code=result.status or 500)
+
+        return JSONResponse(
+            {"success": False, "error": "Webhook handler returned invalid type"},
+            status_code=500,
+        )
+
+    return app

planelet_sdk/trigger.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Awaitable
+
+from .types import (
+    CleanupContext,
+    Param,
+    SetupContext,
+    WebhookContext,
+    WebhookError,
+    WebhookResult,
+    WebhookSkip,
+)
+
+SetupHandler = Callable[[SetupContext], Awaitable[dict[str, Any] | None]]
+CleanupHandler = Callable[[CleanupContext], Awaitable[None]]
+WebhookHandler = Callable[
+    [WebhookContext], Awaitable[WebhookResult | WebhookSkip | WebhookError]
+]
+
+
+class TriggerBuilder:
+    def __init__(
+        self,
+        id: str,
+        *,
+        label: str,
+        description: str | None = None,
+        icon: str | None = None,
+        icon_url: str | None = None,
+        parameters: dict[str, Param] | None = None,
+    ) -> None:
+        self.id = id
+        self.label = label
+        self.description = description
+        self.icon = icon
+        self.icon_url = icon_url
+        self.parameters = parameters or {}
+
+        self._setup: SetupHandler | None = None
+        self._cleanup: CleanupHandler | None = None
+        self._webhook: WebhookHandler | None = None
+
+    def on_setup(self, fn: SetupHandler) -> SetupHandler:
+        self._setup = fn
+        return fn
+
+    def on_cleanup(self, fn: CleanupHandler) -> CleanupHandler:
+        self._cleanup = fn
+        return fn
+
+    def on_webhook(self, fn: WebhookHandler) -> WebhookHandler:
+        self._webhook = fn
+        return fn

planelet_sdk/types.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Param:
+    label: str
+    type: str  # "string" | "text" | "number" | "bool" | "select" | "object"
+    description: str | None = None
+    required: bool = False
+    default: Any = None
+    options: list[ParamOption] | None = None
+
+
+@dataclass
+class ParamOption:
+    label: str
+    value: str
+
+
+# --- Contexts passed to handlers ---
+
+
+@dataclass
+class ActionContext:
+    parameters: dict[str, Any]
+    input: Any | None = None
+
+
+@dataclass
+class WebhookInfo:
+    url: str
+    secret: str | None = None
+
+
+@dataclass
+class SetupContext:
+    parameters: dict[str, Any]
+    webhook: WebhookInfo = field(default_factory=lambda: WebhookInfo(url=""))
+
+
+@dataclass
+class CleanupContext:
+    parameters: dict[str, Any]
+    metadata: dict[str, Any] | None = None
+
+
+@dataclass
+class WebhookRequest:
+    method: str
+    headers: dict[str, list[str]]
+    query: dict[str, list[str]] | None = None
+    raw_body: bytes = b""
+
+
+@dataclass
+class WebhookContext:
+    parameters: dict[str, Any]
+    metadata: dict[str, Any] | None = None
+    request: WebhookRequest = field(
+        default_factory=lambda: WebhookRequest(method="POST", headers={})
+    )
+
+
+# --- Result types returned by handlers ---
+
+
+@dataclass
+class HttpResponse:
+    status: int = 200
+    headers: dict[str, str] | None = None
+    body: str | None = None
+
+
+@dataclass
+class WebhookResult:
+    event_type: str
+    payload: Any = None
+    response: HttpResponse | None = None
+
+
+@dataclass
+class WebhookSkip:
+    reason: str | None = None
+    response: HttpResponse | None = None
+
+
+@dataclass
+class WebhookError:
+    error: str
+    status: int | None = None

planelet_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.3
+Name: planelet-sdk
+Version: 0.1.0
+Summary: Python SDK for building SuperPlane planelets
+Author: ThatXliner
+Author-email: ThatXliner <thatxliner@gmail.com>
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn[standard]>=0.20.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# SuperPlane Planelet SDK for Python
+
+Build custom SuperPlane integrations in Python. Define actions and webhook triggers with decorators, and the SDK serves the full Planelet protocol over HTTP.
+
+## Quick Start
+
+### 1. Create a new project
+
+```bash
+mkdir my-planelet && cd my-planelet
+python -m venv .venv && source .venv/bin/activate
+pip install superplane-planelet-sdk
+```
+
+### 2. Write your Planelet
+
+```python
+# main.py
+from superplane import create_planelet, Param, ActionContext
+
+planelet = create_planelet(
+    id="my-planelet",
+    label="My Planelet",
+    description="Does useful things",
+)
+
+@planelet.action(
+    "hello",
+    label="Say Hello",
+    description="Generates a greeting",
+    parameters={
+        "name": Param(label="Name", type="string", required=True),
+    },
+)
+async def hello(ctx: ActionContext):
+    return {"message": f"Hello, {ctx.parameters['name']}!"}
+
+planelet.listen(3001)
+```
+
+### 3. Run it
+
+```bash
+python main.py
+# Uvicorn running on http://0.0.0.0:3001
+```
+
+### 4. Connect to SuperPlane
+
+1. In SuperPlane, add a new **Planelets** integration
+2. Set **Server URL** to your Planelet server's address
+3. Optionally set an **Auth Token**
+4. Save — SuperPlane fetches your manifest and the integration goes ready
+
+## Documentation
+
+See [PLANELET-DOCS.md](PLANELET-DOCS.md) for the full SDK reference, trigger/webhook guide, and protocol details.
+
+## Example
+
+See [`examples/quotes.py`](examples/quotes.py) for a complete example with two actions. Run it:
+
+```bash
+cd examples
+python quotes.py
+```
+
+Then connect SuperPlane to `http://localhost:3001`.

planelet_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+planelet_sdk/__init__.py,sha256=7wDPuHMmI26-lB_-FYKsnB59JPEtZ2kpEsiynmNeFRk,933
+planelet_sdk/planelet.py,sha256=0CdW6P-DAFLqE4PSiKbcSPG25wrM8rHK-hPox8SbT9c,2631
+planelet_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+planelet_sdk/server.py,sha256=QzDr2vqHYbH-VEaeBG-dW2jG8hFhAqBsrXclFxZfuM8,9019
+planelet_sdk/trigger.py,sha256=BXIrMGh6bQSXsMid0hO21ANgAmIpx1eC_wHfcDgodZQ,1412
+planelet_sdk/types.py,sha256=VWVsiakShC0uBNn09GGthHbOk_nUbVblNI1avoWbq-U,1725
+planelet_sdk-0.1.0.dist-info/WHEEL,sha256=f5fWSvWsg5Knq5GWa6t1nJIug0Tqo69GqAWD_9LbBKw,81
+planelet_sdk-0.1.0.dist-info/METADATA,sha256=OE_QLOAtU8pwhRKe3RbgZ7zPz_SKx8JD8T5Vl6zPJ04,1903
+planelet_sdk-0.1.0.dist-info/RECORD,,

planelet_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.16
+Root-Is-Purelib: true
+Tag: py3-none-any