@classytic/revenue 0.0.23 → 0.1.0

package/dist/types/schemas/transaction/payment.schema.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Current Payment Schema
+ * Use this in your model: currentPayment: { type: currentPaymentSchema }
+ *
+ * Tracks the latest payment transaction for an entity
+ */
+export const currentPaymentSchema: Schema<any, import("mongoose").Model<any, any, any, any, any, any>, {}, {}, {}, {}, {
+    _id: false;
+}, {
+    status: string;
+    transactionId?: import("mongoose").Types.ObjectId;
+    amount?: number;
+    method?: string;
+    reference?: string;
+    verifiedAt?: NativeDate;
+    verifiedBy?: import("mongoose").Types.ObjectId;
+}, import("mongoose").Document<unknown, {}, import("mongoose").FlatRecord<{
+    status: string;
+    transactionId?: import("mongoose").Types.ObjectId;
+    amount?: number;
+    method?: string;
+    reference?: string;
+    verifiedAt?: NativeDate;
+    verifiedBy?: import("mongoose").Types.ObjectId;
+}>, {}, import("mongoose").ResolveSchemaOptions<{
+    _id: false;
+}>> & import("mongoose").FlatRecord<{
+    status: string;
+    transactionId?: import("mongoose").Types.ObjectId;
+    amount?: number;
+    method?: string;
+    reference?: string;
+    verifiedAt?: NativeDate;
+    verifiedBy?: import("mongoose").Types.ObjectId;
+}> & {
+    _id: import("mongoose").Types.ObjectId;
+} & {
+    __v: number;
+}>;
+/**
+ * Payment Summary Schema
+ * Use this in your model: paymentSummary: { type: paymentSummarySchema }
+ *
+ * Tracks payment history and totals
+ */
+export const paymentSummarySchema: Schema<any, import("mongoose").Model<any, any, any, any, any, any>, {}, {}, {}, {}, {
+    _id: false;
+}, {
+    totalPayments: number;
+    totalAmountPaid: number;
+    lastPaymentDate?: NativeDate;
+    lastPaymentAmount?: number;
+}, import("mongoose").Document<unknown, {}, import("mongoose").FlatRecord<{
+    totalPayments: number;
+    totalAmountPaid: number;
+    lastPaymentDate?: NativeDate;
+    lastPaymentAmount?: number;
+}>, {}, import("mongoose").ResolveSchemaOptions<{
+    _id: false;
+}>> & import("mongoose").FlatRecord<{
+    totalPayments: number;
+    totalAmountPaid: number;
+    lastPaymentDate?: NativeDate;
+    lastPaymentAmount?: number;
+}> & {
+    _id: import("mongoose").Types.ObjectId;
+} & {
+    __v: number;
+}>;
+/**
+ * Payment Details Schema (for manual payments)
+ * Embedded in Transaction model
+ */
+export const paymentDetailsSchema: Schema<any, import("mongoose").Model<any, any, any, any, any, any>, {}, {}, {}, {}, {
+    _id: false;
+}, {
+    provider?: string;
+    walletNumber?: string;
+    walletType?: string;
+    trxId?: string;
+    bankName?: string;
+    accountNumber?: string;
+    accountName?: string;
+    proofUrl?: string;
+}, import("mongoose").Document<unknown, {}, import("mongoose").FlatRecord<{
+    provider?: string;
+    walletNumber?: string;
+    walletType?: string;
+    trxId?: string;
+    bankName?: string;
+    accountNumber?: string;
+    accountName?: string;
+    proofUrl?: string;
+}>, {}, import("mongoose").ResolveSchemaOptions<{
+    _id: false;
+}>> & import("mongoose").FlatRecord<{
+    provider?: string;
+    walletNumber?: string;
+    walletType?: string;
+    trxId?: string;
+    bankName?: string;
+    accountNumber?: string;
+    accountName?: string;
+    proofUrl?: string;
+}> & {
+    _id: import("mongoose").Types.ObjectId;
+} & {
+    __v: number;
+}>;
+/**
+ * Tenant Snapshot Schema
+ * Captures organization payment details at transaction time (audit trail)
+ */
+export const tenantSnapshotSchema: Schema<any, import("mongoose").Model<any, any, any, any, any, any>, {}, {}, {}, {}, {
+    _id: false;
+}, {
+    paymentInstructions?: string;
+    bkashNumber?: string;
+    nagadNumber?: string;
+    bankAccount?: string;
+}, import("mongoose").Document<unknown, {}, import("mongoose").FlatRecord<{
+    paymentInstructions?: string;
+    bkashNumber?: string;
+    nagadNumber?: string;
+    bankAccount?: string;
+}>, {}, import("mongoose").ResolveSchemaOptions<{
+    _id: false;
+}>> & import("mongoose").FlatRecord<{
+    paymentInstructions?: string;
+    bkashNumber?: string;
+    nagadNumber?: string;
+    bankAccount?: string;
+}> & {
+    _id: import("mongoose").Types.ObjectId;
+} & {
+    __v: number;
+}>;
+declare namespace _default {
+    export { currentPaymentSchema };
+    export { paymentSummarySchema };
+    export { paymentDetailsSchema };
+    export { tenantSnapshotSchema };
+}
+export default _default;
+import { Schema } from 'mongoose';

