@classytic/revenue 0.0.23 → 0.0.24

package/README.md

@@ -309,6 +309,43 @@ const pending = await Transaction.find({ 'commission.status': 'pending' });
 
 **See:** [`examples/commission-tracking.js`](examples/commission-tracking.js) for complete guide.
 
+## Subscription Utilities
+
+Universal helpers for period calculation, proration, and action eligibility:
+
+```javascript
+import {
+  // Period calculation
+  calculatePeriodRange,
+  calculateProratedAmount,
+  addDuration,
+  
+  // Action eligibility
+  canRenewSubscription,
+  canPauseSubscription,
+  isSubscriptionActive,
+} from '@classytic/revenue/utils';
+
+// Calculate period
+const { startDate, endDate } = calculatePeriodRange({
+  duration: 30,
+  unit: 'days',
+});
+
+// Calculate prorated refund
+const refund = calculateProratedAmount({
+  amountPaid: 1500,
+  startDate: sub.startDate,
+  endDate: sub.endDate,
+  asOfDate: new Date(),
+});
+
+// Check eligibility
+if (canRenewSubscription(membership)) {
+  await revenue.subscriptions.renew(membership.subscriptionId);
+}
+```
+
 ## Polymorphic References
 
 Link transactions to any entity (Order, Subscription, Enrollment):
@@ -448,11 +485,8 @@ const subscription = await revenue.subscriptions.create({ ... });
 
 - [`examples/basic-usage.js`](examples/basic-usage.js) - Quick start guide
 - [`examples/transaction.model.js`](examples/transaction.model.js) - Complete model setup
-- [`examples/transaction-type-mapping.js`](examples/transaction-type-mapping.js) - Income/expense configuration
-- [`examples/complete-flow.js`](examples/complete-flow.js) - Full lifecycle with state management
-- [`examples/commission-tracking.js`](examples/commission-tracking.js) - Platform commission calculation
-- [`examples/polymorphic-references.js`](examples/polymorphic-references.js) - Link transactions to entities
-- [`examples/multivendor-platform.js`](examples/multivendor-platform.js) - Multi-tenant setup
+- [`examples/complete-flow.js`](examples/complete-flow.js) - Full lifecycle (types, refs, state)
+- [`examples/commission-tracking.js`](examples/commission-tracking.js) - Commission calculation
 
 ## Error Handling
 

package/index.js

@@ -49,6 +49,16 @@ export {
   setLogger,
   calculateCommission,
   reverseCommission,
+  // Subscription utilities
+  addDuration,
+  calculatePeriodRange,
+  calculateProratedAmount,
+  resolveIntervalToDuration,
+  isSubscriptionActive,
+  canRenewSubscription,
+  canCancelSubscription,
+  canPauseSubscription,
+  canResumeSubscription,
 } from './utils/index.js';
 
 // ============ DEFAULT EXPORT ============

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/revenue",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "description": "Enterprise revenue management system with subscriptions, purchases, proration, and payment processing",
   "main": "index.js",
   "types": "revenue.d.ts",

package/utils/index.d.ts

@@ -100,6 +100,37 @@ export function reverseCommission(
   refundAmount: number
 ): CommissionObject | null;
 
