@classytic/revenue 0.0.1

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@classytic/revenue",
+  "version": "0.0.1",
+  "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": {
+    ".": "./index.js",
+    "./enums": "./enums/index.js",
+    "./schemas": "./schemas/index.js",
+    "./utils": "./utils/index.js"
+  },
+  "files": [
+    "index.js",
+    "revenue.d.ts",
+    "LICENSE",
+    "README.md",
+    "core/",
+    "providers/",
+    "services/",
+    "enums/",
+    "schemas/",
+    "utils/"
+  ],
+  "dependencies": {
+    "nanoid": "^5.1.6"
+  }
+}

package/providers/base.js

@@ -0,0 +1,162 @@
+/**
+ * Payment Provider Base Class
+ * @classytic/revenue
+ *
+ * Abstract base class for all payment providers
+ * Inspired by: Vercel AI SDK, Stripe SDK
+ */
+
+/**
+ * Payment Intent - standardized response from createIntent
+ */
+export class PaymentIntent {
+  constructor(data) {
+    this.id = data.id;
+    this.provider = data.provider;
+    this.status = data.status; // 'pending', 'processing', 'requires_action', 'succeeded', 'failed'
+    this.amount = data.amount;
+    this.currency = data.currency || 'BDT';
+    this.metadata = data.metadata || {};
+
+    // Provider-specific data
+    this.clientSecret = data.clientSecret; // For frontend (Stripe)
+    this.paymentUrl = data.paymentUrl; // For redirect (SSLCommerz)
+    this.instructions = data.instructions; // For manual
+    this.raw = data.raw; // Raw provider response
+  }
+}
+
+/**
+ * Payment Result - standardized response from verifyPayment
+ */
+export class PaymentResult {
+  constructor(data) {
+    this.id = data.id;
+    this.provider = data.provider;
+    this.status = data.status; // 'succeeded', 'failed', 'processing'
+    this.amount = data.amount;
+    this.currency = data.currency || 'BDT';
+    this.paidAt = data.paidAt;
+    this.metadata = data.metadata || {};
+    this.raw = data.raw;
+  }
+}
+
+/**
+ * Refund Result - standardized response from refund
+ */
+export class RefundResult {
+  constructor(data) {
+    this.id = data.id;
+    this.provider = data.provider;
+    this.status = data.status; // 'succeeded', 'failed', 'processing'
+    this.amount = data.amount;
+    this.currency = data.currency || 'BDT';
+    this.refundedAt = data.refundedAt;
+    this.reason = data.reason;
+    this.metadata = data.metadata || {};
+    this.raw = data.raw;
+  }
+}
+
+/**
+ * Webhook Event - standardized webhook event
+ */
+export class WebhookEvent {
+  constructor(data) {
+    this.id = data.id;
+    this.provider = data.provider;
+    this.type = data.type; // 'payment.succeeded', 'payment.failed', 'refund.succeeded', etc.
+    this.data = data.data;
+    this.createdAt = data.createdAt;
+    this.raw = data.raw;
+  }
+}
+
+/**
+ * Base Payment Provider
+ * All payment providers must extend this class
+ */
+export class PaymentProvider {
+  constructor(config = {}) {
+    this.config = config;
+    this.name = 'base'; // Override in subclass
+  }
+
+  /**
+   * Create a payment intent
+   * @param {Object} params - Payment parameters
+   * @param {number} params.amount - Amount in smallest currency unit
+   * @param {string} params.currency - Currency code
+   * @param {Object} params.metadata - Additional metadata
+   * @returns {Promise<PaymentIntent>}
+   */
+  async createIntent(params) {
+    throw new Error(`${this.constructor.name}: createIntent() must be implemented`);
+  }
+
+  /**
+   * Verify a payment
+   * @param {string} intentId - Payment intent ID
+   * @returns {Promise<PaymentResult>}
+   */
+  async verifyPayment(intentId) {
+    throw new Error(`${this.constructor.name}: verifyPayment() must be implemented`);
+  }
+
+  /**
+   * Get payment status
+   * @param {string} intentId - Payment intent ID
+   * @returns {Promise<PaymentResult>}
+   */
+  async getStatus(intentId) {
+    throw new Error(`${this.constructor.name}: getStatus() must be implemented`);
+  }
+
+  /**
+   * Refund a payment
+   * @param {string} paymentId - Payment ID
+   * @param {number} amount - Amount to refund (optional, full refund if not provided)
+   * @param {Object} options - Refund options
+   * @returns {Promise<RefundResult>}
+   */
+  async refund(paymentId, amount, options = {}) {
+    throw new Error(`${this.constructor.name}: refund() must be implemented`);
+  }
+
+  /**
+   * Handle webhook from provider
+   * @param {Object} payload - Webhook payload
+   * @param {Object} headers - Request headers (for signature verification)
+   * @returns {Promise<WebhookEvent>}
+   */
+  async handleWebhook(payload, headers = {}) {
+    throw new Error(`${this.constructor.name}: handleWebhook() must be implemented`);
+  }
+
+  /**
+   * Verify webhook signature (optional)
+   * @param {Object} payload - Webhook payload
+   * @param {string} signature - Webhook signature
+   * @returns {boolean}
+   */
+  verifyWebhookSignature(payload, signature) {
+    // Override in subclass if provider supports webhook signatures
+    return true;
+  }
+
+  /**
+   * Get provider capabilities
+   * @returns {Object}
+   */
+  getCapabilities() {
+    return {
+      supportsWebhooks: false,
+      supportsRefunds: false,
+      supportsPartialRefunds: false,
+      requiresManualVerification: true,
+    };
+  }
+}
+
+export default PaymentProvider;

