@factor-y/limitless-voltmx-react

React hooks and providers for the HCL Volt MX Foundry JavaScript SDK.

Turns the callback-based Volt MX SDK into idiomatic React: a provider that initializes the SDK from injected configuration, plus hooks for identity (login/logout/profile), integration service calls, and session handling.

This package ships types and React bindings only — not the Volt MX SDK itself. The SDK runtime (voltmx-sdk.js) is provided by HCL and must be loaded by the host application (see Prerequisite).

Installation

npm install @factor-y/limitless-voltmx-react

Peer dependencies

• react >= 18
• react-dom >= 18

Prerequisite: load the Volt MX SDK first

The SDK defines window.voltmx and must be loaded before your React bundle, via a plain <script> tag in your HTML:

<!-- 1. Volt MX SDK (provided by HCL) -->
<script src="/voltmx/voltmx-sdk.js"></script>
<!-- 2. Your React app -->
<script type="module" src="/src/main.tsx"></script>

If window.voltmx is missing when VoltMXProvider mounts, the provider enters an error state with a descriptive message instead of throwing.

Quick start

Build a VoltMXConfig from whatever configuration source your app uses (env vars, a runtime config.js, etc.) and pass it to VoltMXProvider:

import { createRoot } from 'react-dom/client'
import { VoltMXProvider, AuthProvider, type VoltMXConfig } from '@factor-y/limitless-voltmx-react'
import { App } from './App'

const config: VoltMXConfig = {
  appKey: import.meta.env.VITE_VMX_APP_KEY,
  appSecret: import.meta.env.VITE_VMX_APP_SECRET,
  serviceUrl: import.meta.env.VITE_VMX_SERVICE_URL,
  identityProvider: import.meta.env.VITE_VMX_IDENTITY_PROVIDER,
  integrationService: import.meta.env.VITE_VMX_INTEGRATION_SERVICE,
  appId: import.meta.env.VITE_VMX_APP_ID,
  appName: 'My App',
  appVersion: '1.0',
  debug: import.meta.env.DEV, // optional — enables diagnostic logging
}

createRoot(document.getElementById('root')!).render(
  <VoltMXProvider config={config}>
    <AuthProvider>
      <App />
    </AuthProvider>
  </VoltMXProvider>,
)

API

VoltMXProvider

Props: config: VoltMXConfig, children. Initializes the SDK and provides both the runtime SDK state (useVoltMX) and the configuration (useVoltMXConfig).

useVoltMX(): VoltMXContextValue

Returns { sdk, status, error }, where status is 'loading' | 'ready' | 'error'.

useVoltMXConfig(): VoltMXConfig

Returns the injected configuration. Throws if used outside a VoltMXProvider.

AuthProvider / useAuth<TUserData>()

AuthProvider restores a persisted login on mount. useAuth returns { isAuthenticated, isCheckingSession, profile, userData, sessionExpired, setAuth, setUserData, expireSession }. TUserData lets you type an app-specific user object stored via setUserData.

useIdentity(providerName?): UseIdentityReturn

{ isAuthenticated, profile, isLoading, error, login, logout, getProfile, clearError }. Defaults to config.identityProvider; pass providerName to override.

const { login, isLoading } = useIdentity()
await login()

useIntegration(serviceName): UseIntegrationReturn

{ invoke, isLoading, error, clearError }. invoke(operationName, data?, headers?) calls a Foundry integration operation and auto-detects session expiry (HTTP 401 and known auth mfcodes trigger expireSession).

const { invoke } = useIntegration('MyDataService')
const res = await invoke('getItems', { page: 0 })

useSuppressLogoutPopup()

Call once in a root component. Intercepts the SDK's window.open call to /oauth2/logout (which the SDK always opens on OAuth logout) and suppresses the popup. Restores the original window.open on unmount.

Error helpers

• isVoltMXError(err): err is VoltMXError
• getVoltMXErrorMessage(err): string

Logging

Diagnostic logging is off by default. Enable it either through the config (debug: true) or imperatively:

import { setVoltMXDebug } from '@factor-y/limitless-voltmx-react'
setVoltMXDebug(true)

promisify(fn, thisArg, ...args)

Escape hatch that wraps a callback-style SDK method (method(...args, successCb, failureCb)) into a Promise. Useful for raw SDK calls not covered by the provided hooks.

Contributing & releasing

Development setup, versioning (SemVer) and the release process (CI, just recipes, main/next branch model) are documented in RELEASING.md in the repository.

License

MIT © Factor-y S.r.l. — see LICENSE.