Scripting API#

The scripting API is a TypeScript API that you can use when writing custom browser scripts.

Using the scripting API#

The smartbrowser-core-interactions module provides classes and functions that you can use to implement your custom scripts.

You can import those classes and functions from smartbrowser-core-interactions/index.ts. For example:

import { BaseInteraction, Page } from "smartbrowser-core-interactions/index.ts";

Below you can find the reference documentation of the complete scripting API.

BaseInteraction and Page#

BaseInteraction() and Page() are the base of the scripting API.

class BaseInteraction()#

Base class for custom browser scripts.

abstract

exported from base_classes.Base

BaseInteraction.do(page, args)#

Entry point of a custom browser script.

Arguments
Returns

Promise<void>

class GotoOptions()#

Options for Page.goto().

interface

exported from api.page

GotoOptions.timeout?#

type: number

Maximum wait time, in seconds.

Defaults to 30 seconds.

Use 0 to disable the timeout.

GotoOptions.waitUntil#

type: “load”|”networkidle0”

When to consider that navigation has finished.

Possible values:

  • "load" (load event, default).

  • "networkidle0" (no ongoing network connections for at least 0.5 seconds).

class Page()#

The webpage currently loaded.

interface

exported from api.page

Page.click(selector)#

Click the first element matching selector.

Arguments
Returns

Promise<void>

Page.goto(url, options)#

Navigate to url.

By default, the returned promise resolves once url loads. See GotoOptions.waitUntil for other options.

Arguments
  • url (string()) – Target URL

  • options (GotoOptions()) – Navigation options

Returns

Promise<void>

Page.hide(selector)#

Hide all elements matching selector.

Arguments
Returns

Promise<void>

Page.hover(selector)#

Hover over the first element matching selector.

Arguments
Returns

Promise<void>

Page.keyPress(key)#

Press key.

Supported key IDs are:

Key Group

Key

Key IDs

Letters

A

"a", "A", "KeyA"

B

"b", "B", "KeyB"

C

"c", "C", "KeyC"

D

"d", "D", "KeyD"

E

"e", "E", "KeyE"

F

"f", "F", "KeyF"

G

"g", "G", "KeyG"

H

"h", "H", "KeyH"

I

"i", "I", "KeyI"

J

"j", "J", "KeyJ"

K

"k", "K", "KeyK"

L

"l", "L", "KeyL"

M

"m", "M", "KeyM"

N

"n", "N", "KeyN"

O

"o", "O", "KeyO"

P

"p", "P", "KeyP"

Q

"q", "Q", "KeyQ"

R

"r", "R", "KeyR"

S

"s", "S", "KeyS"

T

"t", "T", "KeyT"

U

"u", "U", "KeyU"

V

"v", "V", "KeyV"

W

"w", "W", "KeyW"

X

"x", "X", "KeyX"

Y

"y", "Y", "KeyY"

Z

"z", "Z", "KeyZ"

Digits

0

"0", "Digit0"

1

"1", "Digit1"

2

"2", "Digit2"

3

"3", "Digit3"

4

"4", "Digit4"

5

"5", "Digit5"

6

"6", "Digit6"

7

"7", "Digit7"

8

"8", "Digit8"

9

"9", "Digit9"

Symbols

Ampersand

"&"

Asterisk

"*"

At sign

"@"

Backslash

"Backslash", "\\"

Backtick

"Backquote", "`"

Caret

"^"

Closing brace

"}"

Closing bracket

"BracketRight", "]"

Closing parenthesis

")"

Colon

":"

Comma

"Comma", ","

Dollar sign

"$"

Double quote

'"'

Equal

"Equal", "="

Exclamation mark

"!"

Greater-than sign

">"

Hash

"#"

Interrogation mark

"?"

Less-than sign

"<"

Minus sign

"Minus", "-"

Opening brace

"{"

Opening bracket

"BracketLeft", "["

Opening parenthesis

")"

Percent sign

"%"

Period

"Period", "."

Plus sign

"+"

Semicolon

"Semicolon", ";"

Single quote

"Quote", "'"

Slash

"Slash", "/"

Tilde

"~"

Underscore

"_"

Vertical bar

"|"

Whitespace

Enter

"Enter", "\n"

Space

"Space", " "

Tab

"Tab"

Editing

Backspace

"Backspace", "\r"

Delete

"Delete"

Insert

"Insert"

Navigation

Down arrow

"ArrowDown"

Left arrow

"ArrowLeft"

Page down

"PageDown"

Page up

"PageUp"

Right arrow

"ArrowRight"

Up arrow

"ArrowUp"

Modifier

Alt

"Alt"

Caps Lock

"CapsLock"

Left Alt

"AltLeft"

Left Control

"ControlLeft"

Left Shift

"ShiftLeft"

Right Alt

"AltRight"

Right Control

"ControlRight"

Right Shift

"ShiftRight"

Shift

"Shift"

Numpad

0

"Numpad0"

1

"Numpad1"

2

"Numpad2"

3

"Numpad3"

4

"Numpad4"

5

"Numpad5"

6

"Numpad6"

7

"Numpad7"

8

