@stacksjs/payments 0.75.342 → 0.75.343

package/README.md

@@ -61,3 +61,13 @@ Many thanks to the following core technologies & people who have contributed to
 The MIT License (MIT). Please see [LICENSE](https://github.com/stacksjs/stacks/tree/main/LICENSE.md) for more information.
 
 Made with 💙
+
+## Direct-charge financial reconciliation
+
+`directChargeFinancials(paymentIntentId, originalAccount)` reads canonical provider facts on the payment's original connected account. It returns the successful charge, every refund and dispute, its application fee and fee refunds, and their balance transactions. Platform fee reads stay on the platform. All lists are paginated, ownership is verified, and incomplete pagination fails. Importing the helper does not initialize Stripe.
+
+Call after acquiring the application's payment lock. Persist immutable movement IDs with their account scope, and use the normal durable queue to retry `DirectChargeFinancialsPendingError`: fees and balance transactions can appear asynchronously. A missing fee is never inferred to be zero. Do not expose the returned Stripe objects in public responses.
+
+Balance amounts, fees and net remain in their actual settlement currency with the provider exchange rate. Contributor allocations belong in their own presentment-currency ledger; a dispute status alone does not prove reinstatement, and a charge refund does not prove that the application fee was returned.
+
+References: [direct charges](https://docs.stripe.com/connect/direct-charges), [refund pagination](https://docs.stripe.com/api/refunds/list), [disputes](https://docs.stripe.com/api/disputes/list), [application fees](https://docs.stripe.com/api/application_fees/list).

package/dist/connect/financials.d.ts

@@ -0,0 +1,30 @@
+import type Stripe from 'stripe';
+/** Retrieve current facts on the ORIGINAL direct-charge account. Call after
+ * acquiring the application's payment lock, not before it. Every list is fully
+ * paginated; platform application fees never use the connected-account header.
+ * No writes, transfers, credentials, or event-snapshot state are accepted.
+ * https://docs.stripe.com/connect/direct-charges
+ */
+export declare function directChargeFinancials(paymentIntentId: string, account: string, client?: Stripe): Promise<DirectChargeFinancials>;
+export declare interface DirectChargeMovement {
+  account: string | 'platform'
+  sourceId: string
+  kind: 'charge' | 'refund' | 'dispute' | 'application_fee' | 'application_fee_refund'
+  transaction: Stripe.BalanceTransaction
+}
+/** Server-only provider facts. Settlement amounts retain their own currency and
+ * exchange rate; they are not contributor allocations or available funds. */
+export declare interface DirectChargeFinancials {
+  account: string
+  charge: Stripe.Charge
+  refunds: Stripe.Refund[]
+  disputes: Stripe.Dispute[]
+  applicationFee: Stripe.ApplicationFee | null
+  applicationFeeRefunds: Stripe.FeeRefund[]
+  movements: DirectChargeMovement[]
+}
+/** Stripe creates application fees/balance transactions asynchronously. Retry
+ * through the caller's durable queue; absence must never mean a zero fee. */
+export declare class DirectChargeFinancialsPendingError extends Error {
+
+}

package/dist/connect/financials.js

@@ -0,0 +1 @@
+import{stripe}from"../drivers/stripe";import{asAccount}from"./direct";export class DirectChargeFinancialsPendingError extends Error{}function id(value){return typeof value==="string"?value:String(value?.id||"")}async function allPages(read){const rows=[],seen=new Set;let after;for(let page=0;page<100;page++){const result=await read(after);for(const row of result.data){if(!row.id||seen.has(row.id))throw Error("Incomplete or repeated Stripe financial page");seen.add(row.id);rows.push(row)}if(!result.has_more)return rows;if(!result.data.length)throw Error("Incomplete Stripe financial page");after=result.data.at(-1).id}throw Error("Stripe financial pagination exceeded its bound")}export async function directChargeFinancials(paymentIntentId,account,client=stripe){const options=asAccount(account);if(!/^pi_[a-z0-9_]+$/i.test(paymentIntentId))throw Error("Expected a Stripe PaymentIntent ID");const intent=await client.paymentIntents.retrieve(paymentIntentId,{},options);if(intent.id!==paymentIntentId||intent.status!=="succeeded"||!id(intent.latest_charge))throw new DirectChargeFinancialsPendingError("The original payment has no successful charge yet");const charge=await client.charges.retrieve(id(intent.latest_charge),{},options);if(id(charge.payment_intent)!==paymentIntentId||charge.id!==id(intent.latest_charge)||!charge.paid||!charge.captured)throw Error("Charge does not match the successful direct payment");const refunds=await allPages((after)=>client.refunds.list({charge:charge.id,limit:100,...after?{starting_after:after}:{}},options)),disputes=await allPages((after)=>client.disputes.list({charge:charge.id,limit:100,...after?{starting_after:after}:{}},options));for(const item of[...refunds,...disputes])if(id(item.charge)!==charge.id||item.payment_intent&&id(item.payment_intent)!==paymentIntentId)throw Error("Foreign refund or dispute in direct-charge financials");let applicationFee=null;if(id(charge.application_fee))applicationFee=await client.applicationFees.retrieve(id(charge.application_fee));else if(Number(charge.application_fee_amount)>0){const fees=await allPages((after)=>client.applicationFees.list({charge:charge.id,limit:100,...after?{starting_after:after}:{}}));if(fees.length!==1)throw new DirectChargeFinancialsPendingError("The direct-charge application fee is not available yet");applicationFee=fees[0]}if(applicationFee&&(id(applicationFee.account)!==account||id(applicationFee.charge)!==charge.id))throw Error("Application fee belongs to another direct charge or account");const applicationFeeRefunds=applicationFee?await allPages((after)=>client.applicationFees.listRefunds(applicationFee.id,{limit:100,...after?{starting_after:after}:{}})):[];if(applicationFeeRefunds.some((refund)=>id(refund.fee)!==applicationFee.id))throw Error("Foreign application-fee refund");const movements=[],seen=new Map;async function movement(reference,sourceId,kind,scope,required=!0){const transactionId=id(reference);if(!transactionId){if(required)throw new DirectChargeFinancialsPendingError("A provider balance transaction is not available yet");return}if(!/^txn_[a-z0-9_]+$/i.test(transactionId))throw Error("Invalid provider balance transaction");const transaction=await client.balanceTransactions.retrieve(transactionId,{},scope==="platform"?void 0:options);if(transaction.id!==transactionId||id(transaction.source)&&id(transaction.source)!==sourceId)throw Error("Foreign provider balance transaction");const entry={account:scope,sourceId,kind,transaction},key=`${scope}:${transactionId}`;if(seen.has(key)){if(JSON.stringify(seen.get(key))!==JSON.stringify(entry))throw Error("Conflicting provider balance transaction");return}seen.set(key,entry);movements.push(entry)}await movement(charge.balance_transaction,charge.id,"charge",account);for(const refund of refunds){await movement(refund.balance_transaction,refund.id,"refund",account,refund.status==="succeeded");await movement(refund.failure_balance_transaction,refund.id,"refund",account,!1)}for(const dispute of disputes)for(const transaction of dispute.balance_transactions)await movement(transaction,dispute.id,"dispute",account);if(applicationFee)await movement(applicationFee.balance_transaction,applicationFee.id,"application_fee","platform");for(const refund of applicationFeeRefunds)await movement(refund.balance_transaction,refund.id,"application_fee_refund","platform");return{account,charge,refunds,disputes,applicationFee,applicationFeeRefunds,movements}}

package/dist/connect/index.d.ts

@@ -1,6 +1,7 @@
 import { asAccount, connectedCustomer, directCheckout, directCheckoutPaymentData, directCheckoutSubscriptionData, directPaymentIntentParams, directSubscriptionParams, manageDirectSubscription } from './direct';
 import { checkoutLineItemsTotal, destinationCheckoutPaymentData, destinationCheckoutSubscriptionData, destinationFeeCents, destinationFeePercent, destinationPaymentIntentParams, destinationSubscriptionParams, splitFee } from './destination';
 import { connectRefund, connectRefundParams, isDestinationCharge } from './refund';
+import { directChargeFinancials } from './financials';
 import { manageConnectedAccount } from './account';
 import { manageConnectWebhook } from './webhook';
 import { manageDestinationCharge } from './charge';
@@ -29,6 +30,7 @@ export declare const connect: {
   asAccount: typeof asAccount;
   customer: typeof connectedCustomer;
   directCheckout: typeof directCheckout;
+  directChargeFinancials: typeof directChargeFinancials;
   directPaymentIntentParams: typeof directPaymentIntentParams;
   directCheckoutPaymentData: typeof directCheckoutPaymentData;
   directCheckoutSubscriptionData: typeof directCheckoutSubscriptionData;
@@ -74,6 +76,7 @@ export * from './account';
 export * from './charge';
 export * from './destination';
 export * from './direct';
+export * from './financials';
 export * from './payout';
 export * from './refund';
 export * from './subscription';

package/dist/connect/index.js

@@ -1 +1 @@
-export*from"./account";export*from"./charge";export*from"./destination";export*from"./direct";export*from"./payout";export*from"./refund";export*from"./subscription";export*from"./transfer";export*from"./webhook";import{manageConnectedAccount}from"./account";import{manageDestinationCharge}from"./charge";import{asAccount,connectedCustomer,directCheckout,directCheckoutPaymentData,directCheckoutSubscriptionData,directPaymentIntentParams,directSubscriptionParams,manageDirectSubscription}from"./direct";import{checkoutLineItemsTotal,destinationCheckoutPaymentData,destinationCheckoutSubscriptionData,destinationFeeCents,destinationFeePercent,destinationPaymentIntentParams,destinationSubscriptionParams,splitFee}from"./destination";import{managePayout}from"./payout";import{connectRefund,connectRefundParams,isDestinationCharge}from"./refund";import{manageDestinationSubscription}from"./subscription";import{manageTransfer}from"./transfer";import{manageConnectWebhook}from"./webhook";export const connect={createAccount:manageConnectedAccount.createConnectedAccount,createTestAccount:manageConnectedAccount.createTestConnectedAccount,onboardingLink:manageConnectedAccount.accountOnboardingLink,accountStatus:manageConnectedAccount.accountStatus,retrieveAccount:manageConnectedAccount.retrieveConnectedAccount,destinationCharge:manageDestinationCharge.destinationCharge,applicationFeeFor:manageDestinationCharge.applicationFeeFor,feeCents:destinationFeeCents,feePercent:destinationFeePercent,paymentIntentParams:destinationPaymentIntentParams,checkoutPaymentData:destinationCheckoutPaymentData,checkoutSubscriptionData:destinationCheckoutSubscriptionData,subscriptionParams:destinationSubscriptionParams,lineItemsTotal:checkoutLineItemsTotal,splitFee,asAccount,customer:connectedCustomer,directCheckout,directPaymentIntentParams,directCheckoutPaymentData,directCheckoutSubscriptionData,directSubscriptionParams,directSubscriptionCheckout:manageDirectSubscription.checkout,refund:connectRefund,refundParams:connectRefundParams,isDestinationCharge,subscriptionCheckout:manageDestinationSubscription.checkout,subscriptionFeePercent:manageDestinationSubscription.feePercentFor,subscriptionDestination:manageDestinationSubscription.destinationOf,createTransfer:manageTransfer.createTransfer,reverseTransfer:manageTransfer.reverseTransfer,listTransfers:manageTransfer.listTransfers,retrieveTransfer:manageTransfer.retrieveTransfer,listPayouts:managePayout.listPayouts,retrievePayout:managePayout.retrievePayout,accountBalance:managePayout.accountBalance,onAccount:manageConnectWebhook.onAccount,onPayout:manageConnectWebhook.onPayout,getAccount:manageConnectWebhook.getAccount,getPayout:manageConnectWebhook.getPayout,getConnectedAccountId:manageConnectWebhook.getConnectedAccountId,account:manageConnectedAccount,charge:manageDestinationCharge,subscription:manageDestinationSubscription,directSubscription:manageDirectSubscription,transfer:manageTransfer,payout:managePayout};
+export*from"./account";export*from"./charge";export*from"./destination";export*from"./direct";export*from"./financials";export*from"./payout";export*from"./refund";export*from"./subscription";export*from"./transfer";export*from"./webhook";import{manageConnectedAccount}from"./account";import{manageDestinationCharge}from"./charge";import{asAccount,connectedCustomer,directCheckout,directCheckoutPaymentData,directCheckoutSubscriptionData,directPaymentIntentParams,directSubscriptionParams,manageDirectSubscription}from"./direct";import{checkoutLineItemsTotal,destinationCheckoutPaymentData,destinationCheckoutSubscriptionData,destinationFeeCents,destinationFeePercent,destinationPaymentIntentParams,destinationSubscriptionParams,splitFee}from"./destination";import{managePayout}from"./payout";import{directChargeFinancials}from"./financials";import{connectRefund,connectRefundParams,isDestinationCharge}from"./refund";import{manageDestinationSubscription}from"./subscription";import{manageTransfer}from"./transfer";import{manageConnectWebhook}from"./webhook";export const connect={createAccount:manageConnectedAccount.createConnectedAccount,createTestAccount:manageConnectedAccount.createTestConnectedAccount,onboardingLink:manageConnectedAccount.accountOnboardingLink,accountStatus:manageConnectedAccount.accountStatus,retrieveAccount:manageConnectedAccount.retrieveConnectedAccount,destinationCharge:manageDestinationCharge.destinationCharge,applicationFeeFor:manageDestinationCharge.applicationFeeFor,feeCents:destinationFeeCents,feePercent:destinationFeePercent,paymentIntentParams:destinationPaymentIntentParams,checkoutPaymentData:destinationCheckoutPaymentData,checkoutSubscriptionData:destinationCheckoutSubscriptionData,subscriptionParams:destinationSubscriptionParams,lineItemsTotal:checkoutLineItemsTotal,splitFee,asAccount,customer:connectedCustomer,directCheckout,directChargeFinancials,directPaymentIntentParams,directCheckoutPaymentData,directCheckoutSubscriptionData,directSubscriptionParams,directSubscriptionCheckout:manageDirectSubscription.checkout,refund:connectRefund,refundParams:connectRefundParams,isDestinationCharge,subscriptionCheckout:manageDestinationSubscription.checkout,subscriptionFeePercent:manageDestinationSubscription.feePercentFor,subscriptionDestination:manageDestinationSubscription.destinationOf,createTransfer:manageTransfer.createTransfer,reverseTransfer:manageTransfer.reverseTransfer,listTransfers:manageTransfer.listTransfers,retrieveTransfer:manageTransfer.retrieveTransfer,listPayouts:managePayout.listPayouts,retrievePayout:managePayout.retrievePayout,accountBalance:managePayout.accountBalance,onAccount:manageConnectWebhook.onAccount,onPayout:manageConnectWebhook.onPayout,getAccount:manageConnectWebhook.getAccount,getPayout:manageConnectWebhook.getPayout,getConnectedAccountId:manageConnectWebhook.getConnectedAccountId,account:manageConnectedAccount,charge:manageDestinationCharge,subscription:manageDestinationSubscription,directSubscription:manageDirectSubscription,transfer:manageTransfer,payout:managePayout};

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/payments",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.342",
+  "version": "0.75.343",
   "description": "The Stacks payments package. Currently supporting Stripe.",
   "author": "Chris Breuer",
   "contributors": [
@@ -60,12 +60,12 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/config": "0.75.342",
-    "@stacksjs/database": "0.75.342",
-    "@stacksjs/error-handling": "0.75.342",
-    "@stacksjs/logging": "0.75.342",
-    "@stacksjs/orm": "0.75.342",
-    "@stacksjs/types": "0.75.342"
+    "@stacksjs/config": "0.75.343",
+    "@stacksjs/database": "0.75.343",
+    "@stacksjs/error-handling": "0.75.343",
+    "@stacksjs/logging": "0.75.343",
+    "@stacksjs/orm": "0.75.343",
+    "@stacksjs/types": "0.75.343"
   },
   "peerDependencies": {
     "@stripe/stripe-js": "^10.0.0",
@@ -80,7 +80,7 @@
     }
   },
   "devDependencies": {
-    "@stacksjs/utils": "0.75.342",
+    "@stacksjs/utils": "0.75.343",
     "@stripe/stripe-js": "^10.0.0",
     "better-dx": "^0.2.24",
     "stripe": "23.0.0"