primitivedotdev 2.3.0__tar.gz → 2.4.0__tar.gz

{primitivedotdev-2.3.0 → primitivedotdev-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: primitivedotdev
-Version: 2.3.0
+Version: 2.4.0
 Summary: Official Primitive Python SDK for webhook handling and API access
 Project-URL: Homepage, https://primitive.dev
 Project-URL: Repository, https://github.com/primitivedotdev/sdks
@@ -223,6 +223,34 @@ client.send(
 )
 ```
 
+A send with no idempotency key gets an automatic one: a hash of the request
+content (recipients included) and a fixed 5-minute window. An identical send
+inside one window is not sent again. The result says so: `idempotent_replay`
+is true and `idempotency` names why.
+
+```python
+result = client.send(
+    from_email="support@example.com",
+    to="alice@example.com",
+    subject="Hello",
+    body_text="Hi there",
+)
+if result.idempotency is not None:
+    # Nothing was sent for this call.
+    result.idempotency.key_source  # "auto_content", "explicit" or "function_trigger"
+    result.idempotency.original_sent_email_id  # the send that answered it
+    result.idempotency.original_created_at  # ISO 8601, or None
+    result.idempotency.window_seconds  # 300 for an automatic content key, else None
+```
+
+`key_source` is `explicit` when you passed a key, `auto_content` when the key
+was derived from content, and `function_trigger` for a keyless send made by a
+Function. A keyless reply to an email that already has a reply is also
+answered with that reply; it reports `dedup_reason == "parent_already_replied"`
+and no window. To send the same message again on purpose, pass an
+`idempotency_key` of your own. `idempotency` is `None` on a send that went
+out.
+
 Use `client.with_options(...)` to clone the client with new defaults applied
 to every subsequent call. Per-call kwargs still win over these defaults.
 

{primitivedotdev-2.3.0 → primitivedotdev-2.4.0}/README.md

@@ -193,6 +193,34 @@ client.send(
 )
 ```
 
+A send with no idempotency key gets an automatic one: a hash of the request
+content (recipients included) and a fixed 5-minute window. An identical send
+inside one window is not sent again. The result says so: `idempotent_replay`
+is true and `idempotency` names why.
+
+```python
+result = client.send(
+    from_email="support@example.com",
+    to="alice@example.com",
+    subject="Hello",
+    body_text="Hi there",
+)
+if result.idempotency is not None:
+    # Nothing was sent for this call.
+    result.idempotency.key_source  # "auto_content", "explicit" or "function_trigger"
+    result.idempotency.original_sent_email_id  # the send that answered it
+    result.idempotency.original_created_at  # ISO 8601, or None
+    result.idempotency.window_seconds  # 300 for an automatic content key, else None
+```
+
+`key_source` is `explicit` when you passed a key, `auto_content` when the key
+was derived from content, and `function_trigger` for a keyless send made by a
+Function. A keyless reply to an email that already has a reply is also
+answered with that reply; it reports `dedup_reason == "parent_already_replied"`
+and no window. To send the same message again on purpose, pass an
+`idempotency_key` of your own. `idempotency` is `None` on a send that went
+out.
+
 Use `client.with_options(...)` to clone the client with new defaults applied
 to every subsequent call. Per-call kwargs still win over these defaults.
 

{primitivedotdev-2.3.0 → primitivedotdev-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "primitivedotdev"
-version = "2.3.0"
+version = "2.4.0"
 description = "Official Primitive Python SDK for webhook handling and API access"
 readme = "README.md"
 requires-python = ">=3.11"

{primitivedotdev-2.3.0 → primitivedotdev-2.4.0}/src/primitive/__init__.py

@@ -3,6 +3,8 @@ from .client import (
     PrimitiveClient,
     RateLimit,
     SendAttachment,
+    SendIdempotency,
+    SendIdempotencyKeySource,
     SendResult,
     SendThread,
     client,
@@ -273,6 +275,8 @@ __all__ = [
     "STANDARD_WEBHOOK_SIGNATURE_HEADER",
     "STANDARD_WEBHOOK_TIMESTAMP_HEADER",
     "SendAttachment",
+    "SendIdempotency",
+    "SendIdempotencyKeySource",
     "SendResult",
     "SendThread",
     "VERIFICATION_ERRORS",

{primitivedotdev-2.3.0 → primitivedotdev-2.4.0}/src/primitive/api/models/__init__.py

@@ -501,6 +501,8 @@ from .semantic_search_score_breakdown import SemanticSearchScoreBreakdown
 from .semantic_search_snippet import SemanticSearchSnippet
 from .send_email_response_200 import SendEmailResponse200
 from .send_mail_attachment import SendMailAttachment
+from .send_mail_idempotency_replay import SendMailIdempotencyReplay
+from .send_mail_idempotency_replay_key_source import SendMailIdempotencyReplayKeySource
 from .send_mail_input import SendMailInput
 from .send_mail_payload_ref import SendMailPayloadRef
 from .send_mail_result import SendMailResult
@@ -1161,6 +1163,8 @@ __all__ = (
     "SemanticSearchSnippet",
     "SendEmailResponse200",
     "SendMailAttachment",
+    "SendMailIdempotencyReplay",
+    "SendMailIdempotencyReplayKeySource",
     "SendMailInput",
     "SendMailPayloadRef",
     "SendMailResult",

primitivedotdev-2.4.0/src/primitive/api/models/send_mail_idempotency_replay.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, TypeVar, BinaryIO, TextIO, TYPE_CHECKING, Generator
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+
+from ..types import UNSET, Unset
+
+from ..models.send_mail_idempotency_replay_key_source import SendMailIdempotencyReplayKeySource
+from typing import cast
+from uuid import UUID
+import datetime
+
+
+
+
+
+
+T = TypeVar("T", bound="SendMailIdempotencyReplay")
+
+
+
+@_attrs_define
+class SendMailIdempotencyReplay:
+    """ Present only when the request was answered with an existing send
+    instead of making a new one (`idempotent_replay: true`). Nothing
+    was sent for this request. Says how the idempotency key was
+    derived and which send the request collapsed onto. On the replay
+    of a stored failure the same object is under `error.details`.
+
+        Attributes:
+            replayed (bool): Always `true`. The object is absent on a request that made a send of its own.
+            key_source (SendMailIdempotencyReplayKeySource): `explicit`: the request carried an `Idempotency-Key` header.
+                `auto_content`: no header was sent, so the key was derived
+                from the canonical request content (recipients included) and
+                a fixed 5-minute window; an identical send inside the same
+                window was not sent again. `function_trigger`: no header on a
+                send made by a Function, so the key was derived from the
+                content, the Function and the inbound email (or event) that
+                invoked it.
+            original_sent_email_id (UUID): The send this request collapsed onto. Same value as `id`.
+            original_created_at (datetime.datetime | None): When that send was created.
+            window_seconds (int | None): Length of the content window (300) when an `auto_content`
+                key matched on content. Null for `explicit` and
+                `function_trigger` keys, which have no window, and for a
+                keyless reply matched because its parent already has a reply
+                (`dedup_reason: parent_already_replied`).
+     """
+
+    replayed: bool
+    key_source: SendMailIdempotencyReplayKeySource
+    original_sent_email_id: UUID
+    original_created_at: datetime.datetime | None
+    window_seconds: int | None
+    additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
+
+
+
+
+
+    def to_dict(self) -> dict[str, Any]:
+        replayed = self.replayed
+
+        key_source = self.key_source.value
+
+        original_sent_email_id = str(self.original_sent_email_id)
+
+        original_created_at: None | str
+        if isinstance(self.original_created_at, datetime.datetime):
+            original_created_at = self.original_created_at.isoformat()
+        else:
+            original_created_at = self.original_created_at
+
+        window_seconds: int | None
+        window_seconds = self.window_seconds
+
+
+        field_dict: dict[str, Any] = {}
+        field_dict.update(self.additional_properties)
+        field_dict.update({
+            "replayed": replayed,
+            "key_source": key_source,
+            "original_sent_email_id": original_sent_email_id,
+            "original_created_at": original_created_at,
+            "window_seconds": window_seconds,
+        })
+
+        return field_dict
+
+
+
+    @classmethod
+    def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
+        d = dict(src_dict)
+        replayed = d.pop("replayed")
+
+        key_source = SendMailIdempotencyReplayKeySource(d.pop("key_source"))
+
+
+
+
+        original_sent_email_id = UUID(d.pop("original_sent_email_id"))
+
+
+
+
+        def _parse_original_created_at(data: object) -> datetime.datetime | None:
+            if data is None:
+                return data
+            try:
+                if not isinstance(data, str):
+                    raise TypeError()
+                original_created_at_type_0 = datetime.datetime.fromisoformat(data)
+
+
+
+                return original_created_at_type_0
+            except (TypeError, ValueError, AttributeError, KeyError):
+                pass
+            return cast(datetime.datetime | None, data)
+
+        original_created_at = _parse_original_created_at(d.pop("original_created_at"))
+
+
+        def _parse_window_seconds(data: object) -> int | None:
+            if data is None:
+                return data
+            return cast(int | None, data)
+
+        window_seconds = _parse_window_seconds(d.pop("window_seconds"))
+
+
+        send_mail_idempotency_replay = cls(
+            replayed=replayed,
+            key_source=key_source,
+            original_sent_email_id=original_sent_email_id,
+            original_created_at=original_created_at,
+            window_seconds=window_seconds,
+        )
+
+
+        send_mail_idempotency_replay.additional_properties = d
+        return send_mail_idempotency_replay
+
+    @property
+    def additional_keys(self) -> list[str]:
+        return list(self.additional_properties.keys())
+
+    def __getitem__(self, key: str) -> Any:
+        return self.additional_properties[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.additional_properties[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        del self.additional_properties[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.additional_properties

primitivedotdev-2.4.0/src/primitive/api/models/send_mail_idempotency_replay_key_source.py

@@ -0,0 +1,9 @@
+from enum import StrEnum
+
+class SendMailIdempotencyReplayKeySource(StrEnum):
+    AUTO_CONTENT = "auto_content"
+    EXPLICIT = "explicit"
+    FUNCTION_TRIGGER = "function_trigger"
+
+    def __str__(self) -> str:
+        return str(self.value)

{primitivedotdev-2.3.0 → primitivedotdev-2.4.0}/src/primitive/api/models/send_mail_result.py

@@ -14,6 +14,8 @@ from typing import cast
 from uuid import UUID
 import datetime
 
+if TYPE_CHECKING:
+  from ..models.send_mail_idempotency_replay import SendMailIdempotencyReplay
 
 
 
@@ -108,6 +110,18 @@ class SendMailResult:
                 is true.
             smtp_response_text (str | Unset): SMTP response text from the first downstream delivery outcome when wait is
                 true.
+            dedup_reason (None | str | Unset): Why the response was a replay; null or absent on a fresh
+                send. `content_hash_match`: the idempotency key matched an
+                earlier send. `parent_already_replied`: a reply sent without
+                an `Idempotency-Key` header was matched to the reply its
+                parent email already has. Pass an `Idempotency-Key` to send
+                another reply to the same email.
+            idempotency (SendMailIdempotencyReplay | Unset): Present only when the request was answered with an existing
+                send
+                instead of making a new one (`idempotent_replay: true`). Nothing
+                was sent for this request. Says how the idempotency key was
+                derived and which send the request collapsed onto. On the replay
+                of a stored failure the same object is under `error.details`.
             scheduled_at (datetime.datetime | Unset): Echoed requested execution time on a `scheduled`
                 response. On scheduled creates, nothing is dispatched
                 yet: `queue_id` is null and `accepted` / `rejected` are
@@ -128,6 +142,8 @@ class SendMailResult:
     delivery_status: DeliveryStatus | Unset = UNSET
     smtp_response_code: int | None | Unset = UNSET
     smtp_response_text: str | Unset = UNSET
+    dedup_reason: None | str | Unset = UNSET
+    idempotency: SendMailIdempotencyReplay | Unset = UNSET
     scheduled_at: datetime.datetime | Unset = UNSET
     additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
 
@@ -136,6 +152,7 @@ class SendMailResult:
 
 
     def to_dict(self) -> dict[str, Any]:
+        from ..models.send_mail_idempotency_replay import SendMailIdempotencyReplay # noqa: PLC0415
         id = self.id
 
         status = self.status.value
@@ -178,6 +195,16 @@ class SendMailResult:
 
         smtp_response_text = self.smtp_response_text
 
+        dedup_reason: None | str | Unset
+        if isinstance(self.dedup_reason, Unset):
+            dedup_reason = UNSET
+        else:
+            dedup_reason = self.dedup_reason
+
+        idempotency: dict[str, Any] | Unset = UNSET
+        if not isinstance(self.idempotency, Unset):
+            idempotency = self.idempotency.to_dict()
+
         scheduled_at: str | Unset = UNSET
         if not isinstance(self.scheduled_at, Unset):
             scheduled_at = self.scheduled_at.isoformat()
@@ -205,6 +232,10 @@ class SendMailResult:
             field_dict["smtp_response_code"] = smtp_response_code
         if smtp_response_text is not UNSET:
             field_dict["smtp_response_text"] = smtp_response_text
+        if dedup_reason is not UNSET:
+            field_dict["dedup_reason"] = dedup_reason
+        if idempotency is not UNSET:
+            field_dict["idempotency"] = idempotency
         if scheduled_at is not UNSET:
             field_dict["scheduled_at"] = scheduled_at
 
@@ -214,6 +245,7 @@ class SendMailResult:
 
     @classmethod
     def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
+        from ..models.send_mail_idempotency_replay import SendMailIdempotencyReplay # noqa: PLC0415
         d = dict(src_dict)
         id = d.pop("id")
 
@@ -278,6 +310,26 @@ class SendMailResult:
 
         smtp_response_text = d.pop("smtp_response_text", UNSET)
 
+        def _parse_dedup_reason(data: object) -> None | str | Unset:
+            if data is None:
+                return data
+            if isinstance(data, Unset):
+                return data
+            return cast(None | str | Unset, data)
+
+        dedup_reason = _parse_dedup_reason(d.pop("dedup_reason", UNSET))
+
+
+        _idempotency = d.pop("idempotency", UNSET)
+        idempotency: SendMailIdempotencyReplay | Unset
+        if isinstance(_idempotency,  Unset):
+            idempotency = UNSET
+        else:
+            idempotency = SendMailIdempotencyReplay.from_dict(_idempotency)
+
+
+
+
         _scheduled_at = d.pop("scheduled_at", UNSET)
         scheduled_at: datetime.datetime | Unset
         if isinstance(_scheduled_at,  Unset):
@@ -303,6 +355,8 @@ class SendMailResult:
             delivery_status=delivery_status,
             smtp_response_code=smtp_response_code,
             smtp_response_text=smtp_response_text,
+            dedup_reason=dedup_reason,
+            idempotency=idempotency,
             scheduled_at=scheduled_at,
         )
 

{primitivedotdev-2.3.0 → primitivedotdev-2.4.0}/src/primitive/client.py

@@ -54,6 +54,9 @@ from .api.models.semantic_search_result import (
     SemanticSearchResult as ApiSemanticSearchResult,
 )
 from .api.models.send_email_response_200 import SendEmailResponse200
+from .api.models.send_mail_idempotency_replay import (
+    SendMailIdempotencyReplay as ApiSendMailIdempotencyReplay,
+)
 from .api.models.send_mail_input import SendMailInput as ApiSendMailInput
 from .api.models.send_mail_result import SendMailResult as ApiSendMailResult
 from .api.types import UNSET
@@ -202,6 +205,36 @@ class SendAttachment(_OptionalSendAttachment):
     content_base64: str
 
 
+SendIdempotencyKeySource = Literal["explicit", "auto_content", "function_trigger"]
+
+
+@dataclass(frozen=True)
+class SendIdempotency:
+    """Why a send was answered with an existing send instead of being made.
+
+    Present on ``SendResult`` only when ``idempotent_replay`` is true:
+    nothing was sent for that request.
+    """
+
+    # ``explicit``: the request carried an idempotency key.
+    # ``auto_content``: it carried none, so the API derived one from the
+    # request content (recipients included) and a fixed 5-minute window.
+    # ``function_trigger``: a keyless send made by a Function; the key came
+    # from the content, the Function and the email or event that invoked it.
+    key_source: SendIdempotencyKeySource
+    # The send this request collapsed onto. Same value as ``SendResult.id``.
+    original_sent_email_id: str
+    # When that send was created (ISO 8601).
+    original_created_at: str | None
+    # Length of the content window (300) when an ``auto_content`` key matched
+    # on content. None for ``explicit`` and ``function_trigger`` keys, which
+    # have no window, and for a keyless reply matched because its parent
+    # already has a reply (``dedup_reason == "parent_already_replied"``).
+    window_seconds: int | None
+    # Always True. The object is absent on a request that sent.
+    replayed: bool = True
+
+
 @dataclass(frozen=True)
 class SendResult:
     id: str
@@ -222,6 +255,13 @@ class SendResult:
     # Echoed requested execution time on a ``scheduled`` response
     # (ISO 8601). None on immediate sends.
     scheduled_at: str | None = None
+    # Present only when ``idempotent_replay`` is true. Says how the key that
+    # matched was derived and which earlier send answered this request.
+    idempotency: SendIdempotency | None = None
+    # Why the response was a replay: ``content_hash_match`` (the idempotency
+    # key matched an earlier send) or ``parent_already_replied`` (a keyless
+    # reply to an email that already has a reply). None on a fresh send.
+    dedup_reason: str | None = None
 
 
 @dataclass(frozen=True)
@@ -557,6 +597,22 @@ def _map_send_result(result: ApiSendMailResult) -> SendResult:
         if result.scheduled_at is UNSET
         else cast(Any, result.scheduled_at).isoformat()
     )
+    replay = result.idempotency
+    idempotency: SendIdempotency | None = None
+    if isinstance(replay, ApiSendMailIdempotencyReplay):
+        idempotency = SendIdempotency(
+            key_source=replay.key_source.value,
+            original_sent_email_id=str(replay.original_sent_email_id),
+            original_created_at=(
+                None
+                if replay.original_created_at is None
+                else replay.original_created_at.isoformat()
+            ),
+            window_seconds=replay.window_seconds,
+        )
+    dedup_reason: str | None = (
+        result.dedup_reason if isinstance(result.dedup_reason, str) else None
+    )
     return SendResult(
         id=result.id,
         status=result.status.value,
@@ -567,6 +623,8 @@ def _map_send_result(result: ApiSendMailResult) -> SendResult:
         content_hash=result.content_hash,
         queue_id=queue_id,
         idempotent_replay=result.idempotent_replay,
+        idempotency=idempotency,
+        dedup_reason=dedup_reason,
         delivery_status=delivery_status,
         smtp_response_code=smtp_response_code,
         smtp_response_text=smtp_response_text,
@@ -1251,6 +1309,8 @@ __all__ = [
     "PrimitiveAPIError",
     "PrimitiveClient",
     "SendAttachment",
+    "SendIdempotency",
+    "SendIdempotencyKeySource",
     "SendResult",
     "SendThread",
     "client",

{primitivedotdev-2.3.0 → primitivedotdev-2.4.0}/tests/test_client.py

@@ -342,6 +342,129 @@ def test_send_accepts_display_name_from(monkeypatch: pytest.MonkeyPatch) -> None
     )
 
 
+REPLAYED_SENT_ID = "3f1c0a9e-2b7d-4e5a-9c6f-8d2e1a4b5c6d"
+
+
+def test_send_surfaces_idempotency_when_answered_by_an_earlier_send() -> None:
+    captured: list[httpx.Request] = []
+    client = PrimitiveClient("prim_test", api_base_url_1=BASE_URL, api_base_url_2=BASE_URL)
+    _install_capturing_transport(
+        client,
+        captured,
+        body=_send_response_body(
+            {
+                "idempotent_replay": True,
+                "dedup_reason": "content_hash_match",
+                "idempotency": {
+                    "replayed": True,
+                    "key_source": "auto_content",
+                    "original_sent_email_id": REPLAYED_SENT_ID,
+                    "original_created_at": "2026-10-06T12:00:07.412Z",
+                    "window_seconds": 300,
+                },
+            }
+        ),
+    )
+
+    result = client.send(
+        from_email="support@example.com",
+        to="alice@example.com",
+        subject="Hello",
+        body_text="Hi there",
+    )
+
+    assert result.idempotent_replay is True
+    assert result.dedup_reason == "content_hash_match"
+    assert result.idempotency == primitive.SendIdempotency(
+        key_source="auto_content",
+        original_sent_email_id=REPLAYED_SENT_ID,
+        original_created_at="2026-10-06T12:00:07.412000+00:00",
+        window_seconds=300,
+    )
+    assert result.idempotency is not None and result.idempotency.replayed is True
+
+
+def test_send_reports_no_window_for_parent_dedup_and_explicit_keys() -> None:
+    captured: list[httpx.Request] = []
+    client = PrimitiveClient("prim_test", api_base_url_1=BASE_URL, api_base_url_2=BASE_URL)
+    _install_capturing_transport(
+        client,
+        captured,
+        body=_send_response_body(
+            {
+                "idempotent_replay": True,
+                "dedup_reason": "parent_already_replied",
+                "idempotency": {
+                    "replayed": True,
+                    "key_source": "explicit",
+                    "original_sent_email_id": REPLAYED_SENT_ID,
+                    "original_created_at": None,
+                    "window_seconds": None,
+                },
+            }
+        ),
+    )
+
+    result = client.send(
+        from_email="support@example.com",
+        to="alice@example.com",
+        subject="Hello",
+        body_text="Hi there",
+    )
+
+    assert result.dedup_reason == "parent_already_replied"
+    assert result.idempotency == primitive.SendIdempotency(
+        key_source="explicit",
+        original_sent_email_id=REPLAYED_SENT_ID,
+        original_created_at=None,
+        window_seconds=None,
+    )
+
+
+def test_send_leaves_idempotency_none_on_a_send_that_went_out() -> None:
+    captured: list[httpx.Request] = []
+    client = PrimitiveClient("prim_test", api_base_url_1=BASE_URL, api_base_url_2=BASE_URL)
+    _install_capturing_transport(
+        client, captured, body=_send_response_body({"dedup_reason": None})
+    )
+
+    result = client.send(
+        from_email="support@example.com",
+        to="alice@example.com",
+        subject="Hello",
+        body_text="Hi there",
+    )
+
+    assert result.idempotent_replay is False
+    assert result.idempotency is None
+    assert result.dedup_reason is None
+
+
+def test_send_result_keeps_its_positional_field_order() -> None:
+    """The replay fields are appended, so positional construction is unchanged."""
+    result = primitive.SendResult(
+        "sent-123",
+        "delivered",
+        ["alice@example.com"],
+        [],
+        "idem-123",
+        "req-123",
+        "hash-123",
+        "qid-123",
+        False,
+        "delivered",
+        250,
+        "250 OK",
+        None,
+    )
+
+    assert result.delivery_status == "delivered"
+    assert result.smtp_response_code == 250
+    assert result.smtp_response_text == "250 OK"
+    assert result.idempotency is None
+    assert result.dedup_reason is None
+
+
 def test_send_passes_wait_options_and_idempotency_key() -> None:
     """Per-call options now ride on the httpx.Request headers, set by hook.