@classytic/revenue 2.1.3 → 2.2.0

package/dist/{settlement.repository-BAdc9qGl.mjs → settlement.repository-CfvgX3et.mjs}

@@ -1,7 +1,7 @@
 import { _ as TRANSACTION_STATUS, a as TRANSACTION_KIND, s as initialStatusFor } from "./bank-feed.enums-kYTLTTbe.mjs";
-import { n as createEvent, t as REVENUE_EVENTS } from "./event-constants-Dn1TKahe.mjs";
+import { n as createEvent, t as REVENUE_EVENTS } from "./event-constants-DM_-A57b.mjs";
 import { g as SETTLEMENT_STATUS, r as SUBSCRIPTION_STATUS, w as HOLD_STATUS } from "./subscription.enums-95othr0i.mjs";
-import { f as SettlementNotFoundError, g as WrongTransactionKindError, h as ValidationError, m as TransactionNotFoundError, n as BankFeedImportError, p as SubscriptionNotFoundError } from "./errors-LYYg9wcs.mjs";
+import { _ as WrongTransactionKindError, g as ValidationError, h as TransactionNotFoundError, m as SubscriptionNotFoundError, n as BankFeedImportError, o as MethodKindLockedError, p as SettlementNotFoundError } from "./errors-Bt5NRVMq.mjs";
 import { SETTLEMENT_STATE_MACHINE, SUBSCRIPTION_STATE_MACHINE, TRANSACTION_STATE_MACHINE, smFor } from "./core/state-machines.mjs";
 import { a as reverseTax, c as reverseCommission, n as calculateSplits, s as calculateCommission, t as calculateOrganizationPayout } from "./splits-CNfQj92L.mjs";
 import { Repository, repoOptionsFromCtx, withTransaction } from "@classytic/mongokit";
@@ -212,6 +212,7 @@ var TransactionRepository = class extends RevenueRepositoryBase {
 					amount: params.amount,
 					currency
 				},
+				methodKind: params.methodKind,
 				metadata: params.metadata,
 				...params.paymentData
 			});
