npm package: @rohit23061999/transaction-review-widget
Description: **@compass/musetax** is a suite of powerful and secure React widgets designed to enhance financial transparency and tax efficiency for users. These plug-and-play components allow seamless integration of AI-driven transaction categorization, historical ana
Latest version: 0.1.6014

# 🧭 MuseTax Widgets – React Integration

**@compass/musetax** is a suite of powerful and secure React widgets designed to enhance financial transparency and tax efficiency for users. These plug-and-play components allow seamless integration of AI-driven transaction categorization, historical analysis, and deduction discovery into any React (16+) application.

---

## 🖼️ Getting Started 
<a href="https://documentation.musetax.com/" target="_blank" rel="noopener noreferrer">📖 View Documentation</a>


### Step 1: API Access Request

Before using the widgets, users must register their email and reason for access. This is the first step in receiving credentials for secure API usage.

<img
  src="https://res.cloudinary.com/dxxdvbzla/image/upload/v1751626831/Screenshot_from_2025-07-04_16-29-03_o3twx7.png"
  alt="Transaction Review Widget Screenshot" style="
  max-width: 600px;
  width: 100%;
  border: 1px solid #ccc;
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
"/>

### Step 2: Client Credentials

Once approved, you will receive:

- `client_id`
- `client_secret`

### Step 3: Get Access Token

Use your `client_id` and `client_secret` to generate an access token:

```
POST /v2/api/auth/token

Response:
{
  "access_token": "string",
  "expires_in": "time"
}
```

### Step 4: Refresh Token

Access tokens are valid for 1 hour. To maintain a secure session without forcing the user to log in again, you can use the `refresh_token` to get a new `access_token`.


```
POST /v2/api/auth/refresh-token

Response:
{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

### Step 5: Generate User Credentials

Register a user using your credentials:

```
POST /v2/api/users
Payload : 
{
  "username": "string",
"email": "string",
"plaid_user_id": "string"
}

Response:
{
  "user_id": "string",
  "session_token": "string",
  "access_token": "Bearer",
  " ": 3600
}
```

These are required to securely initialize the widgets.

### Step 6: Get Compass Widget Session Token

Generate a session token for the Compass widget:

```
POST /v2/api/compass-widget-session

Payload:
- user_id

Security Note: Use this token to securely load widgets.
```

---

## 📦 Installation

```bash
npm install @compass/musetax
```

---

## 🛠️ Prerequisites

| Tool              | Recommended Version | Notes                                                         |
| ----------------- | ------------------- | ------------------------------------------------------------- |
| **Node.js**       | **v21.6.0 or newer**| Earlier LTS branches (≥ 18.x) *may* work but aren’t tested.   |
| **React**         | **18.x**            | Tested with React 18 and React DOM 18.                        |
| **TypeScript**    | **5.4+**            | Full typings are bundled.                                     |
| **Package Manager** | npm 10+, Yarn 1.22+, pnpm 9+ | Use whichever you prefer.                    |
| **Modern Browsers** | Latest 2 versions of Chrome, Firefox, Safari, Edge | Needed for Web Components & Intl APIs. |

> ✅ Smoke-tested frameworks: CRA 5, Vite 5+, Next.js 14+

---

## ⚙️ Required Props

| Prop            | Type   | Description                                    |
| --------------- | ------ | ---------------------------------------------- |
| `userId`        | string | Unique identifier for the current user         |
| `access_token`  | string | Authentication token provided by your backend  |
| `session_token` | string | Session token to validate secure widget access |
| `onError`       | fun    | Catch widget errors                            |

---

## 🔒 Security First

- All interactions are handled **securely** with **no exposed credentials**.
- Tokens are validated server-side for seamless and protected widget usage.

---

## 🧩 Available Widgets

### 1. CategorizeTransactionWidget

Personalized tax optimization using AI insights and secure financial data.

**Prerequisites:**

- User created & transactions synced
- Widget session token generated
- Recent categorization completed

```tsx
<CategorizeTransactionWidget
  userId={userId}
  access_token={accessToken}
  session_token={sessionToken}
  onError={(msg: any) => setWidgetError(msg)}
