@classytic/revenue 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Classytic (Classytic)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,454 @@
+# @classytic/revenue
+
+> Enterprise revenue management with subscriptions and payment processing
+
+Thin, focused, production-ready library with smart defaults. Built for SaaS, marketplaces, and subscription businesses.
+
+## 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
+- **TypeScript Ready**: Full type definitions included
+- **Zero Dependencies**: Only requires `mongoose` as peer dependency
+
+## Installation
+
+```bash
+npm install @classytic/revenue
+```
+
+## 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)
+
+```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 },
+});
+
+// Create a subscription
+const { subscription, transaction } = await revenue.subscriptions.create({
+  data: { organizationId, customerId },
+  planKey: 'monthly',
+  amount: 99.99,
+});
+```
+
+That's it! The package works immediately with sensible defaults.
+
+## Usage Examples
+
+### With Payment Provider
+
+```javascript
+import { createRevenue } from '@classytic/revenue';
+// Future: import { stripe } from '@classytic/revenue-stripe';
+
+const revenue = createRevenue({
+  models: { Transaction },
+  providers: {
+    // Built-in manual provider is auto-included
+    // stripe: stripe({ apiKey: process.env.STRIPE_KEY }),
+  },
+});
+
+// Create subscription with payment gateway
+await revenue.subscriptions.create({
+  data: { organizationId, customerId },
+  planKey: 'monthly',
+  amount: 99.99,
+  gateway: 'stripe', // or 'manual'
+});
+```
+
+### With 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);
+    },
+  },
+});
+```
+
+### Custom Logger
+
+```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 }
+);
+
+// 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:
+
+```javascript
+import {
+  TransactionNotFoundError,
+  ProviderNotFoundError,
+  RefundNotSupportedError
+} from '@classytic/revenue';
+
+try {
+  await revenue.payments.verify(intentId);
+} catch (error) {
+  if (error instanceof TransactionNotFoundError) {
+    console.log('Transaction not found:', error.metadata.transactionId);
+  }
+
+  if (error.code === 'TRANSACTION_NOT_FOUND') {
+    // Handle specific error
+  }
+
+  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
+
+```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,
+});
+```
+
+## 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
+  }
+
+  async verifyPayment(intentId) {
+    // Implementation
+  }
+
+  getCapabilities() {
+    return {
+      supportsWebhooks: true,
+      supportsRefunds: true,
+      supportsPartialRefunds: false,
+      requiresManualVerification: false,
+    };
+  }
+}
+
+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
+
+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)
+```
+
+## 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
+
+## Migration from Legacy API
+
+If you're using the old `initializeRevenue()` API:
+
+```javascript
+// ❌ Old (legacy API - removed)
+import { initializeRevenue, monetization, payment } from '@classytic/revenue';
+initializeRevenue({ TransactionModel, transactionService });
+await monetization.createSubscription(params);
+
+// ✅ New (DI-based API)
+import { createRevenue } from '@classytic/revenue';
+const revenue = createRevenue({ models: { Transaction } });
+await revenue.subscriptions.create(params);
+```
+
+## 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
+
+## Support
+
+- **GitHub**: https://github.com/classytic/revenue
+- **Issues**: https://github.com/classytic/revenue/issues
+- **npm**: https://npmjs.com/package/@classytic/revenue
+
+## License
+
+MIT © Classytic (Classytic)
+
+---
+
+**Built with ❤️ following SOLID principles and industry best practices**

package/core/builder.js

