loopengine 1.0.0__py3-none-any.whl

loopengine/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from .async_client import AsyncLoopEngine
+from .client import LoopEngine
+from .exceptions import LoopEngineError
+from .types import FeedbackPayload, SendResult
+
+__all__ = [
+    "LoopEngine",
+    "AsyncLoopEngine",
+    "LoopEngineError",
+    "FeedbackPayload",
+    "SendResult",
+]
+
+__version__ = "0.1.0"
+

loopengine/async_client.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Optional
+
+from .client import LoopEngine
+from .types import SendResult
+
+
+class AsyncLoopEngine:
+    """Asynchronous wrapper around the synchronous LoopEngine client.
+
+    This uses asyncio.to_thread to avoid extra HTTP dependencies while providing an async-friendly API.
+    """
+
+    def __init__(
+        self,
+        project_key: str,
+        project_secret: str,
+        project_id: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = 10.0,
+    ) -> None:
+        self._client = LoopEngine(
+            project_key=project_key,
+            project_secret=project_secret,
+            project_id=project_id,
+            base_url=base_url,
+            timeout=timeout,
+        )
+
+    async def send(self, payload: Any | None) -> SendResult:
+        """Asynchronously send a feedback payload to LoopEngine."""
+        return await asyncio.to_thread(self._client.send, payload)
+
+
+__all__ = ["AsyncLoopEngine"]
+

