subos-frontend 1.0.0

package/LIBRARY_USAGE.md

@@ -0,0 +1,162 @@
+# SubOS Frontend Library Usage
+
+## Installation
+
+```bash
+npm install subos-frontend
+# or
+yarn add subos-frontend
+```
+
+## Required Peer Dependencies
+
+Make sure your project has these dependencies installed:
+
+```bash
+npm install react react-dom react-router-dom @stripe/react-stripe-js @stripe/stripe-js
+```
+
+## Configuration (REQUIRED)
+
+**⚠️ Important:** You MUST configure SubOS before using any components, otherwise you'll get runtime errors.
+
+### Method 1: Runtime Configuration (Recommended)
+
+```javascript
+import { configureSubOS } from 'subos-frontend';
+
+// Configure SubOS at the root of your app (e.g., in main.jsx, _app.js, or App.jsx)
+configureSubOS({
+  apiEndpoint: 'https://your-api.com/api/v1',
+  projectId: 'your-project-id',
+  stripePublishableKey: 'pk_test_your_stripe_key',
+  appName: 'Your App Name',
+  appEnvironment: 'production' // or 'development'
+});
+```
+
+### Method 2: Environment Variables
+
+Set these environment variables in your project:
+
+```bash
+# .env or .env.local
+VITE_API_ENDPOINT=https://your-api.com/api/v1
+VITE_PROJECT_ID=your-project-id
+VITE_STRIPE_PUBLISHABLE_KEY=pk_test_your_stripe_key
+VITE_APP_NAME=Your App Name
+VITE_APP_ENVIRONMENT=production
+```
+
+## Usage Examples
+
+### Basic Component Usage
+
+```jsx
+import React from 'react';
+import { PlansList, configureSubOS } from 'subos-frontend';
+import 'subos-frontend/style.css';
+
+// Configure first (do this once at app startup)
+configureSubOS({
+  apiEndpoint: 'https://your-api.com/api/v1',
+  projectId: 'your-project-id',
+  stripePublishableKey: 'pk_test_your_stripe_key'
+});
+
+function MyPlansPage() {
+  return (
+    <div>
+      <h1>Choose Your Plan</h1>
+      <PlansList />
+    </div>
+  );
+}
+```
+
+### Validation
+
+```jsx
+import { validateSubOSConfig, ensureSubOSConfig } from 'subos-frontend';
+
+// Check if configuration is valid
+const validation = validateSubOSConfig();
+if (!validation.isValid) {
+  console.error('Missing config:', validation.missingFields);
+}
+
+// Or throw an error if config is invalid
+try {
+  ensureSubOSConfig();
+  // Safe to use SubOS components here
+} catch (error) {
+  console.error('SubOS not configured:', error.message);
+}
+```
+
+### Next.js Setup
+
+```jsx
+// pages/_app.js or app/layout.js
+import { configureSubOS } from 'subos-frontend';
+import 'subos-frontend/style.css';
+
+// Configure SubOS once at app startup
+configureSubOS({
+  apiEndpoint: process.env.NEXT_PUBLIC_API_ENDPOINT,
+  projectId: process.env.NEXT_PUBLIC_PROJECT_ID,
+  stripePublishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
+});
+
+export default function MyApp({ Component, pageProps }) {
+  return <Component {...pageProps} />;
+}
+```
+
+### Vite/React Setup
+
+```jsx
+// main.jsx or App.jsx
+import { configureSubOS } from 'subos-frontend';
+import 'subos-frontend/style.css';
+
+configureSubOS({
+  apiEndpoint: import.meta.env.VITE_API_ENDPOINT,
+  projectId: import.meta.env.VITE_PROJECT_ID,
+  stripePublishableKey: import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY,
+});
+```
+
+## Available Components
+
+- `PlansList` - Display available subscription plans
+- `CheckoutForm` - Handle subscription checkout
+- `SubscriptionManager` - Manage existing subscriptions
+- `TransactionHistory` - Display transaction history
+- `PaymentMethods` - Manage payment methods
+
+## Troubleshooting
+
+### "Cannot read properties of undefined (reading 'VITE_API_ENDPOINT')"
+
+This error occurs when SubOS is not properly configured. Make sure to:
+
+1. Call `configureSubOS()` before using any SubOS components
+2. Provide all required configuration values
+3. Import and configure SubOS at the root of your application
+
+### Missing Peer Dependencies
+
+If you get errors about missing React or Stripe dependencies, install them:
+
+```bash
+npm install react react-dom react-router-dom @stripe/react-stripe-js @stripe/stripe-js
+```
+
+## TypeScript Support
+
+The library includes full TypeScript support. Import types as needed:
+
+```typescript
+import type { ConfigureSubOSInput, EnvConfig } from 'subos-frontend';
+```

package/README.md

