@vectrify-ai/ui

The official JavaScript embed library for Vectrify. Drop it into any website to render a fully functional Connectors and Documents management interface for a specific tenant, hosted in a secure iframe.

Installation

npm install @vectrify-ai/ui

Or via CDN (UMD bundle):

<script src="https://cdn.vectrify.ai/ui/latest/vectrify-ui.umd.js"></script>

Quick Start

Step 1 — Get an ephemeral token from your backend

Your server calls the Vectrify API with your account JWT:

POST /api/v1/auth/ephemeral-token
Authorization: Bearer <your-account-jwt>
Content-Type: application/json

{ "tenantId": 42, "scope": "admin" }

Response:

{
  "accessToken": "<short-lived-jwt>",
  "refreshToken": "<uuid>",
  "expiresIn": 300,
  "scope": "admin"
}

Step 2 — Mount the embed

React

import { VectrifyEmbed } from '@vectrify-ai/ui';

function ConnectorsPage({ tokenData, tenantId }) {
  return (
    <VectrifyEmbed
      accessToken={tokenData.accessToken}
      refreshToken={tokenData.refreshToken}
      view="connectors"
      scope="admin"
      height="100vh"
      width="100%"
      onSessionExpired={(refresh) => {
        // Fetch fresh tokens from your backend
        myApi.getEphemeralToken(tenantId).then(data =>
          refresh(data.accessToken, data.refreshToken)
        );
      }}
    />
  );
}

Vanilla JavaScript

import VectrifyUI from '@vectrify-ai/ui';
// or: const { VectrifyUI } = window.VectrifyUI; // UMD

const handle = VectrifyUI.mount('#my-container', {
  accessToken: tokenData.accessToken,
  refreshToken: tokenData.refreshToken,
  view: 'connectors',
  scope: 'admin',
  height: '600px',
  onSessionExpired: (refresh) => {
    myApi.getEphemeralToken(tenantId).then(data =>
      refresh(data.accessToken, data.refreshToken)
    );
  }
});

// Later: programmatic navigation
handle.navigate('documents');

// Later: clean up
handle.unmount();

CDN / Script Tag

<!-- Include React (peer dependency) if you need the React component -->
<script src="https://unpkg.com/react@19/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@19/umd/react-dom.production.min.js"></script>

<!-- Load the library -->
<script src="https://cdn.vectrify.ai/ui/latest/vectrify-ui.umd.js"></script>

<div id="vectrify-container" style="height: 600px;"></div>

<script>
  // The UMD bundle exposes window.VectrifyUI
  VectrifyUI.mount('#vectrify-container', {
    accessToken: '...',
    refreshToken: '...',
    view: 'connectors',
    scope: 'admin',
    onSessionExpired: (refresh) => {
      // Re-fetch tokens from your backend
    }
  });
</script>

Token Scope

| Scope | Permissions | |---|---| | "read" | View connectors and documents. No mutations. | | "write" | Read + upload documents + add URLs + sync. Cannot delete connectors or create new ones. | | "admin" | Full CRUD — create/edit/delete connectors, delete documents, all write operations. |

Always request the minimum scope needed.

Session Expiry

The ephemeral access token expires in 5 minutes. The library automatically refreshes it silently using the refresh token (valid for 1 hour). When the refresh token itself expires, onSessionExpired is called.

Your callback receives a refresh function. Call it with new tokens from your backend to seamlessly continue the session without unmounting:

onSessionExpired: async (refresh) => {
  const newTokens = await myBackend.getEphemeralToken(tenantId, 'admin');
  refresh(newTokens.accessToken, newTokens.refreshToken);
}

If you do not provide onSessionExpired, the session simply expires and the user sees a "session expired" state within the embed.

Theme Customization

Saved theme (API)

Use PUT /api/v1/tenant-themes with an ephemeral admin token to save CSS variable overrides to the tenant's profile. The app loads these automatically on init.

Runtime override (via library)

Pass a theme object at mount time or update it later:

// At mount time:
VectrifyUI.mount('#container', {
  accessToken,
  refreshToken,
  theme: {
    cssVarsLight: { '--primary': '220 90% 56%' },
    cssVarsDark:  { '--primary': '217 91% 60%' },
  }
});

// After mount:
handle.updateTheme({
  cssVarsLight: { '--primary': '350 80% 50%' },
});

CSS variables use Tailwind HSL format (no hsl() wrapper): "hue saturation% lightness%".

Colour Scheme / Dark Mode

Use themeMode to control whether the embed renders in light, dark, or system (OS) mode. The default is 'system', which follows the OS preference and updates reactively if the OS setting changes at runtime (e.g. scheduled dark mode).

