@classytic/revenue 0.0.1

package/core/container.js

@@ -0,0 +1,119 @@
+/**
+ * Dependency Injection Container
+ * @classytic/revenue
+ *
+ * Lightweight DI container for managing dependencies
+ * Inspired by: Awilix, InversifyJS but much simpler
+ */
+
+export class Container {
+  constructor() {
+    this._services = new Map();
+    this._singletons = new Map();
+  }
+
+  /**
+   * Register a service
+   * @param {string} name - Service name
+   * @param {any} implementation - Service implementation or factory
+   * @param {Object} options - Registration options
+   */
+  register(name, implementation, options = {}) {
+    this._services.set(name, {
+      implementation,
+      singleton: options.singleton !== false, // Default to singleton
+      factory: options.factory || false,
+    });
+    return this;
+  }
+
+  /**
+   * Register a singleton service
+   * @param {string} name - Service name
+   * @param {any} implementation - Service implementation
+   */
+  singleton(name, implementation) {
+    return this.register(name, implementation, { singleton: true });
+  }
+
+  /**
+   * Register a transient service (new instance each time)
+   * @param {string} name - Service name
+   * @param {Function} factory - Factory function
+   */
+  transient(name, factory) {
+    return this.register(name, factory, { singleton: false, factory: true });
+  }
+
+  /**
+   * Get a service from the container
+   * @param {string} name - Service name
+   * @returns {any} Service instance
+   */
+  get(name) {
+    // Check if already instantiated as singleton
+    if (this._singletons.has(name)) {
+      return this._singletons.get(name);
+    }
+
+    const service = this._services.get(name);
+    if (!service) {
+      throw new Error(`Service "${name}" not registered in container`);
+    }
+
+    // Handle factory functions
+    if (service.factory) {
+      const instance = service.implementation(this);
+      if (service.singleton) {
+        this._singletons.set(name, instance);
+      }
+      return instance;
+    }
+
+    // Handle direct values
+    if (service.singleton) {
+      this._singletons.set(name, service.implementation);
+    }
+    return service.implementation;
+  }
+
+  /**
+   * Check if service is registered
+   * @param {string} name - Service name
+   * @returns {boolean}
+   */
+  has(name) {
+    return this._services.has(name);
+  }
+
+  /**
+   * Get all registered service names
+   * @returns {string[]}
+   */
+  keys() {
+    return Array.from(this._services.keys());
+  }
+
+  /**
+   * Clear all services (useful for testing)
+   */
+  clear() {
+    this._services.clear();
+    this._singletons.clear();
+  }
+
+  /**
+   * Create a child container (for scoped dependencies)
+   * @returns {Container}
+   */
+  createScope() {
+    const scope = new Container();
+    // Copy parent services
+    this._services.forEach((value, key) => {
+      scope._services.set(key, value);
+    });
+    return scope;
+  }
+}
+
+export default Container;

package/core/errors.js

