@classytic/revenue 0.0.2 → 0.0.22

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.2",
+  "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

@@ -105,13 +105,21 @@ export class SubscriptionService {
     amount: number;
     currency?: string;
     gateway?: string;
+    entity?: string;
+    monetizationType?: 'free' | 'subscription' | 'purchase';
     paymentData?: any;
     metadata?: Record<string, any>;
     idempotencyKey?: string;
   }): Promise<{ subscription: any; transaction: any; paymentIntent: PaymentIntent | null }>;
 
   activate(subscriptionId: string, options?: { timestamp?: Date }): Promise<any>;
-  renew(subscriptionId: string, params?: any): Promise<{ subscription: any; transaction: any; paymentIntent: PaymentIntent }>;
+  renew(subscriptionId: string, params?: {
+    gateway?: string;
+    entity?: string;
+    paymentData?: any;
+    metadata?: Record<string, any>;
+    idempotencyKey?: string;
+  }): Promise<{ subscription: any; transaction: any; paymentIntent: PaymentIntent }>;
   cancel(subscriptionId: string, options?: { immediate?: boolean; reason?: string }): Promise<any>;
   pause(subscriptionId: string, options?: { reason?: string }): Promise<any>;
   resume(subscriptionId: string, options?: { extendPeriod?: boolean }): Promise<any>;
