@classytic/revenue 1.0.2 → 1.0.6

package/README.md

@@ -126,7 +126,14 @@ revenue.on('*', (event) => {
 ### Validation (Zod v4)
 
 ```typescript
-import { CreatePaymentSchema, validate, safeValidate } from '@classytic/revenue';
+import {
+  CreatePaymentSchema,
+  PaymentEntrySchema,
+  CurrentPaymentInputSchema,
+  validate,
+  safeValidate,
+  validateSplitPayments,
+} from '@classytic/revenue';
 
 // Validate input (throws on error)
 const payment = validate(CreatePaymentSchema, userInput);
@@ -136,6 +143,16 @@ const result = safeValidate(CreatePaymentSchema, userInput);
 if (!result.success) {
   console.log(result.error.issues);
 }
+
+// Split payment validation
+const splitResult = safeValidate(CurrentPaymentInputSchema, {
+  amount: 50000,
+  method: 'split',
+  payments: [
+    { method: 'cash', amount: 25000 },
+    { method: 'bkash', amount: 25000 },
+  ],
+});
 ```
 
 ---
@@ -403,6 +420,7 @@ export const Transaction = mongoose.model('Transaction', transactionSchema);
 | `holdSchema` | Escrow hold/release | `hold: holdSchema` |
 | `splitSchema` | Multi-party splits | `splits: [splitSchema]` |
 | `currentPaymentSchema` | For Order/Subscription models | `currentPayment: currentPaymentSchema` |
+| `paymentEntrySchema` | Individual payment in split payments | Used within `currentPaymentSchema.payments` |
 
 **Usage:** Import and use as nested objects (NOT spread):
 
@@ -517,6 +535,102 @@ const pending = await Transaction.find({
 
 ---
 
+## Multi-Payment Method Support (POS)
+
+For POS scenarios where customers pay using multiple methods (e.g., cash + bank + mobile wallet):
+
+### Schema Structure
+
+```typescript
+import { currentPaymentSchema, paymentEntrySchema } from '@classytic/revenue';
+
+// currentPaymentSchema now supports a `payments` array for split payments
+const orderSchema = new mongoose.Schema({
+  currentPayment: currentPaymentSchema,
+  // ...
+});
+```
+
+### Single Payment (Backward Compatible)
+
+```typescript
+// Traditional single-method payment
+currentPayment: {
+  amount: 50000,  // 500 BDT in paisa
+  method: 'cash',
+  status: 'verified',
+  verifiedAt: new Date(),
+  verifiedBy: cashierId,
+}
+```
+
+### Split Payment (Multiple Methods)
+
+```typescript
+// Customer pays 500 BDT using: 100 cash + 100 bank + 300 bKash
+currentPayment: {
+  amount: 50000,  // Total: 500 BDT
+  method: 'split',
+  status: 'verified',
+  payments: [
+    { method: 'cash', amount: 10000 },                                    // 100 BDT
+    { method: 'bank_transfer', amount: 10000, reference: 'TRF123' },      // 100 BDT
+    { method: 'bkash', amount: 30000, reference: 'TRX456', details: { walletNumber: '01712345678' } }, // 300 BDT
+  ],
+  verifiedAt: new Date(),
+  verifiedBy: cashierId,
+}
+```
+
+### Validation
+
+```typescript
+import {
+  CurrentPaymentInputSchema,
+  PaymentEntrySchema,
+  validateSplitPayments,
+  safeValidate,
+} from '@classytic/revenue';
+
+// Zod validation (automatically validates totals match)
+const result = safeValidate(CurrentPaymentInputSchema, paymentInput);
+if (!result.success) {
+  console.log(result.error.issues); // "Split payments total must equal the transaction amount"
+}
+
+// Helper function for runtime validation
+const isValid = validateSplitPayments({
+  amount: 50000,
+  payments: [
+    { amount: 10000 },
+    { amount: 10000 },
+    { amount: 30000 },
+  ],
+}); // true - totals match
+```
+
+### TypeScript Types
+
+```typescript
+import type { PaymentEntry, CurrentPayment } from '@classytic/revenue';
+
+const entry: PaymentEntry = {
+  method: 'bkash',
+  amount: 30000,
+  reference: 'TRX456',
+  details: { walletNumber: '01712345678' },
+};
+
+const payment: CurrentPayment = {
+  amount: 50000,
+  method: 'split',
+  status: 'verified',
+  payments: [entry],
+};
+```
+
+---
+
 ## Building Custom Providers
 
 ```typescript
@@ -659,15 +773,70 @@ import type {
   ProviderCapabilities,
   RevenueEvents,
   MonetizationCreateParams,
+  // Multi-payment types
+  PaymentEntry,
+  CurrentPayment,
+  PaymentEntryInput,
+  CurrentPaymentInput,
 } from '@classytic/revenue';
 ```
 
+### Type Guards
+
+Runtime type checking for all enum values:
+
+```typescript
+import {
+  isTransactionType,
+  isTransactionStatus,
+  isPaymentStatus,
+  isSubscriptionStatus,
+  isMonetizationType,
+  isHoldStatus,
+  isSplitType,
+} from '@classytic/revenue';
+
+// Validate and narrow types at runtime
+if (isTransactionStatus(userInput)) {
+  // userInput is narrowed to TransactionStatusValue
+  console.log('Valid status:', userInput);
+}
+
+// Useful for API input validation
+function processPayment(status: unknown) {
+  if (!isPaymentStatus(status)) {
+    throw new Error('Invalid payment status');
+  }
+  // status is now typed as PaymentStatusValue
+}
+```
+
+**Available type guards:**
+
+| Guard | Validates |
+|-------|-----------|
+| `isTransactionType` | `'income'` \| `'expense'` |
+| `isTransactionStatus` | `'pending'` \| `'verified'` \| `'completed'` \| ... |
+| `isLibraryCategory` | `'subscription'` \| `'purchase'` |
+| `isPaymentStatus` | `'pending'` \| `'succeeded'` \| `'failed'` \| ... |
+| `isPaymentGatewayType` | `'manual'` \| `'automatic'` |
+| `isGatewayType` | `'redirect'` \| `'direct'` \| `'webhook'` |
+| `isSubscriptionStatus` | `'active'` \| `'paused'` \| `'cancelled'` \| ... |
+| `isPlanKey` | `'monthly'` \| `'yearly'` \| `'one_time'` \| ... |
+| `isMonetizationType` | `'subscription'` \| `'purchase'` |
+| `isHoldStatus` | `'held'` \| `'released'` \| `'partially_released'` \| ... |
+| `isReleaseReason` | `'completed'` \| `'cancelled'` \| `'refunded'` \| ... |
+| `isHoldReason` | `'escrow'` \| `'dispute'` \| `'verification'` \| ... |
+| `isSplitType` | `'platform_commission'` \| `'affiliate_commission'` \| ... |
+| `isSplitStatus` | `'pending'` \| `'processed'` \| `'failed'` |
+| `isPayoutMethod` | `'bank_transfer'` \| `'wallet'` \| `'manual'` |
+
 ---
 
 ## Testing
 
 ```bash
-# Run all tests (84 tests)
+# Run all tests (196 tests)
 npm test
 
 # Run integration tests (requires MongoDB)

package/dist/{actions-CwG-b7fR.d.ts → actions-Ctf2XUL-.d.ts}

@@ -1,5 +1,5 @@
 import { R as Result } from './retry-80lBCmSe.js';
-import { d as TransactionDocument, ac as TransactionTypeOptions, ad as FieldUpdateValidationResult, L as Logger, C as CommissionInfo, o as SplitRule, p as SplitInfo, ab as CommissionWithSplitsOptions, h as MonetizationTypeValue, a6 as PeriodRangeParams, a7 as PeriodRangeResult, a8 as ProratedAmountParams, a9 as DurationResult, e as SubscriptionDocument, aa as SubscriptionEntity } from './index-ChVD3P9k.js';
+import { d as TransactionDocument, ae as TransactionTypeOptions, af as FieldUpdateValidationResult, L as Logger, C as CommissionInfo, q as SplitRule, r as SplitInfo, ad as CommissionWithSplitsOptions, j as MonetizationTypeValue, a8 as PeriodRangeParams, a9 as PeriodRangeResult, aa as ProratedAmountParams, ab as DurationResult, e as SubscriptionDocument, ac as SubscriptionEntity } from './index-C5SsOrV0.js';
 
 /**
  * Money Utility - Integer-safe currency handling

package/dist/core/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MonetizationService, P as PaymentService, T as TransactionService, E as EscrowService, C as Container } from '../index-BnJWVXuw.js';
-import { d as TransactionDocument, e as SubscriptionDocument, a as MongooseModel, z as HooksRegistry, w as PaymentProviderInterface } from '../index-ChVD3P9k.js';
+import { M as MonetizationService, P as PaymentService, T as TransactionService, E as EscrowService, C as Container } from '../index-BnEXsnLJ.js';
+import { d as TransactionDocument, e as SubscriptionDocument, a as MongooseModel, B as HooksRegistry, y as PaymentProviderInterface } from '../index-C5SsOrV0.js';
 import { PaymentResult, RefundResult, PaymentProvider } from '../providers/index.js';
 import { x as RetryConfig, R as Result } from '../retry-80lBCmSe.js';
 export { E as Err, O as Ok, g as all, e as err, f as flatMap, a as isErr, i as isOk, m as map, c as mapErr, h as match, o as ok, t as tryCatch, d as tryCatchSync, u as unwrap, b as unwrapOr } from '../retry-80lBCmSe.js';

package/dist/core/index.js

@@ -1086,14 +1086,37 @@ var TRANSACTION_TYPE = {
   INCOME: "income",
   EXPENSE: "expense"
 };
+var TRANSACTION_TYPE_VALUES = Object.values(
+  TRANSACTION_TYPE
+);
 var TRANSACTION_STATUS = {
+  PENDING: "pending",
+  PAYMENT_INITIATED: "payment_initiated",
+  PROCESSING: "processing",
+  REQUIRES_ACTION: "requires_action",
   VERIFIED: "verified",
   COMPLETED: "completed",
-  CANCELLED: "cancelled"};
+  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_TYPE_VALUES);
+new Set(
+  TRANSACTION_STATUS_VALUES
+);
+new Set(LIBRARY_CATEGORY_VALUES);
 
 // src/utils/category-resolver.ts
 function resolveCategory(entity, monetizationType, categoryMappings = {}) {
@@ -1163,6 +1186,10 @@ var MONETIZATION_TYPES = {
   PURCHASE: "purchase",
   SUBSCRIPTION: "subscription"
 };
+var MONETIZATION_TYPE_VALUES = Object.values(
+  MONETIZATION_TYPES
+);
+new Set(MONETIZATION_TYPE_VALUES);
 
 // src/services/monetization.service.ts
 var MonetizationService = class {
@@ -2162,23 +2189,66 @@ var TransactionService = class {
 
 // src/enums/escrow.enums.ts
 var HOLD_STATUS = {
+  PENDING: "pending",
   HELD: "held",
   RELEASED: "released",
   CANCELLED: "cancelled",
+  EXPIRED: "expired",
   PARTIALLY_RELEASED: "partially_released"
 };
+var HOLD_STATUS_VALUES = Object.values(HOLD_STATUS);
 var RELEASE_REASON = {
-  PAYMENT_VERIFIED: "payment_verified"};
+  PAYMENT_VERIFIED: "payment_verified",
+  MANUAL_RELEASE: "manual_release",
+  AUTO_RELEASE: "auto_release",
+  DISPUTE_RESOLVED: "dispute_resolved"
+};
+var RELEASE_REASON_VALUES = Object.values(
+  RELEASE_REASON
+);
 var HOLD_REASON = {
-  PAYMENT_VERIFICATION: "payment_verification"};
+  PAYMENT_VERIFICATION: "payment_verification",
+  FRAUD_CHECK: "fraud_check",
+  MANUAL_REVIEW: "manual_review",
+  DISPUTE: "dispute",
+  COMPLIANCE: "compliance"
+};
+var HOLD_REASON_VALUES = Object.values(HOLD_REASON);
+new Set(HOLD_STATUS_VALUES);
+new Set(RELEASE_REASON_VALUES);
+new Set(HOLD_REASON_VALUES);
 
 // src/enums/split.enums.ts
 var SPLIT_TYPE = {
+  PLATFORM_COMMISSION: "platform_commission",
+  AFFILIATE_COMMISSION: "affiliate_commission",
+  REFERRAL_COMMISSION: "referral_commission",
+  PARTNER_COMMISSION: "partner_commission",
   CUSTOM: "custom"
 };
+var SPLIT_TYPE_VALUES = Object.values(SPLIT_TYPE);
 var SPLIT_STATUS = {
   PENDING: "pending",
-  PAID: "paid"};
+  DUE: "due",
+  PAID: "paid",
+  WAIVED: "waived",
+  CANCELLED: "cancelled"
+};
+var SPLIT_STATUS_VALUES = Object.values(
+  SPLIT_STATUS
+);
+var PAYOUT_METHOD = {
+  BANK_TRANSFER: "bank_transfer",
+  MOBILE_WALLET: "mobile_wallet",
+  PLATFORM_BALANCE: "platform_balance",
+  CRYPTO: "crypto",
+  CHECK: "check",
+  MANUAL: "manual"
+};
+var PAYOUT_METHOD_VALUES = Object.values(PAYOUT_METHOD);
+new Set(SPLIT_TYPE_VALUES);
+new Set(SPLIT_STATUS_VALUES);
+new Set(PAYOUT_METHOD_VALUES);
 
 // src/utils/commission-split.ts
 function calculateSplits(amount, splitRules = [], gatewayFeeRate = 0) {