@@ -0,0 +1,262 @@
+/**
+ * Revenue Error Classes
+ * @classytic/revenue
+ *
+ * Typed errors with codes for better error handling
+ */
+
+/**
+ * Base Revenue Error
+ */
+export class RevenueError extends Error {
+  constructor(message, code, options = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.retryable = options.retryable || false;
+    this.metadata = options.metadata || {};
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      retryable: this.retryable,
+      metadata: this.metadata,
+    };
+  }
+}
+
+/**
+ * Configuration Errors
+ */
+export class ConfigurationError extends RevenueError {
+  constructor(message, metadata = {}) {
+    super(message, 'CONFIGURATION_ERROR', { retryable: false, metadata });
+  }
+}
+
+export class ModelNotRegisteredError extends ConfigurationError {
+  constructor(modelName) {
+    super(
+      `Model "${modelName}" is not registered. Register it via createRevenue({ models: { ${modelName}: ... } })`,
+      { modelName }
+    );
+  }
+}
+
+/**
+ * Provider Errors
+ */
+export class ProviderError extends RevenueError {
+  constructor(message, code, options = {}) {
+    super(message, code, options);
+  }
+}
+
+export class ProviderNotFoundError extends ProviderError {
+  constructor(providerName, availableProviders = []) {
+    super(
+      `Payment provider "${providerName}" not found. Available: ${availableProviders.join(', ')}`,
+      'PROVIDER_NOT_FOUND',
+      { retryable: false, metadata: { providerName, availableProviders } }
+    );
+  }
+}
+
+export class ProviderCapabilityError extends ProviderError {
+  constructor(providerName, capability) {
+    super(
+      `Provider "${providerName}" does not support ${capability}`,
+      'PROVIDER_CAPABILITY_NOT_SUPPORTED',
+      { retryable: false, metadata: { providerName, capability } }
+    );
+  }
+}
+
+export class PaymentIntentCreationError extends ProviderError {
+  constructor(providerName, originalError) {
+    super(
+      `Failed to create payment intent with provider "${providerName}": ${originalError.message}`,
+      'PAYMENT_INTENT_CREATION_FAILED',
+      { retryable: true, metadata: { providerName, originalError: originalError.message } }
+    );
+  }
+}
+
+export class PaymentVerificationError extends ProviderError {
+  constructor(paymentIntentId, reason) {
+    super(
+      `Payment verification failed for intent "${paymentIntentId}": ${reason}`,
+      'PAYMENT_VERIFICATION_FAILED',
+      { retryable: true, metadata: { paymentIntentId, reason } }
+    );
+  }
+}
+
+/**
+ * Resource Not Found Errors
+ */
+export class NotFoundError extends RevenueError {
+  constructor(message, code, metadata = {}) {
+    super(message, code, { retryable: false, metadata });
+  }
+}
+
+export class SubscriptionNotFoundError extends NotFoundError {
+  constructor(subscriptionId) {
+    super(
+      `Subscription not found: ${subscriptionId}`,
+      'SUBSCRIPTION_NOT_FOUND',
+      { subscriptionId }
+    );
+  }
+}
+
+export class TransactionNotFoundError extends NotFoundError {
+  constructor(transactionId) {
+    super(
+      `Transaction not found: ${transactionId}`,
+      'TRANSACTION_NOT_FOUND',
+      { transactionId }
+    );
+  }
+}
+
+/**
+ * Validation Errors
+ */
+export class ValidationError extends RevenueError {
+  constructor(message, metadata = {}) {
+    super(message, 'VALIDATION_ERROR', { retryable: false, metadata });
+  }
+}
+
+export class InvalidAmountError extends ValidationError {
+  constructor(amount) {
+    super(`Invalid amount: ${amount}. Amount must be non-negative`, { amount });
+  }
+}
+
+export class MissingRequiredFieldError extends ValidationError {
+  constructor(fieldName) {
+    super(`Missing required field: ${fieldName}`, { fieldName });
+  }
+}
+
+/**
+ * State Errors
+ */
+export class StateError extends RevenueError {
+  constructor(message, code, metadata = {}) {
+    super(message, code, { retryable: false, metadata });
+  }
+}
+
+export class AlreadyVerifiedError extends StateError {
+  constructor(transactionId) {
+    super(
+      `Transaction ${transactionId} is already verified`,
+      'ALREADY_VERIFIED',
+      { transactionId }
+    );
+  }
+}
+
+export class InvalidStateTransitionError extends StateError {
+  constructor(resourceType, resourceId, fromState, toState) {
+    super(
+      `Invalid state transition for ${resourceType} ${resourceId}: ${fromState} → ${toState}`,
+      'INVALID_STATE_TRANSITION',
+      { resourceType, resourceId, fromState, toState }
+    );
+  }
+}
+
+export class SubscriptionNotActiveError extends StateError {
+  constructor(subscriptionId) {
+    super(
+      `Subscription ${subscriptionId} is not active`,
+      'SUBSCRIPTION_NOT_ACTIVE',
+      { subscriptionId }
+    );
+  }
+}
+
+/**
+ * Operation Errors
+ */
+export class OperationError extends RevenueError {
+  constructor(message, code, options = {}) {
+    super(message, code, options);
+  }
+}
+
+export class RefundNotSupportedError extends OperationError {
+  constructor(providerName) {
+    super(
+      `Refunds are not supported by provider "${providerName}"`,
+      'REFUND_NOT_SUPPORTED',
+      { retryable: false, metadata: { providerName } }
+    );
+  }
+}
+
+export class RefundError extends OperationError {
+  constructor(transactionId, reason) {
+    super(
+      `Refund failed for transaction ${transactionId}: ${reason}`,
+      'REFUND_FAILED',
+      { retryable: true, metadata: { transactionId, reason } }
+    );
+  }
+}
+
+/**
+ * Error Code Constants
+ */
+export const ERROR_CODES = {
+  // Configuration
+  CONFIGURATION_ERROR: 'CONFIGURATION_ERROR',
+  MODEL_NOT_REGISTERED: 'MODEL_NOT_REGISTERED',
+
+  // Provider
+  PROVIDER_NOT_FOUND: 'PROVIDER_NOT_FOUND',
+  PROVIDER_CAPABILITY_NOT_SUPPORTED: 'PROVIDER_CAPABILITY_NOT_SUPPORTED',
+  PAYMENT_INTENT_CREATION_FAILED: 'PAYMENT_INTENT_CREATION_FAILED',
+  PAYMENT_VERIFICATION_FAILED: 'PAYMENT_VERIFICATION_FAILED',
+
+  // Not Found
+  SUBSCRIPTION_NOT_FOUND: 'SUBSCRIPTION_NOT_FOUND',
+  TRANSACTION_NOT_FOUND: 'TRANSACTION_NOT_FOUND',
+
+  // Validation
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  INVALID_AMOUNT: 'INVALID_AMOUNT',
+  MISSING_REQUIRED_FIELD: 'MISSING_REQUIRED_FIELD',
+
+  // State
+  ALREADY_VERIFIED: 'ALREADY_VERIFIED',
+  INVALID_STATE_TRANSITION: 'INVALID_STATE_TRANSITION',
+  SUBSCRIPTION_NOT_ACTIVE: 'SUBSCRIPTION_NOT_ACTIVE',
+
+  // Operations
+  REFUND_NOT_SUPPORTED: 'REFUND_NOT_SUPPORTED',
+  REFUND_FAILED: 'REFUND_FAILED',
+};
+
+/**
+ * Check if error is retryable
+ */
+export function isRetryable(error) {
+  return error instanceof RevenueError && error.retryable;
+}
+
+/**
+ * Check if error is from revenue package
+ */
+export function isRevenueError(error) {
+  return error instanceof RevenueError;
+}

