@classytic/revenue 0.0.1

package/services/subscription.service.js

@@ -0,0 +1,537 @@
+/**
+ * Subscription Service
+ * @classytic/revenue
+ *
+ * Framework-agnostic subscription management service with DI
+ * Handles complete subscription lifecycle using provider system
+ */
+
+import { nanoid } from 'nanoid';
+import {
+  MissingRequiredFieldError,
+  InvalidAmountError,
+  ProviderNotFoundError,
+  SubscriptionNotFoundError,
+  ModelNotRegisteredError,
+  SubscriptionNotActiveError,
+  PaymentIntentCreationError,
+} from '../core/errors.js';
+import { triggerHook } from '../utils/hooks.js';
+
+/**
+ * Subscription Service
+ * Uses DI container for all dependencies
+ */
+export class SubscriptionService {
+  constructor(container) {
+    this.container = container;
+    this.models = container.get('models');
+    this.providers = container.get('providers');
+    this.config = container.get('config');
+    this.hooks = container.get('hooks');
+    this.logger = container.get('logger');
+  }
+
+  /**
+   * Create a new subscription
+   *
+   * @param {Object} params - Subscription parameters
+   * @param {Object} params.data - Subscription data (organizationId, customerId, etc.)
+   * @param {String} params.planKey - Plan key ('monthly', 'quarterly', 'yearly')
+   * @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 {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 create(params) {
+    const {
+      data,
+      planKey,
+      amount,
+      currency = 'BDT',
+      gateway = 'manual',
+      paymentData,
+      metadata = {},
+      idempotencyKey = null,
+    } = params;
+
+    // Validate required fields
+    if (!data.organizationId) {
+      throw new MissingRequiredFieldError('organizationId');
+    }
+
+    if (!planKey) {
+      throw new MissingRequiredFieldError('planKey');
+    }
+
+    if (amount < 0) {
+      throw new InvalidAmountError(amount);
+    }
+
+    const isFree = amount === 0;
+
+    // Get provider
+    const provider = this.providers[gateway];
+    if (!provider) {
+      throw new ProviderNotFoundError(gateway, Object.keys(this.providers));
+    }
+
+    // Create payment intent if not free
+    let paymentIntent = null;
+    let transaction = null;
+
+    if (!isFree) {
+      // Create payment intent via provider
+      try {
+        paymentIntent = await provider.createIntent({
+          amount,
+          currency,
+          metadata: {
+            ...metadata,
+            type: 'subscription',
+            planKey,
+          },
+        });
+      } catch (error) {
+        throw new PaymentIntentCreationError(gateway, error);
+      }
+
+      // Create transaction record
+      const TransactionModel = this.models.Transaction;
+      transaction = await TransactionModel.create({
+        organizationId: data.organizationId,
+        customerId: data.customerId || null,
+        amount,
+        currency,
+        category: 'platform_subscription',
+        type: 'credit',
+        status: paymentIntent.status === 'succeeded' ? 'verified' : 'pending',
+        gateway: {
+          type: gateway,
+          paymentIntentId: paymentIntent.id,
+          provider: paymentIntent.provider,
+        },
+        paymentDetails: {
+          provider: gateway,
+          ...paymentData,
+        },
+        metadata: {
+          ...metadata,
+          planKey,
+          paymentIntentId: paymentIntent.id,
+        },
+        idempotencyKey: idempotencyKey || `sub_${nanoid(16)}`,
+      });
+    }
+
+    // Create subscription record (if Subscription model exists)
+    let subscription = null;
+    if (this.models.Subscription) {
+      const SubscriptionModel = this.models.Subscription;
+
+      subscription = await SubscriptionModel.create({
+        organizationId: data.organizationId,
+        customerId: data.customerId || null,
+        planKey,
+        amount,
+        currency,
+        status: isFree ? 'active' : 'pending',
+        isActive: isFree,
+        gateway,
+        transactionId: transaction?._id || null,
+        paymentIntentId: paymentIntent?.id || null,
+        metadata: {
+          ...metadata,
+          isFree,
+        },
+        ...data,
+      });
+    }
+
+    // Trigger hook
+    this._triggerHook('subscription.created', {
+      subscription,
+      transaction,
+      paymentIntent,
+      isFree,
+    });
+
+    return {
+      subscription,
+      transaction,
+      paymentIntent,
+    };
+  }
+
+  /**
+   * Activate subscription after payment verification
+   *
+   * @param {String} subscriptionId - Subscription ID or transaction ID
+   * @param {Object} options - Activation options
+   * @returns {Promise<Object>} Updated subscription
+   */
+  async activate(subscriptionId, options = {}) {
+    const { timestamp = new Date() } = options;
+
+    if (!this.models.Subscription) {
+      throw new ModelNotRegisteredError('Subscription');
+    }
+
+    const SubscriptionModel = this.models.Subscription;
+    const subscription = await SubscriptionModel.findById(subscriptionId);
+
+    if (!subscription) {
+      throw new SubscriptionNotFoundError(subscriptionId);
+    }
+
+    if (subscription.isActive) {
+      this.logger.warn('Subscription already active', { subscriptionId });
+      return subscription;
+    }
+
+    // Calculate period dates based on plan
+    const periodEnd = this._calculatePeriodEnd(subscription.planKey, timestamp);
+
+    // Update subscription
+    subscription.isActive = true;
+    subscription.status = 'active';
+    subscription.startDate = timestamp;
+    subscription.endDate = periodEnd;
+    subscription.activatedAt = timestamp;
+
+    await subscription.save();
+
+    // Trigger hook
+    this._triggerHook('subscription.activated', {
+      subscription,
+      activatedAt: timestamp,
+    });
+
+    return subscription;
+  }
+
+  /**
+   * Renew subscription
+   *
+   * @param {String} subscriptionId - Subscription ID
+   * @param {Object} params - Renewal parameters
+   * @returns {Promise<Object>} { subscription, transaction, paymentIntent }
+   */
+  async renew(subscriptionId, params = {}) {
+    const {
+      gateway = 'manual',
+      paymentData,
+      metadata = {},
+      idempotencyKey = null,
+    } = params;
+
+    if (!this.models.Subscription) {
+      throw new Error('Subscription model not registered');
+    }
+
+    const SubscriptionModel = this.models.Subscription;
+    const subscription = await SubscriptionModel.findById(subscriptionId);
+
+    if (!subscription) {
+      throw new Error('Subscription not found');
+    }
+
+    if (subscription.amount === 0) {
+      throw new Error('Free subscriptions do not require renewal');
+    }
+
+    // Get provider
+    const provider = this.providers[gateway];
+    if (!provider) {
+      throw new Error(`Payment provider "${gateway}" not found`);
+    }
+
+    // Create payment intent
+    const paymentIntent = await provider.createIntent({
+      amount: subscription.amount,
+      currency: subscription.currency || 'BDT',
+      metadata: {
+        ...metadata,
+        type: 'subscription_renewal',
+        subscriptionId: subscription._id.toString(),
+      },
+    });
+
+    // Create transaction
+    const TransactionModel = this.models.Transaction;
+    const transaction = await TransactionModel.create({
+      organizationId: subscription.organizationId,
+      customerId: subscription.customerId,
+      amount: subscription.amount,
+      currency: subscription.currency || 'BDT',
+      category: 'platform_subscription',
+      type: 'credit',
+      status: paymentIntent.status === 'succeeded' ? 'verified' : 'pending',
+      gateway: {
+        type: gateway,
+        paymentIntentId: paymentIntent.id,
+        provider: paymentIntent.provider,
+      },
+      paymentDetails: {
+        provider: gateway,
+        ...paymentData,
+      },
+      metadata: {
+        ...metadata,
+        subscriptionId: subscription._id.toString(),
+        isRenewal: true,
+        paymentIntentId: paymentIntent.id,
+      },
+      idempotencyKey: idempotencyKey || `renewal_${nanoid(16)}`,
+    });
+
+    // Update subscription
+    subscription.status = 'pending_renewal';
+    subscription.renewalTransactionId = transaction._id;
+    subscription.renewalCount = (subscription.renewalCount || 0) + 1;
+    await subscription.save();
+
+    // Trigger hook
+    this._triggerHook('subscription.renewed', {
+      subscription,
+      transaction,
+      paymentIntent,
+      renewalCount: subscription.renewalCount,
+    });
+
+    return {
+      subscription,
+      transaction,
+      paymentIntent,
+    };
+  }
+
+  /**
+   * Cancel subscription
+   *
+   * @param {String} subscriptionId - Subscription ID
+   * @param {Object} options - Cancellation options
+   * @param {Boolean} options.immediate - Cancel immediately vs at period end
+   * @param {String} options.reason - Cancellation reason
+   * @returns {Promise<Object>} Updated subscription
+   */
+  async cancel(subscriptionId, options = {}) {
+    const { immediate = false, reason = null } = options;
+
+    if (!this.models.Subscription) {
+      throw new Error('Subscription model not registered');
+    }
+
+    const SubscriptionModel = this.models.Subscription;
+    const subscription = await SubscriptionModel.findById(subscriptionId);
+
+    if (!subscription) {
+      throw new Error('Subscription not found');
+    }
+
+    const now = new Date();
+
+    if (immediate) {
+      subscription.isActive = false;
+      subscription.status = 'cancelled';
+      subscription.canceledAt = now;
+      subscription.cancellationReason = reason;
+    } else {
+      // Schedule cancellation at period end
+      subscription.cancelAt = subscription.endDate || now;
+      subscription.cancellationReason = reason;
+    }
+
+    await subscription.save();
+
+    // Trigger hook
+    this._triggerHook('subscription.cancelled', {
+      subscription,
+      immediate,
+      reason,
+      canceledAt: immediate ? now : subscription.cancelAt,
+    });
+
+    return subscription;
+  }
+
+  /**
+   * Pause subscription
+   *
+   * @param {String} subscriptionId - Subscription ID
+   * @param {Object} options - Pause options
+   * @returns {Promise<Object>} Updated subscription
+   */
+  async pause(subscriptionId, options = {}) {
+    const { reason = null } = options;
+
+    if (!this.models.Subscription) {
+      throw new Error('Subscription model not registered');
+    }
+
+    const SubscriptionModel = this.models.Subscription;
+    const subscription = await SubscriptionModel.findById(subscriptionId);
+
+    if (!subscription) {
+      throw new Error('Subscription not found');
+    }
+
+    if (!subscription.isActive) {
+      throw new Error('Only active subscriptions can be paused');
+    }
+
+    const pausedAt = new Date();
+    subscription.isActive = false;
+    subscription.status = 'paused';
+    subscription.pausedAt = pausedAt;
+    subscription.pauseReason = reason;
+
+    await subscription.save();
+
+    // Trigger hook
+    this._triggerHook('subscription.paused', {
+      subscription,
+      reason,
+      pausedAt,
+    });
+
+    return subscription;
+  }
+
+  /**
+   * Resume subscription
+   *
+   * @param {String} subscriptionId - Subscription ID
+   * @param {Object} options - Resume options
+   * @returns {Promise<Object>} Updated subscription
+   */
+  async resume(subscriptionId, options = {}) {
+    const { extendPeriod = false } = options;
+
+    if (!this.models.Subscription) {
+      throw new Error('Subscription model not registered');
+    }
+
+    const SubscriptionModel = this.models.Subscription;
+    const subscription = await SubscriptionModel.findById(subscriptionId);
+
+    if (!subscription) {
+      throw new Error('Subscription not found');
+    }
+
+    if (!subscription.pausedAt) {
+      throw new Error('Only paused subscriptions can be resumed');
+    }
+
+    const now = new Date();
+    const pausedAt = new Date(subscription.pausedAt);
+    const pauseDuration = now - pausedAt;
+
+    subscription.isActive = true;
+    subscription.status = 'active';
+    subscription.pausedAt = null;
+    subscription.pauseReason = null;
+
+    // Optionally extend period by pause duration
+    if (extendPeriod && subscription.endDate) {
+      const currentEnd = new Date(subscription.endDate);
+      subscription.endDate = new Date(currentEnd.getTime() + pauseDuration);
+    }
+
+    await subscription.save();
+
+    // Trigger hook
+    this._triggerHook('subscription.resumed', {
+      subscription,
+      extendPeriod,
+      pauseDuration,
+      resumedAt: now,
+    });
+
+    return subscription;
+  }
+
+  /**
+   * List subscriptions with filters
+   *
+   * @param {Object} filters - Query filters
+   * @param {Object} options - Query options (limit, skip, sort)
+   * @returns {Promise<Array>} Subscriptions
+   */
+  async list(filters = {}, options = {}) {
+    if (!this.models.Subscription) {
+      throw new Error('Subscription model not registered');
+    }
+
+    const SubscriptionModel = this.models.Subscription;
+    const { limit = 50, skip = 0, sort = { createdAt: -1 } } = options;
+
+    const subscriptions = await SubscriptionModel
+      .find(filters)
+      .limit(limit)
+      .skip(skip)
+      .sort(sort);
+
+    return subscriptions;
+  }
+
+  /**
+   * Get subscription by ID
+   *
+   * @param {String} subscriptionId - Subscription ID
+   * @returns {Promise<Object>} Subscription
+   */
+  async get(subscriptionId) {
+    if (!this.models.Subscription) {
+      throw new Error('Subscription model not registered');
+    }
+
+    const SubscriptionModel = this.models.Subscription;
+    const subscription = await SubscriptionModel.findById(subscriptionId);
+
+    if (!subscription) {
+      throw new Error('Subscription not found');
+    }
+
+    return subscription;
+  }
+
+  /**
+   * Calculate period end date based on plan key
+   * @private
+   */
+  _calculatePeriodEnd(planKey, startDate = new Date()) {
+    const start = new Date(startDate);
+    let end = new Date(start);
+
+    switch (planKey) {
+      case 'monthly':
+        end.setMonth(end.getMonth() + 1);
+        break;
+      case 'quarterly':
+        end.setMonth(end.getMonth() + 3);
+        break;
+      case 'yearly':
+        end.setFullYear(end.getFullYear() + 1);
+        break;
+      default:
+        // Default to 30 days
+        end.setDate(end.getDate() + 30);
+    }
+
+    return end;
+  }
+
+  /**
+   * Trigger event hook (fire-and-forget, non-blocking)
+   * @private
+   */
+  _triggerHook(event, data) {
+    triggerHook(this.hooks, event, data, this.logger);
+  }
+}
+
+export default SubscriptionService;

