@classytic/revenue 0.2.4 → 1.0.0

package/services/payment.service.js

@@ -1,535 +0,0 @@
-/**
- * Payment Service
- * @classytic/revenue
- *
- * Framework-agnostic payment verification and management service with DI
- * Handles payment verification, refunds, and status updates
- */
-
-/**
- * @typedef {Object} PaymentVerifyResult
- * @property {Object} transaction - Updated transaction
- * @property {Object} paymentResult - Payment result from provider
- * @property {string} status - Payment status
- */
-
-/**
- * @typedef {Object} PaymentRefundResult
- * @property {Object} transaction - Original transaction (updated)
- * @property {Object} refundTransaction - New refund transaction record
- * @property {Object} refundResult - Refund result from provider
- * @property {string} status - Transaction status after refund
- */
-
-import {
-  TransactionNotFoundError,
-  ProviderNotFoundError,
-  ProviderError,
-  AlreadyVerifiedError,
-  PaymentVerificationError,
-  RefundNotSupportedError,
-  RefundError,
-  ProviderCapabilityError,
-  ValidationError,
-} from '../core/errors.js';
-import { triggerHook } from '../utils/hooks.js';
-import { reverseCommission } from '../utils/commission.js';
-import { TRANSACTION_TYPE } from '../enums/transaction.enums.js';
-
-/**
- * Payment Service
- * Uses DI container for all dependencies
- */
-export class PaymentService {
-  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');
-  }
-
-  /**
-   * Verify a payment
-   *
-   * @param {String} paymentIntentId - Payment intent ID, session ID, or transaction ID
-   * @param {Object} options - Verification options
-   * @param {String} options.verifiedBy - User ID who verified (for manual verification)
-   * @returns {Promise<Object>} { transaction, status }
-   */
-  async verify(paymentIntentId, options = {}) {
-    const { verifiedBy = null } = options;
-
-    const TransactionModel = this.models.Transaction;
-    let transaction = await this._findTransaction(TransactionModel, paymentIntentId);
-
-    if (!transaction) {
-      throw new TransactionNotFoundError(paymentIntentId);
-    }
-
-    if (transaction.status === 'verified' || transaction.status === 'completed') {
-      throw new AlreadyVerifiedError(transaction._id);
-    }
-
-    // Get provider for verification
-    const gatewayType = transaction.gateway?.type || 'manual';
-    const provider = this.providers[gatewayType];
-
-    if (!provider) {
-      throw new ProviderNotFoundError(gatewayType, Object.keys(this.providers));
-    }
-
-    // Verify payment with provider
-    let paymentResult = null;
-    try {
-      paymentResult = await provider.verifyPayment(paymentIntentId);
-    } catch (error) {
-      this.logger.error('Payment verification failed:', error);
-
-      // Update transaction as failed
-      transaction.status = 'failed';
-      transaction.failureReason = error.message;
-      transaction.metadata = {
-        ...transaction.metadata,
-        verificationError: error.message,
-        failedAt: new Date().toISOString(),
-      };
-      await transaction.save();
-
-      // Trigger payment.failed hook
-      this._triggerHook('payment.failed', {
-        transaction,
-        error: error.message,
-        provider: gatewayType,
-        paymentIntentId,
-      });
-
-      throw new PaymentVerificationError(paymentIntentId, error.message);
-    }
-
-    // Validate amount and currency match
-    if (paymentResult.amount && paymentResult.amount !== transaction.amount) {
-      throw new ValidationError(
-        `Amount mismatch: expected ${transaction.amount}, got ${paymentResult.amount}`,
-        { expected: transaction.amount, actual: paymentResult.amount }
-      );
-    }
-
-    if (paymentResult.currency && paymentResult.currency.toUpperCase() !== transaction.currency.toUpperCase()) {
-      throw new ValidationError(
-        `Currency mismatch: expected ${transaction.currency}, got ${paymentResult.currency}`,
-        { expected: transaction.currency, actual: paymentResult.currency }
-      );
-    }
-
-    // Update transaction based on verification result
-    transaction.status = paymentResult.status === 'succeeded' ? 'verified' : paymentResult.status;
-    transaction.verifiedAt = paymentResult.paidAt || new Date();
-    transaction.verifiedBy = verifiedBy;
-    transaction.gateway = {
-      ...transaction.gateway,
-      verificationData: paymentResult.metadata,
-    };
-
-    await transaction.save();
-
-    // Trigger hook
-    this._triggerHook('payment.verified', {
-      transaction,
-      paymentResult,
-      verifiedBy,
-    });
-
-    return {
-      transaction,
-      paymentResult,
-      status: transaction.status,
-    };
-  }
-
-  /**
-   * Get payment status
-   *
-   * @param {String} paymentIntentId - Payment intent ID, session ID, or transaction ID
-   * @returns {Promise<Object>} { transaction, status }
-   */
-  async getStatus(paymentIntentId) {
-    const TransactionModel = this.models.Transaction;
-    let transaction = await this._findTransaction(TransactionModel, paymentIntentId);
-
-    if (!transaction) {
-      throw new TransactionNotFoundError(paymentIntentId);
-    }
-
-    // Get provider
-    const gatewayType = transaction.gateway?.type || 'manual';
-    const provider = this.providers[gatewayType];
-
-    if (!provider) {
-      throw new ProviderNotFoundError(gatewayType, Object.keys(this.providers));
-    }
-
-    // Get status from provider
-    let paymentResult = null;
-    try {
-      paymentResult = await provider.getStatus(paymentIntentId);
-    } catch (error) {
-      this.logger.warn('Failed to get payment status from provider:', error);
-      // Return transaction status as fallback
-      return {
-        transaction,
-        status: transaction.status,
-        provider: gatewayType,
-      };
-    }
-
-    return {
-      transaction,
-      paymentResult,
-      status: paymentResult.status,
-      provider: gatewayType,
-    };
-  }
-
-  /**
-   * Refund a payment
-   *
-   * @param {String} paymentId - Payment intent ID, session ID, or transaction ID
-   * @param {Number} amount - Amount to refund (optional, full refund if not provided)
-   * @param {Object} options - Refund options
-   * @param {String} options.reason - Refund reason
-   * @returns {Promise<Object>} { transaction, refundResult }
-   */
-  async refund(paymentId, amount = null, options = {}) {
-    const { reason = null } = options;
-
-    const TransactionModel = this.models.Transaction;
-    let transaction = await this._findTransaction(TransactionModel, paymentId);
-
-    if (!transaction) {
-      throw new TransactionNotFoundError(paymentId);
-    }
-
-    if (transaction.status !== 'verified' && transaction.status !== 'completed') {
-      throw new RefundError(transaction._id, 'Only verified/completed transactions can be refunded');
-    }
-
-    // Get provider
-    const gatewayType = transaction.gateway?.type || 'manual';
-    const provider = this.providers[gatewayType];
-
-    if (!provider) {
-      throw new ProviderNotFoundError(gatewayType, Object.keys(this.providers));
-    }
-
-    // Check if provider supports refunds
-    const capabilities = provider.getCapabilities();
-    if (!capabilities.supportsRefunds) {
-      throw new RefundNotSupportedError(gatewayType);
-    }
-
-    // Calculate refundable amount
-    const refundedSoFar = transaction.refundedAmount || 0;
-    const refundableAmount = transaction.amount - refundedSoFar;
-    const refundAmount = amount || refundableAmount;
-
-    // Validate refund amount
-    if (refundAmount <= 0) {
-      throw new ValidationError(`Refund amount must be positive, got ${refundAmount}`);
-    }
-
-    if (refundAmount > refundableAmount) {
-      throw new ValidationError(
-        `Refund amount (${refundAmount}) exceeds refundable balance (${refundableAmount})`,
-        { refundAmount, refundableAmount, alreadyRefunded: refundedSoFar }
-      );
-    }
-
-    // Refund via provider
-    let refundResult = null;
-
-    try {
-      refundResult = await provider.refund(paymentId, refundAmount, { reason });
-    } catch (error) {
-      this.logger.error('Refund failed:', error);
-      throw new RefundError(paymentId, error.message);
-    }
-
-    // Create separate refund transaction (EXPENSE) for proper accounting
-    const refundTransactionType = this.config.transactionTypeMapping?.refund || TRANSACTION_TYPE.EXPENSE;
-    
-    // Reverse commission proportionally for refund
-    const refundCommission = transaction.commission 
-      ? reverseCommission(transaction.commission, transaction.amount, refundAmount)
-      : null;
-
-    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,
-      ...(refundCommission && { commission: refundCommission }), // Reversed commission
-      // Polymorphic reference (copy from original transaction)
-      ...(transaction.referenceId && { referenceId: transaction.referenceId }),
-      ...(transaction.referenceModel && { referenceModel: transaction.referenceModel }),
-      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,
-    };
-
-    await transaction.save();
-
-    // Trigger hook
-    this._triggerHook('payment.refunded', {
-      transaction,
-      refundTransaction,
-      refundResult,
-      refundAmount,
-      reason,
-      isPartialRefund,
-    });
-
-    return {
-      transaction,
-      refundTransaction,
-      refundResult,
-      status: transaction.status,
-    };
-  }
-
-  /**
-   * Handle webhook from payment provider
-   *
-   * @param {String} provider - Provider name
-   * @param {Object} payload - Webhook payload
-   * @param {Object} headers - Request headers
-   * @returns {Promise<Object>} { event, transaction }
-   */
-  async handleWebhook(providerName, payload, headers = {}) {
-    const provider = this.providers[providerName];
-
-    if (!provider) {
-      throw new ProviderNotFoundError(providerName, Object.keys(this.providers));
-    }
-
-    // Check if provider supports webhooks
-    const capabilities = provider.getCapabilities();
-    if (!capabilities.supportsWebhooks) {
-      throw new ProviderCapabilityError(providerName, 'webhooks');
-    }
-
-    // Process webhook via provider
-    let webhookEvent = null;
-    try {
-      webhookEvent = await provider.handleWebhook(payload, headers);
-    } catch (error) {
-      this.logger.error('Webhook processing failed:', error);
-      throw new ProviderError(
-        `Webhook processing failed for ${providerName}: ${error.message}`,
-        'WEBHOOK_PROCESSING_FAILED',
-        { retryable: false }
-      );
-    }
-
-    // Validate webhook event structure
-    if (!webhookEvent?.data?.sessionId && !webhookEvent?.data?.paymentIntentId) {
-      throw new ValidationError(
-        `Invalid webhook event structure from ${providerName}: missing sessionId or paymentIntentId`,
-        { provider: providerName, eventType: webhookEvent?.type }
-      );
-    }
-
-    // Find transaction by sessionId first (for checkout flows), then paymentIntentId
-    const TransactionModel = this.models.Transaction;
-    let transaction = null;
-
-    if (webhookEvent.data.sessionId) {
-      transaction = await TransactionModel.findOne({
-        'gateway.sessionId': webhookEvent.data.sessionId,
-      });
-    }
-
-    if (!transaction && webhookEvent.data.paymentIntentId) {
-      transaction = await TransactionModel.findOne({
-        'gateway.paymentIntentId': webhookEvent.data.paymentIntentId,
-      });
-    }
-
-    if (!transaction) {
-      this.logger.warn('Transaction not found for webhook event', {
-        provider: providerName,
-        eventId: webhookEvent.id,
-        sessionId: webhookEvent.data.sessionId,
-        paymentIntentId: webhookEvent.data.paymentIntentId,
-      });
-      throw new TransactionNotFoundError(
-        webhookEvent.data.sessionId || webhookEvent.data.paymentIntentId
-      );
-    }
-
-    // Update gateway with complete information from webhook
-    if (webhookEvent.data.sessionId && !transaction.gateway.sessionId) {
-      transaction.gateway.sessionId = webhookEvent.data.sessionId;
-    }
-    if (webhookEvent.data.paymentIntentId && !transaction.gateway.paymentIntentId) {
-      transaction.gateway.paymentIntentId = webhookEvent.data.paymentIntentId;
-    }
-
-    // Check for duplicate webhook processing (idempotency)
-    if (transaction.webhook?.eventId === webhookEvent.id && transaction.webhook?.processedAt) {
-      this.logger.warn('Webhook already processed', {
-        transactionId: transaction._id,
-        eventId: webhookEvent.id,
-      });
-      return {
-        event: webhookEvent,
-        transaction,
-        status: 'already_processed',
-      };
-    }
-
-    // Update transaction based on webhook event
-    transaction.webhook = {
-      eventId: webhookEvent.id,
-      eventType: webhookEvent.type,
-      receivedAt: new Date(),
-      processedAt: new Date(),
-      data: webhookEvent.data,
-    };
-
-    // Update status based on webhook type
-    if (webhookEvent.type === 'payment.succeeded') {
-      transaction.status = 'verified';
-      transaction.verifiedAt = webhookEvent.createdAt;
-    } else if (webhookEvent.type === 'payment.failed') {
-      transaction.status = 'failed';
-    } else if (webhookEvent.type === 'refund.succeeded') {
-      transaction.status = 'refunded';
-      transaction.refundedAt = webhookEvent.createdAt;
-    }
-
-    await transaction.save();
-
-    // Trigger hook
-    this._triggerHook(`payment.webhook.${webhookEvent.type}`, {
-      event: webhookEvent,
-      transaction,
-    });
-
-    return {
-      event: webhookEvent,
-      transaction,
-      status: 'processed',
-    };
-  }
-
-  /**
-   * List payments/transactions with filters
-   *
-   * @param {Object} filters - Query filters
-   * @param {Object} options - Query options (limit, skip, sort)
-   * @returns {Promise<Array>} Transactions
-   */
-  async list(filters = {}, options = {}) {
-    const TransactionModel = this.models.Transaction;
-    const { limit = 50, skip = 0, sort = { createdAt: -1 } } = options;
-
-    const transactions = await TransactionModel
-      .find(filters)
-      .limit(limit)
-      .skip(skip)
-      .sort(sort);
-
-    return transactions;
-  }
-
-  /**
-   * Get payment/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;
-  }
-
-  /**
-   * Get provider instance
-   *
-   * @param {String} providerName - Provider name
-   * @returns {Object} Provider instance
-   */
-  getProvider(providerName) {
-    const provider = this.providers[providerName];
-    if (!provider) {
-      throw new ProviderNotFoundError(providerName, Object.keys(this.providers));
-    }
-    return provider;
-  }
-
-  /**
-   * Trigger event hook (fire-and-forget, non-blocking)
-   * @private
-   */
-  _triggerHook(event, data) {
-    triggerHook(this.hooks, event, data, this.logger);
-  }
-
-  /**
-   * Find transaction by sessionId, paymentIntentId, or transaction ID
-   * @private
-   */
-  async _findTransaction(TransactionModel, identifier) {
-    let transaction = await TransactionModel.findOne({
-      'gateway.sessionId': identifier,
-    });
-
-    if (!transaction) {
-      transaction = await TransactionModel.findOne({
-        'gateway.paymentIntentId': identifier,
-      });
-    }
-
-    if (!transaction) {
-      transaction = await TransactionModel.findById(identifier);
-    }
-
-    return transaction;
-  }
-}
-
-export default PaymentService;

package/services/transaction.service.js

@@ -1,142 +0,0 @@
-/**
- * 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;