coconnect 1.0.0__tar.gz

coconnect-1.0.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: coconnect
+Version: 1.0.0
+Summary: Send your platform's events to CoConnect Hub, in your own words. Server side.
+License: MIT
+Keywords: coconnect,quests,rewards,partner,events
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# coconnect
+
+Send what users do on your platform to CoConnect Hub, named the way your platform already names it. CoConnect matches each event to the right task and rewards the member.
+
+```bash
+pip install coconnect
+```
+
+```python
+import os
+from coconnect import CoConnect
+
+hub = CoConnect(token=os.environ["COCONNECT_TOKEN"])
+
+# When a user signs up (cc_id is the cookie set by https://hub.coconnect.co/sdk.js on your site):
+hub.send("user_registered", user="u_1001", cc_id=request.cookies.get("cc_id"))
+
+# Anything else, in your own words, with whatever details you have:
+hub.send("ftd", user="u_1001", amount=75, currency="USD", id="dep_10482")
+hub.send("kyc_failed", user="u_1001", status="failed", reason="Document unreadable")
+```
+
+- **`user`** is required: your own ID for the user.
+- **`cc_id`** links the user to their CoConnect account. Send it at least once per user.
+- **`id`** is your reference for the event. If you leave it out, the SDK generates one, so a retried request is never counted twice.
+- **Any other keyword arguments** are kept as details of the event. Emails and phone numbers are hashed by CoConnect on arrival.
+- **Batching:** `send_batch([...])` sends up to 50 events at once.
+
+The SDK also handles:
+- **Retries:** network errors, 429 and 5xx responses are retried with backoff.
+- **Errors:** a bad token or a malformed event raises `CoConnectError`.
+- **No dependencies** beyond the standard library.
+
+Keep your token on the server.

coconnect-1.0.0/README.md

@@ -0,0 +1,34 @@
+# coconnect
+
+Send what users do on your platform to CoConnect Hub, named the way your platform already names it. CoConnect matches each event to the right task and rewards the member.
+
+```bash
+pip install coconnect
+```
+
+```python
+import os
+from coconnect import CoConnect
+
+hub = CoConnect(token=os.environ["COCONNECT_TOKEN"])
+
+# When a user signs up (cc_id is the cookie set by https://hub.coconnect.co/sdk.js on your site):
+hub.send("user_registered", user="u_1001", cc_id=request.cookies.get("cc_id"))
+
+# Anything else, in your own words, with whatever details you have:
+hub.send("ftd", user="u_1001", amount=75, currency="USD", id="dep_10482")
+hub.send("kyc_failed", user="u_1001", status="failed", reason="Document unreadable")
+```
+
+- **`user`** is required: your own ID for the user.
+- **`cc_id`** links the user to their CoConnect account. Send it at least once per user.
+- **`id`** is your reference for the event. If you leave it out, the SDK generates one, so a retried request is never counted twice.
+- **Any other keyword arguments** are kept as details of the event. Emails and phone numbers are hashed by CoConnect on arrival.
+- **Batching:** `send_batch([...])` sends up to 50 events at once.
+
+The SDK also handles:
+- **Retries:** network errors, 429 and 5xx responses are retried with backoff.
+- **Errors:** a bad token or a malformed event raises `CoConnectError`.
+- **No dependencies** beyond the standard library.
+
+Keep your token on the server.

coconnect-1.0.0/coconnect/__init__.py