package/services/transaction.service.js

@@ -0,0 +1,142 @@
+/**
+ * Transaction Service
+ * @classytic/revenue
+ *
+ * Thin, focused transaction service for core operations
+ * Users handle their own analytics, exports, and complex queries
+ *
+ * Works with ANY model implementation:
+ * - Plain Mongoose models
+ * - @classytic/mongokit Repository instances
+ * - Any other abstraction with compatible interface
+ */
+
+import { TransactionNotFoundError } from '../core/errors.js';
+import { triggerHook } from '../utils/hooks.js';
+
+/**
+ * Transaction Service
+ * Focused on core transaction lifecycle operations
+ */
+export class TransactionService {
+  constructor(container) {
+    this.container = container;
+    this.models = container.get('models');
+    this.hooks = container.get('hooks');
+    this.logger = container.get('logger');
+  }
+
+  /**
+   * Get transaction by ID
+   *
+   * @param {String} transactionId - Transaction ID
+   * @returns {Promise<Object>} Transaction
+   */
+  async get(transactionId) {
+    const TransactionModel = this.models.Transaction;
+    const transaction = await TransactionModel.findById(transactionId);
+
+    if (!transaction) {
+      throw new TransactionNotFoundError(transactionId);
+    }
+
+    return transaction;
+  }
+
+  /**
+   * List transactions with filters
+   *
+   * @param {Object} filters - Query filters
+   * @param {Object} options - Query options (limit, skip, sort, populate)
+   * @returns {Promise<Object>} { transactions, total, page, limit }
+   */
+  async list(filters = {}, options = {}) {
+    const TransactionModel = this.models.Transaction;
+    const {
+      limit = 50,
+      skip = 0,
+      page = null,
+      sort = { createdAt: -1 },
+      populate = [],
+    } = options;
+
+    // Calculate pagination
+    const actualSkip = page ? (page - 1) * limit : skip;
+
+    // Build query
+    let query = TransactionModel.find(filters)
+      .limit(limit)
+      .skip(actualSkip)
+      .sort(sort);
+
+    // Apply population if supported
+    if (populate.length > 0 && typeof query.populate === 'function') {
+      populate.forEach(field => {
+        query = query.populate(field);
+      });
+    }
+
+    const transactions = await query;
+
+    // Count documents (works with both Mongoose and Repository)
+    const total = await (TransactionModel.countDocuments
+      ? TransactionModel.countDocuments(filters)
+      : TransactionModel.count(filters));
+
+    return {
+      transactions,
+      total,
+      page: page || Math.floor(actualSkip / limit) + 1,
+      limit,
+      pages: Math.ceil(total / limit),
+    };
+  }
+
+
+  /**
+   * Update transaction
+   *
+   * @param {String} transactionId - Transaction ID
+   * @param {Object} updates - Fields to update
+   * @returns {Promise<Object>} Updated transaction
+   */
+  async update(transactionId, updates) {
+    const TransactionModel = this.models.Transaction;
+
+    // Support both Repository pattern and Mongoose
+    let transaction;
+    if (typeof TransactionModel.update === 'function') {
+      // Repository pattern
+      transaction = await TransactionModel.update(transactionId, updates);
+    } else {
+      // Plain Mongoose
+      transaction = await TransactionModel.findByIdAndUpdate(
+        transactionId,
+        { $set: updates },
+        { new: true }
+      );
+    }
+
+    if (!transaction) {
+      throw new TransactionNotFoundError(transactionId);
+    }
+
+    // Trigger hook (fire-and-forget, non-blocking)
+    this._triggerHook('transaction.updated', {
+      transaction,
+      updates,
+    });
+
+    return transaction;
+  }
+
+  /**
+   * Trigger event hook (fire-and-forget, non-blocking)
+   * @private
+   */
+  _triggerHook(event, data) {
+    triggerHook(this.hooks, event, data, this.logger);
+  }
+}
+
+export default TransactionService;

package/utils/hooks.js

@@ -0,0 +1,44 @@
+/**
+ * Hook Utilities
+ * @classytic/revenue
+ *
+ * Fire-and-forget hook execution - never blocks main flow
+ */
+
+/**
+ * Trigger hooks asynchronously without waiting
+ * Errors are logged but never thrown
+ *
+ * @param {Object} hooks - Hooks object
+ * @param {string} event - Event name
+ * @param {Object} data - Event data
+ * @param {Object} logger - Logger instance
+ */
+export function triggerHook(hooks, event, data, logger) {
+  const handlers = hooks[event] || [];
+
+  if (handlers.length === 0) {
+    return; // No handlers, return immediately
+  }
+
+  // Fire-and-forget: Don't await, don't block
+  Promise.all(
+    handlers.map(handler =>
+      Promise.resolve(handler(data)).catch(error => {
+        logger.error(`Hook "${event}" failed:`, {
+          error: error.message,
+          stack: error.stack,
+          event,
+          // Don't log full data (could be huge)
+          dataKeys: Object.keys(data),
+        });
+      })
+    )
+  ).catch(() => {
+    // Swallow any Promise.all errors (already logged individually)
+  });
+
+  // Return immediately - hooks run in background
+}
+
+export default triggerHook;