loopengine/client.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import json
+from http.client import HTTPSConnection
+from typing import Any, Callable, Mapping, MutableMapping, Optional
+from urllib.parse import urlparse
+
+from .constants import BASE_URL, FEEDBACK_PATH
+from .exceptions import LoopEngineError
+from .sign import build_auth_headers
+from .types import FeedbackPayload, SendResult
+
+
+_Transport = Callable[[str, bytes, Mapping[str, str], Optional[float]], tuple[int, str, bytes]]
+
+
+def _default_transport(url: str, body: bytes, headers: Mapping[str, str], timeout: Optional[float]) -> tuple[int, str, bytes]:
+    """Minimal HTTPS POST using the standard library."""
+    parsed = urlparse(url)
+    if parsed.scheme != "https":
+        raise LoopEngineError(message=f"loopengine: only https is supported (got {parsed.scheme!r})")
+
+    conn = HTTPSConnection(parsed.hostname, parsed.port or 443, timeout=timeout)
+    try:
+        path = parsed.path or "/"
+        if parsed.query:
+            path = f"{path}?{parsed.query}"
+        conn.request("POST", path, body=body, headers=dict(headers))
+        resp = conn.getresponse()
+        status = resp.status
+        reason = resp.reason or ""
+        data = resp.read()
+        return status, reason, data
+    except OSError as exc:
+        raise LoopEngineError(message="loopengine: send failed", cause=exc) from exc
+    finally:
+        conn.close()
+
+
+class LoopEngine:
+    """Synchronous LoopEngine client for sending feedback to the Ingest API."""
+
+    def __init__(
+        self,
+        project_key: str,
+        project_secret: str,
+        project_id: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = 10.0,
+        transport: Optional[_Transport] = None,
+    ) -> None:
+        project_key = (project_key or "").strip()
+        project_secret = (project_secret or "").strip()
+        project_id = (project_id or "").strip()
+        if not project_key or not project_secret or not project_id:
+            raise ValueError("loopengine: project_key, project_secret, and project_id are required")
+
+        self._project_key = project_key
+        self._project_secret = project_secret
+        self._project_id = project_id
+        self._base_url = (base_url or BASE_URL).rstrip("/")
+        self._timeout = timeout
+        self._transport: _Transport = transport or _default_transport
+
+    def _build_body(self, payload: Any) -> bytes:
+        if payload is None:
+            m: MutableMapping[str, Any] = {}
+        elif isinstance(payload, Mapping):
+            m = dict(payload)
+        else:
+            try:
+                # Convert arbitrary objects into a dict via JSON round-trip, mirroring Go behavior.
+                serialized = json.dumps(payload)
+                decoded = json.loads(serialized)
+            except (TypeError, ValueError) as exc:
+                raise LoopEngineError(message="loopengine: payload must be JSON-serializable") from exc
+            if not isinstance(decoded, Mapping):
+                raise LoopEngineError(message="loopengine: payload must deserialize to an object")
+            m = dict(decoded)
+
+        # Ensure project_id is set from the client configuration.
+        m["project_id"] = self._project_id
+
+        try:
+            body_bytes = json.dumps(m, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+        except (TypeError, ValueError) as exc:
+            raise LoopEngineError(message="loopengine: failed to encode JSON body") from exc
+        return body_bytes
+
+    def send(self, payload: FeedbackPayload | Any | None) -> SendResult:
+        """Send a feedback payload to LoopEngine.
+
+        The payload must be JSON-serializable and conform to your project's schema.
+        `project_id` is injected from the client configuration.
+        """
+        body = self._build_body(payload)
+        url = f"{self._base_url}{FEEDBACK_PATH}"
+        headers = {
+            "Content-Type": "application/json",
+            **build_auth_headers(
+                project_key=self._project_key,
+                project_secret=self._project_secret,
+                method="POST",
+                path=FEEDBACK_PATH,
+                body=body,
+            ),
+        }
+
+        status, reason, data = self._transport(url, body, headers, self._timeout)
+        text = data.decode("utf-8", errors="replace")
+
+        try:
+            parsed = json.loads(text) if text else {}
+        except json.JSONDecodeError:
+            parsed = {"raw": text}
+
+        if 200 <= status < 300:
+            return SendResult(ok=True, status=status, body=parsed)
+
+        raise LoopEngineError(
+            status=status,
+            body=text,
+            message=f"loopengine: {status} {reason} {text}",
+        )
+
+
+__all__ = ["LoopEngine"]
+

loopengine/constants.py

@@ -0,0 +1,3 @@
+BASE_URL = "https://api.loopengine.dev"
+FEEDBACK_PATH = "/feedback"
+

loopengine/exceptions.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class LoopEngineError(Exception):
+    """Error raised when the LoopEngine API responds with a non-2xx status or a request fails."""
+
+    status: Optional[int] = None
+    body: Optional[str] = None
+    message: Optional[str] = None
+    cause: Optional[BaseException] = None
+
+    def __str__(self) -> str:
+        prefix = "loopengine"
+        parts: list[str] = [prefix]
+        if self.status is not None:
+            parts.append(str(self.status))
+        if self.body:
+            snippet = self.body.strip()
+            if len(snippet) > 200:
+                snippet = snippet[:197] + "..."
+            parts.append(snippet)
+        if self.message:
+            parts.append(self.message)
+        return ": ".join(part for part in parts if part)
+

loopengine/sign.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import time
+from typing import Dict
+
+
+def sha256_hex(body: bytes) -> str:
+    """Return the SHA-256 hash of the given bytes as a lowercase hex string."""
+    digest = hashlib.sha256(body).hexdigest()
+    return digest
+
+
+def sign_request(secret: str, method: str, path: str, timestamp: str, body_hex: str) -> str:
+    """Sign the canonical request string with HMAC-SHA256 and return base64url (no padding)."""
+    canonical = f"{method}\n{path}\n{timestamp}\n{body_hex}"
+    mac = hmac.new(secret.encode("utf-8"), canonical.encode("utf-8"), hashlib.sha256)
+    sig_bytes = mac.digest()
+    b64 = base64.urlsafe_b64encode(sig_bytes).rstrip(b"=")
+    return b64.decode("ascii")
+
+
+def build_auth_headers(
+    project_key: str,
+    project_secret: str,
+    method: str,
+    path: str,
+    body: bytes,
+) -> Dict[str, str]:
+    """Build authentication headers for the LoopEngine API request."""
+    timestamp = str(int(time.time()))
+    body_hex = sha256_hex(body)
+    signature = sign_request(project_secret, method, path, timestamp, body_hex)
+    return {
+        "X-Project-Key": project_key,
+        "X-Timestamp": timestamp,
+        "X-Signature": f"v1={signature}",
+    }
+
+
+__all__ = ["sha256_hex", "sign_request", "build_auth_headers"]
+

loopengine/types.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+FeedbackPayload = Mapping[str, Any]
+
+
+@dataclass
+class SendResult:
+    ok: bool
+    status: int
+    body: Any
+
+
+__all__ = [
+    "FeedbackPayload",
+    "SendResult",
+]
+

loopengine-1.0.0.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: loopengine
+Version: 1.0.0
+Summary: Official LoopEngine SDK for sending feedback to the Ingest API
+Project-URL: Homepage, https://loopengine.dev
+Project-URL: Repository, https://github.com/LoopEngine-dev/loopengine-sdks
+Author-email: LoopEngine <support@loopengine.dev>
+License: MIT
+License-File: LICENSE
+Keywords: feedback,loopengine,sdk
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# LoopEngine
+
+Official LoopEngine SDK for sending feedback to the Ingest API. Two-line usage: create a client with your credentials, then call `send` with your payload.
+
+- **No external dependencies** — uses the Python standard library for HTTP and crypto
+- **Small surface** — one main client (`LoopEngine`) plus an async wrapper (`AsyncLoopEngine`)
+
+## Install
+
+```bash
+pip install loopengine
+```
+
+## Usage (sync)
+
+```python
+from loopengine import LoopEngine
+
+client = LoopEngine(
+    project_key="pk_live_...",
+    project_secret="psk_live_...",
+    project_id="proj_...",
+)
+
+result = client.send({"message": "User reported a bug"})
+if result.ok:
+    print(result.body)  # e.g. {"id": "fb_...", "analysis_status": "pending"}
+```
+
+## Usage (async)
+
+```python
+import asyncio
+from loopengine import AsyncLoopEngine
+
+
+async def main() -> None:
+    client = AsyncLoopEngine(
+        project_key="pk_live_...",
+        project_secret="psk_live_...",
+        project_id="proj_...",
+    )
+    result = await client.send({"message": "User reported a bug"})
+    if result.ok:
+        print(result.body)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Config
+
+Obtain `project_key`, `project_secret`, and `project_id` from your [LoopEngine dashboard](https://loopengine.dev). A typical configuration pattern is to read them from environment variables:
+
+```python
+import os
+from loopengine import LoopEngine
+
+client = LoopEngine(
+    project_key=os.environ["LOOPENGINE_PROJECT_KEY"],
+    project_secret=os.environ["LOOPENGINE_PROJECT_SECRET"],
+    project_id=os.environ["LOOPENGINE_PROJECT_ID"],
+)
+```
+
+## Payload
+
+The payload object you send must match the fields and constraints you defined when creating your project in the LoopEngine dashboard (required fields, allowed keys, value types, etc.). At a minimum, it should include all the required fields according to your project's schema.
+
+You **do not** need to pass `project_id` in the payload; it is automatically injected from the client configuration.
+
+Payloads can be:
+
+- A mapping/dict (`dict[str, object]`)
+- Any JSON-serializable object (for example a dataclass) that encodes to a JSON object
+
+## Quick test with `uv` and `clienttest`
+
+This repository includes a small `clienttest` example app you can run to verify your credentials and connectivity.
+
+1. **Install `uv`** (a fast Python package manager/runner):
+
+   ```bash
+   pip install uv
+   # or: pipx install uv
+   ```
+
+2. **From the `loopengine-python` directory, run the example**:
+
+   ```bash
+   # Using environment variables (recommended)
+   export LOOPENGINE_PROJECT_KEY="pk_live_..."
+   export LOOPENGINE_PROJECT_SECRET="psk_live_..."
+   export LOOPENGINE_PROJECT_ID="proj_..."
+
+   uv run examples/clienttest.py
+   ```
+
+   `uv run` creates an isolated environment, resolves dependencies, and executes the script in one step. Because this SDK has no runtime dependencies beyond the standard library, `uv` mainly provides a fast, reproducible way to run the example without managing a separate virtualenv.
+
+3. **Alternatively, edit placeholders directly** in `examples/clienttest.py`:
+
+   ```python
+   project_key = "<your_project_key_here>"
+   project_secret = "<your_project_secret_here>"
+   project_id = "<your_project_id_here>"
+   ```
+
+   Then run:
+
+   ```bash
+   uv run examples/clienttest.py
+   ```
+
+## Development
+
+To run tests locally:
+
+```bash
+uv run pytest
+```
+
+## Requirements
+
+- Python **>= 3.9**
+
+## License
+
+MIT
+

loopengine-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+loopengine/__init__.py,sha256=Cs5lhJjDumFk0lL70cEsiP8Aptf3VUx0VcE5_5k8Jco,340
+loopengine/async_client.py,sha256=twFepA41vbRl4IqWZCGEvx11I7HPsuACPo1wJuj0GkU,1024
+loopengine/client.py,sha256=xqOqbx2OIwRtgKf5R6QhFK2W-xXPsdfxXhrWAZjrNEQ,4757
+loopengine/constants.py,sha256=iZp2o2TdkrZwCx8mvOkeAR8P-fve9sXYegl3edYmxtw,69
+loopengine/exceptions.py,sha256=b_KlCDqS94Zdpupe6r-SoJED10vaZ2kNXVyi3SK7hwU,866
+loopengine/sign.py,sha256=Mnz3SSoSgpA7W2ppD8AF_YVsS5HonAqySp7YjhHR3TU,1315
+loopengine/types.py,sha256=U6MWz5VEHDBRrLi04waA17EIy1ci7OXJvTqF9whFo1w,271
+loopengine-1.0.0.dist-info/METADATA,sha256=8u_DlFB1VZJHcmTjQba27j__kCn9cxdf3VU5sqO1OCo,4485
+loopengine-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+loopengine-1.0.0.dist-info/licenses/LICENSE,sha256=3Fyiw8Brk__kyzxEZ4ZSulqa4N8khKbF17tUhzO2OuM,1068
+loopengine-1.0.0.dist-info/RECORD,,

loopengine-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

loopengine-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 LoopEngine
+
+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.
+