Metadata-Version: 2.4
Name: relayway
Version: 0.2.0
Summary: Python SDK for background job processing via Relayway API
Author: Mario Gegprifti
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Requires-Dist: fastapi>=0.100
Dynamic: license-file

# relayway

Python SDK for enqueueing background jobs via the RelayWay API.

## Installation

```bash
pip install .
```

## Configuration

Set environment variables (or use a `.env` file):

```bash
export RELAYWAY_API_KEY="sk_xxx"              # Your RelayWay API key
export RELAYWAY_WEBHOOK_SECRET="whsec_xxx"     # Shared secret for webhook auth
export RELAYWAY_BASE_URL="https://api.relayway.io"  # RelayWay API URL
export RELAYWAY_ORIGIN="https://myapp.com"     # Your app's public URL
```

## Quick start

```python
from fastapi import FastAPI
from relayway import background, relayway_router

app = FastAPI()
app.include_router(relayway_router)

@background(name="send-email")
def send_email(to: str, subject: str) -> dict:
    send_actual_email(to, subject)
    return {"sent": True}

# Call the function — it enqueues instead of executing locally
result = await send_email("alice@example.com", "Welcome!")
print(result)  # {"id": "task-abc", "status": "pending"}
```

## How it works

1. **Registration** — `@background()` registers your function in the SDK's internal registry.
2. **Enqueue** — Calling the function sends the arguments as a task payload to the RelayWay API.
3. **Execution** — The RelayWay worker picks up the task and POSTs to your app at `/relayway/webhook/{name}`. The router verifies the HMAC signature, looks up your function, and calls it with the original arguments.
4. **Response** — The function's return value is sent back to the worker.

## API reference

### `@background(name="my-func")`

Decorator that marks a function for background execution.

- `name` — unique identifier (defaults to `func.__name__`). The worker calls back to `/relayway/webhook/{name}`.

### `relayway_router`

A FastAPI `APIRouter` you mount on your app. Provides the webhook endpoint:

- `POST /relayway/webhook/{name}` — worker callback, HMAC-protected.

## Run tests

```bash
uv run --group dev pytest -q
```
