feat: add MFA options to agent authentication workflow

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 89
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-8d66dbedea5b240936b338809f272568ca84a452fc13dbda835479f2ec068b41.yml
-openapi_spec_hash: 7c499bfce2e996f1fff5e7791cea390e
-config_hash: 2ee8c7057fa9b05cd0dabd23247c40ec
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-8e4a29d23d2882fcb0864606091790fd58bffa4f5d5c8d081052b72ad47b215b.yml
+openapi_spec_hash: fc82d930dad739ac01e3c2bddba7bf61
+config_hash: 3a5e36dfb245210cfd978f679b3641d2

README.md

@@ -11,7 +11,7 @@ It is generated with [Stainless](https://www.stainless.com/).
 
 ## Documentation
 
-The REST API documentation can be found on [docs.onkernel.com](https://docs.onkernel.com). The full API of this library can be found in [api.md](api.md).
+The REST API documentation can be found on [docs.kernel.com](https://docs.kernel.com). The full API of this library can be found in [api.md](api.md).
 
 ## Installation
 

src/kernel/_client.py

@@ -67,7 +67,7 @@
 ]
 
 ENVIRONMENTS: Dict[str, str] = {
-    "production": "https://api.onkernel.com/",
+    "production": "https://api.kernel.com/",
     "development": "https://localhost:3001/",
 }
 

src/kernel/resources/agents/auth/invocations.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from typing import Dict
-from typing_extensions import overload
+from typing_extensions import Literal, overload
 
 import httpx
 
@@ -233,13 +233,46 @@ def submit(
         """
         ...
 
-    @required_args(["field_values"], ["sso_button"])
+    @overload
+    def submit(
+        self,
+        invocation_id: str,
+        *,
+        selected_mfa_type: Literal["sms", "call", "email", "totp", "push", "security_key"],
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> AgentAuthSubmitResponse:
+        """Submits field values for the discovered login form.
+
+        Returns immediately after
+        submission is accepted. Poll the invocation endpoint to track progress and get
+        results.
+
+        Args:
+          selected_mfa_type: The MFA delivery method type
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        ...
+
+    @required_args(["field_values"], ["sso_button"], ["selected_mfa_type"])
     def submit(
         self,
         invocation_id: str,
         *,
         field_values: Dict[str, str] | Omit = omit,
         sso_button: str | Omit = omit,
+        selected_mfa_type: Literal["sms", "call", "email", "totp", "push", "security_key"] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -255,6 +288,7 @@ def submit(
                 {
                     "field_values": field_values,
                     "sso_button": sso_button,
+                    "selected_mfa_type": selected_mfa_type,
                 },
                 invocation_submit_params.InvocationSubmitParams,
             ),
@@ -471,13 +505,46 @@ async def submit(
         """
         ...
 
-    @required_args(["field_values"], ["sso_button"])
+    @overload
+    async def submit(
+        self,
+        invocation_id: str,
+        *,
+        selected_mfa_type: Literal["sms", "call", "email", "totp", "push", "security_key"],
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> AgentAuthSubmitResponse:
+        """Submits field values for the discovered login form.
+
+        Returns immediately after
+        submission is accepted. Poll the invocation endpoint to track progress and get
+        results.
+
+        Args:
+          selected_mfa_type: The MFA delivery method type
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        ...
+
+    @required_args(["field_values"], ["sso_button"], ["selected_mfa_type"])
     async def submit(
         self,
         invocation_id: str,
         *,
         field_values: Dict[str, str] | Omit = omit,
         sso_button: str | Omit = omit,
+        selected_mfa_type: Literal["sms", "call", "email", "totp", "push", "security_key"] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -493,6 +560,7 @@ async def submit(
                 {
                     "field_values": field_values,
                     "sso_button": sso_button,
+                    "selected_mfa_type": selected_mfa_type,
                 },
                 invocation_submit_params.InvocationSubmitParams,
             ),

src/kernel/types/agents/agent_auth_invocation_response.py

@@ -7,7 +7,23 @@
 from ..._models import BaseModel
 from .discovered_field import DiscoveredField
 
-__all__ = ["AgentAuthInvocationResponse", "PendingSSOButton"]
+__all__ = ["AgentAuthInvocationResponse", "MfaOption", "PendingSSOButton"]
+
+
+class MfaOption(BaseModel):
+    """An MFA method option for verification"""
+
+    label: str
+    """The visible option text"""
+
+    type: Literal["sms", "call", "email", "totp", "push", "security_key"]
+    """The MFA delivery method type"""
+
+    description: Optional[str] = None
+    """Additional instructions from the site"""
+
+    target: Optional[str] = None
+    """The masked destination (phone/email) if shown"""
 
 
 class PendingSSOButton(BaseModel):
@@ -63,6 +79,12 @@ class AgentAuthInvocationResponse(BaseModel):
     live_view_url: Optional[str] = None
     """Browser live view URL for debugging the invocation"""
 
+    mfa_options: Optional[List[MfaOption]] = None
+    """
+    MFA method options to choose from (present when step=awaiting_input and MFA
+    selection is required)
+    """
+
     pending_fields: Optional[List[DiscoveredField]] = None
     """Fields currently awaiting input (present when step=awaiting_input)"""
 

src/kernel/types/agents/auth/invocation_submit_params.py

@@ -3,9 +3,9 @@
 from __future__ import annotations
 
 from typing import Dict, Union
-from typing_extensions import Required, TypeAlias, TypedDict
+from typing_extensions import Literal, Required, TypeAlias, TypedDict
 
-__all__ = ["InvocationSubmitParams", "Variant0", "Variant1"]
+__all__ = ["InvocationSubmitParams", "Variant0", "Variant1", "Variant2"]
 
 
 class Variant0(TypedDict, total=False):
@@ -18,4 +18,9 @@ class Variant1(TypedDict, total=False):
     """Selector of SSO button to click"""
 
 
-InvocationSubmitParams: TypeAlias = Union[Variant0, Variant1]
+class Variant2(TypedDict, total=False):
+    selected_mfa_type: Required[Literal["sms", "call", "email", "totp", "push", "security_key"]]
+    """The MFA delivery method type"""
+
+
+InvocationSubmitParams: TypeAlias = Union[Variant0, Variant1, Variant2]

tests/api_resources/agents/auth/test_invocations.py

@@ -255,6 +255,52 @@ def test_path_params_submit_overload_2(self, client: Kernel) -> None:
                 sso_button="xpath=//button[contains(text(), 'Continue with Google')]",
             )
 
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    def test_method_submit_overload_3(self, client: Kernel) -> None:
+        invocation = client.agents.auth.invocations.submit(
+            invocation_id="invocation_id",
+            selected_mfa_type="sms",
+        )
+        assert_matches_type(AgentAuthSubmitResponse, invocation, path=["response"])
+
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    def test_raw_response_submit_overload_3(self, client: Kernel) -> None:
+        response = client.agents.auth.invocations.with_raw_response.submit(
+            invocation_id="invocation_id",
+            selected_mfa_type="sms",
+        )
+
+        assert response.is_closed is True
+        assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+        invocation = response.parse()
+        assert_matches_type(AgentAuthSubmitResponse, invocation, path=["response"])
+
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    def test_streaming_response_submit_overload_3(self, client: Kernel) -> None:
+        with client.agents.auth.invocations.with_streaming_response.submit(
+            invocation_id="invocation_id",
+            selected_mfa_type="sms",
+        ) as response:
+            assert not response.is_closed
+            assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+
+            invocation = response.parse()
+            assert_matches_type(AgentAuthSubmitResponse, invocation, path=["response"])
+
+        assert cast(Any, response.is_closed) is True
+
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    def test_path_params_submit_overload_3(self, client: Kernel) -> None:
+        with pytest.raises(ValueError, match=r"Expected a non-empty value for `invocation_id` but received ''"):
+            client.agents.auth.invocations.with_raw_response.submit(
+                invocation_id="",
+                selected_mfa_type="sms",
+            )
+
 
 class TestAsyncInvocations:
     parametrize = pytest.mark.parametrize(
@@ -495,3 +541,49 @@ async def test_path_params_submit_overload_2(self, async_client: AsyncKernel) ->
                 invocation_id="",
                 sso_button="xpath=//button[contains(text(), 'Continue with Google')]",
             )
+
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    async def test_method_submit_overload_3(self, async_client: AsyncKernel) -> None:
+        invocation = await async_client.agents.auth.invocations.submit(
+            invocation_id="invocation_id",
+            selected_mfa_type="sms",
+        )
+        assert_matches_type(AgentAuthSubmitResponse, invocation, path=["response"])
+
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    async def test_raw_response_submit_overload_3(self, async_client: AsyncKernel) -> None:
+        response = await async_client.agents.auth.invocations.with_raw_response.submit(
+            invocation_id="invocation_id",
+            selected_mfa_type="sms",
+        )
+
+        assert response.is_closed is True
+        assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+        invocation = await response.parse()
+        assert_matches_type(AgentAuthSubmitResponse, invocation, path=["response"])
+
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    async def test_streaming_response_submit_overload_3(self, async_client: AsyncKernel) -> None:
+        async with async_client.agents.auth.invocations.with_streaming_response.submit(
+            invocation_id="invocation_id",
+            selected_mfa_type="sms",
+        ) as response:
+            assert not response.is_closed
+            assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+
+            invocation = await response.parse()
+            assert_matches_type(AgentAuthSubmitResponse, invocation, path=["response"])
+
+        assert cast(Any, response.is_closed) is True
+
+    @pytest.mark.skip(reason="Prism tests are disabled")
+    @parametrize
+    async def test_path_params_submit_overload_3(self, async_client: AsyncKernel) -> None:
+        with pytest.raises(ValueError, match=r"Expected a non-empty value for `invocation_id` but received ''"):
+            await async_client.agents.auth.invocations.with_raw_response.submit(
+                invocation_id="",
+                selected_mfa_type="sms",
+            )

tests/test_client.py

@@ -578,7 +578,7 @@ def test_base_url_env(self) -> None:
                 Kernel(api_key=api_key, _strict_response_validation=True, environment="production")
 
             client = Kernel(base_url=None, api_key=api_key, _strict_response_validation=True, environment="production")
-            assert str(client.base_url).startswith("https://api.onkernel.com/")
+            assert str(client.base_url).startswith("https://api.kernel.com/")
 
             client.close()
 
@@ -1415,7 +1415,7 @@ async def test_base_url_env(self) -> None:
             client = AsyncKernel(
                 base_url=None, api_key=api_key, _strict_response_validation=True, environment="production"
             )
-            assert str(client.base_url).startswith("https://api.onkernel.com/")
+            assert str(client.base_url).startswith("https://api.kernel.com/")
 
             await client.close()