@classytic/revenue 0.0.21 → 0.0.22

package/README.md

@@ -6,637 +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
 ```
 
-## Core Concepts
+## Quick Start (30 seconds)
 
-### Monetization Types (Strict)
-The library supports **3 monetization types** (strict):
-- **FREE**: No payment required
-- **SUBSCRIPTION**: Recurring payments
-- **PURCHASE**: One-time payments
-
-### Transaction Categories (Flexible)
-You can use **custom category names** for your business logic while using the strict monetization types:
-- `'order_subscription'` for subscription orders
-- `'gym_membership'` for gym memberships
-- `'course_enrollment'` for course enrollments
-- Or any custom names you need
-
-### How It Works
 ```javascript
+import { createRevenue } from '@classytic/revenue';
+import { ManualProvider } from '@classytic/revenue-manual';
+import Transaction from './models/Transaction.js';
+
+// 1. Configure
 const revenue = createRevenue({
   models: { Transaction },
-  config: {
-    categoryMappings: {
-      Order: 'order_subscription',              // Customer orders
-      PlatformSubscription: 'platform_subscription',  // Tenant/org subscriptions
-      Membership: 'gym_membership',              // User memberships
-      Enrollment: 'course_enrollment',           // Course enrollments
-    }
-  }
+  providers: { manual: new ManualProvider() },
 });
 
