primitivedotdev 1.36.0__tar.gz → 2.0.0__tar.gz

{primitivedotdev-1.36.0 → primitivedotdev-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: primitivedotdev
-Version: 1.36.0
+Version: 2.0.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
@@ -571,6 +571,44 @@ Function scope is available on the generated memory operations with
 `scope_type="function"` and `scope_id=<function-id>`; the id is the function
 UUID, not the function name.
 
+### Searching received mail
+
+`search_emails` calls `GET /emails/search`. Each result carries `thread_id`
+(`None` until the email has been threaded) and `direction`. Pass `thread_id`
+to search one conversation, `prefix=SearchEmailsPrefix.TRUE` to match the last
+word of `q` as a prefix while someone is still typing, and
+`count=SearchEmailsCount.FALSE` to skip the total count when you only need the
+page.
+
+```python
+from primitive.api import create_client
+from primitive.api.api.emails.search_emails import sync as search_emails
+from primitive.api.models.search_emails_count import SearchEmailsCount
+from primitive.api.models.search_emails_include_facets import (
+    SearchEmailsIncludeFacets,
+)
+from primitive.api.models.search_emails_prefix import SearchEmailsPrefix
+
+client = create_client("prim_test")
+page = search_emails(
+    client=client,
+    q="quarterly invoi",
+    prefix=SearchEmailsPrefix.TRUE,
+    count=SearchEmailsCount.FALSE,
+    include_facets=SearchEmailsIncludeFacets.FALSE,
+)
+```
+
+`page.meta.total` is `None` when the request sets `count` to false and an
+`int` otherwise; use `page.meta.cursor` to tell whether another page exists.
+Turning `include_facets` off skips the facet aggregation entirely. Search text
+containing a NUL character is rejected with a 400 validation error.
+
+Upgrading to 2.0: `EmailSearchMeta.total` is now typed `int | None`. It is
+`None` only when the request sets `count=SearchEmailsCount.FALSE`; type-checked
+code that treats it as an `int` needs a `None` check. Search results also gain
+the required `thread_id` and `direction` fields.
+
 ### Payment and interaction webhook events
 
 Webhooks are not email-only. The same endpoint also receives `payment.*` settlement notifications and `interaction.x402.*` events from the x402-over-email flow. The event name is carried in the **`X-Webhook-Event` header** for every family. The body is sent verbatim with no envelope, so it is the header (not a body field) that names the event: an `email.*` body carries `event`, a `payment.*` body carries the name in `type`, and an `interaction.*` body is just `{"interaction": {...}}` with no event/type field at all.
@@ -658,10 +696,16 @@ do not replace the idempotency key or retry as a fresh message to bypass it.
 
 ## Receive events in your process
 
+Event subscriptions require a connected agent credential (an API key starting
+with `pconn_`), and each one receives that agent's own address. An account API
+key is refused with `pull_subscription_requires_agent_connection` before any
+request is made; receive mail with `GET /emails?since=<cursor>&wait=30` or an
+HTTP webhook endpoint instead.
+
 ```python
 from primitive import PrimitiveClient, LocalEvent, EventContext
 
-client = PrimitiveClient(api_key="prim_...")
+client = PrimitiveClient(api_key="pconn_...")
 
 async def receive(event: LocalEvent, context: EventContext) -> None:
     await app.receive(event)  # Accept or enqueue within 30 seconds.

{primitivedotdev-1.36.0 → primitivedotdev-2.0.0}/README.md

@@ -541,6 +541,44 @@ Function scope is available on the generated memory operations with
 `scope_type="function"` and `scope_id=<function-id>`; the id is the function
 UUID, not the function name.
 
+### Searching received mail
+
+`search_emails` calls `GET /emails/search`. Each result carries `thread_id`
+(`None` until the email has been threaded) and `direction`. Pass `thread_id`
+to search one conversation, `prefix=SearchEmailsPrefix.TRUE` to match the last
+word of `q` as a prefix while someone is still typing, and
+`count=SearchEmailsCount.FALSE` to skip the total count when you only need the
+page.
+
+```python
+from primitive.api import create_client
+from primitive.api.api.emails.search_emails import sync as search_emails
+from primitive.api.models.search_emails_count import SearchEmailsCount
+from primitive.api.models.search_emails_include_facets import (
+    SearchEmailsIncludeFacets,
+)
+from primitive.api.models.search_emails_prefix import SearchEmailsPrefix
+
+client = create_client("prim_test")
+page = search_emails(
+    client=client,
+    q="quarterly invoi",
+    prefix=SearchEmailsPrefix.TRUE,
+    count=SearchEmailsCount.FALSE,
+    include_facets=SearchEmailsIncludeFacets.FALSE,
+)
+```
+
+`page.meta.total` is `None` when the request sets `count` to false and an
+`int` otherwise; use `page.meta.cursor` to tell whether another page exists.
+Turning `include_facets` off skips the facet aggregation entirely. Search text
+containing a NUL character is rejected with a 400 validation error.
+
+Upgrading to 2.0: `EmailSearchMeta.total` is now typed `int | None`. It is
+`None` only when the request sets `count=SearchEmailsCount.FALSE`; type-checked
+code that treats it as an `int` needs a `None` check. Search results also gain
+the required `thread_id` and `direction` fields.
+
 ### Payment and interaction webhook events
 
 Webhooks are not email-only. The same endpoint also receives `payment.*` settlement notifications and `interaction.x402.*` events from the x402-over-email flow. The event name is carried in the **`X-Webhook-Event` header** for every family. The body is sent verbatim with no envelope, so it is the header (not a body field) that names the event: an `email.*` body carries `event`, a `payment.*` body carries the name in `type`, and an `interaction.*` body is just `{"interaction": {...}}` with no event/type field at all.
@@ -628,10 +666,16 @@ do not replace the idempotency key or retry as a fresh message to bypass it.
 
 ## Receive events in your process
 
+Event subscriptions require a connected agent credential (an API key starting
+with `pconn_`), and each one receives that agent's own address. An account API
+key is refused with `pull_subscription_requires_agent_connection` before any
+request is made; receive mail with `GET /emails?since=<cursor>&wait=30` or an
+HTTP webhook endpoint instead.
+
 ```python
 from primitive import PrimitiveClient, LocalEvent, EventContext
 
-client = PrimitiveClient(api_key="prim_...")
+client = PrimitiveClient(api_key="pconn_...")
 
 async def receive(event: LocalEvent, context: EventContext) -> None:
     await app.receive(event)  # Accept or enqueue within 30 seconds.

{primitivedotdev-1.36.0 → primitivedotdev-2.0.0}/pyproject.toml

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

{primitivedotdev-1.36.0 → primitivedotdev-2.0.0}/src/primitive/api/api/emails/search_emails.py

@@ -12,8 +12,10 @@ from ...models.email_status import EmailStatus
 from ...models.error_response import ErrorResponse
 from ...models.search_emails_automated import SearchEmailsAutomated
 from ...models.search_emails_awaiting import SearchEmailsAwaiting
+from ...models.search_emails_count import SearchEmailsCount
 from ...models.search_emails_has_attachment import SearchEmailsHasAttachment
 from ...models.search_emails_include_facets import SearchEmailsIncludeFacets
+from ...models.search_emails_prefix import SearchEmailsPrefix
 from ...models.search_emails_response_200 import SearchEmailsResponse200
 from ...models.search_emails_snippet import SearchEmailsSnippet
 from ...models.search_emails_sort import SearchEmailsSort
@@ -46,6 +48,9 @@ def _get_kwargs(
     limit: int | Unset = 50,
     snippet: SearchEmailsSnippet | Unset = SearchEmailsSnippet.TRUE,
     include_facets: SearchEmailsIncludeFacets | Unset = SearchEmailsIncludeFacets.TRUE,
+    thread_id: UUID | Unset = UNSET,
+    prefix: SearchEmailsPrefix | Unset = SearchEmailsPrefix.FALSE,
+    count: SearchEmailsCount | Unset = SearchEmailsCount.TRUE,
 
 ) -> dict[str, Any]:
     
@@ -134,6 +139,23 @@ def _get_kwargs(
 
     params["include_facets"] = json_include_facets
 
+    json_thread_id: str | Unset = UNSET
+    if not isinstance(thread_id, Unset):
+        json_thread_id = str(thread_id)
+    params["thread_id"] = json_thread_id
+
+    json_prefix: str | Unset = UNSET
+    if not isinstance(prefix, Unset):
+        json_prefix = prefix.value
+
+    params["prefix"] = json_prefix
+
+    json_count: str | Unset = UNSET
+    if not isinstance(count, Unset):
+        json_count = count.value
+
+    params["count"] = json_count
+
 
     params = {k: v for k, v in params.items() if v is not UNSET and v is not None}
 
@@ -223,6 +245,9 @@ def sync_detailed(
     limit: int | Unset = 50,
     snippet: SearchEmailsSnippet | Unset = SearchEmailsSnippet.TRUE,
     include_facets: SearchEmailsIncludeFacets | Unset = SearchEmailsIncludeFacets.TRUE,
+    thread_id: UUID | Unset = UNSET,
+    prefix: SearchEmailsPrefix | Unset = SearchEmailsPrefix.FALSE,
+    count: SearchEmailsCount | Unset = SearchEmailsCount.TRUE,
 
 ) -> Response[ErrorResponse | SearchEmailsResponse200]:
     """ Search inbound emails
@@ -239,6 +264,10 @@ def sync_detailed(
     `domain_id`, status, attachment presence, and spam score bounds
     are combined with the text query.
 
+    The text parameters (`q`, `from`, `to`, `subject` and `body`) must not
+    contain a NUL character; a value that does is rejected with a 400
+    validation error.
+
     Connected-agent credentials search only mail received by their own
     address. This applies to results, totals, facets, and every page;
     search filters cannot widen the credential's scope. When
@@ -295,6 +324,9 @@ def sync_detailed(
         snippet (SearchEmailsSnippet | Unset):  Default: SearchEmailsSnippet.TRUE.
         include_facets (SearchEmailsIncludeFacets | Unset):  Default:
             SearchEmailsIncludeFacets.TRUE.
+        thread_id (UUID | Unset):
+        prefix (SearchEmailsPrefix | Unset):  Default: SearchEmailsPrefix.FALSE.
+        count (SearchEmailsCount | Unset):  Default: SearchEmailsCount.TRUE.
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -326,6 +358,9 @@ cursor=cursor,
 limit=limit,
 snippet=snippet,
 include_facets=include_facets,
+thread_id=thread_id,
+prefix=prefix,
+count=count,
 
     )
 
@@ -358,6 +393,9 @@ def sync(
     limit: int | Unset = 50,
     snippet: SearchEmailsSnippet | Unset = SearchEmailsSnippet.TRUE,
     include_facets: SearchEmailsIncludeFacets | Unset = SearchEmailsIncludeFacets.TRUE,
+    thread_id: UUID | Unset = UNSET,
+    prefix: SearchEmailsPrefix | Unset = SearchEmailsPrefix.FALSE,
+    count: SearchEmailsCount | Unset = SearchEmailsCount.TRUE,
 
 ) -> ErrorResponse | SearchEmailsResponse200 | None:
     """ Search inbound emails
@@ -374,6 +412,10 @@ def sync(
     `domain_id`, status, attachment presence, and spam score bounds
     are combined with the text query.
 
+    The text parameters (`q`, `from`, `to`, `subject` and `body`) must not
+    contain a NUL character; a value that does is rejected with a 400
+    validation error.
+
     Connected-agent credentials search only mail received by their own
     address. This applies to results, totals, facets, and every page;
     search filters cannot widen the credential's scope. When
@@ -430,6 +472,9 @@ def sync(
         snippet (SearchEmailsSnippet | Unset):  Default: SearchEmailsSnippet.TRUE.
         include_facets (SearchEmailsIncludeFacets | Unset):  Default:
             SearchEmailsIncludeFacets.TRUE.
+        thread_id (UUID | Unset):
+        prefix (SearchEmailsPrefix | Unset):  Default: SearchEmailsPrefix.FALSE.
+        count (SearchEmailsCount | Unset):  Default: SearchEmailsCount.TRUE.
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -462,6 +507,9 @@ cursor=cursor,
 limit=limit,
 snippet=snippet,
 include_facets=include_facets,
+thread_id=thread_id,
+prefix=prefix,
+count=count,
 
     ).parsed
 
@@ -488,6 +536,9 @@ async def asyncio_detailed(
     limit: int | Unset = 50,
     snippet: SearchEmailsSnippet | Unset = SearchEmailsSnippet.TRUE,
     include_facets: SearchEmailsIncludeFacets | Unset = SearchEmailsIncludeFacets.TRUE,
+    thread_id: UUID | Unset = UNSET,
+    prefix: SearchEmailsPrefix | Unset = SearchEmailsPrefix.FALSE,
+    count: SearchEmailsCount | Unset = SearchEmailsCount.TRUE,
 
 ) -> Response[ErrorResponse | SearchEmailsResponse200]:
     """ Search inbound emails
@@ -504,6 +555,10 @@ async def asyncio_detailed(
     `domain_id`, status, attachment presence, and spam score bounds
     are combined with the text query.
 
+    The text parameters (`q`, `from`, `to`, `subject` and `body`) must not
+    contain a NUL character; a value that does is rejected with a 400
+    validation error.
+
     Connected-agent credentials search only mail received by their own
     address. This applies to results, totals, facets, and every page;
     search filters cannot widen the credential's scope. When
@@ -560,6 +615,9 @@ async def asyncio_detailed(
         snippet (SearchEmailsSnippet | Unset):  Default: SearchEmailsSnippet.TRUE.
         include_facets (SearchEmailsIncludeFacets | Unset):  Default:
             SearchEmailsIncludeFacets.TRUE.
+        thread_id (UUID | Unset):
+        prefix (SearchEmailsPrefix | Unset):  Default: SearchEmailsPrefix.FALSE.
+        count (SearchEmailsCount | Unset):  Default: SearchEmailsCount.TRUE.
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -591,6 +649,9 @@ cursor=cursor,
 limit=limit,
 snippet=snippet,
 include_facets=include_facets,
+thread_id=thread_id,
+prefix=prefix,
+count=count,
 
     )
 
@@ -623,6 +684,9 @@ async def asyncio(
     limit: int | Unset = 50,
     snippet: SearchEmailsSnippet | Unset = SearchEmailsSnippet.TRUE,
     include_facets: SearchEmailsIncludeFacets | Unset = SearchEmailsIncludeFacets.TRUE,
+    thread_id: UUID | Unset = UNSET,
+    prefix: SearchEmailsPrefix | Unset = SearchEmailsPrefix.FALSE,
+    count: SearchEmailsCount | Unset = SearchEmailsCount.TRUE,
 
 ) -> ErrorResponse | SearchEmailsResponse200 | None:
     """ Search inbound emails
@@ -639,6 +703,10 @@ async def asyncio(
     `domain_id`, status, attachment presence, and spam score bounds
     are combined with the text query.
 
+    The text parameters (`q`, `from`, `to`, `subject` and `body`) must not
+    contain a NUL character; a value that does is rejected with a 400
+    validation error.
+
     Connected-agent credentials search only mail received by their own
     address. This applies to results, totals, facets, and every page;
     search filters cannot widen the credential's scope. When
@@ -695,6 +763,9 @@ async def asyncio(
         snippet (SearchEmailsSnippet | Unset):  Default: SearchEmailsSnippet.TRUE.
         include_facets (SearchEmailsIncludeFacets | Unset):  Default:
             SearchEmailsIncludeFacets.TRUE.
+        thread_id (UUID | Unset):
+        prefix (SearchEmailsPrefix | Unset):  Default: SearchEmailsPrefix.FALSE.
+        count (SearchEmailsCount | Unset):  Default: SearchEmailsCount.TRUE.
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -727,5 +798,8 @@ cursor=cursor,
 limit=limit,
 snippet=snippet,
 include_facets=include_facets,
+thread_id=thread_id,
+prefix=prefix,
+count=count,
 
     )).parsed

{primitivedotdev-1.36.0 → primitivedotdev-2.0.0}/src/primitive/api/models/__init__.py

@@ -211,6 +211,7 @@ from .email_search_highlights import EmailSearchHighlights
 from .email_search_meta import EmailSearchMeta
 from .email_search_meta_sort import EmailSearchMetaSort
 from .email_search_result import EmailSearchResult
+from .email_search_result_direction import EmailSearchResultDirection
 from .email_status import EmailStatus
 from .email_summary import EmailSummary
 from .email_summary_automation_headers_type_0 import EmailSummaryAutomationHeadersType0
@@ -472,8 +473,10 @@ from .run_wake_schedule_response_200 import RunWakeScheduleResponse200
 from .run_wake_schedule_response_200_data import RunWakeScheduleResponse200Data
 from .search_emails_automated import SearchEmailsAutomated
 from .search_emails_awaiting import SearchEmailsAwaiting
+from .search_emails_count import SearchEmailsCount
 from .search_emails_has_attachment import SearchEmailsHasAttachment
 from .search_emails_include_facets import SearchEmailsIncludeFacets
+from .search_emails_prefix import SearchEmailsPrefix
 from .search_emails_response_200 import SearchEmailsResponse200
 from .search_emails_snippet import SearchEmailsSnippet
 from .search_emails_sort import SearchEmailsSort
@@ -865,6 +868,7 @@ __all__ = (
     "EmailSearchMeta",
     "EmailSearchMetaSort",
     "EmailSearchResult",
+    "EmailSearchResultDirection",
     "EmailStatus",
     "EmailSummary",
     "EmailSummaryAutomationHeadersType0",
@@ -1126,8 +1130,10 @@ __all__ = (
     "RunWakeScheduleResponse200Data",
     "SearchEmailsAutomated",
     "SearchEmailsAwaiting",
+    "SearchEmailsCount",
     "SearchEmailsHasAttachment",
     "SearchEmailsIncludeFacets",
+    "SearchEmailsPrefix",
     "SearchEmailsResponse200",
     "SearchEmailsSnippet",
     "SearchEmailsSort",

{primitivedotdev-1.36.0 → primitivedotdev-2.0.0}/src/primitive/api/models/email_search_meta.py

@@ -24,14 +24,15 @@ T = TypeVar("T", bound="EmailSearchMeta")
 class EmailSearchMeta:
     """ 
         Attributes:
-            total (int): Total number of matching records, capped when `total_capped` is true.
+            total (int | None): Total number of matching records, capped when `total_capped` is true. Null when the request
+                set `count=false`.
             total_capped (bool): Whether `total` was capped instead of counted exactly.
             limit (int): Page size used for this request.
             cursor (None | str): Cursor for the next search page, or null if no more results.
             sort (EmailSearchMetaSort): Sort mode used for the result page.
      """
 
-    total: int
+    total: int | None
     total_capped: bool
     limit: int
     cursor: None | str
@@ -43,6 +44,7 @@ class EmailSearchMeta:
 
 
     def to_dict(self) -> dict[str, Any]:
+        total: int | None
         total = self.total
 
         total_capped = self.total_capped
@@ -72,7 +74,13 @@ class EmailSearchMeta:
     @classmethod
     def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
         d = dict(src_dict)
-        total = d.pop("total")
+        def _parse_total(data: object) -> int | None:
+            if data is None:
+                return data
+            return cast(int | None, data)
+
+        total = _parse_total(d.pop("total"))
+
 
         total_capped = d.pop("total_capped")
 

{primitivedotdev-1.36.0 → primitivedotdev-2.0.0}/src/primitive/api/models/email_search_result.py

@@ -8,6 +8,7 @@ from attrs import field as _attrs_field
 
 from ..types import UNSET, Unset
 
+from ..models.email_search_result_direction import EmailSearchResultDirection
 from ..models.email_status import EmailStatus
 from ..models.email_summary_awaiting import EmailSummaryAwaiting
 from ..models.email_webhook_status_type_1 import EmailWebhookStatusType1
@@ -129,9 +130,14 @@ class EmailSearchResult:
                 `list_unsubscribe`, `list_id`, `auto_response_suppress`,
                 `failed_recipients`, `report`. Treat an unfamiliar value as a
                 reason added after your client was built.
+            thread_id (None | UUID): The conversation thread this email belongs to, usable with `thread_id` on this endpoint
+                and with `/threads/{id}`. Null until the email has been threaded.
             attachment_count (int): Number of parsed attachments on the email.
             from_known_address (bool): Whether the parsed From address is known to this org from prior authenticated inbound
                 mail.
+            direction (EmailSearchResultDirection): Which side of the conversation the result is on: `inbound` for mail
+                received by the organization, `outbound` for mail it sent. This endpoint currently returns received mail only,
+                so every result is `inbound`.
             message_id (None | str | Unset):
             domain_id (None | Unset | UUID):
             org_id (None | Unset | UUID):
@@ -161,9 +167,6 @@ class EmailSearchResult:
                 is `pending`; it means the email is past ingestion but
                 webhook delivery has not yet begun. Two overlapping uses
                 of the word `pending` for distinct lifecycle phases.
-            thread_id (None | Unset | UUID): Conversation thread this message belongs to. Fetch
-                `/threads/{thread_id}` for the full ordered thread. NULL on
-                messages received before threading was enabled.
             presence_control (None | PresenceControlType0 | Unset):
             automation_headers (EmailSummaryAutomationHeadersType0 | None | Unset): What the message declared about being
                 automated, verbatim:
@@ -216,8 +219,10 @@ class EmailSearchResult:
     awaiting: EmailSummaryAwaiting
     automated: bool
     automated_reasons: list[str]
+    thread_id: None | UUID
     attachment_count: int
     from_known_address: bool
+    direction: EmailSearchResultDirection
     message_id: None | str | Unset = UNSET
     domain_id: None | Unset | UUID = UNSET
     org_id: None | Unset | UUID = UNSET
@@ -225,7 +230,6 @@ class EmailSearchResult:
     spam_score: float | None | Unset = UNSET
     raw_size_bytes: int | None | Unset = UNSET
     webhook_status: EmailWebhookStatusType1 | EmailWebhookStatusType2Type1 | EmailWebhookStatusType3Type1 | None | Unset = UNSET
-    thread_id: None | Unset | UUID = UNSET
     presence_control: None | PresenceControlType0 | Unset = UNSET
     automation_headers: EmailSummaryAutomationHeadersType0 | None | Unset = UNSET
     repeat: EmailSummaryRepeatType0 | None | Unset = UNSET
@@ -280,10 +284,18 @@ class EmailSearchResult:
 
 
 
+        thread_id: None | str
+        if isinstance(self.thread_id, UUID):
+            thread_id = str(self.thread_id)
+        else:
+            thread_id = self.thread_id
+
         attachment_count = self.attachment_count
 
         from_known_address = self.from_known_address
 
+        direction = self.direction.value
+
         message_id: None | str | Unset
         if isinstance(self.message_id, Unset):
             message_id = UNSET
@@ -336,14 +348,6 @@ class EmailSearchResult:
         else:
             webhook_status = self.webhook_status
 
-        thread_id: None | str | Unset
-        if isinstance(self.thread_id, Unset):
-            thread_id = UNSET
-        elif isinstance(self.thread_id, UUID):
-            thread_id = str(self.thread_id)
-        else:
-            thread_id = self.thread_id
-
         presence_control: dict[str, Any] | None | Unset
         if isinstance(self.presence_control, Unset):
             presence_control = UNSET
@@ -411,8 +415,10 @@ class EmailSearchResult:
             "awaiting": awaiting,
             "automated": automated,
             "automated_reasons": automated_reasons,
+            "thread_id": thread_id,
             "attachment_count": attachment_count,
             "from_known_address": from_known_address,
+            "direction": direction,
         })
         if message_id is not UNSET:
             field_dict["message_id"] = message_id
@@ -428,8 +434,6 @@ class EmailSearchResult:
             field_dict["raw_size_bytes"] = raw_size_bytes
         if webhook_status is not UNSET:
             field_dict["webhook_status"] = webhook_status
-        if thread_id is not UNSET:
-            field_dict["thread_id"] = thread_id
         if presence_control is not UNSET:
             field_dict["presence_control"] = presence_control
         if automation_headers is not UNSET:
@@ -521,10 +525,33 @@ class EmailSearchResult:
         automated_reasons = cast(list[str], d.pop("automated_reasons"))
 
 
+        def _parse_thread_id(data: object) -> None | UUID:
+            if data is None:
+                return data
+            try:
+                if not isinstance(data, str):
+                    raise TypeError()
+                thread_id_type_0 = UUID(data)
+
+
+
+                return thread_id_type_0
+            except (TypeError, ValueError, AttributeError, KeyError):
+                pass
+            return cast(None | UUID, data)
+
+        thread_id = _parse_thread_id(d.pop("thread_id"))
+
+
         attachment_count = d.pop("attachment_count")
 
         from_known_address = d.pop("from_known_address")
 
+        direction = EmailSearchResultDirection(d.pop("direction"))
+
+
+
+
         def _parse_message_id(data: object) -> None | str | Unset:
             if data is None:
                 return data
@@ -645,26 +672,6 @@ class EmailSearchResult:
         webhook_status = _parse_webhook_status(d.pop("webhook_status", UNSET))
 
 
-        def _parse_thread_id(data: object) -> None | Unset | UUID:
-            if data is None:
-                return data
-            if isinstance(data, Unset):
-                return data
-            try:
-                if not isinstance(data, str):
-                    raise TypeError()
-                thread_id_type_0 = UUID(data)
-
-
-
-                return thread_id_type_0
-            except (TypeError, ValueError, AttributeError, KeyError):
-                pass
-            return cast(None | Unset | UUID, data)
-
-        thread_id = _parse_thread_id(d.pop("thread_id", UNSET))
-
-
         def _parse_presence_control(data: object) -> None | PresenceControlType0 | Unset:
             if data is None:
                 return data
@@ -787,8 +794,10 @@ class EmailSearchResult:
             awaiting=awaiting,
             automated=automated,
             automated_reasons=automated_reasons,
+            thread_id=thread_id,
             attachment_count=attachment_count,
             from_known_address=from_known_address,
+            direction=direction,
             message_id=message_id,
             domain_id=domain_id,
             org_id=org_id,
@@ -796,7 +805,6 @@ class EmailSearchResult:
             spam_score=spam_score,
             raw_size_bytes=raw_size_bytes,
             webhook_status=webhook_status,
-            thread_id=thread_id,
             presence_control=presence_control,
             automation_headers=automation_headers,
             repeat=repeat,

primitivedotdev-2.0.0/src/primitive/api/models/email_search_result_direction.py

@@ -0,0 +1,8 @@
+from enum import StrEnum
+
+class EmailSearchResultDirection(StrEnum):
+    INBOUND = "inbound"
+    OUTBOUND = "outbound"
+
+    def __str__(self) -> str:
+        return str(self.value)

primitivedotdev-2.0.0/src/primitive/api/models/search_emails_count.py

@@ -0,0 +1,8 @@
+from enum import StrEnum
+
+class SearchEmailsCount(StrEnum):
+    FALSE = "false"
+    TRUE = "true"
+
+    def __str__(self) -> str:
+        return str(self.value)

primitivedotdev-2.0.0/src/primitive/api/models/search_emails_prefix.py

@@ -0,0 +1,8 @@
+from enum import StrEnum
+
+class SearchEmailsPrefix(StrEnum):
+    FALSE = "false"
+    TRUE = "true"
+
+    def __str__(self) -> str:
+        return str(self.value)

{primitivedotdev-1.36.0 → primitivedotdev-2.0.0}/src/primitive/event_receiver.py

@@ -29,9 +29,21 @@ Transport = Literal["websocket", "poll"]
 StatusCallback = Callable[["EventStatus"], None]
 
 
+AGENT_CONNECTION_REQUIRED = "pull_subscription_requires_agent_connection"
+AGENT_CONNECTION_REQUIRED_MESSAGE = (
+    "Event subscriptions require a connected agent credential (an API key starting with"
+    " pconn_), which limits them to one address. With an account API key, receive mail"
+    " with GET /emails?since=<cursor>&wait=30 or an HTTP webhook endpoint instead."
+)
+
+
 class EventReceiverError(Exception):
     def __init__(self, code: str, status: int = 0, retry_after: float = 0) -> None:
-        super().__init__(f"Event receiver failed ({code}, HTTP {status})")
+        super().__init__(
+            AGENT_CONNECTION_REQUIRED_MESSAGE
+            if code == AGENT_CONNECTION_REQUIRED
+            else f"Event receiver failed ({code}, HTTP {status})"
+        )
         self.code, self.status, self.retry_after = code, status, retry_after
 
 
@@ -514,6 +526,11 @@ class EventsResource:
         on_status: StatusCallback | None,
         on_gap: Literal["report", "error"],
     ) -> _Connection:
+        # Only connected-agent credentials can create subscriptions. Refuse an
+        # account key here instead of spending a request on the same answer.
+        token = self._client.token
+        if token and not token.startswith("pconn_"):
+            raise EventReceiverError(AGENT_CONNECTION_REQUIRED, 403)
         connection = _Connection(
             self._client.get_async_httpx_client(),
             self._client.token,