Financial Data Platform | Modernbanc
Vault

@modernbanc/js

Modernbanc JS is a plain Javascript library that you can use to embed elements such as inputs and outputs into your UI that will collect or show sensitive data.

Elements are modular, fully customizable so you can easily make them fit your user experience. They’re embedded into your app as securely hosted iFrames that isolate your app from sensitive data. Behind the scenes they use the same /secrets endpoints as in the guide above.

Installation

npm install @modernbanc/js

Initializing

You can initialize your instance with an api key. Make sure that this key has permissions to work with secrets (secret).

const mdb = Modernbanc.init('DEV_TEST_KEY')

Once you’ve initialized it you can start creating or accessing elements.

const elem1 = mdb.addElement({ type: 'input', id: 'card_number' })

You can also access them at any time later.

const elem1 = mdb.getElement({ type: 'input', id: 'card_number' })

Mounting elements

You can mount an element using mount function which will add it to the first div that matches specified css selectors

elem1.mount('#card_number')

The above will put an iFrame as a child of the first div that has card_number id. You can also create and mount elements at the same time:

mdb.addElement({ type: 'input', id: 'card_number', selectors: '#card_number' })

Input element

Create element options.

type InputOptions = {
  id: 'any_id' // Used for identifying the element.
  type: 'input'
  class?: string // Class to be passed to the element.
  css?: string // Raw css string to be passed to the element.
  placeholder?: string
  disabled?: string
  'aria-label'?: string
  auto_complete?: string // Enable auto-complete for this input.
  value?: string // Override current or set an initial input value.
  html_type?: TInputHTMLType // Native <input> html type.
  validation?: {
    regex?: RegExp // if specified on('change') will return a `valid` prop.
  }
}

Methods:

  • setOptions - allows you to update the above options and push the changes to element at any time.
  • createSecret - creates and returns a new secret based on the current text within the input.
    const response = await elem1.createSecret()
    if (response && !response.is_error) {
      console.log(response.secret_id)
    }
  • on(event_type, handler_fn) - subscribe to events:
    • ready - iFrame was loaded
    • change- input value was updated.
    • focus - input was focused.
    • blur - input was unfocused/blurred.
    • key_down - key down event.
  • mount - places the element under a first div that matches css selector. Not needed if you provided selectors in a mdb.addElement method.
  • unmount - removes the element from its parent div.

Extra states:

  • When relevant we add following classes to html element.
    • .empty
    • .valid
    • .touched

Output element:

Options.

type OutputOptions = {
  type: 'output'
  id: 'any_id' // Used for identifying the element.
  class?: string // Class to be passed to the element.
  css?: string // Raw css string to be passed to the element.
  secret_id: string // Id of a secret to show.
}

Methods:

  • setOptions - allows you to update the above options at any time.
  • showSecretValue - reveals the value behind the secret_id
  • on(event_type, handler_fn) - subscribe to events:
    • ready - iFrame was loaded.
  • mount - places the element under a first div that matches css selector. Not needed if you provided selectors in a mdb.addElement method.
  • unmount - removes the element from its parent div.

Styling:

Every element has following properties:

  • css - Raw css string that you can pass directly to the component, E.g background: gray; border: 1px solid black. You can also use it to load a custom font for your inputs.
    • We also expose following css variables that you can refer to within your app.
    --font-size-3xs: 0.563rem; /* 9px */
    --font-size-2xs: 0.625rem; /* 10px */
    --font-size-xs: 0.688rem; /* 11px */
    --font-size-sm: 0.75rem; /* 12px */
    --font-size-md: 0.813rem; /* 13px */
    --font-size-lg: 0.875rem; /* 14px */
    --font-size-xl: 0.9375rem; /* 15px */
    --font-size-2xl: 1rem; /* 16px */
    --font-size-3xl: 1.125rem; /* 18px */
    --font-size-4xl: 1.25rem; /* 20px */
    --font-size-5xl: 1.5rem; /* 24px */
    --font-monospace: 'Roboto Mono', monospace;
    --font-regular: 'Inter', sans-serif;
    --speed-transition-very-fast: 70ms;
    --speed-transition-fast: 100ms;
    --speed-transition-normal: 150ms;
  • class - A string containing one or more classes that we pass directly to the html element.