@liiift-studio/sales-portal 1.3.4 → 1.8.0

package/README.md

@@ -1,23 +1,20 @@
 # @liiift-studio/sales-portal
 
-Centralized sales portal dashboard package for Liiift Studio foundary projects.
-
-## Description
-
-This package provides a comprehensive sales dashboard for type foundries, featuring:
-
-- 📊 Period-over-period sales comparison
-- 📈 Interactive charts and data visualization
-- 🗂️ DataGrid tables with sorting, filtering, and CSV export
-- 📅 Date range selection for custom reports
-- 💰 Stripe reconciliation checks
-- 🎯 Top performers analysis (typefaces and designers)
-- 📋 Detailed typeface and license type breakdowns
-- 🔍 Summary cards with key metrics
-
-## Liiift Add-on Features / Plugins
-
-The Liiift platform provides a modular plugin system. Each feature can be enabled or disabled per foundry via environment variables:
+Centralized sales portal dashboard for Liiift Studio foundry projects.
+
+## Features
+
+- Designer authentication via Sanity CMS
+- Admin multi-designer view with sequential loading
+- Monthly sales data from Stripe (invoices + payment intents)
+- Interactive charts and data visualization (MUI X-Charts)
+- DataGrid tables with sorting, filtering, and CSV export
+- Date range selection for custom export reports
+- Stripe balance reconciliation checks
+- Top performers analysis (typefaces and designers)
+- Typeface and license type breakdowns
+- Summary cards with key metrics
+- Login modal with two-column layout
 
 ## Installation
 
@@ -27,415 +24,146 @@ npm install @liiift-studio/sales-portal
 
 ## Prerequisites
 
-This package requires the following peer dependencies in your project:
+Peer dependencies required in your project:
 
 ```json
 {
-	"@mui/material": "^5.10.0",
-	"@mui/x-data-grid": "^8.0.0",
-	"@mui/x-date-pickers": "^7.0.0",
-	"@mui/x-charts": "^7.0.0",
-	"react": "^18.0.0",
-	"react-dom": "^18.0.0",
-	"next": "^14.0.0",
-	"dayjs": "^1.11.0",
-	"slugify": "^1.6.0"
+  "@mui/material": "^5.10.0",
+  "@mui/x-data-grid": "^8.0.0",
+  "@mui/x-date-pickers": "^7.0.0",
+  "@mui/x-charts": "^7.0.0",
+  "react": "^18.0.0",
+  "react-dom": "^18.0.0",
+  "next": "^14.0.0",
+  "dayjs": "^1.11.0",
+  "slugify": "^1.6.0"
 }
 ```
 
-## Required Foundry Repository Structure
+Note: Compatible with MUI v5 through v7 (uses Box/flexbox instead of Grid).
 
-Your foundry's Next.js application **must** have the following directory structure and wrapper files to use this package. The wrapper files are thin re-exports that allow Next.js API routes to work with the centralized package.
+## Quick Start
 
-### Complete Directory Structure
+### 1. Create API route wrappers
 
 ```
-your-foundry-app/
-├── .env.local                           # Environment variables
-├── .npmrc                               # GitHub Packages authentication
-├── package.json                         # Add @liiift/sales-portal dependency
-├── pages/
-│   ├── _app.js                          # Wrap with MUI providers
-│   ├── sales-portal.js                  # Your sales dashboard page
-│   └── api/
-│       └── sales-portal/                # API wrapper directory
-│           ├── getDesignerInfo.js       # ⚠️ REQUIRED
-│           ├── getDesigners.js          # ⚠️ REQUIRED
-│           ├── getSales.js              # ⚠️ REQUIRED
-│           ├── getSalesRange.js         # ⚠️ REQUIRED
-│           ├── getPreviousSales.js      # ⚠️ REQUIRED
-│           ├── getBalanceTransactions.js # ⚠️ REQUIRED
-│           ├── getAnalytics.js          # ⚠️ REQUIRED
-│           └── utils/                   # Utility wrappers
-│               ├── authMiddleware.js
-│               ├── dateUtils.js
-│               ├── feeCalculator.js
-│               ├── salesDataProcessing.js
-│               ├── salesDataProcessor.js
-│               ├── stripeFetcher.js
-│               └── processors/
-│                   ├── invoiceProcessor.js
-│                   └── paymentProcessor.js
-└── next.config.js                       # MUI transpile configuration
-```
-
-### Required Wrapper Files
-
-Create each of these files **exactly** as shown:
-
-#### API Route Wrappers (with default exports)
-
-**`pages/api/sales-portal/getDesignerInfo.js`**
-```javascript
-export { default, config } from '@liiift-studio/sales-portal/api/getDesignerInfo';
+pages/api/sales-portal/
+  getDesignerInfo.js
+  getDesigners.js
+  getSales.js
+  getBalanceTransactions.js
 ```
 