@@ -0,0 +1,396 @@
+# SubOS Frontend - React Component Library
+
+A comprehensive React component library for subscription management, billing, and payment processing. SubOS Frontend provides a collection of reusable UI components designed to be integrated into React applications for managing subscriptions, pricing, billing, and account logic.
+
+## 🚀 Features
+
+- **Plan Management Components** - Browse, select, and display subscription plans
+- **Payment Processing** - Stripe-integrated payment components and flows
+- **Subscription Management** - View, manage, and cancel subscriptions
+- **Transaction History** - Display payment history and invoices
+- **Billing Components** - Handle billing cycles, pricing tiers, and coupons
+- **TypeScript Support** - Full TypeScript definitions included
+- **Modern UI** - Clean, responsive components built with Tailwind CSS
+- **Tree Shaking** - Optimized bundle size with ESM support
+
+## 📦 Installation
+
+```bash
+npm install subos-frontend
+# or
+yarn add subos-frontend
+# or
+pnpm add subos-frontend
+```
+
+## 🎯 Quick Start
+
+### 1. Import Styles
+
+Import the CSS file in your app's entry point:
+
+```tsx
+import 'subos-frontend/style.css';
+```
+
+### 2. Configure SubOS
+
+You have two options to configure the library:
+
+#### Option A: Runtime Configuration (Recommended)
+
+```tsx
+import { configureSubOS } from 'subos-frontend';
+
+configureSubOS({
+  apiEndpoint: 'https://your-api.com/api/v1',
+  projectId: 'your-project-id',
+  stripePublishableKey: 'pk_live_xxx', // Optional, for payment features
+  appName: 'Your App Name',
+  appEnvironment: 'production'
+});
+```
+
+#### Option B: Environment Variables
+
+Create a `.env` file in your project root (copy from `.env.example` included in the package):
+
+```env
+VITE_API_ENDPOINT=https://your-api.com/api/v1
+VITE_PROJECT_ID=your-project-id
+VITE_STRIPE_PUBLISHABLE_KEY=pk_live_xxx
+VITE_APP_NAME=Your App Name
+VITE_APP_ENVIRONMENT=production
+```
+
+### 3. Use Components
+
+```tsx
+import { PlanCard, PlansGrid, SubscriptionDetails } from 'subos-frontend';
+
+function MyApp() {
+  return (
+    <div>
+      <PlansGrid 
+        plans={plans}
+        onPlanSelect={handlePlanSelect}
+        billingCycle="monthly"
+      />
+    </div>
+  );
+}
+```
+
+## 🧩 Available Components
+
+### Plan Components
+
+```tsx
+import { 
+  PlanCard, 
+  PlansGrid, 
+  PlanSelector, 
+  BillingCycleToggle,
+  TierFilterDropdown 
+} from 'subos-frontend';
+
+// Display individual plan
+<PlanCard 
+  plan={plan}
+  isSelected={false}
+  billingCycle="monthly"
+  onSelect={handleSelect}
+/>
+
+// Display grid of plans
+<PlansGrid 
+  plans={plans}
+  selectedPlan={selectedPlan}
+  billingCycle="monthly"
+  onPlanSelect={handlePlanSelect}
+/>
+
+// Billing cycle toggle
+<BillingCycleToggle 
+  value="monthly"
+  onChange={handleCycleChange}
+/>
+```
+
+### Payment Components
+
+```tsx
+import { 
+  PaymentSuccessView, 
+  PaymentCancelView,
+  ChangeCardButton 
+} from 'subos-frontend';
+
+// Payment result pages
+<PaymentSuccessView />
+<PaymentCancelView />
+
+// Change payment method
+<ChangeCardButton onCardChange={handleCardChange} />
+```
+
+### Subscription Components
+
+```tsx
+import { SubscriptionDetails } from 'subos-frontend';
+
+<SubscriptionDetails 
+  subscription={subscription}
+  onCancel={handleCancel}
+  onUpgrade={handleUpgrade}
+/>
+```
+
+### Transaction Components
+
+```tsx
+import { TransactionList, TransactionModal } from 'subos-frontend';
+
+<TransactionList 
+  transactions={transactions}
+  onViewInvoice={handleViewInvoice}
+/>
+
+<TransactionModal 
+  transaction={transaction}
+  isOpen={isModalOpen}
+  onClose={handleClose}
+/>
+```
+
+### Utility Components
+
+```tsx
+import { Layout, LogoInline, CheckIcon, Pagination } from 'subos-frontend';
+
+// Layout wrapper
+<Layout>
+  <YourContent />
+</Layout>
+
+// Pagination
+<Pagination 
+  currentPage={1}
+  totalPages={10}
+  onPageChange={handlePageChange}
+/>
+```
+
+## ⚙️ Environment Configuration
+
+### Configuration Options
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `VITE_API_ENDPOINT` | Your SubOS backend API URL | ✅ | `http://localhost:3002/api/v1` |
+| `VITE_PROJECT_ID` | Your project ID from SubOS backend | ✅ | - |
+| `VITE_STRIPE_PUBLISHABLE_KEY` | Stripe publishable key for payments | ⚠️ | - |
+| `VITE_APP_NAME` | Your application name | ❌ | `SubOS Frontend` |
+| `VITE_APP_VERSION` | Your application version | ❌ | `1.0.0` |
+| `VITE_APP_ENVIRONMENT` | Environment (development/production) | ❌ | `development` |
+| `VITE_DEBUG` | Enable debug mode | ❌ | `false` |
+
+### Runtime Configuration API
+
+```tsx
+import { configureSubOS, getApiBaseUrl, getProjectId } from 'subos-frontend';
+
+// Configure at app startup
+configureSubOS({
+  apiEndpoint: 'https://api.mycompany.com/api/v1',
+  projectId: 'my-project-id',
+  stripePublishableKey: 'pk_live_xxx',
+  appName: 'My Company App',
+  appEnvironment: 'production',
+  debug: false
+});
+
+// Access configured values
+const apiUrl = getApiBaseUrl();
+const projectId = getProjectId();
+```
+
+### Environment Template
+
+Copy the included `.env.example` file to your project and customize:
+
+```bash
+cp node_modules/subos-frontend/.env.example .env
+```
+
+## 🔧 API Integration
+
+The library includes a complete API client for backend integration:
+
+```tsx
+import { 
+  plansApi, 
+  subscriptionApi, 
+  customerApi, 
+  transactionApi,
+  checkoutApi 
+} from 'subos-frontend';
+
+// Fetch plans
+const { data: plans } = await plansApi.getPlans();
+
+// Get subscription
+const { data: subscription } = await subscriptionApi.getActiveSubscription(userId);
+
+// Create checkout session
+const { data: session } = await plansApi.createPaymentSession(planCode, {
+  customerEmail: 'user@example.com',
+  couponCode: 'DISCOUNT10'
+});
+```
+
+## 🎨 Styling
+
+Components are styled with Tailwind CSS. You can:
+
+1. **Use default styles** - Import the included CSS file
+2. **Customize with Tailwind** - Override classes using Tailwind utilities
+3. **Custom CSS** - Override component styles with custom CSS
+
+## 📋 TypeScript Support
+
+Full TypeScript definitions are included:
+
+```tsx
+import type { 
+  Plan, 
+  Subscription, 
+  Transaction, 
+  PlanCardProps,
+  ApiResponse 
+} from 'subos-frontend';
+```
+
+## 🔄 Development Setup
+
+For contributing or local development:
+
+### Prerequisites
+
+- Node.js (v20.19.0 or higher)
+- pnpm (recommended)
+
+### Setup
+
+```bash
+git clone <repository-url>
+cd subos-frontend
+pnpm install
+pnpm dev
+```
+
+### Build Library
+
+```bash
+pnpm build
+```
+
+This generates:
+- `/dist/index.js` - ESM bundle
+- `/dist/index.cjs` - CommonJS bundle  
+- `/dist/index.d.ts` - TypeScript declarations
+- `/dist/style.css` - Compiled styles
+
+## Project Structure
+
+```
+subos-frontend/
+├── src/
+│   ├── api/          # API utilities and endpoints
+│   ├── assets/       # Static assets
+│   ├── components/   # React components
+│   ├── config/       # Configuration files
+│   ├── hooks/        # Custom React hooks
+│   ├── pages/        # Page components
+│   ├── styles/       # Global styles
+│   ├── types/        # TypeScript type definitions
+│   ├── utils/        # Utility functions
+│   ├── App.tsx       # Main App component with routing
+│   └── main.tsx      # Application entry point
+├── public/           # Public assets
+└── .env              # Environment variables
+```
+
+## Backend Integration
+
+This frontend is designed to work with the SubOS backend API (NestJS, TypeScript, PostgreSQL, TypeORM). 
+
+### Configuration
+
+1. Configure the API endpoint in your environment variables (`.env` file):
+   ```env
+   VITE_API_URL=http://localhost:3000
+   ```
+
+2. The API configuration is handled in `src/config/` directory.
+
+### Backend Requirements
+
+- NestJS backend with TypeScript
+- PostgreSQL database with TypeORM
+- CORS enabled for frontend domain
+- API endpoints for subscription management
+
+## 📚 Available Scripts
+
+- `pnpm build` - Build the library (ESM + CommonJS + types)
+- `pnpm build:watch` - Build in watch mode
+- `pnpm dev` - Start development server
+- `pnpm lint` - Run ESLint
+
+## 🔗 Peer Dependencies
+
+Ensure your project includes these peer dependencies:
+
+```json
+{
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18", 
+    "react-router-dom": ">=6",
+    "@stripe/react-stripe-js": ">=2",
+    "@stripe/stripe-js": ">=1"
+  }
+}
+```
+
+## 🏗️ Tech Stack
+
+- **Frontend**: React 19, TypeScript
+- **Build Tool**: tsup (ESM + CommonJS)
+- **Styling**: Tailwind CSS
+- **Payment**: Stripe integration
+- **Routing**: React Router DOM
+- **Package Manager**: pnpm
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Commit changes: `git commit -m 'Add amazing feature'`
+4. Push to branch: `git push origin feature/amazing-feature`
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License.
+
+## 🆘 Support
+
+For support and questions:
+- Create an issue in the repository
+- Contact the development team
+
+---
+
+Built with ❤️ by the Knovator team