feat: Add auth connection event timeline endpoint

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 123
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-ac06dd66a7a0da0dd6dd6cd98127652891b914e880dbaed90d7ab666b13af8a9.yml
-openapi_spec_hash: 1d35ae59d6570497f8b379ded59f0434
-config_hash: d52b040438a187c46050e0e8395b2f47
+configured_endpoints: 124
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-4fb45d71a99648425c84bdc8e5780920105cede4ee2d4eac67276d0609ac1e94.yml
+openapi_spec_hash: 1f04cb5b36e92db81dfa264c2a59c32a
+config_hash: fb167e754ebb3a14649463725891c9d0

api.md

@@ -300,6 +300,7 @@ from kernel.types.auth import (
     LoginResponse,
     ManagedAuth,
     ManagedAuthCreateRequest,
+    ManagedAuthTimelineEvent,
     ManagedAuthUpdateRequest,
     SubmitFieldsRequest,
     SubmitFieldsResponse,
@@ -317,6 +318,7 @@ Methods:
 - <code title="get /auth/connections/{id}/events">client.auth.connections.<a href="./src/kernel/resources/auth/connections.py">follow</a>(id) -> <a href="./src/kernel/types/auth/connection_follow_response.py">ConnectionFollowResponse</a></code>
 - <code title="post /auth/connections/{id}/login">client.auth.connections.<a href="./src/kernel/resources/auth/connections.py">login</a>(id, \*\*<a href="src/kernel/types/auth/connection_login_params.py">params</a>) -> <a href="./src/kernel/types/auth/login_response.py">LoginResponse</a></code>
 - <code title="post /auth/connections/{id}/submit">client.auth.connections.<a href="./src/kernel/resources/auth/connections.py">submit</a>(id, \*\*<a href="src/kernel/types/auth/connection_submit_params.py">params</a>) -> <a href="./src/kernel/types/auth/submit_fields_response.py">SubmitFieldsResponse</a></code>
+- <code title="get /auth/connections/{id}/timeline">client.auth.connections.<a href="./src/kernel/resources/auth/connections.py">timeline</a>(id, \*\*<a href="src/kernel/types/auth/connection_timeline_params.py">params</a>) -> <a href="./src/kernel/types/auth/managed_auth_timeline_event.py">SyncOffsetPagination[ManagedAuthTimelineEvent]</a></code>
 
 # Proxies
 

src/kernel/resources/auth/connections.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from typing import Any, Dict, cast
+from typing_extensions import Literal
 
 import httpx
 
@@ -24,12 +25,14 @@
     connection_create_params,
     connection_submit_params,
     connection_update_params,
+    connection_timeline_params,
 )
 from ..._base_client import AsyncPaginator, make_request_options
 from ...types.auth.managed_auth import ManagedAuth
 from ...types.auth.login_response import LoginResponse
 from ...types.auth.submit_fields_response import SubmitFieldsResponse
 from ...types.auth.connection_follow_response import ConnectionFollowResponse
+from ...types.auth.managed_auth_timeline_event import ManagedAuthTimelineEvent
 
 __all__ = ["ConnectionsResource", "AsyncConnectionsResource"]
 
@@ -554,6 +557,62 @@ def submit(
             cast_to=SubmitFieldsResponse,
         )
 
+    def timeline(
+        self,
+        id: str,
+        *,
+        limit: int | Omit = omit,
+        offset: int | Omit = omit,
+        type: Literal["login", "reauth", "health_check"] | 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,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> SyncOffsetPagination[ManagedAuthTimelineEvent]:
+        """
+        Returns a chronological timeline of events for an auth connection — login
+        attempts, automatic re-auth attempts, and health checks. Events are returned
+        newest-first.
+
+        Args:
+          limit: Maximum number of events to return
+
+          offset: Number of events to skip
+
+          type: Filter the timeline to a single event 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
+        """
+        if not id:
+            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
+        return self._get_api_list(
+            path_template("/auth/connections/{id}/timeline", id=id),
+            page=SyncOffsetPagination[ManagedAuthTimelineEvent],
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=maybe_transform(
+                    {
+                        "limit": limit,
+                        "offset": offset,
+                        "type": type,
+                    },
+                    connection_timeline_params.ConnectionTimelineParams,
+                ),
+            ),
+            model=ManagedAuthTimelineEvent,
+        )
+
 
 class AsyncConnectionsResource(AsyncAPIResource):
     """Create and manage auth connections for automated credential capture and login."""
@@ -1075,6 +1134,62 @@ async def submit(
             cast_to=SubmitFieldsResponse,
         )
 
+    def timeline(
+        self,
+        id: str,
+        *,
+        limit: int | Omit = omit,
+        offset: int | Omit = omit,
+        type: Literal["login", "reauth", "health_check"] | 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,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> AsyncPaginator[ManagedAuthTimelineEvent, AsyncOffsetPagination[ManagedAuthTimelineEvent]]:
+        """
+        Returns a chronological timeline of events for an auth connection — login
+        attempts, automatic re-auth attempts, and health checks. Events are returned
+        newest-first.
+
+        Args:
+          limit: Maximum number of events to return
+
+          offset: Number of events to skip
+
+          type: Filter the timeline to a single event 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
+        """
+        if not id:
+            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
+        return self._get_api_list(
+            path_template("/auth/connections/{id}/timeline", id=id),
+            page=AsyncOffsetPagination[ManagedAuthTimelineEvent],
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=maybe_transform(
+                    {
+                        "limit": limit,
+                        "offset": offset,
+                        "type": type,
+                    },
+                    connection_timeline_params.ConnectionTimelineParams,
+                ),
+            ),
+            model=ManagedAuthTimelineEvent,
+        )
+
 
 class ConnectionsResourceWithRawResponse:
     def __init__(self, connections: ConnectionsResource) -> None:
