@classytic/revenue 0.2.3 → 1.0.0

package/utils/subscription/period.js

@@ -1,123 +0,0 @@
-/**
- * Subscription Period Utilities
- * @classytic/revenue/utils/subscription
- *
- * Universal period calculation, proration, and date utilities
- */
-
-/**
- * Add duration to date
- */
-export function addDuration(startDate, duration, unit = 'days') {
-  const date = new Date(startDate);
-  
-  switch (unit) {
-    case 'months':
-    case 'month':
-      date.setMonth(date.getMonth() + duration);
-      return date;
-    case 'years':
-    case 'year':
-      date.setFullYear(date.getFullYear() + duration);
-      return date;
-    case 'weeks':
-    case 'week':
-      date.setDate(date.getDate() + (duration * 7));
-      return date;
-    case 'days':
-    case 'day':
-    default:
-      date.setDate(date.getDate() + duration);
-      return date;
-  }
-}
-
-/**
- * Calculate subscription period start/end dates
- */
-export function calculatePeriodRange({
-  currentEndDate = null,
-  startDate = null,
-  duration,
-  unit = 'days',
-  now = new Date(),
-}) {
-  let periodStart;
-
-  if (startDate) {
-    periodStart = new Date(startDate);
-  } else if (currentEndDate) {
-    const end = new Date(currentEndDate);
-    periodStart = end > now ? end : now;
-  } else {
-    periodStart = now;
-  }
-
-  const periodEnd = addDuration(periodStart, duration, unit);
-
-  return { startDate: periodStart, endDate: periodEnd };
-}
-
-/**
- * Calculate prorated refund amount for unused period
- */
-export function calculateProratedAmount({
-  amountPaid,
-  startDate,
-  endDate,
-  asOfDate = new Date(),
-  precision = 2,
-}) {
-  if (!amountPaid || amountPaid <= 0) return 0;
-
-  const start = new Date(startDate);
-  const end = new Date(endDate);
-  const asOf = new Date(asOfDate);
-
-  const totalMs = end - start;
-  if (totalMs <= 0) return 0;
-
-  const remainingMs = Math.max(0, end - asOf);
-  if (remainingMs <= 0) return 0;
-
-  const ratio = remainingMs / totalMs;
-  const amount = amountPaid * ratio;
-  
-  const factor = 10 ** precision;
-  return Math.round(amount * factor) / factor;
-}
-
-/**
- * Convert interval + count to duration/unit
- */
-export function resolveIntervalToDuration(interval = 'month', intervalCount = 1) {
-  const normalized = (interval || 'month').toLowerCase();
-  const count = Number(intervalCount) > 0 ? Number(intervalCount) : 1;
-
-  switch (normalized) {
-    case 'year':
-    case 'years':
-      return { duration: count, unit: 'years' };
-    case 'week':
-    case 'weeks':
-      return { duration: count, unit: 'weeks' };
-    case 'quarter':
-    case 'quarters':
-      return { duration: count * 3, unit: 'months' };
-    case 'day':
-    case 'days':
-      return { duration: count, unit: 'days' };
-    case 'month':
-    case 'months':
-    default:
-      return { duration: count, unit: 'months' };
-  }
-}
-
-export default {
-  addDuration,
-  calculatePeriodRange,
-  calculateProratedAmount,
-  resolveIntervalToDuration,
-};
-

package/utils/transaction-type.js

