npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@getsensibill/web-sdk

v0.8.8

Published

This guide serves as a quickstart and general overview of how to integrate with the Sensibill Web SDK.

Downloads

55

Readme

Sensibill Web SDK Integrator Guide

This guide serves as a quickstart and general overview of how to integrate with the Sensibill Web SDK.

# Using npm
npm i @getsensibill/web-sdk

# Using yarn
yarn add @getsensibill/web-sdk

Import where you need it

import { SensibillSDK } from '@getsensibill/web-sdk';

Initialization

An initialization object which will be used to build the iframe url. The object should include the following properties:

| Name | Required? | type | Use | | ------------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ | | id | false | string | Every instance requires a unique ID. If you'd like, you can provide the ID yourself. | | clientID | true | string | Your unique client ID. | | environment | true | string | One of 'fastlane' 'staging' 'sandbox' 'production'. | | locale | false | string | The locale you would like to load the UI in. You can change this later. | | source | false | string | The source platform loading the web-ui app. Defaults to web-sdk. One of 'web-sdk' 'mobile-sdk' 'tecton-web-sdk' 'tecton-mobile-sdk'. | | disableNav | false | boolean | Disable the breadcrumb navigation bar when true. Defaults to false. |

Locale Breakdown

Available options:

  • 'en', 'en_AU', 'en_CA', 'en_GB'
  • 'es', 'es_ES', 'es_US'
  • 'fr', 'fr_CA'

Notes on the non-country locales:

  • 'en' locale is equal to 'en_US' and is the default locale if no match can be made based on the client’s locale.
  • 'es' locale is equal to 'es_US'
  • 'fr' locale is equal to 'fr_CA'

Opening a Sensibill iframe

Opening an iframe to Sensibill can be done with as little code as the following:

const instance = await SensibillSDK.create(
  // Provide a reference to the element you want to contain the iframe
  document.getElementById('your-element'),

  // Provide an initialization object which contains your client id
  { clientID: 'your-client-id', environment: 'a-valid-environment-value' },

  // Provide a configuration object which contains your access token at a minimum
  { authentication: { accessToken: 'a-valid-access-token' } },
);

While this will open and work fine, occasionally you may need to provide a new access token. You can provide one on demand with the following code:

function refreshAuthentication() {
  // Do what you need to get your new token.  This can be synchronous, or asynchronous.  The iframe will wait.
  const myNewToken = getNewToken();

  // Once you have it, set the new token on the instance
  instance.setToken(myNewToken);
}

// Run the refreshAuthentication function whenever the instance asks for a new token
instance.registerListener(refreshAuthentication, 'getNewToken');

Runtime Branding Configuration

You can inject your brand's font and colors when you initialize the Sensibill instance.

To configure all of the branding properties, include a brand block when opening the Sensibill iframe:

const instance = await SensibillSDK.create(
  // Provide a reference to the element you want to contain the iframe
  document.getElementById('your-element'),

  // Provide an initialization object which contains your client id
  { clientID: 'your-client-id', environment: 'a-valid-environment-value' },

  // Provide a configuration object which contains your access token and branding overrides
  {
    brand: {
      fonts: {
        families: {
          primary: {
            name: 'Sarabun',
            link: 'https://fonts.googleapis.com/css2?family=Sarabun&display=swap',
          },
        },
      },
      colors: {
        primary: '#186DB3',
        primaryVariant: '#21384D',
        onPrimary: '#EEEEEE',
        secondary: '#F8897F',
        onSecondary: '#FEFEFE',
        background: '#FBFBFB',
        onBackground: '#4F5056',
        surface: 'lightgray',
        onSurface: '#000000',
        surfaceVariant: '#E2F9FF',
        onSurfaceFocus: '#0990D5',
        error: '#FF0000',
        onError: '#FFFFFF',
      },
    },
    authentication: { accessToken: 'a-valid-access-token' },
  },
);

Font

Under fonts, supply a Google font name and link, taken from the value of the href in the font's page. For example, to load Sarabun:

  1. Navigate to the Sarabun font page
  2. For the name, use the font name: Sarabun
  3. To find the link, look for the <link> section in the right-hand panel and copy the value of the href. It should start with https://fonts.googleapis.com

The app currently uses just one font.

getLinkedTransactions

Function to get transactions that match the external account transaction id's provided as input

  SensibillSDK.getLinkedTransactions(
  // array of external transaction id's
  ['123', '456'],

  // Provide a valid environment value - default is beta-prod
  'a-valid-environment-value',

  // Provide your access token
  'a-valid-access-token',
);

//output example
{
  "123": {
    "id": "abc999",
    "date": "2021-08-12",
    "merchant": "Test",
    "total": 15
  },
  // no match found returns null for id value
  "456": null
}

getMatchingTransactions

Function to get transactions that potentially match given input

  interface ExternalAccountTransaction {
    id: string;
    amount: number;
    currencyCode: string;
    date?: string;
    postedDate?: string;
  }
  // one of date or postedDate must be included

  SensibillSDK.getMatchingTransactions(
  // array of external ExternalAccountTransaction
  [
    {
      id: 'acb999',
      amount: 15,
      currencyCode: 'CAD',
      date: '2021-09-08',
    },
    {
      id: 'xyz999',
      amount: 10,
      currencyCode: 'CAD',
      date: '2021-09-08',
    }
  ],

  // Provide a valid environment value - default is beta-prod
  'a-valid-environment-value',

  // Provide your access token
  'a-valid-access-token',
);

//output example
{
  "abc999": {
    "id": "abc999",
    "date": "2021-08-12",
    "merchant": "Test",
    "total": 15
  },
  // no match found returns null for id value
  "xyz999": null
}
 // if multiple matches are found, the value will be an array of objects

SDK Errors

The Sensibill Web SDK has custom error types to help clients integrate with the SDK.

The goal of these errors is to catch SDK errors and provide developer documentation to help clients integrate with the SDK. These errors are not meant to help users on the clients sites.

Missing Client Error

WEB_SDK_ERROR_MISSING_CLIENT

This error is a critical error that would occur if the client is attempting to initialize an instance without providing their client ID.

This should just help catch a sloppy integration and avoid back and forth with Sensibill.

Missing Target Error

WEB_SDK_ERROR_MISSING_TARGET

Clients must provide an HTML element to mount the iframe in. If they do not, they are presented with this error.

This should help diagnose errors where a client is integrating the SPA dynamically.

Target in use Error

WEB_SDK_ERROR_TARGET_IN_USE

When an iframe is initialized it is placed in the provided target element. It becomes the sole child in that element.

This is an intentional decision to prevent errors from iframes sharing targets.

This error is provided to help inform clients who may be attempting to reuse a target. It may also help discover instances where the same instance is being initialized multiple times.