-// All these use SUBSCRIPTION monetization type but different categories
-await revenue.subscriptions.create({
-  entity: 'Order',                // Logical identifier → maps to 'order_subscription'
-  monetizationType: 'subscription',
-  // ...
+// 2. Create subscription
+const { subscription, transaction } = await revenue.subscriptions.create({
+  data: { organizationId, customerId },
+  planKey: 'monthly',
+  amount: 1500,
+  gateway: 'manual',
+  paymentData: { method: 'bkash', walletNumber: '01712345678' },
 });
 
-await revenue.subscriptions.create({
-  entity: 'PlatformSubscription',  // Logical identifier → maps to 'platform_subscription'
-  monetizationType: 'subscription',
-  // ...
-});
+// 3. Verify payment
+await revenue.payments.verify(transaction.gateway.paymentIntentId);
+
+// 4. Refund if needed
+await revenue.payments.refund(transaction._id, 500, { reason: 'Partial refund' });
 ```
 
-**Note:** `entity` is NOT a database model name - it's just a logical identifier you choose to organize your business logic.
+**That's it!** Working revenue system in 3 steps.
 
 ## Transaction Model Setup
 
-Spread library enums/schemas into your Transaction model:
+The library requires a Transaction model with specific fields and provides reusable schemas:
 
 ```javascript
 import mongoose from 'mongoose';
 import {
+  TRANSACTION_TYPE_VALUES,
   TRANSACTION_STATUS_VALUES,
-  LIBRARY_CATEGORIES,
 } from '@classytic/revenue/enums';
 import {
   gatewaySchema,
-  currentPaymentSchema,
   paymentDetailsSchema,
 } from '@classytic/revenue/schemas';
 
-// Merge library categories with your custom ones
-const MY_CATEGORIES = {
-  ...LIBRARY_CATEGORIES,           // subscription, purchase (library defaults)
-  ORDER_SUBSCRIPTION: 'order_subscription',
-  ORDER_PURCHASE: 'order_purchase',
-  GYM_MEMBERSHIP: 'gym_membership',
-  COURSE_ENROLLMENT: 'course_enrollment',
-  SALARY: 'salary',
-  RENT: 'rent',
-  EQUIPMENT: 'equipment',
-  // Add as many as you need
-};
-
 const transactionSchema = new mongoose.Schema({
-  // Required by library
+  // ============ 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, enum: Object.values(MY_CATEGORIES), required: true },
-
-  // Spread library schemas
-  gateway: gatewaySchema,
-  currentPayment: currentPaymentSchema,
-  paymentDetails: paymentDetailsSchema,
-
-  // Add your fields
-  notes: String,
-  invoiceNumber: String,
+  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 });
 
 export default mongoose.model('Transaction', transactionSchema);
 ```
 
-**See [`examples/transaction.model.js`](examples/transaction.model.js) for complete example with indexes.**
+## Available Schemas
 
-## Quick Start
+| 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` |
 
-### Minimal Setup (3 lines)
+**Usage:** Import and use as nested objects (NOT spread):
 
 ```javascript
-import { createRevenue } from '@classytic/revenue';
-import Transaction from './models/Transaction.js';
-
-// Works out-of-box with built-in manual provider
-const revenue = createRevenue({
-  models: { Transaction },
-});
+import { gatewaySchema } from '@classytic/revenue/schemas';
 
-// Create a subscription
-const { subscription, transaction } = await revenue.subscriptions.create({
-  data: { organizationId, customerId },
-  planKey: 'monthly',
-  amount: 99.99,
+const schema = new mongoose.Schema({
+  gateway: gatewaySchema,  // ✅ Correct - nested
+  // ...gatewaySchema,     // ❌ Wrong - don't spread
 });
 ```
 
-That's it! The package works immediately with sensible defaults.
-
-## Real-World Use Cases
+## Core API
 
-### E-commerce Platform with Multiple Order Types
+### Subscriptions
 
 ```javascript
-// Setup
-const revenue = createRevenue({
-  models: { Transaction },
-  config: {
-    categoryMappings: {
-      Order: 'order_subscription',      // Recurring orders (meal kits, subscriptions)
-      Purchase: 'order_purchase',        // One-time orders
-    }
-  }
-});
+// Create subscription
+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);
 
-// Subscription order (meal kit subscription)
-const { subscription, transaction } = await revenue.subscriptions.create({
-  data: { organizationId, customerId },
-  entity: 'Order',                    // Logical identifier
-  monetizationType: 'subscription',    // STRICT: Must be subscription/purchase/free
-  planKey: 'monthly',
-  amount: 49.99,
-  metadata: { productType: 'meal_kit' }
+// Renew subscription
+await revenue.subscriptions.renew(subscription._id, {
+  gateway: 'manual',
+  paymentData: { method: 'nagad' },
 });
-// Transaction created with category: 'order_subscription'
 
-// One-time purchase order
-const { transaction } = await revenue.subscriptions.create({
-  data: { organizationId, customerId },
-  entity: 'Purchase',                 // Logical identifier
-  monetizationType: 'purchase',
-  amount: 99.99,
-  metadata: { productType: 'electronics' }
-});
-// Transaction created with category: 'order_purchase'
+// Pause/Resume
+await revenue.subscriptions.pause(subscription._id, { reason: 'Customer request' });
+await revenue.subscriptions.resume(subscription._id, { extendPeriod: true });
+
+// Cancel
+await revenue.subscriptions.cancel(subscription._id, { immediate: true });
 ```
 
-### Gym Management System
+### Payments
 
 ```javascript
-// Setup
-const revenue = createRevenue({
-  models: { Transaction },
-  config: {
-    categoryMappings: {
-      Membership: 'gym_membership',
-      PersonalTraining: 'personal_training',
-      DayPass: 'day_pass',
-    }
-  }
+// Verify payment (admin approval for manual)
+const { transaction } = await revenue.payments.verify(paymentIntentId, {
+  verifiedBy: adminUserId,
 });
 
-// Monthly gym membership
-await revenue.subscriptions.create({
-  entity: 'Membership',
-  monetizationType: 'subscription',
-  planKey: 'monthly',
-  amount: 59.99,
-});
-// Transaction: 'gym_membership'
+// Get payment status
+const { status } = await revenue.payments.getStatus(paymentIntentId);
 
-// Personal training package (one-time purchase)
-await revenue.subscriptions.create({
-  entity: 'PersonalTraining',
-  monetizationType: 'purchase',
-  amount: 299.99,
-});
-// Transaction: 'personal_training'
+// Refund (creates separate EXPENSE transaction)
+const { transaction, refundTransaction } = await revenue.payments.refund(
+  transactionId,
+  500,  // Amount or null for full refund
+  { reason: 'Customer requested' }
+);
 
-// Day pass (free trial)
-await revenue.subscriptions.create({
-  entity: 'DayPass',
-  monetizationType: 'free',
-  amount: 0,
-});
-// No transaction created for free
+// Handle webhook (for automated providers like Stripe)
+const { event, transaction } = await revenue.payments.handleWebhook(
+  'stripe',
+  webhookPayload,
+  headers
+);
 ```
 
-### Online Learning Platform
+### Transactions
 
 ```javascript
-// Setup
-const revenue = createRevenue({
-  models: { Transaction },
-  config: {
-    categoryMappings: {
-      CourseEnrollment: 'course_enrollment',
-      MembershipPlan: 'membership_plan',
-    }
-  }
-});
+// Get transaction by ID
+const transaction = await revenue.transactions.get(transactionId);
 
-// One-time course purchase
-await revenue.subscriptions.create({
-  entity: 'CourseEnrollment',
-  monetizationType: 'purchase',
-  amount: 99.00,
-  metadata: { courseId: 'react-advanced' }
-});
-// Transaction: 'course_enrollment'
+// List with filters
+const { transactions, total } = await revenue.transactions.list(
+  { type: 'income', status: 'verified' },
+  { limit: 50, sort: { createdAt: -1 } }
+);
 
-// Monthly all-access membership
-await revenue.subscriptions.create({
-  entity: 'MembershipPlan',
-  monetizationType: 'subscription',
-  planKey: 'monthly',
-  amount: 29.99,
-});
-// Transaction: 'membership_plan'
+// 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;
 ```
 
-### Without Category Mappings (Defaults)
+## Transaction Types (Income vs Expense)
+
+The library uses **double-entry accounting**:
+
+- **INCOME** (`'income'`): Money coming in - payments, subscriptions
+- **EXPENSE** (`'expense'`): Money going out - refunds, payouts
 
 ```javascript
-// No mappings defined - uses library defaults
 const revenue = createRevenue({
   models: { Transaction },
   config: {
-    categoryMappings: {}  // Empty or omit this
-  }
-});
-
-// All subscriptions use default 'subscription' category
-await revenue.subscriptions.create({
-  monetizationType: 'subscription',
-  planKey: 'monthly',
-  amount: 49.99,
-});
-// Transaction created with category: 'subscription' (library default)
-
-// All purchases use default 'purchase' category
-await revenue.subscriptions.create({
-  monetizationType: 'purchase',
-  amount: 99.99,
+    transactionTypeMapping: {
+      subscription: 'income',
+      purchase: 'income',
+      refund: 'expense',  // Refunds create separate expense transactions
+    },
+  },
 });
-// Transaction created with category: 'purchase' (library default)
 ```
 
-## Usage Examples
+**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)`
 
-### With Payment Provider
+## Custom Categories
 
-```javascript
-import { createRevenue } from '@classytic/revenue';
-// Future: import { stripe } from '@classytic/revenue-stripe';
+Map logical entities to transaction categories:
 
+```javascript
 const revenue = createRevenue({
   models: { Transaction },
-  providers: {
-    // Built-in manual provider is auto-included
-    // stripe: stripe({ apiKey: process.env.STRIPE_KEY }),
+  config: {
+    categoryMappings: {
+      Order: 'order_subscription',
+      PlatformSubscription: 'platform_subscription',
+      Membership: 'gym_membership',
+      Enrollment: 'course_enrollment',
+    },
   },
 });
 
-// Create subscription with payment gateway
+// Usage
 await revenue.subscriptions.create({
-  data: { organizationId, customerId },
-  planKey: 'monthly',
-  amount: 99.99,
-  gateway: 'stripe', // or 'manual'
+  entity: 'Order',  // Maps to 'order_subscription' category
+  monetizationType: 'subscription',
+  // ...
 });
 ```
 
-### With Hooks
+**Note:** `entity` is a logical identifier (not a database model name) for organizing your business logic.
+
+## Hooks
 
 ```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);
     },
+    'payment.verified': async ({ transaction }) => {
+      // Send confirmation email
+    },
+    'payment.refunded': async ({ refundTransaction }) => {
+      // Process refund notification
+    },
   },
 });
 ```
 
-### Custom Logger
+**Available hooks:**
+- `subscription.created`, `subscription.activated`, `subscription.renewed`
+- `subscription.paused`, `subscription.resumed`, `subscription.cancelled`
+- `payment.verified`, `payment.refunded`
+- `payment.webhook.{type}` (for webhook events)
 
-```javascript
-import winston from 'winston';
-
-const revenue = createRevenue({
-  models: { Transaction },
-  logger: winston.createLogger({ /* config */ }),
-});
-```
-
-## Core API
-
-### Services
-
-The `revenue` instance provides three focused services:
-
-#### 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
-});
-
-// 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 });
-
-// Pause/Resume
-await revenue.subscriptions.pause(subscriptionId);
-await revenue.subscriptions.resume(subscriptionId);
-
-// Get/List
-await revenue.subscriptions.get(subscriptionId);
-await revenue.subscriptions.list(filters, options);
-```
-
-#### Payments
-
-```javascript
-// Verify payment
-const { transaction, paymentResult, status } = await revenue.payments.verify(
-  paymentIntentId,
-  { verifiedBy: userId }
-);
+## Building Payment Providers
 
