@spring-money/bse-onboarding-sdk

An enforced 8-step BSE (Bombay Stock Exchange) account opening flow SDK with client-specific theming support for React applications.

Features

• Enforced Flow: 8-step onboarding process that cannot be skipped or reordered
• Theme Customization: CSS variables-based theming for client-specific branding
• Progress Persistence: Optional localStorage support for saving progress
• Form Validation: Built-in validation for all form fields
• TypeScript: Full TypeScript support with type definitions
• Responsive: Mobile-friendly design out of the box

Installation

npm install @spring-money/bse-onboarding-sdk
# or
yarn add @spring-money/bse-onboarding-sdk
# or
pnpm add @spring-money/bse-onboarding-sdk

Quick Start

import { 
  BSEOnboardingProvider, 
  BSEOnboardingFlow,
  DEFAULT_THEME 
} from '@spring-money/bse-onboarding-sdk';
import '@spring-money/bse-onboarding-sdk/styles';

function BSEOnboardingPage() {
  return (
    <BSEOnboardingProvider
      config={{
        apiBaseUrl: process.env.NEXT_PUBLIC_API_BASE_URL!,
        clientId: 'your-client-id',
        onFlowComplete: async (data) => {
          console.log('BSE account created:', data);
          // Navigate to success page
        },
        onError: (error, step) => {
          console.error(`Error in step ${step}:`, error);
        },
      }}
    >
      <BSEOnboardingFlow />
    </BSEOnboardingProvider>
  );
}

8-Step Flow

The SDK implements a mandatory 8-step BSE onboarding flow:

1. Client Type Selection - Individual/Non-Individual, PAN, Tax Status
2. Personal Information - Name, DOB, Gender, Contact details
3. Investor Registration - Holding Nature, Occupation, Address
4. Nominee Addition - Nominee details (configurable)
5. Bank Details - Bank account information, IFSC, Account type
6. FATCA Details - Tax residency, Place of birth, Country
7. Mandate Setup - Payment mandate configuration (configurable)
8. Final Review - Review all details and submit

Configuration

BSEOnboardingConfig

interface BSEOnboardingConfig {
  // Required: API configuration
  apiBaseUrl: string;
  apiKey?: string;
  
  // Required: Client/Account identification
  clientId: string;
  accountId?: string;
  
  // Optional: Theme customization
  theme?: Partial<BSEOnboardingTheme>;
  
  // Optional: Callbacks
  onStepComplete?: (step: number, data: StepData) => void;
  onFlowComplete?: (accountData: BSEAccountData) => Promise<void>;
  onError?: (error: Error, step: number) => void;
  onCancel?: () => void;
  
  // Optional: Feature toggles
  features?: {
    enableNominee?: boolean;        // Default: true
    enableMandate?: boolean;        // Default: true
    requireFATCA?: boolean;         // Default: true
    enableLocalStorage?: boolean;   // Default: true
  };
  
  // Optional: Pre-filled data
  initialData?: Partial<BSEFormData>;
}

Theming

The SDK uses CSS custom properties for theming. You can customize the appearance by providing a theme object:

const customTheme = {
  // Primary Colors
  '--sdk-primary': '#6366f1',
  '--sdk-primary-dark': '#4f46e5',
  '--sdk-primary-light': '#818cf8',
  
  // Text Colors
  '--sdk-text-primary': '#1f2937',
  '--sdk-text-secondary': '#6b7280',
  '--sdk-text-inverse': '#ffffff',
  '--sdk-text-disabled': '#9ca3af',
  
  // Background Colors
  '--sdk-bg-primary': '#ffffff',
  '--sdk-bg-secondary': '#f9fafb',
  '--sdk-bg-input': '#ffffff',
  '--sdk-bg-disabled': '#f3f4f6',
  
  // Border Colors
  '--sdk-border-primary': '#d1d5db',
  '--sdk-border-error': '#ef4444',
  '--sdk-border-disabled': '#e5e7eb',
  
  // Status Colors
  '--sdk-success': '#10b981',
  '--sdk-error': '#ef4444',
  '--sdk-success-light': '#d1fae5',
  
  // Typography (optional)
  '--sdk-font-family': 'Inter, system-ui, sans-serif',
  '--sdk-border-radius': '12px',
};

<BSEOnboardingProvider config={{ ...config, theme: customTheme }}>
  <BSEOnboardingFlow />
</BSEOnboardingProvider>

Theme Variables

