coconnect 1.0.0__tar.gz → 1.1.0__tar.gz

coconnect-1.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: coconnect
+Version: 1.1.0
+Summary: Send your platform's events to CoConnect Hub, in your own words. Server side.
+License-Expression: 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. Everything runs on your server; nothing is added to your web pages.
+
+```bash
+pip install coconnect
+```
+
+## 1. Keep the CoConnect ID
+
+Members arrive from CoConnect with their CoConnect ID in the link (`?cc_id=ck_...`). Read it on your server when they land and keep it in a first-party cookie or the session, so it survives sign-up redirects such as Google sign-in:
+
+```python
+from coconnect import cc_id_from_url
+
+# Flask shown; any framework works the same way.
+@app.after_request
+def keep_cc_id(response):
+    cc_id = cc_id_from_url(request.full_path)
+    if cc_id:
+        response.set_cookie("cc_id", cc_id, max_age=30 * 86400, httponly=True, secure=True, samesite="Lax")
+    return response
+
+# At sign-up, save request.cookies.get("cc_id") with the new account.
+```
+
+## 2. Send events
+
+```python
+import os
+from coconnect import CoConnect
+
+hub = CoConnect(
+    token=os.environ["COCONNECT_TOKEN"],
+    secret=os.environ.get("COCONNECT_SECRET"),  # optional: your signing secret
+)
+
+# When a user signs up:
+hub.send("user_registered", user="u_1001", cc_id=user.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.
+
+## Signed requests
+
+If CoConnect gave you a signing secret (`ccs_...`), pass it as `secret`. Every request is then signed with a timestamp, so it cannot be altered or replayed, even by someone who has seen your token. Without the client, `sign_request(secret, timestamp, method, path, body)` builds the `X-CC-Signature` value.
+
+## Also handled
+
+- **Retries:** network errors, 429 and 5xx responses are retried with backoff.
+- **Errors:** a bad token, a bad signature or a malformed event raises `CoConnectError`.
+- **No dependencies** beyond the standard library.
+
+Keep your token and secret on the server.

coconnect-1.1.0/README.md

@@ -0,0 +1,62 @@
+# 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. Everything runs on your server; nothing is added to your web pages.
+
+```bash
+pip install coconnect
+```
+
+## 1. Keep the CoConnect ID
+
+Members arrive from CoConnect with their CoConnect ID in the link (`?cc_id=ck_...`). Read it on your server when they land and keep it in a first-party cookie or the session, so it survives sign-up redirects such as Google sign-in:
+
+```python
+from coconnect import cc_id_from_url
+
+# Flask shown; any framework works the same way.
+@app.after_request
+def keep_cc_id(response):
+    cc_id = cc_id_from_url(request.full_path)
+    if cc_id:
+        response.set_cookie("cc_id", cc_id, max_age=30 * 86400, httponly=True, secure=True, samesite="Lax")
+    return response
+
+# At sign-up, save request.cookies.get("cc_id") with the new account.
+```
+
+## 2. Send events
+
+```python
+import os
+from coconnect import CoConnect
+
+hub = CoConnect(
+    token=os.environ["COCONNECT_TOKEN"],
+    secret=os.environ.get("COCONNECT_SECRET"),  # optional: your signing secret
+)
+
+# When a user signs up:
+hub.send("user_registered", user="u_1001", cc_id=user.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.
+
+## Signed requests
+
+If CoConnect gave you a signing secret (`ccs_...`), pass it as `secret`. Every request is then signed with a timestamp, so it cannot be altered or replayed, even by someone who has seen your token. Without the client, `sign_request(secret, timestamp, method, path, body)` builds the `X-CC-Signature` value.
+
+## Also handled
+
+- **Retries:** network errors, 429 and 5xx responses are retried with backoff.
+- **Errors:** a bad token, a bad signature or a malformed event raises `CoConnectError`.
+- **No dependencies** beyond the standard library.
+
+Keep your token and secret on the server.

{coconnect-1.0.0 → coconnect-1.1.0}/coconnect/__init__.py

@@ -8,23 +8,48 @@ Partners send what happened on their platform, in their own words::
 
 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.
+briefly unreachable, skips events no task needs once the hub says so, and
+signs every request when you give it your signing secret.
 No dependencies beyond the standard library.
 """
 
+import hashlib
+import hmac
 import json
 import random
 import re
 import time
 import urllib.error
+import urllib.parse
 import urllib.request
 import uuid
 
-__all__ = ["CoConnect", "CoConnectError"]
-__version__ = "1.0.0"
+__all__ = ["CoConnect", "CoConnectError", "cc_id_from_url", "sign_request"]
+__version__ = "1.1.0"
 
 _KNOWN = {"user", "cc_id", "status", "id", "amount", "currency", "reason", "wallet", "email", "x", "discord", "properties"}
 _RETRY = {408, 425, 429, 500, 502, 503, 504}
+_CC_ID = re.compile(r"^[A-Za-z0-9_-]{4,64}$")
+
+
+def cc_id_from_url(url):
+    """The CoConnect ID a member arrived with, read from your landing URL
+    (``?cc_id=...``), or None. Accepts a full URL or a path with its query.
+    Call it on your server when the request comes in, and keep the value in a
+    first-party cookie or the session until sign-up."""
+    try:
+        values = urllib.parse.parse_qs(urllib.parse.urlsplit(str(url)).query).get("cc_id") or []
+    except ValueError:
+        return None
+    value = values[0] if values else None
+    return value if value and _CC_ID.match(value) else None
+
+
+def sign_request(secret, timestamp, method, path, body=""):
+    """The X-CC-Signature value CoConnect expects: ``v1=`` and the hex
+    HMAC-SHA256 of ``<timestamp>.<METHOD>.<path with query>.<raw body>``."""
+    message = "%s.%s.%s.%s" % (timestamp, method.upper(), path, body)
+    return "v1=" + hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()
 
 
 class CoConnectError(Exception):
@@ -40,11 +65,16 @@ def _event_key(name):
 
 
 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)."""
+    def __init__(self, token, secret=None, base_url="https://hub.coconnect.co", max_retries=4, timeout=10, filter=True):
+        """token: your partner token from CoConnect (keep it on the server).
+        secret: your signing secret (ccs_...), if CoConnect gave you one;
+        every request is then signed."""
         if not token or not isinstance(token, str):
             raise CoConnectError("A token is required.")
+        if secret is not None and not isinstance(secret, str):
+            raise CoConnectError("The signing secret must be a string.")
         self.token = token
+        self.secret = secret or None
         self.base_url = base_url.rstrip("/")
         self.max_retries = max_retries
         self.timeout = timeout
@@ -120,15 +150,25 @@ class CoConnect:
 
     def _request(self, method, path, body=None):
         last = None
+        # Serialised once: the signature covers these exact bytes.
+        raw = json.dumps(body) if body is not None else ""
+        url = self.base_url + path
+        parts = urllib.parse.urlsplit(url)
+        signed_path = parts.path + ("?" + parts.query if parts.query else "")
         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
+            headers = {"content-type": "application/json", "x-cc-token": self.token, "user-agent": "coconnect-sdk-python/" + __version__}
+            if self.secret:
+                # A fresh timestamp per attempt, so a retry is never refused as stale.
+                ts = str(int(time.time()))
+                headers["x-cc-timestamp"] = ts
+                headers["x-cc-signature"] = sign_request(self.secret, ts, method, signed_path, raw)
             req = urllib.request.Request(
-                self.base_url + path,
-                data=data,
+                url,
+                data=raw.encode() if body is not None else None,
                 method=method,
-                headers={"content-type": "application/json", "x-cc-token": self.token, "user-agent": "coconnect-sdk-python/" + __version__},
+                headers=headers,
             )
             try:
                 with urllib.request.urlopen(req, timeout=self.timeout) as res:

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

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: coconnect
+Version: 1.1.0
+Summary: Send your platform's events to CoConnect Hub, in your own words. Server side.
+License-Expression: 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. Everything runs on your server; nothing is added to your web pages.
+
+```bash
+pip install coconnect
+```
+
+## 1. Keep the CoConnect ID
+
+Members arrive from CoConnect with their CoConnect ID in the link (`?cc_id=ck_...`). Read it on your server when they land and keep it in a first-party cookie or the session, so it survives sign-up redirects such as Google sign-in:
+
+```python
+from coconnect import cc_id_from_url
+
+# Flask shown; any framework works the same way.
+@app.after_request
+def keep_cc_id(response):
+    cc_id = cc_id_from_url(request.full_path)
+    if cc_id:
+        response.set_cookie("cc_id", cc_id, max_age=30 * 86400, httponly=True, secure=True, samesite="Lax")
+    return response
+
+# At sign-up, save request.cookies.get("cc_id") with the new account.
+```
+
+## 2. Send events
+
+```python
+import os
+from coconnect import CoConnect
+
+hub = CoConnect(
+    token=os.environ["COCONNECT_TOKEN"],
+    secret=os.environ.get("COCONNECT_SECRET"),  # optional: your signing secret
+)
+
+# When a user signs up:
+hub.send("user_registered", user="u_1001", cc_id=user.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.
+
+## Signed requests
+
+If CoConnect gave you a signing secret (`ccs_...`), pass it as `secret`. Every request is then signed with a timestamp, so it cannot be altered or replayed, even by someone who has seen your token. Without the client, `sign_request(secret, timestamp, method, path, body)` builds the `X-CC-Signature` value.
+
+## Also handled
+
+- **Retries:** network errors, 429 and 5xx responses are retried with backoff.
+- **Errors:** a bad token, a bad signature or a malformed event raises `CoConnectError`.
+- **No dependencies** beyond the standard library.
+
+Keep your token and secret on the server.

{coconnect-1.0.0 → coconnect-1.1.0}/pyproject.toml

@@ -1,14 +1,14 @@
 [build-system]
-requires = ["setuptools>=61"]
+requires = ["setuptools>=77"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "coconnect"
-version = "1.0.0"
+version = "1.1.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" }
+license = "MIT"
 keywords = ["coconnect", "quests", "rewards", "partner", "events"]
 dependencies = []
 

coconnect-1.0.0/PKG-INFO

@@ -1,43 +0,0 @@
-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

@@ -1,34 +0,0 @@
-# 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/PKG-INFO

@@ -1,43 +0,0 @@
-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.