cdp-python-sdk 0.1.0__tar.gz → 0.2.0__tar.gz

{cdp_python_sdk-0.1.0 → cdp_python_sdk-0.2.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: cdp-python-sdk
-Version: 0.1.0
+Version: 0.2.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
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.24.0
 Requires-Dist: pydantic>=2.0.0
@@ -165,6 +165,25 @@ await client.send_email(EmailPayload(
 ))
 ```
 
+#### Attachments
+
+Attach up to 5 files (2 MB decoded in total). Bytes are base64-encoded for you:
+
+```python
+payload = EmailPayload(
+    to="user@example.com",
+    identifiers=Identifiers(id="user-123"),
+    transactional_message_id="INVOICE_EMAIL",
+)
+payload.attach_file("./invoice.pdf")                          # named "invoice.pdf"
+payload.attach("notes.txt", "Plain text content")             # strings are base64-encoded by default
+payload.attach("report.csv", existing_base64, encode=False)   # already base64, sent as-is
+
+await client.send_email(payload)
+```
+
+You can also pass `attachments={"invoice.pdf": "<base64>"}` directly. `send_email` validates attachments before sending: at most 5 files, at most 2 MB decoded in total, filenames without `/`, `\` or `..`, and non-empty base64 content. Invalid attachments raise `CDPValidationError` when `fail_on_exception=True`; otherwise the error is logged and nothing is sent. The content type is inferred from the file extension.
+
 ---
 
 ### Send Push Notification
@@ -197,6 +216,27 @@ await client.send_sms(SmsPayload(
 
 ---
 
+### Send WhatsApp
+
+WhatsApp sends use a saved WhatsApp transactional, so `transactional_message_id` is required.
+
+```python
+from cdp_client import WhatsAppPayload, Identifiers
+
+result = await client.send_whatsapp(WhatsAppPayload(
+    identifiers=Identifiers(id="user-123"),
+    transactional_message_id="ORDER_WHATSAPP",
+    to="+14155551234",                          # Optional: overrides the profile phone number
+    message_data={"order_number": "12345"},     # Available in the template as {{trigger.order_number}}
+))
+```
+
+- **A successful return means the message was queued, not delivered.** Delivery runs asynchronously, so a missing WhatsApp provider, no phone number, or a template rejected by Meta does not fail this call. `result` holds the transactional execution record; keep its id to trace the send.
+- `template_variables` (`{"header": {...}, "body": {...}, "button": {...}}`) sets the template slots from code. Keys must be slot numbers (`"1"`, `"2"`, ...), and values may use Liquid such as `{{customer.first_name}}`. Passing it **replaces all variables saved on the transactional**, so include every section the template needs.
+- Sends are not retried on another gateway host after a read, write, or pool timeout or an HTTP error, because the message may already have been queued. The exceptions are connection failures (including connection timeouts) and the Cloudflare errors 521, 523, 525 and 526, which mean the gateway never received the request.
+
+---
+
 ### 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:
@@ -213,22 +253,25 @@ 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:
+By default (`fail_on_exception=False`) the SDK logs errors and does not raise, so a failed call never crashes your app. Set `fail_on_exception=True` to raise instead:
 
 ```python
-import httpx
+from cdp_client import CDPError, CDPValidationError
+
+config = CDPConfig(cdp_api_key="...", fail_on_exception=True)
+client = CDPClient(config)
 
 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}")
