@classytic/revenue 1.0.2 → 1.1.2

package/dist/infrastructure/plugins/index.d.ts

@@ -0,0 +1,267 @@
+import { R as RevenuePlugin } from '../../plugin-Bb9HOE10.js';
+export { d as definePlugin } from '../../plugin-Bb9HOE10.js';
+import { T as TaxConfig } from '../../tax-CV8A0sxl.js';
+import '../../core/events.js';
+import '../../index-cLJBLUvx.js';
+import 'mongoose';
+import '@classytic/shared-types';
+import '../../providers/index.js';
+import '../../settlement.schema-CpamV7ZY.js';
+import '../../split.enums-DG3TxQf9.js';
+
+/**
+ * Logging Plugin
+ * @classytic/revenue
+ *
+ * Logs all revenue operations at specified log level
+ */
+
+/**
+ * Logging plugin options
+ */
+interface LoggingPluginOptions {
+    /** Log level: 'debug' or 'info' */
+    level?: 'debug' | 'info';
+}
+/**
+ * Logging plugin - logs all operations
+ *
+ * Logs payment creation, verification, and refund operations
+ *
+ * @param options - Plugin options
+ * @returns Logging plugin
+ *
+ * @example
+ * ```typescript
+ * import { Revenue } from '@classytic/revenue';
+ * import { loggingPlugin } from '@classytic/revenue/plugins';
+ *
+ * const revenue = Revenue
+ *   .create()
+ *   .withPlugin(loggingPlugin({ level: 'debug' }))
+ *   .build();
+ * ```
+ */
+declare function loggingPlugin(options?: LoggingPluginOptions): RevenuePlugin;
+
+/**
+ * Audit Plugin
+ * @classytic/revenue
+ *
+ * Records all operations for compliance and audit trails
+ */
+
+/**
+ * Audit entry record
+ */
+interface AuditEntry {
+    action: string;
+    requestId: string;
+    timestamp: Date;
+    input: Record<string, unknown>;
+    output: Record<string, unknown>;
+    idempotencyKey?: string;
+}
+/**
+ * Audit plugin options
+ */
+interface AuditPluginOptions {
+    /** Custom storage function for audit entries */
+    store?: (entry: AuditEntry) => Promise<void>;
+}
+/**
+ * Audit plugin - records all operations for compliance
+ *
+ * Records payment creation, refunds, and other operations with sanitized data
+ *
+ * @param options - Plugin options
+ * @returns Audit plugin
+ *
+ * @example
+ * ```typescript
+ * import { Revenue } from '@classytic/revenue';
+ * import { auditPlugin } from '@classytic/revenue/plugins';
+ *
+ * const revenue = Revenue
+ *   .create()
+ *   .withPlugin(auditPlugin({
+ *     store: async (entry) => {
+ *       await AuditLog.create(entry);
+ *     }
+ *   }))
+ *   .build();
+ * ```
+ */
+declare function auditPlugin(options?: AuditPluginOptions): RevenuePlugin;
+
+/**
+ * Metrics Plugin
+ * @classytic/revenue
+ *
+ * Collects operation metrics (duration, success/failure)
+ */
+
+/**
+ * Metric record
+ */
+interface Metric {
+    name: string;
+    duration: number;
+    success: boolean;
+    error?: string;
+    [key: string]: unknown;
+}
+/**
+ * Metrics plugin options
+ */
+interface MetricsPluginOptions {
+    /** Callback for each metric */
+    onMetric?: (metric: Metric) => void;
+}
+/**
+ * Metrics plugin - collects operation metrics
+ *
+ * Tracks duration and success/failure of operations
+ *
+ * @param options - Plugin options
+ * @returns Metrics plugin
+ *
+ * @example
+ * ```typescript
+ * import { Revenue } from '@classytic/revenue';
+ * import { metricsPlugin } from '@classytic/revenue/plugins';
+ *
+ * const revenue = Revenue
+ *   .create()
+ *   .withPlugin(metricsPlugin({
+ *     onMetric: (metric) => {
+ *       // Send to Datadog, Prometheus, etc.
+ *       statsd.timing(metric.name, metric.duration);
+ *       if (!metric.success) {
+ *         statsd.increment(`${metric.name}.error`);
+ *       }
+ *     }
+ *   }))
+ *   .build();
+ * ```
+ */
+declare function metricsPlugin(options?: MetricsPluginOptions): RevenuePlugin;
+
+/**
+ * Tax Plugin Options
+ */
+interface TaxPluginOptions {
+    /**
+     * Function to get tax configuration for an organization
+     * Apps implement this to return jurisdiction-specific config
+     *
+     * @param orgId - Organization ID
+     * @returns Tax configuration or null if not registered
+     *
+     * @example
+     * ```typescript
+     * getTaxConfig: async (orgId) => {
+     *   const org = await Organization.findById(orgId);
+     *   if (!org) return null;
+     *
+     *   return {
+     *     isRegistered: org.country === 'AU',
+     *     defaultRate: org.country === 'AU' ? 0.10 : 0, // 10% GST in Australia
+     *     pricesIncludeTax: org.pricesIncludeTax || false,
+     *     exemptCategories: ['education', 'medical'],
+     *   };
+     * }
+     * ```
+     */
+    getTaxConfig: (orgId: string) => Promise<TaxConfig | null>;
+    /**
+     * Category mappings for resolving transaction categories
+     * Maps entity names to category strings
+     *
+     * @example
+     * ```typescript
+     * {
+     *   Order: 'order_subscription',
+     *   PlatformSubscription: 'platform_subscription',
+     *   Membership: 'gym_membership',
+     * }
+     * ```
+     */
+    categoryMappings?: Record<string, string>;
+    /**
+     * Categories that represent income (vs expense)
+     * Used to determine tax type: 'collected' vs 'paid'
+     *
+     * Default: ['subscription', 'purchase', 'course_enrollment']
+     */
+    incomeCategories?: string[];
+}
+/**
+ * Create Tax Plugin
+ *
+ * Automatically calculates and applies tax to transactions during monetization.create()
+ *
+ * @param options - Plugin options
+ * @returns Tax plugin
+ *
+ * @example
+ * ```typescript
+ * import { Revenue } from '@classytic/revenue';
+ * import { createTaxPlugin } from '@classytic/revenue/plugins';
+ *
+ * const revenue = Revenue
+ *   .create({ defaultCurrency: 'USD' })
+ *   .withModels({ Transaction, Subscription })
+ *   .withProvider('stripe', stripeProvider)
+ *   .withPlugin(createTaxPlugin({
+ *     getTaxConfig: async (orgId) => {
+ *       const org = await Organization.findById(orgId);
+ *       return {
+ *         isRegistered: true,
+ *         defaultRate: 0.15, // 15% tax
+ *         pricesIncludeTax: false,
+ *         exemptCategories: ['education'],
+ *       };
+ *     },
+ *     categoryMappings: {
+ *       Order: 'order_subscription',
+ *       Membership: 'gym_membership',
+ *     },
+ *   }))
+ *   .build();
+ *
+ * // Tax is now automatically calculated
+ * await revenue.monetization.create({
+ *   data: { organizationId: 'org_123', customerId: 'cust_456' },
+ *   planKey: 'monthly',
+ *   amount: 10000, // $100
+ *   entity: 'Order',
+ *   monetizationType: 'subscription',
+ * });
+ * // → Creates transaction with tax: {
+ * //   isApplicable: true,
+ * //   rate: 0.15,
+ * //   baseAmount: 10000,
+ * //   taxAmount: 1500,
+ * //   totalAmount: 11500,
+ * //   type: 'collected'
+ * // }
+ * ```
+ */
+declare function createTaxPlugin(options: TaxPluginOptions): RevenuePlugin;
+
+/**
+ * Built-in Plugins
+ * @classytic/revenue/plugins
+ *
+ * Collection of built-in plugins for common use cases
+ */
+
+declare const _default: {
+    loggingPlugin: typeof loggingPlugin;
+    auditPlugin: typeof auditPlugin;
+    metricsPlugin: typeof metricsPlugin;
+    createTaxPlugin: typeof createTaxPlugin;
+};
+
+export { type AuditEntry, type AuditPluginOptions, type LoggingPluginOptions, type Metric, type MetricsPluginOptions, type TaxPluginOptions, auditPlugin, createTaxPlugin, _default as default, loggingPlugin, metricsPlugin };

