vwp-sdk 0.5.0a1

VWP Python SDK — primitives for vibe-coded backends (rate limiting, auth, notifications, and more).

vwp-sdk

Python SDK for VWP — primitives for vibe-coded backends.

pip install vwp-sdk

Quickstart

import vwp

client = vwp.Client(api_key="vwp_test_...")  # or set VWP_API_KEY in env

result = client.rate_limit.check(
    key="login:[e-mail]",
    limit=5,
    window="15m",
)
if not result.allowed:
    # Block this request — your handler returns 429 to the end user.
    print(f"Try again in {result.retry_after_seconds}s")

Or, async:

import asyncio
import vwp

async def main():
    async with vwp.AsyncClient(api_key="vwp_test_...") as client:
        result = await client.rate_limit.check(
            key="login:[e-mail]", limit=5, window="15m",
        )
        print(result)

asyncio.run(main())

What's in this release (0.2.0a1)

• vwp.rate_limit.check(...) — SECURITY-RATE-LIMIT-001, fully wired against https://api.vibewithprimitiveai.com/v1.
• vwp.auth.magic_link.request(email, return_to, ...) — issues a single-use magic link via email (Azure Communication Services on our side).
• vwp.auth.magic_link.exchange(request | url | dict, handle?) — turns a clicked link into a signed JWT session. SDK pulls _vwp_h out of the request URL automatically.
• vwp.Client / vwp.AsyncClient — explicit clients for connection reuse.
• Typed errors — ApiKeyError (401), BadRequestError (400), MetaRateLimitedError (429), ServerError (5xx), NetworkError (no response).

Other modules (vwp.notify, vwp.data, vwp.queue) are present as stubs and will be implemented in subsequent releases. Calling them raises NotImplementedError with a pointer to the docs.

Magic-link quickstart

import vwp

client = vwp.Client(api_key="vwp_test_...")

# Step 1 — user types their email
r = client.auth.magic_link.request(
    email="[e-mail]",
    return_to="https://yourapp.com/dashboard",
)
# r.expires_at — when the link expires (default 15 min)
# r.delivery_status — "queued"

# Step 2 — user clicks the link, your callback handler runs:
session = client.auth.magic_link.exchange(request)  # request from your framework
# Or pass the URL/handle directly:
session = client.auth.magic_link.exchange(handle="<_vwp_h value from URL>")

# session.session.user_id, session.session.email — for your user table upsert
# session.jwt — set as a HttpOnly cookie

Errors

Every error subclasses vwp.VWPError. Catch the base class to handle anything:

try:
    result = vwp.rate_limit.check(key="...", limit=5, window="15m")
except vwp.ApiKeyError as e:
    print("Bad API key:", e.request_id)
except vwp.BadRequestError as e:
    print("Bad input:", e.field, e.message)
except vwp.VWPError as e:
    print("Other VWP error:", e)

Compatibility

Python 3.9+. Production-tested on 3.12.

License

Apache-2.0.