Ai Lead Scoring

A lightweight React component library to display AI-based Lead Scores and their details in a flexible and customizable way.

This package helps you easily show lead scores, lead score facts, visualize score history, and even inject lead scores into existing HTML tables without rewriting your UI.

📦 Package Overview

@shiftboolean/ai-lead-scoring is a React-based npm package designed to show lead score data and details insights for leads.

It works out-of-the-box with minimal setup and also gives you full freedom to customize UI components according to your design system (MUI, custom CSS, etc.).

🚀 What Can This Package Do?

• Show single lead score
• Inject lead score column into any existing table
• Display lead score details insights in dialog/sidebar
• Support fully custom UI components/styles

📥 Installation

npm install @shiftboolean/ai-lead-scoring

yarn add @shiftboolean/ai-lead-scoring

pnpm add @shiftboolean/ai-lead-scoring

🧩 Components & Usage Details

Below are all available components with clear explanations and prop details.

AiLeadScoreProvider

AiLeadScoreProvider is a React context provider that handles API key validation, authentication state, and global configuration for the AI Lead Scoring system. It validates the provided API key on mount, manages loading and error states, and exposes authentication status, theme, messages, and configuration values to all child components via context.

Wrap your application (or required part of it) with this provider to securely access AI Lead Score features throughout your app.

Props Reference

| Prop Name | Type | Required | Default | Description | | -------------- | ----------------------------------------- | -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------- | | apiKey | string | ✅ | - | API key used to authenticate and validate access to the AI Lead Score API. | | children | React.ReactNode | ✅ | - | React components that will consume the provider's context. | | theme | "light" \| "dark" | ❌ | "light" | UI theme for the provider. Defaults to "light" if not provided. | | primaryColor | string | ❌ | "#0288d1" | Primary theme color of the theme | | fallback | ComponentType<{ error: Error \| null }> | ❌ | - | Component rendered when a child throws during render. Receives the caught error as a prop for custom error messaging. |

Example

 <StrictMode>
      <AiLeadScoreProvider
        apiKey="123"
        fallback={({ error }) => <div>Something went wrong: {error?.message}</div>}
        >
        <App />
      </AiLeadScoreProvider>
    </ThemeProvider>
  </StrictMode>

ShowSingleLeadScore

Displays the lead score for a single student.

Props Reference

| Prop Name | Type | Required | Default | Description | | ----------------- | ---------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------- | | studentId | string | ✅ | - | Unique student ID | | CustomComponent | ComponentType<{ isLoading: boolean; score: {lead_score: number, success: boolean} } }> | ❌ | - | Custom UI for rendering score | | width | string \| number | ❌ | 40 | Width of the component | | height | string \| number | ❌ | 20 | Height of the component | | styles | CSSProperties | ❌ | - | Custom inline styles for the component |

Example

import { ShowSingleLeadScore } from "@shiftboolean/ai-lead-scoring";

export default function SingleScoreExample() {
  return <ShowSingleLeadScore studentId="STUDENT_123" />;
}

InjectLeadScoreTableColumn

Injects a Lead Score column into any existing HTML table using its ID.

Props Reference

| Prop Name | Type | Required | Default | Description | | ---------------------- | ---------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------- | | tableId | string | ✅ | - | Target table ID | | studentIds | string[] | ✅ | - | Student IDs (row-wise) | | headerName | string | ✅ | - | Column header text | | columnInjectionIndex | number | ❌ | - | Injection Column position (>0) | | CustomComponent | ComponentType<{ isLoading: boolean; score: {lead_score: number, success: boolean} } }> | ❌ | - | Custom cell UI | | width | string \| number | ❌ | 40 | Width of the component | | height | string \| number | ❌ | 20 | Height of the component | | styles | CSSProperties | ❌ | - | Custom inline styles for the component |

Example

import { InjectLeadScoreTableColumn } from "@shiftboolean/ai-lead-scoring";