/>
```

<div class="screenshot-container" style="text-align: center; margin-bottom: 1rem">
  <img
    src="https://res.cloudinary.com/dxxdvbzla/image/upload/v1750162428/1._Transaction_Review_Widget_hajyzn.png"
    alt="Transaction Review Widget Screenshot" style="
      max-width: 80%;
      border: 1px solid #ccc;
      border-radius: 8px;
      box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
    " />
  <img
    src="https://res.cloudinary.com/dxxdvbzla/image/upload/v1750162428/1._Transaction_Review_Widget-1_dr8zk6.png"
    alt="Transaction Review Widget Screenshot" style="
      max-width: 80%;
      border: 1px solid #ccc;
      border-radius: 8px;
      box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
    " />
</div>

---

### 2. HistoricalAnalysisWidget

Compare current data with past tax returns to find missed opportunities.


### Prerequisites

- Current year transaction data fully processed
- Widget session token with analysis permissions
- User consent for document upload and processing

### Core Functionality

- 🔐 **Secure & Encrypted:** Handles `/analysis/1040` API integratio
- 🤖 **Comparative Analysis:** Compares filed vs. potential deductions
- 🎯 **Amendment Guidance:** ROI analysis for filing amended returns
- 📊 **Professional Referral:** Integration for complex cases

### API Integration Flow

- **Secure Upload:**
  User uploads their IRS Form 1040 via a secure, encrypted widget interface.
- **Document Processing:**
  Widget sends the file to `/analysis/1040` API for secure extraction and parsing of return data.
- **Comparative Analysis:**
  Extracted return data is automatically compared with current financial data from `/deductions/potential` API.
- **Gap Identification:**
  AI-powered logic detects any missed or underclaimed deductions based on IRS guidelines and current transactions.
- **Amendment Recommendations:**
  System presents actionable next steps, including potential refund amount and guidance on filing amended returns (Form 1040-X).
  

```tsx
<HistoricalAnalysisWidget
  userId={userId}
  access_token={accessToken}
  session_token={sessionToken}
  onError={(msg: any) => setWidgetError(msg)}
/>
```

<div class="screenshot-container" style="text-align: center; margin-bottom: 1rem">
  <img src="https://res.cloudinary.com/dxxdvbzla/image/upload/v1750162608/Historical_Analysis_Widget_Previous_Return_Analysis_kdynsx.png"
    alt="Historical Analysis Screenshot" style="
      max-width: 80%;
      border: 1px solid #ccc;
      border-radius: 8px;
      box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
    " />
  <img
    src="https://res.cloudinary.com/dxxdvbzla/image/upload/v1750161282/Historical_Analysis_Widget_Previous_Return_Analysis_vtlhc4.png"
    alt="Historical Analysis Screenshot" style="
      max-width: 80%;
      border: 1px solid #ccc;
      border-radius: 8px;
      box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
    " />
  <img
    src="https://res.cloudinary.com/dxxdvbzla/image/upload/v1750161282/Historical_Analysis_Widget_Year-over-Year_Comparison_ojlv4y.png"
    alt="Historical Comparison Screenshot" style="
      max-width: 80%;
      border: 1px solid #ccc;
      border-radius: 8px;
      box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
    " />
</div>


---

### 3. PotentialDeductions

AI identifies and groups deductions by IRS categories, allowing real-time modeling.


### Prerequisites

- Complete transaction sync and categorization
- Widget session token with deduction permissions
- User profile data for personalized analysis

### Core Functionality

- 🔐 **Secure Deduction Analysis:** Uses session token to call `/deductions/potential` API
- 🤖 **Schedule-Based Organization:** Groups by IRS tax schedules
- 🎯 **Supporting Evidence:** Links to transactions via `/transactions/details` API
- 📊 **Interactive Selection:** Real-time savings calculation

### API Integration Flow

- **Session Authentication:**
  Validates secure session token
- **Deduction Analysis:**
  Calls /deductions/potential for comprehensive analysis
- **Schedule Organization:**
  Groups deductions by IRS tax schedules
- **Supporting Data:**
  Fetches transaction details via `/transactions/details`
- **Interactive Modeling:**
  Real-time savings calculations


```tsx
<PotentialDeductions
  userId={userId}
  access_token={accessToken}
  session_token={sessionToken}
  onError={(msg: any) => setWidgetError(msg)}
/>
```

<div class="screenshot-container" style="text-align: center; margin-bottom: 1rem">
  <img
    src="https://res.cloudinary.com/dxxdvbzla/image/upload/v1750161282/3._Deduction_Discovery_Widget_oswkaa.png"
    alt="Potential Deductions Screenshot" style="
      max-width: 80%;
      border: 1px solid #ccc;
      border-radius: 8px;
      box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
    " />
</div>

---

## ✅ Key Features

- 🔐 Secure & encrypted token handling
- 🤖 AI-driven suggestions and grouping
- 📊 Bulk deduction modeling and insights
- 💰 Live savings tracking

---

## 📞 Support

Please contact the Compass team or open an issue in the project repository.

---

## 📝 License

This package is proprietary and maintained by Compass. All rights reserved.