Metadata-Version: 2.4
Name: vegabot-py-sdk
Version: 0.2.0
Summary: Official Python SDK for the Vega API (Discord giveaways).
Project-URL: Homepage, https://vegabot.xyz
Project-URL: Documentation, https://docs.vegabot.xyz/sdks/python
License: MIT
License-File: LICENSE
Keywords: api,discord,giveaways,sdk,vega
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Description-Content-Type: text/markdown

# vegabot-py-sdk (Python)

Official Python SDK for the [Vega API](https://vegabot.xyz) — Discord giveaways, required-server management, and
the membership gate. Included with a Vega whitelabel license.

```bash
pip install vegabot-py-sdk
```

Python 3.9+.

## Quick start

```python
import os
from vega import VegaClient

vega = VegaClient(api_key=os.environ["VEGA_API_KEY"])

me = vega.me()                 # {"guildId": ..., "license": {...}}
active = vega.list_giveaways()
```

Get your key from the dashboard: **Whitelabel → API → Generate key** (license owner only). A key is scoped to one
Discord server. Keep it server-side. Use the client as a context manager to auto-close:

```python
with VegaClient(api_key=...) as vega:
    vega.list_giveaways()
```

## Giveaways

```python
res = vega.create_giveaway(
    prize="Nitro",
    channel_id="123456789012345678",
    duration_seconds=86_400,
    winners=1,
    description="Good luck!",
    requirements=[{"requiredGuildId": "987654321098765432"}],
)

active = vega.list_giveaways()
one = vega.get_giveaway(res["giveawayId"])     # {"giveaway":..., "entryCount":..., "winnerIds":[...]}
vega.end_giveaway(res["giveawayId"])
vega.reroll_giveaway(res["giveawayId"], winners=2)
```

## Required servers

```python
vega.register_server(required_guild_id="987...", name="Main Server", invite_url="https://discord.gg/abc")
servers = vega.list_servers()
vega.delete_server("987...")
```

## Membership gate

```python
result = vega.check_membership(user_id="111...", required_guild_id="987...")
print(result["inServer"], result["hasRole"])
```

## Settings

```python
settings = vega.get_settings()
```

## Reacting to giveaway events

Two options: poll (no public URL) or receive webhooks.

### Option A — polling (no public URL needed)

`listen` polls the event feed and calls your handler for each event, in order. It blocks, so run it in a thread.

```python
import threading

def handle(event):
    if event["event"] == "giveaway.ended":
        print("winners", event["data"]["winnerIds"])

stop = threading.Event()
threading.Thread(target=vega.listen, args=(handle,), kwargs={"stop": stop}, daemon=True).start()
# ... later: stop.set()
```

By default only events after `listen` starts are delivered; pass `after=0` to replay everything still in the feed.
You can also poll manually with `vega.list_events(after, limit)` and track the last `id`.

### Option B — webhooks

Set a delivery URL (dashboard **API → Webhooks**, or `vega.set_webhook(url)`). Vega POSTs signed events to it.
Verify the `X-Vega-Signature` header. `construct_event` verifies and parses in one call:

```python
from vega import construct_event, VegaSignatureError

# Flask, needs the RAW body
@app.post("/vega/webhook")
def webhook():
    try:
        event = construct_event(request.get_data(), request.headers.get("X-Vega-Signature"), SECRET)
    except VegaSignatureError:
        return "", 401
    if event["event"] == "giveaway.ended":
        print(event["data"]["winnerIds"])
    return "", 200
```

Prefer verifying yourself? Use `verify_webhook(raw_body: bytes, header, secret) -> bool`.

More examples (Flask, FastAPI, polling) are in the [docs](https://docs.vegabot.xyz/sdks/python).

## Errors

Failed calls raise `VegaApiError` with `.status`, `.code`, and `.detail`.

```python
from vega import VegaApiError
try:
    vega.get_giveaway(999999)
except VegaApiError as e:
    if e.status == 404:
        print("not found")
```

## License

MIT
