JavaScript SDK: Context: inputs, output, and progress

The platform passes ctx into async function run(ctx). Use it to read inputs, call allowed services, and return records. Do not construct ctx yourself.

Each example is a separate fragment inside async function run(ctx). Use await only for methods whose signature returns a Promise.

Methods

• http()
• state()
• storage()
• browser()
• captcha()
• wildberries()
• dom()
• json()
• text()
• url()
• emit()
• flush()
• log()
• progress()
• metric()
• param()
• params()
• credential()
• sleep()
• cancelled()
• abort()
• fail()
• now()
• mail()
• documents()
• ai()
• sources()

http

ctx.http() → HttpClient

Get a client for requests to the site. All requests use the current site's network settings.

const result = ctx.http();

state

ctx.state() → KeyValue

Get a small store for traversal state, such as the last processed page number.

const result = ctx.state();

storage

ctx.storage(code) → Storage

Select an S3 file store by connection code. Configure the connection and allow it for the site first.

const result = ctx.storage('media');

browser

ctx.browser() → Browser

Get a browser for pages that need JavaScript, clicks, or scrolling.

const result = ctx.browser();

wildberries

ctx.wildberries() → Wildberries

Get the ready-made product source for a site created with the Wildberries solution. Products and regions come from site settings. See all methods and an example.

const result = ctx.wildberries();

yandexMarket

const source = ctx.yandexMarket();

Get Yandex Market products and search results for the configured scenario. YandexMarket.

const source = ctx.yandexMarket();

dom

ctx.dom(html, baseUrl) → Dom

Parse HTML already obtained. baseUrl lets relative links become absolute.

const result = ctx.dom('<a href="/product">Product</a>', 'https://example.com');

json

ctx.json(text) → unknown

Parses JSON text using JavaScript. Invalid JSON throws; the JavaScript method has no depth parameter.

const result = ctx.json('{"items":[]}');

text

ctx.text() → TextTools

Get tools for cleaning text, prices, and product codes.

const result = ctx.text();

url

ctx.url() → UrlTools

Get tools for links, query parameters, and page URL templates.

const result = ctx.url();

emit

ctx.emit(item, key) → void

Adds a plain JavaScript object to the output. Do not emit Response, Dom, or Document instances wholesale: select the fields you need. A stable key lets a later run update the record.

ctx.emit({ sku: 'A-1', price: 1250 }, 'A-1');

flush

ctx.flush() → void

Send accumulated records without waiting for the automatic flush.

ctx.flush();

log

ctx.log(message, context, level) → void

Write a clear message to the run log. Pass extra values in context.

ctx.log('Collection started');

progress

ctx.progress(done, total, label, percent) → void

Report work completed and a user-facing stage name. You may not know total in advance.

ctx.progress(1, 10, 'Catalog');

metric

ctx.metric(name, value) → void

Add a numeric execution metric, such as the number of skipped products.

ctx.metric('processed', 1);

param

ctx.param(name, default) → unknown

Get one run parameter. default is used if the parameter is absent or null.

const result = ctx.param('catalog_url', '');

params

ctx.params() → object

Get all run parameters.

const result = ctx.params();

credential

ctx.credential(name) → Promise<string>

Get a named secret for the target website. Its name must match a configured key.

const result = await ctx.credential('site_token');

sleep

ctx.sleep(ms) → Promise<void>

Make a controlled pause. The argument is in milliseconds.

await ctx.sleep(250);

cancelled

ctx.cancelled() → Promise<boolean>

Check whether the user requested a stop. Do this in long loops.

const result = await ctx.cancelled();

abort

ctx.abort(reason) → never

Stop execution with an explanation and retain state for a possible resume. The run receives a stopped status. Use fail() if the source returns an error or data is malformed.

ctx.abort('Could not process the page');

fail

ctx.fail(reason) → never

End a run with an error when the source is unavailable or its response differs from the expected format. Unlike abort(), this stop is recorded as a failure rather than a cancellation.

ctx.fail('Could not process the page');

now

ctx.now() → Date

Returns a Date for the current instant. Use toISOString() for UTC; display depends on the selected time zone.

const result = ctx.now();

mail

ctx.mail() → Mail

Opens inbound-mail methods inside a mail scenario. Content is available only for the pinned event.

const result = ctx.mail();

documents

ctx.documents() → Documents

Opens parsing of allowed Excel, PDF, Word, CSV, and text files.

const result = ctx.documents();

ai

ctx.ai() → Ai

Opens data analysis, extraction, and transformation methods. AI calls are asynchronous and count against the workspace budget.

const result = ctx.ai();

sources

ctx.sources() → Sources

Opens pinned workflow inputs and local price comparison. Inputs are available only to the corresponding workflow scenario.

const inputs = ctx.sources();

captcha

ctx.captcha()

Returns the explicit task API. Catalog and quotation methods do not submit a paid task. Creation, status retrieval and feedback work through the workspace account in the cloud and on an agent.

Full method reference.