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

@@ -265,6 +265,7 @@ Types:
 - <code><a href="./src/resources/auth/connections.ts">LoginResponse</a></code>
 - <code><a href="./src/resources/auth/connections.ts">ManagedAuth</a></code>
 - <code><a href="./src/resources/auth/connections.ts">ManagedAuthCreateRequest</a></code>
+- <code><a href="./src/resources/auth/connections.ts">ManagedAuthTimelineEvent</a></code>
 - <code><a href="./src/resources/auth/connections.ts">ManagedAuthUpdateRequest</a></code>
 - <code><a href="./src/resources/auth/connections.ts">SubmitFieldsRequest</a></code>
 - <code><a href="./src/resources/auth/connections.ts">SubmitFieldsResponse</a></code>
@@ -280,6 +281,7 @@ Methods:
 - <code title="get /auth/connections/{id}/events">client.auth.connections.<a href="./src/resources/auth/connections.ts">follow</a>(id) -> ConnectionFollowResponse</code>
 - <code title="post /auth/connections/{id}/login">client.auth.connections.<a href="./src/resources/auth/connections.ts">login</a>(id, { ...params }) -> LoginResponse</code>
 - <code title="post /auth/connections/{id}/submit">client.auth.connections.<a href="./src/resources/auth/connections.ts">submit</a>(id, { ...params }) -> SubmitFieldsResponse</code>
+- <code title="get /auth/connections/{id}/timeline">client.auth.connections.<a href="./src/resources/auth/connections.ts">timeline</a>(id, { ...params }) -> ManagedAuthTimelineEventsOffsetPagination</code>
 
 # Proxies
 

src/resources/auth/auth.ts

@@ -8,11 +8,14 @@ import {
   ConnectionListParams,
   ConnectionLoginParams,
   ConnectionSubmitParams,
+  ConnectionTimelineParams,
   ConnectionUpdateParams,
   Connections,
   LoginResponse,
   ManagedAuth,
   ManagedAuthCreateRequest,
+  ManagedAuthTimelineEvent,
+  ManagedAuthTimelineEventsOffsetPagination,
   ManagedAuthUpdateRequest,
   ManagedAuthsOffsetPagination,
   SubmitFieldsRequest,
@@ -31,15 +34,18 @@ export declare namespace Auth {
     type LoginResponse as LoginResponse,
     type ManagedAuth as ManagedAuth,
     type ManagedAuthCreateRequest as ManagedAuthCreateRequest,
+    type ManagedAuthTimelineEvent as ManagedAuthTimelineEvent,
     type ManagedAuthUpdateRequest as ManagedAuthUpdateRequest,
     type SubmitFieldsRequest as SubmitFieldsRequest,
     type SubmitFieldsResponse as SubmitFieldsResponse,
     type ConnectionFollowResponse as ConnectionFollowResponse,
     type ManagedAuthsOffsetPagination as ManagedAuthsOffsetPagination,
+    type ManagedAuthTimelineEventsOffsetPagination as ManagedAuthTimelineEventsOffsetPagination,
     type ConnectionCreateParams as ConnectionCreateParams,
     type ConnectionUpdateParams as ConnectionUpdateParams,
     type ConnectionListParams as ConnectionListParams,
     type ConnectionLoginParams as ConnectionLoginParams,
     type ConnectionSubmitParams as ConnectionSubmitParams,
+    type ConnectionTimelineParams as ConnectionTimelineParams,
   };
 }

src/resources/auth/connections.ts

@@ -152,10 +152,39 @@ export class Connections extends APIResource {
   ): APIPromise<SubmitFieldsResponse> {
     return this._client.post(path`/auth/connections/${id}/submit`, { body, ...options });
   }
+
+  /**
+   * Returns a chronological timeline of events for an auth connection — login
+   * attempts, automatic re-auth attempts, and health checks. Events are returned
+   * newest-first.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const managedAuthTimelineEvent of client.auth.connections.timeline(
+   *   'id',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  timeline(
+    id: string,
+    query: ConnectionTimelineParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<ManagedAuthTimelineEventsOffsetPagination, ManagedAuthTimelineEvent> {
+    return this._client.getAPIList(
+      path`/auth/connections/${id}/timeline`,
+      OffsetPagination<ManagedAuthTimelineEvent>,
+      { query, ...options },
+    );
+  }
 }
 
 export type ManagedAuthsOffsetPagination = OffsetPagination<ManagedAuth>;
 
+export type ManagedAuthTimelineEventsOffsetPagination = OffsetPagination<ManagedAuthTimelineEvent>;
+
 /**
  * Response from starting a login flow
  */
@@ -764,6 +793,81 @@ export namespace ManagedAuthCreateRequest {
   }
 }
 
