@classytic/revenue 0.0.24 → 0.1.0

package/dist/types/utils/subscription/period.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Subscription Period Utilities
+ * @classytic/revenue/utils/subscription
+ *
+ * Universal period calculation, proration, and date utilities
+ */
+/**
+ * Add duration to date
+ */
+export function addDuration(startDate: any, duration: any, unit?: string): Date;
+/**
+ * Calculate subscription period start/end dates
+ */
+export function calculatePeriodRange({ currentEndDate, startDate, duration, unit, now, }: {
+    currentEndDate?: any;
+    startDate?: any;
+    duration: any;
+    unit?: string;
+    now?: Date;
+}): {
+    startDate: Date;
+    endDate: Date;
+};
+/**
+ * Calculate prorated refund amount for unused period
+ */
+export function calculateProratedAmount({ amountPaid, startDate, endDate, asOfDate, precision, }: {
+    amountPaid: any;
+    startDate: any;
+    endDate: any;
+    asOfDate?: Date;
+    precision?: number;
+}): number;
+/**
+ * Convert interval + count to duration/unit
+ */
+export function resolveIntervalToDuration(interval?: string, intervalCount?: number): {
+    duration: number;
+    unit: string;
+};
+declare namespace _default {
+    export { addDuration };
+    export { calculatePeriodRange };
+    export { calculateProratedAmount };
+    export { resolveIntervalToDuration };
+}
+export default _default;

package/dist/types/utils/transaction-type.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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: any, options?: {
+    targetModels: Array<string>;
+    additionalCategories: Array<string>;
+}): boolean;
+/**
+ * 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: any, options?: any): boolean;
+/**
+ * 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: any, options?: any): string;
+/**
+ * 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: any, options?: any): Array<string>;
+/**
+ * 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: any, fieldName: string, options?: any): any;
+/**
+ * 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: any, options?: any): boolean;
+export namespace TRANSACTION_TYPE {
+    let MONETIZATION: string;
+    let MANUAL: string;
+}
+/**
+ * Protected fields for monetization transactions
+ * These fields cannot be updated directly by admins
+ */
+export const PROTECTED_MONETIZATION_FIELDS: string[];
+/**
+ * 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: string[];
+/**
+ * Allowed fields for manual transaction creation
+ */
+export const MANUAL_TRANSACTION_CREATE_FIELDS: string[];
+/**
+ * Allowed fields for manual transaction updates
+ */
+export const MANUAL_TRANSACTION_UPDATE_FIELDS: string[];
+declare namespace _default {
+    export { TRANSACTION_TYPE };
+    export { isMonetizationTransaction };
+    export { isManualTransaction };
+    export { getTransactionType };
+    export { PROTECTED_MONETIZATION_FIELDS };
+    export { EDITABLE_MONETIZATION_FIELDS_PRE_VERIFICATION };
+    export { MANUAL_TRANSACTION_CREATE_FIELDS };
+    export { MANUAL_TRANSACTION_UPDATE_FIELDS };
+    export { getAllowedUpdateFields };
+    export { validateFieldUpdate };
+    export { canSelfVerify };
+}
+export default _default;

package/enums/escrow.enums.js

@@ -0,0 +1,36 @@
+/**
+ * Escrow/Hold Enums
+ * @classytic/revenue
+ *
+ * Enums for platform-as-intermediary payment flow
+ */
+
+export const HOLD_STATUS = {
+  PENDING: 'pending',
+  HELD: 'held',
+  RELEASED: 'released',
+  CANCELLED: 'cancelled',
+  EXPIRED: 'expired',
+  PARTIALLY_RELEASED: 'partially_released',
+};
+
+export const HOLD_STATUS_VALUES = Object.values(HOLD_STATUS);
+
+export const RELEASE_REASON = {
+  PAYMENT_VERIFIED: 'payment_verified',
+  MANUAL_RELEASE: 'manual_release',
+  AUTO_RELEASE: 'auto_release',
+  DISPUTE_RESOLVED: 'dispute_resolved',
+};
+
+export const RELEASE_REASON_VALUES = Object.values(RELEASE_REASON);
+
+export const HOLD_REASON = {
+  PAYMENT_VERIFICATION: 'payment_verification',
+  FRAUD_CHECK: 'fraud_check',
+  MANUAL_REVIEW: 'manual_review',
+  DISPUTE: 'dispute',
+  COMPLIANCE: 'compliance',
+};
+
+export const HOLD_REASON_VALUES = Object.values(HOLD_REASON);

