feat: enhance agent authentication API with new endpoints and request…

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 80
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-8a37652fa586b8932466d16285359a89988505f850787f8257d0c4c7053da173.yml
-openapi_spec_hash: 042765a113f6d08109e8146b302323ec
-config_hash: 113f1e5bc3567628a5d51c70bc00969d
+configured_endpoints: 82
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-b6957db438b01d979b62de21d4e674601b37d55b850b95a6e2b4c771aad5e840.yml
+openapi_spec_hash: 1c8aac8322bc9df8f1b82a7e7a0c692b
+config_hash: a4b4d14bdf6af723b235a6981977627c

api.md

@@ -255,15 +255,18 @@ Types:
 
 - <code><a href="./src/resources/agents/auth/auth.ts">AgentAuthDiscoverResponse</a></code>
 - <code><a href="./src/resources/agents/auth/auth.ts">AgentAuthInvocationResponse</a></code>
-- <code><a href="./src/resources/agents/auth/auth.ts">AgentAuthStartResponse</a></code>
 - <code><a href="./src/resources/agents/auth/auth.ts">AgentAuthSubmitResponse</a></code>
 - <code><a href="./src/resources/agents/auth/auth.ts">AuthAgent</a></code>
+- <code><a href="./src/resources/agents/auth/auth.ts">AuthAgentCreateRequest</a></code>
+- <code><a href="./src/resources/agents/auth/auth.ts">AuthAgentInvocationCreateRequest</a></code>
+- <code><a href="./src/resources/agents/auth/auth.ts">AuthAgentInvocationCreateResponse</a></code>
 - <code><a href="./src/resources/agents/auth/auth.ts">DiscoveredField</a></code>
 
 Methods:
 
+- <code title="post /agents/auth">client.agents.auth.<a href="./src/resources/agents/auth/auth.ts">create</a>({ ...params }) -> AuthAgent</code>
 - <code title="get /agents/auth/{id}">client.agents.auth.<a href="./src/resources/agents/auth/auth.ts">retrieve</a>(id) -> AuthAgent</code>
-- <code title="post /agents/auth/start">client.agents.auth.<a href="./src/resources/agents/auth/auth.ts">start</a>({ ...params }) -> AgentAuthStartResponse</code>
+- <code title="get /agents/auth">client.agents.auth.<a href="./src/resources/agents/auth/auth.ts">list</a>({ ...params }) -> AuthAgentsOffsetPagination</code>
 
 ### Invocations
 
@@ -273,6 +276,7 @@ Types:
 
 Methods:
 
+- <code title="post /agents/auth/invocations">client.agents.auth.invocations.<a href="./src/resources/agents/auth/invocations.ts">create</a>({ ...params }) -> AuthAgentInvocationCreateResponse</code>
 - <code title="get /agents/auth/invocations/{invocation_id}">client.agents.auth.invocations.<a href="./src/resources/agents/auth/invocations.ts">retrieve</a>(invocationID) -> AgentAuthInvocationResponse</code>
 - <code title="post /agents/auth/invocations/{invocation_id}/discover">client.agents.auth.invocations.<a href="./src/resources/agents/auth/invocations.ts">discover</a>(invocationID, { ...params }) -> AgentAuthDiscoverResponse</code>
 - <code title="post /agents/auth/invocations/{invocation_id}/exchange">client.agents.auth.invocations.<a href="./src/resources/agents/auth/invocations.ts">exchange</a>(invocationID, { ...params }) -> InvocationExchangeResponse</code>

src/resources/agents/agents.ts

@@ -5,11 +5,15 @@ import * as AuthAPI from './auth/auth';
 import {
   AgentAuthDiscoverResponse,
   AgentAuthInvocationResponse,
-  AgentAuthStartResponse,
   AgentAuthSubmitResponse,
   Auth,
   AuthAgent,
-  AuthStartParams,
+  AuthAgentCreateRequest,
+  AuthAgentInvocationCreateRequest,
+  AuthAgentInvocationCreateResponse,
+  AuthAgentsOffsetPagination,
+  AuthCreateParams,
+  AuthListParams,
   DiscoveredField,
 } from './auth/auth';
 
