volga-sdk 1.0.0__tar.gz

volga_sdk-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+build/
+dist/

volga_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: volga-sdk
+Version: 1.0.0
+Summary: Official Python SDK for the Volga Public API (conversations, messages, outbound webhooks).
+Project-URL: Homepage, https://hooks.volga-ai.com/v1/docs
+Project-URL: Source, https://github.com/volga-ai/volga-core-lite
+Author: Volga
+License: MIT
+Keywords: api,instagram,sdk,volga,webhooks,whatsapp
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# volga
+
+Official Python SDK for the [Volga Public API](https://hooks.volga-ai.com/v1/docs) — conversations, messages, and outbound webhooks.
+
+- Zero dependencies (standard library only)
+- Automatic retries (429 + 5xx + network) with `Retry-After` support
+- Cursor auto-pagination via generators
+- Built-in webhook signature verification
+- Python 3.8+
+
+## Install
+
+```bash
+pip install volga-sdk
+```
+
+(The distribution is `volga-sdk`; you still `import volga`.)
+
+## Quickstart
+
+```python
+import os
+from volga import VolgaClient
+
+volga = VolgaClient(api_key=os.environ["VOLGA_API_KEY"])
+
+# List conversations
+page = volga.conversations.list(channel="whatsapp", limit=25)
+
+# Send a reply (idempotent retries)
+import uuid
+volga.messages.send(
+    conversation_id=page["data"][0]["id"],
+    text="Thanks for reaching out!",
+    idempotency_key=str(uuid.uuid4()),
+)
+```
+
+## Pagination
+
+```python
+# One page at a time
+page = volga.messages.list(conversation_id="c_123")
+print(page["data"], page["has_more"], page["next_cursor"])
+
+# Or auto-paginate every item
+for message in volga.messages.iterate(conversation_id="c_123"):
+    print(message["id"], message["text"])
+```
+
+## Webhooks
+
+Register an endpoint (the signing `secret` is returned **once**):
+
+```python
+endpoint = volga.webhook_endpoints.create(
+    url="https://example.com/volga/webhooks",
+    event_types=["message.received", "conversation.created"],
+)
+# store endpoint["secret"] securely
+```
+
+Verify and parse incoming deliveries (pass the **raw** request body):
+
+```python
+from volga import construct_event, VolgaSignatureVerificationError
+
+@app.post("/volga/webhooks")
+def handle(request):
+    try:
+        event = construct_event(
+            secret=os.environ["VOLGA_WEBHOOK_SECRET"],
+            payload=request.get_data(),  # raw bytes, not parsed JSON
+            signature_header=request.headers.get("Volga-Signature"),
+        )
+    except VolgaSignatureVerificationError:
+        return "", 400
+    # handle event["type"] / event["data"] ...
+    return "", 200
+```
+
+Deliveries are **at-least-once** — deduplicate on the event `id` (or the
+`Volga-Delivery-Id` header).
+
+## Errors
+
+```python
+from volga import VolgaRateLimitError, VolgaPermissionError, VolgaApiError
+
+try:
+    volga.messages.send(conversation_id=cid, text=text)
+except VolgaRateLimitError as e:
+    time.sleep(e.retry_after_sec or 1)
+except VolgaPermissionError:
+    ...  # the key is missing a scope
+except VolgaApiError as e:
+    print(e.status, e.code, e.message, e.trace_id)
+```
+
+| Class | Status |
+| --- | --- |
+| `VolgaInvalidRequestError` | 400 / 422 |
+| `VolgaAuthenticationError` | 401 |
+| `VolgaPaymentRequiredError` | 402 |
+| `VolgaPermissionError` | 403 |
+| `VolgaNotFoundError` | 404 |
+| `VolgaConflictError` | 409 |
+| `VolgaRateLimitError` | 429 |
+| `VolgaServerError` | 5xx |
+| `VolgaConnectionError` / `VolgaTimeoutError` | no response |
+
+## Configuration
+
+```python
+VolgaClient(
+    api_key="vk_live_…",
+    base_url="https://hooks.volga-ai.com/v1",  # default
+    timeout=30.0,        # default
+    max_retries=2,       # default
+    retry_base_delay=0.5,
+    retry_max_delay=8.0,
+)
+```
+
+## License
+
+MIT

volga_sdk-1.0.0/README.md

@@ -0,0 +1,127 @@
+# volga
+
+Official Python SDK for the [Volga Public API](https://hooks.volga-ai.com/v1/docs) — conversations, messages, and outbound webhooks.
+
+- Zero dependencies (standard library only)
+- Automatic retries (429 + 5xx + network) with `Retry-After` support
+- Cursor auto-pagination via generators
+- Built-in webhook signature verification
+- Python 3.8+
+
+## Install
+
+```bash
+pip install volga-sdk
+```
+
+(The distribution is `volga-sdk`; you still `import volga`.)
+
+## Quickstart
+
+```python
+import os
+from volga import VolgaClient
+
+volga = VolgaClient(api_key=os.environ["VOLGA_API_KEY"])
+
+# List conversations
+page = volga.conversations.list(channel="whatsapp", limit=25)
+
+# Send a reply (idempotent retries)
+import uuid
+volga.messages.send(
+    conversation_id=page["data"][0]["id"],
+    text="Thanks for reaching out!",
+    idempotency_key=str(uuid.uuid4()),
+)
+```
+
+## Pagination
+
+```python
+# One page at a time
+page = volga.messages.list(conversation_id="c_123")
+print(page["data"], page["has_more"], page["next_cursor"])
+
+# Or auto-paginate every item
+for message in volga.messages.iterate(conversation_id="c_123"):
+    print(message["id"], message["text"])
+```
+
+## Webhooks
+
+Register an endpoint (the signing `secret` is returned **once**):
+
+```python
+endpoint = volga.webhook_endpoints.create(
+    url="https://example.com/volga/webhooks",
+    event_types=["message.received", "conversation.created"],
+)
+# store endpoint["secret"] securely
+```
+
+Verify and parse incoming deliveries (pass the **raw** request body):
+
+```python
+from volga import construct_event, VolgaSignatureVerificationError
+
+@app.post("/volga/webhooks")
+def handle(request):
+    try:
+        event = construct_event(
+            secret=os.environ["VOLGA_WEBHOOK_SECRET"],
+            payload=request.get_data(),  # raw bytes, not parsed JSON
+            signature_header=request.headers.get("Volga-Signature"),
+        )
+    except VolgaSignatureVerificationError:
+        return "", 400
+    # handle event["type"] / event["data"] ...
+    return "", 200
+```
+
+Deliveries are **at-least-once** — deduplicate on the event `id` (or the
+`Volga-Delivery-Id` header).
+
+## Errors
+
+```python
+from volga import VolgaRateLimitError, VolgaPermissionError, VolgaApiError
+
+try:
+    volga.messages.send(conversation_id=cid, text=text)
+except VolgaRateLimitError as e:
+    time.sleep(e.retry_after_sec or 1)
+except VolgaPermissionError:
+    ...  # the key is missing a scope
+except VolgaApiError as e:
+    print(e.status, e.code, e.message, e.trace_id)
+```
+
+| Class | Status |
+| --- | --- |
+| `VolgaInvalidRequestError` | 400 / 422 |
+| `VolgaAuthenticationError` | 401 |
+| `VolgaPaymentRequiredError` | 402 |
+| `VolgaPermissionError` | 403 |
+| `VolgaNotFoundError` | 404 |
+| `VolgaConflictError` | 409 |
+| `VolgaRateLimitError` | 429 |
+| `VolgaServerError` | 5xx |
+| `VolgaConnectionError` / `VolgaTimeoutError` | no response |
+
+## Configuration
+
+```python
+VolgaClient(
+    api_key="vk_live_…",
+    base_url="https://hooks.volga-ai.com/v1",  # default
+    timeout=30.0,        # default
+    max_retries=2,       # default
+    retry_base_delay=0.5,
+    retry_max_delay=8.0,
+)
+```
+
+## License
+
+MIT

volga_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# Distribution name on PyPI (the bare `volga` is taken by an unrelated project).
+# The import name stays `volga` (see [tool.hatch.build.targets.wheel]).
+name = "volga-sdk"
+version = "1.0.0"
+description = "Official Python SDK for the Volga Public API (conversations, messages, outbound webhooks)."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+keywords = ["volga", "whatsapp", "instagram", "webhooks", "api", "sdk"]
+authors = [{ name = "Volga" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://hooks.volga-ai.com/v1/docs"
+Source = "https://github.com/volga-ai/volga-core-lite"
+
+[tool.hatch.build.targets.wheel]
+packages = ["volga"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

volga_sdk-1.0.0/tests/conftest.py

@@ -0,0 +1,61 @@
+import json
+from typing import Any, Dict, List, Optional
+
+import pytest
+
+from volga import VolgaClient
+from volga._http import HttpResponse
+
+
+class FakeHttp:
+    """Replays a queue of canned responses and records every call."""
+
+    def __init__(self, responses: List[Dict[str, Any]]) -> None:
+        self.responses = responses
+        self.calls: List[Dict[str, Any]] = []
+
+    def __call__(self, method, url, headers, body, timeout):  # noqa: ANN001
+        self.calls.append(
+            {"method": method, "url": url, "headers": headers, "body": body}
+        )
+        idx = min(len(self.calls) - 1, len(self.responses) - 1)
+        spec = self.responses[idx] if self.responses else {}
+        if "raise" in spec:
+            raise spec["raise"]
+        status = spec.get("status", 200)
+        raw = spec.get("body")
+        if raw is None:
+            text = ""
+        elif isinstance(raw, str):
+            text = raw
+        else:
+            text = json.dumps(raw)
+        return HttpResponse(status, spec.get("headers", {}), text)
+
+
+def make_client(responses: List[Dict[str, Any]], **overrides):
+    http = FakeHttp(responses)
+    client = VolgaClient(
+        api_key="vk_test_abc",
+        base_url="https://api.test/v1",
+        http=http,
+        retry_base_delay=0,
+        retry_max_delay=0,
+        sleep=lambda _s: None,
+        **overrides,
+    )
+    return client, http
+
+
+@pytest.fixture
+def client_factory():
+    return make_client
+
+
+def page(data: List[Any], next_cursor: Optional[str] = None) -> Dict[str, Any]:
+    return {
+        "object": "list",
+        "data": data,
+        "has_more": next_cursor is not None,
+        "next_cursor": next_cursor,
+    }

volga_sdk-1.0.0/tests/test_client.py

@@ -0,0 +1,113 @@
+import json
+
+import pytest
+
+from volga import VolgaClient
+from tests.conftest import make_client, page
+
+
+def test_requires_api_key():
+    with pytest.raises(Exception) as exc:
+        VolgaClient(api_key="")
+    assert "api key is required" in str(exc.value).lower()
+
+
+def test_sends_bearer_and_accept():
+    client, http = make_client([{"body": page([])}])
+    client.conversations.list()
+    headers = http.calls[0]["headers"]
+    assert headers["Authorization"] == "Bearer vk_test_abc"
+    assert headers["Accept"] == "application/json"
+    assert headers["User-Agent"].startswith("volga-sdk-python/")
+
+
+def test_conversations_list_builds_query_and_omits_none():
+    client, http = make_client([{"body": page([{"id": "c1"}])}])
+    res = client.conversations.list(channel="instagram", limit=50)
+    assert res["data"][0]["id"] == "c1"
+    assert http.calls[0]["url"] == "https://api.test/v1/conversations?limit=50&channel=instagram"
+    assert "cursor" not in http.calls[0]["url"]
+
+
+def test_retrieve_url_encodes_id():
+    client, http = make_client([{"body": {"id": "a/b"}}])
+    client.conversations.retrieve("a/b")
+    assert http.calls[0]["url"] == "https://api.test/v1/conversations/a%2Fb"
+    assert http.calls[0]["method"] == "GET"
+
+
+def test_messages_list_requires_conversation_id():
+    client, http = make_client([{"body": page([{"id": "m1"}])}])
+    client.messages.list("c1", limit=10)
+    assert http.calls[0]["url"] == "https://api.test/v1/messages?conversationId=c1&limit=10"
+
+
+def test_messages_send_posts_body_and_idempotency_key():
+    client, http = make_client([{"status": 201, "body": {"id": "m9"}}])
+    sent = client.messages.send(conversation_id="c1", text="hello", idempotency_key="idem-123")
+    assert sent["id"] == "m9"
+    call = http.calls[0]
+    assert call["method"] == "POST"
+    assert json.loads(call["body"].decode()) == {"conversationId": "c1", "text": "hello"}
+    assert call["headers"]["Idempotency-Key"] == "idem-123"
+    assert call["headers"]["Content-Type"] == "application/json"
+
+
+def test_messages_send_without_idempotency_key():
+    client, http = make_client([{"status": 201, "body": {"id": "m1"}}])
+    client.messages.send(conversation_id="c1", text="hi")
+    assert "Idempotency-Key" not in http.calls[0]["headers"]
+
+
+def test_webhook_endpoint_create_returns_secret():
+    client, http = make_client(
+        [{"status": 201, "body": {"id": "we_1", "secret": "whsec_xyz"}}]
+    )
+    ep = client.webhook_endpoints.create(
+        url="https://x.test/hook", event_types=["message.sent"]
+    )
+    assert ep["secret"] == "whsec_xyz"
+    assert http.calls[0]["method"] == "POST"
+
+
+def test_webhook_endpoint_update_rotate_secret_is_query_not_body():
+    client, http = make_client([{"body": {"id": "we_1", "secret": "whsec_new"}}])
+    client.webhook_endpoints.update("we_1", is_active=False, rotate_secret=True)
+    call = http.calls[0]
+    assert call["method"] == "PATCH"
+    assert call["url"] == "https://api.test/v1/webhook-endpoints/we_1?rotateSecret=true"
+    assert json.loads(call["body"].decode()) == {"isActive": False}
+
+
+def test_webhook_endpoint_update_can_clear_description():
+    client, http = make_client([{"body": {"id": "we_1"}}])
+    client.webhook_endpoints.update("we_1", description=None)
+    assert json.loads(http.calls[0]["body"].decode()) == {"description": None}
+
+
+def test_webhook_endpoint_update_omits_untouched_description():
+    client, http = make_client([{"body": {"id": "we_1"}}])
+    client.webhook_endpoints.update("we_1", is_active=True)
+    assert json.loads(http.calls[0]["body"].decode()) == {"isActive": True}
+
+
+def test_webhook_endpoint_delete():
+    client, http = make_client([{"body": {"object": "webhook_endpoint", "id": "we_1", "deleted": True}}])
+    res = client.webhook_endpoints.delete("we_1")
+    assert res["deleted"] is True
+    assert http.calls[0]["method"] == "DELETE"
+
+
+def test_webhook_delivery_replay():
+    client, http = make_client([{"body": {"id": "wd_1", "status": "PENDING"}}])
+    res = client.webhook_deliveries.replay("wd_1")
+    assert res["status"] == "PENDING"
+    assert http.calls[0]["method"] == "POST"
+    assert http.calls[0]["url"] == "https://api.test/v1/webhook-deliveries/wd_1/replay"
+
+
+def test_get_openapi_spec():
+    client, http = make_client([{"body": {"openapi": "3.1.0"}}])
+    spec = client.get_openapi_spec()
+    assert spec["openapi"] == "3.1.0"
+    assert http.calls[0]["url"] == "https://api.test/v1/openapi.json"

volga_sdk-1.0.0/tests/test_http.py

@@ -0,0 +1,144 @@
+import pytest
+
+from volga import (
+    VolgaApiError,
+    VolgaAuthenticationError,
+    VolgaConflictError,
+    VolgaConnectionError,
+    VolgaNotFoundError,
+    VolgaPermissionError,
+    VolgaRateLimitError,
+    VolgaServerError,
+    VolgaTimeoutError,
+)
+from volga.errors import VolgaInvalidRequestError
+from tests.conftest import make_client, page
+
+EMPTY = page([])
+
+
+def err(code, message):
+    return {"error": message, "errorCode": code}
+
+
+@pytest.mark.parametrize(
+    "status,ctor",
+    [
+        (400, VolgaInvalidRequestError),
+        (401, VolgaAuthenticationError),
+        (403, VolgaPermissionError),
+        (404, VolgaNotFoundError),
+        (409, VolgaConflictError),
+        (422, VolgaInvalidRequestError),
+        (500, VolgaServerError),
+    ],
+)
+def test_error_mapping(status, ctor):
+    client, _ = make_client([{"status": status, "body": err("X", "boom")}], max_retries=0)
+    with pytest.raises(ctor):
+        client.conversations.list()
+
+
+def test_reads_message_and_code():
+    client, _ = make_client([{"status": 403, "body": err("INSUFFICIENT_SCOPE", "missing scope")}])
+    with pytest.raises(VolgaApiError) as exc:
+        client.conversations.list()
+    assert exc.value.status == 403
+    assert exc.value.code == "INSUFFICIENT_SCOPE"
+    assert exc.value.message == "missing scope"
+
+
+def test_exposes_trace_id_and_details():
+    body = {"error": "bad", "errorCode": "INVALID_PAYLOAD", "traceId": "tr_1", "details": {"f": 1}}
+    client, _ = make_client([{"status": 400, "body": body}])
+    with pytest.raises(VolgaApiError) as exc:
+        client.messages.send(conversation_id="c", text="x")
+    assert exc.value.trace_id == "tr_1"
+    assert exc.value.details == {"f": 1}
+
+
+def test_non_json_body_falls_back_to_synthetic_code():
+    client, _ = make_client([{"status": 404, "body": "Not Found"}], max_retries=0)
+    with pytest.raises(VolgaApiError) as exc:
+        client.conversations.retrieve("x")
+    assert exc.value.code == "HTTP_404"
+
+
+def test_retries_429_then_succeeds():
+    client, http = make_client(
+        [{"status": 429, "headers": {"Retry-After": "0"}, "body": err("RATE_LIMITED", "slow")},
+         {"body": EMPTY}]
+    )
+    client.conversations.list()
+    assert len(http.calls) == 2
+
+
+def test_surfaces_retry_after_when_exhausted():
+    client, _ = make_client(
+        [{"status": 429, "headers": {"Retry-After": "7"}, "body": err("RATE_LIMITED", "slow")}],
+        max_retries=1,
+    )
+    with pytest.raises(VolgaRateLimitError) as exc:
+        client.conversations.list()
+    assert exc.value.retry_after_sec == 7
+
+
+def test_retries_get_on_500():
+    client, http = make_client([{"status": 500, "body": err("X", "e")}, {"body": EMPTY}])
+    client.conversations.list()
+    assert len(http.calls) == 2
+
+
+def test_does_not_retry_post_without_idempotency_on_500():
+    client, http = make_client([{"status": 500, "body": err("X", "e")}])
+    with pytest.raises(VolgaServerError):
+        client.messages.send(conversation_id="c", text="x")
+    assert len(http.calls) == 1
+
+
+def test_retries_post_with_idempotency_on_500():
+    client, http = make_client(
+        [{"status": 500, "body": err("X", "e")}, {"status": 201, "body": {"id": "m1"}}]
+    )
+    client.messages.send(conversation_id="c", text="x", idempotency_key="k1")
+    assert len(http.calls) == 2
+
+
+def test_does_not_retry_4xx_other_than_429():
+    client, http = make_client([{"status": 400, "body": err("INVALID", "bad")}])
+    with pytest.raises(VolgaApiError):
+        client.conversations.list()
+    assert len(http.calls) == 1
+
+
+def test_retries_network_error_on_get():
+    client, http = make_client(
+        [{"raise": VolgaConnectionError("reset")}, {"body": EMPTY}]
+    )
+    client.conversations.list()
+    assert len(http.calls) == 2
+
+
+def test_wraps_persistent_network_failure():
+    client, _ = make_client([{"raise": VolgaConnectionError("reset")}], max_retries=1)
+    with pytest.raises(VolgaConnectionError):
+        client.conversations.list()
+
+
+def test_timeout_on_get_retries_then_raises():
+    client, http = make_client(
+        [{"raise": VolgaTimeoutError("timed out")}], max_retries=2
+    )
+    with pytest.raises(VolgaTimeoutError):
+        client.conversations.list()
+    # initial attempt + 2 retries (timeout is a network-level failure on a GET)
+    assert len(http.calls) == 3
+
+
+def test_timeout_on_post_without_idempotency_is_not_retried():
+    client, http = make_client(
+        [{"raise": VolgaTimeoutError("timed out")}], max_retries=2
+    )
+    with pytest.raises(VolgaTimeoutError):
+        client.messages.send(conversation_id="c", text="x")
+    assert len(http.calls) == 1

volga_sdk-1.0.0/tests/test_operations.py

@@ -0,0 +1,63 @@
+import json
+import os
+
+from volga import OPERATIONS, WEBHOOK_EVENT_TYPES, VolgaClient, operation_key
+
+REPO_ROOT = os.path.abspath(
+    os.path.join(os.path.dirname(__file__), "..", "..", "..")
+)
+OPENAPI_PATH = os.path.join(REPO_ROOT, "openapi", "openapi.json")
+
+HTTP_METHODS = {"get", "post", "put", "patch", "delete"}
+
+
+def _spec_operation_keys():
+    with open(OPENAPI_PATH, "r", encoding="utf-8") as fh:
+        spec = json.load(fh)
+    keys = set()
+    for path, item in spec["paths"].items():
+        for method in item:
+            if method.lower() in HTTP_METHODS:
+                keys.add("{} {}".format(method.upper(), path))
+    return keys
+
+
+def _spec_webhook_event_types():
+    with open(OPENAPI_PATH, "r", encoding="utf-8") as fh:
+        spec = json.load(fh)
+    return set(spec.get("webhooks", {}).keys())
+
+
+def test_sdk_declares_exactly_the_documented_webhook_events():
+    spec_events = _spec_webhook_event_types()
+    sdk_events = set(WEBHOOK_EVENT_TYPES)
+    assert sdk_events == spec_events, (
+        "webhook event drift — sdk: {}, spec: {}".format(sdk_events, spec_events)
+    )
+
+
+def test_operation_keys_are_unique():
+    keys = [operation_key(op) for op in OPERATIONS]
+    assert len(set(keys)) == len(keys)
+
+
+def test_sdk_covers_every_documented_operation():
+    spec_keys = _spec_operation_keys()
+    sdk_keys = {operation_key(op) for op in OPERATIONS}
+    missing = spec_keys - sdk_keys
+    phantom = sdk_keys - spec_keys
+    assert not missing, "documented operations not implemented in the SDK: {}".format(missing)
+    assert not phantom, "SDK operations not in the contract: {}".format(phantom)
+
+
+def test_every_operation_resolves_to_a_real_method():
+    client = VolgaClient(api_key="vk_test_x")
+    for op in OPERATIONS:
+        if op["resource"] == "(client)":
+            assert callable(getattr(client, op["fn"], None)), op["fn"]
+            continue
+        resource = getattr(client, op["resource"], None)
+        assert resource is not None, "missing resource {}".format(op["resource"])
+        assert callable(getattr(resource, op["fn"], None)), "{}.{}".format(
+            op["resource"], op["fn"]
+        )