TW-5372 Add application and workspace admin APIs

Author: AaronDDM

CHANGELOG.md

@@ -27,6 +27,15 @@ v6.14.1
 ----------
 * Fix attachment id to not be a requirement
 
+Unreleased
+----------
+* Added Policies resource (`client.policies`) with `list`, `find`, `create`, `update` (PUT), and `destroy`
+* Added Rules resource (`client.rules`) with `list`, `find`, `create`, `update` (PUT), `destroy`, and `list_evaluations` (per-grant rule evaluations)
+* Added Workspaces resource (`client.workspaces`) with `list`, `find`, `create`, `update` (PATCH), `destroy`, `auto_group`, and `manual_assign`
+* Added Manage Domains resource (`client.domains`) with `list`, `find`, `create`, `update` (PUT), `destroy`, `info`, and `verify` against `/v3/admin/domains`
+* Corrected RedirectUris `update` to use PATCH instead of PUT; added `deleted_at` to the RedirectUri model and made `platform` optional on create
+* Verified and extended Applications: added `update` (PATCH `/v3/applications`) and source-only response fields (`idp_settings`, hosted-authentication legal URLs, `v2_application_id`, `domain`, `blocked`, timestamps)
+
 v6.14.0
 ----------
 * Added `message.deleted` to the Webhook enum, appended tests

nylas/client.py

@@ -20,6 +20,7 @@
 from nylas.resources.scheduler import Scheduler
 from nylas.resources.notetakers import Notetakers
 from nylas.resources.rules import Rules
+from nylas.resources.workspaces import Workspaces
 
 
 class Client:
@@ -246,3 +247,13 @@ def notetakers(self) -> Notetakers:
             The Notetakers API.
         """
         return Notetakers(self.http_client)
+
+    @property
+    def workspaces(self) -> Workspaces:
+        """
+        Access the Workspaces API.
+
+        Returns:
+            The Workspaces API.
+        """
+        return Workspaces(self.http_client)

nylas/models/application_details.py

@@ -1,15 +1,16 @@
 from dataclasses import dataclass, field
-from typing import Literal, Optional, List
+from typing import Optional, List
 
 from dataclasses_json import dataclass_json
+from typing_extensions import TypedDict, NotRequired
 
 from nylas.models.redirect_uri import RedirectUri
 
-Region = Literal["us", "eu"]
-""" Literal representing the available Nylas API regions. """
+Region = str
+""" The Nylas API region (free-form string, e.g. ``us``, ``eu``). """
 
-Environment = Literal["production", "staging", "development", "sandbox"]
-""" Literal representing the different Nylas API environments. """
+Environment = str
+""" The Nylas API environment (free-form string, e.g. ``sandbox``). """
 
 
 @dataclass_json
@@ -46,6 +47,8 @@ class HostedAuthentication:
         subtitle: Subtitle for the hosted authentication page.
         background_color: Background color of the hosted authentication page.
         spacing: CSS spacing attribute in px.
+        terms_of_service_url: URL pointing to the terms of service.
+        privacy_policy_url: URL pointing to the privacy policy.
     """
 
     background_image_url: Optional[str] = None
@@ -56,6 +59,23 @@ class HostedAuthentication:
     subtitle: Optional[str] = None
     background_color: Optional[str] = None
     spacing: Optional[int] = None
+    terms_of_service_url: Optional[str] = None
+    privacy_policy_url: Optional[str] = None
+
+
+@dataclass_json
+@dataclass
+class IdpSettings:
+    """
+    Class representation of identity provider settings for the application.
+
+    Attributes:
+        origins: Comma-separated list of allowed origins.
+        issuers: Comma-separated list of allowed issuers.
+    """
+
+    origins: Optional[str] = None
+    issuers: Optional[str] = None
 
 
 @dataclass_json
@@ -70,14 +90,134 @@ class ApplicationDetails:
         region: Region identifier.
         environment: Environment identifier.
         branding: Branding details for the application.
+        v2_application_id: The associated v2 application ID, if any.
+        domain: The white-label domain associated with the application, if any.
         hosted_authentication: Hosted authentication branding details.
+        idp_settings: Identity provider settings.
         callback_uris: List of redirect URIs.
