@onkernel/sdk 0.22.0 → 0.24.0

package/src/resources/agents/auth/auth.ts

@@ -0,0 +1,509 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+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 { buildHeaders } from '../../../internal/headers';
+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.
+   *
+   * @example
+   * ```ts
+   * const authAgent = await client.agents.auth.retrieve('id');
+   * ```
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<AuthAgent> {
+    return this._client.get(path`/agents/auth/${id}`, options);
+  }
+
+  /**
+   * List auth agents with optional filters for profile_name and target_domain.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const authAgent of client.agents.auth.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: AuthListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): 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>;
+
+/**
+ * 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 invocation endpoint
+ */
+export interface AgentAuthInvocationResponse {
+  /**
+   * App name (org name at time of invocation creation)
+   */
+  app_name: string;
+
+  /**
+   * When the handoff code expires
+   */
+  expires_at: string;
+
+  /**
+   * Invocation status
+   */
+  status: 'IN_PROGRESS' | 'SUCCESS' | 'EXPIRED' | 'CANCELED';
+
+  /**
+   * Target domain for authentication
+   */
+  target_domain: 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;
+}
+
+/**
+ * An auth agent that manages authentication for a specific domain and profile
+ * combination
+ */
+export interface AuthAgent {
+  /**
+   * Unique identifier for the auth agent
+   */
+  id: string;
+
+  /**
+   * Target domain for authentication
+   */
+  domain: string;
+
+  /**
+   * Name of the profile associated with this auth agent
+   */
+  profile_name: string;
+
+  /**
+   * Current authentication status of the managed profile
+   */
+  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
+   */
+  last_auth_check_at?: string;
+}
+
+/**
+ * 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 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.
+   */
+  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;
+
+  /**
+   * 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 when the agent is already authenticated.
+ */
+export type AuthAgentInvocationCreateResponse =
+  | AuthAgentInvocationCreateResponse.AuthAgentAlreadyAuthenticated
+  | AuthAgentInvocationCreateResponse.AuthAgentInvocationCreated;
+
+export namespace AuthAgentInvocationCreateResponse {
+  /**
+   * Response when the agent is already authenticated.
+   */
+  export interface AuthAgentAlreadyAuthenticated {
+    /**
+     * Indicates the agent is already authenticated and no invocation was created.
+     */
+    status: 'already_authenticated';
+  }
+
+  /**
+   * Response when a new invocation was created.
+   */
+  export interface AuthAgentInvocationCreated {
+    /**
+     * 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;
+
+    /**
+     * Indicates an invocation was created.
+     */
+    status: 'invocation_created';
+  }
+}
+
+/**
+ * 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';
+
+  /**
+   * Field placeholder
+   */
+  placeholder?: string;
+
+  /**
+   * Whether field is required
+   */
+  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
+   */
+  profile_name: string;
+
+  /**
+   * Target domain for authentication
+   */
+  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.
+   */
+  login_url?: string;
+
+  /**
+   * Optional proxy configuration
+   */
+  proxy?: AuthCreateParams.Proxy;
+}
+
+export namespace AuthCreateParams {
+  /**
+   * Optional proxy configuration
+   */
+  export interface Proxy {
+    /**
+     * ID of the proxy to use
+     */
+    proxy_id?: string;
+  }
+}
+
+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 AgentAuthSubmitResponse as AgentAuthSubmitResponse,
+    type AuthAgent as AuthAgent,
+    type AuthAgentCreateRequest as AuthAgentCreateRequest,
+    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,
+  };
+
+  export {
+    Invocations as Invocations,
+    type InvocationExchangeResponse as InvocationExchangeResponse,
+    type InvocationCreateParams as InvocationCreateParams,
+    type InvocationDiscoverParams as InvocationDiscoverParams,
+    type InvocationExchangeParams as InvocationExchangeParams,
+    type InvocationSubmitParams as InvocationSubmitParams,
+  };
+}

package/src/resources/agents/auth/index.ts

@@ -0,0 +1,25 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Auth,
+  type AgentAuthDiscoverResponse,
+  type AgentAuthInvocationResponse,
+  type AgentAuthSubmitResponse,
+  type AuthAgent,
+  type AuthAgentCreateRequest,
+  type AuthAgentInvocationCreateRequest,
+  type AuthAgentInvocationCreateResponse,
+  type DiscoveredField,
+  type ReauthResponse,
+  type AuthCreateParams,
+  type AuthListParams,
+  type AuthAgentsOffsetPagination,
+} from './auth';
+export {
+  Invocations,
+  type InvocationExchangeResponse,
+  type InvocationCreateParams,
+  type InvocationDiscoverParams,
+  type InvocationExchangeParams,
+  type InvocationSubmitParams,
+} from './invocations';

