sessions.ts

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../resource';
import { isRequestOptions } from '../../core';
import * as Core from '../../core';
import * as DownloadsAPI from './downloads';
import { Downloads } from './downloads';
import * as LogsAPI from './logs';
import { LogListResponse, Logs, SessionLog } from './logs';
import * as RecordingAPI from './recording';
import { Recording, RecordingRetrieveResponse, SessionRecording } from './recording';
import * as UploadsAPI from './uploads';
import { UploadCreateParams, UploadCreateResponse, Uploads } from './uploads';

export class Sessions extends APIResource {
  downloads: DownloadsAPI.Downloads = new DownloadsAPI.Downloads(this._client);
  logs: LogsAPI.Logs = new LogsAPI.Logs(this._client);
  recording: RecordingAPI.Recording = new RecordingAPI.Recording(this._client);
  uploads: UploadsAPI.Uploads = new UploadsAPI.Uploads(this._client);

  /**
   * Create a Session
   */
  create(body: SessionCreateParams, options?: Core.RequestOptions): Core.APIPromise<SessionCreateResponse> {
    return this._client.post('/v1/sessions', { body, ...options });
  }

  /**
   * Session
   */
  retrieve(id: string, options?: Core.RequestOptions): Core.APIPromise<Session> {
    return this._client.get(`/v1/sessions/${id}`, options);
  }

  /**
   * Update Session
   */
  update(id: string, body: SessionUpdateParams, options?: Core.RequestOptions): Core.APIPromise<Session> {
    return this._client.post(`/v1/sessions/${id}`, { body, ...options });
  }

  /**
   * List Sessions
   */
  list(query?: SessionListParams, options?: Core.RequestOptions): Core.APIPromise<SessionListResponse>;
  list(options?: Core.RequestOptions): Core.APIPromise<SessionListResponse>;
  list(
    query: SessionListParams | Core.RequestOptions = {},
    options?: Core.RequestOptions,
  ): Core.APIPromise<SessionListResponse> {
    if (isRequestOptions(query)) {
      return this.list({}, query);
    }
    return this._client.get('/v1/sessions', { query, ...options });
  }

  /**
   * Session Live URLs
   */
  debug(id: string, options?: Core.RequestOptions): Core.APIPromise<SessionLiveURLs> {
    return this._client.get(`/v1/sessions/${id}/debug`, options);
  }
}

export interface Session {
  id: string;

  createdAt: string;

  expiresAt: string;

  /**
   * Indicates if the Session was created to be kept alive upon disconnections
   */
  keepAlive: boolean;

  /**
   * The Project ID linked to the Session.
   */
  projectId: string;

  /**
   * Bytes used via the [Proxy](/features/stealth-mode#proxies-and-residential-ips)
   */
  proxyBytes: number;

  /**
   * The region where the Session is running.
   */
  region: 'us-west-2' | 'us-east-1' | 'eu-central-1' | 'ap-southeast-1';

  startedAt: string;

  status: 'RUNNING' | 'ERROR' | 'TIMED_OUT' | 'COMPLETED';

  updatedAt: string;

  /**
   * CPU used by the Session
   */
  avgCpuUsage?: number;

  /**
   * Optional. The Context linked to the Session.
   */
  contextId?: string;

  endedAt?: string;

  /**
   * Memory used by the Session
   */
  memoryUsage?: number;

  /**
   * Arbitrary user metadata to attach to the session. To learn more about user
   * metadata, see [User Metadata](/features/sessions#user-metadata).
   */
  userMetadata?: Record<string, unknown>;
}

export interface SessionLiveURLs {
  debuggerFullscreenUrl: string;

  debuggerUrl: string;

  pages: Array<SessionLiveURLs.Page>;

  wsUrl: string;
}

export namespace SessionLiveURLs {
  export interface Page {
    id: string;

    debuggerFullscreenUrl: string;

    debuggerUrl: string;

    faviconUrl: string;

    title: string;

    url: string;
  }
}

export interface SessionCreateResponse {
  id: string;

