Concepts

Core Concepts

Core Concepts

Under the Hood

GPAL is the highest-level automation layer, but it sits on top of lower-level layers you can use directly for custom tooling or finer control. All layers are fluent and all map to the same set of operations.

The Layer Stack

GPAL is the main automation layer -- it abstracts browsers, desktop applications, data operations, and everything else into one consistent fluent interface. Below it sit four lower-level layers, each offering a different altitude of control: a fluent HTTP client, a single-call endpoint helper, a user-friendly CDP interface, and a raw async CDP command surface at the very bottom. All layers expose the same set of browser control operations under the same names.

Same Operations, Different Altitude

Every layer uses the same method names for the same operations -- GoTo is GoTo at every level. Three of the four lower layers are fully fluent and chainable, reading just like a GPAL chain one altitude lower. The fourth is the exception: flat static helpers, one call at a time, with no chaining.

// GPAL - highest level, full automation context

browser.GoTo("https://example.com");

// RESTClient - chainable like GPAL, or call .Execute() after a single method

restClient.GoTo("https://example.com").Execute();

// MagicHelper - single endpoint execution, by design not chainable

MagicHelper.GoTo("https://example.com");

// PuppeteerClient - chainable like RESTClient, or standalone with .Execute()

puppeteerClient.GoTo("https://example.com").Execute();

// PuppeteerCommunicator - lowest level, single endpoint, async

await communicator.GoTo("https://example.com");

TIP

Most automation is written at the GPAL level. The lower layers are covered in the tutorials section for developers building custom tooling.

When to Go Lower

Use the lower layers when building custom tooling on top of GPAL infrastructure, integrating browser control into a non-.NET system via the REST API, or when you need fine-grained control over individual CDP commands. The REST API accepts commands from any HTTP client. Not just GPAL. And that same naming consistency makes it a universal browser-control protocol: other-language SDKs can be generated straight from the endpoint list without drifting out of sync, and an AI agent that has read GPAL's docs can call the REST API directly using names it already knows.

WARNING

PuppeteerCommunicator sends raw CDP commands with no fluent validation. Invalid command sequences will not be caught at compile time. Almost every method is also async. GPAL, RESTClient, MagicHelper, and PuppeteerClient are synchronous. Use PuppeteerClient or GPAL unless you specifically need direct CDP access.

On this page

Core Concepts
Under the Hood
  • The Layer Stack
  • Same Operations, Different Altitude
  • When to Go Lower