@@ -1,254 +0,0 @@
-/**
- * Transaction Type Detection & Classification
- *
- * Distinguishes between:
- * - Monetization-managed transactions (library-controlled, strict rules)
- * - Manual admin transactions (flexible, admin-controlled)
- *
- * @module @classytic/revenue/utils/transaction-type
- */
-
-/**
- * Transaction types with different protection rules
- */
-export const TRANSACTION_TYPE = {
-  MONETIZATION: 'monetization', // Library-managed (subscriptions, purchases)
-  MANUAL: 'manual',             // Admin-managed (expenses, income, adjustments)
-};
-
-/**
- * Default monetization categories
- * Users can extend this via config.categoryMappings
- */
-const DEFAULT_MONETIZATION_CATEGORIES = [
-  'subscription',
-  'purchase',
-];
-
-/**
- * Check if category is monetization-related
- * @param {string} category - Transaction category
- * @param {Array<string>} additionalCategories - Additional categories from user config
- * @returns {boolean}
- */
-function isMonetizationCategory(category, additionalCategories = []) {
-  const allCategories = [...DEFAULT_MONETIZATION_CATEGORIES, ...additionalCategories];
-  return allCategories.includes(category);
-}
-
-/**
- * Check if transaction is monetization-managed
- *
- * Monetization-managed means:
- * - Created through subscription/purchase flows via the library
- * - Status controlled by payment webhooks/verification
- * - Amount/commission calculated by library
- * - Protected fields: status, amount, commission, gateway, verifiedAt, verifiedBy
- *
- * @param {Object} transaction - Transaction document or data
- * @param {Object} options - Options
- * @param {Array<string>} options.targetModels - Target models from config (default: ['Subscription', 'Membership'])
- * @param {Array<string>} options.additionalCategories - Additional categories from user config
- * @returns {boolean}
- */
-export function isMonetizationTransaction(transaction, options = {}) {
-  const {
-    targetModels = ['Subscription', 'Membership'],
-    additionalCategories = [],
-  } = options;
-
-  // Check 1: Has referenceModel from registered models
-  if (transaction.referenceModel && targetModels.includes(transaction.referenceModel)) {
-    return true;
-  }
-
-  // Check 2: Category is monetization-related
-  if (transaction.category) {
-    return isMonetizationCategory(transaction.category, additionalCategories);
-  }
-
-  return false;
-}
-
-/**
- * Check if transaction is manual admin transaction
- *
- * Manual transactions:
- * - Created directly by admins for operational expenses/income
- * - Can be self-verified by admins
- * - More flexible updates allowed
- * - No commission/gateway complexity
- *
- * @param {Object} transaction - Transaction document or data
- * @param {Object} options - Options (same as isMonetizationTransaction)
- * @returns {boolean}
- */
-export function isManualTransaction(transaction, options = {}) {
-  return !isMonetizationTransaction(transaction, options);
-}
-
-/**
- * Get transaction type
- *
- * @param {Object} transaction - Transaction document or data
- * @param {Object} options - Options (same as isMonetizationTransaction)
- * @returns {string} TRANSACTION_TYPE.MONETIZATION or TRANSACTION_TYPE.MANUAL
- */
-export function getTransactionType(transaction, options = {}) {
-  return isMonetizationTransaction(transaction, options)
-    ? TRANSACTION_TYPE.MONETIZATION
-    : TRANSACTION_TYPE.MANUAL;
-}
-
-/**
- * Protected fields for monetization transactions
- * These fields cannot be updated directly by admins
- */
-export const PROTECTED_MONETIZATION_FIELDS = [
-  'status',
-  'amount',
-  'platformCommission',
-  'netAmount',
-  'verifiedAt',
-  'verifiedBy',
-  'gateway',
-  'webhook',
-  'metadata.commission',
-  'metadata.gateway',
-  'type',
-  'category',
-  'referenceModel',
-  'referenceId',
-];
-
-/**
- * Editable fields for monetization transactions (before verification)
- * These fields can be updated by frontend/customer before payment is verified
- */
-export const EDITABLE_MONETIZATION_FIELDS_PRE_VERIFICATION = [
-  'reference',
-  'paymentDetails',
-  'notes',
-];
-
-/**
- * Allowed fields for manual transaction creation
- */
-export const MANUAL_TRANSACTION_CREATE_FIELDS = [
-  'organizationId',
-  'type',
-  'category',
-  'amount',
-  'method',
-  'reference',
-  'paymentDetails',
-  'notes',
-  'date', // Transaction date (can be backdated)
-  'description',
-];
-
-/**
- * Allowed fields for manual transaction updates
- */
-export const MANUAL_TRANSACTION_UPDATE_FIELDS = [
-  'amount',
-  'method',
-  'reference',
-  'paymentDetails',
-  'notes',
-  'date',
-  'description',
-];
-
-/**
- * Get allowed update fields based on transaction type and status
- *
- * @param {Object} transaction - Transaction document
- * @param {Object} options - Options for transaction type detection
- * @returns {Array<string>} Allowed field names
- */
-export function getAllowedUpdateFields(transaction, options = {}) {
-  const type = getTransactionType(transaction, options);
-
-  if (type === TRANSACTION_TYPE.MONETIZATION) {
-    // Monetization transactions: only allow pre-verification edits
-    if (transaction.status === 'pending') {
-      return EDITABLE_MONETIZATION_FIELDS_PRE_VERIFICATION;
-    }
-    // After verification, no direct updates allowed
-    return [];
-  }
-
-  // Manual transactions: more flexible
-  if (transaction.status === 'verified' || transaction.status === 'completed') {
-    // Once verified/completed, only notes can be updated
-    return ['notes'];
-  }
-
-  // Pending manual transactions can be fully edited
-  return MANUAL_TRANSACTION_UPDATE_FIELDS;
-}
-
-/**
- * Validate if field update is allowed
- *
- * @param {Object} transaction - Transaction document
- * @param {string} fieldName - Field being updated
- * @param {Object} options - Options for transaction type detection
- * @returns {Object} { allowed: boolean, reason?: string }
- */
-export function validateFieldUpdate(transaction, fieldName, options = {}) {
-  const allowedFields = getAllowedUpdateFields(transaction, options);
-
-  if (allowedFields.includes(fieldName)) {
-    return { allowed: true };
-  }
-
-  const type = getTransactionType(transaction, options);
-
-  if (type === TRANSACTION_TYPE.MONETIZATION) {
-    if (PROTECTED_MONETIZATION_FIELDS.includes(fieldName)) {
-      return {
-        allowed: false,
-        reason: `Field "${fieldName}" is protected for monetization transactions. Updates must go through payment flow.`,
-      };
-    }
-  }
-
-  return {
-    allowed: false,
-    reason: `Field "${fieldName}" cannot be updated for ${transaction.status} transactions.`,
-  };
-}
-
-/**
- * Check if transaction can be self-verified by admin
- *
- * @param {Object} transaction - Transaction document
- * @param {Object} options - Options for transaction type detection
- * @returns {boolean}
- */
-export function canSelfVerify(transaction, options = {}) {
-  const type = getTransactionType(transaction, options);
-
-  // Only manual transactions can be self-verified
-  if (type === TRANSACTION_TYPE.MANUAL) {
-    return transaction.status === 'pending';
-  }
-
-  return false;
-}
-
-export default {
-  TRANSACTION_TYPE,
-  isMonetizationTransaction,
-  isManualTransaction,
-  getTransactionType,
-  PROTECTED_MONETIZATION_FIELDS,
-  EDITABLE_MONETIZATION_FIELDS_PRE_VERIFICATION,
-  MANUAL_TRANSACTION_CREATE_FIELDS,
-  MANUAL_TRANSACTION_UPDATE_FIELDS,
-  getAllowedUpdateFields,
-  validateFieldUpdate,
-  canSelfVerify,
-};