@@ -0,0 +1,170 @@
+/**
+ * Revenue Builder - Main Entry Point
+ * @classytic/revenue
+ *
+ * Factory function to create revenue instance
+ * Inspired by: AI SDK, LangChain, Prisma Client
+ */
+
+import { Container } from './container.js';
+import { SubscriptionService } from '../services/subscription.service.js';
+import { PaymentService } from '../services/payment.service.js';
+import { TransactionService } from '../services/transaction.service.js';
+
+/**
+ * Create revenue instance with dependency injection
+ *
+ * @param {Object} options - Configuration options
+ * @param {Object} options.models - Mongoose models { Transaction, Subscription, etc. }
+ * @param {Object} options.providers - Payment providers { manual, stripe, etc. }
+ * @param {Object} options.hooks - Event hooks
+ * @param {Object} options.config - Additional configuration
+ * @param {Object} options.logger - Logger instance
+ * @returns {Revenue} Revenue instance
+ *
+ * @example
+ * ```javascript
+ * import { createRevenue, ManualProvider } from '@classytic/revenue';
+ *
+ * const revenue = createRevenue({
+ *   models: {
+ *     Transaction: TransactionModel,
+ *     Subscription: SubscriptionModel,
+ *   },
+ *   providers: {
+ *     manual: new ManualProvider(),
+ *   },
+ *   config: {
+ *     targetModels: ['Subscription', 'Membership'],
+ *     categoryMappings: {
+ *       Subscription: 'platform_subscription',
+ *       Membership: 'gym_membership',
+ *     },
+ *   },
+ * });
+ *
+ * // Use anywhere
+ * const subscription = await revenue.subscriptions.create({ ... });
+ * await revenue.payments.verify(txnId);
+ * ```
+ */
+export function createRevenue(options = {}) {
+  // Validate required options
+  if (!options.models || !options.models.Transaction) {
+    throw new Error('createRevenue(): options.models.Transaction is required');
+  }
+
+  // Create DI container
+  const container = new Container();
+
+  // Register models
+  container.singleton('models', options.models);
+
+  // Register providers
+  const providers = options.providers || {};
+  container.singleton('providers', providers);
+
+  // Register hooks
+  container.singleton('hooks', options.hooks || {});
+
+  // Register config
+  const config = {
+    targetModels: ['Subscription', 'Membership'],
+    categoryMappings: {},
+    ...options.config,
+  };
+  container.singleton('config', config);
+
+  // Register logger
+  container.singleton('logger', options.logger || console);
+
+  // Create service instances (lazy-loaded)
+  const services = {
+    subscriptions: null,
+    payments: null,
+    transactions: null,
+  };
+
+  // Create revenue instance
+  const revenue = {
+    /**
+     * Get container (for advanced usage)
+     */
+    container,
+
+    /**
+     * Registered payment providers
+     */
+    providers,
+
+    /**
+     * Configuration
+     */
+    config,
+
+    /**
+     * Subscription service
+     * Lazy-loaded on first access
+     */
+    get subscriptions() {
+      if (!services.subscriptions) {
+        services.subscriptions = new SubscriptionService(container);
+      }
+      return services.subscriptions;
+    },
+
+    /**
+     * Payment service
+     * Lazy-loaded on first access
+     */
+    get payments() {
+      if (!services.payments) {
+        services.payments = new PaymentService(container);
+      }
+      return services.payments;
+    },
+
+    /**
+     * Transaction service
+     * Lazy-loaded on first access
+     */
+    get transactions() {
+      if (!services.transactions) {
+        services.transactions = new TransactionService(container);
+      }
+      return services.transactions;
+    },
+
+    /**
+     * Get a specific provider
+     */
+    getProvider(name) {
+      const provider = providers[name];
+      if (!provider) {
+        throw new Error(`Provider "${name}" not found. Available: ${Object.keys(providers).join(', ')}`);
+      }
+      return provider;
+    },
+  };
+
+  // Deeply freeze the revenue object (truly immutable)
+  Object.freeze(revenue);
+  Object.freeze(providers);
+  Object.freeze(config);
+
+  return revenue;
+}
+
+/**
+ * Revenue instance type (for documentation)
+ * @typedef {Object} Revenue
+ * @property {Container} container - DI container (readonly)
+ * @property {Object} providers - Payment providers (readonly, frozen)
+ * @property {Object} config - Configuration (readonly, frozen)
+ * @property {SubscriptionService} subscriptions - Subscription service
+ * @property {PaymentService} payments - Payment service
+ * @property {TransactionService} transactions - Transaction service
+ * @property {Function} getProvider - Get payment provider
+ */
+
+export default createRevenue;