package/dist/types/services/escrow.service.d.ts

@@ -0,0 +1,51 @@
+export class EscrowService {
+    constructor(container: any);
+    container: any;
+    models: any;
+    providers: any;
+    config: any;
+    hooks: any;
+    logger: any;
+    /**
+     * Hold funds in escrow
+     *
+     * @param {String} transactionId - Transaction to hold
+     * @param {Object} options - Hold options
+     * @returns {Promise<Object>} Updated transaction
+     */
+    hold(transactionId: string, options?: any): Promise<any>;
+    /**
+     * Release funds from escrow to recipient
+     *
+     * @param {String} transactionId - Transaction to release
+     * @param {Object} options - Release options
+     * @returns {Promise<Object>} { transaction, releaseTransaction }
+     */
+    release(transactionId: string, options?: any): Promise<any>;
+    /**
+     * Cancel hold and release back to customer
+     *
+     * @param {String} transactionId - Transaction to cancel hold
+     * @param {Object} options - Cancel options
+     * @returns {Promise<Object>} Updated transaction
+     */
+    cancel(transactionId: string, options?: any): Promise<any>;
+    /**
+     * Split payment to multiple recipients
+     * Deducts splits from held amount and releases remainder to organization
+     *
+     * @param {String} transactionId - Transaction to split
+     * @param {Array} splitRules - Split configuration
+     * @returns {Promise<Object>} { transaction, splitTransactions, organizationTransaction }
+     */
+    split(transactionId: string, splitRules?: any[]): Promise<any>;
+    /**
+     * Get escrow status
+     *
+     * @param {String} transactionId - Transaction ID
+     * @returns {Promise<Object>} Escrow status
+     */
+    getStatus(transactionId: string): Promise<any>;
+    _triggerHook(event: any, data: any): void;
+}
+export default EscrowService;

package/dist/types/services/payment.service.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Payment Service
+ * Uses DI container for all dependencies
+ */
+export class PaymentService {
+    constructor(container: any);
+    container: any;
+    models: any;
+    providers: any;
+    config: any;
+    hooks: any;
+    logger: any;
+    /**
+     * Verify a payment
+     *
+     * @param {String} paymentIntentId - Payment intent 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 }
+     */
+    verify(paymentIntentId: string, options?: {
+        verifiedBy: string;
+    }): Promise<any>;
+    /**
+     * Get payment status
+     *
+     * @param {String} paymentIntentId - Payment intent ID or transaction ID
+     * @returns {Promise<Object>} { transaction, status }
+     */
+    getStatus(paymentIntentId: string): Promise<any>;
+    /**
+     * Refund a payment
+     *
+     * @param {String} paymentId - Payment intent 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 }
+     */
+    refund(paymentId: string, amount?: number, options?: {
+        reason: string;
+    }): Promise<any>;
+    /**
+     * 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 }
+     */
+    handleWebhook(providerName: any, payload: any, headers?: any): Promise<any>;
+    /**
+     * List payments/transactions with filters
+     *
+     * @param {Object} filters - Query filters
+     * @param {Object} options - Query options (limit, skip, sort)
+     * @returns {Promise<Array>} Transactions
+     */
+    list(filters?: any, options?: any): Promise<any[]>;
+    /**
+     * Get payment/transaction by ID
+     *
+     * @param {String} transactionId - Transaction ID
+     * @returns {Promise<Object>} Transaction
+     */
+    get(transactionId: string): Promise<any>;
+    /**
+     * Get provider instance
+     *
+     * @param {String} providerName - Provider name
+     * @returns {Object} Provider instance
+     */
+    getProvider(providerName: string): any;
+    /**
+     * Trigger event hook (fire-and-forget, non-blocking)
+     * @private
+     */
+    private _triggerHook;
+}
+export default PaymentService;

