module.js API

The module.js script is the actual logic behind a module. It exists in a separate context from the module webpage.

While on the module page within Somiibo, you can press cmd+option+i or ctrl+shift+i to open the DevTools which includes a console.

From within the module.js script you can require any core Node.js module as well as any of the supported 3rd party modules.

Overview

The module.js script is the actual logic behind a module. It controls the webpages and performs actions on websites.

The Somiibo library is the first argument passed to the exported function, so as seen here, mod can be stored to a variable somiibo in the global scope so that it can be accessed throughout the rest of the module's lifecycle.

Using Node.js Modules in module.js

From within the module.js script you can require any Node.js module that is a dependency in Somiibo.

Visit somiibo://developer and go to the "Using Node.js Modules" tab to see the currently supported modules.

module.js Skeleton File

API

Discover the module.js API

Flow

Flow controls the initialization and looping of the module.

somiibo.initialize(fn)

  • fn <function(Object)> A function to execute
    • defaults <Object> A mutable object representing the defaults for every method
  • returns <null>

.initialize() runs only once and, as such, it is an easy way to implement any configuration or setup that does not need to be executed multiple times. Any subsequent calls to .initialize() will be ignored. defaults for each method can be overwritten here via defaults[library][method][name] = 'new'.

somiibo.loop(fn)

  • fn <function(Object)> A function to execute
  • delay <?number> Number of milliseconds to wait before the script loops
  • returns <null>

.loop() drives the repeating nature of modules by executing the fn passed to it, effectively starting the module from the top again.

somiibo.stop()

  • returns <null>

Stop the module's execution. Calling this is the same as if the user pressed the 'stop' button on the module manager page.

somiibo.error(reason)

  • returns <null>

Stop module execution and displays an error message with reason.

somiibo.wait(minTime, maxTime)

  • minTime <number> Minimum time in milliseconds to wait
  • maxTime <number> Maximum time in milliseconds to wait
  • returns <Promise(number)> The promise resolves when the wait is over with the number of milliseconds waited.

This method pauses execution of the script for the amount of minTime specified in milliseconds. If maxTime is also supplied, a random duration between the two is waited.

Settings

somiibo.getSetting(path, def)

  • path <string> Path to the settings key to retrieve
  • def <any> The default value to provide if the setting does not exist
  • returns <any>

Get the user's settings for this module. If path is not supplied, the entire settings object will be returned.

Development & Debugging

somiibo.log([, ...args])

  • ...args <...Serializable> Arguments to pass to the console
  • returns <null>

Executes console.log in the module's DevTools console.

somiibo.openDevTools()

  • returns <null>

Opens the module's dev tools.

Workers

somiibo.worker(fn, options)

  • fn <Function> Function to be passed to the worker process
  • options <Object> Function to be passed to the worker process
    • arguments <Array> Arguments to be passed to the worker script
    • url <string> The URL to open the worker to
    • referrer <string> An HTTP Referrer URL
    • userAgent <string> A user agent originating the request
    • proxy <string> A proxy that the worker should connect to
    • timeout <number> A maximum number of milliseconds before the worker is automatically closed
    • width <number> The width of the worker window
    • height <number> The height of the worker window
  • returns <Promise(number)> This method resolves when the worker launches successfully. The resolve will always happen before the worker times out.

This method launches a worker process—an isolated subpage—within the module webpage. Workers are useful for bulk tasks.

Note: Currently, launching a worker requires a page navigation to a custom inner page prior to execution. This process happens automatically. For workers to be enabled on a module, the main.json module properties must contain webview: true.

Miscellaneous methods

somiibo.alert(options)

  • options <Object> Function to be passed to the alert process
    • type <string> Type of the alert
    • title <string> Title of the alert
    • content <string> HTML enabled content of the alert
    • button <string> Text on the alert's button
  • returns <null>

Display an alert message to the user.

Events