+except CDPValidationError as e:
+    # Invalid input, caught before any request is sent
+    print(f"Invalid {e.field}: {e}")
+except CDPError as e:
+    # status_code is the HTTP status, or None when the gateway could not be reached
+    print(f"API error {e.status_code}: {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.
+> This applies to all methods (`identify`, `track`, `send_email`, `send_push`, `send_sms`, `send_whatsapp`, `register_device`). Dual-write Customer.io errors are non-fatal and only emit a warning log.
 
 ---
 

{cdp_python_sdk-0.1.0 → cdp_python_sdk-0.2.0}/README.md

@@ -147,6 +147,25 @@ await client.send_email(EmailPayload(
 ))
 ```
 
+#### Attachments
+
+Attach up to 5 files (2 MB decoded in total). Bytes are base64-encoded for you:
+
+```python
+payload = EmailPayload(
+    to="user@example.com",
+    identifiers=Identifiers(id="user-123"),
+    transactional_message_id="INVOICE_EMAIL",
+)
+payload.attach_file("./invoice.pdf")                          # named "invoice.pdf"
+payload.attach("notes.txt", "Plain text content")             # strings are base64-encoded by default
+payload.attach("report.csv", existing_base64, encode=False)   # already base64, sent as-is
+
+await client.send_email(payload)
+```
+
+You can also pass `attachments={"invoice.pdf": "<base64>"}` directly. `send_email` validates attachments before sending: at most 5 files, at most 2 MB decoded in total, filenames without `/`, `\` or `..`, and non-empty base64 content. Invalid attachments raise `CDPValidationError` when `fail_on_exception=True`; otherwise the error is logged and nothing is sent. The content type is inferred from the file extension.
+
 ---
 
 ### Send Push Notification
@@ -179,6 +198,27 @@ await client.send_sms(SmsPayload(
 
 ---
 
+### Send WhatsApp
+
+WhatsApp sends use a saved WhatsApp transactional, so `transactional_message_id` is required.
+
+```python
+from cdp_client import WhatsAppPayload, Identifiers
+
+result = await client.send_whatsapp(WhatsAppPayload(
+    identifiers=Identifiers(id="user-123"),
+    transactional_message_id="ORDER_WHATSAPP",
+    to="+14155551234",                          # Optional: overrides the profile phone number
+    message_data={"order_number": "12345"},     # Available in the template as {{trigger.order_number}}
+))
+```
+
+- **A successful return means the message was queued, not delivered.** Delivery runs asynchronously, so a missing WhatsApp provider, no phone number, or a template rejected by Meta does not fail this call. `result` holds the transactional execution record; keep its id to trace the send.
+- `template_variables` (`{"header": {...}, "body": {...}, "button": {...}}`) sets the template slots from code. Keys must be slot numbers (`"1"`, `"2"`, ...), and values may use Liquid such as `{{customer.first_name}}`. Passing it **replaces all variables saved on the transactional**, so include every section the template needs.
+- Sends are not retried on another gateway host after a read, write, or pool timeout or an HTTP error, because the message may already have been queued. The exceptions are connection failures (including connection timeouts) and the Cloudflare errors 521, 523, 525 and 526, which mean the gateway never received the request.
+
+---
+
 ### 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:
@@ -195,22 +235,25 @@ 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:
+By default (`fail_on_exception=False`) the SDK logs errors and does not raise, so a failed call never crashes your app. Set `fail_on_exception=True` to raise instead:
 
 ```python
-import httpx
+from cdp_client import CDPError, CDPValidationError
+
+config = CDPConfig(cdp_api_key="...", fail_on_exception=True)
+client = CDPClient(config)
 
 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}")