+        created_at: Unix timestamp (seconds) when the application was created.
+        updated_at: Unix timestamp (seconds) when the application was last updated.
+        blocked: Whether the application is blocked.
     """
 
     application_id: str
     organization_id: str
     region: Region
     environment: Environment
     branding: Branding
+    v2_application_id: Optional[str] = None
+    domain: Optional[str] = None
     hosted_authentication: Optional[HostedAuthentication] = None
+    idp_settings: Optional[IdpSettings] = None
     callback_uris: List[RedirectUri] = field(default_factory=list)
+    created_at: Optional[int] = None
+    updated_at: Optional[int] = None
+    blocked: Optional[bool] = None
+
+
+class WritableBranding(TypedDict):
+    """
+    Class representing branding details for a create/update application call.
+
+    Attributes:
+        name: Name of the application.
+        icon_url: URL pointing to the application icon.
+        website_url: Application/publisher website URL.
+        description: Description of the application.
+    """
+
+    name: NotRequired[str]
+    icon_url: NotRequired[str]
+    website_url: NotRequired[str]
+    description: NotRequired[str]
+
+
+class WritableHostedAuthentication(TypedDict):
+    """
+    Class representing hosted authentication details for a create/update application call.
+
+    Attributes:
+        background_image_url: URL pointing to the background image.
+        alignment: Alignment of the background image.
+        color_primary: Primary color of the hosted authentication page.
+        color_secondary: Secondary color of the hosted authentication page.
+        title: Title of the hosted authentication page.
+        subtitle: Subtitle for the hosted authentication page.
+        background_color: Background color of the hosted authentication page.
+        spacing: CSS spacing attribute in px.
+        terms_of_service_url: URL pointing to the terms of service.
+        privacy_policy_url: URL pointing to the privacy policy.
+    """
+
+    background_image_url: NotRequired[str]
+    alignment: NotRequired[str]
+    color_primary: NotRequired[str]
+    color_secondary: NotRequired[str]
+    title: NotRequired[str]
+    subtitle: NotRequired[str]
+    background_color: NotRequired[str]
+    spacing: NotRequired[int]
+    terms_of_service_url: NotRequired[str]
+    privacy_policy_url: NotRequired[str]
+
+
+class WritableIdpSettings(TypedDict):
+    """
+    Class representing identity provider settings for a create/update application call.
+
+    Attributes:
+        origins: Comma-separated list of allowed origins.
+        issuers: Comma-separated list of allowed issuers.
+    """
+
+    origins: NotRequired[str]
+    issuers: NotRequired[str]
+
+
+class WritableAdditionalSettings(TypedDict):
+    """
+    Class representing additional application settings for an update call.
+
+    These settings are write-only: they can be set via the update call but are
+    stripped from every response and are not bound on the application model.
+
+    Attributes:
+        login_url: The login URL.
+        logout_url: The logout URL.
+        refresh_token_expiration_absolute: Absolute refresh token expiration.
+        refresh_token_expiration_idle: Idle refresh token expiration.
+        rotate_refresh_token: Whether to rotate the refresh token.
+        allow_query_param_in_redirect_uri: Whether query params are allowed in redirect URIs.
+    """
+
+    login_url: NotRequired[str]
+    logout_url: NotRequired[str]
+    refresh_token_expiration_absolute: NotRequired[int]
+    refresh_token_expiration_idle: NotRequired[int]
+    rotate_refresh_token: NotRequired[bool]
+    allow_query_param_in_redirect_uri: NotRequired[bool]
+
+
+class UpdateApplicationRequest(TypedDict):
+    """
+    Class representing a request to update a Nylas application.
+
+    Note:
+        ``callback_uris`` / ``redirect_uris`` cannot be set via this request; the
+        server silently ignores them. Manage callback URIs via the dedicated
+        redirect-uris endpoints. ``additional_settings`` is write-only and is
+        stripped from the response.
+
+    Attributes:
+        branding: Branding details for the application.
+        hosted_authentication: Hosted authentication branding details.
+        idp_settings: Identity provider settings.
+        domain: The white-label domain associated with the application.
+        additional_settings: Additional (write-only) application settings.
+    """
+
+    branding: NotRequired[WritableBranding]
+    hosted_authentication: NotRequired[WritableHostedAuthentication]
+    idp_settings: NotRequired[WritableIdpSettings]
+    domain: NotRequired[str]
+    additional_settings: NotRequired[WritableAdditionalSettings]

nylas/models/redirect_uri.py

@@ -39,12 +39,14 @@ class RedirectUri:
         url: Redirect URL.
         platform: Platform identifier.
         settings: Configuration settings.
+        deleted_at: Soft-delete timestamp (Unix seconds); omitted when not deleted.
     """
 
     id: str
     url: str
     platform: str
     settings: Optional[RedirectUriSettings] = None
+    deleted_at: Optional[int] = None
 
 
 class WritableRedirectUriSettings(TypedDict):
@@ -74,12 +76,12 @@ class CreateRedirectUriRequest(TypedDict):
 
     Attributes:
         url: Redirect URL.
-        platform: Platform identifier.
+        platform: Platform identifier. Optional; defaults to "web" server-side.
         settings: Optional settings for the redirect uri.
     """
 
     url: str
-    platform: str
+    platform: NotRequired[str]
     settings: NotRequired[WritableRedirectUriSettings]