browserless 1.0.0

A fully-typed Dart SDK for interacting with Browserless via REST and WebSockets.

browserless

A fully-typed Dart SDK for interacting with Browserless.

To read more about the Browserless Chromium container, visit the browserless/chromium GitHub Packages page.

This SDK is generated automatically directly from the Browserless OpenAPI (swagger.json) specifications, ensuring that all API endpoints, parameters, and Data Transfer Objects (DTOs) are typed and up to date.

Features

• Compositional API Clients: Organizes endpoints intuitively by sub-groups (e.g., api.chromium.pdf(), api.json.list()). Separates stateful connections from stateless requests:
  • BrowserlessHttpApi: For REST/HTTP endpoints.
  • BrowserlessWebSocketApi: For WebSocket connections.
• Fully Typed DTOs & Responses: Methods natively return strong Dart types (like Uint8List for PDFs, or generated model lists), avoiding raw http.Response handling. Includes full support for union classes like CDPLaunchOptionsOrString.
• Dynamic Generator: The included generator script authenticates and pulls the live swagger.json directly from your Browserless endpoint to generate the SDK.

Getting Started

Add the package to your pubspec.yaml (or install via dart pub add browserless), then import the SDK:

import 'package:browserless/browserless_api.dart';

Note for Contributors and Testing ⚠️

The .env file is not pushed to version control for security reasons. If you want to run the tests (dart test) or regenerate the SDK (dart run generator/generator.dart), you must provide the BROWSERLESS_ENDPOINT and BROWSERLESS_TOKEN via a .env file in the root of the project, or directly through your system environment variables (useful for CI):

BROWSERLESS_ENDPOINT=https://your-browserless-endpoint.com
BROWSERLESS_TOKEN=your-browserless-token

Usage

Using the REST API

import 'package:browserless/browserless_api.dart';

void main() async {
  final api = BrowserlessHttpApi(
    baseUrl: 'https://your-browserless-endpoint.com',
    defaultToken: 'your-browserless-token'
  );

  // Example: Getting active sessions
  final sessions = await api.json.list();
  print(sessions); // Returns a strongly-typed List

  // Example: Generating a PDF from HTML
  final pdfBytes = await api.chromium.pdf(
    body: {'html': '<h1>Hello Browserless!</h1>'}
  );
  // pdfBytes contains the Uint8List PDF data directly
}

Using the WebSocket API

import 'package:browserless/browserless_api.dart';

void main() async {
  final wsApi = BrowserlessWebSocketApi(
    baseUrl: 'https://your-browserless-endpoint.com',
    defaultToken: 'your-browserless-token'
  );

  // Connect to the generic Chromium WebSocket endpoint via .call()
  final channel = wsApi.chromium();
  
  // Send CDP commands or use with Puppeteer/Playwright Dart ports
  // channel.sink.add(...);
}