Add Policies API support with typed models, client wiring, and expanded test coverage

CHANGELOG.md

@@ -4,6 +4,7 @@ Unreleased
 ----------
 * Added Manage Domains (`Client.domains`, `/v3/admin/domains`): list, create, find, update, delete, `get_info`, and `verify` with models in `nylas.models.domains`; optional `ServiceAccountSigner` (`nylas.handler.service_account`) for service-account headers (`X-Nylas-Kid`, `X-Nylas-Nonce`, `X-Nylas-Timestamp`, `X-Nylas-Signature`) on each `Domains` method; new `cryptography` dependency, RSA signing, and `HttpClient` `serialized_json_body` so signed payloads match the wire body
 * Added Transactional Send: `Client.transactional_send.send()` for `POST /v3/domains/{domain_name}/messages/send`, with `TransactionalSendMessageRequest` and `TransactionalTemplate` models (JSON and multipart send behavior aligned with grant `messages.send`)
+* Added Policies support (`Client.policies`, `/v3/policies`): list, create, find, update, and delete, with typed request/response models in `nylas.models.policies`
 
 v6.14.3
 ----------

nylas/client.py

@@ -15,6 +15,7 @@
 from nylas.resources.drafts import Drafts
 from nylas.resources.domains import Domains
 from nylas.resources.grants import Grants
+from nylas.resources.policies import Policies
 from nylas.resources.scheduler import Scheduler
 from nylas.resources.notetakers import Notetakers
 
@@ -154,6 +155,16 @@ def grants(self) -> Grants:
         """
         return Grants(self.http_client)
 
+    @property
+    def policies(self) -> Policies:
+        """
+        Access the Policies API.
+
+        Returns:
+            The Policies API.
+        """
+        return Policies(self.http_client)
+
     @property
     def messages(self) -> Messages:
         """

nylas/models/auth.py

@@ -7,7 +7,7 @@
 AccessType = Literal["online", "offline"]
 """ Literal for the access type of the authentication URL. """
 