+except CDPValidationError as e:
+    # Invalid input, caught before any request is sent
+    print(f"Invalid {e.field}: {e}")
+except CDPError as e:
+    # status_code is the HTTP status, or None when the gateway could not be reached
+    print(f"API error {e.status_code}: {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.
+> This applies to all methods (`identify`, `track`, `send_email`, `send_push`, `send_sms`, `send_whatsapp`, `register_device`). Dual-write Customer.io errors are non-fatal and only emit a warning log.
 
 ---
 

{cdp_python_sdk-0.1.0 → cdp_python_sdk-0.2.0}/cdp_client/__init__.py

@@ -5,8 +5,10 @@ from .models import (
     CustomerIoConfig,
     DeviceRegistrationParameters,
     EmailPayload,
+    Identifiers,
     PushPayload,
     SmsPayload,
+    WhatsAppPayload,
 )
 
 __all__ = [
@@ -17,6 +19,8 @@ __all__ = [
     "CustomerIoConfig",
     "DeviceRegistrationParameters",
     "EmailPayload",
+    "Identifiers",
     "PushPayload",
     "SmsPayload",
+    "WhatsAppPayload",
 ]

{cdp_python_sdk-0.1.0 → cdp_python_sdk-0.2.0}/cdp_client/client.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
-from typing import Any, Dict, Optional
+from typing import Any
 
 import httpx
 from customerio import CustomerIO
@@ -15,11 +15,26 @@ from .models import (
     EmailPayload,
     PushPayload,
     SmsPayload,
+    WhatsAppPayload,
+)
+from .validators import (
+    validate_email_attachments,
+    validate_event_name,
+    validate_identifier,
+    validate_properties,
+    validate_whatsapp_payload,
 )
-from .validators import validate_event_name, validate_identifier, validate_properties
 
 logger = logging.getLogger("CDPClient")
 
+# Cloudflare (in front of the primary host) reports these when it never sent the request to the
+# gateway: 521 refused, 523 unreachable, 525/526 TLS failure. Generic 502/503
+# are excluded because a proxy can return them after the gateway has already queued the message,
+# and 522/524 because Cloudflare may already have sent the request when it timed out.
+_SEND_RETRYABLE_STATUSES = (521, 523, 525, 526)
+# Raised before the request was sent. Read timeouts are excluded: the request may have been accepted.
+_SEND_RETRYABLE_ERRORS = (httpx.ConnectError, httpx.ConnectTimeout)
+
 
 class CDPClient:
     """Client for the OpenCDP Data Gateway with optional Customer.io dual-write."""
@@ -33,7 +48,7 @@ class CDPClient:
         self._timeout = config.timeout_ms / 1000.0
         logger.setLevel(logging.DEBUG if config.debug else logging.INFO)
 
-        self.cio: Optional[CustomerIO] = None
+        self.cio: CustomerIO | None = None
         if self.config.send_to_customer_io and self.config.customer_io:
             try:
                 self.cio = CustomerIO(
@@ -65,34 +80,48 @@ class CDPClient:
         method: str,
         path: str,
         *,
-        json_body: Optional[dict] = None,
+        json_body: dict | None = None,
+        send_safe: bool = False,
     ) -> httpx.Response:
-        last_error: Optional[Exception] = None
+        """With send_safe, only fail over when the host provably never processed the request.
+
+        Message sends are not idempotent: retrying after a read timeout, a redirect, or a 4xx/5xx
+        outside _SEND_RETRYABLE_STATUSES could deliver the same message twice.
+        """
+        last_error: Exception | None = None
         async with httpx.AsyncClient(
             timeout=self._timeout,
             headers=self._headers(),
+            # A followed redirect would turn a failed connection to the redirect target into a
+            # "never reached" error, and failover would deliver the message twice.
+            follow_redirects=False,
         ) 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 send_safe and not isinstance(e, _SEND_RETRYABLE_ERRORS):
+                        raise
                     if self.config.debug:
                         logger.debug("Gateway %s unreachable: %s", base_url, e)
+                    continue
+                if 200 <= response.status_code < 300:
+                    return response
+                last_error = httpx.HTTPStatusError(
+                    f"HTTP {response.status_code}",
+                    request=response.request,
+                    response=response,
+                )
+                if send_safe and response.status_code not in _SEND_RETRYABLE_STATUSES:
+                    raise last_error
+                if self.config.debug:
+                    logger.debug(
+                        "Gateway %s returned %s, trying next host",
+                        base_url,
+                        response.status_code,
+                    )
         assert last_error is not None
         raise last_error
 
@@ -104,7 +133,7 @@ class CDPClient:
             self._handle_error("Ping failed", e)
             return False
 
-    async def identify(self, identifier: str, properties: Optional[Dict[str, Any]] = None) -> None:
+    async def identify(self, identifier: str, properties: dict[str, Any] | None = None) -> None:
         try:
             validated_id = validate_identifier(identifier)
             normalized_props = validate_properties(properties)
@@ -130,7 +159,7 @@ class CDPClient:
         self,
         identifier: str,
         event_name: str,
-        properties: Optional[Dict[str, Any]] = None,
+        properties: dict[str, Any] | None = None,
     ) -> None:
         try:
             validated_id = validate_identifier(identifier)
@@ -192,10 +221,17 @@ class CDPClient:
             self._handle_error("Error registering device", e)
 
     async def send_email(self, payload: EmailPayload) -> None:
+        try:
+            validate_email_attachments(payload.attachments)
+        except CDPValidationError as e:
+            if self.config.fail_on_exception:
+                raise
+            logger.error("Email validation failed: %s", e)
+            return
         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)
