@classytic/revenue 0.0.24 → 0.2.0

package/README.md

@@ -9,6 +9,9 @@ Thin, focused, production-ready library with smart defaults. Built for SaaS, mar
 - **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
+- **Escrow & Hold/Release**: Platform-as-intermediary payment flow (NEW in v0.1.0)
+- **Multi-Party Splits**: Distribute revenue to platform, affiliates, partners (NEW)
+- **Affiliate Commissions**: Built-in support for referral/affiliate programs (NEW)
 - **Commission Tracking**: Automatic platform commission calculation with gateway fee deduction
 - **Provider Pattern**: Pluggable payment providers (like LangChain/Vercel AI SDK)
 - **Framework Agnostic**: Works with Express, Fastify, Next.js, or standalone
@@ -21,41 +24,51 @@ npm install @classytic/revenue
 npm install @classytic/revenue-manual  # For manual payments
 ```
 
-## Quick Start (30 seconds)
+## Quick Start
+
+### Single-Tenant (Simple SaaS)
 
 ```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 },
   providers: { manual: new ManualProvider() },
 });
 
-// 2. Create subscription
-const { subscription, transaction } = await revenue.subscriptions.create({
-  data: {
-    organizationId,
-    customerId,
-    referenceId: orderId,        // Optional: Link to Order, Subscription, etc.
-    referenceModel: 'Order',     // Optional: Model name for polymorphic ref
-  },
+// Create subscription (no organizationId needed)
+const { transaction } = await revenue.subscriptions.create({
+  data: { customerId: user._id },
   planKey: 'monthly',
-  amount: 1500,
+  amount: 2999,  // $29.99
   gateway: 'manual',
-  paymentData: { method: 'bkash', walletNumber: '01712345678' },
+  paymentData: { method: 'card' },
 });
 
-// 3. Verify payment
+// Verify → Refund
 await revenue.payments.verify(transaction.gateway.paymentIntentId);
+```
+
+### Multi-Tenant (Marketplace/Platform)
 
-// 4. Refund if needed
-await revenue.payments.refund(transaction._id, 500, { reason: 'Partial refund' });
+```javascript
+// Same API, just pass organizationId
+const { transaction } = await revenue.subscriptions.create({
+  data: {
+    organizationId: vendor._id,  // ← Multi-tenant
+    customerId: customer._id,
+    referenceId: order._id,
+    referenceModel: 'Order',
+  },
+  planKey: 'monthly',
+  amount: 1500,
+  gateway: 'manual',
+  paymentData: { method: 'bkash' },
+});
 ```
 
-**That's it!** Working revenue system in 3 steps.
+**Works for both!** Same API, different use cases.
 
 ## Transaction Model Setup
 
@@ -74,12 +87,14 @@ import {
 
 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
+  
+  // ============ MULTI-TENANT (optional) ============
+  organizationId: { type: String, index: true },  // For multi-tenant platforms
 
   // ============ LIBRARY SCHEMAS (nested) ============
   gateway: gatewaySchema,              // Payment gateway details
@@ -346,6 +361,103 @@ if (canRenewSubscription(membership)) {
 }
 ```
 
+## Escrow & Multi-Party Splits (v0.1.0+)
+
+**NEW:** Platform-as-intermediary payment flow for marketplaces, group buy, and affiliate systems.
+
+### Basic Escrow Flow
+
+```javascript
+// 1. Customer makes purchase
+const { transaction } = await revenue.subscriptions.create({
+  amount: 1000,
+  gateway: 'stripe',
+  // ...
+});
+
+// 2. Verify payment
+await revenue.payments.verify(transaction._id);
+
+// 3. Hold in escrow
+await revenue.escrow.hold(transaction._id);
+
+// 4. Split to multiple recipients
+await revenue.escrow.split(transaction._id, [
+  { type: 'platform_commission', recipientId: 'platform', rate: 0.10 },
+  { type: 'affiliate_commission', recipientId: 'affiliate-123', rate: 0.05 },
+]);
+// Auto-releases remainder to organization (85%)
+
+// Or manually release
+await revenue.escrow.release(transaction._id, {
+  recipientId: 'org-123',
+  recipientType: 'organization',
+});
+```
+
+### Affiliate Commission (Simplified API)
+
+```javascript
+import { calculateCommissionWithSplits } from '@classytic/revenue';
+
+const commission = calculateCommissionWithSplits(
+  5000,    // amount
+  0.10,    // platform rate
+  0.029,   // gateway fee
+  {
+    affiliateRate: 0.05,
+    affiliateId: 'affiliate-123',
+  }
+);
+
+// Returns:
+// {
+//   grossAmount: 500,  // Platform: 10%
+//   netAmount: 355,    // After gateway fee (2.9%)
+//   affiliate: {
+//     grossAmount: 250,  // Affiliate: 5%
+//     netAmount: 250,
+//   },
+//   splits: [...]
+// }
+```
+
+### Multi-Party Splits
+
+```javascript
+import { calculateSplits } from '@classytic/revenue';
+
+const splits = calculateSplits(10000, [
+  { type: 'platform_commission', recipientId: 'platform', rate: 0.10 },
+  { type: 'affiliate_commission', recipientId: 'level1', rate: 0.05 },
+  { type: 'affiliate_commission', recipientId: 'level2', rate: 0.02 },
+  { type: 'partner_commission', recipientId: 'partner', rate: 0.03 },
+], 0.029);  // Gateway fee
+
+// Returns splits array with calculated amounts
+// Organization receives: 8000 (80%)
+```
+
+### Schemas for Escrow
+
+Add to your transaction model when using escrow:
+
+```javascript
+import { holdSchema, splitsSchema } from '@classytic/revenue';
+
+TransactionSchema.add(holdSchema);    // Adds hold/release tracking
+TransactionSchema.add(splitsSchema);  // Adds multi-party splits
+```
+
+**Use Cases:**
+- E-commerce marketplaces (hold until delivery confirmed)
+- Course platforms with affiliates
+- Group buy / crowdfunding
+- Multi-level marketing
+- SaaS reseller programs
+
+**See:** [`ESCROW_FEATURES.md`](../../ESCROW_FEATURES.md) and [`examples/escrow-flow.js`](examples/escrow-flow.js)
+
 ## Polymorphic References
 
 Link transactions to any entity (Order, Subscription, Enrollment):
@@ -382,24 +494,71 @@ const transactions = await Transaction.find({ ... })
 const revenue = createRevenue({
   models: { Transaction },
   hooks: {
-    'subscription.created': async ({ subscription, transaction }) => {
-      console.log('New subscription:', subscription._id);
+    // Monetization lifecycle (specific)
+    'purchase.created': async ({ transaction, isFree }) => {
+      console.log('One-time purchase:', transaction._id);
+    },
+    'subscription.created': async ({ transaction, isFree }) => {
+      console.log('Recurring subscription:', transaction._id);
     },
+    'free.created': async ({ transaction }) => {
+      console.log('Free access granted:', transaction._id);
+    },
+    
+    // Generic event (fires for all types)
+    'monetization.created': async ({ transaction, monetizationType }) => {
+      console.log(`${monetizationType} created:`, transaction._id);
+    },
+
+    // Payment lifecycle
     'payment.verified': async ({ transaction }) => {
       // Send confirmation email
     },
+    'payment.failed': async ({ transaction, error, provider }) => {
+      // Alert admin or send customer notification
+      console.error('Payment failed:', error);
+    },
     'payment.refunded': async ({ refundTransaction }) => {
       // Process refund notification
     },
+    
+    // Subscription management (requires Subscription model)
+    'subscription.activated': async ({ subscription }) => {
+      // Subscription activated after payment
+    },
+    'subscription.renewed': async ({ subscription, renewalCount }) => {
+      // Subscription renewed
+    },
+    'subscription.paused': async ({ subscription }) => {
+      // Subscription paused
+    },
+    'subscription.resumed': async ({ subscription }) => {
+      // Subscription resumed
+    },
+    'subscription.cancelled': async ({ subscription }) => {
+      // Subscription cancelled
+    },
   },
 });
 ```
 
 **Available hooks:**
-- `subscription.created`, `subscription.activated`, `subscription.renewed`
+
+**Monetization Events (specific):**
+- `purchase.created` - One-time purchase
+- `subscription.created` - Recurring subscription
+- `free.created` - Free access granted
+- `monetization.created` - Generic event (fires for all types)
+
+**Payment Events:**
+- `payment.verified` - Payment confirmed
+- `payment.failed` - Payment verification failed
+- `payment.refunded` - Refund processed
+- `payment.webhook.{type}` - Webhook events from providers
+
+**Subscription Management Events (requires Subscription model):**
+- `subscription.activated`, `subscription.renewed`
 - `subscription.paused`, `subscription.resumed`, `subscription.cancelled`
-- `payment.verified`, `payment.refunded`
-- `payment.webhook.{type}` (for webhook events)
 
 ## Provider Patterns
 
@@ -483,10 +642,11 @@ const subscription = await revenue.subscriptions.create({ ... });
 
 ## Examples
 
-- [`examples/basic-usage.js`](examples/basic-usage.js) - Quick start guide
+- [`examples/single-tenant.js`](examples/single-tenant.js) - Simple SaaS (no organizations)
 - [`examples/transaction.model.js`](examples/transaction.model.js) - Complete model setup
 - [`examples/complete-flow.js`](examples/complete-flow.js) - Full lifecycle (types, refs, state)
 - [`examples/commission-tracking.js`](examples/commission-tracking.js) - Commission calculation
+- [`examples/hooks-v0.2.0.js`](examples/hooks-v0.2.0.js) - v0.2.0 semantic hooks (NEW)
 
 ## Error Handling
 

package/core/builder.js

@@ -10,13 +10,15 @@ 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';
+import { EscrowService } from '../services/escrow.service.js';
+import { ConfigurationError } from './errors.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 {Record<string, import('../providers/base.js').PaymentProvider>} options.providers - Payment providers - Register ANY custom gateway by name
  * @param {Object} options.hooks - Event hooks
  * @param {Object} options.config - Additional configuration
  * @param {Object} options.logger - Logger instance
@@ -24,7 +26,8 @@ import { TransactionService } from '../services/transaction.service.js';
  *
  * @example
  * ```javascript
- * import { createRevenue, ManualProvider } from '@classytic/revenue';
+ * import { createRevenue } from '@classytic/revenue';
+ * import { ManualProvider } from '@classytic/revenue-manual';
  *
  * const revenue = createRevenue({
  *   models: {
@@ -33,6 +36,10 @@ import { TransactionService } from '../services/transaction.service.js';
  *   },
  *   providers: {
  *     manual: new ManualProvider(),
+ *     bkash: new BkashProvider(),      // Custom gateway
+ *     nagad: new NagadProvider(),      // Custom gateway
+ *     stripe: new StripeProvider(),    // Custom gateway
+ *     // ... register any gateway you want
  *   },
  *   config: {
  *     targetModels: ['Subscription', 'Membership'],
@@ -43,8 +50,11 @@ import { TransactionService } from '../services/transaction.service.js';
  *   },
  * });
  *
- * // Use anywhere
- * const subscription = await revenue.subscriptions.create({ ... });
+ * // Use any registered gateway by name
+ * const subscription = await revenue.subscriptions.create({
+ *   gateway: 'bkash',  // Use your custom gateway
+ *   // ...
+ * });
  * await revenue.payments.verify(txnId);
  * ```
  */
@@ -62,6 +72,14 @@ export function createRevenue(options = {}) {
 
   // Register providers
   const providers = options.providers || {};
+
+  // Validate provider interface in non-production
+  if (process.env.NODE_ENV !== 'production') {
+    for (const [name, provider] of Object.entries(providers)) {
+      validateProvider(name, provider);
+    }
+  }
+
   container.singleton('providers', providers);
 
   // Register hooks
@@ -83,6 +101,7 @@ export function createRevenue(options = {}) {
     subscriptions: null,
     payments: null,
     transactions: null,
+    escrow: null,
   };
 
   // Create revenue instance
@@ -135,6 +154,17 @@ export function createRevenue(options = {}) {
       return services.transactions;
     },
 
+    /**
+     * Escrow service
+     * Lazy-loaded on first access
+     */
+    get escrow() {
+      if (!services.escrow) {
+        services.escrow = new EscrowService(container);
+      }
+      return services.escrow;
+    },
+
     /**
      * Get a specific provider
      */
@@ -155,6 +185,22 @@ export function createRevenue(options = {}) {
   return revenue;
 }
 
+/**
+ * Validate provider implements required interface
+ * @private
+ */
+function validateProvider(name, provider) {
+  const required = ['createIntent', 'verifyPayment', 'getStatus', 'getCapabilities'];
+  const missing = required.filter(method => typeof provider[method] !== 'function');
+
+  if (missing.length > 0) {
+    throw new ConfigurationError(
+      `Provider "${name}" is missing required methods: ${missing.join(', ')}`,
+      { provider: name, missing }
+    );
+  }
+}
+
 /**
  * Revenue instance type (for documentation)
  * @typedef {Object} Revenue
@@ -164,6 +210,7 @@ export function createRevenue(options = {}) {
  * @property {SubscriptionService} subscriptions - Subscription service
  * @property {PaymentService} payments - Payment service
  * @property {TransactionService} transactions - Transaction service
+ * @property {EscrowService} escrow - Escrow service
  * @property {Function} getProvider - Get payment provider
  */
 

package/dist/types/core/builder.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Create revenue instance with dependency injection
+ *
+ * @param {Object} options - Configuration options
+ * @param {Object} options.models - Mongoose models { Transaction, Subscription, etc. }
+ * @param {Record<string, import('../providers/base.js').PaymentProvider>} options.providers - Payment providers - Register ANY custom gateway by name
+ * @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 } from '@classytic/revenue';
+ * import { ManualProvider } from '@classytic/revenue-manual';
+ *
+ * const revenue = createRevenue({
+ *   models: {
+ *     Transaction: TransactionModel,
+ *     Subscription: SubscriptionModel,
+ *   },
+ *   providers: {
+ *     manual: new ManualProvider(),
+ *     bkash: new BkashProvider(),      // Custom gateway
+ *     nagad: new NagadProvider(),      // Custom gateway
+ *     stripe: new StripeProvider(),    // Custom gateway
+ *     // ... register any gateway you want
+ *   },
+ *   config: {
+ *     targetModels: ['Subscription', 'Membership'],
+ *     categoryMappings: {
+ *       Subscription: 'platform_subscription',
+ *       Membership: 'gym_membership',
+ *     },
+ *   },
+ * });
+ *
+ * // Use any registered gateway by name
+ * const subscription = await revenue.subscriptions.create({
+ *   gateway: 'bkash',  // Use your custom gateway
+ *   // ...
+ * });
+ * await revenue.payments.verify(txnId);
+ * ```
+ */
+export function createRevenue(options?: {
+    models: any;
+    providers: Record<string, import("../providers/base.js").PaymentProvider>;
+    hooks: any;
+    config: any;
+    logger: any;
+}): Revenue;
+export default createRevenue;
+/**
+ * Revenue instance type (for documentation)
+ */
+export type Revenue = {
+    /**
+     * - DI container (readonly)
+     */
+    container: Container;
+    /**
+     * - Payment providers (readonly, frozen)
+     */
+    providers: any;
+    /**
+     * - Configuration (readonly, frozen)
+     */
+    config: any;
+    /**
+     * - Subscription service
+     */
+    subscriptions: SubscriptionService;
+    /**
+     * - Payment service
+     */
+    payments: PaymentService;
+    /**
+     * - Transaction service
+     */
+    transactions: TransactionService;
+    /**
+     * - Escrow service
+     */
+    escrow: EscrowService;
+    /**
+     * - Get payment provider
+     */
+    getProvider: Function;
+};
+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';
+import { EscrowService } from '../services/escrow.service.js';

package/dist/types/core/container.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Dependency Injection Container
+ * @classytic/revenue
+ *
+ * Lightweight DI container for managing dependencies
+ * Inspired by: Awilix, InversifyJS but much simpler
+ */
+export class Container {
+    _services: Map<any, any>;
+    _singletons: Map<any, any>;
+    /**
+     * Register a service
+     * @param {string} name - Service name
+     * @param {any} implementation - Service implementation or factory
+     * @param {Object} options - Registration options
+     */
+    register(name: string, implementation: any, options?: any): this;
+    /**
+     * Register a singleton service
+     * @param {string} name - Service name
+     * @param {any} implementation - Service implementation
+     */
+    singleton(name: string, implementation: any): this;
+    /**
+     * Register a transient service (new instance each time)
+     * @param {string} name - Service name
+     * @param {Function} factory - Factory function
+     */
+    transient(name: string, factory: Function): this;
+    /**
+     * Get a service from the container
+     * @param {string} name - Service name
+     * @returns {any} Service instance
+     */
+    get(name: string): any;
+    /**
+     * Check if service is registered
+     * @param {string} name - Service name
+     * @returns {boolean}
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered service names
+     * @returns {string[]}
+     */
+    keys(): string[];
+    /**
+     * Clear all services (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Create a child container (for scoped dependencies)
+     * @returns {Container}
+     */
+    createScope(): Container;
+}
+export default Container;

package/dist/types/core/errors.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Check if error is retryable
+ */
+export function isRetryable(error: any): any;
+/**
+ * Check if error is from revenue package
+ */
+export function isRevenueError(error: any): error is RevenueError;
+/**
+ * Revenue Error Classes
+ * @classytic/revenue
+ *
+ * Typed errors with codes for better error handling
+ */
+/**
+ * Base Revenue Error
+ */
+export class RevenueError extends Error {
+    constructor(message: any, code: any, options?: {});
+    code: any;
+    retryable: any;
+    metadata: any;
+    toJSON(): {
+        name: string;
+        message: string;
+        code: any;
+        retryable: any;
+        metadata: any;
+    };
+}
+/**
+ * Configuration Errors
+ */
+export class ConfigurationError extends RevenueError {
+    constructor(message: any, metadata?: {});
+}
+export class ModelNotRegisteredError extends ConfigurationError {
+    constructor(modelName: any);
+}
+/**
+ * Provider Errors
+ */
+export class ProviderError extends RevenueError {
+}
+export class ProviderNotFoundError extends ProviderError {
+    constructor(providerName: any, availableProviders?: any[]);
+}
+export class ProviderCapabilityError extends ProviderError {
+    constructor(providerName: any, capability: any);
+}
+export class PaymentIntentCreationError extends ProviderError {
+    constructor(providerName: any, originalError: any);
+}
+export class PaymentVerificationError extends ProviderError {
+    constructor(paymentIntentId: any, reason: any);
+}
+/**
+ * Resource Not Found Errors
+ */
+export class NotFoundError extends RevenueError {
+}
+export class SubscriptionNotFoundError extends NotFoundError {
+    constructor(subscriptionId: any);
+}
+export class TransactionNotFoundError extends NotFoundError {
+    constructor(transactionId: any);
+}
+/**
+ * Validation Errors
+ */
+export class ValidationError extends RevenueError {
+    constructor(message: any, metadata?: {});
+}
+export class InvalidAmountError extends ValidationError {
+    constructor(amount: any);
+}
+export class MissingRequiredFieldError extends ValidationError {
+    constructor(fieldName: any);
+}
+/**
+ * State Errors
+ */
+export class StateError extends RevenueError {
+}
+export class AlreadyVerifiedError extends StateError {
+    constructor(transactionId: any);
+}
+export class InvalidStateTransitionError extends StateError {
+    constructor(resourceType: any, resourceId: any, fromState: any, toState: any);
+}
+export class SubscriptionNotActiveError extends StateError {
+    constructor(subscriptionId: any);
+}
+/**
+ * Operation Errors
+ */
+export class OperationError extends RevenueError {
+}
+export class RefundNotSupportedError extends OperationError {
+    constructor(providerName: any);
+}
+export class RefundError extends OperationError {
+    constructor(transactionId: any, reason: any);
+}
+export namespace ERROR_CODES {
+    let CONFIGURATION_ERROR: string;
+    let MODEL_NOT_REGISTERED: string;
+    let PROVIDER_NOT_FOUND: string;
+    let PROVIDER_CAPABILITY_NOT_SUPPORTED: string;
+    let PAYMENT_INTENT_CREATION_FAILED: string;
+    let PAYMENT_VERIFICATION_FAILED: string;
+    let SUBSCRIPTION_NOT_FOUND: string;
+    let TRANSACTION_NOT_FOUND: string;
+    let VALIDATION_ERROR: string;
+    let INVALID_AMOUNT: string;
+    let MISSING_REQUIRED_FIELD: string;
+    let ALREADY_VERIFIED: string;
+    let INVALID_STATE_TRANSITION: string;
+    let SUBSCRIPTION_NOT_ACTIVE: string;
+    let REFUND_NOT_SUPPORTED: string;
+    let REFUND_FAILED: string;
+}