package/providers/manual.js

@@ -0,0 +1,171 @@
+/**
+ * Manual Payment Provider
+ * @classytic/revenue
+ *
+ * Built-in provider for manual payment verification
+ * Perfect for: Cash, bank transfers, mobile money without API
+ */
+
+import { PaymentProvider, PaymentIntent, PaymentResult, RefundResult } from './base.js';
+import { nanoid } from 'nanoid';
+
+export class ManualProvider extends PaymentProvider {
+  constructor(config = {}) {
+    super(config);
+    this.name = 'manual';
+  }
+
+  /**
+   * Create manual payment intent
+   * Returns instructions for manual payment
+   */
+  async createIntent(params) {
+    const intentId = `manual_${nanoid(16)}`;
+
+    return new PaymentIntent({
+      id: intentId,
+      provider: 'manual',
+      status: 'pending',
+      amount: params.amount,
+      currency: params.currency || 'BDT',
+      metadata: params.metadata || {},
+      instructions: this._getPaymentInstructions(params),
+      raw: params,
+    });
+  }
+
+  /**
+   * Verify manual payment
+   * Note: This is called by admin after checking payment proof
+   */
+  async verifyPayment(intentId) {
+    // Manual verification doesn't auto-verify
+    // Admin must explicitly call payment verification endpoint
+    return new PaymentResult({
+      id: intentId,
+      provider: 'manual',
+      status: 'requires_manual_approval',
+      amount: 0, // Amount will be filled by transaction
+      currency: 'BDT',
+      metadata: {
+        message: 'Manual payment requires admin verification',
+      },
+    });
+  }
+
+  /**
+   * Get payment status
+   */
+  async getStatus(intentId) {
+    return this.verifyPayment(intentId);
+  }
+
+  /**
+   * Refund manual payment
+   */
+  async refund(paymentId, amount, options = {}) {
+    const refundId = `refund_${nanoid(16)}`;
+
+    return new RefundResult({
+      id: refundId,
+      provider: 'manual',
+      status: 'succeeded', // Manual refunds are immediately marked as succeeded
+      amount: amount,
+      currency: options.currency || 'BDT',
+      refundedAt: new Date(),
+      reason: options.reason || 'Manual refund',
+      metadata: options.metadata || {},
+    });
+  }
+
+  /**
+   * Manual provider doesn't support webhooks
+   */
+  async handleWebhook(payload, headers) {
+    throw new Error('Manual provider does not support webhooks');
+  }
+
+  /**
+   * Get provider capabilities
+   */
+  getCapabilities() {
+    return {
+      supportsWebhooks: false,
+      supportsRefunds: true,
+      supportsPartialRefunds: true,
+      requiresManualVerification: true,
+      supportedMethods: ['cash', 'bank', 'bkash', 'nagad', 'rocket', 'manual'],
+    };
+  }
+
+  /**
+   * Generate payment instructions for customer
+   * @private
+   */
+  _getPaymentInstructions(params) {
+    const { organizationPaymentInfo, method } = params.metadata || {};
+
+    if (!organizationPaymentInfo) {
+      return 'Please contact the organization for payment details.';
+    }
+
+    const instructions = [];
+
+    // Add method-specific instructions
+    switch (method) {
+      case 'bkash':
+      case 'nagad':
+      case 'rocket':
+        if (organizationPaymentInfo[`${method}Number`]) {
+          instructions.push(
+            `Send money via ${method.toUpperCase()}:`,
+            `Number: ${organizationPaymentInfo[`${method}Number`]}`,
+            `Amount: ${params.amount} ${params.currency || 'BDT'}`,
+            ``,
+            `After payment, provide the transaction ID/reference number.`
+          );
+        }
+        break;
+
+      case 'bank':
+        if (organizationPaymentInfo.bankAccount) {
+          const bank = organizationPaymentInfo.bankAccount;
+          instructions.push(
+            `Bank Transfer Details:`,
+            `Bank: ${bank.bankName || 'N/A'}`,
+            `Account: ${bank.accountNumber || 'N/A'}`,
+            `Account Name: ${bank.accountName || 'N/A'}`,
+            `Amount: ${params.amount} ${params.currency || 'BDT'}`,
+            ``,
+            `After payment, upload proof and provide reference.`
+          );
+        }
+        break;
+
+      case 'cash':
+        instructions.push(
+          `Cash Payment:`,
+          `Amount: ${params.amount} ${params.currency || 'BDT'}`,
+          ``,
+          `Pay at the organization's office and get a receipt.`
+        );
+        break;
+
+      default:
+        instructions.push(
+          `Payment Amount: ${params.amount} ${params.currency || 'BDT'}`,
+          ``,
+          `Contact the organization for payment details.`
+        );
+    }
+
+    // Add custom instructions if provided
+    if (organizationPaymentInfo.paymentInstructions) {
+      instructions.push(``, `Additional Instructions:`, organizationPaymentInfo.paymentInstructions);
+    }
+
+    return instructions.join('\n');
+  }
+}
+
+export default ManualProvider;