event: 'error'

  • event <Event> The generic event
  • error <Error> The error object thrown by the module
  • meta <Object> Includes information about the error
    • navigation <boolean> Whether or not the error was due to navigation

Emitted when the module.js script encounters a fatal error. The default behavior is to stop the module and display an error to the user but this can be prevented with event.preventDefault(). Usually (but not always), navigation errors can be recovered from and calling event.preventDefault() is advised.

event: 'new-worker'

  • event <Event> The generic event
  • payload <Object> Includes information on the success or failure to setup the worker
    • success <boolean> Whether or not the new worker was setup successfully

Emitted when a worker completes its setup phase.

somiibo.browser() API

This API is responsible for navigating and interacting with the single browser window that each module gets.

somiibo.browser().navigate(url, options)

  • url <string> A URL to navigate to
  • options <Object>
    • referrer <string> An HTTP Referrer URL
    • userAgent <string> A user agent originating the request
  • returns <Promise(null)> The promise resolves when the page finishes loading

Navigates the module webpage.

somiibo.browser().navigateBack(offset)

  • offset <number> An offset to navigate backwards
  • returns <Promise(null)> The promise resolves when the page finishes loading

Navigates the module webpage backwards as if the user pressed the back button. offset is the number of pages in the history to go back and defaults to 1.

Note: If the offset provided doesn't exist, no navigation will occur.

somiibo.browser().navigateForward(offset)

  • offset <number> An offset to navigate forwards
  • returns <Promise(null)> The promise resolves when the page finishes loading

Navigates the module webpage forwards as if the user pressed the forward button. offset is the number of pages in the history to go forward and defaults to 1.

Note: If the offset provided doesn't exist, no navigation will occur.

somiibo.browser().reload(offset)

  • returns <Promise(null)> The promise resolves when the page finishes reloading

Reloads the current webpage without affecting the history index as if the user pressed the reload/refresh button.

somiibo.browser().getURL()

  • returns <string> The promise resolves when the page finishes geturling

Returns the webpage's current URL.

somiibo.browser().select(selector, options)

  • selector <string> A selector to query page for
  • options <Object>
    • index <?number, ?string> Index of the element array to return
    • filters <?Array(Object)> An array of filter objects that narrow down the returned array
    • retrieve <?Array(string)> An array of attributes or element properties to include in the returned array
    • wait <?number> A maximum number of milliseconds to wait as the selector is periodically polled
    • positionMethod <?string> Control whether the position is calculated cumulative (default) or bounding
  • returns <Promise(Object)> This method resolves when the element is found or determined to not exist and returns a jQuery-like representation of the selected elements.

This method runs document.querySelectorAll within the page and stores the result in somiibo.browser().properties.select. The currently selected element is stored until overwritten by another call of .select() or a navigation occurs.

The positionMethod determines how the elements x and y are calculated.

Note: Since the module webpage runs in a separate process, it is not possible to access the ElementHandle directly from somiibo.browser().properties.select. Instead, somiibo.browser().properties.select will contain a jQuery-like representation of the result.

somiibo.browser().scroll(position, options)

  • position <?string, ?Object> Position or element on page to scroll to
  • options <Object>
    • offsetX <?number> Offset scroll amount on x axis
    • offsetY <?number> Offset scroll amount on y axis
  • returns <Promise(Object)> This method resolves when the in-page scroll completes or when page navigation completes (if the scroll triggers a navigation) and returns the result of the scroll.

This method scrolls the page based on the current position of the mouse and stores the result in somiibo.browser().properties.scroll.

If position is undefined or somiibo.browser().$selected, the method will try to scroll to the currently selected element.

offsetX and offsetY are absolutely necessary if there are fixed navs or footers on the page or else the element being scrolled to might get stuck under the nav/footer.

