@classytic/revenue 0.1.0 → 0.2.0

package/README.md

@@ -494,24 +494,71 @@ const transactions = await Transaction.find({ ... })
 const revenue = createRevenue({
   models: { Transaction },
   hooks: {
-    'subscription.created': async ({ subscription, transaction }) => {
-      console.log('New subscription:', subscription._id);
+    // Monetization lifecycle (specific)
+    'purchase.created': async ({ transaction, isFree }) => {
+      console.log('One-time purchase:', transaction._id);
     },
+    'subscription.created': async ({ transaction, isFree }) => {
+      console.log('Recurring subscription:', transaction._id);
+    },
+    'free.created': async ({ transaction }) => {
+      console.log('Free access granted:', transaction._id);
+    },
+    
+    // Generic event (fires for all types)
+    'monetization.created': async ({ transaction, monetizationType }) => {
+      console.log(`${monetizationType} created:`, transaction._id);
+    },
+
+    // Payment lifecycle
     'payment.verified': async ({ transaction }) => {
       // Send confirmation email
     },
+    'payment.failed': async ({ transaction, error, provider }) => {
+      // Alert admin or send customer notification
+      console.error('Payment failed:', error);
+    },
     'payment.refunded': async ({ refundTransaction }) => {
       // Process refund notification
     },
+    
+    // Subscription management (requires Subscription model)
+    'subscription.activated': async ({ subscription }) => {
+      // Subscription activated after payment
+    },
+    'subscription.renewed': async ({ subscription, renewalCount }) => {
+      // Subscription renewed
+    },
+    'subscription.paused': async ({ subscription }) => {
+      // Subscription paused
+    },
+    'subscription.resumed': async ({ subscription }) => {
+      // Subscription resumed
+    },
+    'subscription.cancelled': async ({ subscription }) => {
+      // Subscription cancelled
+    },
   },
 });
 ```
 
 **Available hooks:**
-- `subscription.created`, `subscription.activated`, `subscription.renewed`
+
+**Monetization Events (specific):**
+- `purchase.created` - One-time purchase
+- `subscription.created` - Recurring subscription
+- `free.created` - Free access granted
+- `monetization.created` - Generic event (fires for all types)
+
+**Payment Events:**
+- `payment.verified` - Payment confirmed
+- `payment.failed` - Payment verification failed
+- `payment.refunded` - Refund processed
+- `payment.webhook.{type}` - Webhook events from providers
+
+**Subscription Management Events (requires Subscription model):**
+- `subscription.activated`, `subscription.renewed`
 - `subscription.paused`, `subscription.resumed`, `subscription.cancelled`
-- `payment.verified`, `payment.refunded`
-- `payment.webhook.{type}` (for webhook events)
 
 ## Provider Patterns
 
@@ -599,6 +646,7 @@ const subscription = await revenue.subscriptions.create({ ... });
 - [`examples/transaction.model.js`](examples/transaction.model.js) - Complete model setup
 - [`examples/complete-flow.js`](examples/complete-flow.js) - Full lifecycle (types, refs, state)
 - [`examples/commission-tracking.js`](examples/commission-tracking.js) - Commission calculation
+- [`examples/hooks-v0.2.0.js`](examples/hooks-v0.2.0.js) - v0.2.0 semantic hooks (NEW)
 
 ## Error Handling
 

package/core/builder.js

@@ -18,7 +18,7 @@ import { ConfigurationError } from './errors.js';
  *
  * @param {Object} options - Configuration options
  * @param {Object} options.models - Mongoose models { Transaction, Subscription, etc. }
- * @param {Object} options.providers - Payment providers { manual, stripe, etc. }
+ * @param {Record<string, import('../providers/base.js').PaymentProvider>} options.providers - Payment providers - Register ANY custom gateway by name
  * @param {Object} options.hooks - Event hooks
  * @param {Object} options.config - Additional configuration
  * @param {Object} options.logger - Logger instance
@@ -26,7 +26,8 @@ import { ConfigurationError } from './errors.js';
  *
  * @example
  * ```javascript
- * import { createRevenue, ManualProvider } from '@classytic/revenue';
+ * import { createRevenue } from '@classytic/revenue';
+ * import { ManualProvider } from '@classytic/revenue-manual';
  *
  * const revenue = createRevenue({
  *   models: {
@@ -35,6 +36,10 @@ import { ConfigurationError } from './errors.js';
  *   },
  *   providers: {
  *     manual: new ManualProvider(),
+ *     bkash: new BkashProvider(),      // Custom gateway
+ *     nagad: new NagadProvider(),      // Custom gateway
+ *     stripe: new StripeProvider(),    // Custom gateway
+ *     // ... register any gateway you want
  *   },
  *   config: {
  *     targetModels: ['Subscription', 'Membership'],
@@ -45,8 +50,11 @@ import { ConfigurationError } from './errors.js';
  *   },
  * });
  *
- * // Use anywhere
- * const subscription = await revenue.subscriptions.create({ ... });
+ * // Use any registered gateway by name
+ * const subscription = await revenue.subscriptions.create({
+ *   gateway: 'bkash',  // Use your custom gateway
+ *   // ...
+ * });
  * await revenue.payments.verify(txnId);
  * ```
  */

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

@@ -3,7 +3,7 @@
  *
  * @param {Object} options - Configuration options
  * @param {Object} options.models - Mongoose models { Transaction, Subscription, etc. }
- * @param {Object} options.providers - Payment providers { manual, stripe, etc. }
+ * @param {Record<string, import('../providers/base.js').PaymentProvider>} options.providers - Payment providers - Register ANY custom gateway by name
  * @param {Object} options.hooks - Event hooks
  * @param {Object} options.config - Additional configuration
  * @param {Object} options.logger - Logger instance
@@ -11,7 +11,8 @@
  *
  * @example
  * ```javascript
- * import { createRevenue, ManualProvider } from '@classytic/revenue';
+ * import { createRevenue } from '@classytic/revenue';
+ * import { ManualProvider } from '@classytic/revenue-manual';
  *
  * const revenue = createRevenue({
  *   models: {
@@ -20,6 +21,10 @@
  *   },
  *   providers: {
  *     manual: new ManualProvider(),
+ *     bkash: new BkashProvider(),      // Custom gateway
+ *     nagad: new NagadProvider(),      // Custom gateway
+ *     stripe: new StripeProvider(),    // Custom gateway
+ *     // ... register any gateway you want
  *   },
  *   config: {
  *     targetModels: ['Subscription', 'Membership'],
@@ -30,14 +35,17 @@
  *   },
  * });
  *
- * // Use anywhere
- * const subscription = await revenue.subscriptions.create({ ... });
+ * // Use any registered gateway by name
+ * const subscription = await revenue.subscriptions.create({
+ *   gateway: 'bkash',  // Use your custom gateway
+ *   // ...
+ * });
  * await revenue.payments.verify(txnId);
  * ```
  */
 export function createRevenue(options?: {
     models: any;
-    providers: any;
+    providers: Record<string, import("../providers/base.js").PaymentProvider>;
     hooks: any;
     config: any;
     logger: any;

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

@@ -18,7 +18,7 @@ export class SubscriptionService {
      * @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.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')
@@ -35,6 +35,7 @@ export class SubscriptionService {
      *     referenceId: subscription._id,      // Links to entity
      *     referenceModel: 'Subscription',     // Model name
      *   },
+     *   gateway: 'bkash',  // Any registered provider
      *   amount: 1500,
      *   // ...
      * });
@@ -66,7 +67,7 @@ export class SubscriptionService {
      *
      * @param {String} subscriptionId - Subscription ID
      * @param {Object} params - Renewal parameters
-     * @param {String} params.gateway - Payment gateway to use (default: 'manual')
+     * @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 (optional, inherits from subscription)
      * @param {Object} params.paymentData - Payment method details
      * @param {Object} params.metadata - Additional metadata

package/enums/payment.enums.js

@@ -22,13 +22,34 @@ export const PAYMENT_STATUS_VALUES = Object.values(PAYMENT_STATUS);
 
 // ============ PAYMENT GATEWAY TYPES ============
 /**
- * Gateway types that providers can be built for
+ * Common gateway type constants for convenience
  *
- * MANUAL: Built-in manual provider
- * STRIPE: Stripe provider (build with @classytic/revenue-stripe)
- * SSLCOMMERZ: SSLCommerz provider (build with @classytic/revenue-sslcommerz)
+ * ⚠️ IMPORTANT: These are NOT restrictions - just common reference values
  *
- * Users can register custom providers for any gateway type
+ * You can register ANY custom gateway provider by passing it to createRevenue():
+ *
+ * @example
+ * ```javascript
+ * const revenue = createRevenue({
+ *   providers: {
+ *     manual: new ManualProvider(),
+ *     bkash: new BkashProvider(),      // ✅ Custom gateway
+ *     nagad: new NagadProvider(),      // ✅ Custom gateway
+ *     stripe: new StripeProvider(),    // ✅ Custom gateway
+ *     paypal: new PaypalProvider(),    // ✅ Any gateway you want
+ *   }
+ * });
+ *
+ * // Use by name
+ * await revenue.subscriptions.create({ gateway: 'bkash', ... });
+ * ```
+ *
+ * Reference values:
+ * - MANUAL: Built-in manual provider (@classytic/revenue-manual)
+ * - STRIPE: Stripe provider (build with @classytic/revenue-stripe)
+ * - SSLCOMMERZ: SSLCommerz provider (build with @classytic/revenue-sslcommerz)
+ *
+ * Add your own: bkash, nagad, rocket, paypal, razorpay, flutterwave, etc.
  */
 export const PAYMENT_GATEWAY_TYPE = {
   MANUAL: 'manual',

package/index.js

@@ -1,6 +1,6 @@
 /**
  * @classytic/revenue
- * Enterprise Revenue Management System
+ * Revenue Management System
  *
  * A unified, enterprise-grade revenue management system combining
  * monetization (subscriptions, purchases, proration) and payment processing
@@ -8,7 +8,7 @@
  *
  * Thin, focused, production-ready library with smart defaults.
  *
- * @version 1.0.0
+ * @version 0.2.0
  * @author Classytic (Classytic)
  * @license MIT
  */

package/package.json

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

package/services/payment.service.js

@@ -83,12 +83,22 @@ export class PaymentService {
 
       // Update transaction as failed
       transaction.status = 'failed';
+      transaction.failureReason = error.message;
       transaction.metadata = {
         ...transaction.metadata,
         verificationError: error.message,
+        failedAt: new Date().toISOString(),
       };
       await transaction.save();
 
+      // Trigger payment.failed hook
+      this._triggerHook('payment.failed', {
+        transaction,
+        error: error.message,
+        provider: gatewayType,
+        paymentIntentId,
+      });
+
       throw new PaymentVerificationError(paymentIntentId, error.message);
     }
 

package/services/subscription.service.js

@@ -45,14 +45,14 @@ export class SubscriptionService {
    * @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.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
-   * 
+   *
    * @example
    * // With polymorphic reference (recommended)
    * await revenue.subscriptions.create({
@@ -62,10 +62,11 @@ export class SubscriptionService {
    *     referenceId: subscription._id,      // Links to entity
    *     referenceModel: 'Subscription',     // Model name
    *   },
+   *   gateway: 'bkash',  // Any registered provider
    *   amount: 1500,
    *   // ...
    * });
-   * 
+   *
    * @returns {Promise<Object>} { subscription, transaction, paymentIntent }
    */
   async create(params) {
@@ -204,13 +205,26 @@ export class SubscriptionService {
       subscription = await SubscriptionModel.create(subscriptionData);
     }
 
-    // Trigger hook
-    this._triggerHook('subscription.created', {
+    // Trigger hooks - emit specific event based on monetization type
+    const eventData = {
       subscription,
       transaction,
       paymentIntent,
       isFree,
-    });
+      monetizationType,
+    };
+
+    // Emit specific monetization event
+    if (monetizationType === MONETIZATION_TYPES.PURCHASE) {
+      this._triggerHook('purchase.created', eventData);
+    } else if (monetizationType === MONETIZATION_TYPES.SUBSCRIPTION) {
+      this._triggerHook('subscription.created', eventData);
+    } else if (monetizationType === MONETIZATION_TYPES.FREE) {
+      this._triggerHook('free.created', eventData);
+    }
+
+    // Also emit generic event for backward compatibility
+    this._triggerHook('monetization.created', eventData);
 
     return {
       subscription,
@@ -271,7 +285,7 @@ export class SubscriptionService {
    *
    * @param {String} subscriptionId - Subscription ID
    * @param {Object} params - Renewal parameters
-   * @param {String} params.gateway - Payment gateway to use (default: 'manual')
+   * @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 (optional, inherits from subscription)
    * @param {Object} params.paymentData - Payment method details
    * @param {Object} params.metadata - Additional metadata