export default function InjectColumnExample() {
  return (
    <table id="student-table">
      <thead>
        <tr>
          <th>Name</th>
          <th>Email</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>John</td>
          <td>[email protected]</td>
        </tr>
        <tr>
          <td>Jane</td>
          <td>[email protected]</td>
        </tr>
      </tbody>

      <InjectLeadScoreTableColumn
        tableId="student-table"
        headerName="Lead Score"
        studentIds={["STUDENT_1", "STUDENT_2"]}
      />
    </table>
  );
}

LeadScoreDetailsDialog

Shows the lead score insights with history, recommendation, factors, risks, and overview in a dialog

Props Reference

| Prop Name | Type | Required | Default | Description | | ----------------- | ---------------------------------------- | -------- | ----------------- | ----------------------------------------------------- | | DialogInitiator | ComponentType<{ onClick: () => void }> | ✅ | - | Component that triggers opening the dialog. | | studentId | string | ✅ | - | Unique student/lead ID. | | open | boolean | ✅ | - | Dialog opening state | | onClose | ()=> void | ✅ | - | Dialog closing function | | dialogTitle | string | ❌ | "AI Lead Score" | Optional title displayed on the dialog. | | leadStage | string | ❌ | - | Lead stage of the student | | studentName | string | ❌ | - | Name of the student | | dialogWidth | 'sm' \| 'md' \| 'lg' \| 'full' | ❌ | "md" | Width of the dialog. | | styles | React.CSSProperties | ❌ | - | Custom inline styles applied to the dialog container. |

Example

<LeadScoreDetailsDialog
  DialogInitiator={({ onClick }) => (
    <Button onClick={onClick}>Score Details</Button>
  )}
  studentId="2333443"
/>

LeadScoreDetailsSidebar

Shows the lead score insights with history, recommendation, factors, risks, and overview in a sidebar

Props

| Prop Name | Type | Required | Default | Description | | ----------------- | ---------------------------------------- | -------- | ----------------- | ------------------------------------------------------ | | DialogInitiator | ComponentType<{ onClick: () => void }> | ✅ | - | Component that triggers opening the sidebar. | | studentId | string | ✅ | - | Unique student/lead ID. | | open | boolean | ✅ | - | Sidebar opening state | | onClose | ()=> void | ✅ | - | Sidebar closing function | | sidebarTitle | string | ❌ | "AI Lead Score" | Optional title displayed on the sidebar. | | sidebarWidth | 'sm' \| 'md' \| 'lg' \| 'full' | ❌ | "md" | Width of the sidebar. | | sidebarPosition | 'left' \| 'right' | ❌ | "right" | Position of the sidebar on the screen. | | styles | React.CSSProperties | ❌ | - | Custom inline styles applied to the sidebar container. | | leadStage | string | ❌ | - | Lead stage of the student | | studentName | string | ❌ | - | Name of the student |

Example

<LeadScoreDetailsSidebar
  DialogInitiator={({ onClick }) => (
    <Button onClick={onClick}>Score Details</Button>
  )}
  studentId="2333443"
/>

🧠 Summary

• @shiftboolean/ai-lead-scoring helps you display lead scores and insights quickly
• Works well with existing UI and tables
• Fully customizable components and UI
• Easy to integrate into any React app
• Currently uses a static API key, which will be improved later

🔒 Content Security Policy (CSP)

When deploying an application that uses this library, add the following directives to your Content Security Policy header to ensure it functions correctly while maintaining a secure posture:

Content-Security-Policy:
  default-src 'self';
  connect-src 'self' https://<your-api-domain>;
  style-src   'self' 'unsafe-inline';
  script-src  'self';

Directive notes

| Directive | Reason | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | connect-src 'self' https://<your-api-domain> | The library makes fetch requests to your configured ECHO_AI_API_BASE_URL. Replace <your-api-domain> with that origin (e.g. https://api.example.com). | | style-src 'self' 'unsafe-inline' | CSS custom properties (--echo-als-brand-primary) are applied via inline styles. If your CSP supports 'nonce-...' or 'strict-dynamic', prefer those over 'unsafe-inline'. |

Tip: Always scope connect-src to the exact API origin rather than using a wildcard (*) to limit the blast radius of a compromised dependency.