  /**
   * WebSocket URL to connect to the Session.
   */
  connectUrl: string;

  createdAt: string;

  expiresAt: string;

  /**
   * Indicates if the Session was created to be kept alive upon disconnections
   */
  keepAlive: boolean;

  /**
   * The Project ID linked to the Session.
   */
  projectId: string;

  /**
   * Bytes used via the [Proxy](/features/stealth-mode#proxies-and-residential-ips)
   */
  proxyBytes: number;

  /**
   * The region where the Session is running.
   */
  region: 'us-west-2' | 'us-east-1' | 'eu-central-1' | 'ap-southeast-1';

  /**
   * HTTP URL to connect to the Session.
   */
  seleniumRemoteUrl: string;

  /**
   * Signing key to use when connecting to the Session via HTTP.
   */
  signingKey: string;

  startedAt: string;

  status: 'RUNNING' | 'ERROR' | 'TIMED_OUT' | 'COMPLETED';

  updatedAt: string;

  /**
   * CPU used by the Session
   */
  avgCpuUsage?: number;

  /**
   * Optional. The Context linked to the Session.
   */
  contextId?: string;

  endedAt?: string;

  /**
   * Memory used by the Session
   */
  memoryUsage?: number;

  /**
   * Arbitrary user metadata to attach to the session. To learn more about user
   * metadata, see [User Metadata](/features/sessions#user-metadata).
   */
  userMetadata?: Record<string, unknown>;
}

export type SessionListResponse = Array<Session>;

export interface SessionCreateParams {
  /**
   * The Project ID. Can be found in
   * [Settings](https://www.browserbase.com/settings).
   */
  projectId: string;

  browserSettings?: SessionCreateParams.BrowserSettings;

  /**
   * The uploaded Extension ID. See
   * [Upload Extension](/reference/api/upload-an-extension).
   */
  extensionId?: string;

  /**
   * Set to true to keep the session alive even after disconnections. This is
   * available on the Startup plan only.
   */
  keepAlive?: boolean;

  /**
   * Proxy configuration. Can be true for default proxy, or an array of proxy
   * configurations.
   */
  proxies?:
    | boolean
    | Array<SessionCreateParams.BrowserbaseProxyConfig | SessionCreateParams.ExternalProxyConfig>;

  /**
   * The region where the Session should run.
   */
  region?: 'us-west-2' | 'us-east-1' | 'eu-central-1' | 'ap-southeast-1';

  /**
   * Duration in seconds after which the session will automatically end. Defaults to
   * the Project's `defaultTimeout`.
   */
  timeout?: number;

  /**
   * Arbitrary user metadata to attach to the session. To learn more about user
   * metadata, see [User Metadata](/features/sessions#user-metadata).
   */
  userMetadata?: Record<string, unknown>;
}

export namespace SessionCreateParams {
  export interface BrowserSettings {
    /**
     * Advanced Browser Stealth Mode
     */
    advancedStealth?: boolean;

    /**
     * Enable or disable ad blocking in the browser. Defaults to `false`.
     */
    blockAds?: boolean;

    context?: BrowserSettings.Context;

    /**
     * The uploaded Extension ID. See
     * [Upload Extension](/reference/api/upload-an-extension).
     */
    extensionId?: string;

    /**
     * See usage examples
     * [in the Stealth Mode page](/features/stealth-mode#fingerprinting).
     */
    fingerprint?: BrowserSettings.Fingerprint;

    /**
     * Enable or disable session logging. Defaults to `true`.
     */
    logSession?: boolean;

    /**
     * Enable or disable session recording. Defaults to `true`.
     */
    recordSession?: boolean;

    /**
     * Enable or disable captcha solving in the browser. Defaults to `true`.
     */
    solveCaptchas?: boolean;

    viewport?: BrowserSettings.Viewport;
  }

  export namespace BrowserSettings {
    export interface Context {
      /**
       * The Context ID.
       */
      id: string;

      /**
       * Whether or not to persist the context after browsing. Defaults to `false`.
       */
      persist?: boolean;
    }