@@ -124,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>;
@@ -193,8 +201,43 @@ export interface RevenueOptions {
   providers?: Record<string, PaymentProvider>;
   hooks?: Record<string, Function[]>;
   config?: {
-    targetModels?: string[];
+    /**
+     * Maps logical entity identifiers to custom transaction category names
+     *
+     * Entity identifiers are NOT database model names - they are logical identifiers
+     * you choose to organize your business logic.
+     *
+     * @example
+     * categoryMappings: {
+     *   Order: 'order_subscription',              // Customer orders
+     *   PlatformSubscription: 'platform_subscription',  // Tenant/org subscriptions
+     *   TenantUpgrade: 'tenant_upgrade',          // Tenant upgrades
+     *   Membership: 'gym_membership',              // User memberships
+     *   Enrollment: 'course_enrollment',           // Course enrollments
+     * }
+     *
+     * 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;
@@ -204,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';
@@ -218,19 +266,10 @@ export const TRANSACTION_STATUS: {
   PARTIALLY_REFUNDED: 'partially_refunded';
 };
 
-export const TRANSACTION_TYPES: {
-  INCOME: 'income';
-  EXPENSE: 'expense';
-};
-
-// Note: PAYMENT_METHOD removed - users define their own payment methods
-
 export const PAYMENT_GATEWAY_TYPE: {
   MANUAL: 'manual';
   STRIPE: 'stripe';
   SSLCOMMERZ: 'sslcommerz';
-  BKASH_GATEWAY: 'bkash_gateway';
-  NAGAD_GATEWAY: 'nagad_gateway';
 };
 
 export const SUBSCRIPTION_STATUS: {
@@ -263,15 +302,6 @@ export const subscriptionPlanSchema: Schema;
 export const gatewaySchema: Schema;
 export const commissionSchema: Schema;
 export const paymentDetailsSchema: Schema;
-export const tenantSnapshotSchema: Schema;
-export const timelineEventSchema: Schema;
-export const customerInfoSchema: Schema;
-export const customDiscountSchema: Schema;
-export const stripeAccountSchema: Schema;
-export const sslcommerzAccountSchema: Schema;
-export const bkashMerchantSchema: Schema;
-export const bankAccountSchema: Schema;
-export const walletSchema: Schema;
 
 // ============ UTILITIES ============
 

package/schemas/index.d.ts

@@ -12,23 +12,11 @@ export const paymentSummarySchema: Schema;
 export const paymentDetailsSchema: Schema;
 export const gatewaySchema: Schema;
 export const commissionSchema: Schema;
-export const tenantSnapshotSchema: Schema;
-export const timelineEventSchema: Schema;
-export const customerInfoSchema: Schema;
 
 // ============ SUBSCRIPTION SCHEMAS ============
 
 export const subscriptionInfoSchema: Schema;
 export const subscriptionPlanSchema: Schema;
-export const customDiscountSchema: Schema;
-
-// ============ GATEWAY ACCOUNT SCHEMAS ============
-
-export const stripeAccountSchema: Schema;
-export const sslcommerzAccountSchema: Schema;
-export const bkashMerchantSchema: Schema;
-export const bankAccountSchema: Schema;
-export const walletSchema: Schema;
 
 // ============ DEFAULT EXPORT ============
 
@@ -38,17 +26,8 @@ declare const _default: {
   paymentDetailsSchema: Schema;
   gatewaySchema: Schema;
   commissionSchema: Schema;
-  tenantSnapshotSchema: Schema;
-  timelineEventSchema: Schema;
-  customerInfoSchema: Schema;
   subscriptionInfoSchema: Schema;
   subscriptionPlanSchema: Schema;
-  customDiscountSchema: Schema;
-  stripeAccountSchema: Schema;
-  sslcommerzAccountSchema: Schema;
-  bkashMerchantSchema: Schema;
-  bankAccountSchema: Schema;
-  walletSchema: Schema;
 };
 
 export default _default;

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
@@ -132,7 +133,7 @@ export class PaymentService {
     }
 
     if (!transaction) {
-      throw new Error('Transaction not found');
+      throw new TransactionNotFoundError(paymentIntentId);
     }
 
     // Get provider
@@ -140,7 +141,7 @@ export class PaymentService {
     const provider = this.providers[gatewayType];
 
     if (!provider) {
-      throw new Error(`Payment provider "${gatewayType}" not found`);
+      throw new ProviderNotFoundError(gatewayType, Object.keys(this.providers));
     }
 
     // Get status from provider
@@ -218,18 +219,46 @@ export class PaymentService {
       refundResult = await provider.refund(paymentId, refundAmount, { reason });
     } catch (error) {
       this.logger.error('Refund failed:', error);
-      throw new Error(`Refund failed: ${error.message}`);
+      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,
     };
@@ -262,7 +293,7 @@ export class PaymentService {
     const provider = this.providers[providerName];
 
     if (!provider) {
-      throw new Error(`Payment provider "${providerName}" not found`);
+      throw new ProviderNotFoundError(providerName, Object.keys(this.providers));
     }
 
     // Process webhook via provider
@@ -271,7 +302,7 @@ export class PaymentService {
       webhookEvent = await provider.handleWebhook(payload, headers);
     } catch (error) {
       this.logger.error('Webhook processing failed:', error);
-      throw new Error(`Webhook processing failed: ${error.message}`);
+      throw new ProviderError(providerName, `Webhook processing failed: ${error.message}`);
     }
 
     // Find transaction by payment intent ID from webhook
@@ -286,7 +317,7 @@ export class PaymentService {
         eventId: webhookEvent.id,
         paymentIntentId: webhookEvent.data.paymentIntentId,
       });
-      throw new Error('Transaction not found for payment intent');
+      throw new TransactionNotFoundError(webhookEvent.data.paymentIntentId);
     }
 
     // Check for duplicate webhook processing (idempotency)
@@ -368,7 +399,7 @@ export class PaymentService {
     const transaction = await TransactionModel.findById(transactionId);
 
     if (!transaction) {
-      throw new Error('Transaction not found');
+      throw new TransactionNotFoundError(transactionId);
     }
 
     return transaction;
@@ -383,7 +414,7 @@ export class PaymentService {
   getProvider(providerName) {
     const provider = this.providers[providerName];
     if (!provider) {
-      throw new Error(`Payment provider "${providerName}" not found. Available: ${Object.keys(this.providers).join(', ')}`);
+      throw new ProviderNotFoundError(providerName, Object.keys(this.providers));
     }
     return provider;
   }

package/services/subscription.service.js

@@ -15,8 +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
@@ -41,6 +45,9 @@ export class SubscriptionService {
    * @param {Number} params.amount - Subscription amount
    * @param {String} params.currency - Currency code (default: 'BDT')
    * @param {String} params.gateway - Payment gateway to use (default: 'manual')
+   * @param {String} params.entity - Logical entity identifier (e.g., 'Order', 'PlatformSubscription', 'Membership')
+   *                                 NOTE: This is NOT a database model name - it's just a logical identifier for categoryMappings
+   * @param {String} params.monetizationType - Monetization type ('free', 'subscription', 'purchase')
    * @param {Object} params.paymentData - Payment method details
    * @param {Object} params.metadata - Additional metadata
    * @param {String} params.idempotencyKey - Idempotency key for duplicate prevention
@@ -53,6 +60,8 @@ export class SubscriptionService {
       amount,
       currency = 'BDT',
       gateway = 'manual',
+      entity = null,
+      monetizationType = MONETIZATION_TYPES.SUBSCRIPTION,
       paymentData,
       metadata = {},
       idempotencyKey = null,
@@ -99,6 +108,14 @@ export class SubscriptionService {
         throw new PaymentIntentCreationError(gateway, error);
       }
 
+      // 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({
@@ -106,8 +123,9 @@ export class SubscriptionService {
         customerId: data.customerId || null,
         amount,
         currency,
-        category: 'platform_subscription',
-        type: 'credit',
+        category,
+        type: transactionType,
+        method: paymentData?.method || 'manual',
         status: paymentIntent.status === 'succeeded' ? 'verified' : 'pending',
         gateway: {
           type: gateway,
@@ -121,6 +139,8 @@ export class SubscriptionService {
         metadata: {
           ...metadata,
           planKey,
+          entity,
+          monetizationType,
           paymentIntentId: paymentIntent.id,
         },
         idempotencyKey: idempotencyKey || `sub_${nanoid(16)}`,
@@ -146,6 +166,8 @@ export class SubscriptionService {
         metadata: {
           ...metadata,
           isFree,
+          entity,
+          monetizationType,
         },
         ...data,
       });
@@ -218,35 +240,41 @@ export class SubscriptionService {
    *
    * @param {String} subscriptionId - Subscription ID
    * @param {Object} params - Renewal parameters
+   * @param {String} params.gateway - Payment gateway to use (default: 'manual')
+   * @param {String} params.entity - Logical entity identifier (optional, inherits from subscription)
+   * @param {Object} params.paymentData - Payment method details
+   * @param {Object} params.metadata - Additional metadata
+   * @param {String} params.idempotencyKey - Idempotency key for duplicate prevention
    * @returns {Promise<Object>} { subscription, transaction, paymentIntent }
    */
   async renew(subscriptionId, params = {}) {
     const {
       gateway = 'manual',
+      entity = null,
       paymentData,
       metadata = {},
       idempotencyKey = null,
     } = params;
 
     if (!this.models.Subscription) {
-      throw new Error('Subscription model not registered');
+      throw new ModelNotRegisteredError('Subscription');
     }
 
     const SubscriptionModel = this.models.Subscription;
     const subscription = await SubscriptionModel.findById(subscriptionId);
 
     if (!subscription) {
-      throw new Error('Subscription not found');
+      throw new SubscriptionNotFoundError(subscriptionId);
     }
 
     if (subscription.amount === 0) {
-      throw new Error('Free subscriptions do not require renewal');
+      throw new InvalidAmountError(0, 'Free subscriptions do not require renewal');
     }
 
     // Get provider
     const provider = this.providers[gateway];
     if (!provider) {
-      throw new Error(`Payment provider "${gateway}" not found`);
+      throw new ProviderNotFoundError(gateway, Object.keys(this.providers));
     }
 
     // Create payment intent
@@ -260,6 +288,17 @@ export class SubscriptionService {
       },
     });
 
+    // Resolve category - use provided entity or inherit from subscription metadata
+    const effectiveEntity = entity || subscription.metadata?.entity;
+    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({
@@ -267,8 +306,9 @@ export class SubscriptionService {
       customerId: subscription.customerId,
       amount: subscription.amount,
       currency: subscription.currency || 'BDT',
-      category: 'platform_subscription',
-      type: 'credit',
+      category,
+      type: transactionType,
+      method: paymentData?.method || 'manual',
       status: paymentIntent.status === 'succeeded' ? 'verified' : 'pending',
       gateway: {
         type: gateway,
@@ -282,6 +322,8 @@ export class SubscriptionService {
       metadata: {
         ...metadata,
         subscriptionId: subscription._id.toString(),
+        entity: effectiveEntity,
+        monetizationType: effectiveMonetizationType,
         isRenewal: true,
         paymentIntentId: paymentIntent.id,
       },
@@ -322,14 +364,14 @@ export class SubscriptionService {
     const { immediate = false, reason = null } = options;
 
     if (!this.models.Subscription) {
-      throw new Error('Subscription model not registered');
+      throw new ModelNotRegisteredError('Subscription');
     }
 
     const SubscriptionModel = this.models.Subscription;
     const subscription = await SubscriptionModel.findById(subscriptionId);
 
     if (!subscription) {
-      throw new Error('Subscription not found');
+      throw new SubscriptionNotFoundError(subscriptionId);
     }
 
     const now = new Date();
@@ -369,18 +411,18 @@ export class SubscriptionService {
     const { reason = null } = options;
 
     if (!this.models.Subscription) {
-      throw new Error('Subscription model not registered');
+      throw new ModelNotRegisteredError('Subscription');
     }
 
     const SubscriptionModel = this.models.Subscription;
     const subscription = await SubscriptionModel.findById(subscriptionId);
 
     if (!subscription) {
-      throw new Error('Subscription not found');
+      throw new SubscriptionNotFoundError(subscriptionId);
     }
 
     if (!subscription.isActive) {
-      throw new Error('Only active subscriptions can be paused');
+      throw new SubscriptionNotActiveError(subscriptionId, 'Only active subscriptions can be paused');
     }
 
     const pausedAt = new Date();
@@ -412,18 +454,23 @@ export class SubscriptionService {
     const { extendPeriod = false } = options;
 
     if (!this.models.Subscription) {
-      throw new Error('Subscription model not registered');
+      throw new ModelNotRegisteredError('Subscription');
     }
 
     const SubscriptionModel = this.models.Subscription;
     const subscription = await SubscriptionModel.findById(subscriptionId);
 
     if (!subscription) {
-      throw new Error('Subscription not found');
+      throw new SubscriptionNotFoundError(subscriptionId);
     }
 
     if (!subscription.pausedAt) {
-      throw new Error('Only paused subscriptions can be resumed');
+      throw new InvalidStateTransitionError(
+        'resume',
+        'paused',
+        subscription.status,
+        'Only paused subscriptions can be resumed'
+      );
     }
 
     const now = new Date();
@@ -463,7 +510,7 @@ export class SubscriptionService {
    */
   async list(filters = {}, options = {}) {
     if (!this.models.Subscription) {
-      throw new Error('Subscription model not registered');
+      throw new ModelNotRegisteredError('Subscription');
     }
 
     const SubscriptionModel = this.models.Subscription;
@@ -486,14 +533,14 @@ export class SubscriptionService {
    */
   async get(subscriptionId) {
     if (!this.models.Subscription) {
-      throw new Error('Subscription model not registered');
+      throw new ModelNotRegisteredError('Subscription');
     }
 
     const SubscriptionModel = this.models.Subscription;
     const subscription = await SubscriptionModel.findById(subscriptionId);
 
     if (!subscription) {
-      throw new Error('Subscription not found');
+      throw new SubscriptionNotFoundError(subscriptionId);
     }
 
     return subscription;