@hasna/connectors 0.8.2 → 0.9.1

package/connectors/connect-browseruse/src/api/files.ts

@@ -0,0 +1,70 @@
+import type { BrowserUseClient } from './client';
+import type { PresignedUrl, UploadFileParams } from '../types';
+
+/**
+ * Files API
+ */
+export class FilesApi {
+  constructor(private client: BrowserUseClient) {}
+
+  /**
+   * Get presigned URL for uploading a file to an agent session
+   */
+  async getAgentSessionUploadUrl(sessionId: string, params: UploadFileParams): Promise<PresignedUrl> {
+    return this.client.post<PresignedUrl>(`/v2/sessions/${sessionId}/files/upload`, {
+      file_name: params.fileName,
+      content_type: params.contentType,
+    });
+  }
+
+  /**
+   * Get presigned URL for uploading a file to a browser session
+   */
+  async getBrowserSessionUploadUrl(browserId: string, params: UploadFileParams): Promise<PresignedUrl> {
+    return this.client.post<PresignedUrl>(`/v2/browsers/${browserId}/files/upload`, {
+      file_name: params.fileName,
+      content_type: params.contentType,
+    });
+  }
+
+  /**
+   * Get presigned URL for downloading a task output file
+   */
+  async getTaskOutputUrl(taskId: string, fileId: string): Promise<PresignedUrl> {
+    return this.client.get<PresignedUrl>(`/v2/tasks/${taskId}/files/${fileId}`);
+  }
+
+  /**
+   * Upload a file using a presigned URL
+   */
+  async uploadFile(presignedUrl: string, data: Uint8Array | Buffer | string, contentType?: string): Promise<void> {
+    const headers: Record<string, string> = {};
+    if (contentType) {
+      headers['Content-Type'] = contentType;
+    }
+
+    const response = await fetch(presignedUrl, {
+      method: 'PUT',
+      headers,
+      body: data,
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to upload file: ${response.status} ${response.statusText}`);
+    }
+  }
+
+  /**
+   * Download a file from a presigned URL
+   */
+  async downloadFile(presignedUrl: string): Promise<Uint8Array> {
+    const response = await fetch(presignedUrl);
+
+    if (!response.ok) {
+      throw new Error(`Failed to download file: ${response.status} ${response.statusText}`);
+    }
+
+    const arrayBuffer = await response.arrayBuffer();
+    return new Uint8Array(arrayBuffer);
+  }
+}

package/connectors/connect-browseruse/src/api/index.ts

@@ -0,0 +1,95 @@
+import { BrowserUseClient, type BrowserUseClientConfig } from './client';
+import { TasksApi } from './tasks';
+import { SessionsApi } from './sessions';
+import { ProfilesApi } from './profiles';
+import { BrowsersApi } from './browsers';
+import { SkillsApi, MarketplaceApi } from './skills';
+import { FilesApi } from './files';
+import { BillingApi } from './billing';
+
+/**
+ * Main Browser Use Connector class
+ * Provides access to all Browser Use Cloud API endpoints
+ */
+export class BrowserUse {
+  private readonly client: BrowserUseClient;
+
+  // API modules
+  public readonly tasks: TasksApi;
+  public readonly sessions: SessionsApi;
+  public readonly profiles: ProfilesApi;
+  public readonly browsers: BrowsersApi;
+  public readonly skills: SkillsApi;
+  public readonly marketplace: MarketplaceApi;
+  public readonly files: FilesApi;
+  public readonly billing: BillingApi;
+
+  constructor(config: BrowserUseClientConfig) {
+    this.client = new BrowserUseClient(config);
+    this.tasks = new TasksApi(this.client);
+    this.sessions = new SessionsApi(this.client);
+    this.profiles = new ProfilesApi(this.client);
+    this.browsers = new BrowsersApi(this.client);
+    this.skills = new SkillsApi(this.client);
+    this.marketplace = new MarketplaceApi(this.client);
+    this.files = new FilesApi(this.client);
+    this.billing = new BillingApi(this.client);
+  }
+
+  /**
+   * Create a client from environment variables
+   * Looks for BROWSER_USE_API_KEY and optionally BROWSER_USE_BASE_URL
+   */
+  static fromEnv(): BrowserUse {
+    const apiKey = process.env.BROWSER_USE_API_KEY;
+    const baseUrl = process.env.BROWSER_USE_BASE_URL;
+
+    if (!apiKey) {
+      throw new Error('BROWSER_USE_API_KEY environment variable is required');
+    }
+
+    return new BrowserUse({ apiKey, baseUrl });
+  }
+
+  /**
+   * Run a task with a simple interface
+   */
+  async run(task: string, options?: { schema?: Record<string, unknown>; timeout?: number }): Promise<unknown> {
+    const result = await this.tasks.run(
+      { task, schema: options?.schema },
+      2000,
+      options?.timeout || 300000
+    );
+    return result.output;
+  }
+
+  /**
+   * Get API key preview (for debugging)
+   */
+  getApiKeyPreview(): string {
+    return this.client.getApiKeyPreview();
+  }
+
+  /**
+   * Get base URL
+   */
+  getBaseUrl(): string {
+    return this.client.getBaseUrl();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): BrowserUseClient {
+    return this.client;
+  }
+}
+
+export { BrowserUseClient } from './client';
+export { TasksApi } from './tasks';
+export { SessionsApi } from './sessions';
+export { ProfilesApi } from './profiles';
+export { BrowsersApi } from './browsers';
+export { SkillsApi, MarketplaceApi } from './skills';
+export { FilesApi } from './files';
+export { BillingApi } from './billing';

package/connectors/connect-browseruse/src/api/profiles.ts

@@ -0,0 +1,59 @@
+import type { BrowserUseClient } from './client';
+import type {
+  Profile,
+  CreateProfileParams,
+  UpdateProfileParams,
+  ListProfilesParams,
+  PaginatedResponse,
+} from '../types';
+
+/**
+ * Profiles API (Browser Profiles for persistent state)
+ */
+export class ProfilesApi {
+  constructor(private client: BrowserUseClient) {}
+
+  /**
+   * List all profiles
+   */
+  async list(params?: ListProfilesParams): Promise<PaginatedResponse<Profile>> {
+    return this.client.get<PaginatedResponse<Profile>>('/v2/profiles', {
+      limit: params?.limit,
+      cursor: params?.cursor,
+    });
+  }
+
+  /**
+   * Create a new profile
+   */
+  async create(params: CreateProfileParams): Promise<Profile> {
+    return this.client.post<Profile>('/v2/profiles', {
+      name: params.name,
+      description: params.description,
+    });
+  }
+
+  /**
+   * Get a profile by ID
+   */
+  async get(profileId: string): Promise<Profile> {
+    return this.client.get<Profile>(`/v2/profiles/${profileId}`);
+  }
+
+  /**
+   * Update a profile
+   */
+  async update(profileId: string, params: UpdateProfileParams): Promise<Profile> {
+    return this.client.patch<Profile>(`/v2/profiles/${profileId}`, {
+      name: params.name,
+      description: params.description,
+    });
+  }
+
+  /**
+   * Delete a profile
+   */
+  async delete(profileId: string): Promise<void> {
+    await this.client.delete(`/v2/profiles/${profileId}`);
+  }
+}

package/connectors/connect-browseruse/src/api/sessions.ts

@@ -0,0 +1,88 @@
+import type { BrowserUseClient } from './client';
+import type {
+  Session,
+  CreateSessionParams,
+  ListSessionsParams,
+  SessionPublicShare,
+  PaginatedResponse,
+} from '../types';
+
+/**
+ * Sessions API
+ */
+export class SessionsApi {
+  constructor(private client: BrowserUseClient) {}
+
+  /**
+   * List all sessions
+   */
+  async list(params?: ListSessionsParams): Promise<PaginatedResponse<Session>> {
+    return this.client.get<PaginatedResponse<Session>>('/v2/sessions', {
+      limit: params?.limit,
+      cursor: params?.cursor,
+      status: params?.status,
+    });
+  }
+
+  /**
+   * Create a new session
+   */
+  async create(params?: CreateSessionParams): Promise<Session> {
+    return this.client.post<Session>('/v2/sessions', {
+      task: params?.task,
+      profile_id: params?.profileId,
+      proxy_url: params?.proxyUrl,
+      keep_alive: params?.keepAlive,
+      save_browser_data: params?.save_browser_data,
+    });
+  }
+
+  /**
+   * Get a session by ID
+   */
+  async get(sessionId: string): Promise<Session> {
+    return this.client.get<Session>(`/v2/sessions/${sessionId}`);
+  }
+
+  /**
+   * Update a session (stop)
+   */
+  async update(sessionId: string, action: 'stop'): Promise<Session> {
+    return this.client.patch<Session>(`/v2/sessions/${sessionId}`, { action });
+  }
+
+  /**
+   * Stop a session
+   */
+  async stop(sessionId: string): Promise<Session> {
+    return this.update(sessionId, 'stop');
+  }
+
+  /**
+   * Delete a session
+   */
+  async delete(sessionId: string): Promise<void> {
+    await this.client.delete(`/v2/sessions/${sessionId}`);
+  }
+
+  /**
+   * Get public share for a session
+   */
+  async getPublicShare(sessionId: string): Promise<SessionPublicShare> {
+    return this.client.get<SessionPublicShare>(`/v2/sessions/${sessionId}/public-share`);
+  }
+
+  /**
+   * Create public share for a session
+   */
+  async createPublicShare(sessionId: string): Promise<SessionPublicShare> {
+    return this.client.post<SessionPublicShare>(`/v2/sessions/${sessionId}/public-share`);
+  }
+
+  /**
+   * Delete public share for a session
+   */
+  async deletePublicShare(sessionId: string): Promise<void> {
+    await this.client.delete(`/v2/sessions/${sessionId}/public-share`);
+  }
+}

package/connectors/connect-browseruse/src/api/skills.ts

@@ -0,0 +1,194 @@
+import type { BrowserUseClient } from './client';
+import type {
+  Skill,
+  CreateSkillParams,
+  UpdateSkillParams,
+  ExecuteSkillParams,
+  RefineSkillParams,
+  SkillExecution,
+  ListSkillsParams,
+  ListSkillExecutionsParams,
+  PaginatedResponse,
+  PresignedUrl,
+  MarketplaceSkill,
+  CloneSkillParams,
+} from '../types';
+
+/**
+ * Skills API
+ */
+export class SkillsApi {
+  constructor(private client: BrowserUseClient) {}
+
+  /**
+   * List all skills
+   */
+  async list(params?: ListSkillsParams): Promise<PaginatedResponse<Skill>> {
+    return this.client.get<PaginatedResponse<Skill>>('/v2/skills', {
+      limit: params?.limit,
+      cursor: params?.cursor,
+      status: params?.status,
+    });
+  }
+
+  /**
+   * Create a new skill
+   */
+  async create(params: CreateSkillParams): Promise<Skill> {
+    return this.client.post<Skill>('/v2/skills', {
+      name: params.name,
+      description: params.description,
+      task: params.task,
+      example_inputs: params.exampleInputs,
+    });
+  }
+
+  /**
+   * Get a skill by ID
+   */
+  async get(skillId: string): Promise<Skill> {
+    return this.client.get<Skill>(`/v2/skills/${skillId}`);
+  }
+
+  /**
+   * Update a skill
+   */
+  async update(skillId: string, params: UpdateSkillParams): Promise<Skill> {
+    return this.client.patch<Skill>(`/v2/skills/${skillId}`, {
+      name: params.name,
+      description: params.description,
+      is_public: params.isPublic,
+    });
+  }
+
+  /**
+   * Delete a skill
+   */
+  async delete(skillId: string): Promise<void> {
+    await this.client.delete(`/v2/skills/${skillId}`);
+  }
+
+  /**
+   * Execute a skill
+   */
+  async execute(skillId: string, params: ExecuteSkillParams): Promise<SkillExecution> {
+    return this.client.post<SkillExecution>(`/v2/skills/${skillId}/execute`, {
+      parameters: params.parameters,
+      session_id: params.sessionId,
+    });
+  }
+
+  /**
+   * Refine a skill
+   */
+  async refine(skillId: string, params: RefineSkillParams): Promise<Skill> {
+    return this.client.post<Skill>(`/v2/skills/${skillId}/refine`, {
+      feedback: params.feedback,
+    });
+  }
+
+  /**
+   * Cancel skill generation
+   */
+  async cancelGeneration(skillId: string): Promise<Skill> {
+    return this.client.post<Skill>(`/v2/skills/${skillId}/cancel`);
+  }
+
+  /**
+   * Rollback skill to previous version
+   */
+  async rollback(skillId: string, version?: number): Promise<Skill> {
+    return this.client.post<Skill>(`/v2/skills/${skillId}/rollback`, {
+      version,
+    });
+  }
+
+  /**
+   * List skill executions
+   */
+  async listExecutions(skillId: string, params?: ListSkillExecutionsParams): Promise<PaginatedResponse<SkillExecution>> {
+    return this.client.get<PaginatedResponse<SkillExecution>>(`/v2/skills/${skillId}/executions`, {
+      limit: params?.limit,
+      cursor: params?.cursor,
+    });
+  }
+
+  /**
+   * Get skill execution output download URL
+   */
+  async getExecutionOutput(skillId: string, executionId: string): Promise<PresignedUrl> {
+    return this.client.get<PresignedUrl>(`/v2/skills/${skillId}/executions/${executionId}/output`);
+  }
+
+  /**
+   * Wait for skill execution completion
+   */
+  async waitForExecution(skillId: string, executionId: string, pollIntervalMs = 2000, timeoutMs = 300000): Promise<SkillExecution> {
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < timeoutMs) {
+      const executions = await this.listExecutions(skillId, { limit: 100 });
+      const execution = executions.data.find(e => e.id === executionId);
+
+      if (execution && ['completed', 'failed'].includes(execution.status)) {
+        return execution;
+      }
+
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+    }
+
+    throw new Error(`Skill execution ${executionId} did not complete within ${timeoutMs}ms`);
+  }
+
+  /**
+   * Run a skill and wait for completion
+   */
+  async run(skillId: string, params: ExecuteSkillParams, pollIntervalMs = 2000, timeoutMs = 300000): Promise<SkillExecution> {
+    const execution = await this.execute(skillId, params);
+    return this.waitForExecution(skillId, execution.id, pollIntervalMs, timeoutMs);
+  }
+}
+
+/**
+ * Skills Marketplace API
+ */
+export class MarketplaceApi {
+  constructor(private client: BrowserUseClient) {}
+
+  /**
+   * List marketplace skills
+   */
+  async list(params?: { limit?: number; cursor?: string; search?: string }): Promise<PaginatedResponse<MarketplaceSkill>> {
+    return this.client.get<PaginatedResponse<MarketplaceSkill>>('/v2/marketplace/skills', {
+      limit: params?.limit,
+      cursor: params?.cursor,
+      search: params?.search,
+    });
+  }
+
+  /**
+   * Get a marketplace skill by ID
+   */
+  async get(skillId: string): Promise<MarketplaceSkill> {
+    return this.client.get<MarketplaceSkill>(`/v2/marketplace/skills/${skillId}`);
+  }
+
+  /**
+   * Clone a marketplace skill to your project
+   */
+  async clone(skillId: string, params?: CloneSkillParams): Promise<Skill> {
+    return this.client.post<Skill>(`/v2/marketplace/skills/${skillId}/clone`, {
+      name: params?.name,
+    });
+  }
+
+  /**
+   * Execute a marketplace skill directly
+   */
+  async execute(skillId: string, params: ExecuteSkillParams): Promise<SkillExecution> {
+    return this.client.post<SkillExecution>(`/v2/marketplace/skills/${skillId}/execute`, {
+      parameters: params.parameters,
+      session_id: params.sessionId,
+    });
+  }
+}

package/connectors/connect-browseruse/src/api/tasks.ts

@@ -0,0 +1,117 @@
+import type { BrowserUseClient } from './client';
+import type {
+  Task,
+  CreateTaskParams,
+  UpdateTaskParams,
+  ListTasksParams,
+  PaginatedResponse,
+} from '../types';
+
+/**
+ * Tasks API
+ */
+export class TasksApi {
+  constructor(private client: BrowserUseClient) {}
+
+  /**
+   * List all tasks
+   */
+  async list(params?: ListTasksParams): Promise<PaginatedResponse<Task>> {
+    return this.client.get<PaginatedResponse<Task>>('/tasks', {
+      limit: params?.limit,
+      cursor: params?.cursor,
+      session_id: params?.sessionId,
+      status: params?.status,
+    });
+  }
+
+  /**
+   * Create a new task
+   */
+  async create(params: CreateTaskParams): Promise<Task> {
+    return this.client.post<Task>('/tasks', {
+      task: params.task,
+      session_id: params.sessionId,
+      schema: params.schema,
+      save_browser_data: params.save_browser_data,
+    });
+  }
+
+  /**
+   * Get a task by ID
+   */
+  async get(taskId: string): Promise<Task> {
+    return this.client.get<Task>(`/tasks/${taskId}`);
+  }
+
+  /**
+   * Update a task (stop, pause, resume)
+   */
+  async update(taskId: string, params: UpdateTaskParams): Promise<Task> {
+    return this.client.patch<Task>(`/tasks/${taskId}`, {
+      action: params.action,
+    });
+  }
+
+  /**
+   * Stop a task
+   */
+  async stop(taskId: string): Promise<Task> {
+    return this.update(taskId, { action: 'stop' });
+  }
+
+  /**
+   * Pause a task
+   */
+  async pause(taskId: string): Promise<Task> {
+    return this.update(taskId, { action: 'pause' });
+  }
+
+  /**
+   * Resume a task
+   */
+  async resume(taskId: string): Promise<Task> {
+    return this.update(taskId, { action: 'resume' });
+  }
+
+  /**
+   * Stop task and close session
+   */
+  async stopAndCloseSession(taskId: string): Promise<Task> {
+    return this.update(taskId, { action: 'stop-and-close-session' });
+  }
+
+  /**
+   * Get task logs download URL
+   */
+  async getLogs(taskId: string): Promise<{ url: string; expiresAt: string }> {
+    return this.client.get<{ url: string; expiresAt: string }>(`/tasks/${taskId}/logs`);
+  }
+
+  /**
+   * Wait for task completion
+   */
+  async waitForCompletion(taskId: string, pollIntervalMs = 2000, timeoutMs = 300000): Promise<Task> {
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < timeoutMs) {
+      const task = await this.get(taskId);
+
+      if (['completed', 'failed', 'stopped'].includes(task.status)) {
+        return task;
+      }
+
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+    }
+
+    throw new Error(`Task ${taskId} did not complete within ${timeoutMs}ms`);
+  }
+
+  /**
+   * Run a task and wait for completion
+   */
+  async run(params: CreateTaskParams, pollIntervalMs = 2000, timeoutMs = 300000): Promise<Task> {
+    const task = await this.create(params);
+    return this.waitForCompletion(task.id, pollIntervalMs, timeoutMs);
+  }
+}