@classytic/revenue 0.0.2 → 0.0.22

package/README.md

@@ -6,449 +6,375 @@ Thin, focused, production-ready library with smart defaults. Built for SaaS, mar
 
 ## Features
 
-- **Subscriptions**: Create, renew, upgrade, downgrade with smart proration
-- **Payment Processing**: Multi-gateway support (Stripe, SSLCommerz, bKash, manual)
-- **Transaction Management**: Complete lifecycle with verification and refunds
-- **Provider Pattern**: Pluggable payment providers (like AI SDK)
-- **Framework Agnostic**: Works with Fastify, Express, Nest, or standalone
-- **Model Flexible**: Plain Mongoose OR @classytic/mongokit Repository
+- **Subscriptions**: Create, renew, pause, cancel with lifecycle management
+- **Payment Processing**: Multi-gateway support (Stripe, SSLCommerz, manual, etc.)
+- **Transaction Management**: Income/expense tracking with verification and refunds
+- **Provider Pattern**: Pluggable payment providers (like LangChain/Vercel AI SDK)
+- **Framework Agnostic**: Works with Express, Fastify, Next.js, or standalone
 - **TypeScript Ready**: Full type definitions included
-- **Zero Dependencies**: Only requires `mongoose` as peer dependency
 
 ## Installation
 
 ```bash
 npm install @classytic/revenue
+npm install @classytic/revenue-manual  # For manual payments
 ```
 
-## Transaction Model Setup
-
-Spread library enums/schemas into your Transaction model:
-
-```javascript
-import mongoose from 'mongoose';
-import {
-  TRANSACTION_STATUS_VALUES,
-  LIBRARY_CATEGORIES,
-} from '@classytic/revenue/enums';
-import {
-  gatewaySchema,
-  currentPaymentSchema,
-  paymentDetailsSchema,
-} from '@classytic/revenue/schemas';
-
-// Merge library categories with your own
-const MY_CATEGORIES = {
-  ...LIBRARY_CATEGORIES,  // subscription, purchase
-  SALARY: 'salary',
-  RENT: 'rent',
-  EQUIPMENT: 'equipment',
-  // Add as many as you need
-};
-
-const transactionSchema = new mongoose.Schema({
-  // Required by library
-  organizationId: { type: String, required: true, index: true },
-  amount: { type: Number, required: true, min: 0 },
-  status: { type: String, enum: TRANSACTION_STATUS_VALUES, required: true },
-  category: { type: String, enum: Object.values(MY_CATEGORIES), required: true },
-
-  // Spread library schemas
-  gateway: gatewaySchema,
-  currentPayment: currentPaymentSchema,
-  paymentDetails: paymentDetailsSchema,
-
-  // Add your fields
-  notes: String,
-  invoiceNumber: String,
-}, { timestamps: true });
-
-export default mongoose.model('Transaction', transactionSchema);
-```
-
-**See [`examples/transaction.model.js`](examples/transaction.model.js) for complete example with indexes.**
-
-## Quick Start
-
-### Minimal Setup (3 lines)
+## Quick Start (30 seconds)
 
 ```javascript
 import { createRevenue } from '@classytic/revenue';
+import { ManualProvider } from '@classytic/revenue-manual';
 import Transaction from './models/Transaction.js';
 
-// Works out-of-box with built-in manual provider
+// 1. Configure
 const revenue = createRevenue({
   models: { Transaction },
+  providers: { manual: new ManualProvider() },
 });
 
-// Create a subscription
+// 2. Create subscription
 const { subscription, transaction } = await revenue.subscriptions.create({
   data: { organizationId, customerId },
   planKey: 'monthly',
-  amount: 99.99,
+  amount: 1500,
+  gateway: 'manual',
+  paymentData: { method: 'bkash', walletNumber: '01712345678' },
 });
+
+// 3. Verify payment
+await revenue.payments.verify(transaction.gateway.paymentIntentId);
+
+// 4. Refund if needed
+await revenue.payments.refund(transaction._id, 500, { reason: 'Partial refund' });
 ```
 