    /**
     * See usage examples
     * [in the Stealth Mode page](/features/stealth-mode#fingerprinting).
     */
    export interface Fingerprint {
      browsers?: Array<'chrome' | 'edge' | 'firefox' | 'safari'>;

      devices?: Array<'desktop' | 'mobile'>;

      httpVersion?: 1 | 2;

      /**
       * Full list of locales is available
       * [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).
       */
      locales?: Array<string>;

      /**
       * Note: `operatingSystems` set to `ios` or `android` requires `devices` to include
       * `"mobile"`.
       */
      operatingSystems?: Array<'android' | 'ios' | 'linux' | 'macos' | 'windows'>;

      screen?: Fingerprint.Screen;
    }

    export namespace Fingerprint {
      export interface Screen {
        maxHeight?: number;

        maxWidth?: number;

        minHeight?: number;

        minWidth?: number;
      }
    }

    export interface Viewport {
      height?: number;

      width?: number;
    }
  }

  export interface BrowserbaseProxyConfig {
    /**
     * Type of proxy. Always use 'browserbase' for the Browserbase managed proxy
     * network.
     */
    type: 'browserbase';

    /**
     * Domain pattern for which this proxy should be used. If omitted, defaults to all
     * domains. Optional.
     */
    domainPattern?: string;

    /**
     * Configuration for geolocation
     */
    geolocation?: BrowserbaseProxyConfig.Geolocation;
  }

  export namespace BrowserbaseProxyConfig {
    /**
     * Configuration for geolocation
     */
    export interface Geolocation {
      /**
       * Country code in ISO 3166-1 alpha-2 format
       */
      country: string;

      /**
       * Name of the city. Use spaces for multi-word city names. Optional.
       */
      city?: string;

      /**
       * US state code (2 characters). Must also specify US as the country. Optional.
       */
      state?: string;
    }
  }

  export interface ExternalProxyConfig {
    /**
     * Server URL for external proxy. Required.
     */
    server: string;

    /**
     * Type of proxy. Always 'external' for this config.
     */
    type: 'external';

    /**
     * Domain pattern for which this proxy should be used. If omitted, defaults to all
     * domains. Optional.
     */
    domainPattern?: string;

    /**
     * Password for external proxy authentication. Optional.
     */
    password?: string;

    /**
     * Username for external proxy authentication. Optional.
     */
    username?: string;
  }
}

export interface SessionUpdateParams {
  /**
   * The Project ID. Can be found in
   * [Settings](https://www.browserbase.com/settings).
   */
  projectId: string;

  /**
   * Set to `REQUEST_RELEASE` to request that the session complete. Use before
   * session's timeout to avoid additional charges.
   */
  status: 'REQUEST_RELEASE';
}

export interface SessionListParams {
  /**
   * Query sessions by user metadata. See
   * [Querying Sessions by User Metadata](/features/sessions#querying-sessions-by-user-metadata)
   * for the schema of this query.
   */
  q?: string;

  status?: 'RUNNING' | 'ERROR' | 'TIMED_OUT' | 'COMPLETED';
}

Sessions.Downloads = Downloads;
Sessions.Logs = Logs;
Sessions.Recording = Recording;
Sessions.Uploads = Uploads;

export declare namespace Sessions {
  export {
    type Session as Session,
    type SessionLiveURLs as SessionLiveURLs,
    type SessionCreateResponse as SessionCreateResponse,
    type SessionListResponse as SessionListResponse,
    type SessionCreateParams as SessionCreateParams,
    type SessionUpdateParams as SessionUpdateParams,
    type SessionListParams as SessionListParams,
  };

  export { Downloads as Downloads };

  export { Logs as Logs, type SessionLog as SessionLog, type LogListResponse as LogListResponse };

  export {
    Recording as Recording,
    type SessionRecording as SessionRecording,
    type RecordingRetrieveResponse as RecordingRetrieveResponse,
  };

  export {
    Uploads as Uploads,
    type UploadCreateResponse as UploadCreateResponse,
    type UploadCreateParams as UploadCreateParams,
  };
}