| Variable | Description | Default | |----------|-------------|---------| | --sdk-primary | Primary brand color | #2563eb | | --sdk-primary-dark | Darker shade of primary | #1d4ed8 | | --sdk-primary-light | Lighter shade of primary | #3b82f6 | | --sdk-text-primary | Main text color | #1f2937 | | --sdk-text-secondary | Secondary text color | #6b7280 | | --sdk-text-inverse | Text on dark backgrounds | #ffffff | | --sdk-text-disabled | Disabled text color | #9ca3af | | --sdk-bg-primary | Main background | #ffffff | | --sdk-bg-secondary | Secondary background | #f9fafb | | --sdk-bg-input | Input field background | #ffffff | | --sdk-bg-disabled | Disabled element background | #f3f4f6 | | --sdk-border-primary | Default border color | #d1d5db | | --sdk-border-error | Error state border | #ef4444 | | --sdk-border-disabled | Disabled border color | #e5e7eb | | --sdk-success | Success color | #10b981 | | --sdk-error | Error color | #ef4444 | | --sdk-success-light | Light success background | #d1fae5 | | --sdk-font-family | Font family | System fonts | | --sdk-border-radius | Border radius | 8px |

Integration with manthan-ria-planner-portal

// app/bse-onboarding/page.tsx
import { 
  BSEOnboardingProvider, 
  BSEOnboardingFlow,
  DEFAULT_THEME 
} from '@spring-money/bse-onboarding-sdk';
import '@spring-money/bse-onboarding-sdk/styles';

// Map existing CSS variables to SDK variables
const manthanTheme = {
  '--sdk-primary': 'rgb(var(--primary))',
  '--sdk-primary-dark': 'rgb(var(--primary-dark))',
  '--sdk-text-primary': 'rgb(var(--text-primary))',
  '--sdk-text-secondary': 'rgb(var(--text-secondary))',
  // ... other mappings
};

export default function BSEOnboardingPage() {
  const router = useRouter();
  const { clientId, accountId } = useParams();

  return (
    <BSEOnboardingProvider
      config={{
        apiBaseUrl: process.env.NEXT_PUBLIC_API_BASE_URL!,
        clientId: clientId as string,
        accountId: accountId as string,
        theme: manthanTheme,
        onFlowComplete: async (data) => {
          router.push(`/accounts/${accountId}/bse-account/success`);
        },
        onError: (error, step) => {
          toast.error(`Error in step ${step}: ${error.message}`);
        },
        onCancel: () => {
          router.back();
        },
      }}
    >
      <BSEOnboardingFlow />
    </BSEOnboardingProvider>
  );
}

Using the Status Hook

You can access the current flow status using the useBSEOnboardingStatus hook:

import { useBSEOnboardingStatus } from '@spring-money/bse-onboarding-sdk';

function StatusIndicator() {
  const { 
    currentStep, 
    totalSteps, 
    completedSteps,
    isLoading,
    isSubmitting,
    error 
  } = useBSEOnboardingStatus();

  return (
    <div>
      Step {currentStep} of {totalSteps}
      {isLoading && <span>Loading...</span>}
      {error && <span>Error: {error.message}</span>}
    </div>
  );
}

Feature Toggles

You can customize which steps are enabled:

<BSEOnboardingProvider
  config={{
    ...config,
    features: {
      enableNominee: false,      // Skip nominee step
      enableMandate: false,      // Skip mandate step
      requireFATCA: true,        // Require FATCA details
      enableLocalStorage: true,  // Save progress to localStorage
    },
  }}
>
  <BSEOnboardingFlow />
</BSEOnboardingProvider>

Pre-filling Data

You can pre-fill form data using the initialData prop:

<BSEOnboardingProvider
  config={{
    ...config,
    initialData: {
      clientType: {
        clientType: 'individual',
        pan: 'ABCDE1234F',
        taxStatus: '01',
      },
      personalInfo: {
        firstName: 'John',
        lastName: 'Doe',
        email: '[email protected]',
        mobile: '9876543210',
        gender: 'male',
        dateOfBirth: '1990-01-01',
      },
    },
  }}
>
  <BSEOnboardingFlow />
</BSEOnboardingProvider>

TypeScript

The SDK is written in TypeScript and provides full type definitions:

import type {
  BSEOnboardingConfig,
  BSEOnboardingTheme,
  BSEFormData,
  BSEAccountData,
  StepData,
} from '@spring-money/bse-onboarding-sdk';

API Reference

Components

• BSEOnboardingProvider - Context provider with theme injection
• BSEOnboardingFlow - Main flow orchestrator component

Hooks

• useBSEOnboardingStatus - Access read-only flow status

Types

• BSEOnboardingConfig - SDK configuration interface
• BSEOnboardingTheme - Theme contract interface
• BSEFormData - Combined form data for all steps
• BSEAccountData - Data returned after successful registration

Utilities

• DEFAULT_THEME - Default theme values
• createTheme - Helper to create a theme by merging with defaults

License

MIT © Spring Money