@stacksjs/payments 0.75.159 → 0.75.161

package/dist/connect/index.d.ts

@@ -1,6 +1,7 @@
 import { manageConnectedAccount } from './account';
 import { manageConnectWebhook } from './webhook';
 import { manageDestinationCharge } from './charge';
+import { manageDestinationSubscription } from './subscription';
 import { managePayout } from './payout';
 import { manageTransfer } from './transfer';
 /**
@@ -14,6 +15,9 @@ export declare const connect: {
   retrieveAccount: typeof manageConnectedAccount.retrieveConnectedAccount;
   destinationCharge: typeof manageDestinationCharge.destinationCharge;
   applicationFeeFor: typeof manageDestinationCharge.applicationFeeFor;
+  subscriptionCheckout: typeof manageDestinationSubscription.checkout;
+  subscriptionFeePercent: typeof manageDestinationSubscription.feePercentFor;
+  subscriptionDestination: typeof manageDestinationSubscription.destinationOf;
   createTransfer: typeof manageTransfer.createTransfer;
   reverseTransfer: typeof manageTransfer.reverseTransfer;
   listTransfers: typeof manageTransfer.listTransfers;
@@ -28,6 +32,7 @@ export declare const connect: {
   getConnectedAccountId: typeof manageConnectWebhook.getConnectedAccountId;
   account: typeof manageConnectedAccount;
   charge: typeof manageDestinationCharge;
+  subscription: typeof manageDestinationSubscription;
   transfer: typeof manageTransfer;
   payout: typeof managePayout
 };
@@ -45,5 +50,6 @@ export declare const connect: {
 export * from './account';
 export * from './charge';
 export * from './payout';
+export * from './subscription';
 export * from './transfer';
 export * from './webhook';

package/dist/connect/index.js

@@ -1 +1 @@
-export*from"./account";export*from"./charge";export*from"./payout";export*from"./transfer";export*from"./webhook";import{manageConnectedAccount}from"./account";import{manageDestinationCharge}from"./charge";import{managePayout}from"./payout";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,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,transfer:manageTransfer,payout:managePayout};
+export*from"./account";export*from"./charge";export*from"./payout";export*from"./subscription";export*from"./transfer";export*from"./webhook";import{manageConnectedAccount}from"./account";import{manageDestinationCharge}from"./charge";import{managePayout}from"./payout";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,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,transfer:manageTransfer,payout:managePayout};

package/dist/connect/subscription.d.ts

@@ -0,0 +1,51 @@
+import type { UserModel } from '@stacksjs/orm';
+import type Stripe from 'stripe';
+export declare const manageDestinationSubscription: ManageDestinationSubscription;
+/** A recurring price defined at checkout rather than in the catalog. */
+export declare interface InlineRecurringPrice {
+  amount: number
+  currency: string
+  interval: SubscriptionInterval
+  intervalCount?: number
+  productName: string
+  productDescription?: string
+}
+export declare interface DestinationSubscriptionCheckoutOptions {
+  destination: string
+  price: string | InlineRecurringPrice
+  quantity?: number
+  trialDays?: number
+  platformFeePercent?: number
+  onBehalfOf?: boolean
+  metadata?: Record<string, string>
+  clientReferenceId?: string
+  customer?: string
+  successUrl: string
+  cancelUrl: string
+  sessionParams?: Partial<Stripe.Checkout.SessionCreateParams>
+}
+export declare interface ManageDestinationSubscription {
+  feePercentFor: (options?: { platformFeePercent?: number }) => number | undefined
+  subscriptionData: (destination: string, options?: Pick<DestinationSubscriptionCheckoutOptions, 'trialDays' | 'platformFeePercent' | 'onBehalfOf' | 'metadata'>) => Stripe.Checkout.SessionCreateParams.SubscriptionData
+  lineItem: (price: string | InlineRecurringPrice, quantity?: number) => Stripe.Checkout.SessionCreateParams.LineItem
+  checkout: (user: UserModel, options: DestinationSubscriptionCheckoutOptions) => Promise<Stripe.Response<Stripe.Checkout.Session>>
+  destinationOf: (subscription: { transfer_data?: { destination?: string | { id?: string } | null } | null }) => string | null
+}
+/**
+ * Destination subscriptions: a merchant's recurring price, billed by the
+ * platform and settled to the merchant's connected account.
+ *
+ * The subscription, its customer and its invoices live on the platform, the
+ * same as a destination charge, so one webhook endpoint sees every renewal,
+ * failed payment and cancellation, and refunds and disputes stay with the
+ * platform. Each paid invoice transfers to `transfer_data.destination`, less
+ * `application_fee_percent` (a percentage, unlike a one-off charge's fee
+ * amount, because Stripe applies it to every invoice whatever its total:
+ * prorations, a coupon's discount, a trial's zero).
+ *
+ * Cancel, resume and read these with `manageSubscription` like any other
+ * platform subscription; nothing about them needs the connected account's
+ * credentials.
+ */
+/** Billing periods Stripe accepts for a recurring price. */
+export type SubscriptionInterval = 'day' | 'week' | 'month' | 'year';

