@classytic/revenue 0.0.24 → 0.1.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):
@@ -483,7 +595,7 @@ 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

package/core/builder.js

@@ -10,6 +10,8 @@ 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
@@ -62,6 +64,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 +93,7 @@ export function createRevenue(options = {}) {
     subscriptions: null,
     payments: null,
     transactions: null,
+    escrow: null,
   };
 
   // Create revenue instance
@@ -135,6 +146,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 +177,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 +202,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,87 @@
+/**
+ * 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?: {
+    models: any;
+    providers: any;
+    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;
+}

package/dist/types/enums/escrow.enums.d.ts

@@ -0,0 +1,24 @@
+export namespace HOLD_STATUS {
+    let PENDING: string;
+    let HELD: string;
+    let RELEASED: string;
+    let CANCELLED: string;
+    let EXPIRED: string;
+    let PARTIALLY_RELEASED: string;
+}
+export const HOLD_STATUS_VALUES: string[];
+export namespace RELEASE_REASON {
+    let PAYMENT_VERIFIED: string;
+    let MANUAL_RELEASE: string;
+    let AUTO_RELEASE: string;
+    let DISPUTE_RESOLVED: string;
+}
+export const RELEASE_REASON_VALUES: string[];
+export namespace HOLD_REASON {
+    let PAYMENT_VERIFICATION: string;
+    let FRAUD_CHECK: string;
+    let MANUAL_REVIEW: string;
+    let DISPUTE: string;
+    let COMPLIANCE: string;
+}
+export const HOLD_REASON_VALUES: string[];

package/dist/types/enums/index.d.ts

@@ -0,0 +1,69 @@
+export * from "./transaction.enums.js";
+export * from "./payment.enums.js";
+export * from "./subscription.enums.js";
+export * from "./monetization.enums.js";
+export * from "./escrow.enums.js";
+export * from "./split.enums.js";
+declare namespace _default {
+    export { TRANSACTION_TYPE };
+    export { TRANSACTION_TYPE_VALUES };
+    export { TRANSACTION_STATUS };
+    export { TRANSACTION_STATUS_VALUES };
+    export { LIBRARY_CATEGORIES };
+    export { LIBRARY_CATEGORY_VALUES };
+    export { PAYMENT_STATUS };
+    export { PAYMENT_STATUS_VALUES };
+    export { PAYMENT_GATEWAY_TYPE };
+    export { PAYMENT_GATEWAY_TYPE_VALUES };
+    export { GATEWAY_TYPES };
+    export { GATEWAY_TYPE_VALUES };
+    export { SUBSCRIPTION_STATUS };
+    export { SUBSCRIPTION_STATUS_VALUES };
+    export { PLAN_KEYS };
+    export { PLAN_KEY_VALUES };
+    export { MONETIZATION_TYPES };
+    export { MONETIZATION_TYPE_VALUES };
+    export { HOLD_STATUS };
+    export { HOLD_STATUS_VALUES };
+    export { RELEASE_REASON };
+    export { RELEASE_REASON_VALUES };
+    export { HOLD_REASON };
+    export { HOLD_REASON_VALUES };
+    export { SPLIT_TYPE };
+    export { SPLIT_TYPE_VALUES };
+    export { SPLIT_STATUS };
+    export { SPLIT_STATUS_VALUES };
+    export { PAYOUT_METHOD };
+    export { PAYOUT_METHOD_VALUES };
+}
+export default _default;
+import { TRANSACTION_TYPE } from './transaction.enums.js';
+import { TRANSACTION_TYPE_VALUES } from './transaction.enums.js';
+import { TRANSACTION_STATUS } from './transaction.enums.js';
+import { TRANSACTION_STATUS_VALUES } from './transaction.enums.js';
+import { LIBRARY_CATEGORIES } from './transaction.enums.js';
+import { LIBRARY_CATEGORY_VALUES } from './transaction.enums.js';
+import { PAYMENT_STATUS } from './payment.enums.js';
+import { PAYMENT_STATUS_VALUES } from './payment.enums.js';
+import { PAYMENT_GATEWAY_TYPE } from './payment.enums.js';
+import { PAYMENT_GATEWAY_TYPE_VALUES } from './payment.enums.js';
+import { GATEWAY_TYPES } from './payment.enums.js';
+import { GATEWAY_TYPE_VALUES } from './payment.enums.js';
+import { SUBSCRIPTION_STATUS } from './subscription.enums.js';
+import { SUBSCRIPTION_STATUS_VALUES } from './subscription.enums.js';
+import { PLAN_KEYS } from './subscription.enums.js';
+import { PLAN_KEY_VALUES } from './subscription.enums.js';
+import { MONETIZATION_TYPES } from './monetization.enums.js';
+import { MONETIZATION_TYPE_VALUES } from './monetization.enums.js';
+import { HOLD_STATUS } from './escrow.enums.js';
+import { HOLD_STATUS_VALUES } from './escrow.enums.js';
+import { RELEASE_REASON } from './escrow.enums.js';
+import { RELEASE_REASON_VALUES } from './escrow.enums.js';
+import { HOLD_REASON } from './escrow.enums.js';
+import { HOLD_REASON_VALUES } from './escrow.enums.js';
+import { SPLIT_TYPE } from './split.enums.js';
+import { SPLIT_TYPE_VALUES } from './split.enums.js';
+import { SPLIT_STATUS } from './split.enums.js';
+import { SPLIT_STATUS_VALUES } from './split.enums.js';
+import { PAYOUT_METHOD } from './split.enums.js';
+import { PAYOUT_METHOD_VALUES } from './split.enums.js';

package/dist/types/enums/monetization.enums.d.ts

@@ -0,0 +1,6 @@
+export namespace MONETIZATION_TYPES {
+    let FREE: string;
+    let PURCHASE: string;
+    let SUBSCRIPTION: string;
+}
+export const MONETIZATION_TYPE_VALUES: string[];

package/dist/types/enums/payment.enums.d.ts

@@ -0,0 +1,16 @@
+export namespace PAYMENT_STATUS {
+    let PENDING: string;
+    let VERIFIED: string;
+    let FAILED: string;
+    let REFUNDED: string;
+    let CANCELLED: string;
+}
+export const PAYMENT_STATUS_VALUES: string[];
+export namespace PAYMENT_GATEWAY_TYPE {
+    let MANUAL: string;
+    let STRIPE: string;
+    let SSLCOMMERZ: string;
+}
+export const PAYMENT_GATEWAY_TYPE_VALUES: string[];
+export namespace GATEWAY_TYPES { }
+export const GATEWAY_TYPE_VALUES: string[];

package/dist/types/enums/split.enums.d.ts

@@ -0,0 +1,25 @@
+export namespace SPLIT_TYPE {
+    let PLATFORM_COMMISSION: string;
+    let AFFILIATE_COMMISSION: string;
+    let REFERRAL_COMMISSION: string;
+    let PARTNER_COMMISSION: string;
+    let CUSTOM: string;
+}
+export const SPLIT_TYPE_VALUES: string[];
+export namespace SPLIT_STATUS {
+    let PENDING: string;
+    let DUE: string;
+    let PAID: string;
+    let WAIVED: string;
+    let CANCELLED: string;
+}
+export const SPLIT_STATUS_VALUES: string[];
+export namespace PAYOUT_METHOD {
+    let BANK_TRANSFER: string;
+    let MOBILE_WALLET: string;
+    let PLATFORM_BALANCE: string;
+    let CRYPTO: string;
+    let CHECK: string;
+    let MANUAL: string;
+}
+export const PAYOUT_METHOD_VALUES: string[];