-Provider = Literal["google", "imap", "microsoft", "icloud", "virtual-calendar", "yahoo", "ews", "zoom"]
+Provider = Literal["google", "imap", "microsoft", "icloud", "virtual-calendar", "yahoo", "ews", "zoom", "nylas"]
 """ Literal for the different authentication providers. """
 
 Prompt = Literal[

nylas/models/policies.py

@@ -0,0 +1,118 @@
+from dataclasses import dataclass
+from typing import List, Optional
+
+from dataclasses_json import dataclass_json
+from typing_extensions import NotRequired, TypedDict
+
+from nylas.models.list_query_params import ListQueryParams
+
+
+class ListPoliciesQueryParams(ListQueryParams):
+    """
+    Query parameters for listing policies.
+
+    Attributes:
+        limit: Maximum number of objects to return.
+        page_token: Cursor for the next page (from ``next_cursor`` on the previous response).
+    """
+
+    pass
+
+
+class PolicyOptionsRequest(TypedDict, total=False):
+    """Request shape for policy options."""
+
+    additional_folders: NotRequired[List[str]]
+    use_cidr_aliasing: NotRequired[bool]
+
+
+class PolicyLimitsRequest(TypedDict, total=False):
+    """Request shape for policy limits."""
+
+    limit_attachment_size_limit: NotRequired[int]
+    limit_attachment_count_limit: NotRequired[int]
+    limit_attachment_allowed_types: NotRequired[List[str]]
+    limit_size_total_mime: NotRequired[int]
+    limit_storage_total: NotRequired[int]
+    limit_count_daily_message_per_grant: NotRequired[int]
+    limit_inbox_retention_period: NotRequired[int]
+    limit_spam_retention_period: NotRequired[int]
+
+
+class PolicySpamDetectionRequest(TypedDict, total=False):
+    """Request shape for policy spam detection settings."""
+
+    use_list_dnsbl: NotRequired[bool]
+    use_header_anomaly_detection: NotRequired[bool]
+    spam_sensitivity: NotRequired[float]
+
+
+class CreatePolicyRequest(TypedDict):
+    """Request body for creating a policy."""
+
+    name: str
+    options: NotRequired[PolicyOptionsRequest]
+    limits: NotRequired[PolicyLimitsRequest]
+    rules: NotRequired[List[str]]
+    spam_detection: NotRequired[PolicySpamDetectionRequest]
+
+
+class UpdatePolicyRequest(TypedDict, total=False):
+    """Request body for updating a policy."""
+
+    name: NotRequired[str]
+    options: NotRequired[PolicyOptionsRequest]
+    limits: NotRequired[PolicyLimitsRequest]
+    rules: NotRequired[List[str]]
+    spam_detection: NotRequired[PolicySpamDetectionRequest]
+
+
+@dataclass_json
+@dataclass
+class PolicyOptions:
+    """Policy options applied to inboxes that use this policy."""
+
+    additional_folders: Optional[List[str]] = None
+    use_cidr_aliasing: Optional[bool] = None
+
+
+@dataclass_json
+@dataclass
+class PolicyLimits:
+    """Operational limits applied to inboxes that use this policy."""
+
+    limit_attachment_size_limit: Optional[int] = None
+    limit_attachment_count_limit: Optional[int] = None
+    limit_attachment_allowed_types: Optional[List[str]] = None
+    limit_size_total_mime: Optional[int] = None
+    limit_storage_total: Optional[int] = None
+    limit_count_daily_message_per_grant: Optional[int] = None
+    limit_inbox_retention_period: Optional[int] = None
+    limit_spam_retention_period: Optional[int] = None
+
+
+@dataclass_json
+@dataclass
+class PolicySpamDetection:
+    """Spam detection settings applied to inboxes that use this policy."""
+
+    use_list_dnsbl: Optional[bool] = None
+    use_header_anomaly_detection: Optional[bool] = None
+    spam_sensitivity: Optional[float] = None
+
+
+@dataclass_json
+@dataclass
+class Policy:
+    """A policy for Nylas Agent Accounts."""
+
+    id: Optional[str] = None
+    name: Optional[str] = None
+    application_id: Optional[str] = None
+    organization_id: Optional[str] = None
+    options: Optional[PolicyOptions] = None
+    limits: Optional[PolicyLimits] = None
+    rules: Optional[List[str]] = None
+    spam_detection: Optional[PolicySpamDetection] = None
+    created_at: Optional[int] = None
+    updated_at: Optional[int] = None

nylas/resources/policies.py

@@ -0,0 +1,81 @@
+from nylas.config import RequestOverrides
+from nylas.handler.api_resources import (
+    CreatableApiResource,
+    DestroyableApiResource,
+    FindableApiResource,
+    ListableApiResource,
+    UpdatableApiResource,
+)
+from nylas.models.policies import (
+    CreatePolicyRequest,
+    ListPoliciesQueryParams,
+    Policy,
+    UpdatePolicyRequest,
+)
+from nylas.models.response import DeleteResponse, ListResponse, Response
+
+
+class Policies(
+    ListableApiResource,
+    FindableApiResource,
+    CreatableApiResource,
+    UpdatableApiResource,
+    DestroyableApiResource,
+):
+    """
+    Nylas Policies API.
+
+    Policies define operational configuration for Nylas Agent Accounts.
+    """
+
+    def list(
+        self,
+        query_params: ListPoliciesQueryParams = None,
+        overrides: RequestOverrides = None,
+    ) -> ListResponse[Policy]:
+        return super().list(
+            path="/v3/policies",
+            response_type=Policy,
+            query_params=query_params,
+            overrides=overrides,
+        )
+
+    def create(
+        self,
+        request_body: CreatePolicyRequest,
+        overrides: RequestOverrides = None,
+    ) -> Response[Policy]:
+        return super().create(
+            path="/v3/policies",
+            request_body=request_body,
+            response_type=Policy,
+            overrides=overrides,
+        )
+
+    def find(
+        self, policy_id: str, overrides: RequestOverrides = None
+    ) -> Response[Policy]:
+        return super().find(
+            path=f"/v3/policies/{policy_id}",
+            response_type=Policy,
+            overrides=overrides,
+        )
+
+    def update(
+        self,
+        policy_id: str,
+        request_body: UpdatePolicyRequest,
+        overrides: RequestOverrides = None,
+    ) -> Response[Policy]:
+        return super().update(
+            path=f"/v3/policies/{policy_id}",
+            response_type=Policy,
+            request_body=request_body,
+            method="PUT",
+            overrides=overrides,
+        )
+
+    def destroy(
+        self, policy_id: str, overrides: RequestOverrides = None
+    ) -> DeleteResponse:
+        return super().destroy(path=f"/v3/policies/{policy_id}", overrides=overrides)