package/dist/connect/subscription.js

@@ -0,0 +1 @@
+import{config}from"@stacksjs/config";import{manageCheckout}from"../billable/checkout";import{manageCustomer}from"../billable/customer";import{requireAccountId}from"./account";const INTERVALS=["day","week","month","year"];function configuredFeePercent(){return(config||{}).payment?.connect?.platformFeePercent}export const manageDestinationSubscription=(()=>{function feePercentFor(options={}){const percent=options.platformFeePercent??configuredFeePercent();if(percent==null)return;if(!Number.isFinite(percent)||percent<0||percent>100)throw Error(`[payments/connect] platformFeePercent must be between 0 and 100, got ${percent}`);if(Math.round(percent*100)!==percent*100)throw Error(`[payments/connect] platformFeePercent takes at most two decimal places, got ${percent}`);return percent>0?percent:void 0}function subscriptionData(destination,options={}){requireAccountId(destination,"destinationSubscription");if(options.trialDays!=null&&(!Number.isInteger(options.trialDays)||options.trialDays<1||options.trialDays>730))throw Error(`[payments/connect] trialDays must be a whole number from 1 to 730, got ${options.trialDays}`);const fee=feePercentFor({platformFeePercent:options.platformFeePercent});return{transfer_data:{destination},...fee!=null?{application_fee_percent:fee}:{},...options.onBehalfOf?{on_behalf_of:destination}:{},...options.trialDays?{trial_period_days:options.trialDays}:{},...options.metadata?{metadata:options.metadata}:{}}}function lineItem(price,quantity=1){if(!Number.isInteger(quantity)||quantity<1)throw Error(`[payments/connect] quantity must be a positive whole number, got ${quantity}`);if(typeof price==="string"){if(!price.startsWith("price_"))throw Error(`[payments/connect] a catalog price id starts with "price_", got "${price}"`);return{price,quantity}}if(!Number.isInteger(price.amount)||price.amount<=0)throw Error("[payments/connect] a recurring price needs a positive amount in minor units");if(!INTERVALS.includes(price.interval))throw Error(`[payments/connect] interval must be one of ${INTERVALS.join(", ")}, got ${price.interval}`);const intervalCount=price.intervalCount??1;if(!Number.isInteger(intervalCount)||intervalCount<1)throw Error(`[payments/connect] intervalCount must be a positive whole number, got ${intervalCount}`);if(!price.productName?.trim())throw Error("[payments/connect] a recurring price needs a productName");return{quantity,price_data:{currency:price.currency.toLowerCase(),unit_amount:price.amount,recurring:{interval:price.interval,...intervalCount!==1?{interval_count:intervalCount}:{}},product_data:{name:price.productName.slice(0,250),...price.productDescription?{description:price.productDescription.slice(0,500)}:{}}}}}async function checkout(user,options){const customer=options.customer??(await manageCustomer.createOrGetStripeUser(user,{})).id;return await manageCheckout.create(user,{mode:"subscription",customer,line_items:[lineItem(options.price,options.quantity)],subscription_data:subscriptionData(options.destination,options),success_url:options.successUrl,cancel_url:options.cancelUrl,...options.clientReferenceId?{client_reference_id:options.clientReferenceId}:{},...options.metadata?{metadata:options.metadata}:{},...options.sessionParams})}function destinationOf(subscription){const destination=subscription.transfer_data?.destination;if(!destination)return null;return(typeof destination==="string"?destination:destination.id)||null}return{feePercentFor,subscriptionData,lineItem,checkout,destinationOf}})();

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/payments",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.159",
+  "version": "0.75.161",
   "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.159",
-    "@stacksjs/database": "0.75.159",
-    "@stacksjs/error-handling": "0.75.159",
-    "@stacksjs/logging": "0.75.159",
-    "@stacksjs/orm": "0.75.159",
-    "@stacksjs/types": "0.75.159"
+    "@stacksjs/config": "0.75.161",
+    "@stacksjs/database": "0.75.161",
+    "@stacksjs/error-handling": "0.75.161",
+    "@stacksjs/logging": "0.75.161",
+    "@stacksjs/orm": "0.75.161",
+    "@stacksjs/types": "0.75.161"
   },
   "peerDependencies": {
     "@stripe/stripe-js": "^10.0.0",
@@ -80,7 +80,7 @@
     }
   },
   "devDependencies": {
-    "@stacksjs/utils": "0.75.159",
+    "@stacksjs/utils": "0.75.161",
     "@stripe/stripe-js": "^10.0.0",
     "better-dx": "^0.2.24",
     "stripe": "23.0.0"