feat: Enhance AuthAgentInvocationCreateResponse to include already_authenti…

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 82
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-dac11bdb857e700a8c39d183e753ddd1ebaaca69fd9fc5ee57d6b56b70b00e6e.yml
-openapi_spec_hash: 78fbc50dd0b61cdc87564fbea278ee23
-config_hash: a4b4d14bdf6af723b235a6981977627c
+configured_endpoints: 89
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-486d57f189abcec3a678ad4a619ee8a6b8aec3a3c2f3620c0423cb16cc755a13.yml
+openapi_spec_hash: affde047293fc74a8343a121d5e58a9c
+config_hash: 7225e7b7e4695c81d7be26c7108b5494

api.md

@@ -261,12 +261,15 @@ Types:
 - <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>
+- <code><a href="./src/resources/agents/auth/auth.ts">ReauthResponse</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="get /agents/auth">client.agents.auth.<a href="./src/resources/agents/auth/auth.ts">list</a>({ ...params }) -> AuthAgentsOffsetPagination</code>
+- <code title="delete /agents/auth/{id}">client.agents.auth.<a href="./src/resources/agents/auth/auth.ts">delete</a>(id) -> void</code>
+- <code title="post /agents/auth/{id}/reauth">client.agents.auth.<a href="./src/resources/agents/auth/auth.ts">reauth</a>(id) -> ReauthResponse</code>
 
 ### Invocations
 
@@ -281,3 +284,19 @@ Methods:
 - <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>
 - <code title="post /agents/auth/invocations/{invocation_id}/submit">client.agents.auth.invocations.<a href="./src/resources/agents/auth/invocations.ts">submit</a>(invocationID, { ...params }) -> AgentAuthSubmitResponse</code>
+
+# Credentials
+
+Types:
+
+- <code><a href="./src/resources/credentials.ts">CreateCredentialRequest</a></code>
+- <code><a href="./src/resources/credentials.ts">Credential</a></code>
+- <code><a href="./src/resources/credentials.ts">UpdateCredentialRequest</a></code>
+
+Methods:
+
+- <code title="post /credentials">client.credentials.<a href="./src/resources/credentials.ts">create</a>({ ...params }) -> Credential</code>
+- <code title="get /credentials/{id}">client.credentials.<a href="./src/resources/credentials.ts">retrieve</a>(id) -> Credential</code>
+- <code title="patch /credentials/{id}">client.credentials.<a href="./src/resources/credentials.ts">update</a>(id, { ...params }) -> Credential</code>
+- <code title="get /credentials">client.credentials.<a href="./src/resources/credentials.ts">list</a>({ ...params }) -> CredentialsOffsetPagination</code>
+- <code title="delete /credentials/{id}">client.credentials.<a href="./src/resources/credentials.ts">delete</a>(id) -> void</code>

src/client.ts

@@ -34,6 +34,16 @@ import {
   BrowserPoolUpdateRequest,
   BrowserPools,
 } from './resources/browser-pools';