-**`pages/api/sales-portal/getDesigners.js`**
-```javascript
-export { default, config } from '@liiift-studio/sales-portal/api/getDesigners';
-```
+Each file is a one-line re-export:
 
-**`pages/api/sales-portal/getSales.js`**
-```javascript
+```js
+// pages/api/sales-portal/getSales.js
 export { default, config } from '@liiift-studio/sales-portal/api/getSales';
 ```
 
-**`pages/api/sales-portal/getSalesRange.js`**
-```javascript
-export { default, config } from '@liiift-studio/sales-portal/api/getSalesRange';
-```
-
-**`pages/api/sales-portal/getPreviousSales.js`**
-```javascript
-export { default, config } from '@liiift-studio/sales-portal/api/getPreviousSales';
-```
-
-**`pages/api/sales-portal/getBalanceTransactions.js`**
-```javascript
-export { default, config } from '@liiift-studio/sales-portal/api/getBalanceTransactions';
-```
-
-**`pages/api/sales-portal/getAnalytics.js`**
-```javascript
-export { default, config } from '@liiift-studio/sales-portal/api/getAnalytics';
-```
-
-#### Utility Wrappers (with named exports)
+### 2. Create the page
 
-**`pages/api/sales-portal/utils/authMiddleware.js`**
-```javascript
-export * from '@liiift-studio/sales-portal/api/utils/authMiddleware';
-```
-
-**`pages/api/sales-portal/utils/dateUtils.js`**
-```javascript
-export * from '@liiift-studio/sales-portal/api/utils/dateUtils';
-```
-
-**`pages/api/sales-portal/utils/feeCalculator.js`**
-```javascript
-export * from '@liiift-studio/sales-portal/api/utils/feeCalculator';
-```
-
-**`pages/api/sales-portal/utils/salesDataProcessing.js`**
-```javascript
-export * from '@liiift-studio/sales-portal/api/utils/salesDataProcessing';
-```
-
-**`pages/api/sales-portal/utils/salesDataProcessor.js`**
-```javascript
-export * from '@liiift-studio/sales-portal/api/utils/salesDataProcessor';
-```
-
-**`pages/api/sales-portal/utils/stripeFetcher.js`**
-```javascript
-export * from '@liiift-studio/sales-portal/api/utils/stripeFetcher';
-```
-
-**`pages/api/sales-portal/utils/processors/invoiceProcessor.js`**
-```javascript
-export * from '@liiift-studio/sales-portal/api/utils/processors/invoiceProcessor';
-```
-
-**`pages/api/sales-portal/utils/processors/paymentProcessor.js`**
-```javascript
-export * from '@liiift-studio/sales-portal/api/utils/processors/paymentProcessor';
+```jsx
+// pages/sales-portal.js
+import { SalesPortalPage } from '@liiift-studio/sales-portal';
+
+export default function SalesPortal() {
+  return (
+    <SalesPortalPage
+      texts={{
+        title: 'Sales Portal',
+        dashboardTitle: 'Monthly Sales',
+        dashboardSubtitle: 'by designer'
+      }}
+    />
+  );
+}
 ```
 
-### Quick Setup Script
+### 3. Configure Next.js
 
