flowqueue 0.1.0__py3-none-any.whl

flowqueue/__init__.py

@@ -0,0 +1,17 @@
+"""FlowQueue Python SDK — sync client for the FlowQueue message platform."""
+
+from .client import FlowQueueClient
+from .consumer import FlowQueueConsumer
+from .errors import ApiError, FlowQueueError
+from .models import Delivery
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FlowQueueClient",
+    "FlowQueueConsumer",
+    "Delivery",
+    "FlowQueueError",
+    "ApiError",
+    "__version__",
+]

flowqueue/client.py

@@ -0,0 +1,266 @@
+"""FlowQueue synchronous client — full coverage of the FlowQueue HTTP API."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+
+import httpx
+
+from .errors import ApiError
+
+
+def _iso(value: Optional[datetime | str]) -> Optional[str]:
+    if value is None:
+        return None
+    return value.isoformat() if isinstance(value, datetime) else value
+
+
+class FlowQueueClient:
+    """Authenticated client for a FlowQueue server.
+
+    Example:
+        from flowqueue import FlowQueueClient
+        client = FlowQueueClient("https://flowqueue.example.com", "fq_...")
+        q = client.create_queue("orders")
+        client.publish(q["id"], {"hello": "world"}, idempotency_key="abc")
+    """
+
+    def __init__(self, base_url: str, api_key: str, *, timeout: float = 30.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+
+    # ---- lifecycle -------------------------------------------------------- #
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "FlowQueueClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # ---- low-level -------------------------------------------------------- #
+    def _request(self, method: str, path: str, **kw) -> Any:
+        resp = self._http.request(method, path, **kw)
+        if resp.status_code == 204 or not resp.content:
+            if 200 <= resp.status_code < 300:
+                return None
+        try:
+            body = resp.json()
+        except ValueError:
+            body = None
+        if not (200 <= resp.status_code < 300):
+            code, message = None, resp.text
+            if isinstance(body, dict):
+                err = body.get("error")
+                if isinstance(err, dict):
+                    code, message = err.get("code"), err.get("message", message)
+                elif "detail" in body:
+                    message = body["detail"]
+            raise ApiError(resp.status_code, code, message or "request failed")
+        return body
+
+    _v = "/api/v1"
+
+    # ---- queues ----------------------------------------------------------- #
+    def create_queue(self, name: str, **opts) -> dict:
+        """Create a queue. opts: fifo_enabled, max_retries, retry_delay_seconds,
+        visibility_timeout_seconds, retention_seconds, processed_retention_seconds,
+        dlq_enabled, metadata."""
+        return self._request("POST", f"{self._v}/queues", json={"name": name, **opts})
+
+    def list_queues(self, archived: bool = False, limit: int = 100, offset: int = 0) -> dict:
+        return self._request(
+            "GET", f"{self._v}/queues",
+            params={"archived": archived, "limit": limit, "offset": offset},
+        )
+
+    def get_queue(self, queue_id: str) -> dict:
+        return self._request("GET", f"{self._v}/queues/{queue_id}")
+
+    def update_queue(self, queue_id: str, **fields) -> dict:
+        return self._request("PATCH", f"{self._v}/queues/{queue_id}", json=fields)
+
+    def archive_queue(self, queue_id: str) -> dict:
+        return self._request("DELETE", f"{self._v}/queues/{queue_id}")
+
+    def restore_queue(self, queue_id: str) -> dict:
+        return self._request("PATCH", f"{self._v}/queues/{queue_id}", json={"is_active": True})
+
+    def pause_queue(self, queue_id: str) -> dict:
+        return self._request("POST", f"{self._v}/queues/{queue_id}/pause")
+
+    def resume_queue(self, queue_id: str) -> dict:
+        return self._request("POST", f"{self._v}/queues/{queue_id}/resume")
+
+    def queue_stats(self, queue_id: str) -> dict:
+        return self._request("GET", f"{self._v}/queues/{queue_id}/stats")
+
+    def queue_timeseries(self, queue_id: str, minutes: int = 60) -> list:
+        return self._request(
+            "GET", f"{self._v}/queues/{queue_id}/timeseries", params={"minutes": minutes}
+        )
+
+    # ---- consumers -------------------------------------------------------- #
+    def create_consumer(
+        self,
+        queue_id: str,
+        name: str,
+        type: str = "http",
+        *,
+        endpoint_url: str | None = None,
+        routing_rules: list | None = None,
+        match_mode: str = "any",
+        auto_complete: bool = True,
+        signing_secret: str | None = None,
+        metadata: dict | None = None,
+    ) -> dict:
+        body = {
+            "name": name,
+            "type": type,
+            "endpoint_url": endpoint_url,
+            "routing_rules": routing_rules or [],
+            "match_mode": match_mode,
+            "auto_complete": auto_complete,
+            "signing_secret": signing_secret,
+            "metadata": metadata or {},
+        }
+        return self._request("POST", f"{self._v}/queues/{queue_id}/consumers", json=body)
+
+    def list_consumers(self, queue_id: str, limit: int = 100, offset: int = 0) -> dict:
+        return self._request(
+            "GET", f"{self._v}/queues/{queue_id}/consumers",
+            params={"limit": limit, "offset": offset},
+        )
+
+    def get_consumer(self, consumer_id: str) -> dict:
+        return self._request("GET", f"{self._v}/consumers/{consumer_id}")
+
+    def update_consumer(self, queue_id: str, consumer_id: str, **fields) -> dict:
+        return self._request(
+            "PATCH", f"{self._v}/queues/{queue_id}/consumers/{consumer_id}", json=fields
+        )
+
+    def deactivate_consumer(self, queue_id: str, consumer_id: str) -> dict:
+        return self._request("DELETE", f"{self._v}/queues/{queue_id}/consumers/{consumer_id}")
+
+    def test_consumer(self, queue_id: str, consumer_id: str) -> dict:
+        return self._request("POST", f"{self._v}/queues/{queue_id}/consumers/{consumer_id}/test")
+
+    # ---- messages (producer) --------------------------------------------- #
+    def publish(
+        self,
+        queue_id: str,
+        payload: dict,
+        idempotency_key: str | None = None,
+        *,
+        delay_seconds: int | None = None,
+        deliver_at: datetime | str | None = None,
+    ) -> dict:
+        """Publish a message. Optionally schedule it with delay_seconds or deliver_at."""
+        body: dict[str, Any] = {"payload": payload}
+        if idempotency_key is not None:
+            body["idempotency_key"] = idempotency_key
+        if delay_seconds is not None:
+            body["delay_seconds"] = delay_seconds
+        if deliver_at is not None:
+            body["deliver_at"] = _iso(deliver_at)
+        return self._request("POST", f"{self._v}/queues/{queue_id}/messages", json=body)
+
+    def list_messages(self, queue_id: str, limit: int = 50, offset: int = 0) -> dict:
+        return self._request(
+            "GET", f"{self._v}/queues/{queue_id}/messages",
+            params={"limit": limit, "offset": offset},
+        )
+
+    def get_message(self, queue_id: str, message_id: str) -> dict:
+        return self._request("GET", f"{self._v}/queues/{queue_id}/messages/{message_id}")
+
+    # ---- deliveries (consumer) ------------------------------------------- #
+    def poll(self, consumer_id: str) -> dict | None:
+        return self._request("POST", f"{self._v}/consumers/{consumer_id}/poll")
+
+    def ack(self, delivery_id: str) -> dict:
+        return self._request("POST", f"{self._v}/deliveries/{delivery_id}/ack")
+
+    def complete(self, delivery_id: str, remark: str | None = None, metadata: dict | None = None) -> dict:
+        return self._request(
+            "POST", f"{self._v}/deliveries/{delivery_id}/complete",
+            json={"remark": remark, "metadata": metadata or {}},
+        )
+
+    def fail(self, delivery_id: str, remark: str, metadata: dict | None = None) -> dict:
+        return self._request(
+            "POST", f"{self._v}/deliveries/{delivery_id}/fail",
+            json={"remark": remark, "metadata": metadata or {}},
+        )
+
+    def add_remark(self, delivery_id: str, remark: str) -> dict:
+        return self._request(
+            "POST", f"{self._v}/deliveries/{delivery_id}/remark", json={"remark": remark}
+        )
+
+    def get_delivery(self, delivery_id: str) -> dict:
+        return self._request("GET", f"{self._v}/deliveries/{delivery_id}")
+
+    def delivery_history(self, delivery_id: str) -> list:
+        return self._request("GET", f"{self._v}/deliveries/{delivery_id}/history")
+
+    def list_consumer_deliveries(
+        self, consumer_id: str, status: str | None = None, limit: int = 50, offset: int = 0
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        if status:
+            params["status"] = status
+        return self._request(
+            "GET", f"{self._v}/consumers/{consumer_id}/deliveries", params=params
+        )
+
+    # ---- replay ----------------------------------------------------------- #
+    def replay_failed(self, consumer_id: str) -> dict:
+        return self._request("POST", f"{self._v}/consumers/{consumer_id}/replay/failed")
+
+    def replay_range(self, consumer_id: str, from_ts: datetime | str, to_ts: datetime | str) -> dict:
+        return self._request(
+            "POST", f"{self._v}/consumers/{consumer_id}/replay/range",
+            json={"from_ts": _iso(from_ts), "to_ts": _iso(to_ts)},
+        )
+
+    def replay_selected(self, consumer_id: str, message_ids: list[str]) -> dict:
+        return self._request(
+            "POST", f"{self._v}/consumers/{consumer_id}/replay/selected",
+            json={"message_ids": message_ids},
+        )
+
+    def replay_backfill(self, consumer_id: str) -> dict:
+        return self._request("POST", f"{self._v}/consumers/{consumer_id}/replay/backfill")
+
+    def get_replay(self, replay_id: str) -> dict:
+        return self._request("GET", f"{self._v}/replay/{replay_id}")
+
+    # ---- dead-letter queue ----------------------------------------------- #
+    def dlq_list(self, queue_id: str, limit: int = 100, offset: int = 0) -> dict:
+        return self._request(
+            "GET", f"{self._v}/queues/{queue_id}/dlq", params={"limit": limit, "offset": offset}
+        )
+
+    def requeue(self, delivery_id: str) -> dict:
+        return self._request("POST", f"{self._v}/deliveries/{delivery_id}/requeue")
+
+    def discard(self, delivery_id: str) -> dict:
+        return self._request("POST", f"{self._v}/deliveries/{delivery_id}/discard")
+
+    def requeue_all(self, queue_id: str) -> dict:
+        return self._request("POST", f"{self._v}/queues/{queue_id}/dlq/requeue")
+
+    # ---- api keys --------------------------------------------------------- #
+    def create_api_key(self, name: str, scopes: list[str] | None = None) -> dict:
+        return self._request(
+            "POST", f"{self._v}/api-keys",
+            json={"name": name, "scopes": scopes or ["publish", "consume"]},
+        )

flowqueue/consumer.py

@@ -0,0 +1,75 @@
+"""High-level pull consumer with an optional run() loop."""
+
+from __future__ import annotations
+
+import time
+from typing import Callable, Optional
+
+from .client import FlowQueueClient
+from .models import Delivery
+
+
+class FlowQueueConsumer:
+    """Pull consumer bound to a single consumer id.
+
+    Example:
+        from flowqueue import FlowQueueClient, FlowQueueConsumer
+        client = FlowQueueClient(url, key)
+        consumer = FlowQueueConsumer(client, consumer_id)
+
+        # one-shot
+        d = consumer.poll()
+        if d:
+            consumer.complete(d.id, remark="ok")
+
+        # or run forever (handler return => complete, raise => fail)
+        consumer.run(lambda d: process(d.payload))
+    """
+
+    def __init__(self, client: FlowQueueClient, consumer_id: str) -> None:
+        self.client = client
+        self.consumer_id = consumer_id
+
+    def poll(self) -> Optional[Delivery]:
+        data = self.client.poll(self.consumer_id)
+        return Delivery.from_dict(data) if data else None
+
+    def ack(self, delivery_id: str) -> dict:
+        return self.client.ack(delivery_id)
+
+    def complete(self, delivery_id: str, remark: str | None = None) -> dict:
+        return self.client.complete(delivery_id, remark=remark)
+
+    def fail(self, delivery_id: str, remark: str, metadata: dict | None = None) -> dict:
+        return self.client.fail(delivery_id, remark, metadata)
+
+    def add_remark(self, delivery_id: str, remark: str) -> dict:
+        return self.client.add_remark(delivery_id, remark)
+
+    def run(
+        self,
+        handler: Callable[[Delivery], None],
+        *,
+        poll_interval: float = 2.0,
+        auto_complete: bool = True,
+        max_iterations: int | None = None,
+    ) -> None:
+        """Continuously poll and dispatch deliveries to `handler`.
+
+        On success the delivery is completed (when auto_complete); on exception it is
+        failed (triggering retry/DLQ per queue config). Sleeps poll_interval when idle.
+        Set max_iterations to bound the loop (useful for tests/cron-style runs).
+        """
+        iterations = 0
+        while max_iterations is None or iterations < max_iterations:
+            iterations += 1
+            delivery = self.poll()
+            if delivery is None:
+                time.sleep(poll_interval)
+                continue
+            try:
+                handler(delivery)
+                if auto_complete:
+                    self.complete(delivery.id, remark="ok")
+            except Exception as exc:  # noqa: BLE001
+                self.fail(delivery.id, remark=str(exc)[:500])

flowqueue/errors.py

@@ -0,0 +1,23 @@
+"""SDK exceptions."""
+
+from __future__ import annotations
+
+
+class FlowQueueError(Exception):
+    """Base error for the FlowQueue SDK."""
+
+
+class ApiError(FlowQueueError):
+    """Raised on a non-2xx API response.
+
+    Attributes:
+        status: HTTP status code.
+        code: machine-readable error code from the API envelope (if any).
+        message: human-readable message.
+    """
+
+    def __init__(self, status: int, code: str | None, message: str) -> None:
+        self.status = status
+        self.code = code
+        self.message = message
+        super().__init__(f"[{status}] {code or 'error'}: {message}")

flowqueue/models.py

@@ -0,0 +1,33 @@
+"""Lightweight data models returned by the SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class Delivery:
+    """A delivery claimed by a consumer via poll()."""
+
+    id: str
+    message_id: str
+    consumer_id: str
+    status: str
+    attempt_count: int
+    payload: dict
+    sequence_num: int
+    raw: dict[str, Any]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Delivery":
+        return cls(
+            id=data["id"],
+            message_id=data["message_id"],
+            consumer_id=data["consumer_id"],
+            status=data["status"],
+            attempt_count=data["attempt_count"],
+            payload=data.get("payload", {}),
+            sequence_num=data.get("sequence_num", 0),
+            raw=data,
+        )

