connector-py 4.179.0__py3-none-any.whl → 4.181.0__py3-none-any.whl

connector/__about__.py

@@ -1 +1 @@
-__version__ = "4.179.0"
+__version__ = "4.181.0"

connector/client.py

@@ -1,5 +1,9 @@
 from .httpx_rewrite import AsyncClient, GqlHTTPXAsyncTransport, HTTPXAsyncTransport
-from .oai.base_clients import BaseGraphQLSession, BaseIntegrationClient
+from .oai.base_clients import (
+    BaseGraphQLSession,
+    BaseIntegrationClient,
+    RateLimitedHTTPXAsyncTransport,
+)
 from .oai.capability import (
     get_basic_auth,
     get_jwt_auth,
@@ -20,6 +24,7 @@ from .utils.sync_to_async import sync_to_async
 __all__ = [
     "GqlHTTPXAsyncTransport",
     "HTTPXAsyncTransport",
+    "RateLimitedHTTPXAsyncTransport",
     "BaseGraphQLSession",
     "BaseIntegrationClient",
     "get_basic_auth",

connector/generated/__init__.py

@@ -40,7 +40,6 @@ from connector_sdk_types.generated.models.assign_entitlement_response import (
 )
 from connector_sdk_types.generated.models.assigned_entitlement import AssignedEntitlement
 from connector_sdk_types.generated.models.auth_credential import AuthCredential
-from connector_sdk_types.generated.models.auth_model import AuthModel
 from connector_sdk_types.generated.models.authorization_url import AuthorizationUrl
 from connector_sdk_types.generated.models.basic_authentication import BasicAuthentication
 from connector_sdk_types.generated.models.basic_credential import BasicCredential
@@ -53,7 +52,6 @@ from connector_sdk_types.generated.models.create_account_request import CreateAc
 from connector_sdk_types.generated.models.create_account_response import CreateAccountResponse
 from connector_sdk_types.generated.models.created_account import CreatedAccount
 from connector_sdk_types.generated.models.created_effect import CreatedEffect
-from connector_sdk_types.generated.models.credential_config import CredentialConfig
 from connector_sdk_types.generated.models.custom_attribute_customized_type import (
     CustomAttributeCustomizedType,
 )
@@ -320,7 +318,6 @@ __all__ = [
     "AssignEntitlementResponse",
     "AssignedEntitlement",
     "AuthCredential",
-    "AuthModel",
     "AuthorizationUrl",
     "BasicAuthentication",
     "BasicCredential",
@@ -332,7 +329,6 @@ __all__ = [
     "CreateAccountRequest",
     "CreateAccountResponse",
     "CreatedAccount",
-    "CredentialConfig",
     "CustomAttributeCustomizedType",
     "CustomAttributeSchema",
     "CustomAttributeType",

connector/generated/models/__init__.py

@@ -36,7 +36,6 @@ from connector_sdk_types.generated.models.assign_entitlement_response import (
 )
 from connector_sdk_types.generated.models.assigned_entitlement import AssignedEntitlement
 from connector_sdk_types.generated.models.auth_credential import AuthCredential
-from connector_sdk_types.generated.models.auth_model import AuthModel
 from connector_sdk_types.generated.models.authorization_url import AuthorizationUrl
 from connector_sdk_types.generated.models.basic_authentication import BasicAuthentication
 from connector_sdk_types.generated.models.basic_credential import BasicCredential
@@ -48,7 +47,6 @@ from connector_sdk_types.generated.models.create_account_entitlement import Crea
 from connector_sdk_types.generated.models.create_account_request import CreateAccountRequest
 from connector_sdk_types.generated.models.create_account_response import CreateAccountResponse
 from connector_sdk_types.generated.models.created_account import CreatedAccount
-from connector_sdk_types.generated.models.credential_config import CredentialConfig
 from connector_sdk_types.generated.models.custom_attribute_customized_type import (
     CustomAttributeCustomizedType,
 )
@@ -304,7 +302,6 @@ __all__ = [
     "AssignEntitlementResponse",
     "AssignedEntitlement",
     "AuthCredential",
-    "AuthModel",
     "AuthorizationUrl",
     "BasicAuthentication",
     "BasicCredential",
@@ -316,7 +313,6 @@ __all__ = [
     "CreateAccountRequest",
     "CreateAccountResponse",
     "CreatedAccount",
-    "CredentialConfig",
     "CustomAttributeCustomizedType",
     "CustomAttributeSchema",
     "CustomAttributeType",

connector/oai/base_clients.py

@@ -10,11 +10,11 @@ from connector_sdk_types.generated import ErrorCode
 from gql import Client
 from gql.client import AsyncClientSession
 from gql.dsl import DSLSchema
-from graphql import GraphQLSchema, build_client_schema, build_schema
+from graphql import DocumentNode, GraphQLSchema, build_client_schema, build_schema
 from httpx import Response
 from typing_extensions import Self
 
-from connector.httpx_rewrite import AsyncClient
+from connector.httpx_rewrite import AsyncClient, HTTPXAsyncTransport
 from connector.oai.capability import Request
 from connector.oai.errors import ConnectorError
 from connector.utils.rate_limiting import RateLimitConfig, RateLimiter
@@ -178,6 +178,75 @@ class RateLimitedClient(AsyncClient):
             await self.base_client.__aexit__(exc_type, exc_val, exc_tb)
 
 
+class RateLimitedHTTPXAsyncTransport(HTTPXAsyncTransport):
+    """A wrapper around HTTPXAsyncTransport that applies rate limiting to GraphQL requests."""
+
+    def __init__(self, base_transport: HTTPXAsyncTransport, rate_limit_config: RateLimitConfig):
+        # Copy all attributes from base transport, but exclude 'execute' to avoid shadowing our method
+        base_dict = {k: v for k, v in base_transport.__dict__.items() if k != "execute"}
+        self.__dict__.update(base_dict)
+        self.base_transport = base_transport
+        self.rate_limiter = RateLimiter[Callable[[], Any], Any](rate_limit_config)
+
+    async def connect(self):
+        """Connect the underlying transport and replace its client with a rate-limited one."""
+        await self.base_transport.connect()
+
+        # Replace the base transport's client with a rate-limited version
+        if hasattr(self.base_transport, "client") and self.base_transport.client:
+            # The transport's client should be our AsyncClient type, but we need to handle the type
+            if isinstance(self.base_transport.client, AsyncClient):
+                self.base_transport.client = RateLimitedClient(
+                    self.base_transport.client, self.rate_limiter.config
+                )
+
+        # Copy the client reference
+        self.client = self.base_transport.client
+
+    async def execute(
+        self,
+        document: DocumentNode,
+        variable_values: dict[str, Any] | None = None,
+        operation_name: str | None = None,
+        extra_args: dict[str, Any] | None = None,
+        upload_files: bool = False,
+    ):
+        """Execute a GraphQL request with rate limiting."""
+
+        async def request_func():
+            result = await self.base_transport.execute(
+                document=document,
+                variable_values=variable_values,
+                operation_name=operation_name,
+                extra_args=extra_args,
+                upload_files=upload_files,
+            )
+            return result
+
+        # Use the rate limiter to execute the request
+        responses = await self.rate_limiter.execute_requests([request_func], lambda x: x())
+        if responses:
+            return responses[0]
+
+        raise ConnectorError(
+            message="No response from GraphQL API",
+            error_code=ErrorCode.API_ERROR,
+        )
+
+    def get_state(self) -> tuple[RateLimitConfig, float]:
+        """Get the current rate limit state."""
+        return self.rate_limiter.config, self.rate_limiter.current_delay
+
+    async def close(self):
+        """Close the underlying transport."""
+        if hasattr(self.base_transport, "close"):
+            await self.base_transport.close()
+
+    def __getattr__(self, name):
+        """Delegate attribute access to the underlying base_transport."""
+        return getattr(self.base_transport, name)
+
+
 class BaseIntegrationClient:
     _http_client: AsyncClient | RateLimitedClient
     _rate_limit_config: RateLimitConfig | None = None
@@ -248,8 +317,11 @@ class BaseIntegrationClient:
 
 
 class BaseGraphQLSession(AsyncClientSession):
-    def __init__(self, args: Request):
-        super().__init__(client=self.build_client(args))
+    _rate_limit_config: RateLimitConfig | None = None
+
+    def __init__(self, args: Request, rate_limit_config: RateLimitConfig | None = None):
+        client = self.build_client(args, rate_limit_config)
+        super().__init__(client=client)
 
     async def __aenter__(self) -> Self:
         await self.client.__aenter__()
@@ -267,8 +339,31 @@ class BaseGraphQLSession(AsyncClientSession):
         pass
 
     @classmethod
-    def build_client(cls, args: Request) -> Client:
-        return Client(**cls.prepare_client_args(args))
+    def build_client(
+        cls, args: Request, rate_limit_config: RateLimitConfig | None = None
+    ) -> Client:
+        client_args = cls.prepare_client_args(args)
+
+        # Apply rate limiting if configured
+        rate_limiting = rate_limit_config or cls._rate_limit_config
+        if rate_limiting is not None and "transport" in client_args:
+            transport = client_args["transport"]
+            if isinstance(transport, HTTPXAsyncTransport):
+                client_args["transport"] = RateLimitedHTTPXAsyncTransport(transport, rate_limiting)
+
+        return Client(**client_args)
+
+    def get_current_rate_limits(self) -> tuple[RateLimitConfig | None, float]:
+        """
+        Get the current rate limit state.
+
+        Returns a tuple of the rate limit config and the current delay. (or None if the client is not rate limited)
+        """
+        if hasattr(self.client, "transport") and isinstance(
+            self.client.transport, RateLimitedHTTPXAsyncTransport
+        ):
+            return self.client.transport.get_state()
+        return None, 0
 
     @classmethod
     def load_schema(cls, schema_file_path: str | Path) -> GraphQLSchema:

connector/oai/capabilities/executor.py

@@ -8,7 +8,6 @@ from typing import Any, ClassVar, Generic, Literal, TypeVar, cast
 from connector_sdk_types.generated import (
     AuthCredential,
     BasicCredential,
-    CredentialConfig,
     ErrorResponse,
     JWTCredential,
     KeyPairCredential,
@@ -20,8 +19,9 @@ from connector_sdk_types.generated import (
     TokenCredential,
 )
 from connector_sdk_types.oai.capability import Request
-from connector_sdk_types.oai.modules.oauth_module_types import (
+from connector_sdk_types.oai.modules.credentials_module_types import (
     AuthSetting,
+    CredentialConfig,
     EmptySettings,
     OAuthConfig,
 )

connector/oai/capabilities/factory.py

@@ -2,9 +2,12 @@ from collections.abc import Mapping, Sequence
 from functools import partial
 from typing import Generic, TypeVar
 
-from connector_sdk_types.generated import CredentialConfig
 from connector_sdk_types.oai.capability import Request
-from connector_sdk_types.oai.modules.oauth_module_types import AuthSetting, OAuthConfig
+from connector_sdk_types.oai.modules.credentials_module_types import (
+    AuthSetting,
+    CredentialConfig,
+    OAuthConfig,
+)
 from pydantic import BaseModel
 
 from connector.oai.capability import CapabilityCallableProto, get_capability_annotations

connector/oai/capability.py

@@ -103,6 +103,8 @@ from connector_sdk_types.generated import (
     UnassignEntitlementResponse,
     UpdateAccountRequest,
     UpdateAccountResponse,
+    ValidateCredentialConfigRequest,
+    ValidateCredentialConfigResponse,
     ValidateCredentialsRequest,
     ValidateCredentialsResponse,
 )
@@ -829,4 +831,15 @@ _STANDARD_CAPABILITY_SIGNATURES: dict[StandardCapabilityName, CapabilitySignatur
             envelope_type=UnassignApplicationEntitlementResponse, is_request=False
         ),
     ),
+    # Per-credential validation capabilities
+    StandardCapabilityName.VALIDATE_CREDENTIAL_CONFIG: CapabilitySignature(
+        input_payload=_payload_type_data(
+            envelope_type=ValidateCredentialConfigRequest,
+            is_request=True,
+        ),
+        output_payload=_payload_type_data(
+            envelope_type=ValidateCredentialConfigResponse,
+            is_request=False,
+        ),
+    ),
 }

connector/oai/integration.py

@@ -32,15 +32,14 @@ from functools import cached_property
 
 from connector_sdk_types.generated import (
     AppCategory,
-    AuthModel,
     BasicCredential,
     CapabilitySchema,
-    CredentialConfig,
     EntitlementType,
     Info,
     InfoResponse,
     JWTCredential,
     KeyPairCredential,
+    OAuth1Credential,
     OAuthClientCredential,
     OAuthCredential,
     ResourceType,
@@ -48,7 +47,14 @@ from connector_sdk_types.generated import (
     StandardCapabilityName,
     TokenCredential,
 )
-from connector_sdk_types.oai.modules.oauth_module_types import AuthSetting, EmptySettings
+from connector_sdk_types.oai.modules.credentials_module_types import (
+    AuthModel,
+    AuthSetting,
+    CredentialConfig,
+    CredentialsSettings,
+    EmptySettings,
+    OAuthConfig,
+)
 from pydantic import BaseModel
 
 from connector.oai.capability import (
@@ -58,14 +64,15 @@ from connector.oai.capability import (
 )
 from connector.oai.errors import ErrorMap
 from connector.oai.modules.base_module import BaseIntegrationModule
+from connector.oai.modules.credentials_module import CredentialsModule
 from connector.oai.modules.info_module import InfoModule
 from connector.oai.modules.oauth_module import OAuthModule
-from connector.oai.modules.oauth_module_types import OAuthConfig, OAuthSettings
+from connector.oai.modules.oauth_module_types import OAuthSettings
 
 from .capabilities.errors import CapabilityError, CapabilityNotImplementedError
 from .capabilities.factory import CapabilityExecutorFactory
 
-AUTH_TYPE_MAP = {
+AUTH_TYPE_MAP: dict[AuthModel, type[BaseModel]] = {
     AuthModel.OAUTH: OAuthCredential,
     AuthModel.OAUTH_CLIENT_CREDENTIALS: OAuthClientCredential,
     AuthModel.BASIC: BasicCredential,
@@ -73,6 +80,7 @@ AUTH_TYPE_MAP = {
     AuthModel.JWT: JWTCredential,
     AuthModel.SERVICE_ACCOUNT: ServiceAccountCredential,
     AuthModel.KEY_PAIR: KeyPairCredential,
+    AuthModel.OAUTH1: OAuth1Credential,
 }
 
 
@@ -183,6 +191,7 @@ class Integration:
         entitlement_types: list[EntitlementType] | None = None,
         settings_model: type[BaseModel] | None = None,
         oauth_settings: OAuthSettings | None = None,
+        credentials_settings: CredentialsSettings | None = None,
     ):
         self.app_id = app_id.strip()
         self.version = version
@@ -195,6 +204,7 @@ class Integration:
         self.entitlement_types = entitlement_types or []
         self.settings_model = settings_model or EmptySettings
         self.oauth_settings = oauth_settings
+        self.credentials_settings = credentials_settings
 
         if len(self.app_id) == 0:
             raise InvalidAppIdError
@@ -219,6 +229,12 @@ class Integration:
         # Attach the info module (app_info capability)
         self.add_module(InfoModule())
 
+        # Attach a credentials module if credentials are provided
+        if self.credentials:
+            self.add_module(
+                CredentialsModule(settings=credentials_settings or CredentialsSettings.default())
+            )
+
     def add_module(self, module: BaseIntegrationModule):
         self.modules.append(module)
         module.register(self)

connector/oai/modules/credentials_module.py

@@ -0,0 +1,282 @@
+import inspect
+from collections.abc import Awaitable, Sequence
+from typing import TYPE_CHECKING, cast
+
+from connector_sdk_types.generated import (
+    Error,
+    ErrorCode,
+    ErrorResponse,
+    StandardCapabilityName,
+    ValidateCredentialConfigRequest,
+    ValidateCredentialConfigResponse,
+    ValidatedCredentialConfig,
+)
+from connector_sdk_types.oai.modules.credentials_module_types import (
+    CredentialConfig,
+    CredentialsSettings,
+    OAuthConfig,
+    ValidateCredentialConfigCallable,
+)
+from pydantic import ValidationError
+
+from connector.oai.capabilities.errors import CapabilityExecutionError
+from connector.oai.modules.base_module import BaseIntegrationModule
+
+if TYPE_CHECKING:
+    from connector.oai.integration import Integration
+
+
+class CredentialsModule(BaseIntegrationModule):
+    """
+    Credentials module is responsible for handling the credentials for an Integration.
+    It can register the following capabilities:
+    - VALIDATE_CREDENTIAL_CONFIG
+
+    It can be configured with the following settings:
+    - register_validation_capability: bool - Flag that indicates whether the CredentialsModule should register the validate_credential_config capability. Set to `False` to skip registration and implement the capability manually.
+
+    You can also call the base_validation method to perform base validation on a credential config request.
+
+    Example usage when manually registering the capability:
+        @integration.register_capability(StandardCapabilityName.VALIDATE_CREDENTIAL_CONFIG)
+        async def validate_credential_config(
+            args: ValidateCredentialConfigRequest,
+        ) -> ValidateCredentialConfigResponse:
+            # Use base validation
+            errors = CredentialsModule.base_validation(integration, args)
+            if errors:
+                return ValidateCredentialConfigResponse(response=ValidatedCredentialConfig(valid=False, errors=errors))
+            # Add custom validation logic here
+            # ...
+            return ValidateCredentialConfigResponse(response=ValidatedCredentialConfig(valid=True))
+    """
+
+    credentials: dict[str, CredentialConfig]
+    settings: CredentialsSettings
+
+    def __init__(self, settings: CredentialsSettings):
+        super().__init__()
+        self.credentials = {}
+        self.settings = settings
+
+    def add_capability(self, capability: str):
+        """Add a capability to the module."""
+        self.capabilities.append(capability)
+
+    def get_capability(self, capability: str) -> StandardCapabilityName | str | None:
+        """Get a capability from the module."""
+        for cap in self.capabilities:
+            if cap == capability:
+                return cap
+        return None
+
+    def register(self, integration: "Integration"):
+        """Register validate_credential_config capability for each credential config."""
+        self.integration = integration
+        validation_functions: dict[str, ValidateCredentialConfigCallable] = {}
+
+        for credential in integration.credentials:
+            self.credentials[credential.id] = credential
+            validation_implementation = credential.validation
+            if validation_implementation:
+                validation_functions[credential.id] = cast(
+                    ValidateCredentialConfigCallable, validation_implementation
+                )
+
+        if self.settings.register_validation_capability and (
+            StandardCapabilityName.VALIDATE_CREDENTIAL_CONFIG.value
+            not in self.integration.capabilities.keys()
+        ):
+            """
+            If the Integration already registers a validate_credential_config capability,
+            we don't register another one, as it would be a duplicate.
+            """
+            self.register_dynamic_validation_capability(
+                StandardCapabilityName.VALIDATE_CREDENTIAL_CONFIG,
+                validation_functions,
+            )
+
+    def register_dynamic_validation_capability(
+        self,
+        capability_name: StandardCapabilityName,
+        validation_functions: dict[str, ValidateCredentialConfigCallable],
+    ):
+        @self.integration.register_capability(capability_name)
+        async def validate_credential_config(
+            args: ValidateCredentialConfigRequest,
+        ) -> ValidateCredentialConfigResponse:
+            is_valid = False
+            errors = CredentialsModule.base_validation(
+                self.integration.app_id, self.integration.credentials, args
+            )
+
+            if errors:
+                return ValidateCredentialConfigResponse(
+                    response=ValidatedCredentialConfig(
+                        valid=is_valid,
+                        validation_errors=errors,
+                    ),
+                )
+
+            for credential_id, validation_function in validation_functions.items():
+                if credential_id != args.request.credential.id:
+                    # Skip validation for non-received credentials
+                    continue
+
+                """
+                If this raises, it will bubble up just like any other capability error.
+                """
+                result = validation_function(args)
+                if inspect.isawaitable(result):
+                    result = await cast(
+                        Awaitable[ValidateCredentialConfigResponse | ErrorResponse],
+                        result,
+                    )
+
+                if isinstance(result, ErrorResponse):
+                    raise CapabilityExecutionError(result)
+
+                if isinstance(result, ValidateCredentialConfigResponse):
+                    if not result.response.valid or result.response.validation_errors:
+                        errors.extend(result.response.validation_errors or [])
+
+                    if not result.response.valid and not result.response.validation_errors:
+                        errors.append("Credential is invalid, unexpected error occurred")
+
+            if not errors:
+                is_valid = True
+
+            return ValidateCredentialConfigResponse(
+                response=ValidatedCredentialConfig(
+                    valid=is_valid,
+                    validation_errors=errors,
+                ),
+            )
+
+        return validate_credential_config
+
+    # Utility methods
+
+    @classmethod
+    def base_validation(
+        cls,
+        app_id: str,
+        credentials: Sequence[CredentialConfig | OAuthConfig],
+        request: ValidateCredentialConfigRequest,
+    ) -> list[str]:
+        """
+        Perform base validation on a credential config request.
+
+        This method can be called as a class method to reuse the base validation logic
+        when manually implementing the validate_credential_config capability.
+
+        Example usage when manually registering the capability:
+            @integration.register_capability(StandardCapabilityName.VALIDATE_CREDENTIAL_CONFIG)
+            async def validate_credential_config(
+                args: ValidateCredentialConfigRequest,
+            ) -> ValidateCredentialConfigResponse:
+                # Use base validation
+                errors = CredentialsModule.base_validation("app_id", CredentialConfigList, args)
+                if errors:
+                    return ValidateCredentialConfigResponse(
+                        response=ValidatedCredentialConfig(valid=False, validation_errors=errors)
+                    )
+                # Add custom validation logic here
+                # ...
+                return ValidateCredentialConfigResponse(
+                    response=ValidatedCredentialConfig(valid=True, validation_errors=[])
+                )
+
+        Args:
+            app_id: The App ID of the integration
+            credentials: The credentials (configs) to validate against
+            request: The validation request to validate
+
+        Returns:
+            A list of error messages (empty if validation passes)
+
+        Raises:
+            CapabilityExecutionError: For critical validation failures (missing ID, invalid config, etc.)
+        """
+        errors: list[str] = []  # Customer facing errors
+        credential_config_id = request.request.credential.id
+        credential = request.request.credential
+        credential_dict = credential.model_dump()
+
+        if not credential_config_id:
+            # This should not happen, and should in such case fail immediately
+            raise CapabilityExecutionError(
+                ErrorResponse(
+                    is_error=True,
+                    error=Error(
+                        error_code=ErrorCode.BAD_REQUEST,
+                        message="Received credential without an ID",
+                        app_id=app_id,
+                    ),
+                )
+            )
+
+        # Build credentials dict from integration.credentials
+        credentials_dict = {cred.id: cred for cred in credentials}
+        credential_config = credentials_dict.get(credential_config_id)
+
+        if credential_config is None:
+            # Should fail fast
+            raise CapabilityExecutionError(
+                ErrorResponse(
+                    is_error=True,
+                    error=Error(
+                        error_code=ErrorCode.BAD_REQUEST,
+                        message=f"Missing credential configuration for ID {credential_config_id}",
+                        app_id=app_id,
+                    ),
+                )
+            )
+
+        try:
+            from connector.oai.integration import AUTH_TYPE_MAP
+
+            credential_model = AUTH_TYPE_MAP[credential_config.type](
+                **credential_dict[credential_config.type]
+            )
+            connector_credential = credential_model.model_validate(credential_model)
+        except ValidationError as e:
+            raise CapabilityExecutionError(
+                ErrorResponse(
+                    is_error=True,
+                    error=Error(
+                        error_code=ErrorCode.BAD_REQUEST,
+                        message="Invalid or malformed credential received",
+                        app_id=app_id,
+                    ),
+                )
+            ) from e
+
+        # Dump the model
+        credential_dict = connector_credential.model_dump(exclude_none=True)
+
+        # Check for empty models
+        if credential_dict == {}:
+            errors.append("Credential is missing required fields")
+            return errors
+
+        # Get the list of required fields from the model's JSON schema
+        model_schema = credential_model.model_json_schema()
+        required_fields = set(model_schema.get("required", []))
+
+        # Check for empty strings on required fields
+        for field_name, value in credential_dict.items():
+            if field_name in required_fields and value == "":
+                errors.append(
+                    "A required field is empty, please provide a value before submitting again"
+                )
+                return errors
+
+        # Check for extra whitespace
+        if any(value.strip() != value for value in credential_dict.values()):
+            errors.append(
+                "Credential has extra whitespace, please remove it before submitting it again"
+            )
+            return errors
+
+        return errors