-To quickly create all wrapper files, you can run this bash script from your foundry app root:
-
-```bash
-#!/bin/bash
-# create-sales-portal-wrappers.sh
-
-# Create directory structure
-mkdir -p pages/api/sales-portal/utils/processors
-
-# API route wrappers
-echo "export { default, config } from '@liiift-studio/sales-portal/api/getDesignerInfo';" > pages/api/sales-portal/getDesignerInfo.js
-echo "export { default, config } from '@liiift-studio/sales-portal/api/getDesigners';" > pages/api/sales-portal/getDesigners.js
-echo "export { default, config } from '@liiift-studio/sales-portal/api/getSales';" > pages/api/sales-portal/getSales.js
-echo "export { default, config } from '@liiift-studio/sales-portal/api/getSalesRange';" > pages/api/sales-portal/getSalesRange.js
-echo "export { default, config } from '@liiift-studio/sales-portal/api/getPreviousSales';" > pages/api/sales-portal/getPreviousSales.js
-echo "export { default, config } from '@liiift-studio/sales-portal/api/getBalanceTransactions';" > pages/api/sales-portal/getBalanceTransactions.js
-echo "export { default, config } from '@liiift-studio/sales-portal/api/getAnalytics';" > pages/api/sales-portal/getAnalytics.js
-
-# Utility wrappers
-echo "export * from '@liiift-studio/sales-portal/api/utils/authMiddleware';" > pages/api/sales-portal/utils/authMiddleware.js
-echo "export * from '@liiift-studio/sales-portal/api/utils/dateUtils';" > pages/api/sales-portal/utils/dateUtils.js
-echo "export * from '@liiift-studio/sales-portal/api/utils/feeCalculator';" > pages/api/sales-portal/utils/feeCalculator.js
-echo "export * from '@liiift-studio/sales-portal/api/utils/salesDataProcessing';" > pages/api/sales-portal/utils/salesDataProcessing.js
-echo "export * from '@liiift-studio/sales-portal/api/utils/salesDataProcessor';" > pages/api/sales-portal/utils/salesDataProcessor.js
-echo "export * from '@liiift-studio/sales-portal/api/utils/stripeFetcher';" > pages/api/sales-portal/utils/stripeFetcher.js
-echo "export * from '@liiift-studio/sales-portal/api/utils/processors/invoiceProcessor';" > pages/api/sales-portal/utils/processors/invoiceProcessor.js
-echo "export * from '@liiift-studio/sales-portal/api/utils/processors/paymentProcessor';" > pages/api/sales-portal/utils/processors/paymentProcessor.js
-
-echo "✅ All sales-portal wrapper files created!"
-```
-
-Make the script executable and run it:
-```bash
-chmod +x create-sales-portal-wrappers.sh
-./create-sales-portal-wrappers.sh
+```js
+// next.config.js
+const nextConfig = {
+  transpilePackages: ['@mui/x-charts', '@liiift-studio/sales-portal'],
+};
 ```
 
-### Environment Variables
-
-Create `.env.local` in your foundry app root with these required variables:
+### 4. Set environment variables
 
 ```bash
-# Sanity CMS Configuration
+# .env.local
 SANITY_STUDIO_PROJECT_ID=your_project_id
 SANITY_STUDIO_DATASET=production
-SANITY_STUDIO_API_VERSION=2022-04-01
-SANITY_STUDIO_TOKEN=your_sanity_token_here
-
-# Stripe Configuration
-STRIPE_SECRET_KEY=your_stripe_secret_key_here
-
-# ============================================
-# LIIIFT ADD-ON FEATURES / PLUGINS
-# ============================================
-# Each feature can be enabled/disabled independently per foundry
-
-# Sales Portal - Designer sales dashboard with analytics
+SANITY_STUDIO_TOKEN=your_sanity_token
+STRIPE_SECRET_KEY=your_stripe_secret_key
 SALES_PORTAL_ENABLED=true