package/enums/index.js

@@ -13,6 +13,8 @@ export * from './transaction.enums.js';
 export * from './payment.enums.js';
 export * from './subscription.enums.js';
 export * from './monetization.enums.js';
+export * from './escrow.enums.js';
+export * from './split.enums.js';
 
 // Default export for convenience
 import {
@@ -45,6 +47,24 @@ import {
   MONETIZATION_TYPE_VALUES,
 } from './monetization.enums.js';
 
+import {
+  HOLD_STATUS,
+  HOLD_STATUS_VALUES,
+  RELEASE_REASON,
+  RELEASE_REASON_VALUES,
+  HOLD_REASON,
+  HOLD_REASON_VALUES,
+} from './escrow.enums.js';
+
+import {
+  SPLIT_TYPE,
+  SPLIT_TYPE_VALUES,
+  SPLIT_STATUS,
+  SPLIT_STATUS_VALUES,
+  PAYOUT_METHOD,
+  PAYOUT_METHOD_VALUES,
+} from './split.enums.js';
+
 export default {
   // Transaction enums
   TRANSACTION_TYPE,
@@ -71,4 +91,20 @@ export default {
   // Monetization enums
   MONETIZATION_TYPES,
   MONETIZATION_TYPE_VALUES,
+
+  // Escrow enums
+  HOLD_STATUS,
+  HOLD_STATUS_VALUES,
+  RELEASE_REASON,
+  RELEASE_REASON_VALUES,
+  HOLD_REASON,
+  HOLD_REASON_VALUES,
+
+  // Split enums
+  SPLIT_TYPE,
+  SPLIT_TYPE_VALUES,
+  SPLIT_STATUS,
+  SPLIT_STATUS_VALUES,
+  PAYOUT_METHOD,
+  PAYOUT_METHOD_VALUES,
 };

package/enums/split.enums.js

@@ -0,0 +1,37 @@
+/**
+ * Split Payment Enums
+ * @classytic/revenue
+ *
+ * Enums for multi-party commission splits
+ */
+
+export const SPLIT_TYPE = {
+  PLATFORM_COMMISSION: 'platform_commission',
+  AFFILIATE_COMMISSION: 'affiliate_commission',
+  REFERRAL_COMMISSION: 'referral_commission',
+  PARTNER_COMMISSION: 'partner_commission',
+  CUSTOM: 'custom',
+};
+
+export const SPLIT_TYPE_VALUES = Object.values(SPLIT_TYPE);
+
+export const SPLIT_STATUS = {
+  PENDING: 'pending',
+  DUE: 'due',
+  PAID: 'paid',
+  WAIVED: 'waived',
+  CANCELLED: 'cancelled',
+};
+
+export const SPLIT_STATUS_VALUES = Object.values(SPLIT_STATUS);
+
+export const PAYOUT_METHOD = {
+  BANK_TRANSFER: 'bank_transfer',
+  MOBILE_WALLET: 'mobile_wallet',
+  PLATFORM_BALANCE: 'platform_balance',
+  CRYPTO: 'crypto',
+  CHECK: 'check',
+  MANUAL: 'manual',
+};
+
+export const PAYOUT_METHOD_VALUES = Object.values(PAYOUT_METHOD);

package/index.js

@@ -38,6 +38,7 @@ import { PaymentProvider as _PaymentProvider } from './providers/base.js';
 export { SubscriptionService } from './services/subscription.service.js';
 export { PaymentService } from './services/payment.service.js';
 export { TransactionService } from './services/transaction.service.js';
+export { EscrowService } from './services/escrow.service.js';
 
 // ============ ENUMS & SCHEMAS (FOR INJECTION) ============
 export * from './enums/index.js';
@@ -49,6 +50,11 @@ export {
   setLogger,
   calculateCommission,
   reverseCommission,
+  // Split/Escrow utilities
+  calculateSplits,
+  calculateOrganizationPayout,
+  reverseSplits,
+  calculateCommissionWithSplits,
   // Subscription utilities
   addDuration,
   calculatePeriodRange,

package/package.json

@@ -1,74 +1,91 @@
-{
-  "name": "@classytic/revenue",
-  "version": "0.0.24",
-  "description": "Enterprise revenue management system with subscriptions, purchases, proration, and payment processing",
-  "main": "index.js",
-  "types": "revenue.d.ts",
-  "type": "module",
-  "keywords": [
-    "revenue",
-    "monetization",
-    "subscription",
-    "payment",
-    "saas",
-    "billing",
-    "proration",
-    "recurring",
-    "gateway",
-    "webhook",
-    "stripe",
-    "sslcommerz",
-    "bkash",
-    "transaction",
-    "invoice"
-  ],
-  "author": "Sadman Chowdhury",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/classytic/revenue"
-  },
-  "bugs": {
-    "url": "https://github.com/classytic/revenue/issues"
-  },
-  "homepage": "https://github.com/classytic/revenue#readme",
-  "peerDependencies": {
-    "mongoose": "^8.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "exports": {
-    ".": {
-      "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",
-    "revenue.d.ts",
-    "LICENSE",
-    "README.md",
-    "core/",
-    "providers/",
-    "services/",
-    "enums/",
-    "schemas/",
-    "utils/"
-  ],
-  "dependencies": {
-    "nanoid": "^5.1.6"
-  }
-}
+{
+  "name": "@classytic/revenue",
+  "version": "0.1.0",
+  "description": "Enterprise revenue management system with subscriptions, purchases, proration, payment processing, escrow, and multi-party splits",
+  "main": "index.js",
+  "type": "module",
+  "keywords": [
+    "revenue",
+    "monetization",
+    "subscription",
+    "payment",
+    "saas",
+    "billing",
+    "proration",
+    "recurring",
+    "gateway",
+    "webhook",
+    "stripe",
+    "sslcommerz",
+    "bkash",
+    "transaction",
+    "invoice",
+    "escrow",
+    "hold",
+    "release",
+    "split",
+    "affiliate",
+    "commission",
+    "marketplace"
+  ],
+  "author": "Sadman Chowdhury",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/classytic/revenue.git"
+  },
+  "bugs": {
+    "url": "https://github.com/classytic/revenue/issues"
+  },
+  "homepage": "https://github.com/classytic/revenue#readme",
+  "scripts": {
+    "types": "tsc -p tsconfig.types.json",
+    "build": "npm run types",
+    "prepublishOnly": "npm run build",
+    "test": "node ../tests/run-all.js"
+  },
+  "peerDependencies": {
+    "mongoose": "^8.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./index.js"
+    },
+    "./enums": {
+      "types": "./dist/types/enums/index.d.ts",
+      "default": "./enums/index.js"
+    },
+    "./schemas": {
+      "types": "./dist/types/schemas/index.d.ts",
+      "default": "./schemas/index.js"
+    },
+    "./utils": {
+      "types": "./dist/types/utils/index.d.ts",
+      "default": "./utils/index.js"
+    }
+  },
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "index.js",
+    "LICENSE",
+    "README.md",
+    "core/",
+    "providers/",
+    "services/",
+    "enums/",
+    "schemas/",
+    "utils/",
+    "dist/types/"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.8.7",
+    "typescript": "^5.6.3"
+  },
+  "dependencies": {
+    "nanoid": "^5.1.6"
+  }
+}