package/dist/types/services/subscription.service.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Subscription Service
+ * Uses DI container for all dependencies
+ */
+export class SubscriptionService {
+    constructor(container: any);
+    container: any;
+    models: any;
+    providers: any;
+    config: any;
+    hooks: any;
+    logger: any;
+    /**
+     * Create a new subscription
+     *
+     * @param {Object} params - Subscription parameters
+     * @param {Object} params.data - Subscription data (organizationId, customerId, referenceId, referenceModel, 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 {String} params.entity - Logical entity identifier (e.g., 'Order', 'PlatformSubscription', 'Membership')
+     *                                 NOTE: This is NOT a database model name - it's just a logical identifier for categoryMappings
+     * @param {String} params.monetizationType - Monetization type ('free', 'subscription', 'purchase')
+     * @param {Object} params.paymentData - Payment method details
+     * @param {Object} params.metadata - Additional metadata
+     * @param {String} params.idempotencyKey - Idempotency key for duplicate prevention
+     *
+     * @example
+     * // With polymorphic reference (recommended)
+     * await revenue.subscriptions.create({
+     *   data: {
+     *     organizationId: '...',
+     *     customerId: '...',
+     *     referenceId: subscription._id,      // Links to entity
+     *     referenceModel: 'Subscription',     // Model name
+     *   },
+     *   amount: 1500,
+     *   // ...
+     * });
+     *
+     * @returns {Promise<Object>} { subscription, transaction, paymentIntent }
+     */
+    create(params: {
+        data: any;
+        planKey: string;
+        amount: number;
+        currency: string;
+        gateway: string;
+        entity: string;
+        monetizationType: string;
+        paymentData: any;
+        metadata: any;
+        idempotencyKey: string;
+    }): Promise<any>;
+    /**
+     * Activate subscription after payment verification
+     *
+     * @param {String} subscriptionId - Subscription ID or transaction ID
+     * @param {Object} options - Activation options
+     * @returns {Promise<Object>} Updated subscription
+     */
+    activate(subscriptionId: string, options?: any): Promise<any>;
+    /**
+     * Renew subscription
+     *
+     * @param {String} subscriptionId - Subscription ID
+     * @param {Object} params - Renewal parameters
+     * @param {String} params.gateway - Payment gateway to use (default: 'manual')
+     * @param {String} params.entity - Logical entity identifier (optional, inherits from subscription)
+     * @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 }
+     */
+    renew(subscriptionId: string, params?: {
+        gateway: string;
+        entity: string;
+        paymentData: any;
+        metadata: any;
+        idempotencyKey: string;
+    }): Promise<any>;
+    /**
+     * 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
+     */
+    cancel(subscriptionId: string, options?: {
+        immediate: boolean;
+        reason: string;
+    }): Promise<any>;
+    /**
+     * Pause subscription
+     *
+     * @param {String} subscriptionId - Subscription ID
+     * @param {Object} options - Pause options
+     * @returns {Promise<Object>} Updated subscription
+     */
+    pause(subscriptionId: string, options?: any): Promise<any>;
+    /**
+     * Resume subscription
+     *
+     * @param {String} subscriptionId - Subscription ID
+     * @param {Object} options - Resume options
+     * @returns {Promise<Object>} Updated subscription
+     */
+    resume(subscriptionId: string, options?: any): Promise<any>;
+    /**
+     * List subscriptions with filters
+     *
+     * @param {Object} filters - Query filters
+     * @param {Object} options - Query options (limit, skip, sort)
+     * @returns {Promise<Array>} Subscriptions
+     */
+    list(filters?: any, options?: any): Promise<any[]>;
+    /**
+     * Get subscription by ID
+     *
+     * @param {String} subscriptionId - Subscription ID
+     * @returns {Promise<Object>} Subscription
+     */
+    get(subscriptionId: string): Promise<any>;
+    /**
+     * Calculate period end date based on plan key
+     * @private
+     */
+    private _calculatePeriodEnd;
+    /**
+     * Trigger event hook (fire-and-forget, non-blocking)
+     * @private
+     */
+    private _triggerHook;
+}
+export default SubscriptionService;