@@ -1104,6 +1219,9 @@ def __init__(self, connections: ConnectionsResource) -> None:
         self.submit = to_raw_response_wrapper(
             connections.submit,
         )
+        self.timeline = to_raw_response_wrapper(
+            connections.timeline,
+        )
 
 
 class AsyncConnectionsResourceWithRawResponse:
@@ -1134,6 +1252,9 @@ def __init__(self, connections: AsyncConnectionsResource) -> None:
         self.submit = async_to_raw_response_wrapper(
             connections.submit,
         )
+        self.timeline = async_to_raw_response_wrapper(
+            connections.timeline,
+        )
 
 
 class ConnectionsResourceWithStreamingResponse:
@@ -1164,6 +1285,9 @@ def __init__(self, connections: ConnectionsResource) -> None:
         self.submit = to_streamed_response_wrapper(
             connections.submit,
         )
+        self.timeline = to_streamed_response_wrapper(
+            connections.timeline,
+        )
 
 
 class AsyncConnectionsResourceWithStreamingResponse:
@@ -1194,3 +1318,6 @@ def __init__(self, connections: AsyncConnectionsResource) -> None:
         self.submit = async_to_streamed_response_wrapper(
             connections.submit,
         )
+        self.timeline = async_to_streamed_response_wrapper(
+            connections.timeline,
+        )

src/kernel/types/auth/__init__.py

@@ -11,3 +11,5 @@
 from .connection_submit_params import ConnectionSubmitParams as ConnectionSubmitParams
 from .connection_update_params import ConnectionUpdateParams as ConnectionUpdateParams
 from .connection_follow_response import ConnectionFollowResponse as ConnectionFollowResponse
+from .connection_timeline_params import ConnectionTimelineParams as ConnectionTimelineParams
+from .managed_auth_timeline_event import ManagedAuthTimelineEvent as ManagedAuthTimelineEvent

src/kernel/types/auth/connection_timeline_params.py

@@ -0,0 +1,18 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Literal, TypedDict
+
+__all__ = ["ConnectionTimelineParams"]
+
+
+class ConnectionTimelineParams(TypedDict, total=False):
+    limit: int
+    """Maximum number of events to return"""
+
+    offset: int
+    """Number of events to skip"""
+
+    type: Literal["login", "reauth", "health_check"]
+    """Filter the timeline to a single event type."""

src/kernel/types/auth/managed_auth_timeline_event.py

@@ -0,0 +1,77 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+from datetime import datetime
+from typing_extensions import Literal
+
+from ..._models import BaseModel
+
+__all__ = ["ManagedAuthTimelineEvent"]
+
+
+class ManagedAuthTimelineEvent(BaseModel):
+    """
+    A single event in an auth connection's history — a login attempt, an automatic re-auth attempt, or a health check.
+    """
+
+    id: str
+    """Identifier of the underlying login/reauth session or health check."""
+
+    status: Literal["IN_PROGRESS", "SUCCESS", "EXPIRED", "CANCELED", "FAILED", "AUTHENTICATED", "NEEDS_AUTH"]
+    """Outcome of the event.
+
+    For login/reauth events this is the flow status (IN_PROGRESS, SUCCESS, EXPIRED,
+    CANCELED, FAILED). For health_check events it is the observed session state
+    (AUTHENTICATED, NEEDS_AUTH).
+    """
+
+    timestamp: datetime
+    """When the event occurred."""
+
+    type: Literal["login", "reauth", "health_check"]
+    """The kind of event.
+
+    "login" and "reauth" are authentication attempts; "health_check" is a periodic
+    session-validity check.
+    """
+
+    error_code: Optional[str] = None
+    """Machine-readable error code. Present when a login/reauth event failed."""
+
+    error_message: Optional[str] = None
+    """Human-readable error message. Present when a login/reauth event failed."""
+
+    previous_status: Optional[Literal["AUTHENTICATED", "NEEDS_AUTH"]] = None
+    """The session state observed before this event.
+
+    Present for health_check events that recorded a prior state.
+    """
+
+    replay_id: Optional[str] = None
+    """
+    Replay recording ID for the event's browser session, if session recording was
+    enabled.
+    """
+
+    step: Optional[
+        Literal[
+            "INITIALIZED",
+            "DISCOVERING",
+            "AWAITING_INPUT",
+            "AWAITING_EXTERNAL_ACTION",
+            "AWAITING_HUMAN_INTERVENTION",
+            "SUBMITTING",
+            "COMPLETED",
+            "EXPIRED",
+        ]
+    ] = None
+    """The step the flow reached. Present for login/reauth events."""
+
+    updated_at: Optional[datetime] = None
+    """When the event was last updated. Present for login/reauth events."""
+
+    website_error: Optional[str] = None
+    """Visible error message from the website (e.g., 'Incorrect password').
+
+    Present when the website displayed an error during the attempt.
+    """