feat(api): adding support for browser profiles

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 41
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-a7c1df5070fe59642d7a1f168aa902a468227752bfc930cbf38930f7c205dbb6.yml
-openapi_spec_hash: eab65e39aef4f0a0952b82adeecf6b5b
-config_hash: 5de78bc29ac060562575cb54bb26826c
+configured_endpoints: 46
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-e98d46c55826cdf541a9ee0df04ce92806ac6d4d92957ae79f897270b7d85b23.yml
+openapi_spec_hash: 8a1af54fc0a4417165b8a52e6354b685
+config_hash: 043ddc54629c6d8b889123770cb4769f

api.md

@@ -59,6 +59,7 @@ Methods:
 Types:
 
 - <code><a href="./src/resources/browsers/browsers.ts">BrowserPersistence</a></code>
+- <code><a href="./src/resources/browsers/browsers.ts">Profile</a></code>
 - <code><a href="./src/resources/browsers/browsers.ts">BrowserCreateResponse</a></code>
 - <code><a href="./src/resources/browsers/browsers.ts">BrowserRetrieveResponse</a></code>
 - <code><a href="./src/resources/browsers/browsers.ts">BrowserListResponse</a></code>
@@ -145,3 +146,17 @@ Methods:
 Methods:
 
 - <code title="get /browsers/{id}/logs/stream">client.browsers.logs.<a href="./src/resources/browsers/logs.ts">stream</a>(id, { ...params }) -> LogEvent</code>
+
+# Profiles
+
+Types:
+
+- <code><a href="./src/resources/profiles.ts">ProfileListResponse</a></code>
+
+Methods:
+
+- <code title="post /profiles">client.profiles.<a href="./src/resources/profiles.ts">create</a>({ ...params }) -> Profile</code>
+- <code title="get /profiles/{id_or_name}">client.profiles.<a href="./src/resources/profiles.ts">retrieve</a>(idOrName) -> Profile</code>
+- <code title="get /profiles">client.profiles.<a href="./src/resources/profiles.ts">list</a>() -> ProfileListResponse</code>
+- <code title="delete /profiles/{id_or_name}">client.profiles.<a href="./src/resources/profiles.ts">delete</a>(idOrName) -> void</code>
+- <code title="get /profiles/{id_or_name}/download">client.profiles.<a href="./src/resources/profiles.ts">download</a>(idOrName) -> Response</code>

src/client.ts

@@ -39,6 +39,7 @@ import {
   InvocationUpdateResponse,
   Invocations,
 } from './resources/invocations';