package/dist/types/services/transaction.service.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Transaction Service
+ * Focused on core transaction lifecycle operations
+ */
+export class TransactionService {
+    constructor(container: any);
+    container: any;
+    models: any;
+    hooks: any;
+    logger: any;
+    /**
+     * Get transaction by ID
+     *
+     * @param {String} transactionId - Transaction ID
+     * @returns {Promise<Object>} Transaction
+     */
+    get(transactionId: string): Promise<any>;
+    /**
+     * 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 }
+     */
+    list(filters?: any, options?: any): Promise<any>;
+    /**
+     * Update transaction
+     *
+     * @param {String} transactionId - Transaction ID
+     * @param {Object} updates - Fields to update
+     * @returns {Promise<Object>} Updated transaction
+     */
+    update(transactionId: string, updates: any): Promise<any>;
+    /**
+     * Trigger event hook (fire-and-forget, non-blocking)
+     * @private
+     */
+    private _triggerHook;
+}
+export default TransactionService;

package/dist/types/utils/category-resolver.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Resolve category for a transaction based on entity and monetizationType
+ *
+ * Resolution Logic:
+ * 1. If categoryMappings[entity] exists → use it
+ * 2. Otherwise → fall back to default library category
+ *
+ * @param {String} entity - The logical entity/identifier (e.g., 'Order', 'PlatformSubscription', 'Membership')
+ *                          NOTE: This is NOT a database model name - it's just a logical identifier
+ * @param {String} monetizationType - The monetization type ('subscription', 'purchase', 'free')
+ * @param {Object} categoryMappings - User-defined category mappings from config
+ * @returns {String} Category name for the transaction
+ *
+ * @example
+ * // With mapping defined
+ * resolveCategory('Order', 'subscription', { Order: 'order_subscription' })
+ * // Returns: 'order_subscription'
+ *
+ * @example
+ * // Without mapping, falls back to library default
+ * resolveCategory('Order', 'subscription', {})
+ * // Returns: 'subscription'
+ *
+ * @example
+ * // Different entities with different mappings
+ * const mappings = {
+ *   Order: 'order_subscription',
+ *   PlatformSubscription: 'platform_subscription',
+ *   TenantUpgrade: 'tenant_upgrade',
+ *   Membership: 'gym_membership',
+ *   Enrollment: 'course_enrollment',
+ * };
+ * resolveCategory('PlatformSubscription', 'subscription', mappings)
+ * // Returns: 'platform_subscription'
+ */
+export function resolveCategory(entity: string, monetizationType: string, categoryMappings?: any): string;
+/**
+ * Validate that a category is defined in user's Transaction model enum
+ * This is informational - actual validation happens at Mongoose schema level
+ *
+ * @param {String} category - Category to validate
+ * @param {Array<String>} allowedCategories - List of allowed categories
+ * @returns {Boolean} Whether category is valid
+ */
+export function isCategoryValid(category: string, allowedCategories?: Array<string>): boolean;
+export default resolveCategory;

package/dist/types/utils/commission-split.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Calculate multi-party commission splits
+ *
+ * @param {Number} amount - Transaction amount
+ * @param {Array} splitRules - Split configuration
+ * @param {Number} gatewayFeeRate - Gateway fee rate (optional)
+ * @returns {Array} Split objects
+ *
+ * @example
+ * calculateSplits(1000, [
+ *   { type: 'platform_commission', recipientId: 'platform', recipientType: 'platform', rate: 0.10 },
+ *   { type: 'affiliate_commission', recipientId: 'affiliate-123', recipientType: 'user', rate: 0.02 },
+ * ], 0.018);
+ *
+ * Returns:
+ * [
+ *   { type: 'platform_commission', recipientId: 'platform', grossAmount: 100, gatewayFeeAmount: 18, netAmount: 82, ... },
+ *   { type: 'affiliate_commission', recipientId: 'affiliate-123', grossAmount: 20, gatewayFeeAmount: 0, netAmount: 20, ... },
+ * ]
+ */
+export function calculateSplits(amount: number, splitRules?: any[], gatewayFeeRate?: number): any[];
+/**
+ * Calculate organization payout after splits
+ *
+ * @param {Number} amount - Total transaction amount
+ * @param {Array} splits - Calculated splits
+ * @returns {Number} Amount organization receives
+ */
+export function calculateOrganizationPayout(amount: number, splits?: any[]): number;
+/**
+ * Reverse splits proportionally on refund
+ *
+ * @param {Array} originalSplits - Original split objects
+ * @param {Number} originalAmount - Original transaction amount
+ * @param {Number} refundAmount - Amount being refunded
+ * @returns {Array} Reversed splits
+ */
+export function reverseSplits(originalSplits: any[], originalAmount: number, refundAmount: number): any[];
+/**
+ * Build commission object with splits support
+ * Backward compatible with existing calculateCommission
+ *
+ * @param {Number} amount - Transaction amount
+ * @param {Number} commissionRate - Platform commission rate
+ * @param {Number} gatewayFeeRate - Gateway fee rate
+ * @param {Object} options - Additional options
+ * @returns {Object} Commission with optional splits
+ */
+export function calculateCommissionWithSplits(amount: number, commissionRate: number, gatewayFeeRate?: number, options?: any): any;
+declare namespace _default {
+    export { calculateSplits };
+    export { calculateOrganizationPayout };
+    export { reverseSplits };
+    export { calculateCommissionWithSplits };
+}
+export default _default;