@@ -24,10 +28,14 @@ export declare namespace Agents {
     Auth as Auth,
     type AgentAuthDiscoverResponse as AgentAuthDiscoverResponse,
     type AgentAuthInvocationResponse as AgentAuthInvocationResponse,
-    type AgentAuthStartResponse as AgentAuthStartResponse,
     type AgentAuthSubmitResponse as AgentAuthSubmitResponse,
     type AuthAgent as AuthAgent,
+    type AuthAgentCreateRequest as AuthAgentCreateRequest,
+    type AuthAgentInvocationCreateRequest as AuthAgentInvocationCreateRequest,
+    type AuthAgentInvocationCreateResponse as AuthAgentInvocationCreateResponse,
     type DiscoveredField as DiscoveredField,
-    type AuthStartParams as AuthStartParams,
+    type AuthAgentsOffsetPagination as AuthAgentsOffsetPagination,
+    type AuthCreateParams as AuthCreateParams,
+    type AuthListParams as AuthListParams,
   };
 }

src/resources/agents/auth/auth.ts

@@ -3,19 +3,39 @@
 import { APIResource } from '../../../core/resource';
 import * as InvocationsAPI from './invocations';
 import {
+  InvocationCreateParams,
   InvocationDiscoverParams,
   InvocationExchangeParams,
   InvocationExchangeResponse,
   InvocationSubmitParams,
   Invocations,
 } from './invocations';
 import { APIPromise } from '../../../core/api-promise';