-That's it! The package works immediately with sensible defaults.
+**That's it!** Working revenue system in 3 steps.
 
-## Usage Examples
+## Transaction Model Setup
 
-### With Payment Provider
+The library requires a Transaction model with specific fields and provides reusable schemas:
 
 ```javascript
-import { createRevenue } from '@classytic/revenue';
-// Future: import { stripe } from '@classytic/revenue-stripe';
+import mongoose from 'mongoose';
+import {
+  TRANSACTION_TYPE_VALUES,
+  TRANSACTION_STATUS_VALUES,
+} from '@classytic/revenue/enums';
+import {
+  gatewaySchema,
+  paymentDetailsSchema,
+} from '@classytic/revenue/schemas';
 
-const revenue = createRevenue({
-  models: { Transaction },
-  providers: {
-    // Built-in manual provider is auto-included
-    // stripe: stripe({ apiKey: process.env.STRIPE_KEY }),
-  },
-});
+const transactionSchema = new mongoose.Schema({
+  // ============ REQUIRED BY LIBRARY ============
+  organizationId: { type: String, required: true, index: true },
+  amount: { type: Number, required: true, min: 0 },
+  type: { type: String, enum: TRANSACTION_TYPE_VALUES, required: true },  // 'income' | 'expense'
+  method: { type: String, required: true },  // 'manual' | 'bkash' | 'card' | etc.
+  status: { type: String, enum: TRANSACTION_STATUS_VALUES, required: true },
+  category: { type: String, required: true },  // Your custom categories
+
+  // ============ LIBRARY SCHEMAS (nested) ============
+  gateway: gatewaySchema,              // Payment gateway details
+  paymentDetails: paymentDetailsSchema, // Payment info (wallet, bank, etc.)
+
+  // ============ YOUR CUSTOM FIELDS ============
+  customerId: String,
+  currency: { type: String, default: 'BDT' },
+  verifiedAt: Date,
+  verifiedBy: mongoose.Schema.Types.ObjectId,
+  refundedAmount: Number,
+  idempotencyKey: { type: String, unique: true, sparse: true },
+  metadata: mongoose.Schema.Types.Mixed,
+}, { timestamps: true });
 
-// Create subscription with payment gateway
-await revenue.subscriptions.create({
-  data: { organizationId, customerId },
-  planKey: 'monthly',
-  amount: 99.99,
-  gateway: 'stripe', // or 'manual'
-});
+export default mongoose.model('Transaction', transactionSchema);
 ```
 
-### With Hooks
+## Available Schemas
 
-```javascript
-const revenue = createRevenue({
-  models: { Transaction },
-  hooks: {
-    'payment.verified': async ({ transaction }) => {
-      console.log('Payment verified:', transaction._id);
-      // Send email, update analytics, etc.
-    },
-    'subscription.created': async ({ subscription, transaction }) => {
-      console.log('New subscription:', subscription._id);
-    },
-  },
-});
-```
+| Schema | Purpose | Key Fields |
+|--------|---------|------------|
+| `gatewaySchema` | Payment gateway integration | `type`, `paymentIntentId`, `sessionId` |
+| `paymentDetailsSchema` | Payment method info | `walletNumber`, `trxId`, `bankName` |
+| `commissionSchema` | Commission tracking | `rate`, `grossAmount`, `netAmount` |
+| `currentPaymentSchema` | Latest payment (for Order/Subscription models) | `transactionId`, `status`, `verifiedAt` |
+| `subscriptionInfoSchema` | Subscription details (for Order models) | `planKey`, `startDate`, `endDate` |
 
-### Custom Logger
+**Usage:** Import and use as nested objects (NOT spread):
 
 ```javascript
-import winston from 'winston';
+import { gatewaySchema } from '@classytic/revenue/schemas';
 
-const revenue = createRevenue({
-  models: { Transaction },
-  logger: winston.createLogger({ /* config */ }),
+const schema = new mongoose.Schema({
+  gateway: gatewaySchema,  // ✅ Correct - nested
+  // ...gatewaySchema,     // ❌ Wrong - don't spread
 });
 ```
 
 ## Core API
 