@@ -238,6 +239,7 @@ var TransactionRepository = class extends RevenueRepositoryBase {
 			tax: 0,
 			net: params.amount - (commission?.gatewayFeeAmount ?? 0),
 			method: params.gateway,
+			methodKind: params.methodKind,
 			status: params.amount === 0 ? TRANSACTION_STATUS.VERIFIED : TRANSACTION_STATUS.PENDING,
 			gateway: gatewayData,
 			commission: commission ?? void 0,
@@ -342,6 +344,7 @@ var TransactionRepository = class extends RevenueRepositoryBase {
 				tax: reversedTax?.taxAmount ?? 0,
 				net: refundAmount - (reversedCommission?.gatewayFeeAmount ?? 0) - (reversedTax?.taxAmount ?? 0),
 				method: transaction.method,
+				methodKind: transaction.methodKind,
 				status: TRANSACTION_STATUS.VERIFIED,
 				gateway: transaction.gateway,
 				commission: reversedCommission ?? void 0,
@@ -479,6 +482,7 @@ var TransactionRepository = class extends RevenueRepositoryBase {
 				tax: 0,
 				net: releaseAmount,
 				method: transaction.method,
+				methodKind: transaction.methodKind,
 				status: TRANSACTION_STATUS.VERIFIED,
 				relatedTransactionId: transaction._id,
 				sourceId: transaction.sourceId,
@@ -533,6 +537,7 @@ var TransactionRepository = class extends RevenueRepositoryBase {
 				tax: 0,
 				net: s.netAmount,
 				method: transaction.method,
+				methodKind: transaction.methodKind,
 				status: TRANSACTION_STATUS.VERIFIED,
 				relatedTransactionId: transaction._id,
 				sourceId: transaction.sourceId,
@@ -557,6 +562,7 @@ var TransactionRepository = class extends RevenueRepositoryBase {
 				tax: 0,
 				net: orgPayout,
 				method: transaction.method,
+				methodKind: transaction.methodKind,
 				status: TRANSACTION_STATUS.VERIFIED,
 				relatedTransactionId: transaction._id,
 				verifiedAt: /* @__PURE__ */ new Date()
@@ -604,6 +610,7 @@ var TransactionRepository = class extends RevenueRepositoryBase {
 	*              `source` (provenance — `'plaid'`, `'ofx'`, …).
 	*/
 	async import(rows, opts, ctx = {}) {
+		if (!opts.methodKind) throw new BankFeedImportError("`opts.methodKind` is required on TransactionRepository.import() — pick the canonical PaymentMethodKind for the source (e.g. `'bank_transfer'` for Plaid/OFX, `'card'` for a Stripe balance, `'wallet'` for PayPal, `'cryptocurrency'` for an exchange).");
 		const startedAt = Date.now();
 		if (!Array.isArray(rows) || rows.length === 0) return {
 			inserted: 0,
@@ -663,6 +670,7 @@ var TransactionRepository = class extends RevenueRepositoryBase {
 				source: opts.source,
 				type: "bank_feed",
 				tags: ["bank_feed", opts.source],
+				methodKind: opts.methodKind,
 				fee: 0,
 				tax: 0,
 				net: absoluteAmount,
@@ -747,7 +755,8 @@ var TransactionRepository = class extends RevenueRepositoryBase {
 			if (page.transactions && page.transactions.length > 0) {
 				const report = await this.import(page.transactions, {
 					bankAccountId: params.bankAccountId,
-					source: providerName
+					source: providerName,
+					methodKind: params.methodKind
 				}, ctx);
 				totalImported += report.inserted;
 				totalUpdated += report.updated;
@@ -789,7 +798,8 @@ var TransactionRepository = class extends RevenueRepositoryBase {
 		});
 		return this.import(parsed.transactions, {
 			bankAccountId: upload.bankAccountId,
-			source: providerName
+			source: providerName,
+			methodKind: upload.methodKind
 		}, ctx);
 	}
 	/**
@@ -812,6 +822,7 @@ var TransactionRepository = class extends RevenueRepositoryBase {
 			tax: 0,
 			net: data.amount,
 			method: "manual",
+			methodKind: data.methodKind,
 			status: initialStatusFor(TRANSACTION_KIND.MANUAL),
 			source: "manual",
 			...data.description !== void 0 ? { description: data.description } : {},
@@ -826,6 +837,56 @@ var TransactionRepository = class extends RevenueRepositoryBase {
 		}, this.optsFromCtx(ctx));
 	}
 	/**
+	* Backfill the `methodKind` on a Transaction created with kind
+	* unknown — the canonical use case is hosted-checkout (Stripe
+	* Checkout, PayPal redirect, Razorpay Checkout) where the customer
+	* picks their payment method on the gateway's UI, AFTER the host has
+	* already created the PaymentIntent + Transaction with
+	* `methodKind: 'other'`.
+	*
+	* Call this from your verification / webhook handler once you know
+	* the customer's actual choice — e.g. inside
+	* `payment_intent.succeeded`:
+	*
+	* ```ts
+	* await transactionRepository.backfillMethodKind(
+	*   tx._id,
+	*   stripePaymentIntentToKind(event.data.object),
+	*   ctx,
+	* );
+	* ```
+	*
+	* **Guard rule.** Atomic CAS — succeeds only when the doc has
+	* `methodKind === 'other'` AND `status === 'pending'`. Any other
+	* combination throws `MethodKindLockedError` (HTTP 409): once a
+	* transaction has a specific kind (or has settled past pending),
+	* silently overwriting it would corrupt downstream analytics and
+	* accounting reports.
+	*
+	* Emits `revenue:transaction.updated` with `changedFields:
+	* ['methodKind']` so subscribers can re-bucket the row.
+	*/
+	async backfillMethodKind(transactionId, methodKind, ctx = {}) {
+		const updated = await this.findOneAndUpdate({
+			_id: transactionId,
+			methodKind: "other",
+			status: TRANSACTION_STATUS.PENDING
+		}, { $set: { methodKind } }, { returnDocument: "after" });
+		if (!updated) {
+			const existing = await this.getById(transactionId, this.optsFromCtx(ctx, { throwOnNotFound: false }));
+			if (!existing) throw new TransactionNotFoundError(transactionId);
+			throw new MethodKindLockedError(transactionId, existing.methodKind ?? "unknown", existing.status ?? "unknown");
+		}
+		await this.dispatch(createEvent(REVENUE_EVENTS.TRANSACTION_UPDATED, {
+			transaction: updated,
+			changedFields: ["methodKind"]
+		}, ctx, {
+			resource: "transaction",
+			resourceId: updated.publicId
+		}), ctx);
+		return updated;
+	}
+	/**
 	* Match a bank-feed / manual transaction to GL accounts, optionally
 	* cross-linking to an upstream payment-flow transaction.
 	*

package/dist/validators/index.d.mts

@@ -1,4 +1,4 @@
-import { A as transactionBaseSchema, C as subscriptionBaseSchema, D as TransactionCreateInput, E as subscriptionUpdateSchema, M as transactionListFilterSchema, N as transactionUpdateSchema, O as TransactionListFilter, S as SubscriptionUpdateInput, T as subscriptionListFilterSchema, _ as settlementCreateSchema, a as escrowReleaseSchema, b as SubscriptionCreateInput, c as PaymentVerifyInput, d as paymentVerifySchema, f as refundSchema, g as settlementBaseSchema, h as SettlementUpdateInput, i as escrowHoldSchema, j as transactionCreateSchema, k as TransactionUpdateInput, l as RefundInput, m as SettlementListFilter, n as EscrowReleaseInput, o as splitRuleSchema, p as SettlementCreateInput, r as SplitRuleInput, s as PaymentIntentInput, t as EscrowHoldInput, u as paymentIntentSchema, v as settlementListFilterSchema, w as subscriptionCreateSchema, x as SubscriptionListFilter, y as settlementUpdateSchema } from "../escrow.schema-YuBgjL-I.mjs";
+import { A as transactionBaseSchema, C as subscriptionBaseSchema, D as TransactionCreateInput, E as subscriptionUpdateSchema, M as transactionListFilterSchema, N as transactionUpdateSchema, O as TransactionListFilter, S as SubscriptionUpdateInput, T as subscriptionListFilterSchema, _ as settlementCreateSchema, a as escrowReleaseSchema, b as SubscriptionCreateInput, c as PaymentVerifyInput, d as paymentVerifySchema, f as refundSchema, g as settlementBaseSchema, h as SettlementUpdateInput, i as escrowHoldSchema, j as transactionCreateSchema, k as TransactionUpdateInput, l as RefundInput, m as SettlementListFilter, n as EscrowReleaseInput, o as splitRuleSchema, p as SettlementCreateInput, r as SplitRuleInput, s as PaymentIntentInput, t as EscrowHoldInput, u as paymentIntentSchema, v as settlementListFilterSchema, w as subscriptionCreateSchema, x as SubscriptionListFilter, y as settlementUpdateSchema } from "../escrow.schema-BdDHuQ8C.mjs";
 import { z } from "zod";
 
 //#region src/validators/bank-feed.schema.d.ts

package/dist/validators/index.mjs

@@ -1,5 +1,5 @@
 import { n as BANK_FEED_SOURCE_VALUES, o as TRANSACTION_KIND_VALUES } from "../bank-feed.enums-kYTLTTbe.mjs";
-import { _ as transactionListFilterSchema, a as paymentVerifySchema, c as settlementCreateSchema, d as subscriptionBaseSchema, f as subscriptionCreateSchema, g as transactionCreateSchema, h as transactionBaseSchema, i as paymentIntentSchema, l as settlementListFilterSchema, m as subscriptionUpdateSchema, n as escrowReleaseSchema, o as refundSchema, p as subscriptionListFilterSchema, r as splitRuleSchema, s as settlementBaseSchema, t as escrowHoldSchema, u as settlementUpdateSchema, v as transactionUpdateSchema } from "../escrow.schema-C-b41z_G.mjs";
+import { _ as transactionListFilterSchema, a as paymentVerifySchema, c as settlementCreateSchema, d as subscriptionBaseSchema, f as subscriptionCreateSchema, g as transactionCreateSchema, h as transactionBaseSchema, i as paymentIntentSchema, l as settlementListFilterSchema, m as subscriptionUpdateSchema, n as escrowReleaseSchema, o as refundSchema, p as subscriptionListFilterSchema, r as splitRuleSchema, s as settlementBaseSchema, t as escrowHoldSchema, u as settlementUpdateSchema, v as transactionUpdateSchema } from "../escrow.schema-BcKdzrJ7.mjs";
 import { z } from "zod";
 
 //#region src/validators/bank-feed.schema.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/revenue",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "description": "Payment lifecycle engine — transactions, subscriptions, escrow, settlements, commissions. MongoKit-powered, Arc-compatible, framework-agnostic.",
   "type": "module",
   "sideEffects": false,
@@ -101,7 +101,7 @@
   ],
   "peerDependencies": {
     "@classytic/mongokit": ">=3.13.3",
-    "@classytic/primitives": ">=0.5.0",
+    "@classytic/primitives": ">=0.7.1",
     "@classytic/repo-core": ">=0.4.2",
     "mongoose": ">=9.4.1",
     "zod": ">=4.0.0"
@@ -111,7 +111,7 @@
   },
   "devDependencies": {
     "@classytic/mongokit": "^3.13.3",
-    "@classytic/primitives": ">=0.5.0",
+    "@classytic/primitives": "^0.7.1",
     "@classytic/repo-core": "^0.4.2",
     "@types/node": "^22.8.7",
     "mongoose": "^9.4.1",