@classytic/revenue 0.0.1 → 0.0.21

package/README.md

@@ -21,6 +21,51 @@ Thin, focused, production-ready library with smart defaults. Built for SaaS, mar
 npm install @classytic/revenue
 ```
 
+## Core Concepts
+
+### 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
+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
+    }
+  }
+});
+
+// All these use SUBSCRIPTION monetization type but different categories
+await revenue.subscriptions.create({
+  entity: 'Order',                // Logical identifier → maps to 'order_subscription'
+  monetizationType: 'subscription',
+  // ...
+});
+
+await revenue.subscriptions.create({
+  entity: 'PlatformSubscription',  // Logical identifier → maps to 'platform_subscription'
+  monetizationType: 'subscription',
+  // ...
+});
+```
+
+**Note:** `entity` is NOT a database model name - it's just a logical identifier you choose to organize your business logic.
+
 ## Transaction Model Setup
 
 Spread library enums/schemas into your Transaction model:
@@ -37,9 +82,13 @@ import {
   paymentDetailsSchema,
 } from '@classytic/revenue/schemas';
 
-// Merge library categories with your own
+// Merge library categories with your custom ones
 const MY_CATEGORIES = {
-  ...LIBRARY_CATEGORIES,  // subscription, purchase
+  ...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',
@@ -91,6 +140,145 @@ const { subscription, transaction } = await revenue.subscriptions.create({
 
 That's it! The package works immediately with sensible defaults.
 
+## Real-World Use Cases
+
+### E-commerce Platform with Multiple Order Types
+
+```javascript
+// Setup
+const revenue = createRevenue({
+  models: { Transaction },
+  config: {
+    categoryMappings: {
+      Order: 'order_subscription',      // Recurring orders (meal kits, subscriptions)
+      Purchase: 'order_purchase',        // One-time orders
+    }
+  }
+});
+
+// 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' }
+});
+// 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'
+```
+
+### Gym Management System
+
+```javascript
+// Setup
+const revenue = createRevenue({
+  models: { Transaction },
+  config: {
+    categoryMappings: {
+      Membership: 'gym_membership',
+      PersonalTraining: 'personal_training',
+      DayPass: 'day_pass',
+    }
+  }
+});
+
+// Monthly gym membership
+await revenue.subscriptions.create({
+  entity: 'Membership',
+  monetizationType: 'subscription',
+  planKey: 'monthly',
+  amount: 59.99,
+});
+// Transaction: 'gym_membership'
+
+// Personal training package (one-time purchase)
+await revenue.subscriptions.create({
+  entity: 'PersonalTraining',
+  monetizationType: 'purchase',
+  amount: 299.99,
+});
+// Transaction: 'personal_training'
+
+// Day pass (free trial)
+await revenue.subscriptions.create({
+  entity: 'DayPass',
+  monetizationType: 'free',
+  amount: 0,
+});
+// No transaction created for free
+```
+
+### Online Learning Platform
+
+```javascript
+// Setup
+const revenue = createRevenue({
+  models: { Transaction },
+  config: {
+    categoryMappings: {
+      CourseEnrollment: 'course_enrollment',
+      MembershipPlan: 'membership_plan',
+    }
+  }
+});
+
+// One-time course purchase
+await revenue.subscriptions.create({
+  entity: 'CourseEnrollment',
+  monetizationType: 'purchase',
+  amount: 99.00,
+  metadata: { courseId: 'react-advanced' }
+});
+// Transaction: 'course_enrollment'
+
+// Monthly all-access membership
+await revenue.subscriptions.create({
+  entity: 'MembershipPlan',
+  monetizationType: 'subscription',
+  planKey: 'monthly',
+  amount: 29.99,
+});
+// Transaction: 'membership_plan'
+```
+
+### Without Category Mappings (Defaults)
+
+```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,
+});
+// Transaction created with category: 'purchase' (library default)
+```
+
 ## Usage Examples
 
 ### With Payment Provider

package/enums/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * TypeScript definitions for @classytic/revenue/enums
+ * Centralized Enums
+ */
+
+// ============ TRANSACTION ENUMS ============
+
+export const TRANSACTION_STATUS: {
+  readonly PENDING: 'pending';
+  readonly PAYMENT_INITIATED: 'payment_initiated';
+  readonly PROCESSING: 'processing';
+  readonly REQUIRES_ACTION: 'requires_action';
+  readonly VERIFIED: 'verified';
+  readonly COMPLETED: 'completed';
+  readonly FAILED: 'failed';
+  readonly CANCELLED: 'cancelled';
+  readonly EXPIRED: 'expired';
+  readonly REFUNDED: 'refunded';
+  readonly PARTIALLY_REFUNDED: 'partially_refunded';
+};
+
+export const TRANSACTION_STATUS_VALUES: string[];
+
+export const LIBRARY_CATEGORIES: {
+  readonly SUBSCRIPTION: 'subscription';
+  readonly PURCHASE: 'purchase';
+};
+
+export const LIBRARY_CATEGORY_VALUES: string[];
+
+// ============ PAYMENT ENUMS ============
+
+export const PAYMENT_STATUS: {
+  readonly PENDING: 'pending';
+  readonly VERIFIED: 'verified';
+  readonly FAILED: 'failed';
+  readonly REFUNDED: 'refunded';
+  readonly CANCELLED: 'cancelled';
+};
+
+export const PAYMENT_STATUS_VALUES: string[];
+
+export const PAYMENT_GATEWAY_TYPE: {
+  readonly MANUAL: 'manual';
+  readonly STRIPE: 'stripe';
+  readonly SSLCOMMERZ: 'sslcommerz';
+};
+
+export const PAYMENT_GATEWAY_TYPE_VALUES: string[];
+
+// Backward compatibility aliases
+export const GATEWAY_TYPES: typeof PAYMENT_GATEWAY_TYPE;
+export const GATEWAY_TYPE_VALUES: typeof PAYMENT_GATEWAY_TYPE_VALUES;
+
+// ============ SUBSCRIPTION ENUMS ============
+
+export const SUBSCRIPTION_STATUS: {
+  readonly ACTIVE: 'active';
+  readonly PAUSED: 'paused';
+  readonly CANCELLED: 'cancelled';
+  readonly EXPIRED: 'expired';
+  readonly PENDING: 'pending';
+  readonly INACTIVE: 'inactive';
+};
+
+export const SUBSCRIPTION_STATUS_VALUES: string[];
+
+export const PLAN_KEYS: {
+  readonly MONTHLY: 'monthly';
+  readonly QUARTERLY: 'quarterly';
+  readonly YEARLY: 'yearly';
+};
+
+export const PLAN_KEY_VALUES: string[];
+
+// ============ MONETIZATION ENUMS ============
+
+export const MONETIZATION_TYPES: {
+  readonly FREE: 'free';
+  readonly PURCHASE: 'purchase';
+  readonly SUBSCRIPTION: 'subscription';
+};
+
+export const MONETIZATION_TYPE_VALUES: string[];
+
+// ============ DEFAULT EXPORT ============
+
+declare const _default: {
+  TRANSACTION_STATUS: typeof TRANSACTION_STATUS;
+  TRANSACTION_STATUS_VALUES: typeof TRANSACTION_STATUS_VALUES;
+  LIBRARY_CATEGORIES: typeof LIBRARY_CATEGORIES;
+  LIBRARY_CATEGORY_VALUES: typeof LIBRARY_CATEGORY_VALUES;
+  PAYMENT_STATUS: typeof PAYMENT_STATUS;
+  PAYMENT_STATUS_VALUES: typeof PAYMENT_STATUS_VALUES;
+  PAYMENT_GATEWAY_TYPE: typeof PAYMENT_GATEWAY_TYPE;
+  PAYMENT_GATEWAY_TYPE_VALUES: typeof PAYMENT_GATEWAY_TYPE_VALUES;
+  GATEWAY_TYPES: typeof GATEWAY_TYPES;
+  GATEWAY_TYPE_VALUES: typeof GATEWAY_TYPE_VALUES;
+  SUBSCRIPTION_STATUS: typeof SUBSCRIPTION_STATUS;
+  SUBSCRIPTION_STATUS_VALUES: typeof SUBSCRIPTION_STATUS_VALUES;
+  PLAN_KEYS: typeof PLAN_KEYS;
+  PLAN_KEY_VALUES: typeof PLAN_KEY_VALUES;
+  MONETIZATION_TYPES: typeof MONETIZATION_TYPES;
+  MONETIZATION_TYPE_VALUES: typeof MONETIZATION_TYPE_VALUES;
+};
+
+export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/revenue",
-  "version": "0.0.1",
+  "version": "0.0.21",
   "description": "Enterprise revenue management system with subscriptions, purchases, proration, and payment processing",
   "main": "index.js",
   "types": "revenue.d.ts",
@@ -39,10 +39,22 @@
     "node": ">=18.0.0"
   },
   "exports": {
-    ".": "./index.js",
-    "./enums": "./enums/index.js",
-    "./schemas": "./schemas/index.js",
-    "./utils": "./utils/index.js"
+    ".": {
+      "types": "./revenue.d.ts",
+      "default": "./index.js"
+    },
+    "./enums": {
+      "types": "./enums/index.d.ts",
+      "default": "./enums/index.js"
+    },
+    "./schemas": {
+      "types": "./schemas/index.d.ts",
+      "default": "./schemas/index.js"
+    },
+    "./utils": {
+      "types": "./utils/index.d.ts",
+      "default": "./utils/index.js"
+    }
   },
   "files": [
     "index.js",

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>;
@@ -193,7 +201,23 @@ 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>;
     [key: string]: any;
   };
@@ -218,19 +242,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 +278,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

@@ -0,0 +1,33 @@
+/**
+ * TypeScript definitions for @classytic/revenue/schemas
+ * Core schemas for injection into your models
+ */
+
+import { Schema } from 'mongoose';
+
+// ============ TRANSACTION SCHEMAS ============
+
+export const currentPaymentSchema: Schema;
+export const paymentSummarySchema: Schema;
+export const paymentDetailsSchema: Schema;
+export const gatewaySchema: Schema;
+export const commissionSchema: Schema;
+
+// ============ SUBSCRIPTION SCHEMAS ============
+
+export const subscriptionInfoSchema: Schema;
+export const subscriptionPlanSchema: Schema;
+
+// ============ DEFAULT EXPORT ============
+
+declare const _default: {
+  currentPaymentSchema: Schema;
+  paymentSummarySchema: Schema;
+  paymentDetailsSchema: Schema;
+  gatewaySchema: Schema;
+  commissionSchema: Schema;
+  subscriptionInfoSchema: Schema;
+  subscriptionPlanSchema: Schema;
+};
+
+export default _default;

package/services/payment.service.js

@@ -132,7 +132,7 @@ export class PaymentService {
     }
 
     if (!transaction) {
-      throw new Error('Transaction not found');
+      throw new TransactionNotFoundError(paymentIntentId);
     }
 
     // Get provider
@@ -140,7 +140,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,7 +218,7 @@ 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
@@ -262,7 +262,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 +271,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 +286,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 +368,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 +383,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

@@ -17,6 +17,8 @@ import {
   PaymentIntentCreationError,
 } 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';
 
 /**
  * Subscription Service
@@ -41,6 +43,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 +58,8 @@ export class SubscriptionService {
       amount,
       currency = 'BDT',
       gateway = 'manual',
+      entity = null,
+      monetizationType = MONETIZATION_TYPES.SUBSCRIPTION,
       paymentData,
       metadata = {},
       idempotencyKey = null,
@@ -99,6 +106,9 @@ export class SubscriptionService {
         throw new PaymentIntentCreationError(gateway, error);
       }
 
+      // Resolve category based on entity and monetizationType
+      const category = resolveCategory(entity, monetizationType, this.config.categoryMappings);
+
       // Create transaction record
       const TransactionModel = this.models.Transaction;
       transaction = await TransactionModel.create({
@@ -106,7 +116,7 @@ export class SubscriptionService {
         customerId: data.customerId || null,
         amount,
         currency,
-        category: 'platform_subscription',
+        category,
         type: 'credit',
         status: paymentIntent.status === 'succeeded' ? 'verified' : 'pending',
         gateway: {
@@ -121,6 +131,8 @@ export class SubscriptionService {
         metadata: {
           ...metadata,
           planKey,
+          entity,
+          monetizationType,
           paymentIntentId: paymentIntent.id,
         },
         idempotencyKey: idempotencyKey || `sub_${nanoid(16)}`,
@@ -146,6 +158,8 @@ export class SubscriptionService {
         metadata: {
           ...metadata,
           isFree,
+          entity,
+          monetizationType,
         },
         ...data,
       });
@@ -218,35 +232,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 +280,11 @@ 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);
+
     // Create transaction
     const TransactionModel = this.models.Transaction;
     const transaction = await TransactionModel.create({
@@ -267,7 +292,7 @@ export class SubscriptionService {
       customerId: subscription.customerId,
       amount: subscription.amount,
       currency: subscription.currency || 'BDT',
-      category: 'platform_subscription',
+      category,
       type: 'credit',
       status: paymentIntent.status === 'succeeded' ? 'verified' : 'pending',
       gateway: {
@@ -282,6 +307,8 @@ export class SubscriptionService {
       metadata: {
         ...metadata,
         subscriptionId: subscription._id.toString(),
+        entity: effectiveEntity,
+        monetizationType: effectiveMonetizationType,
         isRenewal: true,
         paymentIntentId: paymentIntent.id,
       },
@@ -322,14 +349,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 +396,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 +439,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 +495,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 +518,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;

package/utils/category-resolver.js

@@ -0,0 +1,74 @@
+/**
+ * Category Resolver Utility
+ * @classytic/revenue
+ *
+ * Resolves transaction category based on referenceModel and categoryMappings
+ */
+
+import { LIBRARY_CATEGORIES } from '../enums/transaction.enums.js';
+
+/**
+ * Resolve category for a transaction based on entity and monetizationType
+ *
+ * Resolution Logic:
+ * 1. If categoryMappings[entity] exists → use it
+ * 2. Otherwise → fall back to default library category
+ *
+ * @param {String} entity - The logical entity/identifier (e.g., 'Order', 'PlatformSubscription', 'Membership')
+ *                          NOTE: This is NOT a database model name - it's just a logical identifier
+ * @param {String} monetizationType - The monetization type ('subscription', 'purchase', 'free')
+ * @param {Object} categoryMappings - User-defined category mappings from config
+ * @returns {String} Category name for the transaction
+ *
+ * @example
+ * // With mapping defined
+ * resolveCategory('Order', 'subscription', { Order: 'order_subscription' })
+ * // Returns: 'order_subscription'
+ *
+ * @example
+ * // Without mapping, falls back to library default
+ * resolveCategory('Order', 'subscription', {})
+ * // Returns: 'subscription'
+ *
+ * @example
+ * // Different entities with different mappings
+ * const mappings = {
+ *   Order: 'order_subscription',
+ *   PlatformSubscription: 'platform_subscription',
+ *   TenantUpgrade: 'tenant_upgrade',
+ *   Membership: 'gym_membership',
+ *   Enrollment: 'course_enrollment',
+ * };
+ * resolveCategory('PlatformSubscription', 'subscription', mappings)
+ * // Returns: 'platform_subscription'
+ */
+export function resolveCategory(entity, monetizationType, categoryMappings = {}) {
+  // If user has defined a custom mapping for this entity, use it
+  if (entity && categoryMappings[entity]) {
+    return categoryMappings[entity];
+  }
+
+  // Otherwise, fall back to library default based on monetization type
+  switch (monetizationType) {
+    case 'subscription':
+      return LIBRARY_CATEGORIES.SUBSCRIPTION; // 'subscription'
+    case 'purchase':
+      return LIBRARY_CATEGORIES.PURCHASE; // 'purchase'
+    default:
+      return LIBRARY_CATEGORIES.SUBSCRIPTION; // Default to subscription
+  }
+}
+
+/**
+ * Validate that a category is defined in user's Transaction model enum
+ * This is informational - actual validation happens at Mongoose schema level
+ *
+ * @param {String} category - Category to validate
+ * @param {Array<String>} allowedCategories - List of allowed categories
+ * @returns {Boolean} Whether category is valid
+ */
+export function isCategoryValid(category, allowedCategories = []) {
+  return allowedCategories.includes(category);
+}
+
+export default resolveCategory;

package/utils/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * TypeScript definitions for @classytic/revenue/utils
+ * Core utilities
+ */
+
+// ============ TRANSACTION TYPE UTILITIES ============
+
+export const TRANSACTION_TYPE: {
+  readonly MONETIZATION: 'monetization';
+  readonly MANUAL: 'manual';
+};
+
+export const PROTECTED_MONETIZATION_FIELDS: readonly string[];
+export const EDITABLE_MONETIZATION_FIELDS_PRE_VERIFICATION: readonly string[];
+export const MANUAL_TRANSACTION_CREATE_FIELDS: readonly string[];
+export const MANUAL_TRANSACTION_UPDATE_FIELDS: readonly string[];
+
+export interface TransactionTypeOptions {
+  targetModels?: string[];
+  additionalCategories?: string[];
+}
+
+export function isMonetizationTransaction(
+  transaction: any,
+  options?: TransactionTypeOptions
+): boolean;
+
+export function isManualTransaction(
+  transaction: any,
+  options?: TransactionTypeOptions
+): boolean;
+
+export function getTransactionType(
+  transaction: any,
+  options?: TransactionTypeOptions
+): 'monetization' | 'manual';
+
+export function getAllowedUpdateFields(
+  transaction: any,
+  options?: TransactionTypeOptions
+): string[];
+
+export interface FieldValidationResult {
+  allowed: boolean;
+  reason?: string;
+}
+
+export function validateFieldUpdate(
+  transaction: any,
+  fieldName: string,
+  options?: TransactionTypeOptions
+): FieldValidationResult;
+
+export function canSelfVerify(
+  transaction: any,
+  options?: TransactionTypeOptions
+): boolean;
+
+// ============ LOGGER UTILITIES ============
+
+export interface Logger {
+  info(...args: any[]): void;
+  warn(...args: any[]): void;
+  error(...args: any[]): void;
+  debug(...args: any[]): void;
+}
+
+export const logger: Logger;
+export function setLogger(logger: Logger | Console): void;
+
+// ============ HOOK UTILITIES ============
+
+export function triggerHook(
+  hooks: Record<string, Function[]>,
+  event: string,
+  data: any,
+  logger: Logger
+): void;
+
+// ============ DEFAULT EXPORT ============
+
+declare const _default: {
+  TRANSACTION_TYPE: typeof TRANSACTION_TYPE;
+  isMonetizationTransaction: typeof isMonetizationTransaction;
+  isManualTransaction: typeof isManualTransaction;
+  getTransactionType: typeof getTransactionType;
+  PROTECTED_MONETIZATION_FIELDS: typeof PROTECTED_MONETIZATION_FIELDS;
+  EDITABLE_MONETIZATION_FIELDS_PRE_VERIFICATION: typeof EDITABLE_MONETIZATION_FIELDS_PRE_VERIFICATION;
+  MANUAL_TRANSACTION_CREATE_FIELDS: typeof MANUAL_TRANSACTION_CREATE_FIELDS;
+  MANUAL_TRANSACTION_UPDATE_FIELDS: typeof MANUAL_TRANSACTION_UPDATE_FIELDS;
+  getAllowedUpdateFields: typeof getAllowedUpdateFields;
+  validateFieldUpdate: typeof validateFieldUpdate;
+  canSelfVerify: typeof canSelfVerify;
+  logger: typeof logger;
+  setLogger: typeof setLogger;
+  triggerHook: typeof triggerHook;
+};
+
+export default _default;

package/utils/logger.js

@@ -6,7 +6,7 @@
  *
  * Usage:
  * ```javascript
- * import { setLogger } from '@fitverse/monetization';
+ * import { setLogger } from '@classytic/revenue';
  *
  * // Optional: Use your own logger
  * setLogger(myPinoLogger);

package/providers/manual.js

@@ -1,171 +0,0 @@
-/**
- * Manual Payment Provider
- * @classytic/revenue
- *
- * Built-in provider for manual payment verification
- * Perfect for: Cash, bank transfers, mobile money without API
- */
-
-import { PaymentProvider, PaymentIntent, PaymentResult, RefundResult } from './base.js';
-import { nanoid } from 'nanoid';
-
-export class ManualProvider extends PaymentProvider {
-  constructor(config = {}) {
-    super(config);
-    this.name = 'manual';
-  }
-
-  /**
-   * Create manual payment intent
-   * Returns instructions for manual payment
-   */
-  async createIntent(params) {
-    const intentId = `manual_${nanoid(16)}`;
-
-    return new PaymentIntent({
-      id: intentId,
-      provider: 'manual',
-      status: 'pending',
-      amount: params.amount,
-      currency: params.currency || 'BDT',
-      metadata: params.metadata || {},
-      instructions: this._getPaymentInstructions(params),
-      raw: params,
-    });
-  }
-
-  /**
-   * Verify manual payment
-   * Note: This is called by admin after checking payment proof
-   */
-  async verifyPayment(intentId) {
-    // Manual verification doesn't auto-verify
-    // Admin must explicitly call payment verification endpoint
-    return new PaymentResult({
-      id: intentId,
-      provider: 'manual',
-      status: 'requires_manual_approval',
-      amount: 0, // Amount will be filled by transaction
-      currency: 'BDT',
-      metadata: {
-        message: 'Manual payment requires admin verification',
-      },
-    });
-  }
-
-  /**
-   * Get payment status
-   */
-  async getStatus(intentId) {
-    return this.verifyPayment(intentId);
-  }
-
-  /**
-   * Refund manual payment
-   */
-  async refund(paymentId, amount, options = {}) {
-    const refundId = `refund_${nanoid(16)}`;
-
-    return new RefundResult({
-      id: refundId,
-      provider: 'manual',
-      status: 'succeeded', // Manual refunds are immediately marked as succeeded
-      amount: amount,
-      currency: options.currency || 'BDT',
-      refundedAt: new Date(),
-      reason: options.reason || 'Manual refund',
-      metadata: options.metadata || {},
-    });
-  }
-
-  /**
-   * Manual provider doesn't support webhooks
-   */
-  async handleWebhook(payload, headers) {
-    throw new Error('Manual provider does not support webhooks');
-  }
-
-  /**
-   * Get provider capabilities
-   */
-  getCapabilities() {
-    return {
-      supportsWebhooks: false,
-      supportsRefunds: true,
-      supportsPartialRefunds: true,
-      requiresManualVerification: true,
-      supportedMethods: ['cash', 'bank', 'bkash', 'nagad', 'rocket', 'manual'],
-    };
-  }
-
-  /**
-   * Generate payment instructions for customer
-   * @private
-   */
-  _getPaymentInstructions(params) {
-    const { organizationPaymentInfo, method } = params.metadata || {};
-
-    if (!organizationPaymentInfo) {
-      return 'Please contact the organization for payment details.';
-    }
-
-    const instructions = [];
-
-    // Add method-specific instructions
-    switch (method) {
-      case 'bkash':
-      case 'nagad':
-      case 'rocket':
-        if (organizationPaymentInfo[`${method}Number`]) {
-          instructions.push(
-            `Send money via ${method.toUpperCase()}:`,
-            `Number: ${organizationPaymentInfo[`${method}Number`]}`,
-            `Amount: ${params.amount} ${params.currency || 'BDT'}`,
-            ``,
-            `After payment, provide the transaction ID/reference number.`
-          );
-        }
-        break;
-
-      case 'bank':
-        if (organizationPaymentInfo.bankAccount) {
-          const bank = organizationPaymentInfo.bankAccount;
-          instructions.push(
-            `Bank Transfer Details:`,
-            `Bank: ${bank.bankName || 'N/A'}`,
-            `Account: ${bank.accountNumber || 'N/A'}`,
-            `Account Name: ${bank.accountName || 'N/A'}`,
-            `Amount: ${params.amount} ${params.currency || 'BDT'}`,
-            ``,
-            `After payment, upload proof and provide reference.`
-          );
-        }
-        break;
-
-      case 'cash':
-        instructions.push(
-          `Cash Payment:`,
-          `Amount: ${params.amount} ${params.currency || 'BDT'}`,
-          ``,
-          `Pay at the organization's office and get a receipt.`
-        );
-        break;
-
-      default:
-        instructions.push(
-          `Payment Amount: ${params.amount} ${params.currency || 'BDT'}`,
-          ``,
-          `Contact the organization for payment details.`
-        );
-    }
-
-    // Add custom instructions if provided
-    if (organizationPaymentInfo.paymentInstructions) {
-      instructions.push(``, `Additional Instructions:`, organizationPaymentInfo.paymentInstructions);
-    }
-
-    return instructions.join('\n');
-  }
-}
-
-export default ManualProvider;