Coast Widget SDK

Embed Coast in your web application.

Getting Started

npm install @coastpay/embedded-widget-sdk

Load the SDK and initialize:

import { loadCoast } from '@coastpay/embedded-widget-sdk';

const coast = await loadCoast();

const widget = coast.initialize({
  container: 'coast-container', // element id or HTMLElement
  embedToken,
  onReady: () => {
    // the embedded app has finished loading and is ready to be used
    console.log('Coast widget is ready');
  },
  onError: (error) => {
    console.error('Coast widget error:', error);
  },
});

API

coast.initialize(options)

Mounts the widget iframe into the container element and returns a CoastWidget instance.

Single-instance limit: Only one widget may be active at a time. Calling initialize() while a widget already exists automatically destroys the previous one.

| Option | Type | Required | Description | | ------------ | ------------------------ | -------- | --------------------------------------------------------------------------------------- | | container | string \| HTMLElement | Yes | Element id or a direct HTMLElement reference | | embedToken | string | Yes | Opaque session token from your backend's Embed Token API call | | onReady | () => void | No | Called when the embedded app has finished loading and is ready to be used | | onError | (error: Error) => void | No | Called on initialization failure or if the embedded app fails to load within 30 seconds | | onLogout | () => void | No | Called when the user logs out from within the embedded app (e.g. session expiry) |

widget.logout()

Notifies the embedded app that the host user has logged out. Call this when your own session ends.

widget.destroy()

Removes the iframe and cleans up all event listeners.