b-end-widget-sdk

b-end-widget-sdk is an embeddable assistant widget for B-end applications. The widget is rendered only after an explicit init(...) call.

Install

npm install b-end-widget-sdk

Public API (frozen)

• init(config: WidgetConfig): void
• setPageContext(context: PageContext): void
• getPageContext(): PageContext | null
• destroy(): void

Exported types:

• WidgetConfig
• PageContext
• WidgetPublicAPI

Integration Contract

1) Initialization behavior

• Importing the package alone does not render any UI.
• You must call init(...) to create container + Shadow DOM and show the floating ball.
• Calling init(...) repeatedly is ignored after first successful initialization.

2) Required and optional config

WidgetConfig:

• required: tenantId
• optional: userId, theme, apiBaseUrl, authToken, defaultPageContext

Default backend URL is http://localhost:8000. Always pass apiBaseUrl in production.

3) Route/page updates

• On route change, call setPageContext(...).
• Prefer sending stable pageId and routePath; attach title when available.
• Use systemPromptExtension and features when you want assistant behavior to adapt per page.

4) Lifecycle and teardown

• On app unmount, tenant switch, or logout, call destroy() to unmount React and clean DOM.
• Re-initialize with init(...) after destroy if needed.

Usage Examples

ESM (recommended)

import {
  init,
  setPageContext,
  getPageContext,
  destroy,
  type WidgetConfig,
} from 'b-end-widget-sdk';

const config: WidgetConfig = {
  tenantId: 'tenant-001',
  userId: 'user-1008',
  apiBaseUrl: 'https://api.example.com',
  authToken: 'your-jwt-token',
  defaultPageContext: {
    pageId: 'dashboard',
    routePath: '/dashboard',
    title: 'Dashboard',
  },
};

init(config);

setPageContext({
  pageId: 'orders',
  routePath: '/orders',
  title: 'Order List',
});

console.log(getPageContext());

// Later when app is torn down:
destroy();

UMD script (global window.MyWidget)

<script src="https://unpkg.com/b-end-widget-sdk/dist/widget-sdk.umd.js"></script>
<script>
  window.MyWidget.init({
    tenantId: 'tenant-001',
    userId: 'user-1008',
    apiBaseUrl: 'https://api.example.com',
  });

  // Route change example
  window.MyWidget.setPageContext({
    pageId: 'reports',
    routePath: '/reports',
    title: 'Reports',
  });
</script>

Framework integration (React)

import { useEffect } from 'react';
import { init, setPageContext, destroy } from 'b-end-widget-sdk';
import { useLocation } from 'react-router-dom';

export function WidgetBridge() {
  const location = useLocation();

  useEffect(() => {
    init({
      tenantId: 'tenant-001',
      userId: 'user-1008',
      apiBaseUrl: 'https://api.example.com',
    });

    return () => destroy();
  }, []);

  useEffect(() => {
    setPageContext({
      pageId: location.pathname || 'unknown',
      routePath: location.pathname,
      title: document.title,
    });
  }, [location.pathname]);

  return null;
}

FAQ

I called init twice and nothing changed

init is idempotent by design; call destroy() first if you need to re-create the widget.

Why does it still call localhost in production?

Because apiBaseUrl is optional and defaults to http://localhost:8000. Pass a production URL explicitly.

Chat stream issues (SSE/CORS/401/403)

• Ensure backend supports text/event-stream.
• Ensure CORS allows your origin and auth headers.
• Ensure authToken is valid for protected endpoints.

Release Checklist

Before publish

1. Clean and build:
   • npm run build
2. Inspect packed files:
   • npm pack --dry-run
   • Verify package includes expected dist artifacts and declarations

Publish

1. Login:
   • npm login
2. Publish:
   • npm publish --access public

Post-publish verification (external demo project)

1. npm install b-end-widget-sdk
2. Call init(...) and confirm floating ball appears
3. Open chat and feedback tabs
4. Trigger route changes and verify setPageContext(...) effects
5. Call destroy() and verify DOM cleanup