npm package: @spring-money/bse-onboarding-sdk
Description: BSE Onboarding SDK with enforced flow and client-specific theming
Author: Spring Money
Latest version: 0.1.0

# @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

```bash
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

```tsx
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

```typescript
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:

```tsx
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

```tsx
// 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:

```tsx
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:

```tsx
<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:

```tsx
<BSEOnboardingProvider
  config={{
    ...config,
    initialData: {
      clientType: {
        clientType: 'individual',
        pan: 'ABCDE1234F',
        taxStatus: '01',
      },
      personalInfo: {
        firstName: 'John',
        lastName: 'Doe',
        email: 'john@example.com',
        mobile: '9876543210',
        gender: 'male',
        dateOfBirth: '1990-01-01',
      },
    },
  }}
>
  <BSEOnboardingFlow />
</BSEOnboardingProvider>
```

## TypeScript

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

```typescript
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