+// ============ SUBSCRIPTION UTILITIES ============
+
+export function addDuration(startDate: Date, duration: number, unit?: string): Date;
+
+export function calculatePeriodRange(params: {
+  currentEndDate?: Date | null;
+  startDate?: Date | null;
+  duration: number;
+  unit?: string;
+  now?: Date;
+}): { startDate: Date; endDate: Date };
+
+export function calculateProratedAmount(params: {
+  amountPaid: number;
+  startDate: Date;
+  endDate: Date;
+  asOfDate?: Date;
+  precision?: number;
+}): number;
+
+export function resolveIntervalToDuration(
+  interval?: string,
+  intervalCount?: number
+): { duration: number; unit: string };
+
+export function isSubscriptionActive(subscription: any): boolean;
+export function canRenewSubscription(entity: any): boolean;
+export function canCancelSubscription(entity: any): boolean;
+export function canPauseSubscription(entity: any): boolean;
+export function canResumeSubscription(entity: any): boolean;
+
 // ============ DEFAULT EXPORT ============
 
 declare const _default: {
@@ -119,6 +150,15 @@ declare const _default: {
   triggerHook: typeof triggerHook;
   calculateCommission: typeof calculateCommission;
   reverseCommission: typeof reverseCommission;
+  addDuration: typeof addDuration;
+  calculatePeriodRange: typeof calculatePeriodRange;
+  calculateProratedAmount: typeof calculateProratedAmount;
+  resolveIntervalToDuration: typeof resolveIntervalToDuration;
+  isSubscriptionActive: typeof isSubscriptionActive;
+  canRenewSubscription: typeof canRenewSubscription;
+  canCancelSubscription: typeof canCancelSubscription;
+  canPauseSubscription: typeof canPauseSubscription;
+  canResumeSubscription: typeof canResumeSubscription;
 };
 
 export default _default;

package/utils/index.js

@@ -7,3 +7,4 @@ export * from './transaction-type.js';
 export { default as logger, setLogger } from './logger.js';
 export { triggerHook } from './hooks.js';
 export { calculateCommission, reverseCommission } from './commission.js';
+export * from './subscription/index.js';

package/utils/subscription/actions.js

@@ -0,0 +1,68 @@
+/**
+ * Subscription Action Utilities
+ * @classytic/revenue/utils/subscription
+ *
+ * Eligibility checks for subscription actions
+ */
+
+import { SUBSCRIPTION_STATUS } from '../../enums/subscription.enums.js';
+
+/**
+ * Check if subscription is active
+ */
+export function isSubscriptionActive(subscription) {
+  if (!subscription) return false;
+  if (!subscription.isActive) return false;
+
+  if (subscription.endDate) {
+    const now = new Date();
+    const endDate = new Date(subscription.endDate);
+    if (endDate < now) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Check if can renew
+ */
+export function canRenewSubscription(entity) {
+  if (!entity || !entity.subscription) return false;
+  return isSubscriptionActive(entity.subscription);
+}
+
+/**
+ * Check if can cancel
+ */
+export function canCancelSubscription(entity) {
+  if (!entity || !entity.subscription) return false;
+  if (!isSubscriptionActive(entity.subscription)) return false;
+  return !entity.subscription.canceledAt;
+}
+
+/**
+ * Check if can pause
+ */
+export function canPauseSubscription(entity) {
+  if (!entity || !entity.subscription) return false;
+  if (entity.status === SUBSCRIPTION_STATUS.PAUSED) return false;
+  if (entity.status === SUBSCRIPTION_STATUS.CANCELLED) return false;
+  return isSubscriptionActive(entity.subscription);
+}
+
+/**
+ * Check if can resume
+ */
+export function canResumeSubscription(entity) {
+  if (!entity || !entity.subscription) return false;
+  return entity.status === SUBSCRIPTION_STATUS.PAUSED;
+}
+
+export default {
+  isSubscriptionActive,
+  canRenewSubscription,
+  canCancelSubscription,
+  canPauseSubscription,
+  canResumeSubscription,
+};
+

package/utils/subscription/index.js

@@ -0,0 +1,20 @@
+/**
+ * Subscription Utilities Index
+ * @classytic/revenue/utils/subscription
+ */
+
+export {
+  addDuration,
+  calculatePeriodRange,
+  calculateProratedAmount,
+  resolveIntervalToDuration,
+} from './period.js';
+
+export {
+  isSubscriptionActive,
+  canRenewSubscription,
+  canCancelSubscription,
+  canPauseSubscription,
+  canResumeSubscription,
+} from './actions.js';
+

package/utils/subscription/period.js

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