somiibo.browser().move(position, options)

  • position <?string, ?Object> Position or element on page to move the mouse to
  • options <Object>
    • offsetX <?number> Offset move amount on x axis
    • offsetY <?number> Offset move amount on y axis
    • ignoreScrollOffset <?boolean> This method resolves when the in-page mouse movement is complete or when page navigation completes (if the mouse movement triggers a navigation) and returns the result of the mouse movement.
  • returns <Promise(Object)> This method resolves when the in-page move completes or when page navigation completes (if the move triggers a navigation) and returns the result of the move.

This method moves the mouse to a position or element and stores the result in somiibo.browser().properties.mouse.

somiibo.browser().click(position, options)

  • position <?string, ?Object> Position or element on page to click
  • options <Object>
    • offsetX <?number> Offset click amount on x axis
    • offsetY <?number> Offset click amount on y axis
    • move <?boolean> Whether to move the mouse to the position before the click event is fired (defaults to true)
    • ignoreScrollOffset <?boolean> Whether to ignore window.scrollX & window.scrollY when calculating path. This should usually be true if the target element exists on an overlay or popup.
  • returns <Promise(Object)> This method resolves when the in-page mouse click is complete or when page navigation completes (if the click triggers a navigation) and returns the result of the mouse click.

If position is undefined or somiibo.browser().$selected, the method will try to click on the currently selected element.

somiibo.browser().type(input, options)

  • input <Array(string)> An array of strings to type
  • options <Object>
    • delayMin <?number> Minimum delay between keystrokes
    • delayMax <?number> Maximum delay between keystrokes
  • returns <Promise(Object)> This method resolves when the in-page typed string is complete or when page navigation completes (if the typed string triggers a navigation) and returns the result of the keyboad type.

Special keys such as Enter must be in their own array element:

['Space', 'Tab', 'Backspace', 'Delete', 'Up', 'Down', 'Left', 'Right', 'Escape', 'Enter']

somiibo.browser().getVariable(path, compare, options)

  • path <string> Path to the variable
  • compare <?Function> Function to compare the result of the variable
    • value <any> The requested variable's current value
  • options <Object>
    • wait <?number> A maximum number of milliseconds to wait for as the variable is periodically polled.
  • returns <Promise(any)> This method resolves when the variable is retrieved and either matches the compare function or times out.

Get and return a variable from within the webpage. Only global scoped variables are acessible. The variable polling will continue until either the compare function returns true or a maximum amount of wait time elapses.

somiibo.browser().execute(fn, options)

  • fn <Function> Function as a string to execute within the module webpage
  • options <Object>
    • arguments <Array(...any)> Arguments to be passed to the script
  • returns <Promise(Object)> A promise that resolves with an object with keys
    • success <boolean> true if the script executed successfully or else false
    • result <any> result returned from the fn or an Error message

This method executes a function in the context of the module webpage. Whatever is returned from the function will be passed to the result property of the resolved Promise value.

somiibo.browser().solveCaptcha(options)

  • options <Object>
    • mode <string> The type of captcha to solve (currently reCaptchaV2 & hCaptcha are supported)
    • service <string> The type of captcha to solve (currently 2Captcha & antiCaptcha are supported)
    • auto <?boolean> Whether the captcha should be automatically detected and solved (Defaults to true)
    • sitekey <?string> The sitekey of the captcha (will be automatically determined if auto is true)
  • returns <Promise(Object)> A promise that is rejected with an Error if the captcha fails or resolves with an object with keys:
    • result <string> The result of the captcha solve

This method can detect and solve a captcha on the module webpage. When auto is true, the API will attempt to determine mode & sitekey automatically but it is better to supply them if the captcha mode is known. service will automatically be set to whatever the user has chosen in their preferences but it can be overriden by setting it manually.

somiibo.browser() Events