package/schemas/escrow/hold.schema.js

@@ -0,0 +1,62 @@
+/**
+ * Hold/Escrow Schema
+ * @classytic/revenue
+ *
+ * Schema for platform-as-intermediary escrow flow
+ * Spread into transaction schema when needed
+ */
+
+import { HOLD_STATUS, HOLD_STATUS_VALUES, HOLD_REASON, HOLD_REASON_VALUES } from '../../enums/escrow.enums.js';
+
+export const holdSchema = {
+  status: {
+    type: String,
+    enum: HOLD_STATUS_VALUES,
+    default: HOLD_STATUS.PENDING,
+    index: true,
+  },
+
+  heldAmount: {
+    type: Number,
+    required: false,
+  },
+
+  releasedAmount: {
+    type: Number,
+    default: 0,
+  },
+
+  reason: {
+    type: String,
+    enum: HOLD_REASON_VALUES,
+    required: false,
+  },
+
+  holdUntil: {
+    type: Date,
+    required: false,
+  },
+
+  heldAt: Date,
+  releasedAt: Date,
+  cancelledAt: Date,
+
+  releases: [
+    {
+      amount: Number,
+      recipientId: String,
+      recipientType: String,
+      releasedAt: Date,
+      releasedBy: String,
+      reason: String,
+      metadata: Object,
+    },
+  ],
+
+  metadata: {
+    type: Object,
+    default: {},
+  },
+};
+
+export default holdSchema;