package/enums/index.js

@@ -0,0 +1,70 @@
+/**
+ * @classytic/revenue - Centralized Enums
+ * All enums for the revenue management system
+ *
+ * This file serves as the single source of truth for all enum values
+ * used across monetization and payment subsystems.
+ *
+ * @module @classytic/revenue/enums
+ */
+
+// Re-export all enums
+export * from './transaction.enums.js';
+export * from './payment.enums.js';
+export * from './subscription.enums.js';
+export * from './monetization.enums.js';
+
+// Default export for convenience
+import {
+  TRANSACTION_STATUS,
+  TRANSACTION_STATUS_VALUES,
+  LIBRARY_CATEGORIES,
+  LIBRARY_CATEGORY_VALUES,
+} from './transaction.enums.js';
+
+import {
+  PAYMENT_STATUS,
+  PAYMENT_STATUS_VALUES,
+  PAYMENT_GATEWAY_TYPE,
+  PAYMENT_GATEWAY_TYPE_VALUES,
+  GATEWAY_TYPES,
+  GATEWAY_TYPE_VALUES,
+} from './payment.enums.js';
+
+import {
+  SUBSCRIPTION_STATUS,
+  SUBSCRIPTION_STATUS_VALUES,
+  PLAN_KEYS,
+  PLAN_KEY_VALUES,
+} from './subscription.enums.js';
+
+import {
+  MONETIZATION_TYPES,
+  MONETIZATION_TYPE_VALUES,
+} from './monetization.enums.js';
+
+export default {
+  // Transaction enums
+  TRANSACTION_STATUS,
+  TRANSACTION_STATUS_VALUES,
+  LIBRARY_CATEGORIES,
+  LIBRARY_CATEGORY_VALUES,
+
+  // Payment enums
+  PAYMENT_STATUS,
+  PAYMENT_STATUS_VALUES,
+  PAYMENT_GATEWAY_TYPE,
+  PAYMENT_GATEWAY_TYPE_VALUES,
+  GATEWAY_TYPES,
+  GATEWAY_TYPE_VALUES,
+
+  // Subscription enums
+  SUBSCRIPTION_STATUS,
+  SUBSCRIPTION_STATUS_VALUES,
+  PLAN_KEYS,
+  PLAN_KEY_VALUES,
+
+  // Monetization enums
+  MONETIZATION_TYPES,
+  MONETIZATION_TYPE_VALUES,
+};

