@lumerahq/ui

React component library and utilities for building Lumera custom applications.

Installation

npm install @lumerahq/ui

Features

• Application Components - Assistant chat surfaces, data tables, record sheets, and automation runner
• Data Table - Full-featured table with filtering, sorting, and pagination
• Bridge Module - Parent-iframe communication for embedded apps
• API Utilities - Lumera client with SQL, CRUD, file, and email operations
• Automation Runner - Start and monitor automation runs
• React Query Integration - Data fetching hooks

Usage

Styles

Import the package stylesheet once in the app entrypoint before rendering any @lumerahq/ui component:

import '@lumerahq/ui/styles.css';

This stylesheet is required for the shared Tailwind/shadcn theme variables, Inter font, assistant markdown styles, and assistant animations. It is not included automatically when importing from @lumerahq/ui/components, @lumerahq/ui/hooks, or @lumerahq/ui/lib.

The stylesheet defines theme tokens as CSS custom properties. Override them on :root, .dark, or a wrapper class to retheme the assistant without changing component code:

.my-assistant-theme {
  --brand: #2563eb;
  --primary: var(--brand);
  --ring: var(--brand);
  --primary-foreground: #ffffff;
  --background: #ffffff;
  --foreground: #111827;
  --card: #ffffff;
  --border: #d1d5db;
}

Components

import { AutomationRunner, DataTable, RecordSheet } from '@lumerahq/ui';

Record Audit Log

Build an app-native activity view from one globally ordered feed across up to 20 audited collections. Pass the same bare collection names used by record CRUD:

import { useRecordAuditLog, useRecordAuditLogSnapshot } from '@lumerahq/ui/hooks';

const audit = useRecordAuditLog({
  collections: ['invoices', 'payments'],
  event: 'updated',
});

const snapshot = useRecordAuditLogSnapshot({
  id: expandedEntry?.id,
  store: expandedEntry?.store,
  enabled: Boolean(expandedEntry?.has_snapshot),
});

The hook returns entries, current per-collection audit status, loading/error state, refresh, and cursor-based load-more state. Entries include stable collection and record identity fields for links and custom rendering. Public helpers under @lumerahq/ui/lib support direct list/snapshot requests and a capped CSV export. A disabled collection can still have visible history; its status means only that future changes are not being captured.

changed_fields describes update events only. For created and deleted records, show the action itself and use the after or before snapshot for expanded detail. The actor identifies the principal that performed the mutation, so human, agent, and automation actions intentionally remain distinct; display the friendly name/email or typed fallback and retain the full actor id for traceability.

Assistant Chat

Use AssistantPage for a full-page chat, AssistantWidget for a floating widget, or AssistantChat when embedding the chat surface inside custom chrome.

import { useMemo } from 'react';
import {
  AssistantPage,
  createLumeraAgentChatTransport,
  type AgentChatToolRenderer,
} from '@lumerahq/ui';
import '@lumerahq/ui/styles.css';

const toolRenderers: AgentChatToolRenderer[] = [
  {
    match: (tc) => tc.name === 'send_invoice',
    summary: (tc) => {
      const input = tc.input as { invoiceId?: string };
      return `Sent invoice ${input.invoiceId ?? ''}`.trim();
    },
    expandedView: (tc) => <pre>{tc.output ?? ''}</pre>,
  },
];

export function AppAssistant({ agentId }: { agentId: string }) {
  const transport = useMemo(() => createLumeraAgentChatTransport({ agentId }), [agentId]);

  return (
    <div style={{ height: '100vh' }}>
      <AssistantPage
        agentId={agentId}
        transport={transport}
        title="Finance assistant"
        suggestions={['Review open invoices', 'Draft collection notes']}
        toolRenderers={toolRenderers}
        className="h-full"
      />
    </div>
  );
}

Custom tool renderers are checked before the built-in renderer registry, so they can add support for custom tools or override how a built-in tool appears. Pass the same renderer array to AssistantPage, AssistantChat, or AssistantWidget through the toolRenderers prop. For the lower-level AgentChat component, pass it as renderers={{ toolRenderers }}.

API Utilities

import { pbSql, pbList, pbGet, pbCreate } from '@lumerahq/ui/lib';

// SQL queries
const result = await pbSql<{ id: string; name: string }>({
  sql: 'SELECT id, name FROM users WHERE active = true'
});

// CRUD operations
const items = await pbList<User>('users', { filter: JSON.stringify({ status: "active" }) });
const user = await pbGet<User>('users', 'user-id');

Shareable App Links

Always use getShareableAppUrl() for any URL a human will open (copy-link buttons, invite/share flows, email bodies, QR codes). Never use window.location.href — the app runs inside an iframe loaded from the backend's internal /_apps/{company}/{app}/ path, so window.location returns that iframe URL, not the Lumera shell URL in the user's browser tab. Sharing window.location.href produces broken links.

import { buildShareableAppUrl, getShareableAppUrl } from '@lumerahq/ui/lib';

// ✅ Correct
const shareUrl = getShareableAppUrl();
// -> https://your-company.lumerahq.dev/app/my-app/orders/123
// HashRouter apps retain their hash route:
// -> https://your-company.lumerahq.dev/app/my-app#/orders/123

// ✅ Correct for a different in-app route, such as an email/invite link
const invoiceUrl = buildShareableAppUrl('/invoices/123');
// Default template apps use hash routing; pass this when generating target links
// from a page where the current hash route cannot be detected.
const hashInvoiceUrl = buildShareableAppUrl('/invoices/123', {
  router: 'hash',
});

// ❌ WRONG — leaks the internal iframe URL
navigator.clipboard.writeText(window.location.href);
// -> https://your-company.lumerahq.dev/_apps/your-company/my-app/#/orders/123

Returns undefined until the bridge handshake completes; guard accordingly if you call it on first render.

File URLs

import { getDownloadUrl } from '@lumerahq/ui/lib';

const url = await getDownloadUrl(record.attachment.object_key);
// -> fresh presigned S3 URL suitable for links, new tabs, and iframe previews
//    (PDFs / images render inline; Content-Type is inferred when the stored
//    object metadata is missing or wrong).

Automation Runner

import { createRun, pollRun } from '@lumerahq/ui/lib';

const run = await createRun({
  automationId: 'my-automation-id',
  inputs: { param: 'value' },
});

const result = await pollRun(run.id);

Standalone Development

For developing outside of a Lumera iframe, create a .env.local file:

cp .env.example .env.local
# Edit .env.local with your credentials

Get your auth token by running lumera login and copying from .lumera/credentials.json.

License

MIT