flowqueue-0.1.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: flowqueue
+Version: 0.1.0
+Summary: Python client SDK for FlowQueue — a cloud-native message processing platform
+Author: FlowQueue
+License: MIT
+Project-URL: Homepage, https://github.com/your-org/flowqueue
+Project-URL: Repository, https://github.com/your-org/flowqueue
+Project-URL: Documentation, https://github.com/your-org/flowqueue#readme
+Keywords: queue,messaging,webhook,delivery,dlq,flowqueue
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# flowqueue
+
+Python client SDK for **FlowQueue** — a cloud-native message processing platform
+(durable queues, per-consumer delivery lifecycle, retries, dead-letter queue,
+scheduled delivery, webhooks with HMAC signing, replay, and a tamper-evident audit
+log).
+
+```bash
+pip install flowqueue
+```
+
+## Quickstart
+
+```python
+from flowqueue import FlowQueueClient, FlowQueueConsumer
+
+client = FlowQueueClient("https://flowqueue.example.com", "fq_your_api_key")
+
+# Create a queue + a pull consumer
+queue = client.create_queue("orders", max_retries=5, dlq_enabled=True)
+consumer = client.create_consumer(queue["id"], "billing", type="http")
+
+# Publish (optionally scheduled)
+client.publish(queue["id"], {"order_id": 42}, idempotency_key="order-42")
+client.publish(queue["id"], {"order_id": 43}, delay_seconds=30)   # deliver in 30s
+
+# Consume one delivery
+c = FlowQueueConsumer(client, consumer["id"])
+d = c.poll()
+if d:
+    print(d.payload)
+    c.complete(d.id, remark="done")
+```
+
+## Run a worker loop
+
+```python
+def handle(delivery):
+    process(delivery.payload)        # raise to fail (retry / DLQ), return to complete
+
+FlowQueueConsumer(client, consumer_id).run(handle, poll_interval=2.0)
+```
+
+## Management, replay, DLQ
+
+```python
+client.pause_queue(qid); client.resume_queue(qid)
+client.queue_stats(qid)
+client.replay_failed(consumer_id)
+dead = client.dlq_list(qid)
+client.requeue_all(qid)              # bulk requeue the dead-letter queue
+```
+
+## API keys & scopes
+
+Generate scoped keys in the FlowQueue UI or:
+
+```python
+key = client.create_api_key("ci-publisher", scopes=["publish"])
+print(key["token"])   # shown once
+```
+
+Errors raise `flowqueue.ApiError(status, code, message)`.
+
+## License
+
+MIT

