payment-kit 1.18.29 → 1.18.31

package/api/src/store/models/checkout-session.ts

@@ -27,6 +27,8 @@ import type {
   ServiceAction,
   SubscriptionData,
 } from './types';
+import { Invoice } from './invoice';
+import { Subscription } from './subscription';
 
 export const nextCheckoutSessionId = createIdGenerator('cs', 58);
 
@@ -54,6 +56,11 @@ export class CheckoutSession extends Model<InferAttributes<CheckoutSession>, Inf
   // The ID of the subscription for Checkout Sessions in subscription mode.
   declare subscription_id?: string;
 
+  // New fields for subscription grouping
+  declare enable_subscription_grouping?: boolean;
+  declare subscription_groups?: Record<string, string>;
+  declare success_subscription_count?: number;
+
   // The ID of the original expired Checkout Session that triggered the recovery flow.
   declare recovered_from?: string;
 
@@ -418,6 +425,18 @@ export class CheckoutSession extends Model<InferAttributes<CheckoutSession>, Inf
           type: DataTypes.STRING(30),
           allowNull: true,
         },
+        enable_subscription_grouping: {
+          type: DataTypes.BOOLEAN,
+          defaultValue: false,
+        },
+        subscription_groups: {
+          type: DataTypes.JSON,
+          allowNull: true,
+        },
+        success_subscription_count: {
+          type: DataTypes.INTEGER,
+          defaultValue: 0,
+        },
       },
       {
         sequelize,
@@ -489,6 +508,39 @@ export class CheckoutSession extends Model<InferAttributes<CheckoutSession>, Inf
   public isImmutable() {
     return ['complete', 'expired'].includes(this.status);
   }
+  public static async findBySubscriptionId(subscriptionId: string, options: FindOptions<CheckoutSession> = {}) {
+    if (!subscriptionId) {
+      return null;
+    }
+    let checkoutSession = await CheckoutSession.findOne({
+      where: { subscription_id: subscriptionId },
+      ...options,
+    });
+    if (!checkoutSession) {
+      const subscription = await Subscription.findByPk(subscriptionId);
+      if (subscription?.metadata?.checkout_session_id) {
+        checkoutSession = await CheckoutSession.findByPk(subscription.metadata.checkout_session_id);
+        return checkoutSession;
+      }
+      const invoice = await Invoice.findOne({
+        // @ts-ignore
+        where: {
+          subscription_id: subscriptionId,
+          checkout_session_id: {
+            [Op.ne]: null,
+          },
+        },
+        order: [['created_at', 'ASC']],
+      });
+      if (invoice) {
+        checkoutSession = await CheckoutSession.findOne({
+          where: { id: invoice.checkout_session_id },
+          ...options,
+        });
+      }
+    }
+    return checkoutSession;
+  }
 }
 
 export type TCheckoutSession = InferAttributes<CheckoutSession>;

package/api/src/store/models/index.ts

@@ -148,6 +148,7 @@ export type TCheckoutSessionExpanded = TCheckoutSession & {
   payment_intent?: TPaymentIntent;
   subscription?: TSubscription;
   customer?: TCustomer;
+  subscriptions?: TSubscription[];
 };
 
 export type TPaymentIntentExpanded = TPaymentIntent & {

package/api/src/store/models/payment-link.ts

@@ -87,6 +87,8 @@ export class PaymentLink extends Model<InferAttributes<PaymentLink>, InferCreati
 
   declare payment_intent_data?: PaymentIntentData;
 
+  declare enable_subscription_grouping?: boolean;
+
   // TODO: following fields not supported
   // application_fee_amount
   // application_fee_percent
@@ -218,6 +220,10 @@ export class PaymentLink extends Model<InferAttributes<PaymentLink>, InferCreati
           type: DataTypes.JSON,
           allowNull: true,
         },