@@ -0,0 +1,146 @@
+"""CoConnect Hub SDK for Python (3.8+), server side only.
+
+Partners send what happened on their platform, in their own words::
+
+    from coconnect import CoConnect
+    hub = CoConnect(token=os.environ["COCONNECT_TOKEN"])
+    hub.send("ftd", user="u_1001", cc_id=cc_id, amount=75, currency="USD")
+
+CoConnect matches each event to the right task. The SDK adds a unique id to
+every event (so a retry is never counted twice), retries when the hub is
+briefly unreachable, and skips events no task needs once the hub says so.
+No dependencies beyond the standard library.
+"""
+
+import json
+import random
+import re
+import time
+import urllib.error
+import urllib.request
+import uuid
+
+__all__ = ["CoConnect", "CoConnectError"]
+__version__ = "1.0.0"
+
+_KNOWN = {"user", "cc_id", "status", "id", "amount", "currency", "reason", "wallet", "email", "x", "discord", "properties"}
+_RETRY = {408, 425, 429, 500, 502, 503, 504}
+
+
+class CoConnectError(Exception):
+    def __init__(self, message, status=None, body=None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+def _event_key(name):
+    s = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", str(name or "")).lower()
+    return re.sub(r"[^a-z0-9]+", "_", s).strip("_")
+
+
+class CoConnect:
+    def __init__(self, token, base_url="https://hub.coconnect.co", max_retries=4, timeout=10, filter=True):
+        """token: your partner token from CoConnect (keep it on the server)."""
+        if not token or not isinstance(token, str):
+            raise CoConnectError("A token is required.")
+        self.token = token
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self.filter = filter
+        self._config = None
+        self._config_at = 0.0
+
+    def send(self, event, user, **details):
+        """Send one event, named the way your platform names it (e.g. "ftd").
+
+        user: your own ID for the user (required). Optional: cc_id, status
+        ("completed" | "failed" | "reversed"), id (your reference), amount,
+        currency, reason, wallet, email, x, discord, and any other details.
+        """
+        out = self.send_batch([dict(details, event=event, user=user)])
+        results = out.get("results") or []
+        return results[0] if results else out
+
+    def send_batch(self, events):
+        """Up to 50 events in one request, each a dict with event, user and details."""
+        if not events:
+            raise CoConnectError("No events.")
+        if len(events) > 50:
+            raise CoConnectError("At most 50 events per batch.")
+        wanted = [self._shape(e) for e in events if self._wanted(e.get("event"))]
+        if not wanted:
+            return {"ok": True, "results": [], "skipped": len(events)}
+        return self._request("POST", "/api/partner/events", {"events": wanted})
+
+    def _shape(self, e):
+        event = e.get("event")
+        if not event:
+            raise CoConnectError("Each event needs a name.")
+        if e.get("user") in (None, ""):
+            raise CoConnectError('"%s" needs user: your own ID for the user.' % event)
+        properties = dict(e.get("properties") or {})
+        for k, v in e.items():
+            if k not in _KNOWN and k != "event" and v is not None:
+                properties[k] = v
+        body = {
+            "event": str(event),
+            "user": str(e["user"]),
+            "status": e.get("status", "completed"),
+            # A unique reference per event: a retried request is then counted once.
+            "id": str(e["id"]) if e.get("id") is not None else str(uuid.uuid4()),
+            "properties": properties,
+        }
+        for k in ("cc_id", "amount", "currency", "reason", "wallet", "email", "x", "discord"):
+            if e.get(k) is not None:
+                body[k] = e[k]
+        return body
+
+    def _wanted(self, name):
+        if not self.filter:
+            return True
+        cfg = self._get_config()
+        key = _event_key(name)
+        if not cfg or key not in (cfg.get("quiet") or []) or key in (cfg.get("events") or []):
+            return True
+        return random.random() < float(cfg.get("sample", 0.05))
+
+    def _get_config(self):
+        age = float((self._config or {}).get("refreshSeconds", 300))
+        if self._config is not None and time.time() - self._config_at < age:
+            return self._config
+        try:
+            self._config = self._request("GET", "/api/partner/config")
+        except CoConnectError:
+            # Without advice, everything is sent.
+            self._config = None
+        self._config_at = time.time()
+        return self._config
+
+    def _request(self, method, path, body=None):
+        last = None
+        for attempt in range(self.max_retries + 1):
+            if attempt:
+                time.sleep(min(8.0, 0.5 * 2 ** (attempt - 1)) + random.random() * 0.25)
+            data = json.dumps(body).encode() if body is not None else None
+            req = urllib.request.Request(
+                self.base_url + path,
+                data=data,
+                method=method,
+                headers={"content-type": "application/json", "x-cc-token": self.token, "user-agent": "coconnect-sdk-python/" + __version__},
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                    return json.loads(res.read() or b"{}")
+            except urllib.error.HTTPError as e:
+                try:
+                    payload = json.loads(e.read() or b"{}")
+                except ValueError:
+                    payload = {}
+                last = CoConnectError(payload.get("error") or "CoConnect answered %s" % e.code, e.code, payload)
+                if e.code not in _RETRY:
+                    raise last
+            except (urllib.error.URLError, TimeoutError, OSError) as e:
+                last = CoConnectError("Couldn't reach CoConnect: %s" % e)
+        raise last

coconnect-1.0.0/coconnect.egg-info/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: coconnect
+Version: 1.0.0
+Summary: Send your platform's events to CoConnect Hub, in your own words. Server side.
+License: MIT
+Keywords: coconnect,quests,rewards,partner,events
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# coconnect
+
+Send what users do on your platform to CoConnect Hub, named the way your platform already names it. CoConnect matches each event to the right task and rewards the member.
+
+```bash
+pip install coconnect
+```
+
+```python
+import os
+from coconnect import CoConnect
+
+hub = CoConnect(token=os.environ["COCONNECT_TOKEN"])
+
+# When a user signs up (cc_id is the cookie set by https://hub.coconnect.co/sdk.js on your site):
+hub.send("user_registered", user="u_1001", cc_id=request.cookies.get("cc_id"))
+
+# Anything else, in your own words, with whatever details you have:
+hub.send("ftd", user="u_1001", amount=75, currency="USD", id="dep_10482")
+hub.send("kyc_failed", user="u_1001", status="failed", reason="Document unreadable")
+```
+
+- **`user`** is required: your own ID for the user.
+- **`cc_id`** links the user to their CoConnect account. Send it at least once per user.
+- **`id`** is your reference for the event. If you leave it out, the SDK generates one, so a retried request is never counted twice.
+- **Any other keyword arguments** are kept as details of the event. Emails and phone numbers are hashed by CoConnect on arrival.
+- **Batching:** `send_batch([...])` sends up to 50 events at once.
+
+The SDK also handles:
+- **Retries:** network errors, 429 and 5xx responses are retried with backoff.
+- **Errors:** a bad token or a malformed event raises `CoConnectError`.
+- **No dependencies** beyond the standard library.
+
+Keep your token on the server.

coconnect-1.0.0/coconnect.egg-info/SOURCES.txt

@@ -0,0 +1,7 @@
+README.md
+pyproject.toml
+coconnect/__init__.py
+coconnect.egg-info/PKG-INFO
+coconnect.egg-info/SOURCES.txt
+coconnect.egg-info/dependency_links.txt
+coconnect.egg-info/top_level.txt

coconnect-1.0.0/coconnect.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

coconnect-1.0.0/coconnect.egg-info/top_level.txt

@@ -0,0 +1 @@
+coconnect

coconnect-1.0.0/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "coconnect"
+version = "1.0.0"
+description = "Send your platform's events to CoConnect Hub, in your own words. Server side."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+keywords = ["coconnect", "quests", "rewards", "partner", "events"]
+dependencies = []
+
+[tool.setuptools]
+packages = ["coconnect"]

coconnect-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+