-### Services
-
-The `revenue` instance provides three focused services:
-
-#### Subscriptions
+### Subscriptions
 
 ```javascript
 // Create subscription
-const { subscription, transaction, paymentIntent } = await revenue.subscriptions.create({
-  data: { organizationId, customerId, ... },
-  planKey: 'monthly',
-  amount: 99.99,
-  currency: 'USD',
-  gateway: 'manual', // optional
-  metadata: { /* ... */ }, // optional
-});
+const { subscription, transaction, paymentIntent } = 
+  await revenue.subscriptions.create({
+    data: { organizationId, customerId },
+    planKey: 'monthly',
+    amount: 1500,
+    currency: 'BDT',
+    gateway: 'manual',
+    paymentData: { method: 'bkash', walletNumber: '01712345678' },
+  });
+
+// Verify and activate
+await revenue.payments.verify(transaction.gateway.paymentIntentId);
+await revenue.subscriptions.activate(subscription._id);
 
 // Renew subscription
-await revenue.subscriptions.renew(subscriptionId, { amount: 99.99 });
-
-// Activate subscription
-await revenue.subscriptions.activate(subscriptionId);
-
-// Cancel subscription
-await revenue.subscriptions.cancel(subscriptionId, { immediate: true });
+await revenue.subscriptions.renew(subscription._id, {
+  gateway: 'manual',
+  paymentData: { method: 'nagad' },
+});
 
 // Pause/Resume
-await revenue.subscriptions.pause(subscriptionId);
-await revenue.subscriptions.resume(subscriptionId);
+await revenue.subscriptions.pause(subscription._id, { reason: 'Customer request' });
+await revenue.subscriptions.resume(subscription._id, { extendPeriod: true });
 
-// Get/List
-await revenue.subscriptions.get(subscriptionId);
-await revenue.subscriptions.list(filters, options);
+// Cancel
+await revenue.subscriptions.cancel(subscription._id, { immediate: true });
 ```
 
-#### Payments
+### Payments
 
 ```javascript
-// Verify payment
-const { transaction, paymentResult, status } = await revenue.payments.verify(
-  paymentIntentId,
-  { verifiedBy: userId }
-);
+// Verify payment (admin approval for manual)
+const { transaction } = await revenue.payments.verify(paymentIntentId, {
+  verifiedBy: adminUserId,
+});
 
 // Get payment status
-const { transaction, status, provider } = await revenue.payments.getStatus(paymentIntentId);
+const { status } = await revenue.payments.getStatus(paymentIntentId);
 
-// Refund payment
-const { transaction, refundResult } = await revenue.payments.refund(
-  paymentId,
-  amount, // optional, defaults to full refund
-  { reason: 'Customer request' }
+// Refund (creates separate EXPENSE transaction)
+const { transaction, refundTransaction } = await revenue.payments.refund(
+  transactionId,
+  500,  // Amount or null for full refund
+  { reason: 'Customer requested' }
 );
 
-// Handle webhook
-const { event, transaction, status } = await revenue.payments.handleWebhook(
+// Handle webhook (for automated providers like Stripe)
+const { event, transaction } = await revenue.payments.handleWebhook(
   'stripe',
-  payload,
+  webhookPayload,
   headers
 );
 ```
 
-#### Transactions
+### Transactions
 
 ```javascript
-// Get transaction
+// Get transaction by ID
 const transaction = await revenue.transactions.get(transactionId);
 
-// List transactions
-const { transactions, total, page, limit, pages } = await revenue.transactions.list(
-  { organizationId, status: 'verified' },
-  { limit: 50, skip: 0, sort: { createdAt: -1 } }
+// List with filters
+const { transactions, total } = await revenue.transactions.list(
+  { type: 'income', status: 'verified' },
+  { limit: 50, sort: { createdAt: -1 } }
 );
 
-// Update transaction
-await revenue.transactions.update(transactionId, { notes: 'Updated' });
+// Calculate net revenue
+const income = await revenue.transactions.list({ type: 'income' });
+const expense = await revenue.transactions.list({ type: 'expense' });
+const netRevenue = income.total - expense.total;
 ```
 