+        enable_subscription_grouping: {
+          type: DataTypes.BOOLEAN,
+          defaultValue: false,
+        },
       },
       {
         sequelize,

package/api/src/store/models/subscription.ts

@@ -7,7 +7,13 @@ import { createCustomEvent, createEvent, createStatusEvent } from '../../libs/au
 import logger from '../../libs/logger';
 import { createIdGenerator } from '../../libs/util';
 import { Invoice } from './invoice';
-import type { PaymentDetails, PaymentSettings, PriceRecurring, ServiceAction } from './types';
+import type {
+  PaymentDetails,
+  PaymentSettings,
+  PriceRecurring,
+  ServiceAction,
+  SubscriptionBillingThresholds,
+} from './types';
 
 export const nextSubscriptionId = createIdGenerator('sub', 24);
 
@@ -69,11 +75,7 @@ export class Subscription extends Model<InferAttributes<Subscription>, InferCrea
   };
 
   declare billing_cycle_anchor: number;
-  declare billing_thresholds?: {
-    amount_gte: number;
-    stake_gte: number;
-    reset_billing_cycle_anchor: boolean;
-  };
+  declare billing_thresholds?: SubscriptionBillingThresholds;
 
   declare collection_method: LiteralUnion<'charge_automatically' | 'send_invoice', string>;
 

package/api/src/store/models/types.ts

