feat: Mason/agent auth api

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 66
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-2af1b468584cb44aa9babbbfb82bff4055614fbb5c815084a6b7dacc1cf1a822.yml
-openapi_spec_hash: 891affa2849341ea01d62011125f7edc
-config_hash: 9421eb86b7f3f4b274f123279da3858e
+configured_endpoints: 71
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-bb3f37e55117a56e7a4208bd646d3a68adeb651ced8531e13fbfc1fc9dcb05a4.yml
+openapi_spec_hash: 7303ce8ce3130e16a6a5c2bb49e43e9b
+config_hash: be146470fb2d4583b6533859f0fa48f5

api.md

@@ -220,3 +220,32 @@ Methods:
 - <code title="get /extensions/{id_or_name}">client.extensions.<a href="./src/resources/extensions.ts">download</a>(idOrName) -> Response</code>
 - <code title="get /extensions/from_chrome_store">client.extensions.<a href="./src/resources/extensions.ts">downloadFromChromeStore</a>({ ...params }) -> Response</code>
 - <code title="post /extensions">client.extensions.<a href="./src/resources/extensions.ts">upload</a>({ ...params }) -> ExtensionUploadResponse</code>
+
+# Agents
+
+## Auth
+
+Types:
+
+- <code><a href="./src/resources/agents/auth/auth.ts">AgentAuthDiscoverResponse</a></code>
+- <code><a href="./src/resources/agents/auth/auth.ts">AgentAuthRunResponse</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">DiscoveredField</a></code>
+
+Methods:
+
+- <code title="post /agents/auth/start">client.agents.auth.<a href="./src/resources/agents/auth/auth.ts">start</a>({ ...params }) -> AgentAuthStartResponse</code>
+
+### Runs
+
+Types:
+
+- <code><a href="./src/resources/agents/auth/runs.ts">RunExchangeResponse</a></code>
+
+Methods:
+
+- <code title="get /agents/auth/runs/{run_id}">client.agents.auth.runs.<a href="./src/resources/agents/auth/runs.ts">retrieve</a>(runID) -> AgentAuthRunResponse</code>
+- <code title="post /agents/auth/runs/{run_id}/discover">client.agents.auth.runs.<a href="./src/resources/agents/auth/runs.ts">discover</a>(runID) -> AgentAuthDiscoverResponse</code>
+- <code title="post /agents/auth/runs/{run_id}/exchange">client.agents.auth.runs.<a href="./src/resources/agents/auth/runs.ts">exchange</a>(runID, { ...params }) -> RunExchangeResponse</code>
+- <code title="post /agents/auth/runs/{run_id}/submit">client.agents.auth.runs.<a href="./src/resources/agents/auth/runs.ts">submit</a>(runID, { ...params }) -> AgentAuthSubmitResponse</code>

src/client.ts

@@ -61,6 +61,7 @@ import {
   ProxyListResponse,
   ProxyRetrieveResponse,
 } from './resources/proxies';