-**Note**: For analytics, exports, or complex queries, use Mongoose aggregations directly on your Transaction model. This keeps the service thin and focused.
+## Transaction Types (Income vs Expense)
 
-### Providers
+The library uses **double-entry accounting**:
 
-```javascript
-// Get specific provider
-const stripeProvider = revenue.getProvider('stripe');
-
-// Check capabilities
-const capabilities = stripeProvider.getCapabilities();
-// {
-//   supportsWebhooks: true,
-//   supportsRefunds: true,
-//   supportsPartialRefunds: true,
-//   requiresManualVerification: false
-// }
-```
-
-## Error Handling
-
-All errors are typed with codes for easy handling:
+- **INCOME** (`'income'`): Money coming in - payments, subscriptions
+- **EXPENSE** (`'expense'`): Money going out - refunds, payouts
 
 ```javascript
-import {
-  TransactionNotFoundError,
-  ProviderNotFoundError,
-  RefundNotSupportedError
-} from '@classytic/revenue';
+const revenue = createRevenue({
+  models: { Transaction },
+  config: {
+    transactionTypeMapping: {
+      subscription: 'income',
+      purchase: 'income',
+      refund: 'expense',  // Refunds create separate expense transactions
+    },
+  },
+});
+```
 
-try {
-  await revenue.payments.verify(intentId);
-} catch (error) {
-  if (error instanceof TransactionNotFoundError) {
-    console.log('Transaction not found:', error.metadata.transactionId);
-  }
+**Refund Pattern:**
+- Refund creates NEW transaction with `type: 'expense'`
+- Original transaction status becomes `'refunded'` or `'partially_refunded'`
+- Both linked via metadata for audit trail
+- Calculate net: `SUM(income) - SUM(expense)`
 
-  if (error.code === 'TRANSACTION_NOT_FOUND') {
-    // Handle specific error
-  }
+## Custom Categories
 
-  if (error.retryable) {
-    // Retry the operation
-  }
-}
-```
-
-### Error Classes
-
-- `RevenueError` - Base error class
-- `ConfigurationError` - Configuration issues
-- `ModelNotRegisteredError` - Model not provided
-- `ProviderError` - Provider-related errors
-- `ProviderNotFoundError` - Provider doesn't exist
-- `PaymentIntentCreationError` - Failed to create payment intent
-- `PaymentVerificationError` - Verification failed
-- `NotFoundError` - Resource not found
-- `TransactionNotFoundError` - Transaction not found
-- `SubscriptionNotFoundError` - Subscription not found
-- `ValidationError` - Validation failed
-- `InvalidAmountError` - Invalid amount
-- `MissingRequiredFieldError` - Required field missing
-- `StateError` - Invalid state
-- `AlreadyVerifiedError` - Already verified
-- `InvalidStateTransitionError` - Invalid state change
-- `RefundNotSupportedError` - Provider doesn't support refunds
-- `RefundError` - Refund failed
-
-## Enums & Schemas
+Map logical entities to transaction categories:
 
 ```javascript
-import {
-  TRANSACTION_STATUS,
-  PAYMENT_GATEWAY_TYPE,
-  SUBSCRIPTION_STATUS,
-  PLAN_KEYS,
-  currentPaymentSchema,
-  subscriptionInfoSchema,
-} from '@classytic/revenue';
+const revenue = createRevenue({
+  models: { Transaction },
+  config: {
+    categoryMappings: {
+      Order: 'order_subscription',
+      PlatformSubscription: 'platform_subscription',
+      Membership: 'gym_membership',
+      Enrollment: 'course_enrollment',
+    },
+  },
+});
 
