TypeScript scenario lifecycle
A scenario moves through several states between editing and regular collection. Following this sequence lets you change an algorithm without disrupting working data.
1. Creation and entry point
When creating a scenario, select a site and TypeScript. The platform saves source code as a scenario version. The entry point is run, which receives only the ctx object with allowed SDK methods.
async function run(ctx: Akmelo.Context): Promise<void> {
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.fail(`Website returned HTTP ${response.status}`);
ctx.emit({ url, title: response.dom().text('h1', '') }, url);
}
The function may call your own helper functions. Each run gets a separate ctx. A live ctx, an open browser page, or a TypeScript variable cannot move between runs. Use state for a small cursor and ctx.emit() for output records.
2. Code validation
Save a draft and run validation. TypeScript 7 checks SDK types and finds syntax errors, an invalid entry point, and some structural mistakes. It does not prove that a CSS selector will match a real product. Step debugging with breakpoints is not available for TypeScript; use a trial run, logs, progress, and output records.
Validation does not publish the version or start collection. Editing creates a new draft version while the published version remains separate.
3. Trial run
A trial executes the selected draft through the same TypeScript sandbox and SDK methods. Its output goes to a preview and does not replace the working catalog. Check record count, keys, prices, missing fields, request logs, and errors. Start with one page and a small set of products.
Parameters come from the site, scenario settings, and the specific run. Read them with ctx.param() or ctx.params(). Read site secrets with await ctx.credential(name) and never put them in logs or emitted records.
4. Publication and regular runs
After validation, publish the intended version. Publication switches the working version but does not itself start a run. Manual runs and schedules use published code. A draft cannot write to the working catalog; use a trial. You can roll back to a previously published version if a change fails.
Every regular run has its own identifier, parameters, log, and status. ctx.emit(record, key) sends a record to the platform. A stable key helps update the same product on a later run. ctx.flush() sends the buffered batch immediately; the buffer is also sent when execution ends. Emitting a record does not mean the whole run succeeded: wait for the final status and inspect the result.
5. What happens during run
TypeScript executes in a separate isolated environment. Local operations (ctx.text(), ctx.dom(), ctx.url(), parsing an already received response) run immediately. Website, browser, storage, document, mail, state, and AI operations go through the platform and return a Promise. Use await; otherwise run may end before an operation finishes.
Direct fetch, require, file-system access, and shell commands are unavailable to scenario code. Use HttpClient for HTTP and BrowserPage for interactive pages. Close browser pages in finally, including after an error.
async function run(ctx: Akmelo.Context): Promise<void> {
const page = await ctx.browser().open(ctx.param<string>('catalog_url'));
try {
await page.click('button.show-products');
await page.waitFor('.product-card');
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, title: card.q('.title')?.text() ?? '' }, sku);
}
} finally {
await page.close();
}
}
6. Stop, failure, and retry
In a long loop, call await ctx.cancelled() and stop when the user cancels the run. ctx.abort(reason) stops intentionally; ctx.fail(reason) reports a failure. An uncaught TypeScript error also fails the run and appears in its log. Do not hide errors with an empty catch, as that can produce an unexplained partial result.
For a safe retry, use stable record keys and keep the last processed page in ctx.state(). State is for a small cursor; store product records and files in their intended destinations. On repeated pagination, verify that the page content actually changed after a Next action.
7. Agent, limits, and cost
A scenario can run on an agent with TypeScript enabled during setup. A PHP-only agent cannot run it. Browser actions require browser support on that agent. Some platform services may be unavailable while an agent is offline, so regular collection should not depend on an essential AI call.
Processing time and AI usage follow the workspace rules. Local text, HTML, and array processing does not itself make a paid AI request. An intentional ctx.sleep() counts toward execution time; protective waiting in a ready-made source follows that solution's billing rules. Check limits and cost with a short trial before a large run.