@liiift-studio/sales-portal 1.2.1

package/README.md

@@ -0,0 +1,461 @@
+# @liiift-studio/sales-portal
+
+Centralized sales portal dashboard package for Liiift Studio projects (Darden Studio & Positype).
+
+## 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:
+
+| Feature | Environment Variable | Description |
+|---------|---------------------|-------------|
+| ✅ Sales Portal | `SALES_PORTAL_ENABLED` | Designer sales dashboard with analytics |
+| ✅ Custom Documents | `CUSTOM_DOCUMENTS_ENABLED` | Branded invoices, receipts, license PDFs |
+| ✅ Meta Fingerprinting | `META_FINGERPRINTING_ENABLED` | On-sale font metadata injection |
+| ✅ Multi-Script License | `MULTI_SCRIPT_LICENSE_ENABLED` | Language/script-based licensing options |
+| ✅ Beta/Pre-release | `BETA_PRERELEASE_ENABLED` | Early access font releases section |
+| ✅ Bulk Font Uploader | `BULK_FONT_UPLOADER_ENABLED` | Batch font file uploads to CMS |
+| ✅ Smart Media Pipeline | `MEDIA_PIPELINE_ENABLED` | Automated image/video optimization |
+
+### Feature Status by Foundry
+
+| Foundry | Sales Portal | Custom Docs | Meta FP | Multi-Script | Beta | Bulk Upload | Media Pipeline |
+|---------|:------------:|:-----------:|:-------:|:------------:|:----:|:-----------:|:--------------:|
+| Positype | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Darden Studio | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ |
+| The Designers Foundry | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ |
+| MCKL | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| Sorkin Type | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+
+## Installation
+
+```bash
+npm install @liiift-studio/sales-portal
+```
+
+## Prerequisites
+
+This package requires the following peer dependencies 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"
+}
+```
+
+## Required Foundry Repository Structure
+
+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.
+
+### Complete Directory Structure
+
+```
+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/getDesigners.js`**
+```javascript
+export { default, config } from '@liiift-studio/sales-portal/api/getDesigners';
+```
+
+**`pages/api/sales-portal/getSales.js`**
+```javascript
+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)
+
+**`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';
+```
+
+### Quick Setup Script
+
+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
+```
+
+### Environment Variables
+
+Create `.env.local` in your foundry app root with these required variables:
+
+```bash
+# Sanity CMS Configuration
+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
+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:
+
+- [ ] ✅ 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
+
+## Setup
+
+### 1. Configure Next.js
+
+Add MUI X packages to transpilation in `next.config.js`:
+
+```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;
+```
+
+## Usage
+
+### Basic Sales Dashboard
+
+```jsx
+import { Sales } from '@liiift-studio/sales-portal';
+
+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)}
+		/>
+	);
+}
+```
+
+### Individual Components
+
+```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';
+```
+
+## 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
+```
+
+## License
+
+UNLICENSED
+
+## Support
+
+For issues or questions, contact the development team or open an issue in the repository.

package/SETUP.md

@@ -0,0 +1,230 @@
+# Sales Portal Package Setup & Usage Guide
+
+## What Was Created
+
+A centralized npm package `@liiift/sales-portal` that contains all the sales portal code:
+
+- **Repository**: https://github.com/Liiift-Studio/sales-portal
+- **Package Name**: `@liiift/sales-portal`
+- **Version**: 1.0.0
+
+## Package Contents
+
+```
+sales-portal/
+├── components/          # All React components
+├── api/                 # API route handlers
+├── hooks/               # Custom React hooks
+├── utils/               # Utility functions
+├── styles/              # SCSS and theme files
+├── data/                # Static data (country codes)
+├── index.js             # Main export file
+├── package.json         # Package configuration
+└── README.md            # Full documentation
+```
+
+## How to Use in Projects
+
+### First Time Setup
+
+1. **Ensure `.npmrc` exists in your project** (already created in Positype):
+   ```
+   @liiift:registry=https://npm.pkg.github.com
+   ```
+
+2. **Authenticate with GitHub Packages** (one-time setup):
+   ```bash
+   # Create a GitHub personal access token with read:packages scope
+   # Then login to GitHub Packages
+   npm login --registry=https://npm.pkg.github.com
+   ```
+
+3. **Install the package**:
+   ```bash
+   # For production (when published)
+   yarn add @liiift/sales-portal
+   
+   # For local development (currently linked)
+   yarn link "@liiift/sales-portal"
+   ```
+
+### In Your Code
+
+**Import components:**
+```jsx
+import { Sales, DateRangeSalesTable, salesTheme } from '@liiift/sales-portal';
+```
+
+**Use in pages:**
+```jsx
+import { Sales, salesTheme } from '@liiift/sales-portal';
+import { ThemeProvider } from '@mui/system';
+
+export default function SalesPortalPage() {
+	return (
+		<ThemeProvider theme={salesTheme}>
+			<Sales designer={designerData} admin={isAdmin} />
+		</ThemeProvider>
+	);
+}
+```
+
+## Testing the Changes in Positype
+
+### Current Status
+
+✅ Package created and linked locally  
+✅ Positype updated to import from package  
+✅ `.npmrc` configured  
+⏳ Needs dev server restart for testing
+
+### Steps to Test
+
+1. **Restart the development server**:
+   ```bash
+   cd /Users/quinn-keaveney/Desktop/GITs/positype
+   # Stop current server (Ctrl+C)
+   yarn dev
+   ```
+
+2. **Visit the sales portal**:
+   ```
+   http://localhost:3000/sales-portal
+   ```
+
+3. **Expected behavior**:
+   - Login page loads correctly
+   - Components import from `@liiift/sales-portal` package
+   - All functionality works as before
+
+## Publishing Updates
+
+### Making Changes to the Package
+
+1. **Make changes in the sales-portal repo**:
+   ```bash
+   cd /Users/quinn-keaveney/Desktop/GITs/sales-portal
+   # Make your changes...
+   ```
+
+2. **Commit changes**:
+   ```bash
+   git add -A
+   git commit -m "Description of changes"
+   ```
+
+3. **Update version**:
+   ```bash
+   npm version patch  # for bug fixes
+   npm version minor  # for new features
+   npm version major  # for breaking changes
+   ```
+
+4. **Push and tag**:
+   ```bash
+   git push
+   git push --tags
+   ```
+
+5. **GitHub Actions will automatically publish** the new version to GitHub Packages
+
+### Updating Projects
+
+When a new version is published, update in your projects:
+
+```bash
+cd /Users/quinn-keaveney/Desktop/GITs/positype
+yarn upgrade @liiift/sales-portal
+
+cd /Users/quinn-keaveney/Desktop/GITs/Darden-Studio
+yarn upgrade @liiift/sales-portal
+```
+
+## Manual Publishing (If Needed)
+
+If GitHub Actions doesn't work or you need to publish manually:
+
+```bash
+cd /Users/quinn-keaveney/Desktop/GITs/sales-portal
+npm publish
+```
+
+Note: You'll need to authenticate with a GitHub token that has `write:packages` permission.
+
+## Migration for Darden Studio
+
+To migrate Darden Studio to use the package:
+
+1. **Add `.npmrc` file**:
+   ```
+   @liiift:registry=https://npm.pkg.github.com
+   ```
+
+2. **Install the package**:
+   ```bash
+   yarn add @liiift/sales-portal
+   ```
+
+3. **Update imports** in Darden Studio's files:
+   ```jsx
+   // Before
+   import { Sales } from '../../components/sales-portal/Sales';
+   
+   // After
+   import { Sales } from '@liiift/sales-portal';
+   ```
+
+4. **Keep API routes** in place (they're project-specific)
+
+5. **Remove old local files**:
+   ```bash
+   # Backup first!
+   rm -rf components/sales-portal
+   # Keep pages/api/sales-portal - these are needed
+   ```
+
+## Benefits
+
+✅ **Single Source of Truth**: One codebase for both projects  
+✅ **Easy Updates**: Update package once, upgrade in both projects  
+✅ **Version Control**: Track changes with semantic versioning  
+✅ **No Code Duplication**: Maintain features in one place  
+✅ **Consistent Experience**: Same portal across all foundries  
+
+## Troubleshooting
+
+### "Cannot find module '@liiift/sales-portal'"
+
+**Solution**: Link the package locally or install from GitHub Packages:
+```bash
+cd /Users/quinn-keaveney/Desktop/GITs/sales-portal
+yarn link
+
+cd /Users/quinn-keaveney/Desktop/GITs/positype
+yarn link "@liiift/sales-portal"
+```
+
+### Import paths not resolving
+
+**Solution**: Check `next.config.js` has `transpilePackages`:
+```js
+transpilePackages: ['@mui/x-data-grid', '@mui/x-date-pickers', '@mui/x-charts']
+```
+
+### MUI theme issues
+
+**Solution**: Ensure `ThemeProvider` and `LocalizationProvider` are set up in `_app.js`
+
+### GitHub Packages authentication
+
+**Solution**: Create a personal access token with `read:packages` scope and run:
+```bash
+npm login --registry=https://npm.pkg.github.com
+```
+
+## Support
+
+For issues or questions about the package:
+- Check the main README.md in the repository
+- Review the GitHub repository: https://github.com/Liiift-Studio/sales-portal
+- Contact the development team