module.js API

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

        
          let somiibo;
async function main(mod) {
  somiibo = mod;

  // Build your module logic here

  somiibo.loop(main);
}

module.exports = main;

        
      

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'.

        
          // Example 1
          somiibo.initialize((defaults) => {
            somiibo.log('Hello, World! I only run once.');
          });

          // Example 2 (Overwrite some defaults)
          somiibo.initialize((defaults) => {
            defaults.loop.delay = 5000;
            defaults.browser.scroll.offsetY = 150;
          });
        
      

somiibo.loop(fn, delay)

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

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

        
          let somiibo:
          async function main(mod) {
            somiibo = mod;
            somiibo.loop(main);
          }
          module.exports = main;
        
      

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.

        
          let somiibo:
          async function main(mod) {
            somiibo = mod;
            somiibo.stop();
          }
          module.exports = main;
        
      

somiibo.error(reason)

• returns <null>

Stop module execution and displays an error message with reason.

        
          let somiibo:
          async function main(mod) {
            somiibo = mod;
            somiibo.error(new Error('Oops!'));
          }
          module.exports = main;
        
      

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.

        
          // Waits 5 seconds
          await somiibo.wait(5000);

          // Waits a random amount of time between 5 and 10 seconds
          await somiibo.wait(5000, 10000);
        
      

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.

        
        // Gets one settings
        somiibo.log(somiibo.getSetting('mySettingName'));

        // Gets all settings as an object
        somiibo.log(somiibo.getSetting());
        
      

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.log('Hello, World!');
        
      

somiibo.openDevTools()

• returns <null>

Opens the module's dev tools.

        
        somiibo.openDevTools();
        
      

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.

        
          await somiibo.worker(async function (one, two, three) {
            let _ = require('lodash');
            console.log('Args', one, two, three);
            console.log('lodash', _.get(three, 'key'));
            console.log(window.location.href);
          }, {
            arguments: ['one', 23 * 3, {key: 3}],
            url: 'https://app.somiibo.com/tools/diagnostic/',
            proxy: '209.97.189.171:8080',
            userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36',
            referrer: 'https://google.com',
            timeout: 60000,
          });
        
      

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.

        
          somiibo.alert({
            type: 'success', // 'success', 'warning', 'danger', 'info',
            title: 'Hello, World!',
            content: '<h1>Greetings</h1> <br> This is my message.',
            button: 'Goodbye'
          });
        
      

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.

        
          somiibo.on('error', (event, error, meta) => {
            somiibo.log('Oops! There was an error', error, meta);

            // If it was a navigation error, we can probably continue safely
            if (meta.navigation) {
              // Calling event.preventDefault() will prevent the module from stopping
              event.preventDefault();
            }
          });
        
      

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.on('new-worker', (event, payload) => {
            somiibo.log('A worker has been set up!', payload);
          });
        
      

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.

        
          // Simple navigation with no options
          await somiibo.browser().navigate('https://google.com');

          // Simple navigation with referrer and userAgent
          await somiibo.browser().navigate('https://google.com', {
            referrer: 'https://reddit.com',
            userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36',
          });
        
      

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.

        
          // Navigate backwards one page
          await somiibo.browser().navigateBack();

          // Navigate backwards three pages
          await somiibo.browser().navigateBack(3);
        
      

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.

        
          // Navigate forwards one page
          await somiibo.browser().navigateForward();

          // Navigate forwards three pages
          await somiibo.browser().navigateForward(3);
        
      

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.

        
          await somiibo.browser().reload();
        
      

somiibo.browser().getURL()

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

