cmp-consent 0.1.1__tar.gz

cmp_consent-0.1.1/.gitignore

@@ -0,0 +1,46 @@
+# Secrets — NEVER commit
+.env
+*.env
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+
+# Build artifacts (python-sdk wheels/sdists)
+# dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Virtual env / uv
+.venv/
+venv/
+.venv-*/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Logs
+*.log
+
+# web
+pnpm-lock.yaml
+pnpm-workspace.yaml
+
+# Claude
+.claude/
+.superpowers/
+docs/
+CLAUDE.md
+package-lock.json
+# package lock (per request)
+web/package-lock.json
+.agents/
+plans/
+skills-lock.json

cmp_consent-0.1.1/INTEGRATION.md

@@ -0,0 +1,628 @@
+# cmp-consent — Developer Integration Guide
+
+A hands-on guide to integrating the **CMP Python SDK** into your website's backend.
+Written for a developer who has never seen this SDK before. By the end you will
+have installed it, raised a consent request, received the outcome, and gated your
+own code on it.
+
+> **Scope.** This is the **server-to-server** SDK. It runs inside *your backend*
+> and holds your API key. It is **not** for the browser — never ship the key or
+> call these endpoints from frontend JavaScript. (The browser cookie-banner is a
+> different SDK, `sdk/cmp.js`.)
+
+---
+
+## Contents
+
+1. [The one-paragraph mental model](#1-the-one-paragraph-mental-model)
+2. [What you need before you start](#2-what-you-need-before-you-start)
+3. [Install (local, for now)](#3-install-local-for-now)
+4. [Configure the client](#4-configure-the-client)
+5. [The full API surface](#5-the-full-api-surface)
+6. [The integration, step by step](#6-the-integration-step-by-step)
+7. [Receiving the outcome — webhooks](#7-receiving-the-outcome--webhooks)
+8. [Error handling — the exception model](#8-error-handling--the-exception-model)
+9. [Async version](#9-async-version)
+10. [Framework snippets (Flask / FastAPI / Django)](#10-framework-snippets)
+11. [Testing without a live person](#11-testing-without-a-live-person)
+12. [Field & value reference](#12-field--value-reference)
+13. [FAQ / troubleshooting](#13-faq--troubleshooting)
+
+---
+
+## 1. The one-paragraph mental model
+
+Your staff member (an **officer**) submits a person's email. You call the SDK to
+**raise a consent request** — CMP emails that person a secure link and gives you
+back a `consent_id` immediately. You store that `consent_id` against your record.
+Later the person clicks the link and **accepts or declines** on a CMP-hosted page.
+CMP tells you the outcome via a **webhook**. From then on, every single time your
+code is about to *use* that person's data, you call **`verify()`** — "am I still
+allowed?" — and only proceed if the answer is yes. `verify()` is **fail-closed**:
+if anything goes wrong (network, timeout, unknown consent) it says *no*, so you
+never process data on an uncertain answer.
+
+```
+ officer submits ──► create_consent_request() ──► store consent_id (t=0)
+                                                        │
+ person clicks email link ──► accepts/declines ──► webhook ──► verify_webhook()
+                                                        │
+ before ANY use of the data ──► verify(consent_id, purpose) ──► proceed only if allowed
+```
+
+---
+
+## 2. What you need before you start
+
+From your CMP admin console (or from whoever operates the CMP), collect:
+
+| Thing | Looks like | Where used |
+|---|---|---|
+| **API base URL** | `https://cmp-api.yourdomain` (or `http://localhost:8000` locally) | `CMPClient(api_base=…)` |
+| **Application API key** | `cmpk_live_…` | `CMPClient(api_key=…)` — sent as `X-API-Key` |
+| **Notice key** | `kyc-notice` | passed to `create_consent_request(notice=…)` |
+| **Purpose code(s)** | `bureau_pull` | passed to `verify(purpose=…)` |
+| **Webhook secret** | `whsec_…` | `CMPClient(webhook_secret=…)` — verifies inbound webhooks |
+
+The API key and webhook secret are **secrets** — keep them in environment
+variables / your secrets manager, never in code or git.
+
+You also need the **CMP API running and reachable** from your backend, and its
+background **worker running** (that's what sends the email — if it's down, you'll
+get a `consent_id` but the person never receives a link).
+
+---
+
+## 3. Install (local, for now)
+
+The package is not on PyPI yet, so install the pre-built wheel straight from disk.
+The wheel lives in `python-sdk/dist/`:
+
+```bash
+# from your website's project, with its virtualenv active
+pip install "D:/consent-management-platform/python-sdk/dist/cmp_consent-0.1.0-py3-none-any.whl"
+```
+
+Using `uv`:
+
+```bash
+uv pip install "D:/consent-management-platform/python-sdk/dist/cmp_consent-0.1.0-py3-none-any.whl"
+```
+
+> **If the wheel isn't there**, build it first:
+> ```bash
+> cd D:/consent-management-platform/python-sdk
+> rm -rf dist/ && uv build      # produces dist/cmp_consent-0.1.0-py3-none-any.whl
+> ```
+
+**Developing the SDK at the same time?** Use an editable install instead — your
+edits to the SDK source are picked up with no rebuild:
+
+```bash
+uv pip install -e "D:/consent-management-platform/python-sdk"
+```
+
+Verify it imported:
+
+```bash
+python -c "import cmp_consent; print(cmp_consent.__version__)"   # → 0.1.0
+```
+
+Requirements: **Python 3.9+**. `httpx` and `pydantic` install automatically.
+
+> Package name vs import name: you install **`cmp-consent`** (hyphen) but import
+> **`cmp_consent`** (underscore). That's normal Python.
+
+---
+
+## 4. Configure the client
+
+Create **one** client at startup and reuse it — it holds a pooled HTTP connection.
+
+```python
+import os
+from cmp_consent import CMPClient
+
+cmp = CMPClient(
+    api_base=os.environ["CMP_API_BASE"],          # e.g. https://cmp-api.yourdomain
+    api_key=os.environ["CMP_API_KEY"],            # cmpk_live_…
+    webhook_secret=os.environ["CMP_WEBHOOK_SECRET"],  # whsec_…  (only needed for webhooks)
+    timeout=10.0,     # seconds per request (default 10)
+    retries=2,        # transport-level retries on connection errors (default 2)
+)
+```
+
+| Argument | Required | Default | Notes |
+|---|---|---|---|
+| `api_base` | ✅ | — | Trailing slash is stripped for you |
+| `api_key` | ✅ | — | Sent as `X-API-Key` on every call |
+| `webhook_secret` | only for `verify_webhook()` | `None` | Omit if you never receive webhooks |
+| `timeout` | — | `10.0` | Per-request, seconds |
+| `retries` | — | `2` | Connection-level only (not on 4xx/5xx) |
+
+The client is a context manager if you want deterministic cleanup:
+
+```python
+with CMPClient(api_base=…, api_key=…) as cmp:
+    ...
+# or call cmp.close() yourself
+```
+
+---
+
+## 5. The full API surface
+
+Everything the SDK exposes. Six methods, five models, five exceptions.
+
+### `CMPClient` methods
+
+| Method | Does | Returns | Raises |
+|---|---|---|---|
+| `create_consent_request(*, email, notice, requested_by, idempotency_key=None, link_expire_seconds=None)` | Raise a PENDING request; CMP emails the link | `ConsentRequest` | `CMPError` on HTTP/network failure |
+| `get_request(request_id)` | Poll a request's status | `RequestStatus` | `CMPError` |
+| `cancel(request_id)` | Cancel a pending request (idempotent) | `dict` | `CMPError` |
+| `resend(request_id)` | Re-mint a fresh magic link | `dict` | `CMPError` |
+| `verify(*, consent_id, purpose)` | **The gate.** May I process this now? | `VerifyResult` | **never raises** (fail-closed → `allowed=False`) |
+| `require_consent(*, consent_id, purpose)` | Like `verify()` but raises when not allowed | `VerifyResult` | `ConsentPending` / `ConsentDeclined` / `ConsentExpired` |
+| `verify_webhook(headers, body)` | Validate an inbound webhook signature | `WebhookEvent` | `SignatureError`, `CMPError` |
+
+All keyword arguments marked `*,` are **keyword-only** — you must name them
+(`create_consent_request(email=…, notice=…)`, not positionally).
+
+### Models (all Pydantic v2)
+
+- **`ConsentRequest`** — `consent_id`, `request_id`, `status`, `request_ref`, `magic_link` (usually `None`).
+- **`RequestStatus`** — `request_id`, `consent_id`, `status`.
+- **`VerifyResult`** — `allowed` (bool — the only thing to branch on), `status`, `purpose`, `purpose_state`, `reason`, `consent_record_id`, `integrity_hash`, `consent_seq`, `needs_reconsent`, `expires_at`.
+- **`WebhookEvent`** — `event_id`, `event_type`, `application_id`, `occurred_at`, `data`; plus convenience properties: `.type`, `.consent_id`, `.request_id`, `.consent_seq`, `.decision`, `.granted_purposes`, `.denied_purposes`.
+
+Value tables (what each `status`/`reason` can be) are in [§12](#12-field--value-reference).
+
+---
+
+## 6. The integration, step by step
+
+### Step 1 — Officer raises the request
+
+When your officer submits the person's details:
+
+```python
+req = cmp.create_consent_request(
+    email="user@example.com",
+    notice="kyc-notice",               # exactly one notice key
+    requested_by="officer-42",         # your officer's id — recorded for audit
+    idempotency_key="loan-9931",       # optional but recommended (see below)
+    link_expire_seconds=1800,          # optional; overrides the default link lifetime
+)
+
+# STORE consent_id NOW — before the person has decided anything.
+save_to_your_db(record_id, consent_id=req.consent_id, request_id=req.request_id)
+```
+
+What comes back (`ConsentRequest`):
+
+| Field | Use |
+|---|---|
+| `consent_id` | **The durable key.** Store it against your record forever — it's how you tie your data to the eventual decision and how you call `verify()` later. |
+| `request_id` | This attempt — use it to `get_request()`, `cancel()`, `resend()`. |
+| `status` | `PENDING` on a fresh request. |
+| `request_ref` | Human-readable reference for support/audit. |
+| `magic_link` | Usually `None`. Only populated if the application is configured in "return link" mode (you send the email yourself). |
+
+**Idempotency.** Pass a stable `idempotency_key` (your loan/application id is
+perfect). If a network blip makes you retry, the same key returns the **same**
+request instead of emailing the person twice.
+
+**If your own save fails** after raising the request, call `cmp.cancel(req.request_id)`
+so no orphaned request stays pending.
+
+### Step 2 — The person decides (nothing to build)
+
+CMP hosts this entirely. The person gets a branded email, opens the link, sees the
+purposes and a per-purpose toggle, and clicks **Accept** or **Decline**. You don't
+build any of it. Two timers matter:
+
+- **Link lifetime** — default 30 min (configurable 5 min–24 h, or per-request via `link_expire_seconds`). If it expires but the request window is still open, `resend()` a fresh link.
+- **Request window** — the request stays `PENDING` for days until decided or expired.
+
+### Step 3 — Learn the outcome (webhook)
+
+The person may decide seconds or days later, so you're notified via a webhook — see
+[§7](#7-receiving-the-outcome--webhooks). (You can also poll `get_request()` as a
+fallback.)
+
+### Step 4 — Gate every use of the data
+
+This is the part that actually enforces consent. **Before any code path that uses
+the person's data**, gate it:
+
+```python
+res = cmp.verify(consent_id=stored_consent_id, purpose="bureau_pull")
+if res.allowed:
+    pull_credit_bureau(...)             # safe — consent-backed
+    log_audit(proof=res.integrity_hash) # keep the proof
+else:
+    # res.reason tells you WHY (CONSENT_PENDING, PURPOSE_OPTED_OUT, …)
+    skip_and_notify(res.reason)
+```
+
+`verify()` **never raises** — on any error it returns `allowed=False` with
+`reason="VERIFY_UNAVAILABLE"`. That's deliberate: a network outage must never
+accidentally permit processing.
+
+If you'd rather have unconsented processing be *impossible* (raise instead of
+branch), use `require_consent()`:
+
+```python
+from cmp_consent import ConsentPending, ConsentDeclined, ConsentExpired
+
+try:
+    cmp.require_consent(consent_id=stored_consent_id, purpose="bureau_pull")
+    pull_credit_bureau(...)             # only reached when allowed
+except ConsentPending:
+    ...   # not decided yet — try later
+except ConsentDeclined:
+    ...   # declined/withdrawn — stop, don't retry
+except ConsentExpired:
+    ...   # needs a fresh request / re-consent
+```
+
+Managing an in-flight request:
+
+```python
+cmp.get_request(req.request_id)   # → RequestStatus(status="PENDING" | "GRANTED" | …)
+cmp.resend(req.request_id)        # re-mint an expired link
+cmp.cancel(req.request_id)        # cancel a pending request
+```
+
+---
+
+## 7. Receiving the outcome — webhooks
+
+CMP POSTs a JSON event to an endpoint you host. You must **verify the signature over
+the raw request body** and then act on it.
+
+### The delivered event
+
+Body (verified against the server envelope):
+
+```json
+{
+  "event_id": "b2c8…",
+  "event_type": "CONSENT_GRANTED",
+  "application_id": "a1…",
+  "occurred_at": "2026-07-24T10:15:00+00:00",
+  "data": {
+    "consent_id": "c9…",
+    "request_id": "r7…",
+    "decision": "FULL",
+    "granted_purposes": ["bureau_pull", "kyc_store"],
+    "denied_purposes": [],
+    "purposes": [ { "purpose_code": "bureau_pull", "state": "OPT_IN", … } ],
+    "consent_seq": 3,
+    "integrity_hash": "…"
+  }
+}
+```
+
+Also sent as headers: `X-CMP-Signature`, `X-CMP-Event-Id`, `X-CMP-Event-Type`.
+
+### Event types
+
+| `event_type` | Fired when |
+|---|---|
+| `CONSENT_REQUEST_CREATED` | You raised a request |
+| `CONSENT_GRANTED` | Accepted (fully or partially — see `data.decision`) |
+| `CONSENT_DECLINED` | Declined |
+| `CONSENT_REQUEST_EXPIRED` | The request window elapsed undecided |
+| `CONSENT_WITHDRAWN` | A previously granted consent was withdrawn |
+
+Subscribe to the ones you need in the CMP console.
+
+### Handling it correctly
+
+```python
+from cmp_consent import SignatureError
+
+def handle_cmp_webhook(request):
+    try:
+        # PASS THE RAW BODY BYTES — not a parsed/re-serialized dict.
+        event = cmp.verify_webhook(request.headers, request.get_data())  # Flask: get_data()
+    except SignatureError:
+        return ("bad signature", 400)      # forged or replayed — reject
+
+    # De-dupe: webhooks are at-least-once. Skip if you've seen this event_id.
+    if already_processed(event.event_id):
+        return ("", 200)
+
+    if event.type == "CONSENT_GRANTED":
+        # order updates by consent_seq if you track state transitions
+        mark_consent_granted(event.consent_id,
+                             granted=event.granted_purposes,
+                             seq=event.consent_seq)
+    elif event.type == "CONSENT_DECLINED":
+        mark_consent_declined(event.consent_id)
+
+    remember(event.event_id)
+    return ("", 200)                        # 2xx = delivered; anything else = retried
+```
+
+Three rules that matter:
+
+1. **Verify over the raw bytes.** The signature covers the exact bytes CMP sent. If your framework parsed the body into a dict and you re-serialize it, the signature won't match. Grab the raw body (`request.get_data()` in Flask, `await request.body()` in FastAPI/Starlette, `request.body` in Django).
+2. **De-dupe by `event.event_id`.** Delivery is at-least-once; the same event can arrive twice.
+3. **Treat `verify()` as the source of truth.** Webhooks can arrive out of order or be missed. For any real decision, `verify()` is authoritative — the webhook is just the nudge to re-check.
+
+Return **2xx** to acknowledge. Any other status (or a timeout) makes CMP retry.
+
+---
+
+## 8. Error handling — the exception model
+
+| Exception | Meaning | Base |
+|---|---|---|
+| `CMPError` | Any HTTP 4xx/5xx or network/timeout failure. Carries `.status` (HTTP) and `.code` (envelope code) when available. | `Exception` |
+| `ConsentPending` | Requested but not yet granted — wait. | `CMPError` |
+| `ConsentDeclined` | Declined or withdrawn — stop. | `CMPError` |
+| `ConsentExpired` | Consent/request expired — needs re-consent. | `CMPError` |
+| `SignatureError` | Inbound webhook signature invalid (forged/replayed). | `CMPError` |
+
+Which methods raise what:
+
+- **`create_consent_request`, `get_request`, `cancel`, `resend`** raise `CMPError` on failure. Wrap them:
+  ```python
+  from cmp_consent import CMPError
+  try:
+      req = cmp.create_consent_request(email=e, notice="kyc-notice", requested_by=o)
+  except CMPError as err:
+      log.error("CMP request failed: %s (status=%s code=%s)", err, err.status, err.code)
+  ```
+- **`verify`** never raises — check `res.allowed`.
+- **`require_consent`** raises `ConsentPending` / `ConsentDeclined` / `ConsentExpired` (all subclasses of `CMPError`, so a bare `except CMPError` catches them all).
+- **`verify_webhook`** raises `SignatureError` (bad/missing signature) or `CMPError` (no `webhook_secret` configured).
+
+---
+
+## 9. Async version
+
+If your website is async (FastAPI, Starlette, aiohttp), use `AsyncCMPClient` — same
+surface, awaitable, except `verify_webhook` which stays sync (it does no I/O):
+
+```python
+from cmp_consent import AsyncCMPClient
+
+cmp = AsyncCMPClient(api_base=…, api_key=…, webhook_secret=…)
+
+async def raise_and_gate():
+    req = await cmp.create_consent_request(
+        email="user@example.com", notice="kyc-notice", requested_by="officer-42")
+    res = await cmp.verify(consent_id=req.consent_id, purpose="bureau_pull")
+    return res.allowed
+
+# or scoped:
+async with AsyncCMPClient(api_base=…, api_key=…) as cmp:
+    ...
+# verify_webhook is NOT awaited — it's synchronous:
+event = cmp.verify_webhook(headers, raw_body)
+```
+
+Create it inside the event loop (e.g. FastAPI startup), and `await cmp.aclose()`
+on shutdown.
+
+---
+
+## 10. Framework snippets
+
+The SDK is framework-agnostic. The only framework-specific part is **getting the
+raw webhook body** and **reading headers**.
+
+### Flask
+
+```python
+from flask import Flask, request
+from cmp_consent import CMPClient, SignatureError
+
+app = Flask(__name__)
+cmp = CMPClient(api_base=…, api_key=…, webhook_secret=…)
+
+@app.post("/webhooks/cmp")
+def cmp_webhook():
+    try:
+        event = cmp.verify_webhook(dict(request.headers), request.get_data())
+    except SignatureError:
+        return "", 400
+    # …dedupe + handle…
+    return "", 200
+```
+
+### FastAPI (async)
+
+```python
+from fastapi import FastAPI, Request
+from cmp_consent import AsyncCMPClient, SignatureError
+
+app = FastAPI()
+cmp = AsyncCMPClient(api_base=…, api_key=…, webhook_secret=…)
+
+@app.post("/webhooks/cmp")
+async def cmp_webhook(request: Request):
+    raw = await request.body()                 # RAW bytes — essential
+    try:
+        event = cmp.verify_webhook(request.headers, raw)   # sync, don't await
+    except SignatureError:
+        return Response(status_code=400)
+    # …dedupe + handle…
+    return Response(status_code=200)
+```
+
+### Django
+
+```python
+from django.views.decorators.csrf import csrf_exempt
+from django.http import HttpResponse
+from cmp_consent import CMPClient, SignatureError
+
+cmp = CMPClient(api_base=…, api_key=…, webhook_secret=…)
+
+@csrf_exempt
+def cmp_webhook(request):
+    try:
+        event = cmp.verify_webhook(request.headers, request.body)  # request.body = raw bytes
+    except SignatureError:
+        return HttpResponse(status=400)
+    # …dedupe + handle…
+    return HttpResponse(status=200)
+```
+
+(Exempt the webhook route from CSRF — it's an inbound machine call, authenticated
+by the signature, not a browser form.)
+
+---
+
+## 11. Testing without a live person
+
+You don't need to actually receive an email to test most of this.
+
+**Webhook verification is pure local crypto — no server needed.** You can forge a
+correctly-signed event and prove your handler works:
+
+```python
+import hmac, hashlib, time, json
+from cmp_consent import CMPClient
+
+cmp = CMPClient(api_base="http://localhost:8000", api_key="x", webhook_secret="whsec_test")
+
+body = json.dumps({
+    "event_id": "e1", "event_type": "CONSENT_GRANTED",
+    "application_id": "a1", "occurred_at": "2026-07-24T10:00:00+00:00",
+    "data": {"consent_id": "c1", "decision": "FULL",
+             "granted_purposes": ["bureau_pull"], "consent_seq": 3},
+}).encode()
+
+ts = int(time.time())
+mac = hmac.new(b"whsec_test", f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
+sig = f"t={ts},v1={mac}"
+
+event = cmp.verify_webhook({"X-CMP-Signature": sig}, body)
+assert event.type == "CONSENT_GRANTED"
+assert event.consent_id == "c1"
+assert "bureau_pull" in event.granted_purposes
+print("webhook handling OK")
+```
+
+**For the request/verify calls** you need the CMP API running (point `api_base` at
+`http://localhost:8000`) and a real application API key. Then a full round-trip is:
+
+```python
+req = cmp.create_consent_request(email="you@example.com",
+                                 notice="kyc-notice", requested_by="dev")
+print(req.consent_id, req.status)          # → …  PENDING
+# (accept via the emailed/hosted link, or simulate the decision server-side)
+res = cmp.verify(consent_id=req.consent_id, purpose="bureau_pull")
+print(res.allowed, res.status, res.reason) # → before decision: False PENDING CONSENT_PENDING
+```
+
+A good local smoke test: raise a request, `verify()` **before** deciding (expect
+`allowed=False`, `reason="CONSENT_PENDING"`), then accept and `verify()` again
+(expect `allowed=True`, `reason="OK"`).
+
+---
+
+## 12. Field & value reference
+
+### `VerifyResult.status`
+
+`GRANTED` · `PARTIALLY_GRANTED` · `PENDING` · `DECLINED` · `EXPIRED` · `CANCELLED` ·
+`WITHDRAWN` · `CONSENT_EXPIRED` · `NOT_FOUND` · `UNKNOWN` (SDK-side, on a failed call).
+
+### `VerifyResult.reason` (machine code — safe to branch on)
+
+| `reason` | `allowed` | Meaning |
+|---|---|---|
+| `OK` | ✅ true | Granted for this purpose |
+| `CONSENT_PENDING` | false | Requested, not yet decided |
+| `CONSENT_DECLINED` | false | Person declined |
+| `CONSENT_WITHDRAWN` | false | Previously granted, now withdrawn |
+| `CONSENT_EXPIRED` | false | Consent expired (`needs_reconsent=True`) |
+| `REQUEST_EXPIRED` | false | Request window elapsed |
+| `REQUEST_CANCELLED` | false | Request cancelled/superseded |
+| `PURPOSE_OPTED_OUT` | false | Consent exists but this purpose is opted out |
+| `PURPOSE_NOT_PRESENTED` | false | This purpose wasn't part of the notice |
+| `NOT_FOUND` | false | Unknown `consent_id` |
+| `VERIFY_UNAVAILABLE` | false | The call to CMP failed (network/timeout) — **fail-closed** |
+
+### `VerifyResult.purpose_state`
+
+`OPT_IN` · `OPT_OUT` · `NOT_PRESENTED`.
+
+### `RequestStatus.status`
+
+`PENDING` · `GRANTED` · `PARTIALLY_GRANTED` · `DECLINED` · `EXPIRED` · `CANCELLED` · `SUPERSEDED`.
+
+### Fields set only when `allowed=True`
+
+`consent_record_id` and `integrity_hash` — keep the `integrity_hash` as your
+audit proof that processing was consent-backed at that moment.
+
+---
+
+## 13. FAQ / troubleshooting
+
+**`ModuleNotFoundError: No module named 'cmp_consent'`**
+You installed the wrong name or into a different venv. Install `cmp-consent`
+(hyphen), import `cmp_consent` (underscore), and make sure it's the same
+interpreter running your app.
+
+**`verify()` always returns `allowed=False`, `reason="VERIFY_UNAVAILABLE"`**
+The call never reached CMP. Check `api_base` (right host/port/scheme), the API key,
+and network/TLS. This is fail-closed doing its job — it's not a consent problem.
+
+**Webhook always fails with `SignatureError`**
+Almost always you passed a parsed/re-serialized body instead of the **raw bytes**.
+Use `request.get_data()` (Flask) / `await request.body()` (FastAPI) / `request.body`
+(Django). Second most common: clock skew > 5 min on your server — fix NTP.
+
+**`CMPError: verify_webhook requires webhook_secret at construction`**
+You called `verify_webhook` but built the client without `webhook_secret=…`. Add it.
+
+**The person never got the email**
+The request was created (you got a `consent_id`) but the CMP **worker** that sends
+email is down, or email mode is `return_link` (then `req.magic_link` is populated
+and *you* send it). Check with the CMP operator.
+
+**Should I create a `CMPClient` per request?**
+No. Create one at startup and reuse it — it pools connections. Create per-request
+only if you have a strong reason.
+
+**Can I call this from my frontend / browser?**
+No. It holds your API key. All calls are server-to-server. The browser has its own
+separate SDK.
+
+---
+
+## Appendix — copy-paste starter
+
+```python
+import os
+from cmp_consent import CMPClient, CMPError, ConsentPending, ConsentDeclined, ConsentExpired
+
+cmp = CMPClient(
+    api_base=os.environ["CMP_API_BASE"],
+    api_key=os.environ["CMP_API_KEY"],
+    webhook_secret=os.environ.get("CMP_WEBHOOK_SECRET"),
+)
+
+def start_consent(record_id: str, email: str, officer_id: str) -> str:
+    req = cmp.create_consent_request(
+        email=email, notice="kyc-notice", requested_by=officer_id,
+        idempotency_key=record_id,
+    )
+    save_consent_id(record_id, req.consent_id)      # your DB
+    return req.consent_id
+
+def use_the_data(consent_id: str):
+    res = cmp.verify(consent_id=consent_id, purpose="bureau_pull")
+    if not res.allowed:
+        raise PermissionError(f"consent not granted: {res.reason}")
+    do_the_processing(proof=res.integrity_hash)
+```