cdp-python-sdk 0.1.0__py3-none-any.whl

cdp_client/__init__.py

@@ -0,0 +1,22 @@
+from .client import CDPClient
+from .errors import CDPError, CDPValidationError
+from .models import (
+    CDPConfig,
+    CustomerIoConfig,
+    DeviceRegistrationParameters,
+    EmailPayload,
+    PushPayload,
+    SmsPayload,
+)
+
+__all__ = [
+    "CDPClient",
+    "CDPConfig",
+    "CDPError",
+    "CDPValidationError",
+    "CustomerIoConfig",
+    "DeviceRegistrationParameters",
+    "EmailPayload",
+    "PushPayload",
+    "SmsPayload",
+]

cdp_client/client.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Dict, Optional
+
+import httpx
+from customerio import CustomerIO
+
+from .errors import CDPError, CDPValidationError
+from .gateway_urls import resolve_all_base_urls
+from .models import (
+    CDPConfig,
+    DeviceRegistrationParameters,
+    EmailPayload,
+    PushPayload,
+    SmsPayload,
+)
+from .validators import validate_event_name, validate_identifier, validate_properties
+
+logger = logging.getLogger("CDPClient")
+
+
+class CDPClient:
+    """Client for the OpenCDP Data Gateway with optional Customer.io dual-write."""
+
+    def __init__(self, config: CDPConfig):
+        self.config = config
+        self._base_urls = resolve_all_base_urls(
+            config.cdp_endpoint,
+            config.cdp_fallback_endpoints,
+        )
+        self._timeout = config.timeout_ms / 1000.0
+        logger.setLevel(logging.DEBUG if config.debug else logging.INFO)
+
+        self.cio: Optional[CustomerIO] = None
+        if self.config.send_to_customer_io and self.config.customer_io:
+            try:
+                self.cio = CustomerIO(
+                    site_id=self.config.customer_io.site_id,
+                    api_key=self.config.customer_io.api_key,
+                    region=self.config.customer_io.region,
+                )
+                logger.info("Customer.io integration enabled.")
+            except Exception as e:
+                logger.error("Failed to initialize Customer.io client: %s", e)
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": self.config.cdp_api_key,
+            "Content-Type": "application/json",
+            "User-Agent": "cdp-python-sdk/0.2.0",
+        }
+
+    def _handle_error(self, message: str, exc: Exception) -> None:
+        status_code = None
+        if isinstance(exc, httpx.HTTPStatusError):
+            status_code = exc.response.status_code
+        if self.config.fail_on_exception:
+            raise CDPError(message, status_code) from exc
+        logger.error("%s: %s", message, exc)
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[dict] = None,
+    ) -> httpx.Response:
+        last_error: Optional[Exception] = None
+        async with httpx.AsyncClient(
+            timeout=self._timeout,
+            headers=self._headers(),
+        ) as client:
+            for base_url in self._base_urls:
+                url = f"{base_url}{path}"
+                try:
+                    response = await client.request(method, url, json=json_body)
+                    if 200 <= response.status_code < 300:
+                        return response
+                    last_error = httpx.HTTPStatusError(
+                        f"HTTP {response.status_code}",
+                        request=response.request,
+                        response=response,
+                    )
+                    if self.config.debug:
+                        logger.debug(
+                            "Gateway %s returned %s, trying next host",
+                            base_url,
+                            response.status_code,
+                        )
+                except Exception as e:
+                    last_error = e
+                    if self.config.debug:
+                        logger.debug("Gateway %s unreachable: %s", base_url, e)
+        assert last_error is not None
+        raise last_error
+
+    async def ping(self) -> bool:
+        try:
+            response = await self._request("GET", "/v1/health/ping")
+            return response.status_code == 200
+        except Exception as e:
+            self._handle_error("Ping failed", e)
+            return False
+
+    async def identify(self, identifier: str, properties: Optional[Dict[str, Any]] = None) -> None:
+        try:
+            validated_id = validate_identifier(identifier)
+            normalized_props = validate_properties(properties)
+            await self._request(
+                "POST",
+                "/v1/persons/identify",
+                json_body={"identifier": validated_id, "properties": normalized_props},
+            )
+            if self.cio:
+                await asyncio.to_thread(
+                    self.cio.identify,
+                    id=validated_id,
+                    **normalized_props,
+                )
+        except CDPValidationError:
+            if self.config.fail_on_exception:
+                raise
+            logger.error("Identify validation failed for %s", identifier)
+        except Exception as e:
+            self._handle_error(f"Error identifying user {identifier}", e)
+
+    async def track(
+        self,
+        identifier: str,
+        event_name: str,
+        properties: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        try:
+            validated_id = validate_identifier(identifier)
+            validated_event = validate_event_name(event_name)
+            normalized_props = validate_properties(properties)
+            await self._request(
+                "POST",
+                "/v1/persons/track",
+                json_body={
+                    "identifier": validated_id,
+                    "eventName": validated_event,
+                    "properties": normalized_props,
+                },
+            )
+            if self.cio:
+                await asyncio.to_thread(
+                    self.cio.track,
+                    customer_id=validated_id,
+                    name=validated_event,
+                    **normalized_props,
+                )
+        except CDPValidationError:
+            if self.config.fail_on_exception:
+                raise
+            logger.error("Track validation failed for %s / %s", identifier, event_name)
+        except Exception as e:
+            self._handle_error(f"Error tracking event {event_name}", e)
+
+    async def register_device(
+        self,
+        identifier: str,
+        params: DeviceRegistrationParameters,
+    ) -> None:
+        try:
+            validated_id = validate_identifier(identifier)
+            if self.cio:
+                try:
+                    await asyncio.to_thread(
+                        self.cio.add_device,
+                        customer_id=validated_id,
+                        device_id=params.device_id,
+                        platform=params.platform,
+                        data={
+                            "token": params.fcm_token,
+                            **(params.attributes or {}),
+                        },
+                    )
+                except Exception as e:
+                    logger.warning("Customer.io add_device failed (non-blocking): %s", e)
+
+            body = params.model_dump(by_alias=True, exclude_none=True)
+            body["identifier"] = validated_id
+            await self._request("POST", "/v1/persons/registerDevice", json_body=body)
+        except CDPValidationError:
+            if self.config.fail_on_exception:
+                raise
+            logger.error("Register device validation failed for %s", identifier)
+        except Exception as e:
+            self._handle_error("Error registering device", e)
+
+    async def send_email(self, payload: EmailPayload) -> None:
+        payload.check_unsupported_fields()
+        try:
+            data = payload.model_dump(exclude_none=True, by_alias=True)
+            await self._request("POST", "/v1/send/email", json_body=data)
+        except Exception as e:
+            self._handle_error("Error sending email", e)
+
+    async def send_push(self, payload: PushPayload) -> None:
+        payload.check_unsupported_fields()
+        try:
+            data = payload.model_dump(exclude_none=True, by_alias=True)
+            await self._request("POST", "/v1/send/push", json_body=data)
+        except Exception as e:
+            self._handle_error("Error sending push", e)
+
+    async def send_sms(self, payload: SmsPayload) -> None:
+        payload.check_unsupported_fields()
+        try:
+            data = payload.model_dump(exclude_none=True, by_alias=True)
+            await self._request("POST", "/v1/send/sms", json_body=data)
+        except Exception as e:
+            self._handle_error("Error sending SMS", e)
+
+    async def close(self) -> None:
+        """No persistent client; kept for API compatibility."""
+        return None

cdp_client/errors.py

@@ -0,0 +1,15 @@
+"""Typed SDK errors."""
+
+from __future__ import annotations
+
+
+class CDPError(Exception):
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class CDPValidationError(CDPError):
+    def __init__(self, message: str, field: str | None = None):
+        super().__init__(message)
+        self.field = field

cdp_client/gateway_urls.py

@@ -0,0 +1,40 @@
+"""Gateway URL resolution — matches Flutter CdpGatewayUrls."""
+
+from __future__ import annotations
+
+DEFAULT_PRIMARY = "https://api.opencdp.com/gateway/data-gateway"
+DEFAULT_FALLBACKS = [
+    "https://api.opencdp.xyz/gateway/data-gateway",
+    "https://api.opencdp.io/gateway/data-gateway",
+]
+
+
+def normalize_base_url(url: str) -> str:
+    trimmed = url.strip()
+    if not trimmed:
+        return trimmed
+    return trimmed[:-1] if trimmed.endswith("/") else trimmed
+
+
+def resolve_all_base_urls(
+    primary_override: str | None = None,
+    fallback_overrides: list[str] | None = None,
+) -> list[str]:
+    primary = normalize_base_url(
+        primary_override if primary_override and primary_override.strip() else DEFAULT_PRIMARY
+    )
+    fallbacks = fallback_overrides if fallback_overrides is not None else DEFAULT_FALLBACKS
+    seen: set[str] = set()
+    ordered: list[str] = []
+
+    def add(url: str) -> None:
+        normalized = normalize_base_url(url)
+        if not normalized or normalized in seen:
+            return
+        seen.add(normalized)
+        ordered.append(normalized)
+
+    add(primary)
+    for fallback in fallbacks:
+        add(fallback)
+    return ordered

cdp_client/models.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from typing import Optional, Dict, Any, Literal
+from pydantic import BaseModel, Field, ConfigDict
+import logging
+
+from .gateway_urls import DEFAULT_PRIMARY
+
+logger = logging.getLogger(__name__)
+
+
+class CustomerIoConfig(BaseModel):
+    site_id: str = Field(..., description="Customer.io Site ID")
+    api_key: str = Field(..., description="Customer.io API Key")
+    region: Optional[Literal["us", "eu"]] = Field("us", description="Data center region")
+
+
+class CDPConfig(BaseModel):
+    cdp_api_key: str = Field(..., description="API Key for the CDP")
+    cdp_endpoint: str = Field(
+        DEFAULT_PRIMARY,
+        description="Primary gateway base URL",
+    )
+    cdp_fallback_endpoints: Optional[list[str]] = Field(
+        None,
+        description="Optional fallback gateway base URLs",
+    )
+    timeout_ms: int = Field(10000, description="Request timeout in milliseconds")
+    fail_on_exception: bool = Field(
+        False,
+        description="When true, raise on validation and HTTP errors",
+    )
+    send_to_customer_io: bool = Field(False, description="Enable dual-write to Customer.io")
+    customer_io: Optional[CustomerIoConfig] = Field(None, description="Customer.io configuration")
+    debug: bool = Field(False, description="Enable debug logging")
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+class Identifiers(BaseModel):
+    id: Optional[str] = None
+    email: Optional[str] = None
+    cdp_id: Optional[str] = None
+
+
+class BaseMessagePayload(BaseModel):
+    identifiers: Identifiers
+    transactional_message_id: Optional[str] = None
+    message_data: Optional[Dict[str, Any]] = None
+    send_at: Optional[int] = None
+    send_to_unsubscribed: Optional[bool] = None
+    tracked: Optional[bool] = None
+    disable_css_preprocessing: Optional[bool] = None
+    headers: Optional[str] = None
+    disable_message_retention: Optional[bool] = None
+    queue_draft: Optional[bool] = None
+    attachments: Optional[Dict[str, Any]] = None
+
+    def check_unsupported_fields(self):
+        unsupported = [
+            "send_at",
+            "send_to_unsubscribed",
+            "tracked",
+            "disable_css_preprocessing",
+            "headers",
+            "disable_message_retention",
+            "queue_draft",
+            "attachments",
+        ]
+        found = [field for field in unsupported if getattr(self, field) is not None]
+        if found:
+            logger.warning(
+                "The following fields are not yet supported by the backend and will be ignored: %s",
+                ", ".join(found),
+            )
+
+
+class EmailPayload(BaseMessagePayload):
+    to: str
+    from_: Optional[str] = Field(None, alias="from")
+    subject: Optional[str] = None
+    body: Optional[str] = None
+    body_plain: Optional[str] = None
+    reply_to: Optional[str] = None
+
+
+class PushPayload(BaseMessagePayload):
+    title: Optional[str] = None
+    body: Optional[str] = None
+
+
+class SmsPayload(BaseMessagePayload):
+    to: Optional[str] = None
+    from_: Optional[str] = Field(None, alias="from")
+    body: Optional[str] = None
+
+
+class DeviceRegistrationParameters(BaseModel):
+    device_id: str = Field(..., alias="deviceId")
+    platform: Literal["android", "ios", "web"]
+    fcm_token: str = Field(..., alias="fcmToken")
+    name: Optional[str] = None
+    os_version: Optional[str] = Field(None, alias="osVersion")
+    model: Optional[str] = None
+    apn_token: Optional[str] = Field(None, alias="apnToken")
+    app_version: Optional[str] = Field(None, alias="appVersion")
+    last_active_at: Optional[str] = None
+    attributes: Optional[Dict[str, Any]] = None
+
+    model_config = ConfigDict(populate_by_name=True)

cdp_client/validators.py

@@ -0,0 +1,35 @@
+"""Input validation — aligned with Flutter SDK rules."""
+
+from __future__ import annotations
+
+import re
+
+from .errors import CDPValidationError
+
+_EMAIL_RE = re.compile(r"^[^\s@]+@[^\s@]+\.[^\s@]+$")
+
+
+def validate_identifier(identifier: str) -> str:
+    if identifier is None or str(identifier).strip() == "":
+        raise CDPValidationError("Identifier cannot be empty", "identifier")
+    value = str(identifier).strip()
+    if _EMAIL_RE.match(value):
+        raise CDPValidationError(
+            "Identifier must not be an email address",
+            "identifier",
+        )
+    return value
+
+
+def validate_event_name(event_name: str) -> str:
+    if not event_name or not event_name.strip():
+        raise CDPValidationError("Event name cannot be empty", "eventName")
+    return event_name.strip()
+
+
+def validate_properties(properties: dict | None) -> dict:
+    if properties is None:
+        return {}
+    if not isinstance(properties, dict):
+        raise CDPValidationError("Properties must be a dictionary", "properties")
+    return properties

cdp_python_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,310 @@
+Metadata-Version: 2.4
+Name: cdp-python-sdk
+Version: 0.1.0
+Summary: A Python client library for Codematic's Customer Data Platform (CDP) with optional Customer.io integration.
+Author-email: Codematic Engineering <engineering@codematic.io>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: customerio>=1.1.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+Requires-Dist: pytest-httpx>=0.21.0; extra == "test"
+
+# CDP Python SDK
+
+A Python client library for Codematic's Customer Data Platform (CDP) with optional Customer.io integration.
+
+## Installation
+
+```bash
+pip install cdp-python-sdk
+```
+
+Or via `requirements.txt`:
+
+```
+cdp-python-sdk
+```
+
+## Features
+
+- **Async Support**: Built on `httpx` and `asyncio` for high-performance non-blocking I/O.
+- **Dual-Write**: Optional integration to send data to both CDP and Customer.io simultaneously.
+- **Type Safety**: Uses Pydantic models for request validation.
+- **Transactional Messaging**: Support for Email, Push, and SMS.
+- **Device Registration**: Register devices for push notification targeting.
+
+## Examples
+
+A complete runnable example is available in [`example/`](example/):
+
+```
+example/
+├── main.py       # Full flow: init → identify → track → register_device → email → push → sms
+└── README.md     # How to run
+```
+
+See [`example/README.md`](example/README.md) for run instructions.
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+from cdp_client import CDPClient, CDPConfig
+
+async def main():
+    config = CDPConfig(cdp_api_key="your-cdp-api-key")
+    client = CDPClient(config)
+
+    await client.identify("user-123", {"email": "user@example.com", "name": "Jane"})
+    await client.track("user-123", "signed_up", {"plan": "pro"})
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+## Usage
+
+### Initialization
+
+```python
+import asyncio
+from cdp_client import CDPClient, CDPConfig, CustomerIoConfig
+
+async def main():
+    config = CDPConfig(
+        cdp_api_key="your-cdp-api-key",
+        debug=True,
+        # Optional: enable Customer.io dual-write
+        send_to_customer_io=True,
+        customer_io=CustomerIoConfig(
+            site_id="your-cio-site-id",
+            api_key="your-cio-api-key",
+            region="us"   # "us" or "eu"
+        )
+    )
+    client = CDPClient(config)
+
+    # ... use client ...
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+---
+
+### Identify a User
+
+Associate a user ID with a set of traits (name, email, plan, etc.). Call this on sign-up, login, or whenever user attributes change.
+
+```python
+await client.identify("user-123", {
+    "email": "user@example.com",
+    "name": "Jane Doe",
+    "plan": "premium"
+})
+```
+
+---
+
+### Track an Event
+
+Record a user action or behaviour.
+
+```python
+await client.track("user-123", "purchase_completed", {
+    "amount": 99.99,
+    "currency": "USD",
+    "item_id": "prod-456"
+})
+```
+
+---
+
+### Register a Device
+
+Register a device token for push notification targeting. Call this after you receive a push token from your mobile platform.
+
+```python
+await client.register_device(
+    user_id="user-123",
+    device_id="device-abc",      # Unique device identifier
+    platform="ios",              # "ios", "android", or "web"
+    token="apns-or-fcm-token",
+    attributes={                  # Optional device metadata
+        "app_version": "2.1.0",
+        "os_version": "17.2"
+    }
+)
+```
+
+---
+
+### Send Transactional Email
+
+```python
+from cdp_client import EmailPayload, Identifiers
+
+await client.send_email(EmailPayload(
+    to="user@example.com",
+    identifiers=Identifiers(id="user-123"),
+    transactional_message_id="WELCOME_EMAIL",
+    subject="Welcome!",
+    body="<h1>Thanks for joining!</h1>",
+    body_plain="Thanks for joining!"
+))
+```
+
+---
+
+### Send Push Notification
+
+```python
+from cdp_client import PushPayload, Identifiers
+
+await client.send_push(PushPayload(
+    identifiers=Identifiers(id="user-123"),
+    transactional_message_id="PROMO_PUSH",
+    title="Flash Sale 🔥",
+    body="50% off for the next hour."
+))
+```
+
+---
+
+### Send SMS
+
+```python
+from cdp_client import SmsPayload, Identifiers
+
+await client.send_sms(SmsPayload(
+    identifiers=Identifiers(id="user-123"),
+    to="+14155551234",            # Optional: raw phone number
+    transactional_message_id="OTP_MSG",
+    body="Your one-time code is 881234."
+))
+```
+
+---
+
+### Clear Identity / Logout
+
+To reset the client's user context (e.g., on logout), close the current client and re-initialize without a user session:
+
+```python
+# On user logout: flush pending work and release the HTTP client
+await client.close()
+
+# Re-initialize for anonymous or new user session
+client = CDPClient(config)
+```
+
+---
+
+## Error Handling
+
+By default, the Python SDK raises exceptions on HTTP errors or network failures. Wrap calls in `try/except` to handle them gracefully:
+
+```python
+import httpx
+
+try:
+    await client.identify("user-123", {"email": "user@example.com"})
+except httpx.HTTPStatusError as e:
+    # Server returned 4xx or 5xx
+    print(f"API error {e.response.status_code}: {e.response.text}")
+except Exception as e:
+    # Network error, timeout, etc.
+    print(f"Unexpected error: {e}")
+```
+
+> All methods (`identify`, `track`, `send_email`, `send_push`, `send_sms`, `register_device`) raise on failure. Dual-write Customer.io errors are non-fatal and only emit a warning log.
+
+---
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `cdp_api_key` | `str` | **Required** | Your CDP API Key |
+| `cdp_endpoint` | `str` | Production URL | Custom CDP Gateway URL |
+| `debug` | `bool` | `False` | Enable verbose debug logging |
+| `send_to_customer_io` | `bool` | `False` | Enable dual-write to Customer.io |
+| `customer_io` | `CustomerIoConfig` | `None` | Customer.io integration config (see below) |
+
+### `CustomerIoConfig` Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `site_id` | `str` | Customer.io Site ID |
+| `api_key` | `str` | Customer.io API Key |
+| `region` | `str` | `"us"` (default) or `"eu"` |
+
+---
+
+## Dual-Write to Customer.io
+
+When `send_to_customer_io=True`, all `identify`, `track`, and `register_device` calls are mirrored to Customer.io automatically. Customer.io failures are **non-blocking** — the CDP call succeeds even if the Customer.io call fails.
+
+```python
+config = CDPConfig(
+    cdp_api_key="your-cdp-api-key",
+    send_to_customer_io=True,
+    customer_io=CustomerIoConfig(
+        site_id="cio-site-id",
+        api_key="cio-api-key",
+        region="eu"
+    )
+)
+```
+
+---
+
+## Development
+
+### Setup
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+python -m pip install --upgrade pip setuptools wheel build
+python -m pip install -e ".[test]"
+```
+
+### Run Tests
+
+```bash
+pytest -v
+```
+
+### Building the Package
+
+```bash
+python -m build
+```
+
+This creates files in the `dist/` directory:
+- `cdp_python_sdk-{version}-py3-none-any.whl`
+- `cdp_python_sdk-{version}.tar.gz`
+
+---
+
+## Versioning
+
+Follow [Semantic Versioning](https://semver.org/):
+
+| Bump | When |
+|------|------|
+| **PATCH** `1.0.0 → 1.0.1` | Bug fixes |
+| **MINOR** `1.0.0 → 1.1.0` | New features, backward compatible |
+| **MAJOR** `1.0.0 → 2.0.0` | Breaking API changes |

cdp_python_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+cdp_client/__init__.py,sha256=e5RV_Us_IdqebbQjPynufcM5i41oba0EomvUwJpLxOE,433
+cdp_client/client.py,sha256=wVBufNCh4gDCU1Dlfua0zalC8yfc0QCJ9Ja-j_qEIE4,8275
+cdp_client/errors.py,sha256=a_TmPv2gxKDy3BlgYhgSmQBSvrcTNbXWVMYH6DNLWqg,395
+cdp_client/gateway_urls.py,sha256=08B8Y3OIc48T3KHiHLndD-R8j3tI43YFywd1eyRw6Ek,1184
+cdp_client/models.py,sha256=Egrdq9tugatsJRM_sqv4350XNaleZM2KRsaeFLK-YRQ,3690
+cdp_client/validators.py,sha256=MDjTrEqj-ALkuuDgMZcUZ9mKeueKny2SEgeYetFZelc,1054
+cdp_python_sdk-0.1.0.dist-info/METADATA,sha256=cuDbg7ViwrZ6tlsb6JO-2uqSrcadnl5JSNBCbb0lghU,7495
+cdp_python_sdk-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+cdp_python_sdk-0.1.0.dist-info/top_level.txt,sha256=jB1SkK6Q3zW7mSoeDfKRHQM2UZCUkDzD5A4TfJrOkZs,11
+cdp_python_sdk-0.1.0.dist-info/RECORD,,

cdp_python_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cdp_python_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cdp_client