npm package: @investipal/portfolio-analytics
Description: Portfolio analytics and visualization SDK for Investipal
Latest version: 0.0.44

# Investipal Portfolio Analytics SDK

A comprehensive React SDK for portfolio analytics and visualization, providing interactive charts, risk metrics, and portfolio analysis tools.

## 🚀 Quick Start

```bash
npm install @investipal/portfolio-analytics
```

**Install specific version:**

```bash
npm install @investipal/portfolio-analytics@1.2.3
```

### Theme Setup (Optional but Recommended)

Wrap your app with the theme provider to enable consistent styling and custom colors:

```jsx
import { SDKThemeProvider } from '@investipal/portfolio-analytics'

function App() {
  return (
    <SDKThemeProvider
      colors={{
        primary: '#007bff',
        secondary: '#6c757d',
        success: '#28a745',
        error: '#dc3545',
        warning: '#ffc107',
        info: '#17a2b8'
      }}
      apiKey="YOUR-API-KEY"
    >
      {/* Your app components */}
    </SDKThemeProvider>
  )
}
```

**Note:** Components now work without the theme provider and will use default colors. For custom styling, wrap your app with `SDKThemeProvider` or `SDKThemeWrapper`.

**Color Structure:** The theme provider uses a simple flat color object structure:

```jsx
const colors = {
  primary: '#754EF5', // Primary brand color
  secondary: '#29C76F', // Secondary brand color
  success: '#29C76F', // Success state color
  error: '#EA5455', // Error state color
  warning: '#FF9F43', // Warning state color
  info: '#00CFE8' // Info state color
}
```

## 🎯 Component Usage Patterns

Each component can be used in **two different ways**:

### 1. **By Portfolio ID** (Fetches data automatically)

```jsx
<ComponentName portfolioId='your-portfolio-id' />
```

### 2. **By Passing Data** (You provide the data)

```jsx
<ComponentName data={yourPortfolioData} />
```

---

## 📊 Available Components

### 1. AnalyzeTabWithApi - Complete Dashboard

**Usage Pattern 1: By Portfolio ID**

```jsx
import { AnalyzeTabWithApi } from '@investipal/portfolio-analytics'
;<AnalyzeTabWithApi portfolioId='your-portfolio-id' />
```

### 2. Stats - Risk Metrics Component

**Usage Pattern 1: By Portfolio ID**

```jsx
import { Stats } from '@investipal/portfolio-analytics'
;<Stats portfolioId='your-portfolio-id' />
```

**Usage Pattern 2: By Passing Data**

```jsx
<Stats
  data={[
    { key: 'risk', value: 7.2 },
    { key: 'div', value: 2.8 },
    { key: 'rtn_inception', value: 18.9, created_on: '2023-01-15T10:30:00Z' },
    { key: 'rtn_1mth', value: 3.45 },
    { key: 'rtn_1yr', value: 12.7 },
    { key: 'stdev', value: 15.3 },
    { key: 'beta', value: 0.95 },
    { key: 'sharpe', value: 1.2 },
    { key: 'fees', value: 0.85 }
  ]}
  title='Portfolio Metrics'
  showTitle={true}
  height='200px'
  width='100%'
/>
```

### 3. HorizontalBarChart - Multi-Purpose Horizontal Bar Chart

**Usage Pattern 1: By Portfolio ID (Auto-fetches data)**

```jsx
import { HorizontalBarChart } from '@investipal/portfolio-analytics'

// Asset allocation chart
<HorizontalBarChart portfolioId='your-portfolio-id' chartType='asset' />

// Sector allocation chart
<HorizontalBarChart portfolioId='your-portfolio-id' chartType='sector' />

// Bond allocation chart
<HorizontalBarChart portfolioId='your-portfolio-id' chartType='bond' />

// Tax allocation chart (requires riskId)
<HorizontalBarChart portfolioId='your-portfolio-id' chartType='tax' riskId='your-risk-id' />
```

**Usage Pattern 2: By Passing Data**

```jsx
<HorizontalBarChart
  data={[
    { label: 'Stocks', value: 45 },
    { label: 'Bonds', value: 25 },
    { label: 'Cash', value: 30 }
  ]}
  height='20rem'
  width='100%'
  title='Portfolio Allocation'
  showTitle={true}
/>
```

### 4. TopHoldingsChart - Top Holdings Visualization

**Usage Pattern 1: By Portfolio ID**

```jsx
import { TopHoldingsChart } from '@investipal/portfolio-analytics'
;<TopHoldingsChart portfolioId='your-portfolio-id' />
```

**Usage Pattern 2: By Passing Data**

```jsx
<TopHoldingsChart
  data={[
    { security: 'AAPL', weight: 15.5 },
    { security: 'MSFT', weight: 12.3 },
    { security: 'GOOGL', weight: 8.7 },
    { security: 'AMZN', weight: 7.2 }
  ]}
  title='Top Holdings'
  showTitle={true}
  height='300px'
  width='100%'
/>
```

### 5. PerformanceChartSDK - Performance Comparison

**Usage Pattern 1: By Portfolio ID**

```jsx
import { PerformanceChartSDK } from '@investipal/portfolio-analytics'
;<PerformanceChartSDK portfolioId='your-portfolio-id' />
```

**Usage Pattern 2: By Passing Data**

```jsx
<PerformanceChartSDK
  data={{
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
    data: [100, 105, 110, 108, 115, 120]
  }}
  benchmarkData={[
    {
      name: 'S&P 500',
      data: [100, 102, 105, 103, 108, 112]
    },
    {
      name: 'NASDAQ',
      data: [100, 104, 108, 106, 112, 118]
    }
  ]}
  height='400px'
  width='600px'
/>
```

### 6. IndividualMapChart - Geographic Distribution

**Usage Pattern 1: By Portfolio ID**

```jsx
import { IndividualMapChart } from '@investipal/portfolio-analytics'
;<IndividualMapChart portfolioId='your-portfolio-id' />
```

**Usage Pattern 2: By Passing Data**

```jsx
<IndividualMapChart
  data={{
    label: 'My Portfolio',
    data: [50, 30, 20]
  }}
  labels={['United States', 'Canada', 'United Kingdom']}
  color='primary'
  active={true}
  height='400px'
  width='600px'
/>
```

### 7. StockTableWithApi - Holdings Table

**Usage Pattern 1: By Portfolio ID**

```jsx
import { StockTableWithApi } from '@investipal/portfolio-analytics'
;<StockTableWithApi portfolioId='your-portfolio-id' />
```

## 📊 Data Structure Examples

### Portfolio Data Format (for passing data)

```javascript
{
  id: "portfolio-id",
  name: "My Portfolio",
  value: 100000,
  currency: "USD",
  holdings: [
    {
      symbol: "AAPL",
      name: "Apple Inc.",
      weight: 0.15,
      value: 15000,
      gain: 0.12,
      sector: "Technology"
    }
  ],
  performance: {
    daily: 0.02,
    weekly: 0.05,
    monthly: 0.15,
    yearly: 0.25
  },
  risk: {
    sharpe: 1.2,
    alpha: 0.05,
    beta: 0.95,
    volatility: 0.18
  }
}
```

## 📋 Requirements

- **React**: 17.0.0 or higher
- **Node.js**: 14.0.0 or higher
- **Browsers**: Chrome, Firefox, Safari, Edge (last 2 versions)

## 📄 License

MIT License - see LICENSE file for details.

---

**Need Help?** Check our documentation or open an issue on GitHub.