-// Get payment status
-const { transaction, status, provider } = await revenue.payments.getStatus(paymentIntentId);
-
-// Refund payment
-const { transaction, refundResult } = await revenue.payments.refund(
-  paymentId,
-  amount, // optional, defaults to full refund
-  { reason: 'Customer request' }
-);
-
-// Handle webhook
-const { event, transaction, status } = await revenue.payments.handleWebhook(
-  'stripe',
-  payload,
-  headers
-);
-```
-
-#### Transactions
-
-```javascript
-// Get transaction
-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 } }
-);
-
-// Update transaction
-await revenue.transactions.update(transactionId, { notes: 'Updated' });
-```
-
-**Note**: For analytics, exports, or complex queries, use Mongoose aggregations directly on your Transaction model. This keeps the service thin and focused.
-
-### Providers
-
-```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:
+Create custom providers for Stripe, PayPal, etc.:
 
 ```javascript
-import {
-  TransactionNotFoundError,
-  ProviderNotFoundError,
-  RefundNotSupportedError
-} from '@classytic/revenue';
+import { PaymentProvider, PaymentIntent, PaymentResult } from '@classytic/revenue';
 
-try {
-  await revenue.payments.verify(intentId);
-} catch (error) {
-  if (error instanceof TransactionNotFoundError) {
-    console.log('Transaction not found:', error.metadata.transactionId);
+export class StripeProvider extends PaymentProvider {
+  constructor(config) {
+    super(config);
+    this.name = 'stripe';
+    this.stripe = new Stripe(config.apiKey);
   }
 
-  if (error.code === 'TRANSACTION_NOT_FOUND') {
-    // Handle specific error
+  async createIntent(params) {
+    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,
+    });
   }
 
-  if (error.retryable) {
-    // Retry the operation
+  async verifyPayment(intentId) {
+    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,
+    });
   }
+
+  // Implement: getStatus(), refund(), handleWebhook()
 }
 ```
 