package/dist/infrastructure/plugins/index.js

@@ -0,0 +1,292 @@
+// @classytic/revenue - Enterprise Revenue Management System
+
+// src/core/plugin.ts
+function definePlugin(plugin) {
+  return plugin;
+}
+
+// src/infrastructure/plugins/business/logging.plugin.ts
+function loggingPlugin(options = {}) {
+  const level = options.level ?? "info";
+  return definePlugin({
+    name: "logging",
+    version: "1.0.0",
+    description: "Logs all revenue operations",
+    hooks: {
+      "payment.create.after": async (ctx, input, next) => {
+        ctx.logger[level]("Creating payment", { amount: input.amount, currency: input.currency });
+        const result = await next();
+        ctx.logger[level]("Payment created", { paymentIntentId: result?.paymentIntentId });
+        return result;
+      },
+      "payment.verify.after": async (ctx, input, next) => {
+        ctx.logger[level]("Verifying payment", { id: input.id });
+        const result = await next();
+        ctx.logger[level]("Payment verified", { verified: result?.verified });
+        return result;
+      },
+      "payment.refund.after": async (ctx, input, next) => {
+        ctx.logger[level]("Processing refund", { transactionId: input.transactionId, amount: input.amount });
+        const result = await next();
+        ctx.logger[level]("Refund processed", { refundId: result?.refundId });
+        return result;
+      }
+    }
+  });
+}
+
+// src/infrastructure/plugins/business/audit.plugin.ts
+function sanitizeInput(input) {
+  if (typeof input !== "object" || !input) return {};
+  const sanitized = { ...input };
+  delete sanitized.apiKey;
+  delete sanitized.secretKey;
+  delete sanitized.password;
+  return sanitized;
+}
+function sanitizeOutput(output) {
+  if (typeof output !== "object" || !output) return {};
+  return { ...output };
+}
+function auditPlugin(options = {}) {
+  const store = options.store ?? (async (entry) => {
+  });
+  return definePlugin({
+    name: "audit",
+    version: "1.0.0",
+    description: "Audit trail for all operations",
+    hooks: {
+      "payment.create.after": async (ctx, input, next) => {
+        const result = await next();
+        await store({
+          action: "payment.create",
+          requestId: ctx.meta.requestId,
+          timestamp: ctx.meta.timestamp,
+          input: sanitizeInput(input),
+          output: sanitizeOutput(result),
+          idempotencyKey: ctx.meta.idempotencyKey
+        });
+        return result;
+      },
+      "payment.refund.after": async (ctx, input, next) => {
+        const result = await next();
+        await store({
+          action: "payment.refund",
+          requestId: ctx.meta.requestId,
+          timestamp: ctx.meta.timestamp,
+          input: sanitizeInput(input),
+          output: sanitizeOutput(result),
+          idempotencyKey: ctx.meta.idempotencyKey
+        });
+        return result;
+      }
+    }
+  });
+}
+
+// src/infrastructure/plugins/business/metrics.plugin.ts
+function metricsPlugin(options = {}) {
+  const record = options.onMetric ?? ((metric) => {
+  });
+  return definePlugin({
+    name: "metrics",
+    version: "1.0.0",
+    description: "Collects operation metrics",
+    hooks: {
+      "payment.create.before": async (_ctx, input, next) => {
+        const start = Date.now();
+        try {
+          const result = await next();
+          record({
+            name: "payment.create",
+            duration: Date.now() - start,
+            success: true,
+            amount: input.amount,
+            currency: input.currency
+          });
+          return result;
+        } catch (error) {
+          record({
+            name: "payment.create",
+            duration: Date.now() - start,
+            success: false,
+            error: error.message
+          });
+          throw error;
+        }
+      }
+    }
+  });
+}
+
+// src/shared/utils/calculators/tax.ts
+function calculateTax(amount, category, config) {
+  if (!config?.isRegistered || config.exemptCategories?.includes(category)) {
+    return {
+      isApplicable: false,
+      rate: 0,
+      baseAmount: amount,
+      taxAmount: 0,
+      totalAmount: amount,
+      pricesIncludeTax: false
+    };
+  }
+  const rate = config.defaultRate;
+  const [baseAmount, taxAmount, totalAmount] = config.pricesIncludeTax ? [
+    // Tax-inclusive: extract tax from total
+    Math.round(amount / (1 + rate)),
+    // baseAmount
+    Math.round(amount - amount / (1 + rate)),
+    // taxAmount
+    amount
+    // totalAmount (already integer)
+  ] : [
+    // Tax-exclusive: add tax to base
+    amount,
+    // baseAmount (already integer)
+    Math.round(amount * rate),
+    // taxAmount
+    Math.round(amount * (1 + rate))
+    // totalAmount
+  ];
+  return {
+    isApplicable: true,
+    rate,
+    baseAmount,
+    taxAmount,
+    totalAmount,
+    pricesIncludeTax: config.pricesIncludeTax
+  };
+}
+function getTaxType(transactionFlow, category, exemptCategories = []) {
+  if (exemptCategories.includes(category)) {
+    return "exempt";
+  }
+  return transactionFlow === "inflow" ? "collected" : "paid";
+}
+
+// src/enums/transaction.enums.ts
+var TRANSACTION_FLOW = {
+  INFLOW: "inflow",
+  OUTFLOW: "outflow"
+};
+var TRANSACTION_FLOW_VALUES = Object.values(
+  TRANSACTION_FLOW
+);
+var 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"
+};
+var TRANSACTION_STATUS_VALUES = Object.values(
+  TRANSACTION_STATUS
+);
+var LIBRARY_CATEGORIES = {
+  SUBSCRIPTION: "subscription",
+  PURCHASE: "purchase"
+};
+var LIBRARY_CATEGORY_VALUES = Object.values(
+  LIBRARY_CATEGORIES
+);
+new Set(TRANSACTION_FLOW_VALUES);
+new Set(
+  TRANSACTION_STATUS_VALUES
+);
+new Set(LIBRARY_CATEGORY_VALUES);
+
+// src/shared/utils/validators/category-resolver.ts
+function resolveCategory(entity, monetizationType, categoryMappings = {}) {
+  if (entity && categoryMappings[entity]) {
+    return categoryMappings[entity];
+  }
+  switch (monetizationType) {
+    case "subscription":
+      return LIBRARY_CATEGORIES.SUBSCRIPTION;
+    // 'subscription'
+    case "purchase":
+      return LIBRARY_CATEGORIES.PURCHASE;
+    // 'purchase'
+    default:
+      return LIBRARY_CATEGORIES.SUBSCRIPTION;
+  }
+}
+
+// src/infrastructure/plugins/business/tax.plugin.ts
+function createTaxPlugin(options) {
+  const {
+    getTaxConfig,
+    categoryMappings = {},
+    incomeCategories = ["subscription", "purchase", "course_enrollment", "product_order"]
+  } = options;
+  return definePlugin({
+    name: "tax",
+    version: "1.0.0",
+    description: "Automatic tax calculation for transactions",
+    hooks: {
+      /**
+       * Calculate tax before monetization creation
+       * Injects tax data into the input so it's saved with the transaction
+       */
+      "monetization.create.before": async (ctx, input, next) => {
+        const orgId = input.data.organizationId;
+        if (!orgId) {
+          ctx.logger.debug("Tax plugin: No organizationId in input.data, skipping tax calculation");
+          return next();
+        }
+        try {
+          const config = await getTaxConfig(orgId);
+          if (!config) {
+            ctx.logger.debug("Tax plugin: No tax config for org", { orgId });
+            return next();
+          }
+          const category = resolveCategory(
+            input.entity,
+            input.monetizationType || "subscription",
+            categoryMappings
+          );
+          const transactionFlow = incomeCategories.includes(category) ? "inflow" : "outflow";
+          const taxCalc = calculateTax(input.amount, category, config);
+          const taxType = getTaxType(transactionFlow, category, config.exemptCategories);
+          input.tax = {
+            ...taxCalc,
+            type: taxType
+          };
+          ctx.logger.debug("Tax plugin: Tax calculated", {
+            orgId,
+            category,
+            entity: input.entity,
+            monetizationType: input.monetizationType,
+            taxAmount: taxCalc.taxAmount,
+            type: taxType
+          });
+        } catch (error) {
+          ctx.logger.error("Tax plugin: Failed to calculate tax", {
+            orgId,
+            error: error.message
+          });
+        }
+        return next();
+      }
+    }
+  });
+}
+
+// src/infrastructure/plugins/index.ts
+var plugins_default = {
+  loggingPlugin,
+  auditPlugin,
+  metricsPlugin,
+  createTaxPlugin
+};
+
+export { auditPlugin, createTaxPlugin, plugins_default as default, definePlugin, loggingPlugin, metricsPlugin };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map