🧭 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

📖 View Documentation

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.

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

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

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

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).

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

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

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

✅ 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.