@nexora/support-widget

Reusable React support chat for any host integrated with the AI Support Service. The package has no merchant auth, router, store, commerce route, tenant credential, or API-key dependency.

Open the complete developer and API documentation.

Quick start

import { AISupportProvider, useAISupport } from '@nexora/support-widget'
import '@nexora/support-widget/styles.css'

// 1 — Implement getSessionToken in your application. Your host decides how to
//     obtain the token. The widget never receives an app token or tenant API key.
async function getSessionToken({ orderId, orderItemId }) {
  return myHostIntegration.createSupportSession({ orderId, orderItemId })
}

// 2 — Wrap your app once near the root.
function Root() {
  return (
    <AISupportProvider
      apiBaseUrl="https://ai-support.example.com"
      getSessionToken={getSessionToken}
      onChooseAnotherOrder={() => navigate('/orders')}
    >
      <App />
    </AISupportProvider>
  )
}

// 3 — Open general or order support from any descendant component.
function GeneralHelpButton() {
  const { openSupport } = useAISupport()
  return <button onClick={() => openSupport()}>Need help?</button>
}

function OrderHelpButton({ orderId, orderItemId }) {
  const { openSupport } = useAISupport()
  return (
    <button onClick={() => openSupport({ orderId, orderItemId })}>
      Get help with this order
    </button>
  )
}

Authentication lifecycle

openSupport({ orderId, orderItemId })
  │
  ▼
getSessionToken({ orderId, orderItemId })     ← host-defined integration
  │  merchant authentication stays outside the package
  │  ← { sessionToken, expiresIn }
  │
  ▼
Widget stores sessionToken in memory only     ← never localStorage / sessionStorage
  │
  ▼
All chat API calls: Authorization: Bearer <sessionToken>
  │
  ├── 401 SUPPORT_SESSION_EXPIRED?
  │     │
  │     ▼
  │   getSessionToken() called again (shared lock — one refresh for N concurrent requests)
  │     │  success → update in-memory token, retry original request once
  │     │  failure → show session error, stop retrying
  │     ▼
  └── continue

Provider props

| Prop | Required | Default | Description | |---|---|---|---| | apiBaseUrl | Yes | — | AI Support Service REST and Socket.IO base URL | | getSessionToken | Yes | — | async ({ orderId, orderItemId }) => string — acquires a support session JWT | | onChooseAnotherOrder | No | — | Callback when the user picks a different order | | showLauncher | No | true | Show the floating "Need help?" button | | supportMountSelector | No | [data-ai-support-root] | CSS selector for page-mode portal |

useAISupport() return value

| Member | Type | Description | |---|---|---| | openSupport | async (ctx?) => void | Acquires session token and opens the widget | | closeSupport | () => void | Hides the widget UI (does not end the backend conversation) | | sessionAcquireError | string \| null | Set when token acquisition or refresh fails |

What is NOT in scope

• No merchant API key or tenant ID is accepted by the widget
• No plain HTML / CDN bundle
• No host access token transmitted to chat APIs
• No customerId prop (server derives identity from the session token)