-// Use in your models
-const organizationSchema = new Schema({
-  currentPayment: currentPaymentSchema,
-  subscription: subscriptionInfoSchema,
+// Usage
+await revenue.subscriptions.create({
+  entity: 'Order',  // Maps to 'order_subscription' category
+  monetizationType: 'subscription',
+  // ...
 });
 ```
 
-## TypeScript
+**Note:** `entity` is a logical identifier (not a database model name) for organizing your business logic.
 
-Full TypeScript support included:
-
-```typescript
-import { createRevenue, Revenue, RevenueOptions } from '@classytic/revenue';
+## Hooks
 
-const options: RevenueOptions = {
-  models: { Transaction: TransactionModel },
-};
-
-const revenue: Revenue = createRevenue(options);
+```javascript
+const revenue = createRevenue({
+  models: { Transaction },
+  hooks: {
+    'subscription.created': async ({ subscription, transaction }) => {
+      console.log('New subscription:', subscription._id);
+    },
+    'payment.verified': async ({ transaction }) => {
+      // Send confirmation email
+    },
+    'payment.refunded': async ({ refundTransaction }) => {
+      // Process refund notification
+    },
+  },
+});
 ```
 
-## Advanced Usage
+**Available hooks:**
+- `subscription.created`, `subscription.activated`, `subscription.renewed`
+- `subscription.paused`, `subscription.resumed`, `subscription.cancelled`
+- `payment.verified`, `payment.refunded`
+- `payment.webhook.{type}` (for webhook events)
+
+## Building Payment Providers
 
-### Custom Providers
+Create custom providers for Stripe, PayPal, etc.:
 
 ```javascript
-import { PaymentProvider } from '@classytic/revenue';
+import { PaymentProvider, PaymentIntent, PaymentResult } from '@classytic/revenue';
 
-class MyCustomProvider extends PaymentProvider {
-  name = 'my-gateway';
+export class StripeProvider extends PaymentProvider {
+  constructor(config) {
+    super(config);
+    this.name = 'stripe';
+    this.stripe = new Stripe(config.apiKey);
+  }
 
   async createIntent(params) {
-    // Implementation
+    const intent = await this.stripe.paymentIntents.create({
+      amount: params.amount,
+      currency: params.currency,
+    });
+
+    return new PaymentIntent({
+      id: intent.id,
+      provider: 'stripe',
+      status: intent.status,
+      amount: intent.amount,
+      currency: intent.currency,
+      clientSecret: intent.client_secret,
+      raw: intent,
+    });
   }
 
   async verifyPayment(intentId) {
-    // Implementation
+    const intent = await this.stripe.paymentIntents.retrieve(intentId);
+    return new PaymentResult({
+      id: intent.id,
+      provider: 'stripe',
+      status: intent.status === 'succeeded' ? 'succeeded' : 'failed',
+      paidAt: new Date(),
+      raw: intent,
+    });
   }
 
-  getCapabilities() {
-    return {
-      supportsWebhooks: true,
-      supportsRefunds: true,
-      supportsPartialRefunds: false,
-      requiresManualVerification: false,
-    };
-  }
+  // Implement: getStatus(), refund(), handleWebhook()
 }
-
-const revenue = createRevenue({
-  models: { Transaction },
-  providers: {
-    'my-gateway': new MyCustomProvider(),
-  },
-});
-```
-
-### DI Container Access
-
-```javascript
-const revenue = createRevenue({ models: { Transaction } });
-
-// Access container
-const models = revenue.container.get('models');
-const providers = revenue.container.get('providers');
 ```
 
-## Hook Events
+**See:** [`docs/guides/PROVIDER_GUIDE.md`](../docs/guides/PROVIDER_GUIDE.md) for complete guide.
 
-Available hook events:
+## TypeScript
 
-- `payment.verified` - Payment verified
-- `payment.failed` - Payment failed
-- `subscription.created` - Subscription created
-- `subscription.renewed` - Subscription renewed
-- `subscription.activated` - Subscription activated
-- `subscription.cancelled` - Subscription cancelled
-- `subscription.paused` - Subscription paused
-- `subscription.resumed` - Subscription resumed
-- `transaction.created` - Transaction created
-- `transaction.updated` - Transaction updated
+Full TypeScript support included:
 
-Hooks are fire-and-forget - they never break the main flow. Errors are logged but don't throw.
+```typescript
+import { createRevenue, Revenue, PaymentService } from '@classytic/revenue';
+import { TRANSACTION_TYPE, TRANSACTION_STATUS } from '@classytic/revenue/enums';
 
-## Architecture
+const revenue: Revenue = createRevenue({
+  models: { Transaction },
+});
 
+// All services are fully typed
+const payment = await revenue.payments.verify(id);
+const subscription = await revenue.subscriptions.create({ ... });
 ```
-@classytic/revenue (core package)
-├── Builder (createRevenue)
-├── DI Container
-├── Services (focused on lifecycle)
-│   ├── SubscriptionService
-│   ├── PaymentService
-│   └── TransactionService
-├── Providers
-│   ├── base.js (interface)
-│   └── manual.js (built-in)
-├── Error classes
-└── Schemas & Enums
-
-@classytic/revenue-stripe (future)
-@classytic/revenue-sslcommerz (future)
-@classytic/revenue-fastify (framework adapter, future)
-```
-
-## Design Principles
 
-- **KISS**: Keep It Simple, Stupid
-- **DRY**: Don't Repeat Yourself
-- **SOLID**: Single responsibility, focused services
-- **Immutable**: Revenue instance is deeply frozen
-- **Thin Core**: Core operations only, users extend as needed
-- **Smart Defaults**: Works out-of-box with minimal config
+## Examples
 
-## Migration from Legacy API
+- [`examples/basic-usage.js`](examples/basic-usage.js) - Quick start guide
+- [`examples/transaction.model.js`](examples/transaction.model.js) - Complete model setup
+- [`examples/transaction-type-mapping.js`](examples/transaction-type-mapping.js) - Income/expense configuration
+- [`examples/complete-flow.js`](examples/complete-flow.js) - Full lifecycle with state management
+- [`examples/multivendor-platform.js`](examples/multivendor-platform.js) - Multi-tenant setup
 
-If you're using the old `initializeRevenue()` API:
+## Error Handling
 
 ```javascript
-// ❌ Old (legacy API - removed)
-import { initializeRevenue, monetization, payment } from '@classytic/revenue';
-initializeRevenue({ TransactionModel, transactionService });
-await monetization.createSubscription(params);
+import { 
+  TransactionNotFoundError,
+  ProviderNotFoundError,
+  AlreadyVerifiedError,
+  RefundError,
+} from '@classytic/revenue';
 
-// ✅ New (DI-based API)
-import { createRevenue } from '@classytic/revenue';
-const revenue = createRevenue({ models: { Transaction } });
-await revenue.subscriptions.create(params);
+try {
+  await revenue.payments.verify(id);
+} catch (error) {
+  if (error instanceof AlreadyVerifiedError) {
+    console.log('Already verified');
+  } else if (error instanceof TransactionNotFoundError) {
+    console.log('Transaction not found');
+  }
+}
 ```
 
 ## Documentation
 
-- **[Building Payment Providers](../docs/guides/PROVIDER_GUIDE.md)** - Create custom payment integrations
-- **[Examples](../docs/examples/)** - Complete usage examples
-- **[Full Documentation](../docs/README.md)** - Comprehensive guides
+- **[Provider Guide](../docs/guides/PROVIDER_GUIDE.md)** - Build custom payment providers
+- **[Architecture](../docs/README.md#architecture)** - System design and patterns
+- **[API Reference](../docs/README.md)** - Complete API documentation
 
 ## Support
 
-- **GitHub**: https://github.com/classytic/revenue
-- **Issues**: https://github.com/classytic/revenue/issues
-- **npm**: https://npmjs.com/package/@classytic/revenue
+- **GitHub**: [classytic/revenue](https://github.com/classytic/revenue)
+- **Issues**: [Report bugs](https://github.com/classytic/revenue/issues)
+- **NPM**: [@classytic/revenue](https://www.npmjs.com/package/@classytic/revenue)
 
 ## License
 
-MIT © Classytic (Classytic)
-
----
-
-**Built with ❤️ following SOLID principles and industry best practices**
+MIT © [Classytic](https://github.com/classytic)