+import { ProfileCreateParams, ProfileListResponse, Profiles } from './resources/profiles';
 import {
   BrowserCreateParams,
   BrowserCreateResponse,
@@ -47,6 +48,7 @@ import {
   BrowserPersistence,
   BrowserRetrieveResponse,
   Browsers,
+  Profile,
 } from './resources/browsers/browsers';
 import { type Fetch } from './internal/builtin-types';
 import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
@@ -795,12 +797,14 @@ export class Kernel {
   apps: API.Apps = new API.Apps(this);
   invocations: API.Invocations = new API.Invocations(this);
   browsers: API.Browsers = new API.Browsers(this);
+  profiles: API.Profiles = new API.Profiles(this);
 }
 
 Kernel.Deployments = Deployments;
 Kernel.Apps = Apps;
 Kernel.Invocations = Invocations;
 Kernel.Browsers = Browsers;
+Kernel.Profiles = Profiles;
 
 export declare namespace Kernel {
   export type RequestOptions = Opts.RequestOptions;
@@ -833,13 +837,20 @@ export declare namespace Kernel {
   export {
     Browsers as Browsers,
     type BrowserPersistence as BrowserPersistence,
+    type Profile as Profile,
     type BrowserCreateResponse as BrowserCreateResponse,
     type BrowserRetrieveResponse as BrowserRetrieveResponse,
     type BrowserListResponse as BrowserListResponse,
     type BrowserCreateParams as BrowserCreateParams,
     type BrowserDeleteParams as BrowserDeleteParams,
   };
 
+  export {
+    Profiles as Profiles,
+    type ProfileListResponse as ProfileListResponse,
+    type ProfileCreateParams as ProfileCreateParams,
+  };
+
   export type AppAction = API.AppAction;
   export type ErrorDetail = API.ErrorDetail;
   export type ErrorEvent = API.ErrorEvent;

src/resources/browsers/browsers.ts

@@ -146,6 +146,36 @@ export interface BrowserPersistence {
   id: string;
 }
 
+/**
+ * Browser profile metadata.
+ */
+export interface Profile {
+  /**
+   * Unique identifier for the profile
+   */
+  id: string;
+
+  /**
+   * Timestamp when the profile was created
+   */
+  created_at: string;
+
+  /**
+   * Timestamp when the profile was last used
+   */
+  last_used_at?: string;
+
+  /**
+   * Optional, easier-to-reference name for the profile
+   */
+  name?: string | null;
+
+  /**
+   * Timestamp when the profile was last updated
+   */
+  updated_at?: string;
+}
+
 export interface BrowserCreateResponse {
   /**
    * Websocket URL for Chrome DevTools Protocol connections to the browser session
@@ -187,6 +217,11 @@ export interface BrowserCreateResponse {
    * Optional persistence configuration for the browser session.
    */
   persistence?: BrowserPersistence;
+
+  /**
+   * Browser profile metadata.
+   */
+  profile?: Profile;
 }
 
 export interface BrowserRetrieveResponse {
@@ -230,6 +265,11 @@ export interface BrowserRetrieveResponse {
    * Optional persistence configuration for the browser session.
    */
   persistence?: BrowserPersistence;
+
+  /**
+   * Browser profile metadata.
+   */
+  profile?: Profile;
 }
 
 export type BrowserListResponse = Array<BrowserListResponse.BrowserListResponseItem>;
@@ -276,6 +316,11 @@ export namespace BrowserListResponse {
      * Optional persistence configuration for the browser session.
      */
     persistence?: BrowsersAPI.BrowserPersistence;
+
+    /**
+     * Browser profile metadata.
+     */
+    profile?: BrowsersAPI.Profile;
   }
 }
 
@@ -296,6 +341,13 @@ export interface BrowserCreateParams {
    */
   persistence?: BrowserPersistence;
 
+  /**
+   * Profile selection for the browser session. Provide either id or name. If
+   * specified, the matching profile will be loaded into the browser session.
+   * Profiles must be created beforehand.
+   */
+  profile?: BrowserCreateParams.Profile;
+
   /**
    * If true, launches the browser in stealth mode to reduce detection by anti-bot
    * mechanisms.
@@ -310,6 +362,32 @@ export interface BrowserCreateParams {
   timeout_seconds?: number;
 }
 
+export namespace BrowserCreateParams {
+  /**
+   * Profile selection for the browser session. Provide either id or name. If
+   * specified, the matching profile will be loaded into the browser session.
+   * Profiles must be created beforehand.
+   */
+  export interface Profile {
+    /**
+     * Profile ID to load for this browser session
+     */
+    id?: string;
+
+    /**
+     * Profile name to load for this browser session (instead of id). Must be 1-255
+     * characters, using letters, numbers, dots, underscores, or hyphens.
+     */
+    name?: string;
+
+    /**
+     * If true, save changes made during the session back to the profile when the
+     * session ends.
+     */
+    save_changes?: boolean;
+  }
+}
+
 export interface BrowserDeleteParams {
   /**
    * Persistent browser identifier
@@ -325,6 +403,7 @@ Browsers.Logs = Logs;
 export declare namespace Browsers {
   export {
     type BrowserPersistence as BrowserPersistence,
+    type Profile as Profile,
     type BrowserCreateResponse as BrowserCreateResponse,
     type BrowserRetrieveResponse as BrowserRetrieveResponse,
     type BrowserListResponse as BrowserListResponse,

src/resources/browsers/index.ts

@@ -3,6 +3,7 @@
 export {
   Browsers,
   type BrowserPersistence,
+  type Profile,
   type BrowserCreateResponse,
   type BrowserRetrieveResponse,
   type BrowserListResponse,

src/resources/index.ts

@@ -5,6 +5,7 @@ export { Apps, type AppListResponse, type AppListParams } from './apps';
 export {
   Browsers,
   type BrowserPersistence,
+  type Profile,
   type BrowserCreateResponse,
   type BrowserRetrieveResponse,
   type BrowserListResponse,
@@ -32,3 +33,4 @@ export {
   type InvocationCreateParams,
   type InvocationUpdateParams,
 } from './invocations';
+export { Profiles, type ProfileListResponse, type ProfileCreateParams } from './profiles';

src/resources/profiles.ts

@@ -0,0 +1,67 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as BrowsersAPI from './browsers/browsers';
+import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Profiles extends APIResource {
+  /**
+   * Create a browser profile that can be used to load state into future browser
+   * sessions.
+   */
+  create(body: ProfileCreateParams, options?: RequestOptions): APIPromise<BrowsersAPI.Profile> {
+    return this._client.post('/profiles', { body, ...options });
+  }
+
+  /**
+   * Retrieve details for a single profile by its ID or name.
+   */
+  retrieve(idOrName: string, options?: RequestOptions): APIPromise<BrowsersAPI.Profile> {
+    return this._client.get(path`/profiles/${idOrName}`, options);
+  }
+
+  /**
+   * List profiles with optional filtering and pagination.
+   */
+  list(options?: RequestOptions): APIPromise<ProfileListResponse> {
+    return this._client.get('/profiles', options);
+  }
+
+  /**
+   * Delete a profile by its ID or by its name.
+   */
+  delete(idOrName: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/profiles/${idOrName}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Download the profile. Profiles are JSON files containing the pieces of state
+   * that we save.
+   */
+  download(idOrName: string, options?: RequestOptions): APIPromise<Response> {
+    return this._client.get(path`/profiles/${idOrName}/download`, {
+      ...options,
+      headers: buildHeaders([{ Accept: 'application/octet-stream' }, options?.headers]),
+      __binaryResponse: true,
+    });
+  }
+}
+
+export type ProfileListResponse = Array<BrowsersAPI.Profile>;
+
+export interface ProfileCreateParams {
+  /**
+   * Optional name of the profile. Must be unique within the organization.
+   */
+  name?: string;
+}
+
+export declare namespace Profiles {
+  export { type ProfileListResponse as ProfileListResponse, type ProfileCreateParams as ProfileCreateParams };
+}

tests/api-resources/browsers/browsers.test.ts

@@ -29,6 +29,7 @@ describe('resource browsers', () => {
           headless: false,
           invocation_id: 'rr33xuugxj9h0bkf1rdt2bet',
           persistence: { id: 'my-awesome-browser-for-user-1234' },
+          profile: { id: 'id', name: 'name', save_changes: true },
           stealth: true,
           timeout_seconds: 0,
         },

tests/api-resources/profiles.test.ts

@@ -0,0 +1,58 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import Kernel from '@onkernel/sdk';
+
+const client = new Kernel({
+  apiKey: 'My API Key',
+  baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010',
+});
+
+describe('resource profiles', () => {
+  // Prism tests are disabled
+  test.skip('create', async () => {
+    const responsePromise = client.profiles.create({});
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  // Prism tests are disabled
+  test.skip('retrieve', async () => {
+    const responsePromise = client.profiles.retrieve('id_or_name');
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  // Prism tests are disabled
+  test.skip('list', async () => {
+    const responsePromise = client.profiles.list();
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  // Prism tests are disabled
+  test.skip('delete', async () => {
+    const responsePromise = client.profiles.delete('id_or_name');
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+});