Returns the webpage's current URL.

        
          somiibo.log('The current URL is ${somiibo.browser().getURL()}');
        
      

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.

        
          // Simple select
          const elements1 = await somiibo.browser().select('a');

          // Select with filters
          const elements2 = await somiibo.browser().select('a', {
            filters: [
              { splice: [0, 10] },
              { match: { innerText: /my text/i } },
              { match: { innerHTML: /hello<\/span>/i } },
            ],
            index: 3, // can also supply '$random'
            retrieve: ['href'],
            wait: 30000,
          });

          // Select chained with scroll and click actions
          const elements3 = await somiibo.browser().select('a') // select the element
            .then(() => somiibo.browser().scroll(undefined, {offsetY: 100})) // scroll to it
            .then(() => somiibo.browser().click()); // then click it
        
      

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.

        
          // Scroll to the selected element (element must be selected first)
          await somiibo.browser().scroll({x: 100, y: 100}, {offsetX: 50, offsetY: -50});

          // Chaining a scroll to a select
          await somiibo.browser().select('a')
            .then(() => somiibo.scroll(somiibo.browser().$selected, {offsetY: 100}));

          // Providing offsets to the scroll
          await somiibo.browser().scroll(somiibo.browser().$selected, {offsetX: 50, offsetY: -50});
        
      

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.

        
          // Scroll to the selected element (element must be selected first)
          await somiibo.browser().move({x: 100, y: 100}, {offsetX: 50, offsetY: -50});

          // Chaining a move to a select
          await somiibo.browser().select('a')
            .then(() => somiibo.browser().move(somiibo.browser().$selected, {offsetY: 100}));

          // Providing offsets to the scroll
          await somiibo.browser().move(somiibo.browser().$selected, {offsetX: 50, offsetY: -50});
        
      

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.

        
          // Click the selected element (element must be selected first)
          await somiibo.browser().click({x: 100, y: 100});

          // Chaining a click to a select
          await somiibo.browser().select('a')
            .then(() => somiibo.browser().click());

          // Providing offsets to the click
          await somiibo.browser().click(somiibo.browser().$selected);
        
      

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']

        
          // Type a single string
          await somiibo.browser().type(['Hello, World!']);

          // Type a single string and one special key, Enter
          await somiibo.browser().type(['Hello, World!', 'Enter']);

          // Type a string with keystroke delay options
          await somiibo.browser().type(['Hello, World!'], {delayMin: 90, delayMax: 140});
        
      

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.

        
          // Retrieve a variable myVariable without waiting for it
          await somiibo.browser().getVariable('myVariable');

          // Retrieve a nested variable without waiting for it
          await somiibo.browser().getVariable('my.variable.is.nested');

          // Continue polling for myVariable until the function returns true for a maximum of 10 seconds
          await somiibo.browser().getVariable('myVariable', function (value) {
            // value = the current value for myVariable
            return typeof value !== 'undefined';
          }, {wait: 10000})
        
      

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.

        
          // Execute a function with some arguments
          await somiibo.browser().execute(async function (one, two, three) {
            console.log('This is execute inside the page so it has access to the window and document', window, document);
            console.log('Arguments', one, two, three);
            await fetch('https://httpbin.org/delay/5');
            return 'Waited 5 seconds';
          }, {
            arguments: [1, 1 + 1, 'three']
          })
          .then((res) => {
            somiibo.log(res); // Should log: {success: true, result: 'Waited 5 seconds'}
          })
        
      

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.

        
          // Solve a captcha on the current webpage
          // Having auto = true will automatically find the captcha on the page and obtain the sitekey
          await somiibo.browser().solveCaptcha({
            auto: true,
            mode: 'hCaptcha',
            service: '2Captcha',
          })
          .then(async (response) => {
            somiibo.log('Solved captcha', response.result); // The token or the response
            await somiibo.browser().select('the form submit button')
              .then(() => somiibo.browser().click())
          })
          .catch(async (e) => {
            somiibo.log('Error solving captcha', e)
            if (e.code === 'INVALID_KEY' || e.code === 'INVALID_SERVICE' || e.toString().includes('ERROR_KEY_DOES_NOT_EXIST')) {
              somiibo.alert({ code: '$captcha-api-key', input: '', });
              somiibo.stop();
            }
          });
        
      

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.browser().on('new-window', async (event, window) => {
            // At this point, the window is open but hidden, unfocused, and muted

            // We can set a script that will execute on every navigation
            await window.setScript(function (one, two, three) {
              // This script is executed in the context of the new window, so 'window' refers to the global variable within the page
              console.log(arg1, arg2, arg3);
              console.log('window', window);
            }, {
              arguments: ['one', 1 + 1, 3]
            });

            // We can navigate the window if we want
            await window.navigate('https://www.youtube.com/watch?v=dQw4w9WgXcQ');

            // We can show the window
            window.setVisibility(true, {inactive: true});

            // We can unmute the window
            window.setAudioMuted(false);

            // We can open the DevTools
            window.openDevTools(false);

            // We can close the window after 10 seconds
            somiibo.setTimeout(function () {
              window.close();
            }, 10000)
          });
        
      

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.log('OS data:', somiibo.device().getOS());

          // Example output for Windows
          {
            platform: 'win32',
            name: 'windows',
            version: '10.0.17763',
          }

          // Example output for Mac
          {
            platform: 'darwin',
            name: 'mac',
            version: '10.15.4',
          }

          // Example output for Linux
          {
            platform: 'linux',
            name: 'linux',
            version: '10.15.4',
          }
        
      

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.

        
          // Return true to get all tabs
          const allTabs = somiibo.tabs().query((tab, index) => true)

          // Apply a filter to get all tabs on Google
          const tabsOnGoogle = somiibo.tabs().query((tab, index) => {
            return tab.url.includes('https://google.com');
          })

          // Get all tabs with running modules
          const runningModules = somiibo.tabs().query((tab, index) => {
            return tab.type === 'module' && tab.module.running;
          })
        
      

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.

        
          // Open a new tab on the default session and navigate to Google
          await somiibo.tabs().add({
            url: 'https://google.com',
            session: 'default',
          })
          .then(tab => {
            somiibo.log(`New tab opened with ID = ${tab.id}:`, tab);
          })
        
      

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.

        
          // Close tab with id = 69
          await somiibo.tabs().close(69);
        
      

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.

        
          // Navigate tab with id = 69
          await somiibo.tabs().navigate(69, 'https://google.com');

          // Navigate with options
          await somiibo.tabs().navigate(1, 'https://google.com', {
            referrer: 'https://reddit.com',
            userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36',
          });
        
      

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.

        
          // Start tab with id = 69
          await somiibo.tabs().start(69);
        
      

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.

        
          // Start tab with id = 69
          await somiibo.tabs().stop(69);