-
-# Custom Documents - Branded invoices, receipts, license PDFs
-CUSTOM_DOCUMENTS_ENABLED=true
-
-# Meta Fingerprinting - On-sale font metadata injection
-META_FINGERPRINTING_ENABLED=true
-
-# Multi-Script License Selection - Language/script-based licensing
-MULTI_SCRIPT_LICENSE_ENABLED=true
-
-# Beta/Pre-release Section - Early access font releases
-BETA_PRERELEASE_ENABLED=true
-
-# Bulk Font Uploader - Batch font file uploads to CMS
-BULK_FONT_UPLOADER_ENABLED=true
-
-# Smart Media Pipeline - Automated image/video optimization
-MEDIA_PIPELINE_ENABLED=true
-
-# Optional: NextAuth (if using)
-NEXTAUTH_URL=https://your-domain.com
-NEXTAUTH_SECRET=your_nextauth_secret
-```
-
-#### Feature Toggle
-
-The `SALES_PORTAL_ENABLED` environment variable controls whether the sales portal is accessible:
-
-- **`true`** (default) - Sales portal functions normally
-- **`false`** - All API endpoints return a 503 response with `{ success: false, message: 'Sales portal is currently disabled', disabled: true }`
-
-This is useful for:
-- Temporarily disabling the sales portal during maintenance
-- Enabling/disabling the feature per foundry site
-- Quick rollback without code changes
-
-### NPM Authentication
-
-This package is published to npmjs.org under the `@liiift-studio` organization. No additional registry configuration is required - npm will automatically fetch from the public registry.
-
-For private installations requiring authentication, configure your npm credentials:
-```bash
-npm login
 ```
 
-### Integration Checklist
-
-Use this checklist to verify your setup:
+## API Endpoints
 
-- [ ] ✅ Package installed: `@liiift-studio/sales-portal` in package.json
-- [ ] ✅ All 7 API route wrappers created in `pages/api/sales-portal/`
-- [ ] ✅ All 8 utility wrappers created in `pages/api/sales-portal/utils/`
-- [ ] ✅ `.env.local` file created with all required environment variables
-- [ ] ✅ `next.config.js` includes MUI transpilePackages
-- [ ] ✅ `pages/_app.js` wrapped with MUI ThemeProvider and LocalizationProvider
-- [ ] ✅ `pages/sales-portal.js` created with Sales component
-- [ ] ✅ Development server starts without errors
-- [ ] ✅ Navigate to `/sales-portal` and see login form
-- [ ] ✅ Login with designer credentials succeeds
-- [ ] ✅ Sales data displays correctly
-- [ ] ✅ CSV export works
-- [ ] ✅ PDF print works
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `getDesignerInfo` | POST | Authenticate designer, return account data |
+| `getDesigners` | GET | List all designers (admin) |
+| `getSales` | POST | Fetch sales data for a month or date range |
+| `getBalanceTransactions` | POST | Fetch Stripe balance transactions for reconciliation |
 
-## Setup
-
-### 1. Configure Next.js
-
-Add MUI X packages to transpilation in `next.config.js`:
+## Component Exports
 
 ```js