+            await self._request("POST", "/v1/send/email", json_body=data, send_safe=True)
         except Exception as e:
             self._handle_error("Error sending email", e)
 
@@ -203,7 +239,7 @@ class CDPClient:
         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)
+            await self._request("POST", "/v1/send/push", json_body=data, send_safe=True)
         except Exception as e:
             self._handle_error("Error sending push", e)
 
@@ -211,10 +247,44 @@ class CDPClient:
         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)
+            await self._request("POST", "/v1/send/sms", json_body=data, send_safe=True)
         except Exception as e:
             self._handle_error("Error sending SMS", e)
 
+    async def send_whatsapp(self, payload: WhatsAppPayload) -> dict[str, Any] | None:
+        """Queue a WhatsApp transactional send.
+
+        Returns the gateway acknowledgement (the transactional execution record). A successful
+        return means the message was queued, not delivered. Returns None on failure unless
+        fail_on_exception is set.
+        """
+        try:
+            validate_whatsapp_payload(payload)
+        except CDPValidationError as e:
+            if self.config.fail_on_exception:
+                raise
+            logger.error("WhatsApp validation failed: %s", e)
+            return None
+        data = payload.model_dump(exclude_none=True)
+        data["transactional_message_id"] = str(payload.transactional_message_id)
+        try:
+            response = await self._request("POST", "/v1/send/whatsapp", json_body=data, send_safe=True)
+            return response.json() if response.content else None
+        except Exception as e:
+            self._handle_error(f"Error sending WhatsApp: {_gateway_message(e)}", e)
+            return None
+
     async def close(self) -> None:
         """No persistent client; kept for API compatibility."""
-        return None
+        return
+
+
+def _gateway_message(exc: Exception) -> str:
+    if isinstance(exc, httpx.HTTPStatusError):
+        try:
+            message = exc.response.json().get("message")
+        except ValueError:
+            message = None
+        if message:
+            return str(message)
+    return str(exc) or type(exc).__name__

{cdp_python_sdk-0.1.0 → cdp_python_sdk-0.2.0}/cdp_client/gateway_urls.py

@@ -2,10 +2,10 @@
 
 from __future__ import annotations
 
-DEFAULT_PRIMARY = "https://api.opencdp.com/gateway/data-gateway"
+DEFAULT_PRIMARY = "https://api.opencdp.io/gateway/data-gateway"
 DEFAULT_FALLBACKS = [
-    "https://api.opencdp.xyz/gateway/data-gateway",
-    "https://api.opencdp.io/gateway/data-gateway",
+    "https://api.open-cdp.com/gateway/data-gateway",
+    "https://api.open-cdp.xyz/gateway/data-gateway",
 ]
 
 
@@ -13,7 +13,7 @@ def normalize_base_url(url: str) -> str:
     trimmed = url.strip()
     if not trimmed:
         return trimmed