React — mirror your app's own theme toggle

const { isDark } = useMyTheme();

<VectrifyEmbed
  themeMode={isDark ? 'dark' : 'light'}
  accessToken={...}
  refreshToken={...}
/>

Vanilla JS — set at mount time

const handle = VectrifyUI.mount('#container', {
  accessToken,
  refreshToken,
  themeMode: 'dark',   // 'light' | 'dark' | 'system'
});

Vanilla JS — update at runtime

handle.setThemeMode('light');

themeMode overrides the "Default Mode" saved in the account theme (set via the Theme editor). If you omit themeMode, the account theme's saved mode is used; if that is also unset, 'system' applies.

Local Development

By default, the library points to https://ui.vectrify.ai. Override this for local testing:

import { configure } from '@vectrify-ai/ui';

// Call once before any mount() calls
configure({ appUrl: 'http://localhost:11084' });

Or in a React app, add to your .env:

VITE_TENANT_UI_URL=http://localhost:11084

And configure early in your app entry point:

import { configure } from '@vectrify-ai/ui';
if (import.meta.env.VITE_TENANT_UI_URL) {
  configure({ appUrl: import.meta.env.VITE_TENANT_UI_URL });
}

API Reference

VectrifyUI.mount(target, options) → VectrifyUIHandle

| Option | Type | Default | Description | |---|---|---|---| | accessToken | string | required | Ephemeral access JWT | | refreshToken | string | required | Ephemeral refresh UUID | | view | 'connectors' \| 'documents' | 'connectors' | Initial view | | scope | 'admin' \| 'write' \| 'read' | 'read' | Token scope | | theme | { cssVarsLight?, cssVarsDark? } | {} | CSS variable overrides | | themeMode | 'light' \| 'dark' \| 'system' | — | Colour scheme override. Omit to use account theme mode (defaults to 'system'). | | onSessionExpired | (refresh) => void | — | Refresh token expiry callback | | height | string | '100%' | CSS height of the container | | width | string | '100%' | CSS width of the container | | className | string | — | CSS class on the wrapper div | | readyTimeout | number | 10000 | ms to wait for app ready signal |

VectrifyUIHandle

| Method | Description | |---|---| | unmount() | Remove iframe, clean up listeners | | navigate(view) | Switch view without remounting | | updateToken(access, refresh) | Push new tokens to the app | | updateTheme(theme) | Push CSS variable overrides at runtime | | setThemeMode(mode) | Force the embed into 'light', 'dark', or 'system' mode at runtime |

configure(options)

| Option | Type | Description | |---|---|---| | appUrl | string | Override the default app URL |

TypeScript

The package ships with TypeScript definitions — no @types/ package needed.

import VectrifyUI, { VectrifyUIHandle, VectrifyUIOptions } from '@vectrify-ai/ui';
import { VectrifyEmbed, VectrifyEmbedProps } from '@vectrify-ai/ui';

Security Notes

• Never pass tokens in URL parameters. The library delivers tokens exclusively via postMessage.
• HTTPS is required in production. The postMessage protocol and token security depend on it.
• No cookies are used. Refresh tokens travel via Authorization header only — this avoids third-party cookie blocking in iframes.
• The embed iframe does not use the sandbox attribute, which would break OAuth popups required by Confluence and SharePoint connectors.

Working Locally with Consumer Apps

When iterating on this library alongside vectrify-webapp or vectrify-demo-ui, use npm link to point those apps at your local build instead of the npm registry — without touching their package.json.

Setup (one-time)

# 1. Register this package globally
cd vectrify-ui/lib
npm link

# 2. Symlink into a consumer app
cd ../vectrify-webapp       # or vectrify-demo-ui
npm link @vectrify-ai/ui

Tip: Run npm run dev (watch mode) in vectrify-ui/lib to get live rebuilds as you edit the library.

Flip back to npm registry (in the consumer app)

npm unlink @vectrify-ai/ui --no-save
npm install

--no-save is important — it prevents npm from modifying package.json.

Summary

| State | Command | package.json changed? | |---|---|---| | Use local lib | npm link @vectrify-ai/ui | No | | Use npm registry | npm unlink @vectrify-ai/ui --no-save && npm install | No |

Publishing (maintainers)

Bump the version in package.json, then:

# Log in if needed (one-time)
npm login

# Publish — the prepublishOnly hook runs the build automatically
npm publish --otp=<your-authenticator-code>

To do a dry run first (builds and lists bundle contents, no publish):

npm publish --dry-run

To publish a pre-release under a dist-tag:

npm publish --tag beta --otp=<code>