# Reference

### Initialisation

#### `stub.init(options)`

Initialises the SDK. Call this before using any other method.

```javascript
window.stub.init({
  appId: '<appid>',          // required
  businessId: '<businessid>',// required
  token: '<token>',          // required
  test: false,
  month: 1,
  year: 2025,
  colours: ['#00A86B', '#6477E3'],
  font: "'Public Sans', Arial, sans-serif",
  emptyImage: {
    light: 'https://your.site/light.png',
    dark: 'https://your.site/dark.png'
  },
  renderImmediately: false
});
```

If `renderImmediately` is `true` you don't need to call `stub.render()` to render the widgets. But make sure that the DOM is ready when you call `stub.init()`, otherwise the widgets will not render.

### Core methods

* **`stub.render()`** – Mount the widgets into the DOM.
* **`stub.refresh()`** – Reload the data displayed in the widgets.
* **`stub.set(options)`** – Update the month, year or authentication token.
* **`stub.getDetails()`** – Retrieve details about the current business.
* **`stub.hasBankAccounts()`** – Returns `true` if the business has any bank accounts on file.
* **`stub.hasLinkedBankAccounts()`** – Returns `true` if any bank account is linked and can sync.
* **`stub.isInitialised()`** – Indicates whether the SDK has been initialised and loaded.

```javascript
// set() options

stub.set({
    month: 3,
    year: 2055,
    token: '<TOKEN>',
})
```

### Bank actions

* **`stub.linkBankAccounts()`** – Start the bank linking flow in the current window.
* **`stub.manageBankAccounts()`** – Open the manage accounts screen in a new tab.

### Events

Use `stub.addEventListener(fn)` to listen for events and `stub.removeEventListener(fn)` to remove a listener. The callback receives an object with `event`, `srcWidget`, `srcElement` and `timeStamp` fields.

Events include:

* `init`, `loading`, `loaded`
* `uncategorised-income-list-opened`, `uncategorised-income-list-closed`, `income-list-opened`, `income-list-closed`, `income-info-opened`, `income-info-closed`, `income-added`, `income-edited`, `income-deleted`, `income-categorised`, `sales-report-opened`
* `uncategorised-expenses-list-opened`, `uncategorised-expenses-list-closed`, `expenses-list-opened`, `expenses-list-closed`, `expenses-info-opened`, `expenses-info-closed`, `expense-added`, `expense-edited`, `expense-deleted`, `expense-categorised`, `expense-report-opened`
* `profit-info-opened`, `profit-info-closed`, `profit-and-loss-report-opened`
* `cashflow-info-opened`, `cashflow-info-closed`, `cashflow-report-opened`
* `balance-sheet-report-opened`, `trial-balance-opened`
* `bank-link-started`, `bank-sync-started`, `bank-sync-completed`, `bank-edit-started`, `bank-refresh-started`, `manage-bank-accounts-started`

### TypeScript usage

You can use the SDK from TypeScript by declaring the `stub` object on the `Window` interface and downloading the type definition from `https://embed.stub.africa/stub-widgets.d.ts`.

```typescript
declare global {
  interface Window { stub: stub }
}

window.stub.init(options);
window.stub.render();
```