+import {
+  CreateCredentialRequest,
+  Credential,
+  CredentialCreateParams,
+  CredentialListParams,
+  CredentialUpdateParams,
+  Credentials,
+  CredentialsOffsetPagination,
+  UpdateCredentialRequest,
+} from './resources/credentials';
 import {
   DeploymentCreateParams,
   DeploymentCreateResponse,
@@ -861,6 +871,7 @@ export class Kernel {
   extensions: API.Extensions = new API.Extensions(this);
   browserPools: API.BrowserPools = new API.BrowserPools(this);
   agents: API.Agents = new API.Agents(this);
+  credentials: API.Credentials = new API.Credentials(this);
 }
 
 Kernel.Deployments = Deployments;
@@ -872,6 +883,7 @@ Kernel.Proxies = Proxies;
 Kernel.Extensions = Extensions;
 Kernel.BrowserPools = BrowserPools;
 Kernel.Agents = Agents;
+Kernel.Credentials = Credentials;
 
 export declare namespace Kernel {
   export type RequestOptions = Opts.RequestOptions;
@@ -971,6 +983,17 @@ export declare namespace Kernel {
 
   export { Agents as Agents };
 
+  export {
+    Credentials as Credentials,
+    type CreateCredentialRequest as CreateCredentialRequest,
+    type Credential as Credential,
+    type UpdateCredentialRequest as UpdateCredentialRequest,
+    type CredentialsOffsetPagination as CredentialsOffsetPagination,
+    type CredentialCreateParams as CredentialCreateParams,
+    type CredentialUpdateParams as CredentialUpdateParams,
+    type CredentialListParams as CredentialListParams,
+  };
+
   export type AppAction = API.AppAction;
   export type BrowserExtension = API.BrowserExtension;
   export type BrowserProfile = API.BrowserProfile;

src/resources/agents/agents.ts

@@ -15,6 +15,7 @@ import {
   AuthCreateParams,
   AuthListParams,
   DiscoveredField,
+  ReauthResponse,
 } from './auth/auth';
 
 export class Agents extends APIResource {
@@ -34,6 +35,7 @@ export declare namespace Agents {
     type AuthAgentInvocationCreateRequest as AuthAgentInvocationCreateRequest,
     type AuthAgentInvocationCreateResponse as AuthAgentInvocationCreateResponse,
     type DiscoveredField as DiscoveredField,
+    type ReauthResponse as ReauthResponse,
     type AuthAgentsOffsetPagination as AuthAgentsOffsetPagination,
     type AuthCreateParams as AuthCreateParams,
     type AuthListParams as AuthListParams,

src/resources/agents/auth/auth.ts

@@ -12,6 +12,7 @@ import {
 } from './invocations';
 import { APIPromise } from '../../../core/api-promise';
 import { OffsetPagination, type OffsetPaginationParams, PagePromise } from '../../../core/pagination';
+import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
@@ -66,6 +67,42 @@ export class Auth extends APIResource {
   ): PagePromise<AuthAgentsOffsetPagination, AuthAgent> {
     return this._client.getAPIList('/agents/auth', OffsetPagination<AuthAgent>, { query, ...options });
   }
+
+  /**
+   * Deletes an auth agent and terminates its workflow. This will:
+   *
+   * - Soft delete the auth agent record
+   * - Gracefully terminate the agent's Temporal workflow
+   * - Cancel any in-progress invocations
+   *
+   * @example
+   * ```ts
+   * await client.agents.auth.delete('id');
+   * ```
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/agents/auth/${id}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Triggers automatic re-authentication for an auth agent using stored credentials.
+   * Requires the auth agent to have a linked credential, stored selectors, and
+   * login_url. Returns immediately with status indicating whether re-auth was
+   * started.
+   *
+   * @example
+   * ```ts
+   * const reauthResponse = await client.agents.auth.reauth(
+   *   'id',
+   * );
+   * ```
+   */
+  reauth(id: string, options?: RequestOptions): APIPromise<ReauthResponse> {
+    return this._client.post(path`/agents/auth/${id}/reauth`, options);
+  }
 }
 
 export type AuthAgentsOffsetPagination = OffsetPagination<AuthAgent>;
@@ -196,6 +233,27 @@ export interface AuthAgent {
    */
   status: 'AUTHENTICATED' | 'NEEDS_AUTH';
 
+  /**
+   * Whether automatic re-authentication is possible (has credential_id, selectors,
+   * and login_url)
+   */
+  can_reauth?: boolean;
+
+  /**
+   * ID of the linked credential for automatic re-authentication
+   */
+  credential_id?: string;
+
+  /**
+   * Name of the linked credential for automatic re-authentication
+   */
+  credential_name?: string;
+
+  /**
+   * Whether this auth agent has stored selectors for deterministic re-authentication
+   */
+  has_selectors?: boolean;
+
   /**
    * When the last authentication check was performed
    */
@@ -216,6 +274,13 @@ export interface AuthAgentCreateRequest {
    */
   target_domain: string;
 
+  /**
+   * Optional name of an existing credential to use for this auth agent. If provided,
+   * the credential will be linked to the agent and its values will be used to
+   * auto-fill the login form on invocation.
+   */
+  credential_name?: string;
+
   /**
    * Optional login page URL. If provided, will be stored on the agent and used to
    * skip discovery in future invocations.
@@ -248,31 +313,62 @@ export interface AuthAgentInvocationCreateRequest {
    * ID of the auth agent to create an invocation for
    */
   auth_agent_id: string;
+
+  /**
+   * If provided, saves the submitted credentials under this name upon successful
+   * login. The credential will be linked to the auth agent for automatic
+   * re-authentication.
+   */
+  save_credential_as?: string;
 }
 
 /**
- * Response from creating an auth agent invocation
+ * Response when the agent is already authenticated.
  */
-export interface AuthAgentInvocationCreateResponse {
-  /**
-   * When the handoff code expires
-   */
-  expires_at: string;
+export type AuthAgentInvocationCreateResponse =
+  | AuthAgentInvocationCreateResponse.AuthAgentAlreadyAuthenticated
+  | AuthAgentInvocationCreateResponse.AuthAgentInvocationCreated;
 
+export namespace AuthAgentInvocationCreateResponse {
   /**
-   * One-time code for handoff
+   * Response when the agent is already authenticated.
    */
-  handoff_code: string;
+  export interface AuthAgentAlreadyAuthenticated {
+    /**
+     * Indicates the agent is already authenticated and no invocation was created.
+     */
+    status: 'already_authenticated';
+  }
 
   /**
-   * URL to redirect user to
+   * Response when a new invocation was created.
    */
-  hosted_url: string;
+  export interface AuthAgentInvocationCreated {
+    /**
+     * When the handoff code expires.
+     */
+    expires_at: string;
 
-  /**
-   * Unique identifier for the invocation
-   */
-  invocation_id: 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;
+
+    /**
+     * Indicates an invocation was created.
+     */
+    status: 'invocation_created';
+  }
 }
 
 /**
@@ -310,6 +406,26 @@ export interface DiscoveredField {
   required?: boolean;
 }
 
+/**
+ * Response from triggering re-authentication
+ */
+export interface ReauthResponse {
+  /**
+   * Result of the re-authentication attempt
+   */
+  status: 'reauth_started' | 'already_authenticated' | 'cannot_reauth';
+
+  /**
+   * ID of the re-auth invocation if one was created
+   */
+  invocation_id?: string;
+
+  /**
+   * Human-readable description of the result
+   */
+  message?: string;
+}
+
 export interface AuthCreateParams {
   /**
    * Name of the profile to use for this auth agent
@@ -321,6 +437,13 @@ export interface AuthCreateParams {
    */
   target_domain: string;
 
+  /**
+   * Optional name of an existing credential to use for this auth agent. If provided,
+   * the credential will be linked to the agent and its values will be used to
+   * auto-fill the login form on invocation.
+   */
+  credential_name?: string;
+
   /**
    * Optional login page URL. If provided, will be stored on the agent and used to
    * skip discovery in future invocations.
@@ -369,6 +492,7 @@ export declare namespace Auth {
     type AuthAgentInvocationCreateRequest as AuthAgentInvocationCreateRequest,
     type AuthAgentInvocationCreateResponse as AuthAgentInvocationCreateResponse,
     type DiscoveredField as DiscoveredField,
+    type ReauthResponse as ReauthResponse,
     type AuthAgentsOffsetPagination as AuthAgentsOffsetPagination,
     type AuthCreateParams as AuthCreateParams,
     type AuthListParams as AuthListParams,

src/resources/agents/auth/index.ts

@@ -10,6 +10,7 @@ export {
   type AuthAgentInvocationCreateRequest,
   type AuthAgentInvocationCreateResponse,
   type DiscoveredField,
+  type ReauthResponse,
   type AuthCreateParams,
   type AuthListParams,
   type AuthAgentsOffsetPagination,

src/resources/agents/auth/invocations.ts

@@ -132,6 +132,13 @@ export interface InvocationCreateParams {
    * ID of the auth agent to create an invocation for
    */
   auth_agent_id: string;
+
+  /**
+   * If provided, saves the submitted credentials under this name upon successful
+   * login. The credential will be linked to the auth agent for automatic
+   * re-authentication.
+   */
+  save_credential_as?: string;
 }
 
 export interface InvocationDiscoverParams {

src/resources/agents/index.ts

@@ -11,6 +11,7 @@ export {
   type AuthAgentInvocationCreateRequest,
   type AuthAgentInvocationCreateResponse,
   type DiscoveredField,
+  type ReauthResponse,
   type AuthCreateParams,
   type AuthListParams,
   type AuthAgentsOffsetPagination,