+import { OffsetPagination, type OffsetPaginationParams, PagePromise } from '../../../core/pagination';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
 export class Auth extends APIResource {
   invocations: InvocationsAPI.Invocations = new InvocationsAPI.Invocations(this._client);
 
+  /**
+   * Creates a new auth agent for the specified domain and profile combination, or
+   * returns an existing one if it already exists. This is idempotent - calling with
+   * the same domain and profile will return the same agent. Does NOT start an
+   * invocation - use POST /agents/auth/invocations to start an auth flow.
+   *
+   * @example
+   * ```ts
+   * const authAgent = await client.agents.auth.create({
+   *   profile_name: 'user-123',
+   *   target_domain: 'netflix.com',
+   * });
+   * ```
+   */
+  create(body: AuthCreateParams, options?: RequestOptions): APIPromise<AuthAgent> {
+    return this._client.post('/agents/auth', { body, ...options });
+  }
+
   /**
    * Retrieve an auth agent by its ID. Returns the current authentication status of
    * the managed profile.
@@ -30,24 +50,26 @@ export class Auth extends APIResource {
   }
 
   /**
-   * Creates a browser session and returns a handoff code for the hosted flow. Uses
-   * standard API key or JWT authentication (not the JWT returned by the exchange
-   * endpoint).
+   * List auth agents with optional filters for profile_name and target_domain.
    *
    * @example
    * ```ts
-   * const agentAuthStartResponse =
-   *   await client.agents.auth.start({
-   *     profile_name: 'auth-abc123',
-   *     target_domain: 'doordash.com',
-   *   });
+   * // Automatically fetches more pages as needed.
+   * for await (const authAgent of client.agents.auth.list()) {
+   *   // ...
+   * }
    * ```
    */
-  start(body: AuthStartParams, options?: RequestOptions): APIPromise<AgentAuthStartResponse> {
-    return this._client.post('/agents/auth/start', { body, ...options });
+  list(
+    query: AuthListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<AuthAgentsOffsetPagination, AuthAgent> {
+    return this._client.getAPIList('/agents/auth', OffsetPagination<AuthAgent>, { query, ...options });
   }
 }
 
+export type AuthAgentsOffsetPagination = OffsetPagination<AuthAgent>;
+
 /**
  * Response from discover endpoint matching AuthBlueprint schema
  */
@@ -108,36 +130,6 @@ export interface AgentAuthInvocationResponse {
   target_domain: string;
 }
 
-/**
- * Response from starting an agent authentication invocation
- */
-export interface AgentAuthStartResponse {
-  /**
-   * Unique identifier for the auth agent managing this domain/profile
-   */
-  auth_agent_id: string;
-
-  /**
-   * When the handoff code expires
-   */
-  expires_at: string;
-
-  /**
-   * One-time code for handoff
-   */
-  handoff_code: string;
-
-  /**
-   * URL to redirect user to
-   */
-  hosted_url: string;
-
-  /**
-   * Unique identifier for the invocation
-   */
-  invocation_id: string;
-}
-
 /**
  * Response from submit endpoint matching SubmitResult schema
  */
@@ -205,6 +197,79 @@ export interface AuthAgent {
   status: 'AUTHENTICATED' | 'NEEDS_AUTH';
 }
 
+/**
+ * Request to create or find an auth agent
+ */
+export interface AuthAgentCreateRequest {
+  /**
+   * Name of the profile to use for this auth agent
+   */
+  profile_name: string;
+
+  /**
+   * Target domain for authentication
+   */
+  target_domain: string;
+
+  /**
+   * Optional login page URL. If provided, will be stored on the agent and used to
+   * skip discovery in future invocations.
+   */
+  login_url?: string;
+
+  /**
+   * Optional proxy configuration
+   */
+  proxy?: AuthAgentCreateRequest.Proxy;
+}
+
+export namespace AuthAgentCreateRequest {
+  /**
+   * Optional proxy configuration
+   */
+  export interface Proxy {
+    /**
+     * ID of the proxy to use
+     */
+    proxy_id?: string;
+  }
+}
+
+/**
+ * Request to create an invocation for an existing auth agent
+ */
+export interface AuthAgentInvocationCreateRequest {
+  /**
+   * ID of the auth agent to create an invocation for
+   */
+  auth_agent_id: string;
+}
+
+/**
+ * Response from creating an auth agent invocation
+ */
+export interface AuthAgentInvocationCreateResponse {
+  /**
+   * When the handoff code expires
+   */
+  expires_at: string;
+
+  /**
+   * One-time code for handoff
+   */
+  handoff_code: string;
+
+  /**
+   * URL to redirect user to
+   */
+  hosted_url: string;
+
+  /**
+   * Unique identifier for the invocation
+   */
+  invocation_id: string;
+}
+
 /**
  * A discovered form field
  */
@@ -240,9 +305,9 @@ export interface DiscoveredField {
   required?: boolean;
 }
 
-export interface AuthStartParams {
+export interface AuthCreateParams {
   /**
-   * Name of the profile to use for this flow
+   * Name of the profile to use for this auth agent
    */
   profile_name: string;
 
@@ -251,24 +316,19 @@ export interface AuthStartParams {
    */
   target_domain: string;
 
-  /**
-   * Optional logo URL for the application
-   */
-  app_logo_url?: string;
-
   /**
    * Optional login page URL. If provided, will be stored on the agent and used to
-   * skip Phase 1 discovery in future invocations.
+   * skip discovery in future invocations.
    */
   login_url?: string;
 
   /**
    * Optional proxy configuration
    */
-  proxy?: AuthStartParams.Proxy;
+  proxy?: AuthCreateParams.Proxy;
 }
 
-export namespace AuthStartParams {
+export namespace AuthCreateParams {
   /**
    * Optional proxy configuration
    */
@@ -280,22 +340,39 @@ export namespace AuthStartParams {
   }
 }
 
+export interface AuthListParams extends OffsetPaginationParams {
+  /**
+   * Filter by profile name
+   */
+  profile_name?: string;
+
+  /**
+   * Filter by target domain
+   */
+  target_domain?: string;
+}
+
 Auth.Invocations = Invocations;
 
 export declare namespace Auth {
   export {
     type AgentAuthDiscoverResponse as AgentAuthDiscoverResponse,
     type AgentAuthInvocationResponse as AgentAuthInvocationResponse,
-    type AgentAuthStartResponse as AgentAuthStartResponse,
     type AgentAuthSubmitResponse as AgentAuthSubmitResponse,
     type AuthAgent as AuthAgent,
+    type AuthAgentCreateRequest as AuthAgentCreateRequest,
+    type AuthAgentInvocationCreateRequest as AuthAgentInvocationCreateRequest,
+    type AuthAgentInvocationCreateResponse as AuthAgentInvocationCreateResponse,
     type DiscoveredField as DiscoveredField,
-    type AuthStartParams as AuthStartParams,
+    type AuthAgentsOffsetPagination as AuthAgentsOffsetPagination,
+    type AuthCreateParams as AuthCreateParams,
+    type AuthListParams as AuthListParams,
   };
 
   export {
     Invocations as Invocations,
     type InvocationExchangeResponse as InvocationExchangeResponse,
+    type InvocationCreateParams as InvocationCreateParams,
     type InvocationDiscoverParams as InvocationDiscoverParams,
     type InvocationExchangeParams as InvocationExchangeParams,
     type InvocationSubmitParams as InvocationSubmitParams,

src/resources/agents/auth/index.ts

@@ -4,15 +4,20 @@ export {
   Auth,
   type AgentAuthDiscoverResponse,
   type AgentAuthInvocationResponse,
-  type AgentAuthStartResponse,
   type AgentAuthSubmitResponse,
   type AuthAgent,
+  type AuthAgentCreateRequest,
+  type AuthAgentInvocationCreateRequest,
+  type AuthAgentInvocationCreateResponse,
   type DiscoveredField,
-  type AuthStartParams,
+  type AuthCreateParams,
+  type AuthListParams,
+  type AuthAgentsOffsetPagination,
 } from './auth';
 export {
   Invocations,
   type InvocationExchangeResponse,
+  type InvocationCreateParams,
   type InvocationDiscoverParams,
   type InvocationExchangeParams,
   type InvocationSubmitParams,