package/dist/types/utils/commission.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Commission Calculation Utility
+ * @classytic/revenue
+ *
+ * Handles platform commission calculation with gateway fee deduction
+ */
+/**
+ * Build commission object for transaction
+ *
+ * @param {Number} amount - Transaction amount
+ * @param {Number} commissionRate - Commission rate (0 to 1, e.g., 0.10 for 10%)
+ * @param {Number} gatewayFeeRate - Gateway fee rate (0 to 1, e.g., 0.018 for 1.8%)
+ * @returns {Object} Commission object or null
+ */
+export function calculateCommission(amount: number, commissionRate: number, gatewayFeeRate?: number): any;
+/**
+ * Reverse commission on refund (proportional)
+ *
+ * @param {Object} originalCommission - Original commission object
+ * @param {Number} originalAmount - Original transaction amount
+ * @param {Number} refundAmount - Amount being refunded
+ * @returns {Object} Reversed commission or null
+ */
+export function reverseCommission(originalCommission: any, originalAmount: number, refundAmount: number): any;
+declare namespace _default {
+    export { calculateCommission };
+    export { reverseCommission };
+}
+export default _default;

package/dist/types/utils/hooks.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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: any, event: string, data: any, logger: any): void;
+export default triggerHook;

package/dist/types/utils/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./transaction-type.js";
+export * from "./subscription/index.js";
+export { triggerHook } from "./hooks.js";
+export { default as logger, setLogger } from "./logger.js";
+export { calculateCommission, reverseCommission } from "./commission.js";
+export { calculateSplits, calculateOrganizationPayout, reverseSplits, calculateCommissionWithSplits } from "./commission-split.js";

package/dist/types/utils/logger.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Set custom logger implementation
+ * @param {Object} customLogger - Logger instance with info, warn, error, debug methods
+ */
+export function setLogger(customLogger: any): void;
+export namespace logger {
+    function info(...args: any[]): void;
+    function warn(...args: any[]): void;
+    function error(...args: any[]): void;
+    function debug(...args: any[]): void;
+}
+export default logger;

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

@@ -0,0 +1,28 @@
+/**
+ * Check if subscription is active
+ */
+export function isSubscriptionActive(subscription: any): boolean;
+/**
+ * Check if can renew
+ */
+export function canRenewSubscription(entity: any): boolean;
+/**
+ * Check if can cancel
+ */
+export function canCancelSubscription(entity: any): boolean;
+/**
+ * Check if can pause
+ */
+export function canPauseSubscription(entity: any): boolean;
+/**
+ * Check if can resume
+ */
+export function canResumeSubscription(entity: any): boolean;
+declare namespace _default {
+    export { isSubscriptionActive };
+    export { canRenewSubscription };
+    export { canCancelSubscription };
+    export { canPauseSubscription };
+    export { canResumeSubscription };
+}
+export default _default;

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

@@ -0,0 +1,2 @@
+export { addDuration, calculatePeriodRange, calculateProratedAmount, resolveIntervalToDuration } from "./period.js";
+export { isSubscriptionActive, canRenewSubscription, canCancelSubscription, canPauseSubscription, canResumeSubscription } from "./actions.js";