package/revenue.d.ts

@@ -0,0 +1,290 @@
+/**
+ * TypeScript definitions for @classytic/revenue
+ * Enterprise Revenue Management System
+ *
+ * Thin, focused, production-ready library with smart defaults.
+ *
+ * @version 1.0.0
+ */
+
+import { Schema, Model, Document } from 'mongoose';
+
+// ============ CORE API ============
+
+// Container
+export class Container {
+  register(name: string, implementation: any, options?: { singleton?: boolean; factory?: boolean }): this;
+  singleton(name: string, implementation: any): this;
+  transient(name: string, factory: Function): this;
+  get(name: string): any;
+  has(name: string): boolean;
+  keys(): string[];
+  clear(): void;
+  createScope(): Container;
+}
+
+// Provider System
+export interface PaymentIntentParams {
+  amount: number;
+  currency?: string;
+  metadata?: Record<string, any>;
+}
+
+export class PaymentIntent {
+  id: string;
+  provider: string;
+  status: string;
+  amount: number;
+  currency: string;
+  metadata: Record<string, any>;
+  clientSecret?: string;
+  paymentUrl?: string;
+  instructions?: string;
+  raw?: any;
+}
+
+export class PaymentResult {
+  id: string;
+  provider: string;
+  status: string;
+  amount: number;
+  currency: string;
+  paidAt?: Date;
+  metadata: Record<string, any>;
+  raw?: any;
+}
+
+export class RefundResult {
+  id: string;
+  provider: string;
+  status: string;
+  amount: number;
+  currency: string;
+  refundedAt?: Date;
+  reason?: string;
+  metadata: Record<string, any>;
+  raw?: any;
+}
+
+export class WebhookEvent {
+  id: string;
+  provider: string;
+  type: string;
+  data: any;
+  createdAt: Date;
+  raw?: any;
+}
+
+export abstract class PaymentProvider {
+  name: string;
+  config: any;
+
+  createIntent(params: PaymentIntentParams): Promise<PaymentIntent>;
+  verifyPayment(intentId: string): Promise<PaymentResult>;
+  getStatus(intentId: string): Promise<PaymentResult>;
+  refund(paymentId: string, amount?: number, options?: any): Promise<RefundResult>;
+  handleWebhook(payload: any, headers?: any): Promise<WebhookEvent>;
+  verifyWebhookSignature(payload: any, signature: string): boolean;
+  getCapabilities(): {
+    supportsWebhooks: boolean;
+    supportsRefunds: boolean;
+    supportsPartialRefunds: boolean;
+    requiresManualVerification: boolean;
+  };
+}
+
+// Note: ManualProvider moved to @classytic/revenue-manual (separate package)
+
+// Services
+export class SubscriptionService {
+  constructor(container: Container);
+
+  create(params: {
+    data: any;
+    planKey: string;
+    amount: number;
+    currency?: string;
+    gateway?: string;
+    paymentData?: any;
+    metadata?: Record<string, any>;
+    idempotencyKey?: string;
+  }): Promise<{ subscription: any; transaction: any; paymentIntent: PaymentIntent | null }>;
+
+  activate(subscriptionId: string, options?: { timestamp?: Date }): Promise<any>;
+  renew(subscriptionId: string, params?: any): Promise<{ subscription: any; transaction: any; paymentIntent: PaymentIntent }>;
+  cancel(subscriptionId: string, options?: { immediate?: boolean; reason?: string }): Promise<any>;
+  pause(subscriptionId: string, options?: { reason?: string }): Promise<any>;
+  resume(subscriptionId: string, options?: { extendPeriod?: boolean }): Promise<any>;
+  list(filters?: any, options?: any): Promise<any[]>;
+  get(subscriptionId: string): Promise<any>;
+}
+
+export class PaymentService {
+  constructor(container: Container);
+
+  verify(paymentIntentId: string, options?: { verifiedBy?: string }): Promise<{ transaction: any; paymentResult: PaymentResult; status: string }>;
+  getStatus(paymentIntentId: string): Promise<{ transaction: any; paymentResult: PaymentResult; status: string; provider: string }>;
+  refund(paymentId: string, amount?: number, options?: { reason?: string }): Promise<{ transaction: any; refundResult: RefundResult; status: string }>;
+  handleWebhook(providerName: string, payload: any, headers?: any): Promise<{ event: WebhookEvent; transaction: any; status: string }>;
+  list(filters?: any, options?: any): Promise<any[]>;
+  get(transactionId: string): Promise<any>;
+  getProvider(providerName: string): PaymentProvider;
+}
+
+export class TransactionService {
+  constructor(container: Container);
+
+  get(transactionId: string): Promise<any>;
+  list(filters?: any, options?: any): Promise<{ transactions: any[]; total: number; page: number; limit: number; pages: number }>;
+  update(transactionId: string, updates: any): Promise<any>;
+}
+
+// Error Classes
+export class RevenueError extends Error {
+  code: string;
+  retryable: boolean;
+  metadata: Record<string, any>;
+  toJSON(): { name: string; message: string; code: string; retryable: boolean; metadata: Record<string, any> };
+}
+
+export class ConfigurationError extends RevenueError {}
+export class ModelNotRegisteredError extends ConfigurationError {}
+export class ProviderError extends RevenueError {}
+export class ProviderNotFoundError extends ProviderError {}
+export class ProviderCapabilityError extends ProviderError {}
+export class PaymentIntentCreationError extends ProviderError {}
+export class PaymentVerificationError extends ProviderError {}
+export class NotFoundError extends RevenueError {}
+export class SubscriptionNotFoundError extends NotFoundError {}
+export class TransactionNotFoundError extends NotFoundError {}
+export class ValidationError extends RevenueError {}
+export class InvalidAmountError extends ValidationError {}
+export class MissingRequiredFieldError extends ValidationError {}
+export class StateError extends RevenueError {}
+export class AlreadyVerifiedError extends StateError {}
+export class InvalidStateTransitionError extends StateError {}
+export class SubscriptionNotActiveError extends StateError {}
+export class OperationError extends RevenueError {}
+export class RefundNotSupportedError extends OperationError {}
+export class RefundError extends OperationError {}
+
+export function isRetryable(error: Error): boolean;
+export function isRevenueError(error: Error): boolean;
+
+// Revenue Instance (Immutable)
+export interface Revenue {
+  readonly container: Container;
+  readonly providers: Readonly<Record<string, PaymentProvider>>;
+  readonly config: Readonly<any>;
+
+  readonly subscriptions: SubscriptionService;
+  readonly payments: PaymentService;
+  readonly transactions: TransactionService;
+
+  getProvider(name: string): PaymentProvider;
+}
+
+export interface RevenueOptions {
+  models: {
+    Transaction: Model<any>;
+    Subscription?: Model<any>;
+    [key: string]: Model<any> | undefined;
+  };
+  providers?: Record<string, PaymentProvider>;
+  hooks?: Record<string, Function[]>;
+  config?: {
+    targetModels?: string[];
+    categoryMappings?: Record<string, string>;
+    [key: string]: any;
+  };
+  logger?: Console | any;
+}
+
+export function createRevenue(options: RevenueOptions): Revenue;
+
+// ============ ENUMS ============
+
+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_TYPES: {
+  INCOME: 'income';
+  EXPENSE: 'expense';
+};
+
+// Note: PAYMENT_METHOD removed - users define their own payment methods
+
+export const PAYMENT_GATEWAY_TYPE: {
+  MANUAL: 'manual';
+  STRIPE: 'stripe';
+  SSLCOMMERZ: 'sslcommerz';
+  BKASH_GATEWAY: 'bkash_gateway';
+  NAGAD_GATEWAY: 'nagad_gateway';
+};
+
+export const SUBSCRIPTION_STATUS: {
+  ACTIVE: 'active';
+  PAUSED: 'paused';
+  CANCELLED: 'cancelled';
+  EXPIRED: 'expired';
+  PENDING: 'pending';
+  INACTIVE: 'inactive';
+};
+
+export const PLAN_KEYS: {
+  MONTHLY: 'monthly';
+  QUARTERLY: 'quarterly';
+  YEARLY: 'yearly';
+};
+
+export const MONETIZATION_TYPES: {
+  FREE: 'free';
+  PURCHASE: 'purchase';
+  SUBSCRIPTION: 'subscription';
+};
+
+// ============ SCHEMAS ============
+
+export const currentPaymentSchema: Schema;
+export const paymentSummarySchema: Schema;
+export const subscriptionInfoSchema: Schema;
+export const subscriptionPlanSchema: Schema;
+export const gatewaySchema: Schema;
+export const commissionSchema: Schema;
+export const paymentDetailsSchema: Schema;
+export const tenantSnapshotSchema: Schema;
+export const timelineEventSchema: Schema;
+export const customerInfoSchema: Schema;
+export const customDiscountSchema: Schema;
+export const stripeAccountSchema: Schema;
+export const sslcommerzAccountSchema: Schema;
+export const bkashMerchantSchema: Schema;
+export const bankAccountSchema: Schema;
+export const walletSchema: Schema;
+
+// ============ UTILITIES ============
+
+export const logger: Console | any;
+export function setLogger(logger: Console | any): void;
+
+// ============ DEFAULT EXPORT ============
+
+declare const _default: {
+  createRevenue: typeof createRevenue;
+  PaymentProvider: typeof PaymentProvider;
+  RevenueError: typeof RevenueError;
+  Container: typeof Container;
+};
+
+export default _default;

package/schemas/index.js

@@ -0,0 +1,21 @@
+/**
+ * Schema Index
+ * @classytic/revenue
+ *
+ * Core schemas for injection into your models
+ *
+ * Note: Enums are separate. Import them from '@classytic/revenue/enums'
+ */
+
+// Re-export core schemas only
+export * from './transaction/index.js';
+export * from './subscription/index.js';
+
+// Default export with core schemas
+import transactionSchemas from './transaction/index.js';
+import subscriptionSchemas from './subscription/index.js';
+
+export default {
+  ...transactionSchemas,
+  ...subscriptionSchemas,
+};