@yuno-payments/dashboard-embed-sdk

Lightweight SDK for embedding the Yuno Dashboard via iframe. Zero dependencies — uses only DOM APIs.

Installation

npm install @yuno-payments/dashboard-embed-sdk

Quick Start

import { initYunoDashboard } from "@yuno-payments/dashboard-embed-sdk";

const sdk = initYunoDashboard({
  baseUrl: "https://dashboard.y.uno",
  container: document.getElementById("dashboard")!,
  token: "your-jwt-token",
  theme: {
    // Simple: flat tokens apply to both light mode and dark mode;
    tokens: { primary: "#134AC3", surface: "#FFFFFF" },
    // Per-mode: full control over both light and dark colors
    // tokens: {
    //   light: { primary: "#134AC3", surface: "#FFFFFF" },
    //   dark: { primary: "#5B7BFF", surface: "#0A0A0A" },
    // },
    typography: {
      fontFamily: "'Inter', sans-serif",
      fontUrl: "https://fonts.googleapis.com/css2?family=Inter",
    },
    mode: "light",
    styles: ".yuno-card { border-radius: 8px; }",
  },
  lang: "en",
  path: "/connections",
  onReady: () => console.log("Dashboard is ready"),
});

API

Singleton helpers

The recommended way to manage the SDK instance:

import {
  initYunoDashboard,
  getYunoDashboard,
  destroyYunoDashboard,
} from "@yuno-payments/dashboard-embed-sdk";

// Create (destroys any previous instance automatically)
const sdk = initYunoDashboard(config);

// Retrieve the current instance from anywhere
const sdk = getYunoDashboard();

// Destroy the instance and clean up
destroyYunoDashboard();

initYunoDashboard(config)

| Option | Type | Required | Description | |---|---|---|---| | baseUrl | string | Yes | Dashboard base URL | | container | HTMLElement | Yes | Element to mount the iframe | | token | string | No | JWT auth token — sent via PostMessage after the iframe is ready | | theme | DashboardTheme | No | Initial theme configuration | | lang | string | No | Language code (default: "en") | | path | string | No | Initial navigation path (default: "/") | | onReady | () => void | No | Callback invoked when the dashboard is fully loaded and authenticated | | onSessionExpired | () => void | No | Callback invoked when the embedded session has expired. The host should re-authenticate and call setToken(newToken) to resume. | | loading | HTMLElement | No | Custom loading overlay element. If omitted, a default spinner is shown |

Methods

• setTheme(theme) — Update colors, typography, mode, or external styles
• setLang(lang) — Change display language
• setToken(token) — Update the auth token via PostMessage
• navigate(path) — Navigate to a dashboard route
• destroy() — Remove iframe and clean up event listeners

Types

interface ThemeColors {
  primary: string;
  primaryForeground: string;
  secondary: string;
  secondaryForeground: string;
  background: string;
  foreground: string;
  muted: string;
  mutedForeground: string;
  accent: string;
  accentForeground: string;
  destructive: string;
  destructiveForeground: string;
  border: string;
  input: string;
  ring: string;
  surface: string;
  card: string;
  cardForeground: string;
  popover: string;
  popoverForeground: string;
  success: string;
  warning: string;
  info: string;
}

interface ThemeTypography {
  fontFamily: string;
  fontUrl: string;
}

interface ModeTokens {
  light?: Partial<ThemeColors>;
  dark?: Partial<ThemeColors>;
}

interface DashboardTheme {
  tokens?: Partial<ThemeColors> | ModeTokens; // flat OR per-mode
  typography?: Partial<ThemeTypography>;
  mode?: "light" | "dark";
  styles?: string; // Custom CSS injected into the dashboard
}

Session timeouts

By default, sessions issued by POST /v1/external/authenticate are valid for 24 hours. You can issue a shorter session by passing timeout_seconds (between 60 and 86400):

curl -X POST https://api.y.uno/v1/external/authenticate \
  -H "x-organization-code: <your-org-uuid>" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"<user-uuid>", "timeout_seconds": 1800}'

When the embedded session expires, the iframe paints a "Session expired" overlay and emits a message to the host. Subscribe via onSessionExpired:

const sdk = initYunoDashboard({
  baseUrl: "https://dashboard.y.uno",
  container: document.getElementById("dashboard")!,
  token: initialToken,
  onSessionExpired: async () => {
    const newToken = await myBackend.requestEmbedToken({ timeout_seconds: 1800 })
    sdk.setToken(newToken)
  },
})

Loading overlay

A loading overlay covers the iframe while initialization completes. You can provide a custom element via the loading config option, or the SDK renders a default spinner. The overlay fades out automatically (300ms transition) once the dashboard is authenticated and ready.

Development

npm install
npm run build      # Build with tsup
npm run dev        # Watch mode
npm run type-check # TypeScript check