-const nextConfig = {
-	transpilePackages: ['@mui/x-data-grid', '@mui/x-date-pickers', '@mui/x-charts'],
-	// ... rest of your config
-};
-```
-
-### 2. Add MUI Providers
-
-Wrap your app with required providers in `pages/_app.js`:
-
-```jsx
-import { ThemeProvider } from '@mui/material/styles';
-import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
-import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
-import { salesTheme } from '@liiift-studio/sales-portal';
-
-function MyApp({ Component, pageProps }) {
-	return (
-		<ThemeProvider theme={salesTheme}>
-			<LocalizationProvider dateAdapter={AdapterDayjs}>
-				<Component {...pageProps} />
-			</LocalizationProvider>
-		</ThemeProvider>
-	);
-}
-```
-
-### 3. Set up API Routes
-
-Copy the API handlers from the package to your `pages/api/sales-portal/` directory:
-
-```bash
-cp -R node_modules/@liiift-studio/sales-portal/api/* pages/api/sales-portal/
-```
-
-Or create wrapper handlers:
-
-```js
-// pages/api/sales-portal/getSales.js
-import handler from '@liiift-studio/sales-portal/api/getSales';
-export default handler;
+import {
+  SalesPortalPage,  // Full page with login modal + dashboard
+  LoginForm,        // Login modal component
+  Sales,            // Individual designer sales dashboard
+  SalesTable,       // Sales data table with CSV export
+  DateRangeSalesTable, // Custom date range export table
+  SalesChart,       // Revenue trend charts
+  SummaryCards,     // Key metrics cards
+  TopPerformers,    // Top typefaces/designers
+  TypefaceList,     // Typeface breakdown
+  LicenseTypeList,  // License type analysis
+  PeriodComparison, // Period comparison charts
+  salesTheme,       // MUI theme
+} from '@liiift-studio/sales-portal';
 ```
 
-## Usage
-
-### Basic Sales Dashboard
-
-```jsx
-import { Sales } from '@liiift-studio/sales-portal';
+## Architecture
 
-export default function SalesPortalPage() {
-	return <Sales designer={designerData} admin={isAdmin} />;
-}
 ```
-
-### Date Range Sales Table
-
-```jsx
-import { DateRangeSalesTable } from '@liiift-studio/sales-portal';
-
-export default function ExportsPage() {
-	return (
-		<DateRangeSalesTable
-			designer={designerData}
-			admin={isAdmin}
-			loading={false}
-			updateLoadingState={(key, state) => console.log(key, state)}
-		/>
-	);
-}
+@liiift-studio/sales-portal
+  api/
+    utils/
+      clients.js           # Shared Sanity + Stripe clients
+      apiResponse.js       # Standardized error/success responses
+      authMiddleware.js     # Request authentication
+      dateUtils.js          # UTC date range utilities
+      salesDataProcessor.js # Core sales data pipeline
+      stripeFetcher.js      # Stripe API pagination
+      feeCalculator.js      # Fee distribution + rounding
+      processors/
+        invoiceProcessor.js     # Stripe invoice processing
+        paymentProcessor.js     # Stripe payment intent processing
+  components/               # React components (Box/flexbox, no MUI Grid)
+  styles/                   # SCSS + MUI theme
+  hooks/                    # Custom React hooks
+  utils/                    # Client-side utilities
 ```
 
-### Individual Components
+## Currently deployed on
 
-```jsx
-import { 
-	SalesTable, 
-	SalesChart, 
-	SummaryCards,
-	TopPerformers 
-} from '@liiift-studio/sales-portal';
-
-// Use components individually as needed
-```
-
-## Exports
-
-### Components
-- `Sales` - Main dashboard component
-- `SalesTable` - Table with sales data
-- `DateRangeSalesTable` - Table for custom date ranges
-- `SalesChart` - Charts for visualizing sales trends
-- `SummaryCards` - Key metrics summary cards
-- `TopPerformers` - Top performing typefaces/designers
-- `TypefaceList` - Detailed typeface breakdown
-- `LicenseTypeList` - License type analysis
-- `PeriodComparison` - Period-over-period comparison
-- `DebugValues` - Debug information display
-- `TableRowCells`, `getCellValue` - Table cell rendering utilities
-- `COLUMNS` - Table column definitions
-
-### Hooks
-- `useSalesDateQuery` - Date query management hook
-
-### Utilities
-- Currency formatting utilities
-- Sales data processing functions
-
-### Styles
-- `salesTheme` - MUI theme configuration
-
-### API Handlers (import separately)
-```js
-import getDesignerInfo from '@liiift-studio/sales-portal/api/getDesignerInfo';
-import getDesigners from '@liiift-studio/sales-portal/api/getDesigners';
-import getSales from '@liiift-studio/sales-portal/api/getSales';
-import getPreviousSales from '@liiift-studio/sales-portal/api/getPreviousSales';
-import getSalesRange from '@liiift-studio/sales-portal/api/getSalesRange';
-import getBalanceTransactions from '@liiift-studio/sales-portal/api/getBalanceTransactions';
-import getAnalytics from '@liiift-studio/sales-portal/api/getAnalytics';
-```
+- [The Designers Foundry](https://thedesignersfoundry.com) (staging)
+- [Darden Studio](https://dardenstudio.com)
+- [Positype](https://positype.com)
 
 ## Development
 
-To make changes to this package:
-
-1. Clone the repository
-2. Make your changes
-3. Update the version: `npm version patch|minor|major`
-4. Commit and push
-5. GitHub Actions will automatically publish to npmjs.org
-
-## Updating in Projects
-
-To get the latest version in your project:
-
-```bash
-npm update @liiift-studio/sales-portal
-```
+1. Make changes in the sales-portal repo
+2. Bump version in package.json
+3. Commit and push to master
+4. Publish: `npm publish --access public`
+5. Foundry sites pick up new version on next deploy (uses `^` semver)
 
 ## License
 
 UNLICENSED
-
-## Support
-
-For issues or questions, contact the development team or open an issue in the repository.