"Numpad8"

Add sign

"NumpadAdd"

Decimal sign

"NumpadDecimal"

Divide sign

"NumpadDivide"

Enter

"NumpadEnter"

Equal

"NumpadEqual"

Multiply sign

"NumpadMultiply"

Substract sign

"NumpadSubtract"

UI

Break key

"Pause"

Composition

Non-conversion

"NonConvert"

Other

Null

"\u0000"

Arguments
  • key (string()) – Key ID.

Returns

Promise<void>

Page.type(selector, text, delay)#

Type text into the first element matching selector.

Arguments
  • selector (Selector|string()) –

    Selector() instance or CSS selector string.

  • text (string()) – Input text.

  • delay (number()) – Time to wait between key presses in seconds, defaults to 0.

Returns

Promise<void>

Page.waitForNavigation(timeout, waitUntil)#

Wait for navigation to finish.

Arguments
  • timeout (number()) – Maximum time to wait, in seconds. Defaults to 30 seconds.

  • waitUntil ("load"|"domcontentloaded"|"networkidle0"()) – When to consider that navigation has finished. One of: "load" (load event, default), "domcontentloaded" (DOMContentLoaded event), or "networkidle0" (no ongoing network connections for at least 0.5 seconds).

Returns

Promise<Response>

Page.waitForSelector(selector, timeout)#

Wait for selector to match an item in the DOM.

If there is already a match by the time the method is called, the returned promise resolves immediately.

Arguments
  • selector (Selector|string()) –

    Selector() instance or CSS selector string.

  • timeout (number()) – Maximum wait time, in seconds. Defaults to 30 seconds.

Returns

Promise<void>

Page.waitForTimeout(timeout)#

Return a promise that resolves after timeout.

Arguments
  • timeout (number()) – Wait time, in seconds.

Returns

Promise<void>

class Selector()#

Expression that aims to match one or more DOM elements.

interface

exported from api.page

Selector.allElements?#

type: boolean

Whether to match all possible elements (true) or only the first one (false, default).

Selector.state?#

type: “attached”|”visible”|”hidden”

Visibility required for an element to match.

Possible values are:

  • "visible" (default): only visible elements are matched.

    An element is visible if it has a non-empty bounding box and does not have visibility set to hidden.

    Note that elements with display set to none have an empty bounding box, and are hence not considered visible.

  • "hidden": only non-visible elements are matched.

  • "attached": any element may be matched, regardless of its visibility.

Selector.type#

type: “css”|”xpath”

Whether value is a CSS selector expression or an XPath 1.0 expression.

Selector.value#

type: string

Expression.

Special action interactions#

Zyte maintains a set of subclasses of BaseInteraction() that all Zyte API users may use as special actions.

When implementing a custom interaction, instead of extending BaseInteraction(), you can extend one of these special action interaction classes:

class SearchKeywordArgs()#

Argument interface for SearchKeywordInteraction().

interface

exported from base_classes.SearchKeyword

SearchKeywordArgs.keyword#

type: string

Keyword or keywords to search for.

class SearchKeywordInteraction()#

Interaction that uses the search box of a page.

See SearchKeywordArgs() for the interface of the args parameter of the do() method of this class.

abstract

exported from base_classes.SearchKeyword

Extends:
  • BaseInteraction()

SearchKeywordInteraction.keywordCssSelector#

type: Selector|string

Selector() instance or CSS selector string to find the input field where the search keywords must be typed.

SearchKeywordInteraction.typeKeyword(page, keyword)#

Type keyword into the search field on page, start the search, and wait for the results page to load.

Arguments
  • page (Page()) – Current page.

  • keyword (string()) – Search keywords.

Returns

Promise<void>

class SetLocation.postalAddress()#

Postal address.

interface

exported from base_classes.SetLocation

SetLocation.postalAddress.country#

type: string

ISO 3166-1 alpha-2 country code.

SetLocation.postalAddress.postalCode#

type: string

Postal code.

SetLocation.postalAddress.region#

type: string

Country subdivision of relevance for the postal address.

SetLocation.postalAddress.streetAddress#

type: string

Street address.

class SetLocationArgs()#

Argument interface for SetLocationInteraction().

interface

exported from base_classes.SetLocation

SetLocationArgs.postalAddress#

type: postalAddress

Postal address.

class SetLocationInteraction()#

Interaction to fill fields on the address form of a page.

See SetLocationArgs() for the interface of the args parameter of the do() method of this class.

abstract

exported from base_classes.SetLocation

Extends:
  • BaseInteraction()

SetLocationInteraction.postalCodeCssSelector#

type: Selector|string

Selector() instance or CSS selector string to find the input field of the postal code.

SetLocationInteraction.typePostalCode(page, postalCode)#

Type postalCode into the postal code field on page.

Arguments
Returns

Promise<void>

Versioning#

Every new version of the smartbrowser-core-interactions module is backward-compatible, and is automatically made available to every instance of Smart Browser DevTools IDE, and to code already deployed to Zyte API.

In the future, we may implement a versioning system to make it possible to introduce backward-incompatible changes into the smartbrowser-core-interactions module without breaking existing code.