package/enums/monetization.enums.js

@@ -0,0 +1,15 @@
+/**
+ * Monetization Enums
+ * @classytic/revenue
+ *
+ * General monetization enums and constants
+ */
+
+// ============ MONETIZATION TYPES ============
+export const MONETIZATION_TYPES = {
+  FREE: 'free',
+  PURCHASE: 'purchase',
+  SUBSCRIPTION: 'subscription',
+};
+
+export const MONETIZATION_TYPE_VALUES = Object.values(MONETIZATION_TYPES);

package/enums/payment.enums.js

@@ -0,0 +1,43 @@
+/**
+ * Payment Enums
+ * @classytic/revenue
+ *
+ * Library-managed payment enums only.
+ * Users define their own payment methods in their schema.
+ */
+
+// ============ PAYMENT STATUS ============
+/**
+ * Payment Status - Library-managed states
+ */
+export const PAYMENT_STATUS = {
+  PENDING: 'pending',
+  VERIFIED: 'verified',
+  FAILED: 'failed',
+  REFUNDED: 'refunded',
+  CANCELLED: 'cancelled',
+};
+
+export const PAYMENT_STATUS_VALUES = Object.values(PAYMENT_STATUS);
+
+// ============ PAYMENT GATEWAY TYPES ============
+/**
+ * Gateway types that providers can be built for
+ *
+ * MANUAL: Built-in manual provider
+ * STRIPE: Stripe provider (build with @classytic/revenue-stripe)
+ * SSLCOMMERZ: SSLCommerz provider (build with @classytic/revenue-sslcommerz)
+ *
+ * Users can register custom providers for any gateway type
+ */
+export const PAYMENT_GATEWAY_TYPE = {
+  MANUAL: 'manual',
+  STRIPE: 'stripe',
+  SSLCOMMERZ: 'sslcommerz',
+};
+
+export const PAYMENT_GATEWAY_TYPE_VALUES = Object.values(PAYMENT_GATEWAY_TYPE);
+
+// Backward compatibility alias
+export const GATEWAY_TYPES = PAYMENT_GATEWAY_TYPE;
+export const GATEWAY_TYPE_VALUES = PAYMENT_GATEWAY_TYPE_VALUES;

package/enums/subscription.enums.js

@@ -0,0 +1,33 @@
+/**
+ * Subscription Enums
+ * @classytic/revenue
+ *
+ * All subscription-related enums and constants
+ */
+
+// ============ SUBSCRIPTION STATUS ============
+/**
+ * Subscription Status
+ */
+export const SUBSCRIPTION_STATUS = {
+  ACTIVE: 'active',
+  PAUSED: 'paused',
+  CANCELLED: 'cancelled',
+  EXPIRED: 'expired',
+  PENDING: 'pending',
+  INACTIVE: 'inactive',
+};
+
+export const SUBSCRIPTION_STATUS_VALUES = Object.values(SUBSCRIPTION_STATUS);
+
+// ============ PLAN KEYS ============
+/**
+ * Supported plan intervals
+ */
+export const PLAN_KEYS = {
+  MONTHLY: 'monthly',
+  QUARTERLY: 'quarterly',
+  YEARLY: 'yearly',
+};
+
+export const PLAN_KEY_VALUES = Object.values(PLAN_KEYS);

