Reference

All the functions and properties available on the stub SDK

init()

Initialise stub. You'll get an error if you try call anything else before you've called this. Only the first 3 props are required, the others are optional.

window.stub.init({
    appId: 'xxxxx',
    businessId: 'xxxxx', 
    token: 'xxxxx',
    test: false,
    month: 2, 
    year: 2024, 
    colours: ['pink','#00A86B','rgb(0,100,200)','#143B78','#9599B2'], 
    font: "'Comic Sans', Arial, sans-serif",
    emptyImage: {
        light: 'https://url.of.your.own/image.png',
        dark: 'https://url.of.your.own/image.png'
    },
    renderImmediately: true
})

renderImmediately is false by default, because most of the time you will want to initialise stub before you have rendered the DOM elements to which it should attach. But if you are running a simpler setup

render()

Render the widgets in the DOM. You can call this multiple times and stub will recreate the DOM each time—but it will not refresh the underlying data. Use refresh() if you just want to refresh the data.

window.stub.render()

refresh()

Refresh the data presented in the widgets. Use this if you've called another stub API somewhere and the widgets need to be updated to reflect the latest data.

window.stub.refresh()

set()

Update the month, year or token.

const stub = window.stub
stub.set({
    month: 4,
    year: 2024, 
    token: 'xxxxx'
})

getDetails()

Get the details of the current business.

const stub = window.stub
stub.getDetails()
/* {
    currency: 'ZAR',
    email: '[e-mail]',
    id: 'xxxxx',
    logo: 'url',
    name: 'Business name',
    premium: true
} */

hasBankAccounts()

Get a Boolean indicating whether the business has bank accounts.

const stub = window.stub
stub.hasBankAccounts() // true

hasLinkedBankAccounts()

Get a Boolean indicating whether the business has linked bank accounts.

const stub = window.stub
stub.hasLinkedBankAccounts() // true

linkBankAccounts()

Initiate linking bank accounts for the business. This will create a session, open it in the current window and return to the current URL.

const stub = window.stub
stub.linkBankAccounts()

The user will be routed back to the current URL, when this function is called, on both success or cancellation of linking.

addEventListener()

Add an event listener for stub events. Listeners will be called with single parameter for the synthetic Event.

const stub = window.stub
const doSomething = (event) => console.log(event)
stub.addEventListener(doSomething)

Events are emitted for the following:

init
loading
loaded

expenses-list-opened
expenses-list-closed
expenses-info-opened
expenses-info-closed
expense-categorised
expense-edited
expense-added
expense-deleted
expense-report-opened

add-expense-opened
add-expense-closed
edit-expense-opened
edit-expense-closed
delete-expense-opened
delete-expense-closed

income-list-opened
income-list-closed
income-info-opened
income-info-closed
income-categorised
income-edited
income-added
income-deleted
income-report-opened

add-income-opened
add-income-closed
edit-income-opened
edit-income-closed
delete-income-opened
delete-income-closed

bank-link-started
bank-sync-started
bank-sync-completed

profit-info-opened
profit-info-closed
profit-and-loss-report-opened
balance-sheet-report-opened

cashflow-info-opened
cashflow-info-closed
cashflow-report-opened

The listener that you add will be called with exactly one parameter with details about the respective event:

{
    event: '<event-name>',
    srcElement: '<src-element>', // only if available
    srcWidget: '<src-widget>, // only if the event was emitted by a specific widget
    timeStamp: 1721121465704
}

You can see an example of this with the following:

const doSomething = (event) => console.log(event)
window.stub.addEventListener(doSomething)
/*
{
    "event": "profit-info-focused",
    "timeStamp": 1721121465704,
    "srcWidget": "profit",
    "srcElement": "button#stub-profit-info"
}
*/

srcElement and srcWidget may be undefined if the event originated from the SDK directly. For example, the loaded event is originated by the SDK directly—and not from a user interaction.

removeEventListener()

Remove an event listener that you've previously added. If you must.

const stub = window.stub
const doSomething = (event) => console.log(event)
stub.addEventListener(doSomething)
stub.removeEventListener(doSomething)

Typescript

The Embedded Accounting widget is built and published in Javascript, but it can be used in Typescript projects as well.

1. Include the script tag as usual on index.html

2. Download the interface type definition https://embed.stub.africa/stub-widgets.d.ts and include it in your project
3. Link the widget object to the global Window interface

4. Initialize the widget with you appId,businessId, and token

5. Once the DOM has loaded, call the render() method to load the widgets into the DOM.

// Example from example Typescript + React started code

import React from 'react';
import './App.css';


declare global {
  interface Window { stub: stub; }
}

const options = { 
  appId: '<appid>', 
  businessId: '<businessid>', 
  token: '<token>', 
  test: true,
  modal: "#stub-modal", 
}

const stub =  window.stub || {};
stub.init(options)

function App() {

  React.useEffect(() => {
    stub.render()   
  }, []);

  return (
    <div className="App">
      <div id="stub-cashflow"></div>
      <div id="stub-income"></div>
      <div id="stub-expenses"></div>
      <div id="stub-profit"></div>
    </div>
  );
}

export default App;