flowqueue-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+flowqueue/__init__.py,sha256=EnfxSqLJ1gWkne2ESt6huQJOYHkhK5ocKT1Xa5jXW04,389
+flowqueue/client.py,sha256=fV0eTW6wt4-b4VRwSCRg3Mn_mn0dbhKFh54-AxH2JUY,10823
+flowqueue/consumer.py,sha256=nn-4LUd-I-5xtehyO92yKKote5AuXgMYRLVRTQvwwns,2581
+flowqueue/errors.py,sha256=kj0ASuNpAMQYvcD__WNqeNfRGj_uqnTJU_Gz7aRdOEo,618
+flowqueue/models.py,sha256=2rpvLqXh1Uj2Q7EZYoZROKuC-aWFxvLtwEImpixTrz8,804
+flowqueue-0.1.0.dist-info/licenses/LICENSE,sha256=HY8eppn2qqxGTR4WJwFhdKwTGEJ89QQ7e1-6TpJWMRQ,1066
+flowqueue-0.1.0.dist-info/METADATA,sha256=UV6FluqcLep6-tMEd9sRZGUE9HpVBVdEZ_GEgJDevWo,2673
+flowqueue-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+flowqueue-0.1.0.dist-info/top_level.txt,sha256=Xf0tKH0SZR4P9Kj5BjNPPEt6OXhmV2BqQr6MXEe39o0,10
+flowqueue-0.1.0.dist-info/RECORD,,

flowqueue-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flowqueue-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlowQueue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flowqueue-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+flowqueue