package/enums/transaction.enums.js

@@ -0,0 +1,53 @@
+/**
+ * Transaction Enums
+ * @classytic/revenue
+ *
+ * Library-managed transaction enums only.
+ * Users should define their own categories and merge with these.
+ */
+
+// ============ TRANSACTION STATUS ============
+/**
+ * Transaction Status - Library-managed states
+ */
+export const TRANSACTION_STATUS = {
+  PENDING: 'pending',
+  PAYMENT_INITIATED: 'payment_initiated',
+  PROCESSING: 'processing',
+  REQUIRES_ACTION: 'requires_action',
+  VERIFIED: 'verified',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  CANCELLED: 'cancelled',
+  EXPIRED: 'expired',
+  REFUNDED: 'refunded',
+  PARTIALLY_REFUNDED: 'partially_refunded',
+};
+
+export const TRANSACTION_STATUS_VALUES = Object.values(TRANSACTION_STATUS);
+
+// ============ LIBRARY CATEGORIES ============
+/**
+ * Categories managed by this library
+ *
+ * SUBSCRIPTION: Recurring subscription payments
+ * PURCHASE: One-time purchases
+ *
+ * Users should spread these into their own category enums:
+ *
+ * @example
+ * import { LIBRARY_CATEGORIES } from '@classytic/revenue';
+ *
+ * export const MY_CATEGORIES = {
+ *   ...LIBRARY_CATEGORIES,
+ *   SALARY: 'salary',
+ *   RENT: 'rent',
+ *   EQUIPMENT: 'equipment',
+ * };
+ */
+export const LIBRARY_CATEGORIES = {
+  SUBSCRIPTION: 'subscription',
+  PURCHASE: 'purchase',
+};
+
+export const LIBRARY_CATEGORY_VALUES = Object.values(LIBRARY_CATEGORIES);

package/index.js

@@ -0,0 +1,58 @@
+/**
+ * @classytic/revenue
+ * Enterprise Revenue Management System
+ *
+ * A unified, enterprise-grade revenue management system combining
+ * monetization (subscriptions, purchases, proration) and payment processing
+ * (verification, refunds, webhooks) into a single, cohesive package.
+ *
+ * Thin, focused, production-ready library with smart defaults.
+ *
+ * @version 1.0.0
+ * @author Classytic (Classytic)
+ * @license MIT
+ */
+
+// ============ CORE API ============
+export { createRevenue } from './core/builder.js';
+export { Container } from './core/container.js';
+import { createRevenue as _createRevenue } from './core/builder.js';
+import { Container as _Container } from './core/container.js';
+
+// ============ ERROR CLASSES ============
+export * from './core/errors.js';
+import { RevenueError } from './core/errors.js';
+
+// ============ PROVIDER SYSTEM ============
+export {
+  PaymentProvider,
+  PaymentIntent,
+  PaymentResult,
+  RefundResult,
+  WebhookEvent,
+} from './providers/base.js';
+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 { PaymentService } from './services/payment.service.js';
+export { TransactionService } from './services/transaction.service.js';
+
+// ============ ENUMS & SCHEMAS (FOR INJECTION) ============
+export * from './enums/index.js';
+export * from './schemas/index.js';
+
+// ============ UTILITIES ============
+export {
+  logger,
+  setLogger,
+} from './utils/index.js';
+
+// ============ DEFAULT EXPORT ============
+export default {
+  createRevenue: _createRevenue,
+  PaymentProvider: _PaymentProvider,
+  RevenueError,
+  Container: _Container,
+};