event: 'new-window'

  • event <Event> The generic event
  • window <Class> The error object thrown by the module
    • .setVisibility(state, options)
      • state <string> Visibility state of the window which can be hide or show
      • options <Object> Options for the visibility function
        • inactive <?boolean> Activity state of the window which can be true or false where true will not focus the window
      • returns <null>
    • .navigate(url)
      • url <string> URL to navigate to
      • returns <Promise(null)> A promise that resolves when the page finishes navigating or rejects if the navigation fails
    • .setAudioMuted(state)
      • state <boolean> Audibility state of the window which can be true or false
      • returns <null>
    • .setFocusable(state)
      • state <boolean> Controls the user's ability to focus the window which can be true or false
      • returns <null>
    • .setAlwaysOnTop(state)
      • state <boolean> Controls the windows position on top of other windows which can be true or false
      • returns <null>
    • .getURL()
      • returns <string> The current URL of the window
    • .openDevTools() Open the DevTools of the window
      • returns <null>
    • .setScript(script, options) Set a script that will be executed within the window
      • script <Function> Script that will be executed on every navigation of the window
      • options <Object> Open the DevTools of the window
        • arguments <Array(any)> An array of arguments that are passed to the script
      • returns <null>
      • Note: The script has full access to the DOM and the window object since it is executed directly on the page

Emitted when the module browser window receives a request to open a new window. The default behavior is to open the new window but the window will be hidden, unfocused, and muted.

If you do not expect your module to open windows, you should listen for this event and call window.close() immediately.

somiibo.device() API

This API is responsible for interacting with the user's device and getting information about the user's device and OS.

somiibo.device().getOS()

  • returns <Object> An object with properties
    • platform <string> The platform (in Node.js terms)
    • name <string> The platform's simple name
    • version <string> The OS version

Returns the current user's operating system data as an object.

somiibo.tabs() API

This API is responsible for interacting with other open tabs on Somiibo

somiibo.tabs().query(fn)

  • fn <Function> A filtering function that is called on tab object with tab and index
    • tab <Object> A read-only object representing the tab
      • id <number> The ID of the tab
      • active <boolean> Boolean representing if the tab has focus
      • url <string> The current URL of the tab
      • type <string> Type of the tabs (module or browser)
      • module <Object> Object representing the module if type is module
        • moduleId <string> The ID of the module from the module's package
        • packageId <string> The ID of the package
        • properties <Object> An object of module properties
          • running <boolean> The run state of the module
          • settings <Object> Object representing the module's running settings
          • webContentsId <number> The webContents ID
          • webContentsId <number> The webContents ID
        • session <string> The Session ID of the tab
        • partition <string> The Session partition of the tab
        • userAgent <string> The userAgent string of the tab
    • index <number> The index of the loop
  • returns <Array(Class)> An array of tab objects matching the query filter

Iterates through all opened tabs returns an array of tabs matching the filter fn. Return true inside the fn to include the tab in the result.

somiibo.tabs().add(options)

  • options <Object>
    • url <string> The URL of the new tab
    • session <?string> The Session ID of the new tab
  • returns <Promise(Object)> The promise resolves when the tab is opened and passes the new tab object.

Opens a new tab with the options. In the future, this method will be able to open tabs with the module type. You can get the session ID of a Session from somiibo://settings in the Sessions panel.

somiibo.tabs().close(id)

  • id <number> ID of the tab to close
  • returns <Promise(null)> The promise resolves when the tab is closed.

Closes a tab with id.

somiibo.tabs().navigate(id, url, options)

  • id <number> ID of the tab to navigate
  • url <string> The URL to navigate to
  • options <Object>
    • referrer <string> An HTTP Referrer URL
    • userAgent <string> A user agent originating the request
  • returns <Promise(null)> The promise resolves when the page finishes loading.

Navigates the tab with id to the url.

somiibo.tabs().start(id)

  • id <number> ID of the tab to start
  • returns <Promise(null)> A Promise that resolves when the module finishes starting or rejects if startup failed

Start the tab's module with id.

somiibo.tabs().stop(id)

  • id <number> ID of the tab to stop
  • returns <Promise(null)> A Promise that resolves when the module finishes stoping or rejects if stopup failed

Start the tab's module with id.

× You are using an outdated browser that our site DOES NOT support. Please click here to update your browser.