@classytic/revenue 0.2.1 → 0.2.2

package/README.md

@@ -38,9 +38,10 @@ const revenue = createRevenue({
 });
 
 // Create subscription (no organizationId needed)
-const { transaction } = await revenue.subscriptions.create({
+const { transaction } = await revenue.monetization.create({
   data: { customerId: user._id },
   planKey: 'monthly',
+  monetizationType: 'subscription',
   amount: 2999,  // $29.99
   gateway: 'manual',
   paymentData: { method: 'card' },
@@ -54,14 +55,15 @@ await revenue.payments.verify(transaction.gateway.paymentIntentId);
 
 ```javascript
 // Same API, just pass organizationId
-const { transaction } = await revenue.subscriptions.create({
+const { transaction } = await revenue.monetization.create({
   data: {
     organizationId: vendor._id,  // ← Multi-tenant
     customerId: customer._id,
     referenceId: order._id,
     referenceModel: 'Order',
   },
-  planKey: 'monthly',
+  planKey: 'one_time',
+  monetizationType: 'purchase',  // One-time purchase
   amount: 1500,
   gateway: 'manual',
   paymentData: { method: 'bkash' },
@@ -152,7 +154,7 @@ const schema = new mongoose.Schema({
 ```javascript
 // Create subscription
 const { subscription, transaction, paymentIntent } = 
-  await revenue.subscriptions.create({
+  await revenue.monetization.create({
     data: { organizationId, customerId },
     planKey: 'monthly',
     amount: 1500,
@@ -163,20 +165,20 @@ const { subscription, transaction, paymentIntent } =
 
 // Verify and activate
 await revenue.payments.verify(transaction.gateway.paymentIntentId);
-await revenue.subscriptions.activate(subscription._id);
+await revenue.monetization.activate(subscription._id);
 
 // Renew subscription
-await revenue.subscriptions.renew(subscription._id, {
+await revenue.monetization.renew(subscription._id, {
   gateway: 'manual',
   paymentData: { method: 'nagad' },
 });
 
 // Pause/Resume
-await revenue.subscriptions.pause(subscription._id, { reason: 'Customer request' });
-await revenue.subscriptions.resume(subscription._id, { extendPeriod: true });
+await revenue.monetization.pause(subscription._id, { reason: 'Customer request' });
+await revenue.monetization.resume(subscription._id, { extendPeriod: true });
 
 // Cancel
-await revenue.subscriptions.cancel(subscription._id, { immediate: true });
+await revenue.monetization.cancel(subscription._id, { immediate: true });
 ```
 
 ### Payments
@@ -267,7 +269,7 @@ const revenue = createRevenue({
 });
 
 // Usage
-await revenue.subscriptions.create({
+await revenue.monetization.create({
   entity: 'Order',  // Maps to 'order_subscription' category
   monetizationType: 'subscription',
   // ...
@@ -301,7 +303,7 @@ const revenue = createRevenue({
 });
 
 // Commission calculated automatically
-const { transaction } = await revenue.subscriptions.create({
+const { transaction } = await revenue.monetization.create({
   amount: 10000, // $100
   entity: 'ProductOrder',  // → 10% commission
   gateway: 'stripe',       // → 2.9% fee
@@ -357,7 +359,7 @@ const refund = calculateProratedAmount({
 
 // Check eligibility
 if (canRenewSubscription(membership)) {
-  await revenue.subscriptions.renew(membership.subscriptionId);
+  await revenue.monetization.renew(membership.subscriptionId);
 }
 ```
 
@@ -369,7 +371,7 @@ if (canRenewSubscription(membership)) {
 
 ```javascript
 // 1. Customer makes purchase
-const { transaction } = await revenue.subscriptions.create({
+const { transaction } = await revenue.monetization.create({
   amount: 1000,
   gateway: 'stripe',
   // ...
@@ -464,7 +466,7 @@ Link transactions to any entity (Order, Subscription, Enrollment):
 
 ```javascript
 // Create transaction linked to Order
-const { transaction } = await revenue.subscriptions.create({
+const { transaction } = await revenue.monetization.create({
   data: {
     organizationId,
     customerId,
@@ -637,7 +639,7 @@ const revenue: Revenue = createRevenue({
 
 // All services are fully typed
 const payment = await revenue.payments.verify(id);
-const subscription = await revenue.subscriptions.create({ ... });
+const subscription = await revenue.monetization.create({ ... });
 ```
 
 ## Examples

package/core/builder.js

@@ -7,7 +7,7 @@
  */
 
 import { Container } from './container.js';
-import { SubscriptionService } from '../services/subscription.service.js';
+import { MonetizationService } from '../services/monetization.service.js';
 import { PaymentService } from '../services/payment.service.js';
 import { TransactionService } from '../services/transaction.service.js';
 import { EscrowService } from '../services/escrow.service.js';
@@ -51,11 +51,13 @@ import { ConfigurationError } from './errors.js';
  * });
  *
  * // Use any registered gateway by name
- * const subscription = await revenue.subscriptions.create({
+ * const { transaction } = await revenue.monetization.create({
  *   gateway: 'bkash',  // Use your custom gateway
+ *   monetizationType: 'purchase',
+ *   amount: 1500,
  *   // ...
  * });
- * await revenue.payments.verify(txnId);
+ * await revenue.payments.verify(transaction._id);
  * ```
  */
 export function createRevenue(options = {}) {
@@ -98,7 +100,7 @@ export function createRevenue(options = {}) {
 
   // Create service instances (lazy-loaded)
   const services = {
-    subscriptions: null,
+    monetization: null,
     payments: null,
     transactions: null,
     escrow: null,
@@ -122,14 +124,14 @@ export function createRevenue(options = {}) {
     config,
 
     /**
-     * Subscription service
+     * Monetization service (handles purchases, subscriptions, free items)
      * Lazy-loaded on first access
      */
-    get subscriptions() {
-      if (!services.subscriptions) {
-        services.subscriptions = new SubscriptionService(container);
+    get monetization() {
+      if (!services.monetization) {
+        services.monetization = new MonetizationService(container);
       }
-      return services.subscriptions;
+      return services.monetization;
     },
 
     /**
@@ -207,7 +209,7 @@ function validateProvider(name, provider) {
  * @property {Container} container - DI container (readonly)
  * @property {Object} providers - Payment providers (readonly, frozen)
  * @property {Object} config - Configuration (readonly, frozen)
- * @property {SubscriptionService} subscriptions - Subscription service
+ * @property {MonetizationService} monetization - Monetization service (purchases, subscriptions, free items)
  * @property {PaymentService} payments - Payment service
  * @property {TransactionService} transactions - Transaction service
  * @property {EscrowService} escrow - Escrow service

package/dist/types/core/builder.d.ts

@@ -36,11 +36,13 @@
  * });
  *
  * // Use any registered gateway by name
- * const subscription = await revenue.subscriptions.create({
+ * const { transaction } = await revenue.monetization.create({
  *   gateway: 'bkash',  // Use your custom gateway
+ *   monetizationType: 'purchase',
+ *   amount: 1500,
  *   // ...
  * });
- * await revenue.payments.verify(txnId);
+ * await revenue.payments.verify(transaction._id);
  * ```
  */
 export function createRevenue(options?: {
@@ -68,9 +70,9 @@ export type Revenue = {
      */
     config: any;
     /**
-     * - Subscription service
+     * - Monetization service (purchases, subscriptions, free items)
      */
-    subscriptions: SubscriptionService;
+    monetization: MonetizationService;
     /**
      * - Payment service
      */
@@ -89,7 +91,7 @@ export type Revenue = {
     getProvider: Function;
 };
 import { Container } from './container.js';
-import { SubscriptionService } from '../services/subscription.service.js';
+import { MonetizationService } from '../services/monetization.service.js';
 import { PaymentService } from '../services/payment.service.js';
 import { TransactionService } from '../services/transaction.service.js';
 import { EscrowService } from '../services/escrow.service.js';

package/dist/types/index.d.ts

@@ -3,7 +3,7 @@ export { Container } from "./core/container.js";
 export * from "./core/errors.js";
 export * from "./enums/index.js";
 export * from "./schemas/index.js";
-export { SubscriptionService } from "./services/subscription.service.js";
+export { MonetizationService } from "./services/monetization.service.js";
 export { PaymentService } from "./services/payment.service.js";
 export { TransactionService } from "./services/transaction.service.js";
 export { EscrowService } from "./services/escrow.service.js";

package/dist/types/services/{subscription.service.d.ts → monetization.service.d.ts}

@@ -1,8 +1,8 @@
 /**
- * Subscription Service
+ * Monetization Service
  * Uses DI container for all dependencies
  */
-export class SubscriptionService {
+export class MonetizationService {
     constructor(container: any);
     container: any;
     models: any;
@@ -11,49 +11,42 @@ export class SubscriptionService {
     hooks: any;
     logger: any;
     /**
-     * Create a new subscription
+     * Create a new monetization (purchase, subscription, or free item)
      *
-     * @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 name (default: 'manual') - Use ANY registered provider name: 'manual', 'bkash', 'nagad', 'stripe', etc.
-     * @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
+     * @param {MonetizationCreateParams} params - Monetization parameters
      *
      * @example
-     * // With polymorphic reference (recommended)
-     * await revenue.subscriptions.create({
+     * // One-time purchase
+     * await revenue.monetization.create({
      *   data: {
      *     organizationId: '...',
      *     customerId: '...',
-     *     referenceId: subscription._id,      // Links to entity
-     *     referenceModel: 'Subscription',     // Model name
+     *     referenceId: order._id,
+     *     referenceModel: 'Order',
      *   },
-     *   gateway: 'bkash',  // Any registered provider
+     *   planKey: 'one_time',
+     *   monetizationType: 'purchase',
+     *   gateway: 'bkash',
      *   amount: 1500,
-     *   // ...
      * });
      *
-     * @returns {Promise<Object>} { subscription, transaction, paymentIntent }
+     * // Recurring subscription
+     * await revenue.monetization.create({
+     *   data: {
+     *     organizationId: '...',
+     *     customerId: '...',
+     *     referenceId: subscription._id,
+     *     referenceModel: 'Subscription',
+     *   },
+     *   planKey: 'monthly',
+     *   monetizationType: 'subscription',
+     *   gateway: 'stripe',
+     *   amount: 2000,
+     * });
+     *
+     * @returns {Promise<MonetizationCreateResult>} Result with subscription, transaction, and 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>;
+    create(params: MonetizationCreateParams): Promise<MonetizationCreateResult>;
     /**
      * Activate subscription after payment verification
      *
@@ -136,4 +129,65 @@ export class SubscriptionService {
      */
     private _triggerHook;
 }
-export default SubscriptionService;
+export default MonetizationService;
+export type MonetizationCreateParams = {
+    /**
+     * - Monetization data
+     */
+    data: {
+        organizationId?: string;
+        customerId?: string;
+        referenceId?: string;
+        referenceModel?: string;
+    };
+    /**
+     * - Plan key ('monthly', 'quarterly', 'yearly', 'one_time', etc.)
+     */
+    planKey: string;
+    /**
+     * - Amount (0 for free)
+     */
+    amount: number;
+    /**
+     * - Currency code
+     */
+    currency?: string;
+    /**
+     * - Payment gateway name
+     */
+    gateway?: string;
+    /**
+     * - Logical entity identifier
+     */
+    entity?: string;
+    /**
+     * - Monetization type
+     */
+    monetizationType?: "free" | "subscription" | "purchase";
+    /**
+     * - Payment method details
+     */
+    paymentData?: any;
+    /**
+     * - Additional metadata
+     */
+    metadata?: any;
+    /**
+     * - Idempotency key
+     */
+    idempotencyKey?: string;
+};
+export type MonetizationCreateResult = {
+    /**
+     * - Subscription record (if Subscription model exists)
+     */
+    subscription: any | null;
+    /**
+     * - Transaction record
+     */
+    transaction: any | null;
+    /**
+     * - Payment intent from provider
+     */
+    paymentIntent: any | null;
+};

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

@@ -78,3 +78,35 @@ export class PaymentService {
     private _triggerHook;
 }
 export default PaymentService;
+export type PaymentVerifyResult = {
+    /**
+     * - Updated transaction
+     */
+    transaction: any;
+    /**
+     * - Payment result from provider
+     */
+    paymentResult: any;
+    /**
+     * - Payment status
+     */
+    status: string;
+};
+export type PaymentRefundResult = {
+    /**
+     * - Original transaction (updated)
+     */
+    transaction: any;
+    /**
+     * - New refund transaction record
+     */
+    refundTransaction: any;
+    /**
+     * - Refund result from provider
+     */
+    refundResult: any;
+    /**
+     * - Transaction status after refund
+     */
+    status: string;
+};

package/enums/payment.enums.js

@@ -41,7 +41,7 @@ export const PAYMENT_STATUS_VALUES = Object.values(PAYMENT_STATUS);
  * });
  *
  * // Use by name
- * await revenue.subscriptions.create({ gateway: 'bkash', ... });
+ * await revenue.monetization.create({ gateway: 'bkash', ... });
  * ```
  *
  * Reference values:

package/index.js

@@ -35,7 +35,7 @@ import { PaymentProvider as _PaymentProvider } from './providers/base.js';
 // Note: ManualProvider moved to @classytic/revenue-manual (separate package)
 
 // ============ SERVICES (ADVANCED USAGE) ============
-export { SubscriptionService } from './services/subscription.service.js';
+export { MonetizationService } from './services/monetization.service.js';
 export { PaymentService } from './services/payment.service.js';
 export { TransactionService } from './services/transaction.service.js';
 export { EscrowService } from './services/escrow.service.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/revenue",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Enterprise revenue management system with subscriptions, purchases, proration, payment processing, escrow, and multi-party splits",
   "main": "index.js",
   "type": "module",

package/services/{subscription.service.js → monetization.service.js}

@@ -1,9 +1,34 @@
 /**
- * Subscription Service
+ * Monetization Service
  * @classytic/revenue
  *
- * Framework-agnostic subscription management service with DI
- * Handles complete subscription lifecycle using provider system
+ * Framework-agnostic monetization management service with DI
+ * Handles purchases, subscriptions, and free items using provider system
+ */
+
+/**
+ * @typedef {Object} MonetizationCreateParams
+ * @property {Object} data - Monetization data
+ * @property {string} [data.organizationId] - Organization ID (for multi-tenant)
+ * @property {string} [data.customerId] - Customer ID
+ * @property {string} [data.referenceId] - Reference to entity (Order, Subscription, etc.)
+ * @property {string} [data.referenceModel] - Model name for reference
+ * @property {string} planKey - Plan key ('monthly', 'quarterly', 'yearly', 'one_time', etc.)
+ * @property {number} amount - Amount (0 for free)
+ * @property {string} [currency='BDT'] - Currency code
+ * @property {string} [gateway='manual'] - Payment gateway name
+ * @property {string} [entity] - Logical entity identifier
+ * @property {'free'|'subscription'|'purchase'} [monetizationType='subscription'] - Monetization type
+ * @property {Object} [paymentData] - Payment method details
+ * @property {Object} [metadata] - Additional metadata
+ * @property {string} [idempotencyKey] - Idempotency key
+ */
+
+/**
+ * @typedef {Object} MonetizationCreateResult
+ * @property {Object|null} subscription - Subscription record (if Subscription model exists)
+ * @property {Object|null} transaction - Transaction record
+ * @property {Object|null} paymentIntent - Payment intent from provider
  */
 
 import { nanoid } from 'nanoid';
@@ -24,10 +49,10 @@ import { MONETIZATION_TYPES } from '../enums/monetization.enums.js';
 import { TRANSACTION_TYPE } from '../enums/transaction.enums.js';
 
 /**
- * Subscription Service
+ * Monetization Service
  * Uses DI container for all dependencies
  */
-export class SubscriptionService {
+export class MonetizationService {
   constructor(container) {
     this.container = container;
     this.models = container.get('models');
@@ -38,36 +63,40 @@ export class SubscriptionService {
   }
 
   /**
-   * Create a new subscription
+   * Create a new monetization (purchase, subscription, or free item)
    *
-   * @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 name (default: 'manual') - Use ANY registered provider name: 'manual', 'bkash', 'nagad', 'stripe', etc.
-   * @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
+   * @param {MonetizationCreateParams} params - Monetization parameters
    *
    * @example
-   * // With polymorphic reference (recommended)
-   * await revenue.subscriptions.create({
+   * // One-time purchase
+   * await revenue.monetization.create({
    *   data: {
    *     organizationId: '...',
    *     customerId: '...',
-   *     referenceId: subscription._id,      // Links to entity
-   *     referenceModel: 'Subscription',     // Model name
+   *     referenceId: order._id,
+   *     referenceModel: 'Order',
    *   },
-   *   gateway: 'bkash',  // Any registered provider
+   *   planKey: 'one_time',
+   *   monetizationType: 'purchase',
+   *   gateway: 'bkash',
    *   amount: 1500,
-   *   // ...
    * });
    *
-   * @returns {Promise<Object>} { subscription, transaction, paymentIntent }
+   * // Recurring subscription
+   * await revenue.monetization.create({
+   *   data: {
+   *     organizationId: '...',
+   *     customerId: '...',
+   *     referenceId: subscription._id,
+   *     referenceModel: 'Subscription',
+   *   },
+   *   planKey: 'monthly',
+   *   monetizationType: 'subscription',
+   *   gateway: 'stripe',
+   *   amount: 2000,
+   * });
+   *
+   * @returns {Promise<MonetizationCreateResult>} Result with subscription, transaction, and paymentIntent
    */
   async create(params) {
     const {
@@ -641,4 +670,4 @@ export class SubscriptionService {
   }
 }
 
-export default SubscriptionService;
+export default MonetizationService;

package/services/payment.service.js

@@ -6,6 +6,21 @@
  * 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,