package/src/resources/agents/auth/invocations.ts

@@ -0,0 +1,174 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as AuthAPI from './auth';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+export class Invocations extends APIResource {
+  /**
+   * Creates a new authentication invocation for the specified auth agent. This
+   * starts the auth flow and returns a hosted URL for the user to complete
+   * authentication.
+   *
+   * @example
+   * ```ts
+   * const authAgentInvocationCreateResponse =
+   *   await client.agents.auth.invocations.create({
+   *     auth_agent_id: 'abc123xyz',
+   *   });
+   * ```
+   */
+  create(
+    body: InvocationCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<AuthAPI.AuthAgentInvocationCreateResponse> {
+    return this._client.post('/agents/auth/invocations', { body, ...options });
+  }
+
+  /**
+   * Returns invocation details including app_name and target_domain. Uses the JWT
+   * returned by the exchange endpoint, or standard API key or JWT authentication.
+   *
+   * @example
+   * ```ts
+   * const agentAuthInvocationResponse =
+   *   await client.agents.auth.invocations.retrieve(
+   *     'invocation_id',
+   *   );
+   * ```
+   */
+  retrieve(invocationID: string, options?: RequestOptions): APIPromise<AuthAPI.AgentAuthInvocationResponse> {
+    return this._client.get(path`/agents/auth/invocations/${invocationID}`, options);
+  }
+
+  /**
+   * Inspects the target site to detect logged-in state or discover required fields.
+   * Returns 200 with success: true when fields are found, or 4xx/5xx for failures.
+   * Requires the JWT returned by the exchange endpoint.
+   *
+   * @example
+   * ```ts
+   * const agentAuthDiscoverResponse =
+   *   await client.agents.auth.invocations.discover(
+   *     'invocation_id',
+   *   );
+   * ```
+   */
+  discover(
+    invocationID: string,
+    body: InvocationDiscoverParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<AuthAPI.AgentAuthDiscoverResponse> {
+    return this._client.post(path`/agents/auth/invocations/${invocationID}/discover`, { body, ...options });
+  }
+
+  /**
+   * Validates the handoff code and returns a JWT token for subsequent requests. No
+   * authentication required (the handoff code serves as the credential).
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.agents.auth.invocations.exchange(
+   *     'invocation_id',
+   *     { code: 'abc123xyz' },
+   *   );
+   * ```
+   */
+  exchange(
+    invocationID: string,
+    body: InvocationExchangeParams,
+    options?: RequestOptions,
+  ): APIPromise<InvocationExchangeResponse> {
+    return this._client.post(path`/agents/auth/invocations/${invocationID}/exchange`, { body, ...options });
+  }
+
+  /**
+   * Submits field values for the discovered login form and may return additional
+   * auth fields or success. Requires the JWT returned by the exchange endpoint.
+   *
+   * @example
+   * ```ts
+   * const agentAuthSubmitResponse =
+   *   await client.agents.auth.invocations.submit(
+   *     'invocation_id',
+   *     {
+   *       field_values: {
+   *         email: 'user@example.com',
+   *         password: '********',
+   *       },
+   *     },
+   *   );
+   * ```
+   */
+  submit(
+    invocationID: string,
+    body: InvocationSubmitParams,
+    options?: RequestOptions,
+  ): APIPromise<AuthAPI.AgentAuthSubmitResponse> {
+    return this._client.post(path`/agents/auth/invocations/${invocationID}/submit`, { body, ...options });
+  }
+}
+
+/**
+ * Response from exchange endpoint
+ */
+export interface InvocationExchangeResponse {
+  /**
+   * Invocation ID
+   */
+  invocation_id: string;
+
+  /**
+   * JWT token with invocation_id claim (30 minute TTL)
+   */
+  jwt: string;
+}
+
+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 {
+  /**
+   * Optional login page URL. If provided, will override the stored login URL for
+   * this discovery invocation and skip Phase 1 discovery.
+   */
+  login_url?: string;
+}
+
+export interface InvocationExchangeParams {
+  /**
+   * Handoff code from start endpoint
+   */
+  code: string;
+}
+
+export interface InvocationSubmitParams {
+  /**
+   * Values for the discovered login fields
+   */
+  field_values: { [key: string]: string };
+}
+
+export declare namespace Invocations {
+  export {
+    type InvocationExchangeResponse as InvocationExchangeResponse,
+    type InvocationCreateParams as InvocationCreateParams,
+    type InvocationDiscoverParams as InvocationDiscoverParams,
+    type InvocationExchangeParams as InvocationExchangeParams,
+    type InvocationSubmitParams as InvocationSubmitParams,
+  };
+}

package/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';