scalekit-sdk-python 2.9.0__tar.gz → 2.11.0__tar.gz

{scalekit_sdk_python-2.9.0 → scalekit_sdk_python-2.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scalekit-sdk-python
-Version: 2.9.0
+Version: 2.11.0
 Summary: Scalekit official Python SDK
 Home-page: https://github.com/scalekit-inc/scalekit-sdk-python
 Author: Team Scalekit

{scalekit_sdk_python-2.9.0 → scalekit_sdk_python-2.11.0}/scalekit/_version.py

@@ -1,3 +1,3 @@
 # Single source of truth for the SDK version.
 # Import this in setup.py and scalekit/core.py — never hardcode the version elsewhere.
-__version__ = "2.9.0"
+__version__ = "2.11.0"

{scalekit_sdk_python-2.9.0 → scalekit_sdk_python-2.11.0}/scalekit/actions/actions.py

@@ -1,9 +1,13 @@
+from datetime import timedelta
 from typing import Optional, Any, List, Dict, Union
 import requests
 from scalekit.actions.types import ToolRequest,ExecuteToolResponse,MagicLinkResponse,ListConnectedAccountsResponse,DeleteConnectedAccountResponse,GetConnectedAccountAuthResponse,GetConnectedAccountDetailsResponse,ToolInput, \
     UpdateConnectedAccountResponse,CreateMcpConfigResponse,ListMcpConfigsResponse,UpdateMcpConfigResponse,DeleteMcpConfigResponse, \
     EnsureMcpInstanceResponse,UpdateMcpInstanceResponse,GetMcpInstanceResponse,ListMcpInstancesResponse,DeleteMcpInstanceResponse,GetMcpInstanceAuthStateResponse, \
-    McpConfig,McpConfigConnectionToolMapping,VerifyConnectedAccountUserResponse
+    McpConfig,McpConfigConnectionToolMapping,VerifyConnectedAccountUserResponse, \
+    CreateCustomProviderRequest,UpdateCustomProviderRequest,ListProvidersRequest,DeleteCustomProviderRequest, \
+    CreateCustomProviderResponse,UpdateCustomProviderResponse,ListProvidersResponse,DeleteCustomProviderResponse, \
+    ListMcpConnectedAccountsResponse,CreateMcpSessionTokenResponse,McpConnectionAuthState
 from scalekit.actions.models.responses.create_connected_account_response import CreateConnectedAccountResponse
 from scalekit.actions.models.requests.create_connected_account_request import CreateConnectedAccountRequest
 from scalekit.actions.models.requests.update_connected_account_request import UpdateConnectedAccountRequest
@@ -19,17 +23,19 @@ from scalekit.common.exceptions import ScalekitNotFoundException
 class ActionClient:
     """Class definition for Connect Client"""
 
-    def __init__(self,tools_client, connected_accounts_client, mcp_client=None):
+    def __init__(self,tools_client, connected_accounts_client, mcp_client=None, providers_client=None):
         """
         Initialize ActionClient with tools, connected accounts, and MCP dependencies
-        
+
         :param tools_client: ToolsClient instance
         :type: ToolsClient
         :param connected_accounts_client: ConnectedAccountsClient instance
         :type: ConnectedAccountsClient
         :param mcp_client: McpClient instance (optional)
         :type: McpClient
-        
+        :param providers_client: ProvidersClient instance (optional)
+        :type: ProvidersClient
+
         :returns:
             None
         """
@@ -38,6 +44,8 @@ class ActionClient:
         self.connected_accounts = connected_accounts_client
         self._mcp_client = mcp_client
         self._mcp_actions = None
+        self._providers_client = providers_client
+        self._providers_actions = None
         self._modifiers: List[Modifier] = []
         self._google = None
         self._langchain = None
@@ -87,6 +95,20 @@ class ActionClient:
             self._mcp_actions = ActionMcp(self)
         return self._mcp_actions
 
+    @property
+    def providers(self) -> "ActionProviders":
+        """Expose custom provider CRUD with typed request and response objects.
+
+        :returns: ActionProviders instance bound to the configured ProvidersClient.
+        :rtype: ActionProviders
+        :raises ValueError: If no ProvidersClient was passed at construction time.
+        """
+        if self._providers_client is None:
+            raise ValueError("Providers client not initialized.")
+        if self._providers_actions is None:
+            self._providers_actions = ActionProviders(self._providers_client)
+        return self._providers_actions
+
     def execute_tool(
         self,
         tool_input:ToolInput,
@@ -222,37 +244,35 @@ class ActionClient:
         return VerifyConnectedAccountUserResponse.from_proto(proto_response)
     
     def list_connected_accounts(
-        self, 
+        self,
         connection_name: Optional[str] = None,
         identifier: Optional[str] = None,
         provider: Optional[str] = None,
+        connection_names: Optional[List[str]] = None,
         **kwargs
     ) -> ListConnectedAccountsResponse:
+        """List connected accounts with optional filtering.
+
+        Args:
+            connection_name: Filter by a single connector slug, e.g. ``"github"``.
+                Mapped to the ``connector`` field in the underlying request.
+            identifier: Filter by end-user identifier, e.g. email or opaque user ID.
+            provider: Filter by OAuth/API-key provider slug, e.g. ``"google"``.
+            connection_names: Filter results to connected accounts belonging to *any*
+                of these connection slugs. Useful when you want to check multiple
+                connectors at once, e.g. ``["github", "google-calendar", "slack"]``.
+                Can be combined with ``identifier`` to narrow results to a specific user.
+
+        Returns:
+            ListConnectedAccountsResponse containing the matching connected accounts.
         """
-        List connected accounts with optional filtering
-        
-        :param connection_name: Connector identifier (optional)
-        :type: str
-        :param identifier: Identifier filter (optional)
-        :type: str
-        :param provider: Provider filter (optional)
-        :type: str
-        
-        :returns:
-            ListConnectedAccountsResponse containing list of connected accounts
-        """
-        # Call the existing connected_accounts method which returns (response, metadata) tuple
         result_tuple = self.connected_accounts.list_connected_accounts(
             connector=connection_name,
             identifier=identifier,
-            provider=provider
+            provider=provider,
+            connection_names=connection_names,
         )
-        
-        # Extract the response[0] (the actual ListConnectedAccountsResponse proto object)
-        proto_response = result_tuple[0]
-        
-        # Convert proto to our ListConnectedAccountsResponse class
-        return ListConnectedAccountsResponse.from_proto(proto_response)
+        return ListConnectedAccountsResponse.from_proto(result_tuple[0])
     
     def delete_connected_account(
         self,
@@ -523,6 +543,7 @@ class ActionClient:
         filter_id: Optional[str] = None,
         filter_provider: Optional[str] = None,
         filter_name: Optional[str] = None,
+        filter_mcp_server_url: Optional[str] = None,
         search: Optional[str] = None,
         **kwargs,
     ) -> ListMcpConfigsResponse:
@@ -534,6 +555,7 @@ class ActionClient:
             filter_id=filter_id,
             filter_provider=filter_provider,
             filter_name=filter_name,
+            filter_mcp_server_url=filter_mcp_server_url,
             search=search,
         )
 
@@ -880,23 +902,43 @@ class ActionMcp:
         filter_id: Optional[str] = None,
         filter_provider: Optional[str] = None,
         filter_name: Optional[str] = None,
+        filter_mcp_server_url: Optional[str] = None,
         search: Optional[str] = None,
     ) -> ListMcpConfigsResponse:
         """List MCP configurations with optional pagination and filtering.
 
         Args:
             page_size: Maximum number of configs to include in the current page.
-            page_token: Cursor token returned by a previous `list_configs` call.
-            filter_id: Restrict results to a specific configuration identifier.
-            filter_provider: Restrict results to configs for a given provider slug.
-            filter_name: Restrict results to configs whose names match exactly.
-            search: Free-form search query applied to name field.
+                Defaults to the server-side default (typically 20).
+            page_token: Cursor token returned by a previous ``list_configs`` call.
+                Pass this to fetch the next page of results.
+            filter_id: Restrict results to a specific configuration by its Scalekit ID,
+                e.g. ``"cfg_01abc123"``.
+            filter_provider: Restrict results to configs for a given provider slug,
+                e.g. ``"github"`` or ``"google-calendar"``.
+            filter_name: Restrict results to configs whose name matches exactly,
+                e.g. ``"My GitHub Config"``.
+            filter_mcp_server_url: Restrict results to configs whose MCP server URL
+                matches this value, e.g. ``"https://mcp.example.com/sse"``.
+            search: Free-form search query applied to the config name field.
 
         Returns:
-            ListMcpConfigsResponse: Parsed wrapper around the proto response.
+            ListMcpConfigsResponse: Parsed wrapper around the proto response containing
+            a ``configs`` list, ``next_page_token``, and ``total_count``.
 
         Raises:
             ValueError: If an MCP client has not been configured on the action client.
+
+        Example::
+
+            page1 = client.actions.mcp.list_configs(page_size=10)
+            for cfg in page1.configs:
+                print(cfg.name, cfg.mcp_server_url)
+
+            if page1.next_page_token:
+                page2 = client.actions.mcp.list_configs(
+                    page_size=10, page_token=page1.next_page_token
+                )
         """
         client = self._client()
         result_tuple = client.list_configs(
@@ -905,6 +947,7 @@ class ActionMcp:
             filter_id=filter_id,
             filter_provider=filter_provider,
             filter_name=filter_name,
+            filter_mcp_server_url=filter_mcp_server_url,
             search=search,
         )
         return ListMcpConfigsResponse.from_proto(result_tuple[0])
@@ -1139,3 +1182,256 @@ class ActionMcp:
             include_auth_links=include_auth_links,
         )
         return GetMcpInstanceAuthStateResponse.from_proto(result_tuple[0])
+
+    def list_mcp_connected_accounts(
+        self,
+        config_id: str,
+        identifier: str,
+        include_auth_link: Optional[bool] = None,
+    ) -> ListMcpConnectedAccountsResponse:
+        """List the connected account auth state for all connections in an MCP config.
+
+        For each connection defined in the MCP configuration, this method returns the
+        current authorisation status of the end-user's connected account and,
+        optionally, a one-time link the user can open to authorise or re-authorise
+        the connection.
+
+        This is typically called server-side before serving MCP tool calls, to
+        determine whether the user still has valid credentials for every connector
+        the MCP config requires.
+
+        Args:
+            config_id: Scalekit ID of the MCP configuration to inspect,
+                e.g. ``"cfg_01abc123"``.
+            identifier: End-user identifier for whom to fetch auth state — usually
+                an email address or opaque user ID that was used when calling
+                ``ensure_instance``, e.g. ``"alice@example.com"``.
+            include_auth_link: When ``True``, every connected account in the response
+                will include an ``authentication_link`` regardless of its current
+                status. Set this to ``True`` when building a connected-account
+                integration page for an MCP server — it lets the end user see the
+                status of all their connections and authorise or re-authorise any of
+                them in one pass.
+
+                When ``False`` (default), ``authentication_link`` is omitted from
+                the response. If a connected account does not yet exist for a given
+                connection, ``connected_account_id`` will be an empty string. In
+                that situation you can either call ``get_authorization_link`` for
+                the specific connection or re-call this method with
+                ``include_auth_link=True``.
+
+                **Auth links are valid for 1 minute only** — generate them close
+                to the time you redirect the user.
+
+        Returns:
+            ListMcpConnectedAccountsResponse: Contains a ``connected_accounts`` list.
+            Each item is a :class:`McpConnectionAuthState` with fields:
+
+            - ``connection_name`` — slug of the connector (``"github"``)
+            - ``provider`` — OAuth provider (``"github"``)
+            - ``connected_account_id`` — Scalekit ID for the user's connected account;
+              empty string if no connected account exists yet for this connection
+            - ``connected_account_status`` — ``"active"``, ``"expired"``, or ``"disconnected"``
+            - ``authentication_link`` — auth/re-auth URL valid for 1 minute;
+              present for all connections when ``include_auth_link=True``,
+              otherwise omitted
+
+        Raises:
+            ValueError: If ``config_id`` or ``identifier`` is blank.
+
+        Example::
+
+            state = client.actions.mcp.list_mcp_connected_accounts(
+                config_id="cfg_01abc123",
+                identifier="alice@example.com",
+                include_auth_link=True,
+            )
+            for account in state.connected_accounts:
+                if account.connected_account_status != "active":
+                    print(
+                        f"{account.connection_name} needs auth: "
+                        f"{account.authentication_link}"
+                    )
+        """
+        if not config_id:
+            raise ValueError("config_id is required")
+        if not identifier:
+            raise ValueError("identifier is required")
+        result_tuple = self._client().list_mcp_connected_accounts(
+            config_id=config_id,
+            identifier=identifier,
+            include_auth_link=include_auth_link,
+        )
+        return ListMcpConnectedAccountsResponse.from_proto(result_tuple[0])
+
+    def create_session_token(
+        self,
+        mcp_config_id: str,
+        identifier: str,
+        expiry: Optional[timedelta] = None,
+    ) -> CreateMcpSessionTokenResponse:
+        """Create a short-lived session token for a user to access an MCP server.
+
+        The token is scoped to a specific MCP configuration and end-user. Pass it
+        as a ``Bearer`` token in the ``Authorization`` header when making requests
+        to the MCP server URL associated with the config.
+
+        Args:
+            mcp_config_id: Scalekit ID of the MCP configuration the token should
+                grant access to, e.g. ``"cfg_01abc123"``.
+            identifier: End-user identifier for whom the token is minted — typically
+                the same email or opaque ID used when calling ``ensure_instance``,
+                e.g. ``"alice@example.com"``.
+            expiry: Requested lifetime for the token as a Python ``timedelta``.
+                When omitted, the server-side default TTL is applied (typically
+                1 hour). Example values:
+
+                - ``timedelta(minutes=30)`` — 30-minute token
+                - ``timedelta(hours=8)``    — 8-hour token (work-day session)
+                - ``timedelta(days=1)``     — 24-hour token
+
+        Returns:
+            CreateMcpSessionTokenResponse: Contains:
+
+            - ``token`` (``str``) — opaque bearer token string.
+            - ``expires_at`` (``datetime``) — UTC datetime when the token expires.
+
+        Raises:
+            ValueError: If ``mcp_config_id`` or ``identifier`` is blank.
+
+        Example::
+
+            from datetime import timedelta
+
+            resp = client.actions.mcp.create_session_token(
+                mcp_config_id="cfg_01abc123",
+                identifier="alice@example.com",
+                expiry=timedelta(hours=8),
+            )
+
+            headers = {"Authorization": f"Bearer {resp.token}"}
+            # Use headers when calling the MCP server URL
+        """
+        if not mcp_config_id:
+            raise ValueError("mcp_config_id is required")
+        if not identifier:
+            raise ValueError("identifier is required")
+        result_tuple = self._client().create_session_token(
+            mcp_config_id=mcp_config_id,
+            identifier=identifier,
+            expiry=expiry,
+        )
+        return CreateMcpSessionTokenResponse.from_proto(result_tuple[0])
+
+
+class ActionProviders:
+    """Typed action layer over ProvidersClient for custom provider CRUD.
+
+    Accepts typed request objects and returns typed response objects.
+    Access via ActionClient.providers — do not instantiate directly.
+    """
+
+    def __init__(self, providers_client) -> None:
+        self._providers_client = providers_client
+
+    def create_custom_provider(
+        self,
+        request: CreateCustomProviderRequest,
+    ) -> CreateCustomProviderResponse:
+        """Create a new custom provider.
+
+        :param request: Request object containing display_name (required),
+                        proxy_url (required), and optional description,
+                        proxy_enabled, and auth_patterns.
+        :type request: CreateCustomProviderRequest
+
+        :returns: Response containing the created provider with its server-assigned
+                  identifier and all decoded auth_patterns.
+        :rtype: CreateCustomProviderResponse
+
+        :raises ScalekitBadRequestException: If required fields are missing or invalid.
+        :raises ScalekitConflictException: If a provider with the same name already exists.
+        """
+        result_tuple = self._providers_client.create_custom_provider(
+            display_name=request.display_name,
+            proxy_url=request.proxy_url,
+            proxy_enabled=request.proxy_enabled,
+            description=request.description,
+            auth_patterns=request.auth_patterns,
+        )
+        return CreateCustomProviderResponse.from_proto(result_tuple[0])
+
+    def update_custom_provider(
+        self,
+        request: UpdateCustomProviderRequest,
+    ) -> UpdateCustomProviderResponse:
+        """Update an existing custom provider.
+
+        Only fields set to a non-None value in the request are applied.
+        Fields left as None are ignored and their existing server values are kept.
+
+        :param request: Request object containing identifier (required) and any
+                        combination of display_name, description, proxy_url, and
+                        auth_patterns to update.
+        :type request: UpdateCustomProviderRequest
+
+        :returns: Response containing the provider's full state after the update.
+        :rtype: UpdateCustomProviderResponse
+
+        :raises ScalekitNotFoundException: If no provider with the given identifier exists.
+        :raises ScalekitBadRequestException: If any updated field value is invalid.
+        """
+        result_tuple = self._providers_client.update_custom_provider(
+            identifier=request.identifier,
+            display_name=request.display_name,
+            proxy_url=request.proxy_url,
+            description=request.description,
+            auth_patterns=request.auth_patterns,
+        )
+        return UpdateCustomProviderResponse.from_proto(result_tuple[0])
+
+    def list_providers(
+        self,
+        request: ListProvidersRequest,
+    ) -> ListProvidersResponse:
+        """List providers with optional filtering and pagination.
+
+        :param request: Request object with optional provider_type, page_size,
+                        page_token, and identifier filters. All fields are optional —
+                        an empty ListProvidersRequest() returns all providers.
+        :type request: ListProvidersRequest
+
+        :returns: Response containing a page of providers and a next_page_token
+                  for fetching subsequent pages.
+        :rtype: ListProvidersResponse
+        """
+        result_tuple = self._providers_client.list_providers(
+            page_size=request.page_size,
+            page_token=request.page_token,
+            provider_type=request.provider_type,
+            identifier=request.identifier,
+        )
+        return ListProvidersResponse.from_proto(result_tuple[0])
+
+    def delete_custom_provider(
+        self,
+        request: DeleteCustomProviderRequest,
+    ) -> DeleteCustomProviderResponse:
+        """Delete a custom provider by identifier.
+
+        Deletion is permanent. Returns an empty response on success. Any error
+        (provider not found, insufficient permissions) raises a
+        ScalekitServerException subclass before this method returns.
+
+        :param request: Request object containing the identifier of the provider
+                        to delete.
+        :type request: DeleteCustomProviderRequest
+
+        :returns: Empty response confirming deletion.
+        :rtype: DeleteCustomProviderResponse
+
+        :raises ScalekitNotFoundException: If no provider with the given identifier exists.
+        :raises ScalekitForbiddenException: If the caller lacks permission to delete.
+        """
+        result_tuple = self._providers_client.delete_custom_provider(request.identifier)
+        return DeleteCustomProviderResponse.from_proto(result_tuple[0])