-### 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
-
-```javascript
-import {
-  TRANSACTION_STATUS,
-  PAYMENT_GATEWAY_TYPE,
-  SUBSCRIPTION_STATUS,
-  PLAN_KEYS,
-  currentPaymentSchema,
-  subscriptionInfoSchema,
-} from '@classytic/revenue';
-
-// Use in your models
-const organizationSchema = new Schema({
-  currentPayment: currentPaymentSchema,
-  subscription: subscriptionInfoSchema,
-});
-```
+**See:** [`docs/guides/PROVIDER_GUIDE.md`](../docs/guides/PROVIDER_GUIDE.md) for complete guide.
 
 ## TypeScript
 
 Full TypeScript support included:
 
 ```typescript
-import { createRevenue, Revenue, RevenueOptions } from '@classytic/revenue';
-
-const options: RevenueOptions = {
-  models: { Transaction: TransactionModel },
-};
-
-const revenue: Revenue = createRevenue(options);
-```
-
-## Advanced Usage
-
-### Custom Providers
-
-```javascript
-import { PaymentProvider } from '@classytic/revenue';
-
-class MyCustomProvider extends PaymentProvider {
-  name = 'my-gateway';
-
-  async createIntent(params) {
-    // Implementation
-  }
+import { createRevenue, Revenue, PaymentService } from '@classytic/revenue';
+import { TRANSACTION_TYPE, TRANSACTION_STATUS } from '@classytic/revenue/enums';
 
-  async verifyPayment(intentId) {
-    // Implementation
-  }
-
-  getCapabilities() {
-    return {
-      supportsWebhooks: true,
-      supportsRefunds: true,
-      supportsPartialRefunds: false,
-      requiresManualVerification: false,
-    };
-  }
-}
-
-const revenue = createRevenue({
+const revenue: 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');
+// All services are fully typed
+const payment = await revenue.payments.verify(id);
+const subscription = await revenue.subscriptions.create({ ... });
 ```
 