+import { Agents } from './resources/agents/agents';
 import {
   BrowserCreateParams,
   BrowserCreateResponse,
@@ -843,6 +844,7 @@ export class Kernel {
   profiles: API.Profiles = new API.Profiles(this);
   proxies: API.Proxies = new API.Proxies(this);
   extensions: API.Extensions = new API.Extensions(this);
+  agents: API.Agents = new API.Agents(this);
 }
 
 Kernel.Deployments = Deployments;
@@ -852,6 +854,7 @@ Kernel.Browsers = Browsers;
 Kernel.Profiles = Profiles;
 Kernel.Proxies = Proxies;
 Kernel.Extensions = Extensions;
+Kernel.Agents = Agents;
 
 export declare namespace Kernel {
   export type RequestOptions = Opts.RequestOptions;
@@ -933,6 +936,8 @@ export declare namespace Kernel {
     type ExtensionUploadParams as ExtensionUploadParams,
   };
 
+  export { Agents as Agents };
+
   export type AppAction = API.AppAction;
   export type ErrorDetail = API.ErrorDetail;
   export type ErrorEvent = API.ErrorEvent;

src/resources/agents.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './agents/index';

src/resources/agents/agents.ts

@@ -0,0 +1,31 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as AuthAPI from './auth/auth';
+import {
+  AgentAuthDiscoverResponse,
+  AgentAuthRunResponse,
+  AgentAuthStartResponse,
+  AgentAuthSubmitResponse,
+  Auth,
+  AuthStartParams,
+  DiscoveredField,
+} from './auth/auth';
+
+export class Agents extends APIResource {
+  auth: AuthAPI.Auth = new AuthAPI.Auth(this._client);
+}
+
+Agents.Auth = Auth;
+
+export declare namespace Agents {
+  export {
+    Auth as Auth,
+    type AgentAuthDiscoverResponse as AgentAuthDiscoverResponse,
+    type AgentAuthRunResponse as AgentAuthRunResponse,
+    type AgentAuthStartResponse as AgentAuthStartResponse,
+    type AgentAuthSubmitResponse as AgentAuthSubmitResponse,
+    type DiscoveredField as DiscoveredField,
+    type AuthStartParams as AuthStartParams,
+  };
+}

src/resources/agents/auth.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './auth/index';

src/resources/agents/auth/auth.ts

@@ -0,0 +1,245 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as RunsAPI from './runs';
+import { RunDiscoverParams, RunExchangeParams, RunExchangeResponse, RunSubmitParams, Runs } from './runs';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+
+export class Auth extends APIResource {
+  runs: RunsAPI.Runs = new RunsAPI.Runs(this._client);
+
+  /**
+   * 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).
+   *
+   * @example
+   * ```ts
+   * const agentAuthStartResponse =
+   *   await client.agents.auth.start({
+   *     profile_name: 'auth-abc123',
+   *     target_domain: 'doordash.com',
+   *   });
+   * ```
+   */
+  start(body: AuthStartParams, options?: RequestOptions): APIPromise<AgentAuthStartResponse> {
+    return this._client.post('/agents/auth/start', { body, ...options });
+  }
+}
+
+/**
+ * Response from discover endpoint matching AuthBlueprint schema
+ */
+export interface AgentAuthDiscoverResponse {
+  /**
+   * Whether discovery succeeded
+   */
+  success: boolean;
+
+  /**
+   * Error message if discovery failed
+   */
+  error_message?: string;
+
+  /**
+   * Discovered form fields (present when success is true)
+   */
+  fields?: Array<DiscoveredField>;
+
+  /**
+   * Whether user is already logged in
+   */
+  logged_in?: boolean;
+
+  /**
+   * URL of the discovered login page
+   */
+  login_url?: string;
+
+  /**
+   * Title of the login page
+   */
+  page_title?: string;
+}
+
+/**
+ * Response from get run endpoint
+ */
+export interface AgentAuthRunResponse {
+  /**
+   * App name (org name at time of run creation)
+   */
+  app_name: string;
+
+  /**
+   * When the handoff code expires
+   */
+  expires_at: string;
+
+  /**
+   * Run status
+   */
+  status: 'ACTIVE' | 'ENDED' | 'EXPIRED' | 'CANCELED';
+
+  /**
+   * Target domain for authentication
+   */
+  target_domain: string;
+}
+
+/**
+ * Response from starting an agent authentication run
+ */
+export interface AgentAuthStartResponse {
+  /**
+   * 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 run
+   */
+  run_id: string;
+}
+
+/**
+ * Response from submit endpoint matching SubmitResult schema
+ */
+export interface AgentAuthSubmitResponse {
+  /**
+   * Whether submission succeeded
+   */
+  success: boolean;
+
+  /**
+   * Additional fields needed (e.g., OTP) - present when needs_additional_auth is
+   * true
+   */
+  additional_fields?: Array<DiscoveredField>;
+
+  /**
+   * App name (only present when logged_in is true)
+   */
+  app_name?: string;
+
+  /**
+   * Error message if submission failed
+   */
+  error_message?: string;
+
+  /**
+   * Whether user is now logged in
+   */
+  logged_in?: boolean;
+
+  /**
+   * Whether additional authentication fields are needed
+   */
+  needs_additional_auth?: boolean;
+
+  /**
+   * Target domain (only present when logged_in is true)
+   */
+  target_domain?: string;
+}
+
+/**
+ * A discovered form field
+ */
+export interface DiscoveredField {
+  /**
+   * Field label
+   */
+  label: string;
+
+  /**
+   * Field name
+   */
+  name: string;
+
+  /**
+   * CSS selector for the field
+   */
+  selector: string;
+
+  /**
+   * Field type
+   */
+  type: 'text' | 'email' | 'password' | 'tel' | 'number' | 'url' | 'code' | 'checkbox';
+
+  /**
+   * Field placeholder
+   */
+  placeholder?: string;
+
+  /**
+   * Whether field is required
+   */
+  required?: boolean;
+}
+
+export interface AuthStartParams {
+  /**
+   * Name of the profile to use for this flow
+   */
+  profile_name: string;
+
+  /**
+   * Target domain for authentication
+   */
+  target_domain: string;
+
+  /**
+   * Optional logo URL for the application
+   */
+  app_logo_url?: string;
+
+  /**
+   * Optional proxy configuration
+   */
+  proxy?: AuthStartParams.Proxy;
+}
+
+export namespace AuthStartParams {
+  /**
+   * Optional proxy configuration
+   */
+  export interface Proxy {
+    /**
+     * ID of the proxy to use
+     */
+    proxy_id?: string;
+  }
+}
+
+Auth.Runs = Runs;
+
+export declare namespace Auth {
+  export {
+    type AgentAuthDiscoverResponse as AgentAuthDiscoverResponse,
+    type AgentAuthRunResponse as AgentAuthRunResponse,
+    type AgentAuthStartResponse as AgentAuthStartResponse,
+    type AgentAuthSubmitResponse as AgentAuthSubmitResponse,
+    type DiscoveredField as DiscoveredField,
+    type AuthStartParams as AuthStartParams,
+  };
+
+  export {
+    Runs as Runs,
+    type RunExchangeResponse as RunExchangeResponse,
+    type RunDiscoverParams as RunDiscoverParams,
+    type RunExchangeParams as RunExchangeParams,
+    type RunSubmitParams as RunSubmitParams,
+  };
+}

src/resources/agents/auth/index.ts

@@ -0,0 +1,18 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Auth,
+  type AgentAuthDiscoverResponse,
+  type AgentAuthRunResponse,
+  type AgentAuthStartResponse,
+  type AgentAuthSubmitResponse,
+  type DiscoveredField,
+  type AuthStartParams,
+} from './auth';
+export {
+  Runs,
+  type RunExchangeResponse,
+  type RunDiscoverParams,
+  type RunExchangeParams,
+  type RunSubmitParams,
+} from './runs';