package/schemas/escrow/index.js

@@ -0,0 +1,15 @@
+/**
+ * Escrow Schemas
+ * @classytic/revenue
+ */
+
+// Import first
+import { holdSchema } from './hold.schema.js';
+
+// Then re-export
+export { holdSchema };
+
+// Now it's in scope for default export
+export default {
+  holdSchema,
+};

package/schemas/index.js

@@ -10,12 +10,18 @@
 // Re-export core schemas only
 export * from './transaction/index.js';
 export * from './subscription/index.js';
+export * from './escrow/index.js';
+export * from './split/index.js';
 
 // Default export with core schemas
 import transactionSchemas from './transaction/index.js';
 import subscriptionSchemas from './subscription/index.js';
+import escrowSchemas from './escrow/index.js';
+import splitSchemas from './split/index.js';
 
 export default {
   ...transactionSchemas,
   ...subscriptionSchemas,
+  ...escrowSchemas,
+  ...splitSchemas,
 };

package/schemas/split/index.js

@@ -0,0 +1,16 @@
+/**
+ * Split Payment Schemas
+ * @classytic/revenue
+ */
+
+// Import first
+import { splitItemSchema, splitsSchema } from './split.schema.js';
+
+// Then re-export
+export { splitItemSchema, splitsSchema };
+
+// Now they're in scope for default export
+export default {
+  splitItemSchema,
+  splitsSchema,
+};

package/schemas/split/split.schema.js

@@ -0,0 +1,86 @@
+/**
+ * Split Payment Schema
+ * @classytic/revenue
+ *
+ * Schema for multi-party commission splits
+ * Spread into transaction schema when needed
+ */
+
+import { SPLIT_TYPE, SPLIT_TYPE_VALUES, SPLIT_STATUS, SPLIT_STATUS_VALUES, PAYOUT_METHOD, PAYOUT_METHOD_VALUES } from '../../enums/split.enums.js';
+
+export const splitItemSchema = {
+  type: {
+    type: String,
+    enum: SPLIT_TYPE_VALUES,
+    required: true,
+  },
+
+  recipientId: {
+    type: String,
+    required: true,
+    index: true,
+  },
+
+  recipientType: {
+    type: String,
+    required: true,
+  },
+
+  rate: {
+    type: Number,
+    required: true,
+    min: 0,
+    max: 1,
+  },
+
+  grossAmount: {
+    type: Number,
+    required: true,
+  },
+
+  gatewayFeeRate: {
+    type: Number,
+    default: 0,
+  },
+
+  gatewayFeeAmount: {
+    type: Number,
+    default: 0,
+  },
+
+  netAmount: {
+    type: Number,
+    required: true,
+  },
+
+  status: {
+    type: String,
+    enum: SPLIT_STATUS_VALUES,
+    default: SPLIT_STATUS.PENDING,
+  },
+
+  dueDate: Date,
+  paidDate: Date,
+
+  payoutMethod: {
+    type: String,
+    enum: PAYOUT_METHOD_VALUES,
+    required: false,
+  },
+
+  payoutTransactionId: String,
+
+  metadata: {
+    type: Object,
+    default: {},
+  },
+};
+
+export const splitsSchema = {
+  splits: {
+    type: [splitItemSchema],
+    default: [],
+  },
+};
+
+export default splitsSchema;