JavaScript SDK: getting started

Choose JavaScript when creating a scenario manually. Your code runs in a separate, isolated Node.js environment. Use ctx to access websites, the browser, records, documents, and AI. Direct network access, the file system, require, and system commands are unavailable.

One scenario can request several websites and process an incoming email. The selected site determines where the results are stored. Combining sources.

The entry point is run. Methods that request data from the platform return a Promise, so use await.

async function run(ctx) {
  const url = ctx.param('catalog_url', '');
  if (!url) ctx.abort('Enter a catalog URL');

  const response = await ctx.http().get(url);
  if (!response.ok()) ctx.abort(`Website returned HTTP ${response.status}`);

  for (const card of response.dom().qa('.product-card')) {
    const sku = card.attr('data-sku');
    if (!sku) continue;
    ctx.emit({
      sku,
      name: card.q('.title')?.text() ?? '',
      price: ctx.text().money(card.q('.price')?.text() ?? null),
    }, sku);
  }
}

These selectors are examples. Pick selectors for your website in the visual mapper. ctx.emit(record, key) saves a record; a stable key lets a later run update the same product.

Page actions

When a website requires clicks or input, open it through the browser SDK. Actions run in order. The browser must be enabled on your agent.

async function run(ctx) {
  const page = await ctx.browser().open(ctx.param('catalog_url'));
  try {
    await page.click('button.show-products');
    await page.type('input[name="search"]', 'cable');
    await page.press('input[name="search"]', 'Enter');
    await page.waitFor('.product-card');
    await page.scrollTo('.pagination');
    const dom = ctx.dom(await page.content());
    for (const card of dom.qa('.product-card')) {
      const sku = card.attr('data-sku');
      if (sku) ctx.emit({ sku, name: card.q('.title')?.text() ?? '' }, sku);
    }
  } finally {
    await page.close();
  }
}

You can also use hover(selector), select(selector, value), and scroll(steps, delay). To visit multiple pages, repeat the actions in a loop, check for new cards, and set a maximum page count. See browser and page actions.

Other capabilities

Start with the scenario lifecycle: creation, validation, trial run, publication, regular execution, and safe retry. Then read the first complete algorithm. Add await to service calls; local operations such as ctx.text().money(), ctx.dom(), and ctx.emit() run immediately.

Method reference

As in the PHP reference, each method group has its own article with purpose, arguments, result, await behavior, and a short example.

Practical tasks

Pagination, JSON collection, clicks and scrolling, and logs and progress provide complete scenarios. Integrations explain how to connect workflow inputs, files, and ready-made sources.

AI use and processing time follow the same billing rules as PHP. For a self-hosted agent, select JavaScript when creating it. You can enable just the languages you need; the choice is locked once you issue a token. A script will not start on an agent where its language is disabled.

After saving, validate the code, run a trial, and compare records with the source website. Step debugging is not yet available for JavaScript; use trial runs and logs. Language examples in the API section are for external programs, not scenario code.

Working with CAPTCHA: complete examples

Explore catalogs, pagination, batch loading, scrolling, sign-in, JavaScript rendering and control pages in the dedicated section. Each of the 12 walkthroughs includes settings, complete source and an explanation of the algorithm.

Explicit CAPTCHA tasks

Current type catalog, input schemas, cost quotations and task results are available through ctx.captcha(). The API works in the cloud and on agents with workspace billing. Reference.