-## Hook Events
-
-Available hook events:
-
-- `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
-
-Hooks are fire-and-forget - they never break the main flow. Errors are logged but don't throw.
-
-## Architecture
-
-```
-@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)
-```
+## Examples
 
-## Design Principles
+- [`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
 
-- **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
-
-## Migration from Legacy API
-
-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)

package/enums/index.d.ts

@@ -5,6 +5,13 @@
 
 // ============ TRANSACTION ENUMS ============
 
+export const TRANSACTION_TYPE: {
+  readonly INCOME: 'income';
+  readonly EXPENSE: 'expense';
+};
+
+export const TRANSACTION_TYPE_VALUES: string[];
+
 export const TRANSACTION_STATUS: {
   readonly PENDING: 'pending';
   readonly PAYMENT_INITIATED: 'payment_initiated';
@@ -86,6 +93,8 @@ export const MONETIZATION_TYPE_VALUES: string[];
 // ============ DEFAULT EXPORT ============
 
 declare const _default: {
+  TRANSACTION_TYPE: typeof TRANSACTION_TYPE;
+  TRANSACTION_TYPE_VALUES: typeof TRANSACTION_TYPE_VALUES;
   TRANSACTION_STATUS: typeof TRANSACTION_STATUS;
   TRANSACTION_STATUS_VALUES: typeof TRANSACTION_STATUS_VALUES;
   LIBRARY_CATEGORIES: typeof LIBRARY_CATEGORIES;

package/enums/index.js

@@ -16,6 +16,8 @@ export * from './monetization.enums.js';
 
 // Default export for convenience
 import {
+  TRANSACTION_TYPE,
+  TRANSACTION_TYPE_VALUES,
   TRANSACTION_STATUS,
   TRANSACTION_STATUS_VALUES,
   LIBRARY_CATEGORIES,
@@ -45,6 +47,8 @@ import {
 
 export default {
   // Transaction enums
+  TRANSACTION_TYPE,
+  TRANSACTION_TYPE_VALUES,
   TRANSACTION_STATUS,
   TRANSACTION_STATUS_VALUES,
   LIBRARY_CATEGORIES,

package/enums/transaction.enums.js

@@ -6,6 +6,22 @@
  * Users should define their own categories and merge with these.
  */
 
+// ============ TRANSACTION TYPE ============
+/**
+ * Transaction Type - Income vs Expense
+ * 
+ * INCOME: Money coming in (payments, subscriptions, purchases)
+ * EXPENSE: Money going out (refunds, payouts)
+ * 
+ * Users can map these in their config via transactionTypeMapping
+ */
+export const TRANSACTION_TYPE = {
+  INCOME: 'income',
+  EXPENSE: 'expense',
+};
+
+export const TRANSACTION_TYPE_VALUES = Object.values(TRANSACTION_TYPE);
+
 // ============ TRANSACTION STATUS ============
 /**
  * Transaction Status - Library-managed states

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/revenue",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "description": "Enterprise revenue management system with subscriptions, purchases, proration, and payment processing",
   "main": "index.js",
   "types": "revenue.d.ts",

package/revenue.d.ts

@@ -132,7 +132,7 @@ export class PaymentService {
 
   verify(paymentIntentId: string, options?: { verifiedBy?: string }): Promise<{ transaction: any; paymentResult: PaymentResult; status: string }>;
   getStatus(paymentIntentId: string): Promise<{ transaction: any; paymentResult: PaymentResult; status: string; provider: string }>;
-  refund(paymentId: string, amount?: number, options?: { reason?: string }): Promise<{ transaction: any; refundResult: RefundResult; status: string }>;
+  refund(paymentId: string, amount?: number, options?: { reason?: string }): Promise<{ transaction: any; refundTransaction: any; refundResult: RefundResult; status: string }>;
   handleWebhook(providerName: string, payload: any, headers?: any): Promise<{ event: WebhookEvent; transaction: any; status: string }>;
   list(filters?: any, options?: any): Promise<any[]>;
   get(transactionId: string): Promise<any>;
@@ -219,6 +219,25 @@ export interface RevenueOptions {
      * If not specified, falls back to library defaults: 'subscription' or 'purchase'
      */
     categoryMappings?: Record<string, string>;
+    
+    /**
+     * Maps transaction types to income/expense for your accounting system
+     * 
+     * Allows you to control how different transaction types are recorded:
+     * - 'income': Money coming in (payments, subscriptions)
+     * - 'expense': Money going out (refunds)
+     * 
+     * @example
+     * transactionTypeMapping: {
+     *   subscription: 'income',
+     *   subscription_renewal: 'income',
+     *   purchase: 'income',
+     *   refund: 'expense',
+     * }
+     * 
+     * If not specified, library defaults to 'income' for all payment transactions
+     */
+    transactionTypeMapping?: Record<string, 'income' | 'expense'>;
     [key: string]: any;
   };
   logger?: Console | any;
@@ -228,6 +247,11 @@ export function createRevenue(options: RevenueOptions): Revenue;
 
 // ============ ENUMS ============
 
+export const TRANSACTION_TYPE: {
+  INCOME: 'income';
+  EXPENSE: 'expense';
+};
+
 export const TRANSACTION_STATUS: {
   PENDING: 'pending';
   PAYMENT_INITIATED: 'payment_initiated';

package/services/payment.service.js

@@ -16,6 +16,7 @@ import {
   ProviderCapabilityError,
 } from '../core/errors.js';
 import { triggerHook } from '../utils/hooks.js';
+import { TRANSACTION_TYPE } from '../enums/transaction.enums.js';
 
 /**
  * Payment Service
@@ -221,15 +222,43 @@ export class PaymentService {
       throw new RefundError(paymentId, error.message);
     }
 
-    // Update transaction
+    // Create separate refund transaction (EXPENSE) for proper accounting
+    const refundTransactionType = this.config.transactionTypeMapping?.refund || TRANSACTION_TYPE.EXPENSE;
+    
+    const refundTransaction = await TransactionModel.create({
+      organizationId: transaction.organizationId,
+      customerId: transaction.customerId,
+      amount: refundAmount,
+      currency: transaction.currency,
+      category: transaction.category,
+      type: refundTransactionType,  // EXPENSE - money going out
+      method: transaction.method || 'manual',
+      status: 'completed',
+      gateway: {
+        type: transaction.gateway?.type || 'manual',
+        paymentIntentId: refundResult.id,
+        provider: refundResult.provider,
+      },
+      paymentDetails: transaction.paymentDetails,
+      metadata: {
+        ...transaction.metadata,
+        isRefund: true,
+        originalTransactionId: transaction._id.toString(),
+        refundReason: reason,
+        refundResult: refundResult.metadata,
+      },
+      idempotencyKey: `refund_${transaction._id}_${Date.now()}`,
+    });
+
+    // Update original transaction status
     const isPartialRefund = refundAmount < transaction.amount;
     transaction.status = isPartialRefund ? 'partially_refunded' : 'refunded';
     transaction.refundedAmount = (transaction.refundedAmount || 0) + refundAmount;
     transaction.refundedAt = refundResult.refundedAt || new Date();
     transaction.metadata = {
       ...transaction.metadata,
+      refundTransactionId: refundTransaction._id.toString(),
       refundReason: reason,
-      refundResult: refundResult.metadata,
     };
 
     await transaction.save();
@@ -237,6 +266,7 @@ export class PaymentService {
     // Trigger hook
     this._triggerHook('payment.refunded', {
       transaction,
+      refundTransaction,
       refundResult,
       refundAmount,
       reason,
@@ -245,6 +275,7 @@ export class PaymentService {
 
     return {
       transaction,
+      refundTransaction,
       refundResult,
       status: transaction.status,
     };

package/services/subscription.service.js

@@ -15,10 +15,12 @@ import {
   ModelNotRegisteredError,
   SubscriptionNotActiveError,
   PaymentIntentCreationError,
+  InvalidStateTransitionError,
 } from '../core/errors.js';
 import { triggerHook } from '../utils/hooks.js';
 import { resolveCategory } from '../utils/category-resolver.js';
 import { MONETIZATION_TYPES } from '../enums/monetization.enums.js';
+import { TRANSACTION_TYPE } from '../enums/transaction.enums.js';
 
 /**
  * Subscription Service
@@ -109,6 +111,11 @@ export class SubscriptionService {
       // Resolve category based on entity and monetizationType
       const category = resolveCategory(entity, monetizationType, this.config.categoryMappings);
 
+      // Resolve transaction type using config mapping or default to 'income'
+      const transactionType = this.config.transactionTypeMapping?.subscription 
+        || this.config.transactionTypeMapping?.[monetizationType]
+        || TRANSACTION_TYPE.INCOME;
+
       // Create transaction record
       const TransactionModel = this.models.Transaction;
       transaction = await TransactionModel.create({
@@ -117,7 +124,8 @@ export class SubscriptionService {
         amount,
         currency,
         category,
-        type: 'credit',
+        type: transactionType,
+        method: paymentData?.method || 'manual',
         status: paymentIntent.status === 'succeeded' ? 'verified' : 'pending',
         gateway: {
           type: gateway,
@@ -285,6 +293,12 @@ export class SubscriptionService {
     const effectiveMonetizationType = subscription.metadata?.monetizationType || MONETIZATION_TYPES.SUBSCRIPTION;
     const category = resolveCategory(effectiveEntity, effectiveMonetizationType, this.config.categoryMappings);
 
+    // Resolve transaction type using config mapping or default to 'income'
+    const transactionType = this.config.transactionTypeMapping?.subscription_renewal
+      || this.config.transactionTypeMapping?.subscription
+      || this.config.transactionTypeMapping?.[effectiveMonetizationType]
+      || TRANSACTION_TYPE.INCOME;
+
     // Create transaction
     const TransactionModel = this.models.Transaction;
     const transaction = await TransactionModel.create({
@@ -293,7 +307,8 @@ export class SubscriptionService {
       amount: subscription.amount,
       currency: subscription.currency || 'BDT',
       category,
-      type: 'credit',
+      type: transactionType,
+      method: paymentData?.method || 'manual',
       status: paymentIntent.status === 'succeeded' ? 'verified' : 'pending',
       gateway: {
         type: gateway,