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.