@@ -189,6 +189,20 @@ export type LineItem = {
   upsell_price_id?: string;
   cross_sell?: boolean;
   custom_amount?: string;
+  subscription_data?: SubscriptionData & {
+    service_actions?: ServiceAction[];
+    billing_cycle_anchor?: number;
+    metadata?: Record<string, any>;
+    proration_behavior?: LiteralUnion<'create_prorations' | 'none', string>;
+    trial_end?: number;
+    trial_settings?: {
+      end_behavior: {
+        missing_payment_method: LiteralUnion<'cancel' | 'pause' | 'create_invoice', string>;
+      };
+    };
+    days_until_due?: number;
+    days_until_cancel?: number;
+  };
   // TODO: following are not supported
   // price_data?: any;
   // dynamic_tax_rates?: any;
@@ -299,6 +313,7 @@ export type VaultConfig = {
   enabled: boolean;
   deposit_threshold: string; // 存入阈值
   withdraw_threshold: string; // 提取阈值
+  buffer_threshold: string; // 差额阈值
 };
 
 export type PaymentSettings = {
@@ -423,6 +438,16 @@ export type SubscriptionData = {
   recovered_from?: string;
   trial_end?: number;
   trial_currency?: string;
+  no_stake?: boolean; // skip stake for this subscription
+  notification_settings?: NotificationSetting;
+};
+
+export type SubscriptionBillingThresholds = {
+  amount_gte: number;
+  stake_gte: number;
+  reset_billing_cycle_anchor: boolean;
+  no_stake?: boolean;
+  references_primary_stake?: boolean;
 };
 
 // Very similar to PaymentLink
@@ -703,7 +728,7 @@ export type EventType = LiteralUnion<
 
 export type StripeRefundReason = 'duplicate' | 'fraudulent' | 'requested_by_customer';
 
-export type SettingType = LiteralUnion<'donate', string>;
+export type SettingType = LiteralUnion<'donate' | 'notification', string>;
 
 export type NotificationFrequency = 'default' | 'daily' | 'weekly' | 'monthly';
 export type NotificationSchedule = {
@@ -720,3 +745,9 @@ export type CustomerPreferences = {
   notification?: NotificationSettings;
   // support more preferences
 };
+
+export type NotificationSetting = {
+  self_handle: boolean;
+  exclude_events?: EventType[];
+  include_events?: EventType[];
+};

package/api/tests/libs/session.spec.ts

@@ -1,3 +1,4 @@
+import dayjs from '../../src/libs/dayjs';
 import {
   getBillingThreshold,
   getCheckoutAmount,
@@ -5,8 +6,18 @@ import {
   getPriceCurrencyOptions,
   getPriceUintAmountByCurrency,
   getRecurringPeriod,
+  getSubscriptionCreateSetup,
+  getCheckoutSessionSubscriptionIds,
+  getOneTimeLineItems,
+  getRecurringLineItems,
+  mergeSubscriptionDataFromLineItems,
+  getFastCheckoutAmount,
+  createPaymentBeneficiaries,
+  getSubscriptionLineItems,
 } from '../../src/libs/session';
 import type { TLineItemExpanded } from '../../src/store/models';
+import type { PaymentBeneficiary } from '../../src/store/models/types';
+import { SubscriptionItem } from '../../src/store/models';
 
 describe('getCheckoutMode', () => {
   it('should return "setup" when items array is empty', () => {
@@ -265,3 +276,415 @@ describe('getCheckoutAmount', () => {
     expect(result.total).toBe('20');
   });
 });
+
+describe('getSubscriptionCreateSetup', () => {
+  const currencies = [
+    {
+      currency_id: 'usd',
+      unit_amount: '1',
+    },
+  ];
+
+  it('should calculate setup for recurring licensed price type', () => {
+    const items = [
+      {
+        price: { type: 'one_time', currency_options: currencies },
+        quantity: 1,
+      },
+      {
+        price: {
+          type: 'recurring',
+          currency_options: currencies,
+          recurring: { interval: 'day', interval_count: '1', usage_type: 'licensed' },
+        },
+        quantity: 2,
+      },
+    ];
+    const result = getSubscriptionCreateSetup(items as any, 'usd');
+    expect(result.amount.setup).toBe('3');
+  });
+
+  it('should not calculate setup for recurring metered price type', () => {
+    const items = [
+      {
+        price: { type: 'one_time', currency_options: currencies },
+        quantity: 1,
+      },
+      {
+        price: {
+          type: 'recurring',
+          currency_options: currencies,
+          recurring: { interval: 'day', interval_count: '1', usage_type: 'metered' },
+        },
+        quantity: 2,
+      },
+    ];
+    const result = getSubscriptionCreateSetup(items as any, 'usd');
+    expect(result.amount.setup).toBe('1');
+  });
+
+  it('should calculate cycle duration for recurring price type', () => {
+    const items = [
+      {
+        price: { type: 'recurring', currency_options: currencies, recurring: { interval: 'day', interval_count: '1' } },
+        quantity: 2,
+      },
+    ];
+    const result = getSubscriptionCreateSetup(items as any, 'usd');
+    expect(result.cycle.duration).toBe(24 * 60 * 60 * 1000);
+  });
+
+  it('should calculate trial period when only trialInDays is provided', () => {
+    const items = [
+      {
+        price: { type: 'recurring', currency_options: currencies, recurring: { interval: 'day', interval_count: '1' } },
+        quantity: 2,
+      },
+    ];
+    const result = getSubscriptionCreateSetup(items as any, 'usd', 7);
+    const now = dayjs().unix();
+    expect(result.trial.start).toBe(now);
+    expect(result.trial.end).toBe(
+      dayjs()
+        .add(7 * 24 * 60 * 60 * 1000, 'millisecond')
+        .unix()
+    );
+  });
+
+  it('should trialEnd overwrite trialInDays', () => {
+    const items = [
+      {
+        price: { type: 'recurring', currency_options: currencies, recurring: { interval: 'day', interval_count: '1' } },
+        quantity: 2,
+      },
+    ];
+    const result = getSubscriptionCreateSetup(items as any, 'usd', 1, dayjs().add(7, 'day').unix());
+    const now = dayjs().unix();
+    expect(result.trial.start).toBe(now);
+    expect(result.trial.end).toBe(
+      dayjs()
+        .add(7 * 24 * 60 * 60 * 1000, 'millisecond')
+        .unix()
+    );
+  });
+
+  it('should calculate trial period when only trialEnd is provided', () => {
+    const items = [
+      {
+        price: { type: 'recurring', currency_options: currencies, recurring: { interval: 'day', interval_count: '1' } },
+        quantity: 2,
+      },
+    ];
+    const result = getSubscriptionCreateSetup(items as any, 'usd', 0, dayjs().add(7, 'day').unix());
+    const now = dayjs().unix();
+    expect(result.trial.start).toBe(now);
+    expect(result.trial.end).toBe(
+      dayjs()
+        .add(7 * 24 * 60 * 60 * 1000, 'millisecond')
+        .unix()
+    );
+  });
+});
+
+describe('getCheckoutSessionSubscriptionIds', () => {
+  it('should return array with subscription_id when enable_subscription_grouping is false', () => {
+    const checkoutSession = {
+      subscription_id: 'sub_123',
+      enable_subscription_grouping: false,
+      subscription_groups: { price_1: 'sub_456', price_2: 'sub_789' },
+    };
+    const result = getCheckoutSessionSubscriptionIds(checkoutSession as any);
+    expect(result).toEqual(['sub_123']);
+  });
+
+  it('should return array of subscription_groups values when enable_subscription_grouping is true', () => {
+    const checkoutSession = {
+      subscription_id: 'sub_123',
+      enable_subscription_grouping: true,
+      subscription_groups: { price_1: 'sub_456', price_2: 'sub_789' },
+    };
+    const result = getCheckoutSessionSubscriptionIds(checkoutSession as any);
+    expect(result).toEqual(['sub_456', 'sub_789']);
+  });
+
+  it('should filter out empty subscription ids', () => {
+    const checkoutSession = {
+      enable_subscription_grouping: true,
+      subscription_groups: { price_1: 'sub_456', price_2: '', price_3: null },
+    };
+    const result = getCheckoutSessionSubscriptionIds(checkoutSession as any);
+    expect(result).toEqual(['sub_456']);
+  });
+
+  it('should return empty array when no subscription ids exist', () => {
+    const checkoutSession = {
+      enable_subscription_grouping: true,
+      subscription_groups: {},
+    };
+    const result = getCheckoutSessionSubscriptionIds(checkoutSession as any);
+    expect(result).toEqual([]);
+  });
+});
+
+describe('getOneTimeLineItems', () => {
+  it('should return only one-time line items', () => {
+    const lineItems = [
+      { price: { type: 'one_time' } },
+      { price: { type: 'recurring' } },
+      { price: { type: 'one_time' } },
+    ];
+    const result = getOneTimeLineItems(lineItems as TLineItemExpanded[]);
+    expect(result).toHaveLength(2);
+    // @ts-ignore
+    expect(result[0].price && result[0].price.type).toBe('one_time');
+    // @ts-ignore
+    expect(result[1].price && result[1].price.type).toBe('one_time');
+  });
+
+  it('should return empty array when no one-time items exist', () => {
+    const lineItems = [{ price: { type: 'recurring' } }, { price: { type: 'recurring' } }];
+    const result = getOneTimeLineItems(lineItems as TLineItemExpanded[]);
+    expect(result).toEqual([]);
+  });
+});
+
+describe('getRecurringLineItems', () => {
+  it('should return only recurring line items', () => {
+    const lineItems = [
+      { price: { type: 'one_time' } },
+      { price: { type: 'recurring' } },
+      { price: { type: 'recurring' } },
+    ];
+    const result = getRecurringLineItems(lineItems as TLineItemExpanded[]);
+    expect(result).toHaveLength(2);
+    // @ts-ignore
+    expect(result[0].price && result[0].price.type).toBe('recurring');
+    // @ts-ignore
+    expect(result[1].price && result[1].price.type).toBe('recurring');
+  });
+
+  it('should return empty array when no recurring items exist', () => {
+    const lineItems = [{ price: { type: 'one_time' } }, { price: { type: 'one_time' } }];
+    const result = getRecurringLineItems(lineItems as TLineItemExpanded[]);
+    expect(result).toEqual([]);
+  });
+});
+
+describe('mergeSubscriptionDataFromLineItems', () => {
+  it('should merge subscription data from multiple line items', () => {
+    const lineItems = [
+      {
+        subscription_data: {
+          description: 'Item 1',
+          metadata: { key1: 'value1' },
+        },
+      },
+      {
+        subscription_data: {
+          days_until_due: 30,
+          metadata: { key2: 'value2' },
+        },
+      },
+    ];
+    const result = mergeSubscriptionDataFromLineItems(lineItems as any);
+    expect(result).toEqual({
+      description: 'Item 1',
+      days_until_due: 30,
+      metadata: { key1: 'value1', key2: 'value2' },
+    });
+  });
+
+  it('should return empty object when line items array is empty', () => {
+    const result = mergeSubscriptionDataFromLineItems([]);
+    expect(result).toEqual({});
+  });
+
+  it('should handle line items without subscription_data', () => {
+    const lineItems = [
+      { price: { type: 'recurring' } },
+      {
+        subscription_data: {
+          description: 'Item 2',
+        },
+      },
+    ];
+    const result = mergeSubscriptionDataFromLineItems(lineItems as any);
+    expect(result).toEqual({
+      description: 'Item 2',
+    });
+  });
+
+  it('should not include metadata field if no metadata exists', () => {
+    const lineItems = [
+      {
+        subscription_data: {
+          description: 'Item 1',
+        },
+      },
+    ];
+    const result = mergeSubscriptionDataFromLineItems(lineItems as any);
+    expect(result).toEqual({
+      description: 'Item 1',
+    });
+    expect(result.metadata).toBeUndefined();
+  });
+});
+
+describe('getFastCheckoutAmount', () => {
+  it('should return total amount for payment mode', () => {
+    const items = [{ price: { type: 'one_time', currency_id: 'usd', unit_amount: '100' }, quantity: 1 }];
+    const result = getFastCheckoutAmount(items as TLineItemExpanded[], 'payment', 'usd');
+    expect(result).toBe('100');
+  });
+
+  it('should return renew amount for setup mode', () => {
+    const items = [
+      {
+        price: { type: 'recurring', recurring: { usage_type: 'licensed' }, currency_id: 'usd', unit_amount: '100' },
+        quantity: 1,
+      },
+    ];
+    const result = getFastCheckoutAmount(items as any, 'setup', 'usd');
+    expect(result).toBe('100');
+  });
+
+  it('should multiply renew amount by minimumCycle for setup mode', () => {
+    const items = [
+      {
+        price: { type: 'recurring', recurring: { usage_type: 'licensed' }, currency_id: 'usd', unit_amount: '100' },
+        quantity: 1,
+      },
+    ];
+    const result = getFastCheckoutAmount(items as any, 'setup', 'usd', false, 3);
+    expect(result).toBe('300');
+  });
+
+  it('should return total + renew*(minimumCycle-1) for subscription mode', () => {
+    const items = [
+      {
+        price: { type: 'recurring', recurring: { usage_type: 'licensed' }, currency_id: 'usd', unit_amount: '100' },
+        quantity: 1,
+      },
+      { price: { type: 'one_time', currency_id: 'usd', unit_amount: '50' }, quantity: 1 },
+    ];
+    const result = getFastCheckoutAmount(items as any, 'subscription', 'usd', false, 3);
+    expect(result).toBe('350');
+  });
+
+  it('should return total + renew*minimumCycle for subscription mode when trialing', () => {
+    const items = [
+      {
+        price: { type: 'recurring', recurring: { usage_type: 'licensed' }, currency_id: 'usd', unit_amount: '100' },
+        quantity: 1,
+      },
+      { price: { type: 'one_time', currency_id: 'usd', unit_amount: '50' }, quantity: 1 },
+    ];
+    const result = getFastCheckoutAmount(items as any, 'subscription', 'usd', true, 3);
+    expect(result).toBe('350'); // 50 (total, since recurring is 0 during trial) + 100 (renew) * 3
+  });
+
+  it('should return 0 for unknown mode', () => {
+    const items = [{ price: { type: 'one_time', currency_id: 'usd', unit_amount: '100' }, quantity: 1 }];
+    const result = getFastCheckoutAmount(items as any, 'unknown', 'usd');
+    expect(result).toBe('0');
+  });
+});
+
+describe('createPaymentBeneficiaries', () => {
+  it('should return empty array when beneficiaries array is empty', () => {
+    const beneficiaries: PaymentBeneficiary[] = [];
+    const result = createPaymentBeneficiaries('100', beneficiaries);
+    expect(result).toEqual([]);
+  });
+
+  it('should calculate correct amounts based on shares', () => {
+    const beneficiaries: PaymentBeneficiary[] = [
+      { address: 'addr1', share: '30' },
+      { address: 'addr2', share: '70' },
+    ];
+    const result = createPaymentBeneficiaries('100', beneficiaries);
+    expect(result).toHaveLength(2);
+    expect(result[0]?.share).toBe('30');
+    expect(result[0]?.address).toBe('addr1');
+    expect(result[1]?.share).toBe('70');
+    expect(result[1]?.address).toBe('addr2');
+  });
+});
+
+describe('getSubscriptionLineItems', () => {
+  it('should filter line items related to subscription', async () => {
+    const subscription = { id: 'sub_123' };
+    const lineItems = [
+      { price_id: 'price_1', price: { type: 'recurring' } },
+      { price_id: 'price_2', price: { type: 'recurring' } },
+      { price_id: 'price_3', price: { type: 'one_time' } },
+    ];
+
+    // Mock SubscriptionItem.findAll
+    const mockSubscriptionItems = [
+      { subscription_id: 'sub_123', price_id: 'price_1' },
+      { subscription_id: 'sub_123', price_id: 'price_2' },
+    ];
+    jest.spyOn(SubscriptionItem, 'findAll').mockResolvedValue(mockSubscriptionItems as any);
+
+    const result = await getSubscriptionLineItems(subscription as any, lineItems as any);
+
+    expect(result).toHaveLength(2);
+    // @ts-ignore
+    expect(result[0].price_id).toBe('price_1');
+    // @ts-ignore
+    expect(result[1].price_id).toBe('price_2');
+  });
+
+  it('should include one-time items for primary subscription', async () => {
+    const subscription = { id: 'sub_123' };
+    const primarySubscription = { id: 'sub_123' };
+    const lineItems = [
+      { price_id: 'price_1', price: { type: 'recurring' } },
+      { price_id: 'price_3', price: { type: 'one_time' } },
+    ];
+
+    // Mock SubscriptionItem.findAll
+    const mockSubscriptionItems = [{ subscription_id: 'sub_123', price_id: 'price_1' }];
+    jest.spyOn(SubscriptionItem, 'findAll').mockResolvedValue(mockSubscriptionItems as any);
+
+    const result = await getSubscriptionLineItems(subscription as any, lineItems as any, primarySubscription as any);
+
+    expect(result).toHaveLength(2);
+    // @ts-ignore
+    expect(result[0].price_id).toBe('price_1');
+    // @ts-ignore
+    expect(result[1].price_id).toBe('price_3');
+    // @ts-ignore
+    expect(result[1].price.type).toBe('one_time');
+  });
+
+  it('should handle upsell price ids', async () => {
+    const subscription = { id: 'sub_456' };
+    const lineItems = [{ price_id: 'price_1', upsell_price_id: 'price_2', price: { type: 'recurring' } }];
+
+    // Mock SubscriptionItem.findAll
+    const mockSubscriptionItems = [{ subscription_id: 'sub_456', price_id: 'price_2' }];
+    jest.spyOn(SubscriptionItem, 'findAll').mockResolvedValue(mockSubscriptionItems as any);
+
+    const result = await getSubscriptionLineItems(subscription as any, lineItems as any);
+
+    expect(result).toHaveLength(1);
+    // @ts-ignore
+    expect(result[0].price_id).toBe('price_1');
+    // @ts-ignore
+    expect(result[0].upsell_price_id).toBe('price_2');
+  });
+
+  it('should return empty array when no items match', async () => {
+    const subscription = { id: 'sub_789' };
+    const lineItems = [{ price_id: 'price_1', price: { type: 'recurring' } }];
+
+    // Mock SubscriptionItem.findAll with empty array
+    jest.spyOn(SubscriptionItem, 'findAll').mockResolvedValue([]);
+
+    const result = await getSubscriptionLineItems(subscription as any, lineItems as any);
+
+    expect(result).toHaveLength(0);
+  });
+});