-    return trimmed[:-1] if trimmed.endswith("/") else trimmed
+    return trimmed.removesuffix("/")
 
 
 def resolve_all_base_urls(

cdp_python_sdk-0.2.0/cdp_client/models.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import base64
+import logging
+import os
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+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: Literal["us", "eu"] | None = 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: list[str] | None = 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: CustomerIoConfig | None = 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: str | None = None
+    email: str | None = None
+    cdp_id: str | None = None
+
+
+class BaseMessagePayload(BaseModel):
+    identifiers: Identifiers
+    transactional_message_id: str | None = None
+    message_data: dict[str, Any] | None = None
+    send_at: int | None = None
+    send_to_unsubscribed: bool | None = None
+    tracked: bool | None = None
+    disable_css_preprocessing: bool | None = None
+    headers: str | None = None
+    disable_message_retention: bool | None = None
+    queue_draft: bool | None = None
+
+    def check_unsupported_fields(self):
+        unsupported = [
+            "send_at",
+            "send_to_unsubscribed",
+            "tracked",
+            "disable_css_preprocessing",
+            "headers",
+            "disable_message_retention",
+            "queue_draft",
+        ]
+        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_: str | None = Field(None, alias="from")
+    subject: str | None = None
+    body: str | None = None
+    body_plain: str | None = None
+    reply_to: str | None = None
+    # Filename -> base64 content. Max 5 files, 2 MB decoded in total.
+    attachments: dict[str, str] | None = None
+
+    def attach(self, filename: str, data: bytes | str, encode: bool = True) -> None:
+        """Attach a file. Bytes are always base64-encoded; strings are encoded unless encode=False,
+        in which case they must already be base64 (same semantics as customerio's attach)."""
+        if isinstance(data, str):
+            content = base64.b64encode(data.encode()).decode() if encode else data
+        else:
+            content = base64.b64encode(data).decode()
+        if self.attachments is None:
+            self.attachments = {}
+        self.attachments[filename] = content
+
+    def attach_file(self, path: str | os.PathLike[str], filename: str | None = None) -> None:
+        """Read a file from disk and attach it, named after the file unless filename is given."""
+        with open(path, "rb") as f:
+            self.attach(filename or os.path.basename(path), f.read())
+
+
+class PushPayload(BaseMessagePayload):
+    title: str | None = None
+    body: str | None = None
+
+
+class SmsPayload(BaseMessagePayload):
+    to: str | None = None
+    from_: str | None = Field(None, alias="from")
+    body: str | None = None
+
+
+class WhatsAppPayload(BaseModel):
+    """Only the fields the gateway's WhatsApp endpoint accepts; it rejects any other key."""
+
+    identifiers: Identifiers
+    transactional_message_id: str | int
+    to: str | None = None
+    # {"header" | "body" | "button": {"1": value, "2": value, ...}}. Replaces the variables
+    # saved on the transactional entirely when given.
+    template_variables: dict[str, dict[str, Any]] | None = None
+    message_data: dict[str, Any] | None = None
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class DeviceRegistrationParameters(BaseModel):
+    device_id: str = Field(..., alias="deviceId")
+    platform: Literal["android", "ios", "web"]
+    fcm_token: str = Field(..., alias="fcmToken")
+    name: str | None = None
+    os_version: str | None = Field(None, alias="osVersion")
+    model: str | None = None
+    apn_token: str | None = Field(None, alias="apnToken")
+    app_version: str | None = Field(None, alias="appVersion")
+    last_active_at: str | None = None
+    attributes: dict[str, Any] | None = None
+
+    model_config = ConfigDict(populate_by_name=True)

cdp_python_sdk-0.2.0/cdp_client/validators.py

@@ -0,0 +1,119 @@
+"""Input validation — aligned with Flutter SDK rules."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from .errors import CDPValidationError
+
+if TYPE_CHECKING:
+    from .models import WhatsAppPayload
+
+_EMAIL_RE = re.compile(r"^[^\s@]+@[^\s@]+\.[^\s@]+$")
+_PHONE_RE = re.compile(r"^\+?[1-9]\d{1,14}$")
+_SLOT_RE = re.compile(r"^[1-9]\d*$")
+_TEMPLATE_SECTIONS = ("header", "body", "button")
+
+# Mirrors the gateway's limits (backend integrations/email-attachments.ts) so bad input fails before a network call.
+MAX_EMAIL_ATTACHMENTS = 5
+MAX_EMAIL_ATTACHMENTS_DECODED_BYTES = 2 * 1024 * 1024  # 2 MB
+_MAX_EMAIL_ATTACHMENTS_ENCODED_LENGTH = -(-MAX_EMAIL_ATTACHMENTS_DECODED_BYTES // 3) * 4
+# Standard or url-safe alphabet (not both), padding optional, "=" only at the end. Lenient decoders skip invalid
+# characters and anything after padding, so decoding cannot be used to validate.
+_BASE64_RE = re.compile(r"(?:[A-Za-z0-9+/_-]{4})*(?:[A-Za-z0-9+/_-]{2}(?:==)?|[A-Za-z0-9+/_-]{3}=?)?")
+
+
+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
+
+
+def validate_whatsapp_payload(payload: WhatsAppPayload) -> None:
+    identifiers = payload.identifiers
+    provided = [v for v in (identifiers.id, identifiers.email, identifiers.cdp_id) if v not in (None, "")]
+    if len(provided) != 1:
+        raise CDPValidationError(
+            "identifiers must contain exactly one of: id, email, or cdp_id",
+            "identifiers",
+        )
+
+    if payload.transactional_message_id is None or str(payload.transactional_message_id).strip() == "":
+        raise CDPValidationError("transactional_message_id is required", "transactional_message_id")
+
+    if payload.to is not None and not _PHONE_RE.match(payload.to):
+        raise CDPValidationError(
+            "Phone number must be in international format (e.g., +1234567890)",
+            "to",
+        )
+
+    for section, slots in (payload.template_variables or {}).items():
+        if section not in _TEMPLATE_SECTIONS:
+            raise CDPValidationError(
+                "template_variables may only contain header, body, and button",
+                "template_variables",
+            )
+        # The gateway sends parameters by position and drops non-numeric button keys.
+        for slot in slots:
+            if not _SLOT_RE.match(slot):
+                raise CDPValidationError(
+                    f'template_variables.{section} keys must be positional slot numbers ("1", "2", ...), got "{slot}"',
+                    "template_variables",
+                )
+
+
+def validate_email_attachments(attachments: object) -> None:
+    if attachments is None:
+        return
+    if not isinstance(attachments, dict):
+        raise CDPValidationError("attachments must be an object", "attachments")
+    if len(attachments) > MAX_EMAIL_ATTACHMENTS:
+        raise CDPValidationError(
+            f"attachments may contain at most {MAX_EMAIL_ATTACHMENTS} files",
+            "attachments",
+        )
+
+    total_decoded_bytes = 0
+    for filename, content in attachments.items():
+        if not filename or "/" in filename or "\\" in filename or ".." in filename:
+            raise CDPValidationError(f"invalid attachment filename: {filename or '(empty)'}", "attachments")
+        if not isinstance(content, str) or content == "":
+            raise CDPValidationError(f'attachment "{filename}" must be a non-empty base64 string', "attachments")
+        normalized = re.sub(r"\s", "", content)
+        # Check the length before the pattern so oversized content fails fast with the size error.
+        if len(normalized) > _MAX_EMAIL_ATTACHMENTS_ENCODED_LENGTH:
+            raise CDPValidationError(
+                f"attachments decoded size exceeds {MAX_EMAIL_ATTACHMENTS_DECODED_BYTES} bytes (2 MB)",
+                "attachments",
+            )
+        # Mixing "+/" with "-_" is valid in neither the standard nor the url-safe alphabet.
+        mixes_alphabets = bool(re.search(r"[+/]", normalized)) and bool(re.search(r"[-_]", normalized))
+        if not normalized or not _BASE64_RE.fullmatch(normalized) or mixes_alphabets:
+            raise CDPValidationError(f'attachment "{filename}" must be a valid base64 string', "attachments")
+        total_decoded_bytes += len(normalized.rstrip("=")) * 3 // 4
+        if total_decoded_bytes > MAX_EMAIL_ATTACHMENTS_DECODED_BYTES:
+            raise CDPValidationError(
+                f"attachments decoded size exceeds {MAX_EMAIL_ATTACHMENTS_DECODED_BYTES} bytes (2 MB)",
+                "attachments",
+            )

{cdp_python_sdk-0.1.0 → cdp_python_sdk-0.2.0}/cdp_python_sdk.egg-info/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: cdp-python-sdk
-Version: 0.1.0
+Version: 0.2.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
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.24.0
 Requires-Dist: pydantic>=2.0.0
@@ -165,6 +165,25 @@ await client.send_email(EmailPayload(
 ))
 ```
 
+#### Attachments
+
+Attach up to 5 files (2 MB decoded in total). Bytes are base64-encoded for you:
+
+```python
+payload = EmailPayload(
+    to="user@example.com",
+    identifiers=Identifiers(id="user-123"),
+    transactional_message_id="INVOICE_EMAIL",
+)
+payload.attach_file("./invoice.pdf")                          # named "invoice.pdf"
+payload.attach("notes.txt", "Plain text content")             # strings are base64-encoded by default
+payload.attach("report.csv", existing_base64, encode=False)   # already base64, sent as-is
+
+await client.send_email(payload)
+```
+
+You can also pass `attachments={"invoice.pdf": "<base64>"}` directly. `send_email` validates attachments before sending: at most 5 files, at most 2 MB decoded in total, filenames without `/`, `\` or `..`, and non-empty base64 content. Invalid attachments raise `CDPValidationError` when `fail_on_exception=True`; otherwise the error is logged and nothing is sent. The content type is inferred from the file extension.
+
 ---
 
 ### Send Push Notification
@@ -197,6 +216,27 @@ await client.send_sms(SmsPayload(
 
 ---
 
+### Send WhatsApp
+
+WhatsApp sends use a saved WhatsApp transactional, so `transactional_message_id` is required.
+
+```python
+from cdp_client import WhatsAppPayload, Identifiers
+
+result = await client.send_whatsapp(WhatsAppPayload(
+    identifiers=Identifiers(id="user-123"),
+    transactional_message_id="ORDER_WHATSAPP",
+    to="+14155551234",                          # Optional: overrides the profile phone number
+    message_data={"order_number": "12345"},     # Available in the template as {{trigger.order_number}}
+))
+```
+
+- **A successful return means the message was queued, not delivered.** Delivery runs asynchronously, so a missing WhatsApp provider, no phone number, or a template rejected by Meta does not fail this call. `result` holds the transactional execution record; keep its id to trace the send.
+- `template_variables` (`{"header": {...}, "body": {...}, "button": {...}}`) sets the template slots from code. Keys must be slot numbers (`"1"`, `"2"`, ...), and values may use Liquid such as `{{customer.first_name}}`. Passing it **replaces all variables saved on the transactional**, so include every section the template needs.
+- Sends are not retried on another gateway host after a read, write, or pool timeout or an HTTP error, because the message may already have been queued. The exceptions are connection failures (including connection timeouts) and the Cloudflare errors 521, 523, 525 and 526, which mean the gateway never received the request.
+
+---
+
 ### 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:
@@ -213,22 +253,25 @@ 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:
+By default (`fail_on_exception=False`) the SDK logs errors and does not raise, so a failed call never crashes your app. Set `fail_on_exception=True` to raise instead:
 
 ```python
-import httpx
+from cdp_client import CDPError, CDPValidationError
+
+config = CDPConfig(cdp_api_key="...", fail_on_exception=True)
+client = CDPClient(config)
 
 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}")
+except CDPValidationError as e:
+    # Invalid input, caught before any request is sent
+    print(f"Invalid {e.field}: {e}")
+except CDPError as e:
+    # status_code is the HTTP status, or None when the gateway could not be reached
+    print(f"API error {e.status_code}: {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.
+> This applies to all methods (`identify`, `track`, `send_email`, `send_push`, `send_sms`, `send_whatsapp`, `register_device`). Dual-write Customer.io errors are non-fatal and only emit a warning log.
 
 ---
 

{cdp_python_sdk-0.1.0 → cdp_python_sdk-0.2.0}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cdp-python-sdk"
-version = "0.1.0"
+version = "0.2.0"
 description = "A Python client library for Codematic's Customer Data Platform (CDP) with optional Customer.io integration."
 readme = "README.md"
 authors = [{ name = "Codematic Engineering", email = "engineering@codematic.io" }]
 license = "MIT"
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 classifiers = [
     "Programming Language :: Python :: 3",
     "Operating System :: OS Independent",
@@ -34,3 +34,17 @@ exclude = ["tests*", "example*"]
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+exclude = [
+    "example",
+    "main.py",
+    ".venv",
+]
+
+[tool.ruff.lint]
+ignore = [
+    # SDK intentionally catches Exception then uses fail_on_exception / _handle_error
+    "BLE001",
+]

{cdp_python_sdk-0.1.0 → cdp_python_sdk-0.2.0}/setup.py

@@ -1,7 +1,7 @@
-from setuptools import setup, find_packages
+from setuptools import find_packages, setup
 
 setup(
     name="cdp-python-sdk",
-    version="0.1.0",
+    version="0.2.0",
     packages=find_packages(),
 )

cdp_python_sdk-0.1.0/cdp_client/models.py

@@ -1,110 +0,0 @@
-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_python_sdk-0.1.0/cdp_client/validators.py

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