@cas-parser/connect 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CASParser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,263 @@
+# Portfolio Connect SDK
+
+> Drop-in widget for importing Indian investment statements (Mutual Funds, CDSL, NSDL).
+
+[![npm version](https://img.shields.io/npm/v/@cas-parser/connect.svg)](https://www.npmjs.com/package/@cas-parser/connect)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Quick Start
+
+Get your access token from [docs.casparser.in](https://docs.casparser.in)
+
+## Installation
+
+### npm / yarn
+
+```bash
+npm install @cas-parser/connect
+# or
+yarn add @cas-parser/connect
+```
+
+### CDN (Vanilla JS / Angular / Vue)
+
+**Option 1: Standalone Bundle (Recommended)** - Includes React, no extra dependencies:
+
+```html
+<script src="https://unpkg.com/@cas-parser/connect/dist/portfolio-connect.standalone.min.js"></script>
+
+<script>
+  // Simple imperative API - no React knowledge needed!
+  document.getElementById('import-btn').onclick = async () => {
+    try {
+      const { data, metadata } = await PortfolioConnect.open({
+        accessToken: 'your_access_token',
+        config: { enableCdslFetch: true }
+      });
+      console.log('Portfolio:', data);
+    } catch (error) {
+      if (error.message === 'Widget closed by user') {
+        console.log('User cancelled');
+      } else {
+        console.error('Error:', error);
+      }
+    }
+  };
+</script>
+```
+
+**Option 2: Lightweight Bundle** - If you already have React on your page:
+
+```html
+<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
+<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+<script src="https://unpkg.com/@cas-parser/connect/dist/portfolio-connect.umd.min.js"></script>
+
+<script>
+  // Same imperative API works here too
+  document.getElementById('import-btn').onclick = () => {
+    PortfolioConnect.open({
+      accessToken: 'your_access_token',
+    }).then(({ data }) => console.log(data));
+  };
+</script>
+```
+
+**Bundle Sizes:**
+- Standalone: ~54KB gzipped (includes React - no dependencies!)
+- UMD: ~9KB gzipped (requires React 17+ on page)
+
+## Quick Start
+
+### React
+
+```tsx
+import { PortfolioConnect } from '@cas-parser/connect';
+
+function App() {
+  return (
+    <PortfolioConnect
+      accessToken="your_access_token"
+      onSuccess={(data) => console.log('Portfolio:', data)}
+    >
+      {({ open }) => (
+        <button onClick={open}>Import Portfolio</button>
+      )}
+    </PortfolioConnect>
+  );
+}
+```
+
+### Vanilla JS / Angular / Vue (Imperative API)
+
+Use the simple `open()` function - returns a Promise:
+
+```html
+<!-- Standalone build - no React needed! -->
+<script src="https://unpkg.com/@cas-parser/connect/dist/portfolio-connect.standalone.min.js"></script>
+
+<button id="import-btn">Import Portfolio</button>
+
+<script>
+  document.getElementById('import-btn').onclick = async () => {
+    try {
+      const { data, metadata } = await PortfolioConnect.open({
+        accessToken: 'your_access_token',
+        config: {
+          title: 'Import Your Portfolio',
+          enableCdslFetch: true,
+        },
+      });
+      
+      console.log('Portfolio data:', data);
+      console.log('Metadata:', metadata);
+      
+    } catch (error) {
+      if (error.message === 'Widget closed by user') {
+        console.log('User cancelled');
+      } else {
+        console.error('Error:', error);
+      }
+    }
+  };
+</script>
+```
+
+## Configuration
+
+```tsx
+<PortfolioConnect
+  accessToken="your_access_token"
+  config={{
+    // Branding
+    logoUrl: 'https://yourapp.com/logo.png',
+    title: 'Import Your Investments',
+    subtitle: 'Mutual Funds, Stocks, Bonds — all in one place',
+    
+    // Features
+    enableGenerator: true,   // MF statement via email (KFintech)
+    enableCdslFetch: true,   // CDSL statement via OTP
+    
+    // Restrict portfolio types
+    allowedTypes: ['CAMS_KFINTECH', 'CDSL', 'NSDL'],
+    
+    // Pre-fill user details
+    prefill: {
+      pan: 'ABCDE1234F', // Optional, for CAMS_KFINTECH, CDSL
+      email: 'user@example.com', // Optional, for CAMS_KFINTECH, CDSL
+      boId: '1234567890123456',  // Optional, CDSL BO ID
+      dob: '1990-01-15',        // Optional, CDSL DOB
+    },
+    
+    // Generator options
+    generator: {
+      fromDate: '2020-01-01',
+      toDate: '2024-12-31',
+    },
+    
+    // UI options
+    showShortcuts: true,    // Email search shortcuts
+    showPortalLinks: true,  // Links to download portals
+  }}
+  onSuccess={handleSuccess}
+  onError={handleError}
+  onEvent={(event, metadata) => analytics.track(event, metadata)}
+>
+  {({ open, isReady }) => (
+    <button onClick={open} disabled={!isReady}>
+      Import Portfolio
+    </button>
+  )}
+</PortfolioConnect>
+```
+
+## Framework Support
+
+| Framework | Support | Method |
+|-----------|---------|--------|
+| **React** | ✅ Native | npm package |
+| **Next.js** | ✅ Native | npm package |
+| **Angular** | ✅ Via CDN | UMD bundle |
+| **Vue** | ✅ Via CDN | UMD bundle |
+| **Vanilla JS** | ✅ Via CDN | UMD bundle |
+| **React Native** | ✅ WebView | See examples |
+| **Flutter** | ✅ WebView | See examples |
+
+See [EXAMPLES.md](./EXAMPLES.md) for framework-specific integration guides.
+
+## API Reference
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `accessToken` | `string` | Yes | Your access token ([get one](https://docs.casparser.in)) |
+| `onSuccess` | `(data, metadata) => void` | Yes | Success callback with parsed data |
+| `onError` | `(error) => void` | No | Error callback |
+| `onExit` | `() => void` | No | Widget closed callback |
+| `onEvent` | `(event, metadata) => void` | No | Analytics/tracking callback |
+| `config` | `PortfolioConnectConfig` | No | Configuration options |
+
+### Config Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `logoUrl` | `string` | CASParser logo | Your brand logo URL |
+| `title` | `string` | "Import Your Investments" | Widget title |
+| `subtitle` | `string` | "Mutual Funds, Stocks..." | Widget subtitle |
+| `enableGenerator` | `boolean` | `false` | Enable MF fetch via email |
+| `enableCdslFetch` | `boolean` | `false` | Enable CDSL fetch via OTP |
+| `allowedTypes` | `PortfolioType[]` | All | Restrict to specific types |
+| `prefill` | `object` | - | Pre-fill user details |
+
+### Events
+
+| Event | Description |
+|-------|-------------|
+| `WIDGET_OPENED` | Widget opened |
+| `WIDGET_CLOSED` | Widget closed |
+| `FILE_SELECTED` | User selected a file |
+| `PARSE_STARTED` | Parsing started |
+| `PARSE_SUCCESS` | Parsing completed |
+| `PARSE_ERROR` | Parsing failed |
+| `GENERATOR_STARTED` | MF email request started |
+| `GENERATOR_SUCCESS` | MF email request sent |
+| `CDSL_FETCH_STARTED` | CDSL fetch started |
+| `CDSL_OTP_SENT` | CDSL OTP sent |
+| `CDSL_FETCH_SUCCESS` | CDSL files retrieved |
+
+### Response Data
+
+```typescript
+interface ParsedData {
+  cas_type: 'CAMS_KFINTECH' | 'CDSL' | 'NSDL';
+  status: 'success' | 'failed';
+  investor_info?: {
+    name: string;
+    email?: string;
+    pan?: string;
+  };
+  folios?: [...];    // MF folios
+  holdings?: [...];  // Demat holdings
+  summary?: {
+    total_value: number;
+    as_on_date: string;
+  };
+}
+```
+
+## Documentation
+
+For full documentation, API reference, and examples:
+
+📖 **[docs.casparser.in](https://docs.casparser.in)**
+
+## Support
+
+- 📧 sameer@casparser.in
+- 📖 [docs.casparser.in](https://docs.casparser.in)
+- 🐛 [GitHub Issues](https://github.com/CASParser/cas-connect/issues)
+
+## License
+
+MIT © [CASParser](https://casparser.in)

package/dist/PortfolioConnect.d.ts

@@ -0,0 +1,5 @@
+import React from 'react';
+import type { PortfolioConnectProps } from './types';
+export declare const PortfolioConnect: React.FC<PortfolioConnectProps>;
+export declare const CASConnect: React.FC<PortfolioConnectProps>;
+export default PortfolioConnect;

package/dist/components/CDSLFetchMode.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+interface CDSLFetchModeProps {
+    prefill?: {
+        pan?: string;
+        boId?: string;
+        dob?: string;
+    };
+    onRequestOtp: (pan: string, boId: string, dob: string) => Promise<string>;
+    onVerifyOtp: (sessionId: string, otp: string, pan: string) => Promise<void>;
+    onBack: () => void;
+}
+export declare const CDSLFetchMode: React.FC<CDSLFetchModeProps>;
+export {};

package/dist/components/FetchMode.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+interface FetchModeProps {
+    prefill?: {
+        pan?: string;
+        email?: string;
+    };
+    onSubmit: (pan: string, email: string) => Promise<void>;
+    onBack: () => void;
+    isLoading: boolean;
+}
+export declare const FetchMode: React.FC<FetchModeProps>;
+export {};

package/dist/components/Modal.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+interface ModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    onBack?: () => void;
+    showBackButton?: boolean;
+    children: React.ReactNode;
+    width?: number;
+    isSandbox?: boolean;
+}
+export declare const Modal: React.FC<ModalProps>;
+export {};

package/dist/components/PortfolioConnectWidget.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import type { PortfolioConnectConfig, ParsedData, PortfolioConnectEvent, PortfolioConnectError } from '../types';
+interface PortfolioConnectWidgetProps {
+    isOpen: boolean;
+    onClose: () => void;
+    apiKey: string;
+    apiBaseUrl?: string;
+    config?: PortfolioConnectConfig;
+    onSuccess: (data: ParsedData, metadata: any) => void;
+    onError?: (error: PortfolioConnectError) => void;
+    onEvent?: (event: PortfolioConnectEvent, metadata: any) => void;
+}
+export declare const PortfolioConnectWidget: React.FC<PortfolioConnectWidgetProps>;
+export {};

package/dist/components/ShortcutLinks.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { CASType } from '../types';
+interface ShortcutLinksProps {
+    selectedType?: CASType;
+    onSearchClick?: (provider: string) => void;
+}
+export declare const ShortcutLinks: React.FC<ShortcutLinksProps>;
+export {};

package/dist/components/UploadZone.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+interface UploadZoneProps {
+    onFileSelect: (file: File, password: string) => void;
+    isProcessing: boolean;
+    progress: number;
+}
+export declare const UploadZone: React.FC<UploadZoneProps>;
+export {};

package/dist/imperative.d.ts

@@ -0,0 +1,87 @@
+import type { PortfolioConnectConfig, ParsedData, ParseMetadata, PortfolioConnectError } from './types';
+/**
+ * Configuration for the imperative open() API.
+ * Used for non-React environments (Vanilla JS, Angular, Vue, etc.)
+ */
+export interface ImperativeConfig {
+    /** Access token for authentication. Get yours at docs.casparser.in */
+    accessToken?: string;
+    /** @deprecated Use accessToken instead */
+    apiKey?: string;
+    /** Widget configuration options */
+    config?: PortfolioConnectConfig;
+    /** Called when widget is opened */
+    onOpen?: () => void;
+    /** Called for all widget events (useful for analytics) */
+    onEvent?: (event: string, metadata: Record<string, any>) => void;
+}
+/**
+ * Result returned from the open() promise
+ */
+export interface OpenResult {
+    /** Parsed portfolio data */
+    data: ParsedData;
+    /** Parsing metadata (source, duration, etc.) */
+    metadata: ParseMetadata;
+}
+/**
+ * Handle returned from create() for manual control
+ */
+export interface WidgetHandle {
+    /** Open the widget modal */
+    open: () => void;
+    /** Close the widget and cleanup */
+    destroy: () => void;
+}
+/**
+ * Opens the Portfolio Connect widget and returns a promise that resolves with parsed data.
+ *
+ * This is the recommended API for non-React applications (Vanilla JS, Angular, Vue, etc.)
+ *
+ * @example
+ * ```javascript
+ * // Vanilla JS
+ * document.getElementById('btn').onclick = async () => {
+ *   try {
+ *     const { data, metadata } = await PortfolioConnect.open({
+ *       apiKey: 'your_api_key',
+ *       config: { enableCdslFetch: true }
+ *     });
+ *     console.log('Portfolio data:', data);
+ *   } catch (error) {
+ *     if (error.message === 'Widget closed by user') {
+ *       console.log('User cancelled');
+ *     } else {
+ *       console.error('Error:', error);
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @param config - Configuration options
+ * @returns Promise that resolves with { data, metadata } on success, rejects on error/close
+ */
+export declare function open(config: ImperativeConfig): Promise<OpenResult>;
+/**
+ * Creates a widget handle for manual control.
+ * Useful when you need to open/close the widget multiple times.
+ *
+ * @example
+ * ```javascript
+ * const widget = PortfolioConnect.create({
+ *   apiKey: 'your_api_key',
+ *   onSuccess: (data) => console.log(data),
+ * });
+ *
+ * document.getElementById('open-btn').onclick = () => widget.open();
+ * document.getElementById('close-btn').onclick = () => widget.destroy();
+ * ```
+ *
+ * @param config - Configuration options including callbacks
+ * @returns Handle with open() and destroy() methods
+ */
+export declare function create(config: ImperativeConfig & {
+    onSuccess: (data: ParsedData, metadata: ParseMetadata) => void;
+    onError?: (error: PortfolioConnectError) => void;
+    onClose?: () => void;
+}): WidgetHandle;