+/**
+ * A single event in an auth connection's history — a login attempt, an automatic
+ * re-auth attempt, or a health check.
+ */
+export interface ManagedAuthTimelineEvent {
+  /**
+   * Identifier of the underlying login/reauth session or health check.
+   */
+  id: string;
+
+  /**
+   * 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).
+   */
+  status: 'IN_PROGRESS' | 'SUCCESS' | 'EXPIRED' | 'CANCELED' | 'FAILED' | 'AUTHENTICATED' | 'NEEDS_AUTH';
+
+  /**
+   * When the event occurred.
+   */
+  timestamp: string;
+
+  /**
+   * The kind of event. "login" and "reauth" are authentication attempts;
+   * "health_check" is a periodic session-validity check.
+   */
+  type: 'login' | 'reauth' | 'health_check';
+
+  /**
+   * Machine-readable error code. Present when a login/reauth event failed.
+   */
+  error_code?: string;
+
+  /**
+   * Human-readable error message. Present when a login/reauth event failed.
+   */
+  error_message?: string;
+
+  /**
+   * The session state observed before this event. Present for health_check events
+   * that recorded a prior state.
+   */
+  previous_status?: 'AUTHENTICATED' | 'NEEDS_AUTH';
+
+  /**
+   * Replay recording ID for the event's browser session, if session recording was
+   * enabled.
+   */
+  replay_id?: string;
+
+  /**
+   * The step the flow reached. Present for login/reauth events.
+   */
+  step?:
+    | 'INITIALIZED'
+    | 'DISCOVERING'
+    | 'AWAITING_INPUT'
+    | 'AWAITING_EXTERNAL_ACTION'
+    | 'AWAITING_HUMAN_INTERVENTION'
+    | 'SUBMITTING'
+    | 'COMPLETED'
+    | 'EXPIRED';
+
+  /**
+   * When the event was last updated. Present for login/reauth events.
+   */
+  updated_at?: string;
+
+  /**
+   * Visible error message from the website (e.g., 'Incorrect password'). Present
+   * when the website displayed an error during the attempt.
+   */
+  website_error?: string;
+}
+
 /**
  * Request to update an auth connection's configuration
  */
@@ -1466,20 +1570,30 @@ export interface ConnectionSubmitParams {
   sso_provider?: string;
 }
 
+export interface ConnectionTimelineParams extends OffsetPaginationParams {
+  /**
+   * Filter the timeline to a single event type.
+   */
+  type?: 'login' | 'reauth' | 'health_check';
+}
+
 export declare namespace Connections {
   export {
     type LoginResponse as LoginResponse,
     type ManagedAuth as ManagedAuth,
     type ManagedAuthCreateRequest as ManagedAuthCreateRequest,
+    type ManagedAuthTimelineEvent as ManagedAuthTimelineEvent,
     type ManagedAuthUpdateRequest as ManagedAuthUpdateRequest,
     type SubmitFieldsRequest as SubmitFieldsRequest,
     type SubmitFieldsResponse as SubmitFieldsResponse,
     type ConnectionFollowResponse as ConnectionFollowResponse,
     type ManagedAuthsOffsetPagination as ManagedAuthsOffsetPagination,
+    type ManagedAuthTimelineEventsOffsetPagination as ManagedAuthTimelineEventsOffsetPagination,
     type ConnectionCreateParams as ConnectionCreateParams,
     type ConnectionUpdateParams as ConnectionUpdateParams,
     type ConnectionListParams as ConnectionListParams,
     type ConnectionLoginParams as ConnectionLoginParams,
     type ConnectionSubmitParams as ConnectionSubmitParams,
+    type ConnectionTimelineParams as ConnectionTimelineParams,
   };
 }

src/resources/auth/index.ts

@@ -6,6 +6,7 @@ export {
   type LoginResponse,
   type ManagedAuth,
   type ManagedAuthCreateRequest,
+  type ManagedAuthTimelineEvent,
   type ManagedAuthUpdateRequest,
   type SubmitFieldsRequest,
   type SubmitFieldsResponse,
@@ -15,5 +16,7 @@ export {
   type ConnectionListParams,
   type ConnectionLoginParams,
   type ConnectionSubmitParams,
+  type ConnectionTimelineParams,
   type ManagedAuthsOffsetPagination,
+  type ManagedAuthTimelineEventsOffsetPagination,
 } from './connections';

tests/api-resources/auth/connections.test.ts

@@ -160,4 +160,32 @@ describe('resource connections', () => {
     expect(dataAndResponse.data).toBe(response);
     expect(dataAndResponse.response).toBe(rawResponse);
   });
+
+  // Mock server tests are disabled
+  test.skip('timeline', async () => {
+    const responsePromise = client.auth.connections.timeline('id');
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  // Mock server tests are disabled
+  test.skip('timeline: request options and params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(
+      client.auth.connections.timeline(
+        'id',
+        {
+          limit: 100,
+          offset: 0,
+          type: 'login',
+        },
+        { path: '/_stainless_unknown_path' },
+      ),
+    ).rejects.toThrow(Kernel.NotFoundError);
+  });
 });